From 6da0cd07ca214d30417b3751da11ab9138a3da0e Mon Sep 17 00:00:00 2001 From: Riccardo Date: Fri, 4 Aug 2017 18:42:08 -0700 Subject: [PATCH] First draft of a README file with good practices --- README.md | 42 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c63454d..7278559 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,45 @@ opendbc The project to democratize access to the decoder ring of your car. -Integrated with [cabana](https://community.comma.ai/cabana/) - -Use [panda](https://github.com/commaai/panda) to connect your car to a computer +### DBC file basics +A DBC file encodes, in a humanly readable way, the information needed to understand a vehicle's CAN bus traffic. A vehicle might have multiple CAN buses and every CAN bus is represented by its own dbc file. +Wondering what's the DBC file format? [Here](http://www.socialledge.com/sjsu/index.php?title=DBC_Format) a good overview. + +### How to start reverse engineering cars + +[opendbc](https://github.com/commaai/opendbc) is integrated with [cabana](https://community.comma.ai/cabana/). + +Use [panda](https://github.com/commaai/panda) to connect your car to a computer. + +### Good practices for contributing to opendbc + +- Comments: the best way to store comments is to add them directly to the DBC files. For example: +``` +CM_ SG_ 490 LONG_ACCEL "wheel speed derivative, noisy and zero snapping";``` +is a comment that refers to signal `LONG_ACCEL` in message `490`. Using comments is highly recommended, especially for doubts and uncertainties. [cabana](https://community.comma.ai/cabana/) can easily display/add/edit comments to signals and messages. + +- Units: when applicable, it's recommended to convert signals into physical units, by using a proper signal factor. Using a SI unit is preferred, unless a non-SI unit rounds the signal factor much better. +For example: +``` +SG_ VEHICLE_SPEED : 7|15@0+ (0.00278,0) [0|70] "m/s" PCM +``` +is better than: +``` +SG_ VEHICLE_SPEED : 7|15@0+ (0.00620,0) [0|70] "mph" PCM``` +However, the cleanest option is really: +``` +SG_ VEHICLE_SPEED : 7|15@0+ (0.01,0) [0|70] "kph" PCM +``` + +- Signal's size: always use the smallest amount of bits possible. For example, let's say I'm reverse engineering the gas pedal position and I've determined that it's in a 3 bytes message. For 0% pedal position I read a message value of `0x000000`, while for 100% of pedal position I read `0x640000`: clearly, the gas pedal position is within the first byte of the message and I might be tempted to define the signal `GAS_POS` as: +``` +SG_ GAS_POS : 7|8@0+ (1,0) [0|100] "%" PCM +``` +However, I can't be sure that the very first bit of the message is referred to the pedal position: I haven't seen it changing! Therefore, a safer way of defining the signal is: +``` +SG_ GAS_POS : 6|7@0+ (1,0) [0|100] "%" PCM +``` +which leaves the first bit unallocated. This prevents from very erroneous reading of the gas pedal position, in case the first bit is indeed used for something else.