A CAN DBC parsing library for javascript/typescript
npm install dbc-canNot all the stated goals of this project are currently implemented, and as
such, we are looking for active contributors. See our Contribution section
if you are interested expanding and developing for this project.
dbc-can is freely available on NPM and can be installed directly using the command
npm install dbc-can
js
import Dbc from 'dbc-can';
// OR
const Dbc = require('dbc-can');
`
Note that if you are using Node, you may need to include:
in your parent package.json file so that the package can be imported correctly if using `import`.$3
This README only gives a glimpse into how to use this library, for a more detailed
write up, make sure to check out our documentation: readthedocs$3
The DBC file is an ASCII based translation file used to apply identifying names, scaling, offsets, and defining information, to data transmitted within a CAN frame.
Simply put, it helps decode raw CAN (Controller Area Network) frames into something that is human readable.
CAN-DBC is one of the few (if not only) fully featured DBC parsing libraries that exist for Javascript/Typescript.
With CAN-DBC, you can translate the majority of a .dbc file's content into something that is human-readable and as such,
can handle the following:
1. Message definitions
2. Signal definitions
3. Environment variables
4. Network bridges
5. CAN Network Nodes/ECUs
6. Value table definitions
7. Signal groupings
8. Comments/descriptions for all signals, nodes, environment variables, messages, and others.
9. All defined attributes (global, signals, nodes, EVs, messages, etc)
10. File version number
11. All defined 'New Symbols'
12. Auto data type detection (uint8 vs float vs double vs int16, etc)
Creating DBC files are a breeze too. This library offers multiple ways of
creating DBC files from scratch, including structured typing (method chaining).
`ts
import Dbc from 'dbc-can';const dbc = new Dbc();
dbc.version = '1.0';
dbc.description = 'DBC file for a cars tranmission message';
/ Create a new DBC file from scratch /
const transStaMsg = dbc.createMessage('TransmissionStatusMsg', 100, 8);
transStaMsg.add()
.updateDescription('Indicates the status of a cars transmission')
.updateNode('EngineECU') // Where the message is going
.addSignal('OperatingStatus', 0, 10)
.addSignal('RotationSpeed', 10, 32, {isFloat: true, signed: true, unit: 'RPM'})
.addSignal('LimpMode', 45, 2, {endian: 'Motorola', max: 3});
dbc.write();
`For an alternative approach we can:
ts
import Dbc from 'dbc-can';const dbc = new Dbc();
dbc.version = '1.0';
dbc.description = 'DBC file for a cars tranmission message';
/ Create a new DBC file from scratch /
const transStaMsg = dbc.createMessage('TransmissionStatusMsg', 100, 8);
dbc.addMessage(transStMsg);
const sig1 = dbc.createSignal('OperatingStatus', 0, 10);
const sig2 = dbc.createSignal('RotationSpeed', 10, 32, {isFloat: true, signed: true, unit: 'RPM'});
const sig3 = dbc.createSignal('LimpMode', 45, 2, {endian: 'Motorola', max: 3});
dbc.addSignal([sig1,sig2,sig3])
dbc.write();
`#### Loading DBC files
This library offers two ways main ways of loading a DBC file into human-readable content
- An Asynchronous/Non-blocking method
- A Synchronous/Blocking Method
ts
import Dbc from 'dbc-can';async function loadData(dbc, file) {
const data = await dbc.load(file)
}
const dbc = new Dbc();
const file = 'my_file.dbc'
loadData(dbc, file);
/ OR /
const data = dbc.loadSync(file);
`#### Decoding CAN Messages
DBC-CAN has the ability to decode CAN frames to its real world values.
ts
import Dbc from 'dbc-can';
import { CAN } from 'dbc-can';const dbc = new Dbc();
dbc.load('tesla_can.dbc').then(data=>{
// Can() class allows for creation of CAN frames as well as message decoding
const can = new Can(data);
const canFrame = can.createFrame(264, [40, 200, 100, 140, 23, 255, 66, 12]);
// decode takes in type Frame. Returns a bound message type
/*
name: string;
id: number;
signals: Map;
*/
let boundMsg = can.decode(canFrame);
/* Bound signals contain:
Physical value - Conditioned value that has any units applied, as well as any scaling, factors, and min/max values
if any enumerations are attached the signal, the enumeration member will automatically be returned
Value - Conditioned value that has scaling, factor, and min/max values applied
Raw Value - Raw value as extracted according to the DBC file
*/
let boundSignals = boundMsg?.signals;
console.log(boundSignals);
});
/ RETURNS /
Map(7) {
'DI_torqueDriver' => { value: 522, rawValue: 2088, physValue: '522 Nm' },
'DI_torque1Counter' => { value: 6, rawValue: 6, physValue: '6' },
'DI_torqueMotor' => { value: 750, rawValue: 3172, physValue: '750 Nm' },
'DI_soptState' => { value: 4, rawValue: 4, physValue: 'SOPT_TEST_NOT_RUN' },
'DI_motorRPM' => { value: -233, rawValue: -233, physValue: '-233 RPM' },
'DI_pedalPos' => {
value: 26.400000000000002,
rawValue: 66,
physValue: '26.400000000000002 %'
},
'DI_torque1Checksum' => { value: 12, rawValue: 12, physValue: '12' }
}
`$3
DBC-CAN allows you to export loaded or created DBC data directly from the class instancets
import Dbc from 'dbc-can';const dbc = new Dbc();
dbc.loadSync('tesla_can.dbc');
dbc.toJson();
`Returns
json
{
"version": "1.0",
"messages": [
{
"name": "CANMessage",
"id": 1234,
"dlc": 8,
"sendingNode": "Node0",
"signals": [
{
"name": "Signal0",
"multiplex": "",
"startBit": 0,
"length": 32,
"endianness": "Intel",
"signed": true,
"factor": 1,
"offset": 0,
"min": 0,
"max": 0,
"unit": "",
"receivingNodes": [
"Node1",
"Node2"
],
"description": "First signal in this message",
"valueTable": null
}
...
`
Contributing
Contributing is highly encouraged! Help is wanted to expand upon this
libraries feature set, fix bugs, general refactoring, etc.
Contributing is easy. If you see something that:
1. Needs improving
2. Has bugs
3. Needs new features
Open a new GitHub issue on this project. We can either get you set up
on a new branch within this repository, or alternatively you can create a fork
and do a pull request.
All pull requests are ran through Circle CI before we allow you to merge, and as
such, you will need to:
1. Pass all linting rules
2. Pass all unit tests
3. Ensure all typescript files are buildable
You should also write tests for all added features/bugs, etc. We use Jest, but
if you think something else will fit the bill. Use it.
What you'll be using out of the box:
1. Jest for tesing
2. TSLint for all linting
3. Prettier for file formatting and clean code
4. Typescript
Suggestions for new tooling are more than welcome.
package.json
| Name | Type |
| ------------- |:-------------:|
| test | Run all unit test suites |
| coverage | Code coverage report |
| build | Build the typescript files |
| format | Code Formatting |
| lint | Linting |
| go | Quick utility function that will build and run index.ts |
| buildparser | Builds the DBC parser class |
| test:debug | Debug jest test files |
This project uses TSPeg for its parser generator. As such, a PEG style grammar file is defined
in the parser_generator folder of this project. If you are making edits to the parsing
grammar,