Skip to content

Latest commit

 

History

History
194 lines (156 loc) · 8.84 KB

README.md

File metadata and controls

194 lines (156 loc) · 8.84 KB
Raw

DbcParser

Continuous Integration GitHub

Probably the first .NET DBC file parser. Includes packing and unpacking functionality for sending and receiving CAN signals.

Below is a quick preview of the extracted data using a Tesla dbc file taken from commaai/opendbc project:

Preview


Important

DbcParser currently relies on well formatted dbc files as input. Well formatted means that tags are non splitted on several lines or cumulated into a single line. The only multiline support is for comments. This may change in future, but at the moment this is a requirement. As an example of unsupported stuff:

BO_ 1160 DAS_steeringControl: 4 NEO
 SG_ DAS_steeringControlType : 23|2@0+ 
 (1,0) [0|0] ""  EPAS

VAL_ 1160 DAS_steeringControlType 1 "ANGLE_CONTROL" 3 
"DISABLED" 0 "NONE" 2 "RESERVED" ;

Quickstart

Install the library via Nuget Packages and add at the top of your file:

using DbcParserLib;
using DbcParserLib.Model;

Parsing

Then to parse a dbc file use the static class Parser, using one oth the parsing flavours:

Dbc dbc = Parser.ParseFromPath("C:\\your_dbc_file.dbc");
Dbc dbc = Parser.ParseFromStream(File.OpenRead("C:\\your_dbc_file.dbc")); // Or a stream from network
Dbc dbc = Parser.Parse("a dbc as string");

Handling Dbc object

The Dbc object contains two collections, Messages and Nodes, both are IEnumerable<T> so can be accessed, iterated and queried using standard LINQ.

As an example, take all messages with id > 100 and more than 2 signals:

var filteredSelection = dbc
			.Messages
			.Where(m => m.ID > 100 && m.Signals.Count > 2)
			.ToArray();

Parsing errors management

From v1.4.0 parsing errors management has been introduced to inform users about syntax errors occurred during parsing procedure. The IParseFailureObserver interface provides all methods to handle syntax errors, like:

  • Generic syntax error (eg. ;, ', , missing)
  • Duplicated object definition (eg. messages with same ID; nodes, signals, custom properties with same name etc..)
  • Object definition missing (eg. custom property is assigned before its declaration)
  • Value consistency (eg. custom property value is out of bound with respect to min and max values defined in the property)

The library comes with two different implementations:

  1. SilentFailureObserver: the default one. It silently swallow errors when parsing
  2. SimpleFailureObserver: simple observer that logs any error. SimpleFailureObserver errors list:
    • Unknown sintax: there is no corresponding TAG1 sintax
    • [TAG] Syntax error: syntax error for a specific TAG
    • Duplicated object2: the parser found (and ignores) a dulicated object
    • Object Not found: an object is declared or referenced before its definition
    • Property value out of bound: the value assigned to a property is lower/greater with respect to the minimum/maximum value declared in the property definition
    • Property value out of index: the declared index is an unacceptable value (for properties that support access to the value via index, e.g. enum value)

Errors list can be retrieve through GetErrorList() method, like in the example below

// Comment this two lines to remove errors parsing management (errors will be silent)
// You can provide your own IParseFailureObserver implementation to customize errors parsing management
var failureObserver = new SimpleFailureObserver();
Parser.SetParsingFailuresObserver(failureObserver);

var dbc = Parser.ParseFromPath(filePath);
var errors = failureObserver.GetErrorList();

The user is free to create its own implementation to customize error management.

1TAG: BA_, BA_DEF_, BA_DEF_DEF_, BO_, BU_, CM_, EV_, ENVVAR_DATA_, SIG_VALTYPE_ SG_, VAL_, VAL_TABLE_
2Object: Node, Message, Signal, Property, Environment variable, Value table


Packing/Unpacking signals

Simple scenario

To pack and unpack signals you can use static class Packer Example for packing/unpacking a signal: 14 bits, Min: -61.92, Max: 101.91

Signal sig = new Signal
{
  sig.Length = 14,
  sig.StartBit = 2,
  sig.IsSigned = 1,
  sig.ByteOrder = 1, // 0 = Big Endian (Motorola), 1 = Little Endian (Intel)
  sig.Factor = 0.01,
  sig.Offset = 20
};

// This packs the signal for sending
ulong TxMsg = Packer.TxSignalPack(-34.3, sig);

// This unpacks a received signal and calculates the corresponding engineering value
double val = Packer.RxSignalUnpack(TxMsg, sig);

Multiple signals can be packed before CAN transmission using:

ulong TxMsg = 0;
TxMsg |= Packer.TxSignalPack(value1, sig1);
TxMsg |= Packer.TxSignalPack(value2, sig2);
TxMsg |= Packer.TxSignalPack(value3, sig3);
// ...
// Send TxMsg on CAN

The user needs to make sure that the signals do not overlap with each other by properly specifying the Length and StartBit.

Multiplexing

A message can contain multiplexed data, i.e. layout can change depending on a multiplexor value. The Packer class is unaware of multiplexing, so it's up to the user to check that the given message actually contains the signal. As an example, consider the following dbc lines:

BO_ 568 UI_driverAssistRoadSign: 8 GTW
 SG_ UI_roadSign M : 0|8@1+ (1,0) [0|0] ""  DAS
 SG_ UI_dummyData m0 : 8|1@1+ (1,0) [0|0] "" Vector__XXX
 SG_ UI_stopSignStopLineDist m1 : 8|10@1+ (0.25,-8) [-8|247.5] "m" Vector__XXX

Signal UI_dummyData will only be available when UI_roadSign value is 0 while UI_stopSignStopLineDist will only be available when UI_roadSign value is 1. You can access multiplexing information calling

var multiplexingInfo = signal.MultiplexingInfo();
if(multiplexingInfo.Role == MultiplexingRole.Multiplexor)
{
	// This is a multiplexor!
}
else if(multiplexingInfo.Role == MultiplexingRole.Multiplexed)
{
	Console.WriteLine($"This signal is multiplexed and will be available when multiplexor value is {multiplexingInfo.Group}");
}

You can also check is a message does contain multiplexed signals by calling the extension method

if(message.IsMultiplexed())
{
	// ...
}

Obsolete stuff

Below you can find a list of obsolete stuff that are going to be removed in the future releases.

Class Property/Method Obsolete Removed Replaced by Comment
Signal IsSigned v1.3.0 v1.5.0 ValueType Byte property replaced by DbcValueType property which provides
more informations about signal type
Signal ValueTable v1.3.0 v1.5.0 ValueTableMap String property replaced by a IDictionary<int,string> property
Signal ToPairs() v1.3.0 v1.4.2 - Extension method used to convert ValueTable into ValueTableMap
Message CycleTime v1.4.2 1.6.0 bool CycleTime(out int cycleTime) CycleTime is no more a message property (replaced by an extension method)

Useful references

Contributions

Contributions are appreciated! Feel free to create pull requests to improve this library.

Support

This project is supported by JetBrains for Open Source development

JetBrains Logo (Main) logo