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, the CanBus, KlineBus, Terminal15Bus, and DoipBus types are supported.

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.

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. Additionally, this protocol keeps an ECU awake by automatically sending tester present messages to the ECU.

To communicate with ECUs that use K-Line, a KlineBus will need to be set up. The fields of a KlineBus message are described below.

Field Description
pin The OBD pin on which K-Line communication should take place.
kline_protocol A KlineProtocol enum specifying which protocol to use during communication.
kline_bit_rate A KlineBitRate enum specifying the bit rate of the bus.

For many K-Line ECUs, communication can be established by setting the protocol to KLINE_PROTOCOL_ISO14230_FAST and the bit rate to KLINE_BIT_RATE_10400.

If the ignition switch (terminal 15) signal is returned on a specific pin, a Terminal15Bus should be set up. The fields of a Terminal15Bus message are described below.

Field Description
pin The OBD pin on which Terminal 15 communication should take place.

Only a single terminal 15 bus can be opened.

To communicate with ECUs that use DoIP, a DoipBus will have to be configured. The fields of a DoipBus message are described below.

Field Description
doip_option A DoipOption enum which determines how DoIP communication should take place (as specified by ISO 13400).
doip_network_configuration A DoipNetworkConfiguration enum specifying which configuration to use during communication. This depends on the manufacturer of the vehicle.

It can take up to 90 seconds for a DoIP bus to be configured.

ECU communication

Once the buses have been configured, streams can be started to communicate with the ECUs on these buses. The appropriate stream to use depends on the BusConfiguration that has been set.

If CAN_PROTOCOL_ISOTP has been selected for the configured CanBus, 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.

If CAN_PROTOCOL_TP20 has been selected for the configured CanBus, the openTp20Stream method can be used to send and recieve messages to ECUs. This method opens a bidirectional stream with Tp20Message as both requests and responses. A Tp20Message holds the following information:

  • payload: The payload of the message as a string, without any frame formatting
  • channel: A Tp20Channel representing a communication channel between sender and recipient of messages.

An Tp20Channel 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.
logical_address An integer specifying a 'communication channel' on which the remote will communicate.

If CAN_PROTOCOL_FRAMES has been selected for the configured CanBus, 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.

For communication with a K-Line ECU, the kline service can be used. This service provides the openKlineStream method, which opens a bidirectional stream used for exchanging KlineMessages. A KlineMessage has the following fields:

  • payload: The payload of the message as a string.
  • channel: A KlineChannel representing the ECU that is the sender or recipient of the message.

A KlineChannel contains the information necessary to identify the correct ECU to communicate with. The fields of a KlineChannel are described 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.
ecu_id An integer specifying on which ID the ECU communicates (e.g. 0xC0).
keyword An optional Keyword message containing two key bytes used for configuring communication according to ISO 14230.

To listen to the ignition switch signal (terminal 15), the terminal15 service can be used. This service provides the openTerminal15Stream method, which opens a stream used to receive Terminal15Messages.

The stream will return a message with the initial state of the ignition switch when opening the stream. Afterwards, one message will be returned for each state change.

A Terminal15Message has the following fields:

  • state: The current state of the ignition switch. May be undefined, if the current state is not (yet) known.

The doip service can be used to communicate with an ECU using DoIP. This service provides the openDoipStream method, which opens a stream that can be used to exchange DoipMessages. A DoipMessage has the following fields:

  • payload: The payload of the message as a string.
  • channel: A DoipChannel representing the ECU that is the sender or recipient of the message.

A DoipChannel contains the information necessary to communicate with the correct ECU. The fields of a DoipChannel are described 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.
gateway_id Integer specifying the ID of the gateway through which communication should take place.
tester_id Integer specifying the ID to which the ECU should send its response.
ecu_id Integer specifying the ID of the ECU that should be communicated with.

Note

Once communication has started on a stream, it is not possible to use a different channel on that same stream. This means that a new stream must be started to communicate with a different ECU or to use a different channel configuration.