diff --git a/README.md b/README.md index a988db2..3d3c9ee 100644 --- a/README.md +++ b/README.md @@ -19,31 +19,31 @@ 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. + ``` + 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 -``` + ``` + 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. + ``` + 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.