Skip to content

CANbus Device Service Component

The CANbus Device Service component integrates the CANbus protocol with Edge Xrt using SocketCAN and supports the following features:

  • Read a single RAW CANbus frame as a String - CAN ID : DATA LEN : DATA BYTES
  • Read a single J1939 CANbus frame as a String - SOURCE ADDRESS : PGN : DATA BYTES
  • Continuously read CANbus frames from a network and process them into Device Resources
  • Support for ethernet connection using the USR-CANET200 CAN to Ethernet Adaptor via TCP

For information on the J1939 standard see SAE J1939 for the collection of standards.

CANbus Device Service Configuration

For information on setting up a CAN network using SocketCAN see SocketCAN.

Note

The core components required for running CANbus (and all other device services) are contained in Device Service Component Configuration. Please refer to this page to ensure the appropriate core components are assigned before continuing.

CANbus Configuration File Example

An example for the CANbus configuration file is shown below: 

{
  "Library": "libxrt-canbus-device-service.so",
  "Factory": "xrt_canbus_device_service_factory",
  "Name":"canbus",
  "TelemetryTopic":"xrt/devices/canbus/telemetry",
  "RequestTopic": "xrt/devices/canbus/request",
  "ReplyTopic": "xrt/devices/canbus/reply",
  "AutoRegister": true,
  "PublishRegisteredDevices": true,
  "PublishAttributes": true,
  "ProfileDir":"./deployment/profiles",
  "StateDir":"./deployment/state",
  "Scheduler":"sched",
  "Logger":"logger",
  "ThreadPool":"pool",
  "Bus":"bus",
}

CANbus Device Profile

Details on general profile usage can be found on the Device Profiles page.

The following sections will cover how device resources are used in CANbus.

Attributes

Attributes and properties in a CANbus device resource are used to detail how data should be extracted from the CANbus message. Currently if a Device file has Standard as J1939 then attributes are required to be used for parsing data into resources. Attributes should also be assigned for resources where continuous reading and processing is being used. Note that currently in 2.1.10 multiplexing is not supported for resources. Below are the available attributes:

Attribute Description Valid Values Required
muxNum The multiplexor number used for correctly decoding data. Mandatory if muxSignal is present. Currently unsupported UInt8 No
muxSignal Indicates that this CAN frame describes the multiplexing numbering for the CAN message. Currently unsupported Bool No
bitStart Indicates the start offset for the data in bits UInt64 Yes
bitLen The length of bits to be read UInt8 Yes
littleEndian Use to indicate that the data bytes should be interpreted in a little endian format For example the bytes 0xAABBCC should be treated as 0xCCBBAA before data is read. Default is Big Endian Bool : True for little endian, false or absent for big endian No
receiverName Name of the Receiver String No

Below are the available properties. These should be used during continuous read and processing:

Property Description Valid Values Required
scale State the scaling for decoding Numeric value : Integer and Float supported Yes
offset Defines the offset for decoding Numeric value : Integer and Float Supported Yes
minVal The minimum value Numeric value : Integer and Float supported No
maxVal The maximum value Numeric value : Integer and Float supported No
unit The units for the resource String No

Data Types

The table below details the Data Types that are supported for the different features of CANbus:

Feature Data Type
Raw CANbus Reading String
J1939 CANbus Reading String
Continuous reading and processing
  • Uint 8/16/32/64
  • Int 8/16/32/64
  • Float 32/64
  • Bool

Example Device Resources

Below are examples for Device resources used for Raw CANbus reading, J1939 CANbus reading and continuous reading and processing:

RAW CANbus Resource

Resource used for reading raw CANbus frames require no attributes or properties but must be set to String data type. These resources are for use with Get requests not with continuous reading and processing. An example resource is shown below:

"deviceResources": [
   {
      "description": "Read from CAN network RAW CANbus frames",
      "attributes": {},
      "name": "Raw-CAN", 
      "properties": {
        "readWrite": "R",
        "valueType": "String"
      }
    }
  ]

J1939 CANbus Resource

Resource used for reading CANbus frames in the J1939 format require attributes and properties to be set. For use with Get requests the Data Type should be String. For Get requests the entire frame is returned in the format Source Address:PGN:Data Bytes. When using continuous reading and processing to decode CANbus messages based on resource attributes and properties see the Data Type table for valid Data Types.

Below is an example for a J1939 resource for use with Get requests:

"deviceResources": [
   {
      "description": "Read from CAN network J1939 CANbus frames",
      "attributes": {
        "bitStart": 0,
        "bitLen": 2
      },
      "name": "J1939-CAN-String", 
      "properties": {
        "readWrite": "R",
        "valueType": "String"
      }
    }
  ]

Below is an example for use with continuous reading and processing:

"deviceResources": [
    {
      "description": "Signal corresponding to a Message - Engine_Coolant_Temperature",
      "attributes": {
        "bitStart": 0,
        "bitLen": 8,
        "littleEndian": true
      },
      "name": "Engine_Coolant_Temperature", 
      "properties": {
        "readWrite": "R",
        "valueType": "Int64",
        "minVal": -40,
        "maxVal": 210,
        "scale": 1,
        "offset": -40
        "unit": "C"
      }
    }
  ]

Device Commands

See the Device Profiles page for details on how to define device commands for grouping device resources for fewer requests.

CANbus Device Provisioning

The following section will explain how to configure a device for the CANbus Device Service.

Note

For information on dynamic device additions, removals and updates please see the MQTT API Guide.

CANbus Device Protocol Properties

Protocol Property Description Valid Values Required
Network The network name or IP address (when using ethernet) to use for the device connection String Yes
Standard The CAN standard to use for this device. Default is RAW
  • RAW
  • J1939
 No
ID The CAN ID for this device. 11 bit or 29 bit extended are valid UInt64 Yes (when Standard is J1939)
DataSize States how many data bytes are in a message UInt16 Yes (when Standard is J1939)
Sender Name of the ECU sending the message. Is optionally included in DBC files String No
NetType The network type to use for this device. Default is CAN
  • CAN
  • Ethernet
Yes (when using ethernet)
CommType The communication type to be used
  • TCP
  • UDP (Currently unsupported)
Yes (when using ethernet)
Port Port to connect to Uint16 Yes (when using ethernet)

Provisioning

An example of a CANbus device using a CAN network is provided below:

{
  "name": "canbus-device",
      "profileName": "canbus-profile",
      "protocols": {
        "CANbus": {
          "Network": "can0",
          "Standard": "J1939",
          "ID": 2365517566,
          "DataSize": 8,
          "Sender": "Motor"
        }
      }
}

An example of a CANbus device using an Ethernet network is shown below:

{
  "name": "canbus-device",
  "profileName": "canbus-profile",
  "protocols": {
    "CANbus": {
      "Standard": "J1939",
      "ID": 2364539902,
      "DataSize": 8,
      "NetType": "Ethernet",
      "Port": 20001,
      "CommType": "TCP",
      "Network": "192.168.50.7"
    }
  }
}

CANbus Device Interaction

For information on how to dynamically execute reads, writes, setting up schedules and more, please refer to the MQTT API Guide.

For interactive examples of the CANbus Device Service refer to CANbus Xrt Example.

Run the CANbus Device Service

Find details on how to run the CANbus Device Service on the Run Device Services page.

Continuous Read and Processing

One of the features of the CANbus device service is to allow continually reading data from a CAN network and process this data into resources belonging to a device. This allows data to be processed and published via MQTT when it comes into the device service without requiring GET requests to retrieve the data.

To use this feature a schedule must be added to the service with the option parameter of the schedule containing Cyclic set to true. When this is done the interval will be ignored and the data will be published as and when it comes into the device service.

The on_change feature of schedules applies to the CANbus device service. If this parameter is set then only data that has changed will be published. If it is absent or set to false then all data will be published.