docs/2-Installation.md

   1 # Prerequisites
   2
   3 * An AGL system installed with latest Chinook version \(&gt;3.0.2\).
   4
   5 * Make sure you built the AGL generator else you will not be able to generate custom low-level CAN binding. Generator can be found [here](http://github.com/iotbzh/can-config-generator) with the attached instruction to install and run it.
   6
   7 It will produce a _configuration-generated.cpp_ file to paste in the source, _src/_, directory.
   8
   9 * Make sure you already set up the AGL SDK using the following [guide](http://docs.iot.bzh/docs/getting_started/en/dev/reference/setup-sdk-environment.html).
  10
  11 To get the correct SDK version installed, you **must** prepare your environment with the **chinook-next** version. To do so, run the following command in your docker image:
  12
  13 > **NOTE** This command assume that proprietary graphic drivers for Renesas Porter board are located in `/home/devel/share/proprietary-renesas-rcar` directory.
  14
  15 ```bash
  16 $ prepare_meta -f chinook-next -o /xdt -l /home/devel/mirror -p /home/devel/share/proprietary-renesas-rcar/ -t porter -e wipeconfig -e rm_work
  17 ```
  18
  19 * An [USB CAN adapter](http://shop.8devices.com/usb2can) connected to connector through the [right cable](http://www.mouser.fr/ProductDetail/EasySync/OBD-M-DB9-F-ES/)).
  20
  21 # Getting started
  22
  23 ## Use of CAN config generator
  24
  25 ### Build requirements
  26
  27 * CMake version 3.0 or later
  28 * G++, Clang++ or any C++11 complient compiler.
  29 * Boost
  30   * filesystem
  31   * program\_options
  32   * system
  33
  34 You can install any of these using your package manager. For instance, inside the iotbzh's docker image, you must enter this command :
  35
  36 ```bash
  37 $ sudo apt-get update
  38 $ sudo apt-get install libboost-system-dev libboost-filesystem-dev libboost-program-options-dev
  39 ```
  40
  41 You may want to install `libboost-all-dev` to get all boost components even if it's not required.
  42
  43 ### Compile
  44
  45 > **CAUTION** It is **very important** that you do not source the SDK environment file to compile this project because some build requirements aren't installed in the AGL SDK for now.
  46
  47 ```bash
  48 $ export PATH=$PATH:/xdt/sdk/sysroots/x86_64-aglsdk-linux/usr/bin
  49 $ export WD=$(pwd)
  50 $ git clone https://github.com/iotbzh/can-config-generator.git
  51 $ cd can-config-generator
  52 $ mkdir -p build
  53 $ cd build
  54 $ cmake -G "Unix Makefiles" ..
  55 $ make
  56 ```
  57
  58 ### Naming convention
  59
  60 We chose a doted naming convention because it's a well know schema.
  61
  62 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.
  63
  64 Let's take an example, here is an example about standard PID name following this convention:
  65
  66 ```
  67 engine.load
  68 engine.coolant.temperature
  69 fuel.pressure
  70 intake.manifold.pressure
  71 engine.speed
  72 vehicle.speed
  73 intake.air.temperature
  74 mass.airflow
  75 throttle.position
  76 running.time
  77 EGR.error
  78 fuel.level
  79 barometric.pressure
  80 commanded.throttle.position
  81 ethanol.fuel.percentage
  82 accelerator.pedal.position
  83 hybrid.battery-pack.remaining.life
  84 engine.oil.temperature
  85 engine.torque
  86 ```
  87
  88 > **NOTE** It's recommended that you follow this naming convention to named your CAN signals.
  89 >
  90 > There is only character `*` that is forbidden in names because it's used as wildcard for subscription and unsubscrition.
  91 >
  92 > This described in the below chapter.
  93
  94 ### Generating JSON from Vector CANoe Database
  95
  96 > **CAUTION** This chapter has not been tested since we haven't necessary automotive tools for that.
  97
  98 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:
  99
 100 - CAN messages.
 101 - Name of CAN signals within messages and their generic_name.
 102 - Optionnaly name of diagnostic messages and their name.
 103
 104 To install the OpenXC utilities and runs `xml_to_json.py` script:
 105
 106 ```bash
 107 $ sudo pip install openxc
 108 $ cd /usr/local/lib/python2.7/dist-packages/openxc/generator
 109 ```
 110
 111 Assuming the data exported from Vector is in `signals.xml` and your minimal mapping file is `mapping.json`, run the script:
 112
 113 ```bash
 114 $ python -m openxc.utils ./xml_to_json.py signals.xml mapping.json signals.json
 115 ```
 116
 117 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`.
 118
 119 The resulting file together with `mapping.json` will work as input to the code generation script.
 120
 121 ### Generate your config file
 122
 123 To generate your config file you just have to run the generator using the `-m` option to specify your JSON file.
 124
 125 ```bash
 126 $ ./can-config-generator -m ../tests/basic.json -o configuration-generated.cpp
 127 ```
 128
 129 If you omit the `-o` option, then code is generated on the stdout.
 130 You also can specify a header and a footer file.
 131 These files must be valid C++ fragment as long as they will be inserted as is.
 132 Use the `-h` option to display help.
 133
 134 > **CAUTION:** Each `diagnostic_message` must define the same `bus` as the binding will use only one bus.
 135
 136 ### Supported OpenXC items
 137
 138 About now, compliance with OpenXC reference is in progress, can-config-generator and CAN\_signaling will implement them soon.
 139 `initializers`, `loopers`, `commands` and `handlers` nodes are ignored for now.
 140
 141 This generator will follow OpenXC support status of the low level CAN signaling binding.
 142
 143 > **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.
 144
 145 ## Compile and install the binding
 146 Clone the binding repository, copy the generated file and updated the git submodules.
 147
 148 Execute the following commands from this repository:
 149
 150 ```bash
 151 $ cd $WD
 152 $ git clone https://github.com/iotbzh/CAN_signaling
 153 $ cd CAN_signaling
 154 $ git submodule init
 155 $ git submodule update
 156 $ cp $WD/can-config-generator/build/configuration-generated.cpp src/
 157 ```
 158
 159 With an AGL SDK environment correctly configured and **sourced**, I suggest you to set the TARGET variable in the root CMakeLists.txt file if you have an AGL target already running in your network.
 160
 161 Then you can directly build and install the binding and source directory on your target system.
 162
 163 Execute these commands to get your binding compile:
 164
 165 ```bash
 166 $ mkdir -p build
 167 $ cd build
 168 $ cmake ..
 169 $ make
 170 ```
 171
 172 And if you have set TARGET variable, you can install it on your AGL system:
 173
 174 ```bash
 175 $ make install
 176 [ 16%] Built target bitfield
 177 [ 27%] Built target isotp
 178 [ 40%] Built target openxc
 179 [ 48%] Built target uds
 180 [ 97%] Built target low-can-binding
 181 [100%] Built target widget
 182 Install the project...
 183 -- Install configuration: ""
 184 true
 185 { "added": "low-can-binding@0.1" }
 186 ```
 187
 188 It's possible that you'll see the following message :
 189
 190 ```bash
 191 Error org.freedesktop.DBus.Error.Failed: "system error"
 192 ```
 193
 194 It's because installation remove the binding before installing it.
 195
 196 If it is the first time that you make the installation then you'll have this message in place of _**true**_.
 197
 198 To install it manually, you need to copy the _low-can-binding.wgt_ file on your target, then from it execute the following commands :
 199
 200 On your host, to copy over the network :
 201
 202 ```bash
 203 $ scp low-can-binding.wgt root@<target_IP>:~
 204 ```
 205
 206 On the target, assuming _**wgt**_ file is in the root home directory :
 207
 208 ```bash
 209 ~# afm-util install low-can-binding.wgt
 210 { "added": "low-can-binding@0.1" }
 211 ```