From 4aad369c9728061c97b3de792286e743ee884b09 Mon Sep 17 00:00:00 2001 From: growupboron Date: Fri, 11 Sep 2020 17:18:57 +0530 Subject: Simplified doc-site generation Updated theme to windmill Using Mkdocs static site generator Deployed on readthedocs Signed-off-by: growupboron Change-Id: If62eaaea1855c91b64f687900f54eba6bc1caee8 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25236 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../1_Message_Signaling/architecture.md | 476 ++++++++++++ .../1_Message_Signaling/images/can-generator.svg | 244 ++++++ .../1_Message_Signaling/images/cloud-arch.svg | 837 +++++++++++++++++++++ .../images/distributed-arch.png | Bin 0 -> 73736 bytes .../images/signal-service-arch.svg | 296 ++++++++ .../2_AGL_Service_CAN_Low_Level/1_Architecture.md | 34 + .../2_AGL_Service_CAN_Low_Level/2_Installation.md | 196 +++++ .../3_Installation-J1939.md | 90 +++ .../4_Installation-ISOTP.md | 59 ++ .../2_AGL_Service_CAN_Low_Level/5_Usage.md | 433 +++++++++++ .../images/CAN_bindings_communication.png | Bin 0 -> 43504 bytes .../images/CAN_level_mapping.png | Bin 0 -> 56087 bytes .../images/OpenXC_to_AGL.png | Bin 0 -> 84031 bytes .../1_Architecture_presentation.md | 32 + .../3_High_Level_VIWI_Service/2_Install_Usage.md | 208 +++++ .../images/high-level-arch.png | Bin 0 -> 30810 bytes .../1_Architecture.md | 73 ++ .../2_Configuration.md | 109 +++ .../4_AGL_Service_Signal_Composer/3_Plugins.md | 32 + .../4_SignalComposerAPI.md | 71 ++ .../pictures/Global_Signaling_Architecture.png | Bin 0 -> 195325 bytes ..._AGL-Message-Signaling-Developer-Guidelines.pdf | Bin 0 -> 777644 bytes .../AGL-Message-Signaling-Developer-Guidelines.md | 1 + .../4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf | Bin 0 -> 305379 bytes .../AGL-AppFW-CAN-Signaling-Benchmark.md | 1 + .../candevstudio/1_Usage.md | 26 + .../candevstudio/2_can_device_socketcan_backend.md | 44 ++ .../candevstudio/3_Add_CAN_Device.md | 41 + .../candevstudio/4_Configure_CanRawSender_Node.md | 28 + .../candevstudio/5_Using_CanRawView.md | 18 + .../candevstudio/pictures/CANdevStudio.png | Bin 0 -> 52285 bytes .../candevstudio/pictures/canrawsender.png | Bin 0 -> 43850 bytes .../candevstudio/pictures/canrawviewer.png | Bin 0 -> 125506 bytes .../4.5_Message_Signaling/8_Resources/index.md | 95 +++ 34 files changed, 3444 insertions(+) create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png create mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md (limited to 'docs/4_APIs_and_Services/4.5_Message_Signaling') diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md new file mode 100644 index 0000000..aaf7e08 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md @@ -0,0 +1,476 @@ +--- +edit_link: '' +title: Message Signaling +origin_url: >- + https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/signaling/architecture.md +--- + + + +--- +title: AGL - Message Signaling Architecture +author: Fulup Ar Foll (IoT.bzh) +date: 2016-06-30 + +categories: architecture, appfw +tags: architecture, signal, message +layout: techdoc + +--- + +**Table of Content** + +1. TOC +{:toc} + +## Context + +Automotive applications need to understand in real time the context in which +vehicles operate. In order to do so, it is critical for automotive application +to rely on a simple, fast and secure method to access data generated by the +multiple sensors/ECU embedded in modern cars. + +This signaling problem is neither new, neither unique to the automotive and +multiple solutions often described as Message Broker or Signaling Gateway have +been around for a while. + +The present document is the now implemented since AGL Daring Dab version, to +handle existing signaling/message in a car. It relies on [[APbinder]] +binder/bindings model to minimize complexity while keeping the system fast +around secure. We propose a model with multiple transport options and a full set +of security feature to protect the service generating the signal as well as +consuming them. + +## Objectives + +Our objectives are solving following 3 key issues: + +1. reduce as much as possible the amount of exchanged data to the meaningful + subset really used by applications +1. offer a high level API that obfuscates low level and proprietary interface to + improve stability in time of the code +1. hide specificities of low level implementation as well as the chosen + deployment distribution model. + +To reach first objective, events emission frequency should be controlled at the +lowest level it possibly can. Aggregation, composition, treatment, filtering of +signals should be supported at software level when not supported by the hardware. + +Second objectives of offering long term stable hight level API while allowing +flexibility in changing low level implementation may look somehow conflicting. +Nevertheless by isolating low level interface from high level and allowing +dynamic composition it is possible to mitigate both objectives. + +## Architecture + +Good practice is often based on modularity with clearly separated components +assembled within a common framework. Such modularity ensures separation of +duties, robustness, resilience and achievable long term maintenance. + +This document uses the term "**Service**" to define a specific instance of this +proposed common framework used to host a group of dedicated separated components +that handle targeted signals/events. Each service exposes to services/applications +the signals/events it is responsible for. + +As an example, a CAN service may want to mix non-public proprietary API with +CANopen compatible devices while hiding this complexity to applications. The +goal is on one hand to isolate proprietary piece of code in such a way that it +is as transparent as possible for the remaining part of the architecture. On a +second hand isolation of code related to a specific device provides a better +separation of responsibilities, keeping all specificity related to a given +component clearly isolated and much easier to test or maintain. Last but not +least if needed this model may also help to provide some proprietary code +directly as binary and not as source code. + +Communicating between the car and regular apps should be done using a 2 levels +AGL services which have two distincts roles: + +- low level should handle communication with CAN bus device (read, decoding, + basic and efficient filtering, caching, ...) +- high level should handle more complex tasks (signals compositions, complex + algorythms like Kalman filter, business logic...) + +![image](images/signal-service-arch.svg "Signal Agent Architecture") + +To do so, the choice has been to use a similar architecture than [[OpenXC]], a +Ford project. Principle is simple, from a JSON file that describes all CAN +signals wanted to be handled, in general a conversion from a **dbc** file, AGL +generator convert it to a C++ source code file. This file which in turn is used +as part of the low level CAN service which can now be compiled. This service +reads, decodes and serves this CAN signals to a high level CAN service that +holds business logic and high level features like described is the above +chapter. + +![image](images/can-generator.svg "AGL CAN generator") + +While in some cases it may be chosen to implement a single service responsible +for everything, other scenarii may chose to split responsibility between +multiple services. Those multiple services may run on a single ECU or on +multiple ECUs. Chosen deployment distribution strategy should not impact the +development of components responsible for signals/events capture. As well as it +should have a loose impact on applications/services consuming those events. + +A distributed capable architecture may provide multiple advantages: + +- it avoids to concentrate complexity in a single big/fat component. +- it leverages naturally multiple ECUs and existing network architecture +- it simplifies security by enabling isolation and sandboxing +- it clearly separates responsibilities and simplifies resolution of conflicts + +Distributed architecture has to be discussed and about now is not fully +implemented. Low level CAN service isn't fully functional nor tested to assume +this feature but its architecture let the possibility open and will be +implemented later. + +![image](images/distributed-arch.png "Distributed Architecture") + +Performance matters. There is a trade-off between modularity and efficiency. +This is specially critical for signals where propagation time from one module to +the other should remain as short as possible and furthermore should consume as +little computing resources as possible. + +A flexible solution should provide enough versatility to either compose modules +in separate processes; either chose a model where everything is hosted within a +single process. Chosen deployment model should have minor or no impact on +development/integration processes. Deployment model should be something easy to +change, it should remain a tactical decision and never become a structuring +decision. + +Nevertheless while grouping modules may improve performance and reduce resource consumption, on the other hand, +it has a clear impact on security. No one should forget that some signals have very different level of security from other ones. +Mixing everything within a single process makes all signal's handling within a single security context. +Such a decision may have a significant impact on the level on confidence one may have in the global system. + +Providing such flexibility constrains the communication model used by modules: + +- The API of integration of the modules (the API of the framework) that enables + the connection of modules must be independent of the implementation of + the communication layer +- The communication layer must be as transparent as possible, its + implementation shouldn't impact how it is used +- The cost of the abstraction for modules grouped in a same process + must be as little as possible +- The cost of separating modules with the maximum of security must remain as + minimal as possible + +Another point impacting performance relates to a smart limitation on the number +of emitted signals. Improving the cost of sending a signal is one thing, +reducing the number of signals is an other one. No one should forget that the +faster you ignore a useless signal the better it is. The best way to achieve +this is by doing the filtering of useless signal as close as possible of the +component generating the signal and when possible directly at the hardware level. + +To enable the right component to filter useless signals, consumer clients must +describe precisely the data they need. A filter on frequency is provided since +Daring Dab version, as well as minimum and maximum limits. These filters can be +specified at subscription time. Also, any data not required by any client should +at the minimum never be transmitted. So only changed data is transmitted and if +another service needs to receive at a regular time, it has to assume that if no +events are received then it is that the value hasn't change. Furthermore when +possible then should even not be computed at all, a CAN signal received on +socket is purely ignored if no one asks for it. + +Describing expected data in a precise but nevertheless simple manner remains a +challenge. It implies to manage: + +- requested frequency of expected data +- accuracy of data to avoid detection of inaccurate changes +- when signaling is required (raising edge, falling edge, + on maintained state, ...), +- filtering of data to avoid glitches and noise, +- composition of signals both numerically and logically (adding, + subtracting, running logical operators like AND/OR/XOR, getting the mean, ...) +- etc... + +It is critical to enable multiple features in signal queries to enable modules +to implement the best computing method. The best computing method may have an +impact on which device to query as well as on which filters should be applied. +Furthermore filtering should happen as soon as possible and obviously when +possible directly at hardware level. + +### Transport Solutions + +D-Bus is the standard choice for Linux, nevertheless it has some serious +performance limitation due to internal verbosity. Nevertheless because it is +available and pre-integrated with almost every Linux component, D-Bus may still +remains an acceptable choice for signal with low rate of emission (i.e. HMI). + +For a faster communication, Jaguar-Land-Rover proposes a memory shared signal +infrastructure. Unfortunately this solution is far from solving all issues and +has some drawbacks. Let check the open issues it has: + +- there is no management of what requested data are. This + translate in computing data even when not needed. +- on top of shared memory, an extra side channel is required for processes + to communicate with the daemon. +- a single shared memory implies a lot of concurrency handling. This might + introduce drawbacks that otherwise would be solved through communication + buffering. + +ZeroMQ, NanoMSG and equivalent libraries focused on fast communication. Some +(e.g. ZeroMQ) come with a commercial licensing model when others (e.g. NanoMSG) +use an open source licensing. Those solutions are well suited for both +communicating inside a unique ECU or across several ECUs. However, most of them +are using Unix domain sockets and TCP sockets and typically do not use shared +memory for inter-process communication. + +Last but not least Android binder, Kdbus and other leverage shared memory, zero +copy and sit directly within Linux kernel. While this may boost information +passing between local processes, it also has some limitations. The first one is +the non support of a multi-ECU or vehicle to cloud distribution. The second one +is that none of them is approved upstream in kernel tree. This last point may +create some extra burden each time a new version of Linux kernel is needed or +when porting toward a new hardware is required. + +### Query and Filtering Language + +Description language for filtering of expected data remains an almost green +field where nothing really fit signal service requirements. Languages like +Simulink or signal processing graphical languages are valuable modelling tools. +Unfortunately they cannot be inserted in the car. Furthermore those languages +have many features that are not useful in proposed signal service context and +cost of integrating such complex languages might not be justified for something +as simple as a signal service. The same remarks apply for automation languages. + +Further investigations leads to some specifications already presents like the +one from Jaguar Land Rover [[VISS]], for **Vehicule Information Service +Specification** and another from Volkwagen AG named [[ViWi]], stand for +**Volkwagen Infotainment Web Interface**. Each ones has their differences and +provides different approach serving the same goal: + +| VISS | ViWi | +|---------------------------------------------------------------|-----------------------------------------------------------------| +| Filtering on node (not possible on several nodes or branches) | Describe a protocol | +| Access restrictions to signals | Ability to specify custom signals | +| Use high level development languages | RESTful HTTP calls | +| One big Server that handle requests | Stateless | +| Filtering | Filtering, sorting | +| Static signals tree not extensible [[VSS]] | Use JSON objects to communicate | +| Use of AMB ? | Identification of resources may be a bit heavy going using UUID | +| Use of Websocket | | + +About **[[VISS]]** specification, the major problem comes from the fact that +signals are specified under the [[VSS]], **Vehicle Signal Specification**. So, +problem is that it is difficult, if not impossible, to make a full inventory +of all signals existing for each car. More important, each evolution in signals +must be reported in the specification and it is without seeing the fact that +car makers have their names and set of signals that would mostly don't +comply with the [[VSS]]. VISS doesn't seems to be an valuable way to handle +car's signals, a big component that responds requests, use of **Automotive +Message Broker** that use DBus is a performance problem. Fujitsu Ten recent +study[[1]] highlights that processor can't handle an heavy load on CAN bus and +that Low level binding adopted for AGL is about 10 times[[2]] less impact on +performance. + +## Describing Signal Subscriptions using JSON + +JSON is a rich structured representation of data. For requested data, it allows +the expression of multiple features and constraints. JSON is both very flexible +and efficient. There are significant advantages in describing requested data at +subscription time using a language like JSON. Another advantage of JSON is that +no parser is required to analyse the request. + +Existing works exists to describe a signals that comes first from Vector with +its proprietary database (`DBC`) which widely used in industry. Make a +description based on this format appears to be a good solution and Open Source +community already has existing tools that let you convert proprietary file +format to an open one. So, a JSON description based on work from [[OpenXC]] is +specified [here](https://github.com/openxc/vi-firmware/blob/master/docs/config/reference.rst) +which in turn is used in Low level CAN service in AGL: + +```json +{ "name": "example", + "extra_sources": [], + "initializers": [], + "loopers": [], + "buses": {}, + "commands": [], + "0x3D9": { + "bus": "hs", + "signals": { + "PT_FuelLevelPct": { + "generic_name": "fuel.level", + "bit_position": 8, + "bit_size": 8, + "factor": 0.392157, + "offset": 0 + }, + "PT_EngineSpeed": { + "generic_name": "engine.speed", + "bit_position": 16, + "bit_size": 16, + "factor": 0.25, + "offset": 0 + }, + "PT_FuelLevelLow": { + "generic_name": "fuel.level.low", + "bit_position": 55, + "bit_size": 1, + "factor": 1, + "offset": 0, + "decoder": "decoder_t::booleanDecoder" + } + } + } +} +``` + +From a description like the above one, low level CAN generator will output +a C++ source file which let low level CAN service that uses it to handle such +signal definition. + +## Naming Signal + +Naming and defining signals is something very complex. For example just +***speed***, as a signal, is difficult to define. +What unit is used (km/h, M/h, m/s, ...)? +From which source (wheels, GPS, AccelMeter)? +How was it captured (period of measure, instantaneous, mean, filtered)? + +In order to simplify application development we should nevertheless agree on +some naming convention for key signals. Those names might be relatively complex +and featured. They may include a unit, a rate, a precision, etc. + +How these names should be registered, documented and managed is out of scope of +this document but extremely important and at some point in time should be +addressed. Nevertheless this issue should not prevent from moving forward +developing a modern architecture. Developers should be warned that naming is a +complex task, and that in the future naming scheme should be redefined, and +potential adjustments would be required. + +About Low level CAN signals naming a doted notation, like the one used by Jaguar +Landrover, is a good compromise as it describe a path to an car element. It +separates and organize names into hierarchy. From the left to right, you +describe your names using the more common ancestor at the left then more you go +to the right the more it will be accurate. Using this notation let you subscribe +or unsubscribe several signals at once using a globbing expression. + +Example using OBD2 standard PID: + +```path +engine.load +engine.coolant.temperature +fuel.pressure +intake.manifold.pressure +engine.speed +vehicle.speed +intake.air.temperature +mass.airflow +throttle.position +running.time +EGR.error +fuel.level +barometric.pressure +commanded.throttle.position +ethanol.fuel.percentage +accelerator.pedal.position +hybrid.battery-pack.remaining.life +engine.oil.temperature +engine.torque +``` + +Here you can chose to subscribe to all engine component using an expression +like : `engine.*` + +## Reusing existing/legacy code + +About now provided services use: + +- **Low Level** [[OpenXC]] project provides logic and some useful libraries to + access a CAN bus. It is the choice for AGL. + +- **High Level** In many cases accessing to low level signal is not enough. + Low level information might need to be composed (i.e. GPS+Gyro+Accel). + Writing this composition logic might be quite complex and reusing existing + libraries like: LibEkNav for Kalman filtering [[9]] or Vrgimbal for 3 axes + control[[10]] may help saving a lot of time. AGL apps should access CAN + signals through High Level service. High level can lean on as many low level + service as needed to compute its **Virtual signals** coming from differents + sources. Viwi protocol seems to be a good solution. + +## Leveraging AGL binder + +Such a model is loosely coupled with AGL binder. Low level CAN service as well +as virtual signal components may potentially run within any hosting environment +that would provide the right API with corresponding required facilities. +Nevertheless leveraging [[APbinder]] has multiple advantages. It already +implements event notification to support a messaging/signaling model for +distributed services. It enables a subscribe model responding to the +requirement and finally it uses JSON natively. + +This messaging/signalling model already enforces the notion of subscription for +receiving data. It implies that unexpected data are not sent and merely not +computed. When expected data is available, it is pushed to all waiting +subscriber only one time. + +The [[APbinder]] provides transparency of communication. +It currently implements the transparency over D-Bus/Kdbus and WebSocket. +Its transparency mechanism of communication is easy to extend to other +technologies: pools of shared memory or any proprietary transport model. + +When bindings/services are loaded by the same binder, it provides transparently +`in-memory` communication. This in-memory communication is really efficient: on +one hand, the exchanged JSON objects are not serialized (because not streamed), +on the other hand, those JSON objects provide a high level of abstraction able +to transfer any data. + +Technically a service is a standard [[APbinder]] binding which is also handled +by the system and launched as a daemon by systemD. +Therefore Signal/Agent inherits of security protection through SMACK, access +control through Cynara, transparency of API to transport layer, life cycle +management, ... Like any other [[APbinder]] process is composed of a set of +bindings. In signal service specific case, those bindings are in fact the +`signal modules`. + +The proposed model allows to implement low level dependencies as independent +signal modules. Those modules when developed are somehow like "Lego Bricks". +They can be spread or grouped within one or multiple services depending on +deployment constraints (performance, multi-ECU, security & isolation +constraints,...). + +On top of that low level signal modules, you should use a high level service. +A first implementation of [[ViWi]] is available [here](https://github.com/iotbzh/high-level-viwi-service) +and can be use to integrate business logic and high level features. + +The model naturally uses JSON to represent data. + +## Multi-ECU and Vehicule to Cloud interactions + +While this might not be a show stopper for current projects, it is obvious that +in the near future Signal/Agent should support a fully distributed +architectures. Some event may come from the cloud (i.e. request to start +monitoring a given feature), some may come from SmartCity and nearby vehicles, +and last but not least some may come from another ECU within the same vehicle or +from a virtualized OS within the same ECU (e.g. cluster & IVI). In order to do +so, Signal modules should enable composition within one or more [[APbinder]] +inside the same ECU. Furthermore they should also support chaining with the +outside world. + +![image](images/cloud-arch.svg "Cloud & Multi-ECU Architecture") + +1. Application requests Virtual Signal exactly like if it was a low level signal +1. Agent Signal has direct relation to low level signal +1. Agent needs to proxy to an other service inside the same ECU to access the signal +1. Signal is not present on current ECU. Request has to be proxied to the outside world + +[AppFw]: http://iot.bzh/download/public/2016/appfw/01_Introduction-to-AppFW-for-AGL-1.0.pdf "Application Framework" +[APcore]: http://iot.bzh/download/public/2016/appfw/03_Documentation-AppFW-Core-1.0.pdf "AppFw Core" +[APmain]: https://gerrit.automotivelinux.org/gerrit/#/q/project:src/app-framework-main "AppFw Main" +[APbinder]: https://gerrit.automotivelinux.org/gerrit/#/q/project:src/app-framework-binder "AppFw Binder" +[APsamples]: https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=tree;f=bindings/samples "AppFw Samples" +[Signal-K]: http://signalk.org/overview.html +[1]: http://schd.ws/hosted_files/aglmmwinter2017/37/20170201_AGL-AMM_F10_kusakabe.pdf +[2]: https://wiki.automotivelinux.org/_media/agl-distro/20170402_ften_can_kusakabe_v2.pdf +[6]: https://github.com/otcshare/automotive-message-broker +[7]: http://ardupilot.org/rover/index.html +[8]: https://github.com/ArduPilot/ardupilot/tree/master/libraries +[9]: https://bitbucket.org/jbrandmeyer/libeknav/wiki/Home +[10]: http://ardupilot.org/rover/docs/common-vrgimbal.html +[11]: http://elinux.org/R-Car/Boards/Porter:PEXT01 +[12]: https://github.com/gpsnavi/gpsnavi +[VISS]: http://rawgit.com/w3c/automotive/gh-pages/vehicle_data/vehicle_information_service.html +[VSS]: https://github.com/GENIVI/vehicle_signal_specification +[ViWi]: https://www.w3.org/Submission/2016/SUBM-viwi-protocol-20161213/ +[OpenXC]: http://openxcplatform.com/ +[low level CAN service]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/low-level-can-generator +[high level ViWi]: https://github.com/iotbzh/high-level-viwi-service diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg new file mode 100644 index 0000000..f5a567c --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg @@ -0,0 +1,244 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CAN Low Level Bindng(Shared Library) + + + + + + + + + + + + + + OPENXC SignalDescription(JSON) + + + + + + + + + + + + + + + + + + + + + Low LevelBindingStatic Code(AGL) + + + + + + + + + + + + + + CANDecoding/EncodingC++ Code(vendor) + + + + + + + + + + + + + + OptionalMessageHandlers(vendor) + + + + + + + + + + + + + + + Call for decode/encode + + + + + + + + + + CANConfigGenerator + + + + + + + + + + C/C++Compiler + + + + + + + + + + + + + + OPENXC SignalDescription(JSON) + + + + + + + + + + + + + + OPENXC SignalDescription(JSON) + + + + + + + + \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg new file mode 100644 index 0000000..3cecbdc --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg @@ -0,0 +1,837 @@ + +image/svg+xml +Access Control +Transport . +Custer ECU +Access Control +Transport DBUS, WebSocket, ... +NavigationService +Carte handling +POI management +etc... +CAN GPS +GeopositioningVirtualSignal +Multi ECU Architecture +ABS +Publish/Subscribe +IVI ECU +CAN-BUSVirtual Signal +Publish/Subscribe +Gyro, Acelerometer +CAN-BUS +LIN-BUS +ClusterVirtual Signal +Publish/Subscribe +Engine-CAN-BUS +ABS +1 +2 +3 +4 + \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png new file mode 100644 index 0000000..3c4f4a0 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg new file mode 100644 index 0000000..3dee802 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg @@ -0,0 +1,296 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Binder + + + + + + + + CAN Low Level Binding(s)Decoding / EncodingAuthentication / Crypto / FirewallingTransaction (set… ack ...)Stats & MathsCaching (low freq. Signals, get() call)Debug + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CAN High Level Binding(s)LogicAggregation (« vehicle.doors.any.open »)Advanced Ops + + + + + + + + + + + + + + + + + + + + + + + + + CAN BUS + + + + + + + + + + + + + + + + CAN frames - 011010010 + + + + + + + + + Signals - « vehicle.doors.left.open »(Binder Events) + + + + + + + + UI + + + + + + + + Publish Subscribe + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md new file mode 100644 index 0000000..4606568 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md @@ -0,0 +1,34 @@ +--- +edit_link: '' +title: Architecture presentation +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/1-Architecture.md?h=master +--- + + + +# AGL CAN binding architecture proposal + +It's meant to generate, from a JSON file describing CAN messages and diagnostic message \(OBD2 for now\), a cpp file to integrate with the project. + +Once generated binding is built with it and result will be a widget file to install on an AGL target system. + +![From OpenXC firmware to AGL binding](images/OpenXC_to_AGL.png) + +Bringing CAN management into the AGL project is more than allowing decode and print CAN messages, lot of tools can do that (Wireshark, CAN-utils, ...). + +The goal is to provide a common API and abstraction to the CAN bus then you can bring some more high level functionalities to the system. + +CAN binding will be separated in two parts: + +![CAN low and high level bindings mapping](images/CAN_level_mapping.png) + +- High level: Binding from which others applications will connect to. +It will provides valuable access to the CAN bus by aggregate signals or providing new signals from several originals. For example, a signal exposing whether or not a door is open, no matter which one it is. Also, we can imagine an application which supervise if there is no one in the car but moving (1m, 2m ?) to alert the owner of an unexpected behavior. The high level binding will sends a single event representing that behavior to the application which in turn will send a phone message to. + +- Low level: Decode messages that transit and send event through **Application Framework** to the subscribers with human readable message. It provides some basic access to the bus + some basic mathematical, statistical features (last_values, min, max, timestamps, averaging) as well as basic filter to get discerning signal only (This part are not implemented yet in the low level). + + +![Communication between CAN bindings and third applications](images/CAN_bindings_communication.png) + +Last but not least, the low level binding can be shipped as binary only using OpenXC inspired [AGL low level CAN binding Generator](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/low-level-can-generator.git;a=summary). diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md new file mode 100644 index 0000000..ad7fedb --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md @@ -0,0 +1,196 @@ +--- +edit_link: '' +title: Installation Guide +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/2-Installation.md?h=master +--- + + + +# Prerequisites + +* An AGL system installed with latest Daring Dab version with latest Application +framework version >= 0.6. + +* Make sure you built the AGL generator else you will not be able to generate custom low-level CAN binding. + +It will produce a _application-generated.cpp_ file to paste in the source, _CAN-binder/low-can-binding/binding/_, directory. + +* Make sure you already set up the AGL SDK using the following [Download or Build Your SDK Installer](../../../getting_started/reference/getting-started/app-workflow-sdk.html). Alternatively, please refer to official guides available on [AGL Developer Site](../../../devguides). + +If you need to have the graphic stack inside your SDK, you have to prepare your environment with the **iotbzh**, or **Daring Dab** flavor using _prepare_meta_ tool. To do so, run the following command in your docker image in the step 4 in place of `... [ prepare build environment ] ...`: + +> **NOTE** These commands assume that proprietary graphic drivers for Renesas Porter board are located in _/home/devel/share/proprietary-renesas-rcar_ directory. + +```bash +prepare_meta -f iotbzh -o /xdt -l /home/devel/mirror -p /home/devel/share/proprietary-renesas-rcar/ -t m3ulcb -e wipeconfig -e rm_work -e cleartemp +/xdt/build/m3ulcb/agl-init-build-env +``` + +* (Optionnal) An [USB CAN adapter](https://shop.8devices.com/index.php?route=product/product&path=67&product_id=54) connected to connector through the [right cable](https://www.mouser.fr/ProductDetail/EasySync/OBD-M-DB9-F-ES?qs=pLQRQR43dtrcAQQLCUAIxA%3D%3D) if you want to connect to a real car through the OBD2 connector. + + + +# Getting started + +## CAN config generator usage + +### Build requirements + +* CMake version 3.3 or later +* G++, Clang++ or any C++11 compliant compiler. + +### Compile + +```bash +source /xdt/sdk/environment-setup-aarch64-agl-linux +export PATH=$PATH:/xdt/sdk/sysroots/x86_64-aglsdk-linux/usr/bin +export WD=$(pwd) +git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/agl-service-can-low-level -b Renesas_delivery_Q2 +git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-generator +cd ${WD}/low-level-can-generator +mkdir -p build +cd build +cmake -G "Unix Makefiles" .. +make +``` + +### Naming convention + +We chose a doted naming convention because it's a well know schema. + +It separates and organize names into hierarchy. From the left to right, you describe your names using the more common ancestor at the left then more you go to the right the more it will be accurate. + +Let's take an example, here is an example about standard PID name following this convention: + +``` +engine.load +engine.coolant.temperature +fuel.pressure +intake.manifold.pressure +engine.speed +vehicle.speed +intake.air.temperature +mass.airflow +throttle.position +running.time +EGR.error +fuel.level +barometric.pressure +commanded.throttle.position +ethanol.fuel.percentage +accelerator.pedal.position +hybrid.battery-pack.remaining.life +engine.oil.temperature +engine.torque +``` + +> **NOTE** It's recommended that you follow this naming convention to named your CAN signals. +> +> There is only character `*` that is forbidden in names because it's used as wildcard for subscription and unsubscription. +> +> This described in the below chapter. + +### Available decoder + +You can use some basic decoder provided by default by the binding which are: + +* ***decoder_t::decode_noop*** : Default decoder if not specified, return raw value from signal's bitfield. +* ***decoder_t::decode_boolean*** : Coerces a numerical value to a boolean. +* ***decoder_t::decode_state*** : Find and return the corresponding string state for a CAN signal's raw integer value. + +### Generating JSON from Vector CANoe Database + +> **CAUTION** This chapter has not been tested since it haven't necessary automotive tools for that. + +If you use CANoe to store your `gold standard` CAN signal definitions, you may be able to use the OpenXC `xml_to_json.py` script to make your JSON for you. First, export the Canoe .dbc file as XML - you can do this with Vector CANdb++. Next, create a JSON file according to the format defined above, but only define: + +* CAN messages. +* Name of CAN signals within messages and their generic_name. +* Optionnaly name of diagnostic messages and their name. + +To install the OpenXC utilities and runs `xml_to_json.py` script: + +```bash +sudo pip install openxc +cd /usr/local/lib/python2.7/dist-packages/openxc/generator +``` + +Assuming the data exported from Vector is in `signals.xml` and your minimal mapping file is `mapping.json`, run the script: + +```bash +python -m openxc.utils ./xml_to_json.py signals.xml mapping.json signals.json +``` + +The script scans `mapping.json` to identify the CAN messages and signals that you want to use from the XML file. It pulls the neccessary details of the messages (bit position, bit size, offset, etc) and outputs the resulting subset as JSON into the output file, `signals.json`. + +The resulting file together with `mapping.json` will work as input to the code generation script. + +### Generate your config file + +To generate your config file you just have to run the generator using the `-m` option to specify your JSON file. + +```bash +./can-config-generator -m ../tests/basic.json -o application-generated.cpp +``` + +If you omit the `-o` option, then code is generated on the stdout. +You also can specify a header and a footer file. +These files must be valid C++ fragment as long as they will be inserted as is. +Use the `-h` option to display help. + +> **CAUTION:** Each `diagnostic_message` must define the same `bus` as the binding will use only one bus. + +### Supported OpenXC items + +About now, compliance with OpenXC reference is in progress, can-config-generator and CAN\_signaling will implement them soon. +`initializers`, `loopers`, `commands` and `handlers` nodes are ignored for now. + +This generator will follow OpenXC support status of the low level CAN signaling binding. + +> **NOTE**: The `buses` item will not be supported by this generator because the binding use another way to declare and configure buses. Please refer to the binding's documentation. + +## Compile and install the binding + +### Build requirements + +* Kernel >= 4.8 +* CMake version 3.3 or later +* G++, Clang++ or any C++11 compliant compiler. + +### Compile + +Clone the binding repository, copy the generated file and updated the git submodules. + +Execute the following commands from this repository: + +```bash +cd ${WD}/agl-service-can-low-level +cp ${WD}/low-level-can-generator/build/application-generated.cpp ../low-can-binding/binding +``` + +### Installation + +```bash +cd ${WD}/agl-service-can-low-level +mkdir build +cd build +cmake .. +make +make widget +``` + +To install it manually, you need to copy the _low-can-service.wgt_ file on your target, then from it execute the following commands : + +On your host, to copy over the network : + +```bash +scp low-can-service.wgt root@:~ +``` + +On the target, assuming _**wgt**_ file is in the root home directory: + +```bash +afm-util install low-can-service.wgt +{ "added": "low-can-service@4.0" } +``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md new file mode 100644 index 0000000..6ba03af --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md @@ -0,0 +1,90 @@ +--- +edit_link: '' +title: Installation Guide for J1939 +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/3-Installation-J1939.md?h=master +--- + + + +# Installation j1939 for AGL + +#### Minimum kernel version : 4.19 + +## Compilation of kernel j1939 + +##### Clone linux-can-next repository on kernel.org + +```bash +git clone https://git.kernel.org/pub/scm/linux/kernel/git/mkl/linux-can-next.git/ +``` + +##### Checkout on j1939 branch + +```bash +git checkout j1939 +``` + +##### Add the compilation of the j1939 + +```bash +make menuconfig + - Networking Support + - Can bus subsystem support + - SAE J1939 + - [*] debug SAE J1939 +``` + +##### Compile + +```bash +make +``` + +##### Install + +```bash +make modules_install +make install +``` + +##### Update grub + +###### CentOS/RHEL/Oracle/Scientific and Fedora Linux + +```bash +grub2-mkconfig -o /boot/grub2/grub.cfg +grubby --set-default /boot/vmlinuz-... +reboot +``` + +###### Debian/Ubuntu Linux + +```bash +update-grub +reboot +``` + +##### Check if the installation is correct + +```bash +modprobe can-j1939 +``` + +If no errors are generated you have successfully install a kernel with j1939 module. + +You can have a problem with header file, to check that go in the file /usr/include/linux/can.h + +```bash +vi /usr/include/linux/can.h +``` + +If in the struct sockaddr_can you don't see j1939, the header are not upgrade. + +So you need to do this manually, go to you're linux-can-next repository and do the following command: + +```bash +cp include/uapi/linux/can.h /usr/include/linux/can.h +cp include/uapi/linux/can/j1939.h /usr/include/linux/can/ +``` + diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md new file mode 100644 index 0000000..066ef27 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md @@ -0,0 +1,59 @@ +--- +edit_link: '' +title: Installation Guide for ISOTP +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/4-Installation-ISOTP.md?h=master +--- + + + +# Installation isotp for AGL + +## Compilation and installation of module kernel isotp + +##### Clone repository Linux Kernel Module for ISO 15765-2:2016 CAN transport protocol + +```bash +git clone https://github.com/hartkopp/can-isotp.git +``` + +##### Move into the new repository + +```bash +cd can-isotp +``` + +##### Install packages to build + +```bash +sudo apt-get install build-essential linux-headers-$(uname -r) +``` + +##### Compile + +```bash +make +``` + +##### Install + +```bash +sudo make modules_install +``` + +##### Load module + + +```bash +modprobe can +modprobe vcan +sudo insmod ./net/can/can-isotp.ko +``` + + +## Include headers files + + +```bash +sudo cp include/uapi/linux/can/isotp.h /usr/include/linux/can/ +``` \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md new file mode 100644 index 0000000..77aad7f --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md @@ -0,0 +1,433 @@ +--- +edit_link: '' +title: Usage Guide +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/5-Usage.md?h=master +--- + + + +# Configure the AGL system + +## Virtual CAN device + +Connected to the target, here is how to load the virtual CAN device driver and +set up a new vcan device : + +```bash +modprobe vcan +ip link add vcan0 type vcan +ip link set vcan0 up +``` + +You also can named your linux CAN device like you want and if you need name it +`can0` : + +```bash +modprobe vcan +ip link add can0 type vcan +ip link set can0 up +``` + +## CAN device using the USB CAN adapter + +Using real connection to CAN bus of your car using the USB CAN adapter +connected to the OBD2 connector. + +Once connected, launch `dmesg` command and search which device to use: + +```bash +dmesg +[...] +[ 131.871441] usb 1-3: new full-speed USB device number 4 using ohci-pci +[ 161.860504] can: controller area network core (rev 20120528 abi 9) +[ 161.860522] NET: Registered protocol family 29 +[ 177.561620] usb 1-3: USB disconnect, device number 4 +[ 191.061423] usb 1-2: USB disconnect, device number 3 +[ 196.095325] usb 1-2: new full-speed USB device number 5 using ohci-pci +[ 327.568882] usb 1-2: USB disconnect, device number 5 +[ 428.594177] CAN device driver interface +[ 1872.551543] usb 1-2: new full-speed USB device number 6 using ohci-pci +[ 1872.809302] usb_8dev 1-2:1.0 can0: firmware: 1.7, hardware: 1.0 +[ 1872.809356] usbcore: registered new interface driver usb_8dev +``` + +Here device is named `can0`. + +This instruction assuming a speed of 500000kbps for your CAN bus, you can try +others supported bitrate like 125000, 250000 if 500000 doesn't work: + +```bash +ip link set can0 type can bitrate 500000 +ip link set can0 up +ip link show can0 + can0: mtu 16 qdisc pfifo_fast state UNKNOWN qlen 10 + link/can + can state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 + bitrate 500000 sample-point 0.875 + tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 + sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 + clock 16000000 +``` + +On a Rcar Gen3 board, you'll have your CAN device as `can1` because `can0` +already exists as an embedded device. + +The instructions will be the same: + +```bash +ip link set can1 type can bitrate 500000 +ip link set can1 up +ip link show can1 + can0: mtu 16 qdisc pfifo_fast state UNKNOWN qlen 10 + link/can + can state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 + bitrate 500000 sample-point 0.875 + tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 + sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 + clock 16000000 +``` + +## Rename an existing CAN device + +You can rename an existing CAN device using following command and doing so move +an existing `can0` device to anything else and then use another device as `can0` +. For a Rcar Gen3 board do the following by example: + +```bash +sudo ip link set can0 down +sudo ip link set can0 name bsp-can0 +sudo ip link set bsp-can0 up +``` + +Then connect your USB CAN device that will be named `can0` by default. + +# Configure the binding + +The binding reads system configuration file _/etc/dev-mapping.conf_ at start to +map logical name from signals described in JSON file to linux devices name +initialized by the system. + +Edit file _/etc/dev-mapping.conf_ and add mapping in section `CANbus-mapping`. + +Default binding configuration use a CAN bus named `hs` so you need to map it to +the real one, here are some examples: + +* Using virtual CAN device as described in the previous chapter: + +```ini +[CANbus-mapping] +hs="vcan0" +ls="vcan1" +``` + +* Using real CAN device, this example assume CAN bus traffic will be on can0. + +```ini +[CANbus-mapping] +hs="can0" +ls="can1" +``` + +* On a Rcar Gen3 board there is an embedded CAN device so `can0` already exists. So you might want to use your USB CAN adapter plugged to the OBD2 connector, in this case use `can1`: + +```ini +[CANbus-mapping] +hs="can1" +``` + +* You can use this configuration for j1939: + +```ini +[CANbus-mapping] +hs="can0" +ls="can1" +j1939="can2" +``` + +> **CAUTION VERY IMPORTANT:** Make sure the CAN bus\(es\) you specify in your +> configuration file match those specified in your generated source file with +> the `CAN-config-generator`. + + + +## Change name of ECU for J1939 + +To change the name of an ECU to J1939, you must go to the file conf.d/cmake/config.cmake and modify the value at : + + +```cmake +# Define name for ECU +set(J1939_NAME_ECU 0x1239) +``` + + + +# Run it, test it, use it. + +You can run the binding using **afm-util** tool, here is the classic way to go : + +```bash +afm-util run low-can-service@4.0 +1 +``` + +You can find instructions to use afm-util tool +[here](../../reference/af-main/1-afm-daemons.html#using-afm-util), + as well as documentation about Application Framework. + +But you can't control nor interact with it because you don't know security +token that **Application Framework** gaves it at launch. + +So, to test it, it is better to launch the binding manually. In the following +example, it will use port **1234** and left empty security token for testing +purpose: + +```bash +afb-daemon --binding=/var/lib/afm/applications/low-can-service/4.0/lib/afb-low-can.so --rootdir=/var/lib/afm/applications/low-can-service/4.0/ --port=1234 --token=1 +NOTICE: binding [/usr/lib/afb/afb-dbus-binding.so] calling registering function afbBindingV1Register +NOTICE: binding /usr/lib/afb/afb-dbus-binding.so loaded with API prefix dbus +NOTICE: binding [/usr/lib/afb/authLogin.so] calling registering function afbBindingV1Register +NOTICE: binding /usr/lib/afb/authLogin.so loaded with API prefix auth +NOTICE: binding [/var/lib/afm/applications/low-can-service/4.0/libs//low-can-binding.so] calling registering function afbBindingV1Register +NOTICE: binding /var/lib/afm/applications/low-can-service/4.0/libs//low-can-binding.so loaded with API prefix low-can +NOTICE: Waiting port=1234 rootdir=/var/lib/afm/applications/low-can-service/4.0/ +NOTICE: Browser URL= http:/*localhost:1234 +``` + +On another terminal, connect to the binding using previously installed +**AFB Websocket CLI** tool: + +```bash +afb-client-demo ws://localhost:1234/api?token=1 +``` + +You will be on an interactive session where you can communicate directly with +the binding API. + +The binding provides at this moment 2 verbs, _subscribe_ and _unsubscribe_, +which can take argument by a JSON **event** object. + +The argument value is the CAN message **generic\_name** as described in the +JSON file used to generate cpp file for the binding. + +To use the _**AFB Websocket CLI**_ tool, a command line will be like the +following: + +``` + +``` + +Where: + +* API : _**low-can**_. +* Verb : _**subscribe**_ or _**unsubscribe**_ +* Arguments : _**{ "event": "driver.doors.open" }**_ + +## Subscription and unsubscription + +You can ask to subscribe to chosen CAN event with a call to _subscribe_ API +verb with the CAN messages name as JSON argument. + +> **NOTE:** If no argument is provided, then you'll subscribe to all signals +> at once. + +For example from a websocket session: + +```json +low-can subscribe { "event": "doors.driver.open" } +ON-REPLY 1:low-can/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"a18fd375-b6fa-4c0e-a1d4-9d3955975ae8"}} +``` + +Subscription and unsubscription can take wildcard in their _event_ value and are +**case-insensitive**. + +To receive all doors events : + +```json +low-can subscribe { "event" : "doors*" } +ON-REPLY 1:low-can/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"511c872e-d7f3-4f3b-89c2-aa9a3e9fbbdb"}} +``` + +Then you will receive an event each time a CAN message is decoded for the event +named _doors.driver.open_ with its received timestamp if available: + +```json +ON-EVENT low-can/messages.doors.driver.open({"event":"low-can\/messages.doors.driver.open","data":{"name":"messages.doors.driver.open","value":true, "timestamp": 1505812906020023},"jtype":"afb-event"}) +``` + +Notice that event shows you that the CAN event is named +_messages.doors.driver.open_ but you ask for event about +_doors.driver.open_. + +This is because all CAN messages or diagnostic messages are prefixed by the +JSON parent node name, **messages** for CAN messages and +**diagnostic\_messages** for diagnostic messages like OBD2. + +This will let you subscribe or unsubcribe to all signals at once, not +recommended, and better make filter on subscribe operation based upon their type. Examples: + +```json +low-can subscribe { "event" : "*speed*" } --> will subscribe to all messages with speed in their name. Search will be make without prefix for it. +low-can subscribe { "event" : "speed*" } --> will subscribe to all messages begin by speed in their name. Search will be make without prefix for it. +low-can subscribe { "event" : "messages*speed*" } --> will subscribe to all CAN messages with speed in their name. Search will be on prefixed messages here. +low-can subscribe { "event" : "messages*speed" } --> will subscribe to all CAN messages ending with speed in their name. Search will be on prefixed messages here. +low-can subscribe { "event" : "diagnostic*speed*" } --> will subscribe to all diagnostic messages with speed in their name. Search will be on prefixed messages here. +low-can subscribe { "event" : "diagnostic*speed" } --> will subscribe to all diagnostic messages ending with speed in their name. Search will be on prefixed messages here. +``` + +You can also subscribe to an event with the ID or the PGN of the message definition : + + +```json +low-can subscribe {"id" : 1568} +low-can subscribe {"pgn" : 61442} +``` + +And subscribe to all ID or PGN : + +```json +low-can subscribe {"id" : "*"} +low-can subscribe {"pgn" : "*"} +``` + + +You can stop receiving event from it by unsubscribe the signal the same way you did for subscribe + +```json +low-can unsubscribe { "event": "doors.driver.open" } +ON-REPLY 2:low-can/unsubscribe: {"jtype":"afb-reply","request":{"status":"success"}} +low-can unsubscribe { "event" : "doors*" } +ON-REPLY 3:low-can/unsubscribe: {"jtype":"afb-reply","request":{"status":"success"}} +``` + +### Filtering capabilities + +It is possible to limits received event notifications into minimum and maximum +boundaries as well as doing frequency thinning. This is possible using the +argument filter with one or more of the filters available : + +* frequency: specify in Hertz the frequency which will be used to getting + notified of new CAN events for the designated signal. If, during the blocked + time, further changed CAN messages are received, the last valid one will be + transferred after the lockout with a RX_CHANGED. +* min: Minimum value that the decoded value needs to be above to get pushed to + the subscribed client(s). +* max: Maximum value that the decoded value needs to be below to get pushed to + the subscribed client(s) +* rx_id : For the ISO TP protocol, define the id of source to write a message +* tx_id : For the ISO TP protocol, define the id of emitter to receive message + +Order doesn't matter neither the number of filters chosen, you can use one, two +or all of them at once. + +Usage examples : + +```json +low-can subscribe {"event": "messages.engine.speed", "filter": { "frequency": 3, "min": 1250, "max": 3500}} +low-can subscribe {"event": "messages.engine.load", "filter": { "min": 30, "max": 100}} +low-can subscribe {"event": "messages.vehicle.speed", "filter": { "frequency": 2}} +# ISOTP +low-can subscribe {"id": 273, "filter": {"tx_id" : 562}} +``` + +## Get last signal value and list of configured signals + +You can also ask for a particular signal value on one shot using **get** verb, like +this: + +```json +low-can get {"event": "messages.engine.speed"} +ON-REPLY 1:low-can/get: {"response":[{"event":"messages.engine.speed","value":0}],"jtype":"afb-reply","request":{"status":"success"}} +``` + +> **CAUTION** Only one event could be requested. + +Also, if you want to know the supported CAN signals loaded by **low-can**, use +verb **list** + +```json +low-can list +ON-REPLY 2:low-can/list: {"response":["messages.hvac.fan.speed","messages.hvac.temperature.left","messages.hvac.temperature.right","messages.hvac.temperature.average","messages.engine.speed","messages.fuel.level.low","messages.fuel.level","messages.vehicle.average.speed","messages.engine.oil.temp","messages.engine.oil.temp.high","messages.doors.boot.open","messages.doors.front_left.open","messages.doors.front_right.open","messages.doors.rear_left.open","messages.doors.rear_right.open","messages.windows.front_left.open","messages.windows.front_right.open","messages.windows.rear_left.open","messages.windows.rear_right.open","diagnostic_messages.engine.load","diagnostic_messages.engine.coolant.temperature","diagnostic_messages.fuel.pressure","diagnostic_messages.intake.manifold.pressure","diagnostic_messages.engine.speed","diagnostic_messages.vehicle.speed","diagnostic_messages.intake.air.temperature","diagnostic_messages.mass.airflow","diagnostic_messages.throttle.position","diagnostic_messages.running.time","diagnostic_messages.EGR.error","diagnostic_messages.fuel.level","diagnostic_messages.barometric.pressure","diagnostic_messages.ambient.air.temperature","diagnostic_messages.commanded.throttle.position","diagnostic_messages.ethanol.fuel.percentage","diagnostic_messages.accelerator.pedal.position","diagnostic_messages.hybrid.battery-pack.remaining.life","diagnostic_messages.engine.oil.temperature","diagnostic_messages.engine.fuel.rate","diagnostic_messages.engine.torque"],"jtype":"afb-reply","request":{"status":"success","uuid":"32df712a-c7fa-4d58-b70b-06a87f03566b"}} +``` + +## Write on CAN buses + +Two modes could be used for that which is either specifying the CAN bus and a +*RAW* CAN message either by specifying a defined signal, **case-insensitively**, +and its value. + +Examples: + +```json +# Authentification +low-can auth +# Write a raw can frame to the CAN id 0x620 +low-can write { "bus_name": "hs", "frame": { "can_id": 1568, "can_dlc": 8, "can_data": [ 255, 255, 255, 255, 255, 255, 255, 255]} } +# Write a signal's value. +low-can write { "signal_name": "engine.speed", "signal_value": 1256} +# Write J1939 'single frame' +low-can write { "bus_name": "j1939", "frame": { "pgn": 61442, "length":8, "data": [ 255, 255, 255, 255, 255, 255, 255, 255]} } +# Write J1939 'multi frame' +low-can write { "bus_name": "j1939", "frame": { "pgn": 61442, "length":9, "data": [ 255, 255, 255, 255, 255, 255, 255, 255, 254]} } +# Write ISOTP 'single frame' +low-can write {"bus_name": "hs", "filter": {"rx_id" : 562}, "frame": { "can_id": 273, "can_dlc": 8, "can_data": [ 255, 255, 255, 255, 255, 255, 255, 255]} } +# Write ISOTP 'multi frame' +low-can write {"bus_name": "hs", "filter": {"rx_id" : 562}, "frame": { "can_id": 273, "can_dlc": 9, "can_data": [ 255, 255, 255, 255, 255, 255, 255, 255, 25]} } +``` + +To be able to use write capability, you need to add the permission + ```urn:AGL:permission::platform:can:write``` to your package configuration + file that need to write on CAN bus through **low-can** api. + +Then in order to write on bus, your app needs to call verb **auth** +before calling **write**, to raise its **LOA**, Level Of Assurance, +which controls usage of verb **write**. + +## Using CAN utils to monitor CAN activity + +You can watch CAN traffic and send custom CAN messages using can-utils +preinstalled on AGL target. + +To watch watch going on a CAN bus use: + +```bash +candump can0 +``` + +Or for an USB CAN adapter connected to porter board: + +```bash +candump can1 +``` + +Send a custom message: + +```bash +cansend can0 ID#DDDDAAAATTTTAAAA +``` + +You can also replay a previously dumped CAN logfiles. These logfiles can be +found in _can_samples_ directory under Git repository. Following examples use +a real trip from an Auris Toyota car. + +Trace has been recorded from a CAN device `can0` so you have to map it to the +correct one you use for your tests. + +Replay on a virtual CAN device `vcan0`: + +```bash +canplayer -I trip_test_with_obd2_vehicle_speed_requests vcan0=can0 +``` + +Replay on a CAN device `can0`: + +```bash +canplayer -I trip_test_with_obd2_vehicle_speed_requests can0 +``` + +Replay on a CAN device `can1` (porter by example): + +```bash +canplayer -I trip_test_with_obd2_vehicle_speed_requests can1=can0 +``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png new file mode 100644 index 0000000..426e2f7 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png new file mode 100644 index 0000000..1f1d906 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png new file mode 100644 index 0000000..6e40336 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md new file mode 100644 index 0000000..a675c98 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md @@ -0,0 +1,32 @@ +--- +edit_link: '' +title: Architecture presentation +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-can-high-level-viwi/plain/docs/1-Architecture.md?h=master +--- + + + +# AGL VIWI HIGH-VIWI binding architecture + +This binding is intended to act between low-level binding(s) and clients. It builds ViWi resources as defined in a json configuration file. It implements subscribe/unsubscribe/get verbs for the clients accordingly with protocol specification. + +Each ViWi resource can be composed of several elements, for which subscriptions will be made to the low-level binding with configurable frequencies or filters. + +![ViWi High Level binding architecture](./images/high-level-arch.png) + + + +## Brief VIWI description + +ViWi (Volkswagen Infotainment Web Interface) protocol defines a serie of objects, which can be queried or updated via JSon messages. + +Each object is assigned with a unique URI. + +The depth of the URI tree is limited to 3, i.e. _/service/resource>/element/_, for instance **/car/doors/3901a278-ba17-44d6-9aef-f7ca67c04840**. + +To retrieve the list of elements for a given resource, one can use the get command, for instance **get /car/doors/**. + +It is also possible to subscribe to elements or group of elements, for instance **subscribe /car/doors/3901a278-ba17-44d6-9aef-f7ca67c04840**. Requests can also have various filters, or specify a frequency. + +More details in the [ViWi general documentation](https://www.w3.org/Submission/viwi-protocol/) and in the [ViWi.service.car documentation](https://www.w3.org/Submission/viwi-service-car/) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md new file mode 100644 index 0000000..cde838f --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md @@ -0,0 +1,208 @@ +--- +edit_link: '' +title: Installation and Usage Guide +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-can-high-level-viwi/plain/docs/2-Install-Usage.md?h=master +--- + + + +## Installation + +## Prerequisites + +Low level CAN service (>=4.0) must be installed. Prerequisites are the same. + +```bash +$ git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service +``` + +## Clone and build high level binding + +### Build requirements + +* CMake version 3.0 or later +* G++, Clang++ or any C++11 compliant compiler. + +### Clone + +```bash +$ export WD=$(pwd) +$ git clone --recusive https://github.com/iotbzh/high-level-viwi-service.git +``` + +### Build + +```bash +$ cd $WD/high-level-viwi-service +$ mkdir build +$ cd build +$ cmake .. +$ make +``` + + + +# Usage + +## JSON configuration file + +This file must be named *high.json*, and must accessible from afb-daemon. + +> **NOTE** A sample is available at the root of the git repository. + +The json configuration file consists in 2 sections: + +### Definitions section + +This section describes each resources defined in the high-level binding. Each resource is composed with different properties having a name, a type and a description. +Type can be boolean, double, string, or int. Properties "id", "uri" and "name" are compulsory. + +For instance: + +```json +{ + "name": "/car/demoboard/", + "properties": { + "id": { + "type": "string", + "description": "identifier" + }, + "uri": { + "type": "string", + "description": "object uri" + }, + "name": { + "type": "string", + "description": "name" + }, + "unit": { + "type": "string", + "description": "units" + }, + "speed": { + "type": "double", + "description": "vehicle centerpoint speed as shown by the instrument cluster" + }, + "rpm": { + "type": "double", + "description": "engine rotations per minute" + }, + "level": { + "type": "double", + "description": "level of tankage" + }, + "load": { + "type": "double", + "description": "engine load" + } + } +} +``` + + + +### Resources section + +This section defines which values should be assigned to resource's properties as defined in the definitions section. +The link to the definitions section is made through the name of the resource. + +Some values are static, some are linked to low-level requests. + +In case a value is linked to a low-level request, the value will start with "${" and end with "}". In that case the value will consist in the name of the low-level signal, followed +with the frequency of the signal in ms. -1 in the frequency means that high level binding should subscribe to low level binding for all changes, without specifying a frequency. + +For instance: +```json +{ + "name": "/car/demoboard/", + "values": [{ + "name": "vehicleSpeed", + "unit": "km/h", + "speed": "${diagnostic_messages.vehicle.speed,1000}" + }, { + "name": "engineSpeed", + "unit": "rpm", + "rpm": "${diagnostic_messages.engine.speed,1000}" + }, { + "name": "fuelLevel", + "unit": "litre", + "level": "${diagnostic_messages.fuel.level,1000}" + }, { + "name": "engineLoad", + "unit": "Nm", + "load": "${diagnostic_messages.engine.load,1000}" + }] +} +``` + + + +## Running and testing + +### Launch the binder together with the two bindings + +The Json high level configuration file *high.json* must be placed in the directory where you launch afb-daemon. + +```bash +$ cp $WD/high-level-viwi-service/high.json $WD + cd $WD +``` + +Then you can natively under linux you can launch afb-daemon with the low-level and high-level bindings with a command like: + +```bash +$ cd $WD +$ afb-daemon --rootdir=$WD/low-level-can-service/CAN-binder/build/package --binding=$WD/low-level-can-service/CAN-binder/build/package/lib/afb-low-can.so --binding=$WD/high-level-viwi-service/build/package/lib/afb-high-viwi.so --port=1234 --tracereq=common --token=1 --verbose +``` + +### Use afb-client-demo to test high level binding + +On another terminal, connect to the binding using previously installed _**AFB Websocket CLI**_ tool: + +```bash +$ afb-client-demo ws://localhost:1234/api?token=1 +``` + +You will be on an interactive session where you can communicate directly with the binding API. + +The binding provides at this moment 3 verbs, _get_, _subscribe_ and _unsubscribe_, which can take a JSON object as an argument. + + +To use the _**AFB Websocket CLI**_ tool, a command line will be like the following : + +``` + +``` + +Where: + +* API : _**high-viwi**_. +* Verb : _**get**_, _**subscribe**_ or _**unsubscribe**_ +* Arguments : _**{ "name": "/car/doors/" }**_ + +You can therefore use commands such as: + +``` +high-viwi subscribe {"name":"/car/doors/","interval":10000} +high-viwi unsubscribe {"name":"/car/doors/","interval":10000} +high-viwi get {"name":"/car/demoboard/"} +high-viwi get {"name":"/car/demoboard/","fields":["fuelLevel","engineLoad"]} +``` + +For instance the output of the third command should be: + +``` +high-viwi get {"name":"/car/demoboard/"} +ON-REPLY 1:high-viwi/get: {"response":{"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5":{"id":"2159e2-5b638a-39e242-7a2f5","name":"vehicleSpeed","speed":0.000000,"unit":"km\/h","uri":"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5"},"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82":{"id":"22ad2c-5a3c2b-50fabb-324c82","level":0.000000,"name":"fuelLevel","unit":"litre","uri":"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82"},"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf":{"id":"3a3ab9-2bd52c-11d30-689acf","name":"engineSpeed","rpm":0.000000,"unit":"rpm","uri":"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf"},"\/car\/demoboard\/5ae808-8093cb-99716-30a605":{"id":"5ae808-8093cb-99716-30a605","load":0.000000,"name":"engineLoad","unit":"Nm","uri":"\/car\/demoboard\/5ae808-8093cb-99716-30a605"}},"jtype":"afb-reply","request":{"status":"success","uuid":"44ce03f9-a7ca-49e1-a62a-40c74db0caa0"}} +``` + +As you can see for the moment all values are 0, because we didn't inject any CAN data in the binder. To do this, you can use **canplayer** to feed the bindings with some data. +You can find an example of data in high level binding, "samples" directory. + +For instance, on a third terminal: + +```bash +$ canplayer -I candata +``` + diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png new file mode 100644 index 0000000..b4a1e8c Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md new file mode 100644 index 0000000..62c2f0f --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md @@ -0,0 +1,73 @@ +--- +edit_link: '' +title: Architecture presentation +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/1-Architecture.md?h=master +--- + + + +# Signal Composer + +## Architecture + +Here is a quick picture about the signaling architecture : + +![GlobalArchitecture] + +Key here are on both layers, **low** and **high**. + +- **Low levels** binding used as _AGL service_, handle data exchange protocol to + decode/encode and retransmit with an AGL compatible format using **Application + Framework** events. These are divided into two parts, which are : + - A transport Layer binding's plug-in that is able to read/write from a device. + - Decoding/Encoding parts that expose signals. +- **High level signal composer** binding gathers multiple **low level** signaling + sources. Then from these sources, it exposes theirs **raw** signals or more interesting + can creates new virtuals signals from them. Example: + A signal made from gps latitude and longitude that computes the heading of + vehicle. This is modular and each signal source should be handled by specific + plugins which take care of get the underlying event from **low level** or + define signaling composition with simple or complex operation to output value + from **raw** signals. + +A transport plug-in is a shared library that shares a common API to be +compatible with **low level** services that is: + +- **open/close**: method to open a handle which could be a socket, file or + device by example. +- **read/write**: method to read and write a stream of data. + +Configuration is made by sending a special packet using a write method to the +handle. In brief, this could be compared to the layer 1 and 2 of [OSI model]. + +There are three main parts with **Signal Composer**: + +- Configuration files which could be splitted in differents files. That will + define: + - metadata with name of **signal composer** api name + - additionnals configurations files + - plugins used if so, **low level** signals sources + - signals definitions +- Dedicated plugins +- Signal composer API + +## Terminology + +Here is a little terminology guide to set the vocabulary: + +- **api**: a binding API name +- **action**: a function called at a certain time +- **callbacks**: a function called at a certain time +- **event**: the raw event that materialize the signal +- **plugins**: a C/C++ code with functions that be called by signal composer + service +- **sources**: an external binding API that generate signals for the signal + composer service +- **signals**: an event generated by the **Application Framework** +- **virtual signals**: a signal composed of **raw signals** with value + calculated by a **callbacks** +- **raw signals**: an event generated by a **low level** binding + +[OSI model]: https://en.wikipedia.org/wiki/OSI_model +[GlobalArchitecture]: pictures/Global_Signaling_Architecture.png "Global architecture" diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md new file mode 100644 index 0000000..6bd3a8a --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md @@ -0,0 +1,109 @@ +--- +edit_link: '' +title: Configuration +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/2-Configuration.md?h=master +--- + + + +# Configuration + +Configuration defines all in **Signal composer** each signals and sources has +to be defined in it. At start, configuration will be searched in default +binding configuration directory which should be _/var/local/lib/afm/applications/signal-composer/VER/etc/_, +VER is the version of **signal composer**. +Binding search for a file name as _init-daemon*.json_. Others files could be +used to split sections and don't have 1 big fat definitions file. + +Saying that you have 4 sections to define: + +- **metadata**: Main parts and the only one that can't be in a separates + configuration. This must appears in the main configuration file. +- **plugins** (optional): Declare plugins that will be used by *sources* and + *signals* for the subscription and composition. +- **sources**: Declare **low level** signals sources (eg. low-can, gps, mraa, + ...). +- **signals**: Declare signals, virtuals and raw. + +## Metadata + +Here we define some metadata about **signal composer** binding. Fields to configure +are : + +- **uid**: self-explanatory +- **version** (optional): self-explanatory +- **api** (optional): name that the binding will be initialized to and later + be accessible by **Application Framework** +- **info** (optional): self-explanatory +- **require** (optional): list of required external apis. + +## Plugins + +This section is the only which is optional, it is needed if you develop +specifics C/C++ plugins to be used with signal-composer. LUA and API +consumption does not need plugins. + +Default path to search for a plugin is in the binding library directory +in a subdirectory _plugins_ _/var/local/lib/afm/applications/signal-composer/VER/lib/plugins_. +Else you could use the environment variable _CONTROL_PLUGIN_PATH_ with a +semicolon separated list of directory. + +Fields are: + +- **uid**: Define the plugin name. This is that label that will be used on + **sources** and **signals** callbacks. +- **ldpath** (optional): path to the plugin directory +- **info** (optional): self-explanatory +- **basename**: shared library file name **without** the extension. +- **files** (optional): list of additionnals files. **ONLY NAME** or part of + it, without extension. Don't mix up section object with this key, either one + or the other but avoid using both + +## Sources + +A source is a **low level** API that will be consume by the **signal composer** +to be able to expose those signals with additionnals treatments, filtering, +thinning,... and create new virtuals signals composed with basic raw signals. + +A source is defined with following fields: + +- **uid**: An unique identifier name for thatuid source API. +- **api**: Name of the source API. +- **info** (optional): self-explanatory +- **init** (optional): an **action** to take to initialize a source. May you + have to call a verb from that API, of create a files etc. +- **getSignals** (optional); an **action** to take to get signals from that + source. These callback will be used for each signals defined later in the + **signals** section. Dedicated arguments for each signal could be defined in + **signals**. +- **files** (optional): list of additionnals files. **ONLY NAME** or part of + it, without extension. Don't mix up section object with this key, either one + or the other but avoid using both + +## Signals + +A signal definition could be either a **raw** one or a **virtual** one. A + **virtual signal** is a set of existing **raw signals** associated to an + **action** on reception which will compute the value of the signal. + +- **uid**: Unique identifier used inside **signal composer**, used to compose + virtual signals. +- **event**: specify a **raw signal** coming from **low level** sources. + Couldn't be used with **depends** field, only one of them is possible. +- **depends**: specify others signals **id** that compose it (eg: heading is + composed with longitude+latitude signals.). Couldn't be used with **event** + field at same time. +- **retention** (optional): retention duration in seconds +- **unit** (optional): Unit used to exprime the signal +- **frequency** (optional): Frequency maximum at which the signal could be + requested or sent. This is a thinning made at **high level** so not best + suited for performance. Used **low level** native filtering capabilities when + possible. +- **getSignalsArgs**: a JSON object used at subscription time. Meant to enabled + filtering capabilities at subscription and to be able to customize in general + a subcription request by signal if needed. +- **onReceived**: an **action** to take when this signal is received! +- **files** (optional): list of additionnals files. **ONLY NAME** or part of + it, without extension. Don't mix up section object with this key, either one + or the other but avoid using both diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md new file mode 100644 index 0000000..aa0ebb4 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md @@ -0,0 +1,32 @@ +--- +edit_link: '' +title: Plugins +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/3-Plugins.md?h=master +--- + + + +# Plugins + +Plugins are C/C++ shared libraries loaded by the binding to execute some +simple routine. Routine could be on reception of a new signal or at sources +initialization time or signal subscription with the respective JSON field +`onReceived` `init` and `getSignals` + +A default plugin (builtin) is provided with 2 functions: + +- **defaultOnReceived**: set and record a new signal value and its timestamp + in the signal composer service. It simply tooks the incoming event JSON object + and search for *key* `value` and `timestamp` then call function + `setSignalValue`. +- **setSignalValueWrap**: a `lua2c` function the could be called from any LUA + script to record a new signal value. + +> **CAUTION**: `timestamp` value has to be typed as *uint64_t* with +> a **nanosecond** precision using a realtime clock. To correctly store it in +> a JSON-C object use the int64 type with the according fonctions: +> *json_object_new_int64()* +> *json_object_get_int64()* +> *json_object_set_int64()* +> *...* diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md new file mode 100644 index 0000000..cc1688c --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md @@ -0,0 +1,71 @@ +--- +edit_link: '' +title: Signal Composer API +origin_url: >- + https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/4-SignalComposerAPI.md?h=master +--- + + + +# Signal Composer API + +## subscribe/unsubscribe + +Using subscribe you can get update on change for signals you chose and you can +using wildcard to subscribe several signals in the same time. + +```json +signal-composer subscribe {"signal": "rear_left*"} +ON-REPLY 1:signal-composer/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"3d4b743b-7ac6-4d3c-8fce-721107f9dee5"}} +``` + +Then event comes up like the following: + +```json +ON-EVENT signal-composer/257b343e-8ea9-4cd7-8f9e-1904fa77f8f2({"event":"signal-composer\/257b343e-8ea9-4cd7-8f9e-1904fa77f8f2","data":{"uid":"rear_left_door","event":"low-can\/messages.doors.rear_left.open","timestamp":4833910845032292484,"value":false},"jtype":"afb-event"}) +``` + +Unsubscribe happens the same way. When no more signals are holded by the client +then it unsubscribe from the *AGL Application Framework* event handle. + +## addObjects + +Let you add sources or signals objects to the signal composer service after +its initialization phase. Use this verb and specify the file as argument, you +could use only the file name or the file name with its absolute path. + +```json +signal-composer addObjects {"file": "sig_doors.json"} +ON-REPLY 1:signal-composer/addObjects: {"jtype":"afb-reply","request":{"status":"success","uuid":"00d7a519-816e-486a-8163-3afb1face4fa"}} +signal-composer addObjects {"file": "/tmp/sig_doors.json"} +ON-REPLY 2:signal-composer/addObjects: {"jtype":"afb-reply","request":{"status":"success"}} +``` + +You can follow the activity using the service log journal and check that the +correct number of objects has been added. + +> **CAUTION**: You need to get the following permission to be able to load new +objects : `urn:AGL:permission::platform:composer:addObjects` + +## get + +You can get a signal value be requesting the API with the verb *get*: + +```json +signal-composer get {"signal": "vehicle_speed", "options": {"average": 10}} +signal-composer get {"signal": "vehicle_speed", "options": {"minimum": 10}} +signal-composer get {"signal": "vehicle_speed", "options": {"maximum": 10}} +signal-composer get {"signal": "vehicle_speed"} +``` + +You apply some simple mathematical functions by default present in the +binding, by default **last** is used: + +- **average**: make an average on X latest seconds. +- **minimum**: return the minimum value found in the X latest seconds. +- **maximum**: return the maximum value found in the X latest seconds. +- **last**: return the latest value. + +## list + +Verb **list** will output the list of defined signals. diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png new file mode 100644 index 0000000..5cfba98 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf b/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf new file mode 100644 index 0000000..885695d Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md new file mode 100644 index 0000000..52718e2 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md @@ -0,0 +1 @@ +[**4.5.5_AGL-Message-Signaling-Developer-Guidelines**](4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf b/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf new file mode 100644 index 0000000..25823c8 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md new file mode 100644 index 0000000..b9b0316 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md @@ -0,0 +1 @@ +[**4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf**](4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md new file mode 100644 index 0000000..a58171c --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md @@ -0,0 +1,26 @@ +--- +edit_link: '' +title: Usage Guide +origin_url: >- + https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/1_Usage.md +--- + + + +# Usage + +You can find the installation part +[here](http://docs.automotivelinux.org/master/docs/devguides/en/dev/reference/host-configuration/docs/5_Candevstudio.html). + +The official repo of CanDevStudio is a subpart of GENIVI and can be found +[here](https://github.com/GENIVI/CANdevStudio/). + +Launch it with following command: + +```bash +CANdevStudio +``` + +Then start a new project. + +![CANdevStudio general screenshot](pictures/CANdevStudio.png) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md new file mode 100644 index 0000000..1a6a52b --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md @@ -0,0 +1,44 @@ +--- +edit_link: '' +title: Bringing up a CAN device using socketcan backend +origin_url: >- + https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/2_can_device_socketcan_backend.md +--- + + + +# Bringing up a CAN device using socketcan backend + +* [Using a supported Linux CAN device](https://www.elinux.org/CAN_Bus): + +```bash +# Find your interface name (e.g. can0) +ip link +# Configure bitrate +sudo ip link set can0 type can bitrate 1000000 +# Bring the device up +sudo ip link set can0 up +# Optionally configure CAN termination +sudo ip link set can0 type can termination 1 +``` + +## Using slcand + +* Based on FTDI Serial driver +* Requires slcand to "convert" serial device to SocketCAN. +* Officially supported in Linux Kernel v2.6.38 + +```bash +# Create SocketCAN device from serial interface +sudo slcand -o -c -s8 -S1000000 /dev/ttyUSB0 can0 +# Bring the device up +sudo ip link set can0 up +``` + +## Using builtin Linux kernel virtual CAN module vcan + +```bash +sudo modprobe vcan +sudo ip link add dev can0 type vcan +sudo ip link set can0 up +``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md new file mode 100644 index 0000000..9eef2c7 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md @@ -0,0 +1,41 @@ +--- +edit_link: '' +title: Add a CAN device in CANdevStudio +origin_url: >- + https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/3_Add_CAN_Device.md +--- + + + +# Add a CAN device in CANdevStudio + +Start a new project and grab a ***CanDevice*** from the left pane in the +***Device Layer*** section and drop it on the grid workspace. Right-Click on it +and open its ***Properties***. Here you have to set the ***backend*** and the +***interface*** name you'll want to use. Backend available are: + +- socketcan: CAN stack present by default in the Linux Kernel. This use Linux socket and open source CAN device driver (More information here). +- systeccan: CAN bus backend using the SYS TEC CAN adapters. +- peakcan: CAN bus plugin using the PEAK CAN adapters. +- tinycan: CAN bus plugin using the MHS CAN adapters. +- vectorcan: CAN bus plugin using the Vector CAN adapters. + +More details about CANdevStudio CAN bus support [here](http://doc.qt.io/qt-5.10/qtcanbus-backends.html). + +***Interface*** is the name of the device you want to use. Bring up your CAN device and use the following command to find out which one are available: + +```bash +ip link +1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: enp0s25: mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000 + link/ether 90:b1:1c:6b:b2:21 brd ff:ff:ff:ff:ff:ff +3: virbr0: mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default qlen 1000 + link/ether 52:54:00:56:86:80 brd ff:ff:ff:ff:ff:ff +4: virbr0-nic: mtu 1500 qdisc fq_codel master virbr0 state DOWN mode DEFAULT group default qlen 1000 + link/ether 52:54:00:56:86:80 brd ff:ff:ff:ff:ff:ff +5: docker0: mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default + link/ether 02:42:81:38:a8:75 brd ff:ff:ff:ff:ff:ff +12: can0: mtu 72 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 + link/can +``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md new file mode 100644 index 0000000..9fc2675 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md @@ -0,0 +1,28 @@ +--- +edit_link: '' +title: Configure a CanRawSender node +origin_url: >- + https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/4_Configure_CanRawSender_Node.md +--- + + + +# Configure a CanRawSender node + +CanRawSender node lets you set a predefined list of CAN Raw messages to send. + +![CanRawSender screenshot](pictures/canrawsender.png) + +Click on the + sign to add as much as needed signals to send. For each signals, you has to define: + +- the CAN arbitration ID +- Data load +- Loop checkbox make the signal repeat infinitely +- Interval is used with loop to define how much time between 2 sends + +Once clicked on ***Play*** button in the main Window to launch the simulation, +then each signals will be sent in the same order than defined in the +CanRawSender node then using interval to repeat themselves. + +Signals without ***loop*** checked will not be sent, you have to click manually +on the ***Send*** button to trigger a sending. diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md new file mode 100644 index 0000000..0d44a87 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md @@ -0,0 +1,18 @@ +--- +edit_link: '' +title: Using CanRawView +origin_url: >- + https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/5_Using_CanRawView.md +--- + + + +# Using CanRawView + +***CanRawViewer*** is pretty simple to use, once simulation launched you'll see +signal flows in the window. You can use ***Clear*** button to wipe the window. + +![CanRawViewer screenshot](pictures/canrawviewer.png) + +Use the ***Combine*** button to stack by arbitration ID the CAN signals. +Then only the latest signal for each arbitration ID will be displayed. diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png new file mode 100644 index 0000000..c944e02 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png new file mode 100644 index 0000000..766ca63 Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png new file mode 100644 index 0000000..f20488b Binary files /dev/null and b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md new file mode 100644 index 0000000..dd52e88 --- /dev/null +++ b/docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md @@ -0,0 +1,95 @@ +--- +edit_link: '' +title: Resources +origin_url: >- + https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/app-framework/index.md +--- + + + +# AGL Application Framework + +This page summarizes all materials related to AGL Application Framework + +## Source Code + +The current code of AGL App-Framework is stored on AGL Code Repository. It's divided in the following projects: + +* [src/app-framework-main](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-main.git;a=summary) Main services +* [src/app-framework-binder](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-binder.git;a=summary): Binder Daemon +* [src/app-framework-demo](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-demo.git;a=summary) Demos + +## Building AGL with Application Framework support + +The Application Framework can be added easily to an AGL build using the feature 'agl-appfw-smack'. + +Typically, the following command can be called to initialize AGL build: + + # meta-agl/scripts/aglsetup.sh -m porter agl-appfw-smack agl-demo agl-devel + ... + # bitbake agl-demo-platform + +## Documentation + +Technical documentation is maintained in the source code and should be browsable with the [upcoming AGL documentation system](https://github.com/automotive-grade-linux/docs-agl) + +Temporarily, a static documentation has been made in PDF format: + +* [Introduction to Application Framework](http://iot.bzh/download/public/2016/appfw/01_Introduction-to-AppFW-for-AGL-1.0.pdf) +* [AppFW Core Documentation](http://iot.bzh/download/public/2016/appfw/02_Documentation-AppFW-Core-2.0.pdf) +* [Privileges Management](http://iot.bzh/download/public/2016/appfw/03-AGL-AppFW-Privileges-Management.pdf) + +Some extra guides are also available in PDF format: + +* [Build your 1st AGL Application](http://iot.bzh/download/public/2016/sdk/AGL-Devkit-Build-your-1st-AGL-Application.pdf) +* Applications Templates are available on [github:iotbzh/app-framework-templates](https://github.com/iotbzh/app-framework-templates) + +### Bindings Examples + +Some bindings are available to quickstart new projects: + +* GPS - see [github:iotbzh/af-gps-binding](https://github.com/iotbzh/af-gps-binding/blob/master/src/af-gps-binding.c) +* OpenXC Reader - see [github:iotbzh/txc-demo](https://github.com/iotbzh/txc-demo/blob/master/binding/txc-binding.c) +* CPU/Memory stats - see [github:iotbzh/txc-demo](https://github.com/iotbzh/txc-demo/blob/master/binding/stat-binding.c) +* Radio - see [gerrit:src/app-framework-binder](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=tree;f=bindings/radio;hb=master) +* Audio - see [gerrit:src/app-framework-binder](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=tree;f=bindings/audio;hb=master) + +The list is not exhaustive. ***Please add other bindings here !*** + +### Demos + +* Simple HTML5 Demos apps (ported from Tizen) on [github:iotbzh/afm-widget-examples](https://github.com/iotbzh/afm-widget-examples) +* Installable package with [TXC Demo Application](http://iot.bzh/download/public/2016/afb-demos/txc-demo_0.1.wgt) +* Applications available in [gerrit:app-framework-demo](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=summary) + +## Presentations + +* Oct 16 - [Application Security Model - Status Update](http://iot.bzh/download/public/2016/genivi/CyberSecurity-Genivi-Q42016-Fulup-IoTbzh.pdf) +* Sept 16 - [Building Applications with AGL Framework](http://iot.bzh/download/public/2016/genivi/CyberSecurity-Genivi-Q42016-Fulup-IoTbzh.pdf) - Also visible in [PDF version](http://iot.bzh/download/public/2016/publications/build-agl-application-AMM-Munich-2016.pdf) +* Feb 16 - [HTML5 Apps for Automotive Systems](http://iot.bzh/download/public/2016/publications/HTML5_Applications_for_Automotive_Systems.pdf) +* Feb 16 - [Application & Security Framework Proposal AGL 2.0](http://iot.bzh/download/public/2016/security/Security-Proposal-AGL20-Fulup.pdf) +* Jan 16 - [Security Architecture Proposal](http://iot.bzh/download/public/2016/security/Security-Architecture-AGL20.pdf) + +## History + +### Motivation for rewriting the App. Framework + +To get the background and motivation on why Application Framework has been rewritten: + +* [Tizen Security: lessons learnt](http://iot.bzh/download/public/2015/tizen-security-lessons-learnt-initial.pdf) +* [this discussion](https://lists.linuxfoundation.org/pipermail/automotive-discussions/2016-October/002749.html) +* [Linux Automotive Security](http://iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf) + +### Comparison/Relationship with Tizen + + Tizen AGL + ---------------------------------- + App/OS isolation yes yes + Container option no possible + Native App partial* yes + HTML5 App yes yes + Cloud App No yes + Unified API (HTLM/Native) No yes + service as App** No yes + Adding API *** core core or App + Devel model bespoke Standard Web -- cgit 1.2.3-korg