DBC Canbus Support

Contents

  1. DBC Canbus Support
    1. What Is It?
    2. Yes, but what does that mean??
    3. How does it work
      1. Notes on ValueGauge usage
      2. Other gauge type such as Needle Gauge, Horizontal Bar etc.
      3. Functionality that is not supported when the datamode is dbccanbus
  2. Hardware Requirements
    1. Evaluation of DBC support
  3. Software Requirements
  4. Configuring DBC Support
    1. Ini file changes
    2. DBC Playback
    3. DBC Mappings
    4. Adding a ValueGauge to display data

What Is It?

As of version 2.00, SDC includes support for DBC files. These files describe the content of CANBus messages from a third party source in a way which can be used by software to decode the messages and extract the values.

To use DBC support you must have a license with the ‘extra’ features (CANBus) enabled. The Evaluation license can play back a pre-recorded DBC based CANBus data stream for evaluation purposes.

The following inifile settings apply to DBC support:

Yes, but what does that mean??

DBC support enables any third party device which has a DBC file describing its canbus broadcast to have its data displayed on an SDC screen. This includes the well known RusEFI engine management platform, and the Haltech platform, both of whose specifications were used during development.

Other third party devices should be similarly supported but some testing will be required as we don’t have access to every platform in the lab here. We can work with you if you’re having trouble getting something working.

Where CANBus Ids do not clash, it is possible to load DBC files for multiple devices and process the CANBus streams concurrently. For example, RusEFI can generate a Haltech broadcast in parallel with its own RusEFI specific broadcast, and both of these can be processed concurrently by loading their respective DBC files at boot.

How does it work

Broadly speaking:

  • SDC reads the DBC file during initialisation and creates attributes with names of the form <dbcnamespace>.<dbc signal name>
  • Once created, these attributes can be used on gauges just like other SDC attributes.
  • DBC attributes can be optionally mapped to SDC internal attributes. When such a mapping exists, both the SDC attribute and the DBC namespaced attribute will show the same value. This allows pagesets to stay working when the datamode is changed (within reason). If you are not migrating from a Speeduino ECU, then you will not need to use this feature.
  • DBC attributes can’t be referenced in scripts as variables (unlike some internal SDC attributes), but you can use script functions to access their values (see the DoubleVal() function).
  • DBC attributes will appear alongside the internal SDC attributes in pick lists etc in SDC tools. You can treat them more or less the same as any other attribute. However, in many cases they will have a data type of ‘double’ (floating point) rather than integer as you might expect. Therefore you may sometimes need to set the DecimalPlaces property of a ValueGauge to zero.

Once everything is configured, and SDC is connected to the CANBus, all messages received are compared against the DBC definitions that were loaded from the DBC file(s), and each message is decoded according to the definition. The individual values in the message (“signals” in DBC terms) are then stored against the attribute names that were created when the DBC file was processed.

Notes on ValueGauge usage

The ValueGauge has some additional processing when the selected attribute is a DBC attribute. Specifically, the gauge establishes sensible values for ‘divideby’ and ‘decimalplaces’, because DBC files often use scaling factors and numbers of limited range so that more values can be fitted into a given 8 byte CANBus message.

‘divideby’, ‘delta’, and ‘decimalplaces’ are defaulted when the attribute on a ValueGauge is set for the first time (either when adding it to the page, or loading it from the pageset file), but you can override them by entering new values. The only way to reset back to the defaults is to delete and re-add the gauge and set the attribute again.

Other gauge type such as Needle Gauge, Horizontal Bar etc.

The values used for other gauge types when the datasource is a DBC based canbus message are the ‘raw’ values. i.e. A DBC signal may define a divideby and a delta, and these are usually copied over to a ValueGauge, but in the case of other gauge types only the raw value is used.

This means that you must set things such as maximum values to the appropriate maximum of the raw value.

For example, in rusEFI, Battery Voltage is sourced from the attribute ‘rusefi.BattVolt’ (assuming the namespace is set to ‘rusefi’). The DBC file for rusEFI sets the divideby for this attribute to 1000, meaning that a voltage of 13.460 volts is received as 13460. If you want to create a NeedleGauge that displays up to 15v, then you need a MaxVal of 15000 rather than 15. You would then set the Attribute property to ‘rusefi.BattVolt’ and the gauge will use the raw value to determine the needle position.

To help determine the appropriate MaxVal value, you can use the ‘Describe’ button in the screen designer in SDC Tools. This will show you what the DivideBy and Delta values are that the DBC file contains. Calculate the MaxVal value by taking the highest value you expect to receive and multiplying it by the DivideBy value that the Describe command returns. You may need to account for the Delta as well, depending upon the scale of the numbers involved.

The ‘describe’ console command can also be used for the same purpose.

Functionality that is not supported when the datamode is dbccanbus

Some features within SDC rely on certain values being present in the standard attributes. This is due to it originally being developed for Speeduino. If these values are not present then some features will not work. In some scenarios it might be possible to use a dbcmapping (for example setting the speed source and mapping in RPM so that torque and horsepower calculations will work) but in some cases this will not be possible.

Hardware Requirements

To use DBC Support you need the following hardware:

  • A Raspberry Pi running SDC (or one of our pre-built products such as the Pro 7)
  • An SDC I/O hat with CANBus Support. Pre-built devices will have this but if you used your own Pi you will still need an SDC I/O hat.
  • An ECU of some sort that generates a CANBus broadcast and has a DBC definition for it. For example, the master branch rusEFI DBC file is here
  • The ECU you are using must have the relevant hardware to allow it to write CANBus messages to an actual two-wire CANbus. The hardware needed is known as a CANBus Transceiver. The SDC I/O hat has a transceiver on-board so that it can receive CANBus messages, which is one of several reasons that you need it.
  • Correct termination resistors on both ends of the bus. The SDC I/O hat has a termination resistor on board which you can enable for one end of the bus (provided it is actually on the end of the bus of course).

