MessageDoIP

Summary

Represents a DO/IP message object.

Methods
Properties
Events

Structure

class MessageDoIP
capture(filter: Filter = None) IMessageDiagBasic

Matches any message with the same protocol.

Parameters

filter (Filter) – Filter to use to narrow down packets to capture

Returns

Listens to the bus until a message is received and returns this first message

Return type

IMessageDiagBasic

capture(timeout: int32, filter: Filter = None) IMessageDiagBasic

Waits for the first message having the same protocol that the sent message without verify the IP address and the port between send and respond message and return it. A timeout is specified to guarantee that the script can continue if no message is captured in a certain time interval.

Parameters
  • timeout (int32) – Max time in milliseconds to wait for the response.

  • filter (Filter) – Filter to use to narrow down packets to capture

Returns

First message captured from the bus or None in case no message is received.

Return type

IMessageDiagBasic

capture_list(timeout: int32, filter: Filter = None) IReadOnlyList[IMessageDiagBasic]

Waits for any response having the same protocol that the sent message without verify the IP address and the port between send and respond message and return them all as a list. A timeout is specified to guarantee that the script can continue if no message is received in a certain time interval.

Parameters
  • timeout (int32) – Max time in milliseconds to wait for the response.

  • filter (Filter) – Filter to use to narrow down packets to capture

Returns

List of messages captured from the bus during a given period of time.

Return type

IReadOnlyList[IMessageDiagBasic]

close_writer()

Closes the file previously created with open_writer(file).

connect(timeout: float = 1) bool

Opens a TCP connection.

Parameters

timeout (float) – Number of seconds to wait for connection to establish before aborting.

Returns

for connect() returns True if there’s a connection.

Return type

bool

disconnect(timeout: float = 0)

Closes the TCP connection opened with connect.

Parameters

timeout (float) – Number of seconds to wait for connection to close before aborting. If timeout is 0 (default) the connection would be closed with a TCP RST instead of normal TCP FIN, this prevents the connection from remaining stuck in the TIME_WAIT state for two minutes.

get_all_bytes() Array[uint8]

Gets the content of the whole message from Ethernet layer.

Returns

Array of bytes representing the message from Ethernet layer.

Return type

Array[uint8]

get_bytes() Array[uint8]

Gets the content of the payload.

Returns

Array of bytes representing the payload of the message.

Return type

Array[uint8]

get_hex_bytes() str

Converts the payload of the message from decimal to hex and outputs it to a string of bytes.

Returns

Payload of message in hex bytes.

Return type

str

hex_view() str

Allows to visualize messages in hexadecimal format.

Returns

Hexadecimal representation of the whole message.

Return type

str

hex_view(nb_bytes_per_line: int32) str

Allows to visualize messages in hexadecimal format.

Parameters

nb_bytes_per_line (int32) – (optional) number of bytes per line.

Returns

Hexadecimal representation of the whole message.

Return type

str

is_segmented() bool

Checks if the message is segmented.

Returns

True if the message is segmented. False if not

Return type

bool

open_writer(file: str, fileFormat: FILEFORMAT or None = None)

Creates a PCAP or PCAPNG file for writing the received messages. If the file already exists, it will be overwritten (old file data will be lost). Use the store() method to record received messages into the file.

Parameters
  • file (str) – Absolute path of the file where the messages will be stored

  • fileFormat (FILEFORMAT or None) – Obsolete, you don't need to specify this argument anymore

receive() IMessageDiagBasic

Matches a response for the used message.

Returns

Listens to the bus until a message is received and returns this first message

Return type

IMessageDiagBasic

receive(timeout: int32) IMessageDiagBasic

Waits for the first response having the IP address destination equals to the IP address source of the sent message and return it. A timeout is specified to guarantee that the script can continue if no message is received in a certain time interval.

Parameters

timeout (int32) – Max time in milliseconds to wait for the response.

Returns

First message received from the bus or None in case no message is received.

Return type

IMessageDiagBasic

receive_list(timeout: int32) IReadOnlyList[IMessageDiagBasic]

Waits for any response having the IP address destination equals to the IP address source of sent message and return them all as a list. A timeout is specified to guarantee that the script can continue if no message is received in a certain time interval.

Parameters

timeout (int32) – Max time in milliseconds to wait for the response.

Returns

List of messages received from the bus during a given period of time.

Return type

IReadOnlyList[IMessageDiagBasic]

send() bool

Sends the message (the one used to call the method) through the Ethernet bus.

Returns

Returns True if the message is sent successfully. Otherwise, an exception will be thrown.

Return type

bool

send_receive(timeout: int32 = 1000) IMessageDiagBasic

Sends the message (the one used to call the method) through the Ethernet bus and waits for a possible response, i.e. a message from the target address to our own address. It is possible to specify a timeout to guarantee that the script can continue if no response is detected in a certain time interval.

Parameters

timeout (int32) – (optional) Max time in milliseconds to wait for the response. Default 1 second

Returns

First message detected from the destination address to our address. This can be the response to the message sent but it is not 100% guaranteed; additional traffic can be captured before this expected response and thus returned.

Return type

IMessageDiagBasic

send_receive_list(timeout: int32) IReadOnlyList[IMessageDiagBasic]

