J1939 Driver

The J1939 driver allows to receive and extract information from the messages sent on a J1939 bus using the Wires and Asset models.

Download

The J1939 driver is available in the Official ESF Downloads page and in the Eclipse Kura Marketplace.
The driver is available for ARM v7+ and x86-64 based gateways.

Features:

  • Allows to receive messages from a J1939 bus filtering by PGN and optionally by CAN source address.

  • Supports extraction of data from the message payloads, the following data formats are supported:

    • Raw byte arrays.
    • ASCII strings.
    • Single bits as booleans.
    • Unsigned integers of various size (not necessarily a multiple of 2).
  • Allows to apply a scale factor and an offset to numeric data.

  • Supports active requests for parameter transmission, allowing to read on-demand data.

CAN interface configuration

Before using the driver it is necessary to manually configure the CAN interface.
This can be done on Linux with the following commands:

ip link set ${interface} down
ip link set ${interface} type can bitrate 250000 triple-sampling on restart-ms 100
ip link set ${interface} up

where ${interface} is the name of the CAN interface to be used (e.g. can0).
Automatic interface configuration might be added in the future.

Driver configuration

The driver configuration allows to specify:

  • The CAN interface to be used.
  • The device NAME.
  • The driver log level on the standard output.

Driver usage

The driver is designed to work in event driven mode, reads in polling mode and writes are not supported, all channels must be defined with the listen flag set to true.

🚧

The driver currently only supports using a single CAN interface. In order to enforce this, it is possible to create at most one driver instance per ESF runtime. Additional instances will not be activated.
This limitation might be removed in the future.

The following channel configuration parameters are relevant for all data formats:

  • pgn: Must be set to the PGN of the message containing the data. If multiple parameters need to be extracted from the same message, multiple channels must be defined with the same value for the pgn parameter.
  • source.address: The driver allows to optionally filter basing on source CAN address, in order to enable this functionality, the source CAN address must be specified as the source.address field. Filtering basing on PGN is always performed.
  • parameter.position: Must be set to the start offset in bits of the parameter data.
  • parameter.size: Must be set to the size in bits of the parameter data.
  • request.transmission: The driver is capable of actively request parameter transmission at regular intervals, this is useful for reading on-demand parameters that are not transmitted spontaneously. In order to enable parameter requests, request.transmission must be set to true.
  • request.transmission.interval: If request.transmission is set to true, this parameter allows to specify the interval in milliseconds between two consecutive requests for the same parameter.

#### Reading numeric values

In order to read numeric values, the following channel configuration parameters should be used:

  • value.type: INTEGER, LONG, FLOAT or DOUBLE.
  • resolution: The value of this parameter will be multiplied by the raw data. It represents a scale factor. Can be a real value.
  • offset: The value of this parameter will be added to the raw value, after multiplying by resolution. Can be a real value.

The conversion is performed as follows:

((rawData as double) * (resolution as double) + (offset as double)) as value.type

Where rawData is the value of raw data from the payload interpreted as a little-endian unsigned integer. Rounding errors might occur due to the conversion of the result from double to the value.type defined in channel configuration.

Reading byte arrays or ASCII strings

In order to extract byte arrays or ASCII strings, the following channel configuration parameters should be used:

  • value.type: STRING for ASCII strings or BYTE_ARRAY for raw byte arrays.
  • parameter.size and parameter.position: must be multiples of 8. If these two parameters define a byte range not entirely contained in the received payload, the driver will read until the payload end.
  • delimiter: Can be set to an integer value from 0 to 255. If this parameter is not empty, the driver will read until the delimiter is encountered or the end of the payload is reached. The driver will always read at most parameter.size bytes. In case of ASCII strings, the value of delimiter must be set as the byte representation of the delimiter character as as an integer, as defined by the ASCII encoding.

#### Reading boolean values

Reading boolean values involves the same parameters as reading numeric data, but value.type must be set to BOOLEAN. The driver will first interpret the raw data as a number as shown above, and then will produce false if the result is 0, and true otherwise. It is possible to read single bits by setting parameter.size to 1.

Using the Driver programmatically

In order to use the driver programmatically, the high level Driver or Asset APIs can be used.

The com.eurotech.addons.esf.j1939.core bundle also provides a lower level API for receiving j1939 frames, the documentation of this API is provided in form of Javadoc.