Diagnostic Messages

Implementation related to diagnostic messages is located in uds.message sub-package.

It is divided into the following parts:

UDS Message

UdsMessage class is meant to provide containers for new diagnostic messages. These objects can be used for complex operations such as transmission or segmentation.

Attributes:

Methods:

Note

All UdsMessage attributes are validated on each value change, therefore a user will face an exception if one tries to set an invalid (e.g. incompatible with the annotation) value to any of its attributes.

Example code:

import uds

# create example UDS Message
uds_message = uds.message.UdsMessage(payload=[0x10, 0x03],
                                     addressing_type=uds.addressing.AddressingType.PHYSICAL)

# present created message
print(uds_message)

# change payload value
uds_message.payload = (0x62, 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF)

# change addressing type attribute
uds_message.addressing_type = uds.addressing.AddressingType.FUNCTIONAL

# present updated message
print(uds_message)

# compare uds messages
uds_message == uds.message.UdsMessage(payload=[0x62, 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF],
                                      addressing_type=uds.addressing.AddressingType.FUNCTIONAL)  # True

UDS Message Record

UdsMessageRecord class is meant to provide containers for recorded information about transmitted or received diagnostic messages.

Attributes:

Methods:

Note

A user would not create objects of UdsMessageRecord class in typical situations, but one would probably use them quite often as they are returned by communication layers (e.g. uds.transport_interface) of uds package.

Warning

All UdsMessageRecord attributes are read-only (they are set only once upon an object creation) as they store historic data and history cannot be changed (can’t it, right?).

Service Identifiers

Definition of Service Identifier (SID) values.

RequestSID

Enum RequestSID contains definitions of request Service Identifiers values.

Methods:

Warning

RequestSID does not contain definition for every POSSIBLE_REQUEST_SIDS value as some Request SID values are reserved for further extension by UDS specification and others are ECU specific (defined by ECU’s manufacturer).

Note

Use add_member() to add new SID values.

Example code:

import uds

# check if a value (0xBA in the example) is a Request SID value
uds.message.RequestSID.is_request_sid(0xBA)  # True

# check if there is member defined for the value
uds.message.RequestSID.is_member(0xBA)  # False
uds.message.RequestSID.validate_member(0xBA)  # raises ValueError

# define a new Request SID value
new_member = uds.message.RequestSID.add_member("NewRequestSIDMemberName", 0xBA)

# check if the value was successfully added as a new member
uds.message.RequestSID.is_member(new_member)  # True
uds.message.RequestSID.is_member(0xBA)  # True
uds.message.RequestSID.validate_member(new_member)  # new_member
uds.message.RequestSID.validate_member(0xBA)  # new_member

ResponseSID

Enum ResponseSID contains definitions of response Service Identifiers values.

Methods:

Warning

ResponseSID does not contain definition for every POSSIBLE_RESPONSE_SIDS value as some Response SID values are reserved for further extension by UDS specification and other are ECU specific (defined by ECU’s manufacturer).

Note

Use add_member() to add new Response SID values.

Example code:

import uds

# check if a value (0xFA in the example) is a Response SID value
uds.message.ResponseSID.is_response_sid(0xFA)  # True

# check if there is member defined for the value
uds.message.ResponseSID.is_member(0xFA)  # False
uds.message.ResponseSID.validate_member(0xFA)  # raises ValueError

# define a new Response SID value
new_member = uds.message.ResponseSID.add_member("NewResponseSIDMemberName", 0xFA)

# check if the value was successfully added as a new member
uds.message.ResponseSID.is_member(new_member)  # True
uds.message.ResponseSID.is_member(0xFA)  # True
uds.message.ResponseSID.validate_member(new_member)  # new_member
uds.message.ResponseSID.validate_member(0xFA)  # new_member

How to define custom Service

To define SID and RSID values for a new (non-standard) service in both RequestSID and ResponseSID enums, use define_service() function.

This is the recommended way as both values would be consistently (with the same name) defined!

Example code:

import uds

# check if a values (0xBA and 0xFA in the example) are Request and Response SID values
uds.message.RequestSID.is_request_sid(0xBA)  # True
uds.message.ResponseSID.is_response_sid(0xFA)  # True
uds.message.RequestSID.is_member(0xBA)  # False
uds.message.ResponseSID.is_member(0xFA)  # False

# define custom SID and RSID members
new_sid_member, new_rsid_member = uds.message.define_service(sid=0xBA, name="CustomService")

# check if the values were successfully added as new members
uds.message.RequestSID.is_request_sid(0xBA)  # True
uds.message.ResponseSID.is_response_sid(0xFA)  # True
uds.message.RequestSID.is_member(0xBA)  # True
uds.message.ResponseSID.is_member(0xFA)  # True

Negative Response Codes

Enum NRC contains definitions of all common (defined by ISO 14229) Negative Response Codes values.

Methods:

Warning

NRC does not contain definition for every possible NRC value as some of them are reserved for further extension by UDS specification and other are ECU specific (defined by ECU’s manufacturer).

Note

Use add_member() method on NRC class to add NRC value that is specific for the system that you communicate with.

Example code:

import uds

# check if a value (0xF0 in the example) is a NRC value
uds.message.NRC.is_member(0xF0)  # False
uds.message.NRC.validate_member(0xF0)  # raises ValueError

# define a new NRC value
new_member = uds.message.NRC.add_member("NewNRCMemberName", 0xF0)

# check if the value was added as a new member
uds.message.NRC.is_member(new_member)  # True
uds.message.NRC.is_member(0xF0)  # True
uds.message.NRC.validate_member(new_member)  # new_member
uds.message.NRC.validate_member(0xF0)  # new_member