OVMS3/OVMS.V3/components/vehicle_dbc/docs/dbc-primer.rst

================
DBC Introduction
================

DBC is a CAN data description file format introduced by `Vector Informatik GmbH <https://www.vector.com/>`_.
DBC files are text files so can be created and edited using a simple text editor like the one built into 
the OVMS web UI.

DBC files can be used to support vehicles that don't have a dedicated native adaption yet. This is done
using the generic DBC vehicle type, which can use DBC files to translate CAN data into metrics.

This section tries to show you how to create and use a DBC specification on the OVMS. Of course 
you'll need to know how to decode your vehicle's CAN frames first. You can use the OVMS RE (reverse 
engineering) toolkit to identify which messages are on the bus and which changes correlate to 
actions and status on the car.

There's also a very good general introduction to DBC from CSS Electronics including an explanatory video:
https://www.csselectronics.com/screen/page/can-dbc-file-database-intro/language/en

DBC files only specify the passive (reading) part, they don't provide a means to define transmissions.
If you need to send frames to request certain information, you can still use the OVMS DBC engine to
decode the results (instead of doing the decoding in C++ code). So a DBC file can be used as a base
for a real vehicle module. To request OBD2 data during development, you can use the ``re obdii``
commands.


-------------
Basic Example
-------------

.. warning::
  The DBC support is usable, but considered to be an alpha release.
  The way it works may change in the future.

This example is taken from the **Twizy**, which sends some primary BMS status data at CAN ID 0x155 (341). 
Note: the Twizy module actually does not use DBC, this is just an example how you would decode this 
message if using DBC.

**Message example**: ``05 96 E7 54 6D 58 00 6F``

- Byte 0: charge current limit [A], scaled by 5, no offset: ``05`` → **25A**
- Bytes 1+2: momentary battery current [A], big endian, lower 12 bits, scaled by -0.25, offset +500: ``_6 E7`` → **58.25A**
- Bytes 4+5: SOC [%], big endian, scaled by 0.0025, no offset: ``6D 58`` → **69.98%**

These can be translated to metrics directly:

- Charge current limit: ``v.c.climit``
- Momentary battery current: ``v.b.current``
- Battery SOC: ``v.b.soc``


---------------
Create DBC File
---------------

**Copy & paste** the following into a new editor window:

.. code-block:: none

  VERSION "DBC Example 1.0"

  BS_: 500000 : 0,0

  BO_ 341 BMS_1: 8 Vector__XXX
    SG_ v_c_climit        :  7|8@0+   (5,0)         [0|35]        "A"   Vector__XXX
    SG_ v_b_current       : 11|12@0+  (-0.25,500)   [-500|1000]   "A"   Vector__XXX
    SG_ v_b_soc           : 39|16@0+  (0.0025,0)    [0|100]       "%"   Vector__XXX


**What does this mean?**

- ``BS_`` defines the bus speed (500 kbit in this example) and bit timings (unused)
- ``BO_`` defines the data object, a CAN frame of length 8 with ID 341 (0x155) ("BMS_1" is just an arbitrary name)
- ``SG_`` lines define the signals (values) embedded in the object (see below)
- ``Vector__XXX`` is just a placeholder for any sender/receiver (currently unused by the OVMS)

**Signals** are defined by their…

- Name (= metric name with ``.`` replaced by ``_``)
- Start position (bit position) and bit length (``7|8``)
- Endianness: ``0`` = big endian (most significant byte first), ``1`` = little endian (least significant byte first) (Note: the DBC format documentation is wrong on this)
- Signedness: ``+`` = unsigned, ``-`` = signed
- Scaling and offset: ``(-0.25,500)`` => real value = raw value * -0.25 + 500
- Minimum/maximum: ``[-500|1000]`` = valid real values are in the range -500 to 1000
- Unit: e.g. ``"A"`` (ignored/irrelevant, defined by the metric)

The metric to set can be given as the name of the signal. You may use the metric name directly 
on the OVMS, but to conform to the DBC standard, replace the dots by ``_``.

