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 configureBus method provided by the config service.

This method requires a BusConfiguration message for each bus that needs to 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 the existing bus configurations by configuring new buses.

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).
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.

Note

If the intention is to only send messages without receiving any, the response_id can be set to the same value as the request_id. For example, to broadcast messages to CAN ID 0x7DF, both the request_id and response_id can be set to 0x7DF.

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.

Note

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.