Skip to content

Vehicle communication

One of the key features of openOBD is to enable remote communication with vehicles. This functionality allows for automated sending and receiving of messages to and from an ECU. Support is currently provided for streamlined ISO-TP communication, as well as directly sending low-level CAN frames. Detailed information about these protocols is provided further down this page. For examples in which vehicle communication is applied, see the vehicle communication examples page.

Bus configuration

Before vehicle communication can be established, the bus configuration must be set. This configuration represents the CAN bus on which communication will take place. Buses can be configured by using the methods provided by the session service, namely the configureBus and configureBuses methods to configure either a single or multiple buses respectively.

These methods require a BusConfiguration message for each bus that should be configured. A BusConfiguration message holds the following information:

  • A representative name for the bus, saved as a string under the bus_name field.
  • A bus definition, specifying the type of bus that should be configured. Currently, only the CanBus object is supported, which should be provided under the can_bus field.

Note

It is not possible to have multiple bus configurations using the same pins. However, you can overwrite an existing bus configuration by configuring a new bus with the same pins.

CAN bus

When communication on a CAN bus is desired, the BusConfiguration message should be supplied with a CanBus object. Below is an overview of the fields a CanBus message contains.

Field Description
pin_plus The CAN high pin of the bus.
pin_min The CAN low pin of the bus.
can_protocol A CanProtocol enum specifying which protocol to use during communication.
can_bit_rate A CanBitRate enum specifying the bit rate of the bus.
transceiver An optional TransceiverSpeed enum specifying the speed of bus communication (either high or low). Defaults to high speed. Generally, high speed is used for bit rates exceeding 50 kbit/s, while low speed is used for bit rates below 50 kbit/s. A bit rate of exactly 50 kbit/s commonly uses low speed, but this may depend on the vehicle.

The can_protocol field can be set to either CAN_PROTOCOL_FRAMES or CAN_PROTOCOL_ISOTP.

  • CAN_PROTOCOL_FRAMES: Communication takes place by sending low-level CAN frames. Messages are transmitted to and from the ECU without any alterations, and must be in the format expected by the ECU. For example, if a message payload exceeds 7 bytes, it cannot fit within a single CAN frame and must be segmented into multiple frames. This necessitates the use of flow control frames to manage multi-frame transmission.
  • CAN_PROTOCOL_ISOTP: This protocol simplifies ISO-TP communication by abstracting the complexity of low-level CAN frames. It enables the sending and receiving of payloads as single messages, regardless of their length, by automatically handling multi-frame segmentation and reassembly. It also handles payload length specification as well as extended CAN ID addressing.

CAN communication

Once the buses have been configured, streams can be started to communicate with the ECUs on these buses. The can service provides several methods for ECU communication on a CAN bus. The appropriate method to use depends on the protocol that has been selected during bus configuration.

ISO-TP stream

If CAN_PROTOCOL_ISOTP has been selected for the configured bus, the openIsotpStream method can be used to send and receive messages to ECUs. This method opens a bidirectional stream with IsotpMessage as both requests and responses. An IsotpMessage holds the following information:

  • payload: The payload of the message as a string, without any frame formatting.
  • channel: An IsotpChannel representing the ECU that is the sender or recipient of the message.

An IsotpChannel contains all the information necessary to send the payload to the correct ECU. This information is shown in the table below.

Field Description
bus_name A string specifying the bus on which the ECU is located. This name corresponds to the name set in the BusConfiguration.
request_id & response_id Integers specifying on which CAN IDs the ECU receives and sends messages, respectively (e.g. 0x7E0 and 0x7E8). If only sending or receiving messages is desired, the unused identifier can be set to any value.
extended_request_address & extended_response_address Optional integers specifying the additional byte at the start of each CAN frame in the case of the ECU using extended CAN addressing.
padding An optional boolean indicating whether CAN frames should be padded with bytes to fill the 8-byte CAN frames. Defaults to false.

CAN frame stream

If CAN_PROTOCOL_FRAMES has been selected for the configured bus, the openRawStream method can be used to send and receive messages to ECUs. This method opens a bidirectional stream with RawFrame as both requests and responses. A RawFrame holds the following information:

  • payload: An optional CAN frame to send, represented as a string.
  • channel: A RawChannel representing the ECU that is the sender or recipient of the message.

In case it is desired to only receive messages from an ECU, an initial RawFrame request is still required to specify the target ECU. The payload of the request can be omitted to prevent an actual CAN frame from being sent on the CAN bus.

A RawChannel contains all the information necessary to identify the correct ECU to send and receive messages from. This information is shown in the table below.

Field Description
bus_name A string specifying the bus on which the ECU is located. This name corresponds to the name set in the BusConfiguration.
request_id & response_id Integers specifying on which CAN IDs the ECU receives and sends messages, respectively (e.g. 0x7E0 and 0x7E8). If only sending or receiving messages is desired, the unused identifier can be omitted.