**Bit positions** are counted from byte 0 upwards by their significance, regardless of the endianness. 
The first message byte has bits 0…7 with bit 7 being the most significant bit of the byte. The 
second byte has bits 8…15 with bit 15 being the MSB, and so on:

.. code-block:: none

  [ 7 6 5 4 3 2 1 0 ] [ 15 14 13 12 11 10 9 8 ] [ 23 22 21 20 …
  `----- Byte 0 ----´ `------- Byte 1 --------´ `----- Byte 2 …

For big endian values, signal start bit positions are given for the most significant bit. For 
little endian values, the start position is that of the least significant bit.

.. note::
  **On endianness**: "big endian" means a byte sequence of ``0x12 0x34`` decodes into ``0x1234`` 
  (most significant byte first), "little endian" means the same byte sequence decodes into ``0x3412`` 
  (least significant byte first). "Big endian" is the natural way of writing numbers, i.e. with their 
  most significant digit coming first, "little endian" is vice versa. Endianness only applies 
  to values of multiple bytes, single byte values are always written naturally / "big endian".


------------
Use DBC File
------------

**Save** the DBC example as: ``/store/dbc/twizy1.dbc`` (the directory will be created by the editor)

**Open the shell**. To see debug logs, issue ``log level debug dbc-parser`` and ``log level debug v-dbc``.

Note: the DBC parser currently isn't graceful on errors, **a wrong DBC file may crash the module**.
So you should only enable automatic loading of DBC files on boot when you're done developing 
and testing it.

So let's first try if the **DBC engine can parse** our file. The ``dbc autoload`` command loads all 
DBC files from the ``/store/dbc`` directory:

.. code-block:: none

  OVMS# dbc autoload
  Auto-loading DBC files...
  D (238062) dbc-parser: VERSION parsed as: DBC Example 1.0
  D (238062) dbc-parser: BU_ parsed 1 nodes
  D (238062) dbc-parser: BO_ parsed message 341
  D (238072) dbc-parser: SG_ parsed signal v_c_climit
  D (238072) dbc-parser: SG_ parsed signal v_b_current
  D (238082) dbc-parser: SG_ parsed signal v_b_soc

Looks good. ``dbc list`` can tell us some statistics:

.. code-block:: none

  OVMS# dbc list
  twizy1: DBC Example 1.0: 1 message(s), 3 signal(s), 56% coverage, 1 lock(s)

The coverage tells us how much of our CAN data bits are covered by signal definitions.

Now let's **load the file into the DBC vehicle**:

.. code-block:: none

  OVMS# config set vehicle dbc.can1 twizy1
  Parameter has been set.

  OVMS# vehicle module NONE
  I (1459922) v-none: Generic NONE vehicle module

  OVMS# vehicle module DBC
  I (249022) v-dbc: Pure DBC vehicle module
  I (249022) v-dbc: Registering can bus #1 as DBC twizy1

Nice. Let's **simulate receiving our test frame** and check the decoded metrics:

.. code-block:: none

  OVMS# can can1 rx standard 155 05 96 E7 54 6D 58 00 6F
  OVMS# me li v.b.soc
  v.b.soc                                  69.98%
  OVMS# me li v.b.current
  v.b.current                              58.25A
  OVMS# me li v.c.climit
  v.c.climit                               25A

So the decoding apparently works.

**To configure DBC mode for autostart** we now just need to set the DBC vehicle mode to be 
loaded on vehicle startup, and to enable autoloading of the DBC files from ``/store/dbc``. You can 
do so either by using the user interface page Config → Autostart (check "Autoload DBC files" and 
set the vehicle type to "DBC"), or from the shell by…

.. code-block:: none

  OVMS# config set auto dbc yes
  OVMS# config set auto vehicle.type DBC

Try a reboot to see if everything works.

You can now add more objects and signals to your DBC file.


.. note::
  During development of a DBC file, you'll need to reload the file frequently. The DBC engine
  locks the currently used vehicle, so you'll need to unload the DBC vehicle (``vehicle module NONE``), 
  then reload the DBC file (``dbc autoload``), then reactivate the DBC vehicle (``vehicle module DBC``).