Improve mapping documentation

Adding some background info on how to decide on mapping.
Change name of file to README to make it easier to
view in github web ui

Signed-off-by: Erik Jaegervall <erik.jaegervall@se.bosch.com>

README.md

@@ -85,7 +85,7 @@ $ pip install -r requirements-dev.txt
 The CAN provider requires a mapping file as input.
 The mapping file describes mapping between VSS signals and CAN (DBC) signals.
 It shall be a JSON file with VSS syntax with metadata for dbc information.
-Please see [mapping documentation](mapping/mapping.md) for more information.
+Please see [mapping documentation](mapping/README.md) for more information.
 
 ## Configuring and Using the CAN Provider
 

mapping/mapping.md → mapping/README.md

@@ -31,6 +31,7 @@ for the DBC feeder, like in the example below.
                         "math": "(x+100)/40"
                       }
                     }
+ }
 ```
 
 Two types of mapping exists.
@@ -147,19 +148,55 @@ If transform is not specified values will be transformed as is.
 
 A Math transformation can be defined by the `math` attribute.
 It accepts [py-expression-eval](https://github.com/AxiaCore/py-expression-eval/) formulas as argument.
-The DBC feeder expects the DBC value to be represented as `x` like in the example below.
+The DBC feeder expects the DBC value to be represented as `x`.
+
+When evaluating what transformation that is needed one must study both the DBC signal and the VSS signal.
+Taking driver side mirror tilt and assuming a left hand drive vehicle the following signals are concerned.
+
+**DBC**
+
+An introduction to DBC file syntax can be found [here](https://www.csselectronics.com/pages/can-dbc-file-database-intro). The specification below shows that on CAN the tilt is represented as 0-5 Volts. The value is sent with a scaling of 0.02 and uses 8 bits, i.e. 5 Volts is transmitted as 250, but that information is not needed for the can-provider transformation as the DBC scaling/offset is performed automatically by the CAN middleware.
+
+```
+SG_ VCLEFT_mirrorTiltYPosition : 41|8@1+ (0.02,0) [0|5] "V"  Receiver
+```
+
+An introduction to DBC file syntax can be found [here](https://www.csselectronics.com/pages/can-dbc-file-database-intro).
+
+**VSS**
+
+The corresponding signal in VSS use -100 percent to +100 percent as range and int8 as datatype:
+
+```
+Tilt:
+  datatype: int8
+  unit: percent
+  min: -100
+  max: 100
+  type: actuator
+  description: Mirror tilt as a percent. 0 = Center Position. 100 = Fully Upward Position. -100 = Fully Downward Position.
+  ```
+
+With an assumptions that 5 Volts corresponds to fully upward (+100%) and 0 Volts corresponds to
+fully downward (-100%) then one could define mapping like in the example below.
 
 ```yaml
-Vehicle.OBD.EngineLoad:
-  type: sensor
-  datatype: float
-  dbc:
-    signal: RearPower266
-    interval_ms: 4000
+  Vehicle.Body.Mirrors.DriverSide.Tilt:
+  datatype: int8
+  type: actuator
+  dbc2vss:
+    signal: VCLEFT_mirrorTiltYPosition
+    interval_ms: 100
+    transform:
+      math: "floor((x*40)-100)"
+  vss2dbc:
+    signal: VCLEFT_mirrorTiltYPosition
     transform:
-      math: "floor(abs(x/5))"
+      math: "(x+100)/40"
 ```
 
+I.e. 5 Volts corresponds to `(5*40)-100` = 100% and -50% corresponds to `(-50+100)/40` = 1.25 Volts.
+
 Transformation may fail. Typical reasons may include that the DBC value is not numerical,
 or that the transformation fails on certain values like division by zero.
 If transformation fails the signal will be ignored.
@@ -239,7 +276,6 @@ There are some minor changes in what constructs that are possible to specify in
 * It was previously theoretically possible to have a mapping multiple DBC signals to the same VSS signal.
   That is no longer possible as each VSS signal must appear at most once in the new format.
 
-
 ### Math Migration
 
 Migrating Math-mapping is straightforward as shown in this example: