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