Evaluation of DBC support

If you just want to evaluate DBC support before buying the SDC Specific hardware, then you can use the dbcplayback datamode. See below for details.

Software Requirements

You will need:

  • An installation of SDC
  • An SDC License with CANBus support enabled (or the evaluation license for playback only).
  • SDC Tools, so that you can configure the bus settings, datamode, etc.

Configuring DBC Support

(If you haven’t configured WiFi in SDC yet, do that first)

Ini file changes

The SDC.ini file included with distributions which support DBC contains example sections for various DBC configurations. If you upgraded from an earlier version then your SDC.ini will not contain these examples. The SDC 2.00 ini file can be found here; you can use it to paste sections into your current ini file after upgrading if you need to.

To configure DBC support, you will need to remove the SD Card from the Pi so that you can copy the DBC file to it. There are already DBC files in the distribution for Haltech and rusEFI and these will already be on your SD card. You will find them in the root directory where they can be referenced directly from the ini file (as below).

  • If you need to add a DBC file for an ECU not covered by the distribution, insert the SD card into your PC and copy your DBC file to the root directory. You might want to shorten the filename to something easy to enter for when you edit the ini file
  • Re-insert the SD card into the Pi and boot it
  • Start up SDC tools
  • Connect to the device using the tools’ Connect button
  • Press the Edit INI file… button
  • Scroll down the file to the [datasource] section
  • Below the datasource section you’ll see some example [dbc<n>] sections. Uncomment one or more of these by removing the semicolons from the start of the lines, and edit them to set the dbcname= and dbcnamespace= values for your specific DBC file. Set dbcname to the name of the file you put onto the SD card. Include the full path. So if you put it in the root directory called haltech.dbc then you would set dbcfilenme=c:\haltech.dbc. For the namespace, use something short and sensible. For example if using the rusEFI DBC file, set dbcnamespace=rusefi
  • Set the datamode to datamode=dbccanbus
  • You can now reboot the device.

You may also need to configure the CANBus settings so that they match the speeds being generated by the source ECU.

After the device reboots, you can check the device log to see if any errors were reported when the DBC File was processed. If processing was successful, then you can move on to adding a valuegauge to view the data coming from the source.

DBC Playback

Included with the SDC distribution is a CANBus binary log that contains approximately 5 minutes of data recorded from a rusEFI ECU running both rusEFI broadcast and Haltech Dash mode concurrently. You can use this by setting up the following configuration:

  • datamode=dbcplayback in the [datasource] section of the ini file

  • Enable [dbc1] and [dbc2] sections in the ini file. The default values for these from the ini file in the distribution are what you need:

    [dbc1]
dbcname=c:\rusEFI_CAN_verbose.dbc
dbcnamespace=rusefi

[dbc2]
dbcname=c:\haltech.dbc
dbcnamespace=hal
  • Choose the rusefidemo.xml pageset from SDC Tools, as this references the attributes populated from the CANBus recording.

Once you have set all this up, reboot the device and the playback will begin. It will loop forever, with a delay of about 8 seconds between the end of the datalog and it returning to the beginning.

The demonstration pageset rusefidemo.xml is configured with a range of attributes that are populated from the data in the CANBus log. Some attributes on some pages are populated via DBC Mappings (see below) just because this pageset is based on something that was originally built for Speeduino (demo1.xml).

The data in the CANBus log with version 2.00 doesn’t change very much because the engine is running at a fixed 4900rpm (it may flicker between 4899-4901rpm) and the MAP sensor and all other sensors were left unconnected. i.e. it was just running on a test bench when the recording was taken.

DBC Mappings

The ini file section [dbcmappings] enables you to configure mappings between the namespaced DBC attributes and the internal SDC attributes. Some mappings are present by default for the rusEFI platform but if you are using something else then you will need to either delete them or adjust them. For further details, see the DBC Mappings Section help

Mappings are really only needed if either:

  • You are migrating from Speeduino to something DBC based and want to try and use your existing pagesets without updating all of the attributes on all of the gauges,

or

  • You want to try and get something in SDC that was previously Speeduino specific working (such as the gear calculations for example, which require speed data). There aren’t many such scenarios.

Example:

[dbcmapping]
;maps a DBC entry to an SDC attribute
;<sdcattribute>=<dbcname>
speedmph=rusefi.vehiclespeed
o2=rusefi.afr
rpm=rusefi.rpm
map=rusefi.map
tps=rusefi.tps1
clt=rusefi.coolanttemp
batteryv=rusefi.battvolt

As you can see in this example, the DBC file supplied was a rusEFI DBC file, and the setting dbcnamespace=rusefi is configured. Note that the mapping is not case sensitive (e.g. the coolant temperature in the rusEFI DBC file is actually CoolantTemp)

Adding a ValueGauge to display data

  • Add a ValueGauge and position it on a page in the normal way.
  • If you have working DBC mappings, you may be able to use an internal SDC name such as rpm as the Attribute property for the gauge.
  • If you don’t have DBC mappings or the attribute you want isn’t mapped, then open the select attribute form using the ellipsis on the Attribute property, and enter the namespace you specified earlier. This will show all attributes that relate to the DBC file.
  • Select one and ensure the value is saved into the property.

Assuming data is flowing and being interpreted correctly, the value for the attribute should display. If nothing happens, check the device log.