Sends the message through the Ethernet bus, listens for a while and returns a list with all the messages captured in that period. It is possible to specify a timeout to guarantee that the script can continue if no response is detected in a certain time interval.

Parameters

timeout (int32) – Max time in milliseconds to wait for the response.

Returns

List of messages detected from the destination address to our address. This can be the response to the message sent but it is not 100% guaranteed; additional traffic can be captured before this expected response and thus returned.

Return type

IReadOnlyList[IMessageDiagBasic]

set_all_bytes(all_packet: Array[uint8]) bool

Sets the content of the whole message from Ethernet layer, byte per byte.

Parameters

all_packet (Array[uint8]) – All packet to set.

Returns

True if the operation was successful, False otherwise.

Return type

bool

set_bytes(payload: Array[uint8])

Sets the content of the payload, byte per byte.

Parameters

payload (Array[uint8]) – Array of bytes to set.

start_capture(filter: Filter = None)

Used for online capture(capturing network traffic from an adapter). Used with callback function(on_message_received()) and stop_capture() method.

Parameters

filter (Filter) – Filter to use to narrow down packets to capture

start_capture(file: str, wait_eof: bool, filter: Filter = None)

Used for offline capture(reading packets from pcap or asc file). Used with callback function(on_message_received()) and stop_capture() method.

Parameters
  • file (str) – The trace file from where the messages will be read.

  • wait_eof (bool) – If True the function would block until all frames in the file are read. If False the function would read the frames in the background.

  • filter (Filter) – Filter to use to narrow down packets to capture

start_listener()

Starts listening for TCP clients through the receiver network adapter.

start_responding_machine()

With this function, it is possible to simulate an ECU. It captures packets and, for every received message, it calls is_request callback. If it returns True, then it calls the make_reply callback

stop_capture()

Stops capturing Ethernet messages, either directly from the bus or from a trace file (depending on the version used to start the capture).

stop_listener(timeout: float = 0)

Stops listening for TCP clients through the receiver network adapter.

Parameters

timeout (float) – Number of seconds to wait for connection to close before aborting. If timeout is 0 (default) the connection would be closed with a TCP RST instead of normal TCP FIN, this prevents the connection from remaining stuck in the TIME_WAIT state for two minutes.

stop_responding_machine()

Stops the responding machine activated with start_responding_machine.

store(file: str)

Writes the message into the trace file.

Parameters

file (str) – Path of the file where the messages will be stored.

store()

Writes the message into the trace file opened with open_writer(file).

tree_view() str

Gives the tree view of the message.

Returns

Tree view representation of the message.

Return type

str

@on_capture_start

The event is triggered when the capture of Ethernet messages is started. See start_capture .

@on_capture_stop

The event is triggered when the capture of Ethernet messages is stopped. See stop_capture .

@on_message_received(message: IMessageDiagBasic)

Event is triggered every time a message is read from the Ethernet bus or a trace file. See start_capture.

Parameters

message (IMessageDiagBasic) – The message object being handled.

capture_info

General information about the context in which the message was captured from. None if the message was not captured

Type

CaptureInfo

connected

True if the message is connected, False otherwise.

Type

bool

data_base

Takes the database object.

Type

Database

doip_ack

The positive acknowledge response code.

Type

uint8 or None

doip_nack

The negative acknowledge response code.

Type

uint8 or None

ethernet_header

Object containing all the information from the Ethernet header like the source and destination MAC addresses of the message.

Type

HeaderEthernet

frame_number

Number of the frame received, in the context of all the ethernet traffic captured.

Type

int64

inverse_protocol_version

The inverse protocol version of the message (could be None).

Type

uint8 or None

ip_header

Object containing all the information from the IP header like the source and destination IP addresses of the message.

Type

HeaderIP

ipv4_header

Object containing all the information from the IPV4 header.

Type

HeaderIPv4

ipv6_header

Object containing all the information from the IPV6 header.

Type

HeaderIPv6

iso_tp

ISO-TP configuration of the diag message. when enabled the message is sent/received respecting ISO-TP protocol standards. For better understanding on how to use this protocol, refer to ISO-TP tutorial for tutorial.

Type

IsoTp

network_protocol

Network Protocol of the message.

Type

NetworkProtocols

payload

Content, in bytes, of the payload of the message.

Type

Array[uint8]

payload_length

The payload length.

Type

uint32 or None

payload_type

The payload type.

Type

uint16

protocol_version

The protocol version.

Type

uint8

source_address

The source address of the message.

Type

uint16

target_address

The DoIP target address of the message.

Type

uint16

tcp_header

Object containing all the information from the TCP header.

Type

HeaderTCP

timestamp

Timestamp of the message.

Type

decimal

transport_header

Object containing all the information from the transport header (usually TCP or UDP) like the source and destination ports.

Type

HeaderTransport

transport_protocol

Object containing all the information from the transport protocol (usually TCP or UDP) like the source and destination ports.

Type

Protocols

udp_header

Object containing all the information from the UDP header.

Type

HeaderUDP

uds

Representation of the doip payload.

Type

Uds

vlan_tag

Object containing all VLAN info.

Type

HeaderVlan