X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2F3-Usage.md;h=daeca878592281c1cd9c92e72cab0d600e0ffde9;hb=492459d87d6dfd2926a551a0e1a679d332d7d1a4;hp=73600a7212893d5e8e1ba3b6c3bb6f17f0bac6ee;hpb=2cf6a1685f3ad53db6714c01d600492fe4bfc11b;p=apps%2Fagl-service-can-low-level.git diff --git a/docs/3-Usage.md b/docs/3-Usage.md index 73600a72..daeca878 100644 --- a/docs/3-Usage.md +++ b/docs/3-Usage.md @@ -1,86 +1,34 @@ -# Install AFB Websocket CLI client to test the binding. +# Configure the AGL system -You can test it using afb-client-demo CLI tool provided by the RPM package _libafbwsc-dev_. +## Virtual CAN device -You can find this package in your build environment, using docker SDK recommended setup the file is `/xdt/build/tmp/deploy/rpm//`. - -After a successful bitbake build and using Renesas RCar Gen2, Porter, you have to copy the file if your board is connected to your network and you know its IP address: - -```bash -$ scp /xdt/build/tmp/deploy/rpm/cortex15hf_neon/libafbwsc-dev-1.0-r0.cortexa15hf_neon.rpm root@:~ -``` - -Else, you have to copy into the SDcard with the AGL image installed on it. - -From the docker image copy RPM to the shared directory between docker image and your host: - -```bash -$ cp /xdt/build/tmp/deploy/rpm/cortex15hf_neon/libafbwsc-dev-1.0-r0.cortexa15hf_neon.rpm ~/share -``` - -Then plugin you SDcard in your Linux host \(Windows can't read ext4 filesystem AGL runs on\) and copy RPM file on it. - -From your host, identify SDcard block device node here it is **sdc** with the correct capacity automounted by the desktop manager: - -```bash -$ lsblk -loop1 7:1 0 2G 0 loop -└─docker-253:0-3146365-pool 253:3 0 100G 0 dm - └─docker-253:0-3146365-e9f80849a2681e18549d3a4238cbf031e44052e36cd88a0abf041804b799b61c - 253:4 0 10G 0 dm /var/lib/docker/devicemapper/mnt/e9f80849a2681e18549d3a4238cbf031e44052e36cd88a0abf041804b799b61c -sdb 8:16 0 238.5G 0 disk -├─sdb2 8:18 0 238G 0 part -│ └─Shamash-agl 253:1 0 238G 0 lvm /home/claneys/Workspace/agl-docker -└─sdb1 8:17 0 500M 0 part /boot -sr0 11:0 1 1024M 0 rom -loop0 7:0 0 100G 0 loop -└─docker-253:0-3146365-pool 253:3 0 100G 0 dm - └─docker-253:0-3146365-e9f80849a2681e18549d3a4238cbf031e44052e36cd88a0abf041804b799b61c - 253:4 0 10G 0 dm /var/lib/docker/devicemapper/mnt/e9f80849a2681e18549d3a4238cbf031e44052e36cd88a0abf041804b799b61c -sdc 8:32 1 14.9G 0 disk -└─sdc1 8:33 1 2G 0 part /run/media/claneys/97f418a5-612f-44e9-b968-a19505695151 -sda 8:0 0 931.5G 0 disk -├─sda2 8:2 0 500G 0 part -│ ├─Shamash-home 253:2 0 150G 0 lvm /home -│ └─Shamash-root 253:0 0 50G 0 lvm / -└─sda1 8:1 0 16G 0 part [SWAP] -``` - -Copy, still from your host: - -> **CAUTION:** Make sure to sync IO with sync command before unplug your SDcard. It could be corrupted if removed before all pending IO aren't done. +Connected to the target, here is how to load the virtual CAN device driver and +set up a new vcan device : ```bash -$ sudo umount /dev/sdc1 -$ export SDCARD=/mnt -$ sudo mount /dev/sdc1 $SDCARD -$ sudo cp ~/devel/docker/share/libafbwsc-dev-1.0-r0.cortexa15hf_neon.rpm $SDCARD/home/root -$ sync -$ sudo umount $SDCARD +modprobe vcan +ip link add vcan0 type vcan +ip link set vcan0 up ``` -Insert the modified SDcard in your Porter board and boot from it. You are ready to go. - -## 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 : +You also can named your linux CAN device like you want and if you need name it +`can0` : ```bash -# modprobe vcan -# ip link add vcan0 type vcan -# ip link set vcan0 up +modprobe vcan +ip link add can0 type vcan +ip link set can0 up ``` -### CAN device using the USB CAN adapter +## 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. +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 : +Once connected, launch `dmesg` command and search which device to use: ```bash -# dmesg +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) @@ -97,12 +45,13 @@ Once connected, launch `dmesg` command and search which device to use : 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: +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 +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 @@ -112,14 +61,15 @@ This instruction assuming a speed of 500000kbps for your CAN bus, you can try ot clock 16000000 ``` -For a Porter board, you'll have your CAN device as `can1` because `can0` already exists as an embedded device. +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 +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 @@ -129,85 +79,108 @@ The instructions will be the same: clock 16000000 ``` -## Configure the binding +## Rename an existing CAN device -Configure the binding specifying in the JSON configuration file the CAN device\(s\) that it will to connect to. Edit file _/var/lib/afm/applications/low-can-binding/0.1/can\_buses.json_ and change the CAN device name to the one you will use : +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: -Using virtual CAN device as described in the previous chapter: -```json -{ - "canbus": "vcan0" -} +```bash +sudo ip link set can0 down +sudo ip link set can0 name bsp-can0 +sudo ip link set bsp-can0 up ``` -Using real CAN device, this example assume CAN bus traffic will be on can0. -```json -{ - "canbus": "can0" -} +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" ``` -On a Porter board there is an embedded CAN device so `can0` already exists. +* Using real CAN device, this example assume CAN bus traffic will be on can0. -So you might want to use your USB CAN adapter plugged to the OBD2 connector, in this case use `can1`: -```json -{ - "canbus": "can1" -} +```ini +[CANbus-mapping] +hs="can0" +ls="can1" ``` -If you have several specify CAN bus devices use an array: +* 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`: -```json -{ - "canbus": [ "can0", "can1" ] -} +```ini +[CANbus-mapping] +hs="can1" ``` -> **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](http://github.com/iotbzh/can-config-generator). +> **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`. -## Run it, test it, use it ! +# 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-binding@0.1 +afm-util run low-can-service@4.0 1 ``` -You can find instructions to use afm-util tool [here](http://docs.iot.bzh/docs/apis_services/en/dev/reference/af-main/afm-daemons.html#using-afm-util), as well as documentation about Application Framework. +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. +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, we will use port **1234** and left empty security token for testing purpose: +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 --ldpaths=/usr/lib/afb:/var/lib/afm/applications/low-can-binding/0.1/libs/ --rootdir=/var/lib/afm/applications/low-can-binding/0.1/ --port=1234 --token= +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-binding/0.1/libs//low-can-binding.so] calling registering function afbBindingV1Register -NOTICE: binding /var/lib/afm/applications/low-can-binding/0.1/libs//low-can-binding.so loaded with API prefix low-can -NOTICE: Waiting port=1234 rootdir=/var/lib/afm/applications/low-can-binding/0.1/ +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 -NOTICE: vcan0 device opened and reading {binding low-can} -NOTICE: Initialized 1/1 can bus device(s) {binding low-can} ``` -On another terminal, connect to the binding using previously installed _**AFB Websocket CLI**_ tool: +On another terminal, connect to the binding using previously installed +**AFB Websocket CLI** tool: ```bash -# afb-client-demo ws://localhost:1234/api?token= +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. +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 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. +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 : +To use the _**AFB Websocket CLI**_ tool, a command line will be like the +following: ``` @@ -219,11 +192,13 @@ Where: * Verb : _**subscribe**_ or _**unsubscribe**_ * Arguments : _**{ "event": "driver.doors.open" }**_ -### Subscription and unsubscription +## 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. +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. +> **NOTE:** If no argument is provided, then you'll subscribe to all signals +> at once. For example from a websocket session: @@ -241,17 +216,23 @@ 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_ +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},"jtype":"afb-event"}) +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_. +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 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: +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. @@ -271,43 +252,120 @@ low-can unsubscribe { "event" : "doors*" } ON-REPLY 3:low-can/unsubscribe: {"jtype":"afb-reply","request":{"status":"success"}} ``` -### Using CAN utils to monitor CAN activity +### Filtering capabilities -You can watch CAN traffic and send custom CAN messages using can-utils preinstalled on AGL target. +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) + +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}} +``` + +## 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 + +A new capability as been introcuded to be able to write on handled 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 and its value. + +Examples: + +```json +# 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} +``` + +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 +candump can0 ``` Or for an USB CAN adapter connected to porter board: ```bash -# candump can1 +candump can1 ``` Send a custom message: ```bash -# cansend can0 ID#DDDDAAAATTTTAAAA +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. +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. +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 +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 +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 +canplayer -I trip_test_with_obd2_vehicle_speed_requests can1=can0 ```