J1979 Driver

The J1939 driver allows to read data from J1979 ECUs using the device CAN interfaces.

Download

TBD

Features:

Allows to send requests to the following J1979 services:
- Service 1
- Service 3
- Service 4
- Service 9
Supports automatic probing of supported items for Service 1 and 9.
Supports trouble code decoding
Supports extraction of data from the message payloads, the following data formats are supported:
- Raw byte arrays.
- ASCII strings.
- Single bits as booleans.
- Signed and Unsigned integers of various size (not necessarily a multiple of 2).
Allows to apply a scale factor and an offset to numeric data.
Supports emitting channel data in JSON format:

Allows to include sender source address.
Allows to include responses from multiple ECUs.

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 ${bitrate} 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), and ${bitrate} is the desired bitrate in bps.

Driver configuration

The driver configuration allows to specify:

The CAN interface to be used.
The maximum number of data items to include in a single request for service 1
The size of the CAN identifier to be used (11 or 29 bits).

Driver usage

The driver can be used in polling mode only. Event driven mode is not supported.

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

json: Enables Json format output. If this parameter is set, the value.type parameter must be set to STRING.
raw.type: Specifies the type of the data to be read.
service: Specifies the service for the request
item: The PID (Service 1) or Infotype (Service 9) to be read.
source.name: Allows to enable NAME based filtering. It must contain a Json object containing the NAME parts to be matched, see below for more details.
item.data.size.bytes: The size in bytes of the data returned by the remote ECU for the PID or Infotype.
parameter.position.bits: The start offset in bits of the parameter to be read data inside the data of the PID or Infotype.
parameter.size.bits: The size in bits of the parameter data. Must be less or equal than item.data.size.bytes * 8.

#### Reading numeric values

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

value.type: INTEGER, LONG, FLOAT or DOUBLE if the Json format is not used. STRING otherwise.
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

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, if the Json format is not used. STRING otherwise.
parameter.size.bits and parameter.position.bits: 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.

#### 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.bits to 1.

Probing supported items

The driver provides a dedicated channel type for probing supported PIDs for Service 1 and InfoTypes for service 9.
The dedicated channel type can be enabled by setting the following parameters:

probe.supported.items: true
json: true
service : SERVICE_1 for probing supported PIDs or SERVICE_9 for probing supported InfoTypes
value.type: STRING

Reading a channel configured in the way above will produce a Json object reporting all supported items for each responding ECU, as described in the Json format section

Reading and decoding pending DTCs

The driver provides a dedicated channel type for reading and decoding pending DTCs.
The dedicated channel type can be enabled by setting the following parameters:

json: true
service : SERVICE_3
value.type: STRING

Reading a channel configured in the way above will produce a Json object containing reporting all pending DTCs for each responding ECU, as described in the Json format section.

Json format

The driver supports emitting data using the Json format. This allows to enrich the channel value with the source address of the sender ECU and return the values coming from multiple responses from different ECUs.

If Json output is enabled, channel value will be an array of Json objects.
The array will contain an object for each response received to the request. Each object contains the following properties:

v: the channel value. The value of this property is a JSON array whose length depends on the request and on the number of data elements returned. For example:
- In case of requests for probing supported items, the array will contain one numeric element per supported item.

[
  {
    "s": 1,
    "v": [ 1, 2, 5, 6, 9, 10, 13 ]
  },
  {
    "s": 2,
    "v": [ 1, 2, 13 ]
  }
]

The example above shows the response for a probe supported items request. Two ECUs responded, ECU with source address 1 supports PIDS 1, 2, 5, 6, 9, 10, 13. ECU with source address 2 supports PIDs 1, 2, 13.

In case of requests for diagnostic trouble codes. The array will contain a string element for each trouble code returned by the ECU.

[
  {
    "s": 1,
    "v": [ "P0100", "P0200", "P0143" ]
  },
  {
    "s": 2,
    "v": [ "P0100" ]
  }
]

In the example above, ECU with source address 1 reports DTC P0100, P0200 and P0143. ECU with source address 2 reports DTC P0100.

In case of requests for numeric, string or byte array parameters, the array will contain exactly one element. The type of the element depends on the value of the raw.type field:
```
* `UNSIGNED` or `SIGNED`: `number`
```json
```
[
{
"s": 1,
"v": [ 25.6 ]
}
]
* `STRING`: 'string' json
[
{
"s": 1,
"v": [ "vehicle id" ]
}
]
* `BYTE_ARRAY`: a Json `array` of unsigned decimal numbers, describing the byte values json
[
{
"s": 1,
"v": [ [ 201, 202, 203, 204 ] ]
}
]
```