docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md

   1 ---
   2 edit_link: ''
   3 title: Installation and Usage Guide
   4 origin_url: >-
   5   https://git.automotivelinux.org/apps/agl-service-can-high-level-viwi/plain/docs/2-Install-Usage.md?h=master
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/high-level-developer-guides-api-services-book.yml -->
   9
  10 ## Installation
  11
  12 ## Prerequisites
  13
  14 Low level CAN service (>=4.0) must be installed. Prerequisites are the same.
  15
  16 ```bash
  17 $ git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service
  18 ```
  19
  20 ## Clone and build high level binding
  21
  22 ### Build requirements
  23
  24 * CMake version 3.0 or later
  25 * G++, Clang++ or any C++11 compliant compiler.
  26
  27 ### Clone
  28
  29 ```bash
  30 $ export WD=$(pwd)
  31 $ git clone --recusive https://github.com/iotbzh/high-level-viwi-service.git
  32 ```
  33
  34 ### Build
  35
  36 ```bash
  37 $ cd $WD/high-level-viwi-service
  38 $ mkdir build
  39 $ cd build
  40 $ cmake ..
  41 $ make
  42 ```
  43
  44
  45
  46 # Usage
  47
  48 ## JSON configuration file
  49
  50 This file must be named *high.json*, and must accessible from afb-daemon.
  51
  52 > **NOTE** A sample is available at the root of the git repository.
  53
  54 The json configuration file consists in 2 sections:
  55
  56 ### Definitions section
  57
  58 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.
  59 Type can be boolean, double, string, or int. Properties "id", "uri" and "name" are compulsory.
  60
  61 For instance:
  62
  63 ```json
  64 {
  65         "name": "/car/demoboard/",
  66         "properties": {
  67                 "id": {
  68                         "type": "string",
  69                         "description": "identifier"
  70                 },
  71                 "uri": {
  72                         "type": "string",
  73                         "description": "object uri"
  74                 },
  75                 "name": {
  76                         "type": "string",
  77                         "description": "name"
  78                 },
  79                 "unit": {
  80                         "type": "string",
  81                         "description": "units"
  82                 },
  83                 "speed": {
  84                         "type": "double",
  85                         "description": "vehicle centerpoint speed as shown by the instrument cluster"
  86                 },
  87                 "rpm": {
  88                         "type": "double",
  89                         "description": "engine rotations per minute"
  90                 },
  91                 "level": {
  92                         "type": "double",
  93                         "description": "level of tankage"
  94                 },
  95                 "load": {
  96                         "type": "double",
  97                         "description": "engine load"
  98                 }
  99         }
 100 }
 101 ```
 102
 103 <!-- pagebreak -->
 104
 105 ### Resources section
 106
 107 This section defines which values should be assigned to resource's properties as defined in the definitions section.
 108 The link to the definitions section is made through the name of the resource.
 109
 110 Some values are static, some are linked to low-level requests.
 111
 112 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
 113 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.
 114
 115 For instance:
 116 ```json
 117 {
 118         "name": "/car/demoboard/",
 119         "values": [{
 120                 "name": "vehicleSpeed",
 121                 "unit": "km/h",
 122                 "speed": "${diagnostic_messages.vehicle.speed,1000}"
 123         }, {
 124                 "name": "engineSpeed",
 125                 "unit": "rpm",
 126                 "rpm": "${diagnostic_messages.engine.speed,1000}"
 127         }, {
 128                 "name": "fuelLevel",
 129                 "unit": "litre",
 130                 "level": "${diagnostic_messages.fuel.level,1000}"
 131         }, {
 132                 "name": "engineLoad",
 133                 "unit": "Nm",
 134                 "load": "${diagnostic_messages.engine.load,1000}"
 135         }]
 136 }
 137 ```
 138
 139 <!-- pagebreak -->
 140
 141 ## Running and testing
 142
 143 ### Launch the binder together with the two bindings
 144
 145 The Json high level configuration file *high.json* must be placed in the directory where you launch afb-daemon.
 146
 147 ```bash
 148 $ cp $WD/high-level-viwi-service/high.json $WD
 149  cd $WD
 150 ```
 151
 152 Then you can natively under linux you can launch afb-daemon with the low-level and high-level bindings with a command like:
 153
 154 ```bash
 155 $ cd $WD
 156 $ 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
 157 ```
 158
 159 ### Use afb-client-demo to test high level binding
 160
 161 On another terminal, connect to the binding using previously installed _**AFB Websocket CLI**_ tool:
 162
 163 ```bash
 164 $ afb-client-demo ws://localhost:1234/api?token=1
 165 ```
 166
 167 You will be on an interactive session where you can communicate directly with the binding API.
 168
 169 The binding provides at this moment 3 verbs, _get_, _subscribe_ and _unsubscribe_, which can take a JSON object as an argument.
 170
 171
 172 To use the _**AFB Websocket CLI**_ tool, a command line will be like the following :
 173
 174 ```
 175 <api> <verb> <arguments>
 176 ```
 177
 178 Where:
 179
 180 * API : _**high-viwi**_.
 181 * Verb : _**get**_, _**subscribe**_ or _**unsubscribe**_
 182 * Arguments : _**{ "name": "/car/doors/" }**_
 183
 184 You can therefore use commands such as:
 185
 186 ```
 187 high-viwi subscribe {"name":"/car/doors/","interval":10000}
 188 high-viwi unsubscribe {"name":"/car/doors/","interval":10000}
 189 high-viwi get {"name":"/car/demoboard/"}
 190 high-viwi get {"name":"/car/demoboard/","fields":["fuelLevel","engineLoad"]}
 191 ```
 192
 193 For instance the output of the third command should be:
 194
 195 ```
 196 high-viwi get {"name":"/car/demoboard/"}
 197 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"}}
 198 ```
 199
 200 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.
 201 You can find an example of data in high level binding, "samples" directory.
 202
 203 For instance, on a third terminal:
 204
 205 ```bash
 206 $ canplayer -I candata
 207 ```
 208