UDS¶

Configurations, enums, and result types are shared by automotive.protocols.uds and automotive.sync.protocols.uds.

Asynchronous API¶

Unified Diagnostic Services with Rust timing, parsing, and validation.

Methods accept named IntEnum members or raw integers. All byte inputs accept bytes, bytearray, and contiguous byte-oriented memoryviews; results use bytes. Each transport serializes exchanges, while separate ECU transports can run concurrently. Negative responses raise NegativeResponseError with a raw code; deadline expiry raises TimeoutError. See automotive.errors for other failures.

class automotive.protocols.uds.DTCFormatIdentifier(*values)¶

Named DTCFormatIdentifier wire values from Rust.

Members are integers and may be passed wherever a raw code is accepted. Unknown codes remain raw integers in protocol results. Iteration visits only known values; constructing this enum with an unknown value raises ValueError.

SAE_J2012_DA_DTC_FORMAT_00 = 0x00¶

ISO_14229_1_DTC_FORMAT = 0x01¶

SAE_J1939_73_DTC_FORMAT = 0x02¶

ISO_11992_4_DTC_FORMAT = 0x03¶

SAE_J2012_DA_DTC_FORMAT_04 = 0x04¶

class automotive.protocols.uds.DTCReportNumberByStatusMask(dtc_status_availability_mask: int, dtc_format_identifier: DTCFormatIdentifier | int, dtc_count: int)[source]¶

DTC count and metadata returned by ReadDTCInformation.

Variables:

dtc_status_availability_mask (int) – ECU-supported status bits.
dtc_format_identifier (automotive._enums.DTCFormatIdentifier | int) – Named DTCFormatIdentifier, or an unknown raw integer.
dtc_count (int) – Number of DTCs matching the requested status mask.

dtc_status_availability_mask: int¶

dtc_format_identifier: DTCFormatIdentifier | int¶

dtc_count: int¶

class automotive.protocols.uds.DataIdentifier(*values)¶

Named DataIdentifier wire values from Rust.

BOOT_SOFTWARE_IDENTIFICATION = 0xF180¶

APPLICATION_SOFTWARE_IDENTIFICATION = 0xF181¶

APPLICATION_DATA_IDENTIFICATION = 0xF182¶

BOOT_SOFTWARE_FINGERPRINT = 0xF183¶

APPLICATION_SOFTWARE_FINGERPRINT = 0xF184¶

APPLICATION_DATA_FINGERPRINT = 0xF185¶

ACTIVE_DIAGNOSTIC_SESSION = 0xF186¶

VEHICLE_MANUFACTURER_SPARE_PART_NUMBER = 0xF187¶

VEHICLE_MANUFACTURER_ECU_SOFTWARE_NUMBER = 0xF188¶

VEHICLE_MANUFACTURER_ECU_SOFTWAREVERSION_NUMBER = 0xF189¶

SYSTEM_SUPPLIER_IDENTIFIER = 0xF18A¶

ECUMANUFACTURING_DATE = 0xF18B¶

ECU_SERIAL_NUMBER = 0xF18C¶

SUPPORTED_FUNCTIONAL_UNITS = 0xF18D¶

VEHICLE_MANUFACTURER_KIT_ASSEMBLY_PART_NUMBER = 0xF18E¶

VIN = 0xF190¶

VEHICLE_MANUFACTURER_ECU_HARDWARE_NUMBER = 0xF191¶

SYSTEM_SUPPLIER_ECU_HARDWARE_NUMBER = 0xF192¶

SYSTEM_SUPPLIER_ECU_HARDWARE_VERSION_NUMBER = 0xF193¶

SYSTEM_SUPPLIER_ECU_SOFTWARE_NUMBER = 0xF194¶

SYSTEM_SUPPLIER_ECU_SOFTWARE_VERSION_NUMBER = 0xF195¶

EXHAUST_REGULATION_OR_TYPE_APPROVAL_NUMBER = 0xF196¶

SYSTEM_NAME_OR_ENGINE_TYPE = 0xF197¶

REPAIR_SHOP_CODEOR_TESTER_SERIAL_NUMBER = 0xF198¶

PROGRAMMING_DATE = 0xF199¶

CALIBRATION_REPAIR_SHOP_CODE_OR_CALIBRATION_EQUIPMENT_SERIAL_NUMBER = 0xF19A¶

CALIBRATION_DATE = 0xF19B¶

CALIBRATION_EQUIPMENT_SOFTWARE_NUMBER = 0xF19C¶

ECU_INSTALLATION_DATE = 0xF19D¶

ODX_FILE = 0xF19E¶

ENTITY = 0xF19F¶

class automotive.protocols.uds.NegativeResponseCode(*values)¶

Named NegativeResponseCode wire values from Rust.

GENERAL_REJECT = 0x10¶

SERVICE_NOT_SUPPORTED = 0x11¶

SUB_FUNCTION_NOT_SUPPORTED = 0x12¶

INCORRECT_MESSAGE_LENGTH_OR_INVALID_FORMAT = 0x13¶

RESPONSE_TOO_LONG = 0x14¶

BUSY_REPEAT_REQUEST = 0x21¶

CONDITIONS_NOT_CORRECT = 0x22¶

REQUEST_SEQUENCE_ERROR = 0x24¶

NO_RESPONSE_FROM_SUBNET_COMPONENT = 0x25¶

FAILURE_PREVENTS_EXECUTION_OF_REQUESTED_ACTION = 0x26¶

REQUEST_OUT_OF_RANGE = 0x31¶

SECURITY_ACCESS_DENIED = 0x33¶

INVALID_KEY = 0x35¶

EXEED_NUMBER_OF_ATTEMPTS = 0x36¶

REQUIRED_TIME_DELAY_NOT_EXPIRED = 0x37¶

UPLOAD_DOWNLOAD_NOT_ACCEPTED = 0x70¶

TRANSFER_DATA_SUSPENDED = 0x71¶

GENERAL_PROGRAMMING_FAILURE = 0x72¶

WRONG_BLOCK_SEQUENCE_COUNTER = 0x73¶

REQUEST_CORRECTLY_RECEIVED_RESPONSE_PENDING = 0x78¶

SUB_FUNCTION_NOT_SUPPORTED_IN_ACTIVE_SESSION = 0x7E¶

SERVICE_NOT_SUPPORTED_IN_ACTIVE_SESSION = 0x7F¶

class automotive.protocols.uds.ReportType(*values)¶

Named ReportType wire values from Rust.

REPORT_NUMBER_OF_DTC_BY_STATUS_MASK = 0x01¶

REPORT_DTC_BY_STATUS_MASK = 0x02¶

REPORT_DTC_SNAPSHOT_IDENTIFICATION = 0x03¶

REPORT_DTC_SNAPSHOT_RECORD_BY_DTC_NUMBER = 0x04¶

REPORT_DTC_STORED_DATA_BY_RECORD_NUMBER = 0x05¶

REPORT_DTC_EXT_DATA_RECORD_BY_DTC_NUMBER = 0x06¶

REPORT_NUMBER_OF_DTC_BY_SEVERITY_MASK_RECORD = 0x07¶

REPORT_DTC_BY_SEVERITY_MASK_RECORD = 0x08¶

REPORT_SEVERITY_INFORMATION_OF_DTC = 0x09¶

REPORT_SUPPORTED_DTC = 0x0A¶

REPORT_FIRST_TEST_FAILED_DTC = 0x0B¶

REPORT_FIRST_CONFIRMED_DTC = 0x0C¶

REPORT_MOST_RECENT_TEST_FAILED_DTC = 0x0D¶

REPORT_MOST_RECENT_CONFIRMED_DTC = 0x0E¶

REPORT_MIRROR_MEMORY_DTC_BY_STATUS_MASK = 0x0F¶

REPORT_MIRROR_MEMORY_DTC_EXT_DATA_RECORD_BY_DTC_NUMBER = 0x10¶

REPORT_NUMBER_OF_MIRROR_MEMORY_DTC_BY_STATUS_MASK = 0x11¶

REPORT_NUMBER_OF_EMISSIONS_OBDDTC_BY_STATUS_MASK = 0x12¶

REPORT_EMISSIONS_OBDDTC_BY_STATUS_MASK = 0x13¶

REPORT_DTC_FAULT_DETECTION_COUNTER = 0x14¶

REPORT_DTC_WITH_PERMANENT_STATUS = 0x15¶

REPORT_DTC_EXT_DATA_RECORD_BY_RECORD_NUMBER = 0x16¶

REPORT_USER_DEF_MEMORY_DTC_BY_STATUS_MASK = 0x17¶

REPORT_USER_DEF_MEMORY_DTC_SNAPSHOT_RECORD_BY_DTC_NUMBER = 0x18¶

REPORT_USER_DEF_MEMORY_DTC_EXT_DATA_RECORD_BY_DTC_NUMBER = 0x19¶

REPORT_WWHOBDDTC_WITH_PERMANENT_STATUS = 0x55¶

class automotive.protocols.uds.ResetType(*values)¶

Named ResetType wire values from Rust.

HARD_RESET = 0x01¶

KEY_OFF_ON_RESET = 0x02¶

SOFT_REST = 0x03¶

ENABLE_RAPID_POWER_SHUT_DOWN = 0x04¶

class automotive.protocols.uds.RoutineControlType(*values)¶

Named RoutineControlType wire values from Rust.

START = 0x01¶

STOP = 0x02¶

REQUEST_RESULTS = 0x03¶

class automotive.protocols.uds.RoutineIdentifier(*values)¶

Named RoutineIdentifier wire values from Rust.

ERASE_MEMORY = 0xFF00¶

CHECK_PROGRAMMING_DEPENDENCIES = 0xFF01¶

ERASE_MIRROR_MEMORY_DT_CS = 0xFF02¶

class automotive.protocols.uds.SecurityAccessType(*values)¶

Named SecurityAccessType wire values from Rust.

REQUEST_SEED = 0x01¶

SEND_KEY = 0x02¶

class automotive.protocols.uds.ServiceIdentifier(*values)¶

Named ServiceIdentifier wire values from Rust.

DIAGNOSTIC_SESSION_CONTROL = 0x10¶

ECU_RESET = 0x11¶

SECURITY_ACCESS = 0x27¶

COMMUNICATION_CONTROL = 0x28¶

TESTER_PRESENT = 0x3E¶

ACCESS_TIMING_PARAMETER = 0x83¶

SECURED_DATA_TRANSMISSION = 0x84¶

CONTROL_DTC_SETTING = 0x85¶

RESPONSE_ON_EVENT = 0x86¶

LINK_CONTROL = 0x87¶

READ_DATA_BY_IDENTIFIER = 0x22¶

READ_MEMORY_BY_ADDRESS = 0x23¶

READ_SCALING_DATA_BY_IDENTIFIER = 0x24¶

READ_DATA_BY_PERIODIC_IDENTIFIER = 0x2A¶

DYNAMICALLY_DEFINE_DATA_IDENTIFIER = 0x2C¶

WRITE_DATA_BY_IDENTIFIER = 0x2E¶

WRITE_MEMORY_BY_ADDRESS = 0x3D¶

CLEAR_DIAGNOSTIC_INFORMATION = 0x14¶

READ_DTC_INFORMATION = 0x19¶

INPUT_OUTPUT_CONTROL_BY_IDENTIFIER = 0x2F¶

ROUTINE_CONTROL = 0x31¶

REQUEST_DOWNLOAD = 0x34¶

REQUEST_UPLOAD = 0x35¶

TRANSFER_DATA = 0x36¶

REQUEST_TRANSFER_EXIT = 0x37¶

REQUEST_FILE_TRANSFER = 0x38¶

class automotive.protocols.uds.SessionParameterRecord(p2_server_max: float, p2_star_server_max: float)[source]¶

Server timings returned by DiagnosticSessionControl, in seconds.

Variables:

p2_server_max (float) – Initial response timing reported by the ECU.
p2_star_server_max (float) – Response-pending timing reported by the ECU.

p2_server_max: float¶

p2_star_server_max: float¶

class automotive.protocols.uds.SessionType(*values)¶

Named SessionType wire values from Rust.

DEFAULT = 0x01¶

PROGRAMMING = 0x02¶

EXTENDED_DIAGNOSTIC = 0x03¶

SAFETY_SYSTEM_DIAGNOSTIC = 0x04¶

class automotive.protocols.uds.UDSClient(transport: Transport, config: UDSConfig | None = None)[source]¶

A persistent diagnostic client retaining its transport and session timing.

Parameters:

transport – Open message transport, such as software or native J2534 ISO-TP.
config – Reusable timing/validation settings. None uses Rust defaults.

Calls on the same transport are serialized. Suppression scopes retain this client’s learned timing. Cancelling queued work prevents transmission; cancelling an active call ends the Python await but lets Rust drain the exchange under the transaction lock. Closing the transport interrupts it. Cancellation cannot undo ECU actions. Requests with unlimited NRC 0x78 responses may hold the lock indefinitely unless request_timeout is set. Idle receive expiry resumes waiting on the same stream without resending the request or extending P2/P2*. Transport transfer failures still raise errors.

Raises:

NegativeResponseError – An ECU rejects the request; code is its raw NRC.
ProtocolDeviationError – A strict validation rule fails; response is the full received PDU and deviation describes the mismatch.
TimeoutError – A transport, response, or overall deadline expires.
ValueError – Rust rejects a service argument before transmission.
ConnectionError – The underlying connection closes during an exchange.

Examples

With an open transport and ECU:

uds = UDSClient(transport, UDSConfig(request_timeout=5.0))
vin = await uds.read_data_by_identifier(DataIdentifier.VIN)

suppress_positive_responses() → Generator[Self, None, None][source]¶

Suppress positive responses within an ordinary with block.

The scope is local to the current async task, supports nesting, and restores its previous setting even after exceptions. Tasks created inside the scope inherit it through Python’s normal context propagation; already-running tasks are unchanged. No connection is opened or closed.

Negative responses still raise; NRC 0x78 requires a final response. Services without sub-functions continue to require positive responses.

Yields:: This client, optionally bindable with as uds.

Examples

With an open client and ECU:

with uds.suppress_positive_responses():
    await uds.tester_present()
await uds.tester_present()  # Requires a positive response again.

Send a custom UDS request and return positive response data.

Parameters:

sid – ServiceIdentifier or raw unsigned byte.
sub_function – Optional raw byte. Bit 7 requests suppression.
data – Optional service-specific bytes following the headers.

Returns:

Response data excluding SID and echoed sub-function, including b”” for an empty response. None means successful suppressed silence; it does not confirm ECU execution.

Rust handles NRC 0x78 and response validation. A pending response makes subsequent silence a timeout rather than successful suppression.

async diagnostic_session_control(session_type: SessionType | int) → SessionParameterRecord | None[source]¶

Select a diagnostic session (SID 0x10).

Parameters:: session_type – Named session or raw byte, including suppression flags.
Returns:: Server timing in seconds, or None for suppression/non-strict responses without a timing record. Rust adopts the record when configured.

async ecu_reset(reset_type: ResetType | int) → int | None[source]¶

Request an ECU reset (SID 0x11).

Parameters:: reset_type – Named reset or raw byte, including suppression flags.
Returns:: Optional power-down time as a raw wire integer; None when absent or when the positive response is suppressed.

Request a security seed or submit a key (SID 0x27).

Parameters:

access_type – Named access type or raw byte.
data – Optional key or manufacturer-specific request bytes.

Returns:

Seed bytes, or None for SendKey acknowledgement/suppressed silence.

Seed/key calculation remains the caller’s responsibility.

async tester_present() → None[source]¶

Send TesterPresent (SID 0x3E), awaiting the configured response window.

A suppression scope accepts initial silence but still handles negative responses and requires a final response after NRC 0x78.

async read_data_by_identifier(data_identifier: DataIdentifier | int) → bytes[source]¶

Read a DID (SID 0x22) and return its data record as bytes.

Parameters:: data_identifier – Named DID or raw unsigned 16-bit integer.

The echoed DID is checked in strict mode. No text decoding is applied.

async write_data_by_identifier(data_identifier: DataIdentifier | int, data_record: bytes | bytearray | memoryview) → None[source]¶

Write a DID (SID 0x2E) and validate its acknowledgement.

Parameters:

data_identifier – Named DID or raw unsigned 16-bit integer.
data_record – New data record; copied before asynchronous work.

async read_memory_by_address(memory_address: bytes | bytearray | memoryview, memory_size: bytes | bytearray | memoryview) → bytes[source]¶

Read memory (SID 0x23) using explicit big-endian byte fields.

Parameters:

memory_address – Big-endian address bytes; leading zeros are retained.
memory_size – Big-endian size bytes; its length determines wire width.

Returns:

Memory data bytes. Use the _alfid variant for integer arguments.

async read_memory_by_address_alfid(memory_address: int, memory_size: int, address_width: int, size_width: int) → bytes[source]¶

Read memory using integer address/size with explicit byte widths.

Parameters:

memory_address – Unsigned 64-bit memory address.
memory_size – Unsigned 64-bit byte count.
address_width – Address byte count, 1–8.
size_width – Size byte count, 1–8.

Raises:

ValueError – A width is invalid or the value does not fit it.

Write memory (SID 0x3D) using big-endian address/size byte fields.

Parameters:

memory_address – Big-endian address, retaining leading zeros.
memory_size – Big-endian byte count, retaining its explicit width.
data – Memory bytes to write; must match the requested size.

async write_memory_by_address_alfid(memory_address: int, memory_size: int, address_width: int, size_width: int, data: bytes | bytearray | memoryview) → None[source]¶

Write memory with unsigned 64-bit address/size and byte widths 1–8.

Parameters:

memory_address – Numeric memory address.
memory_size – Number of memory bytes to write.
address_width – Address field width in bytes.
size_width – Size field width in bytes.
data – Memory data, copied before asynchronous work.

Rust rejects invalid widths or values that do not fit before sending.

async read_dtc_information_number_of_dtc_by_status_mask(mask: int) → DTCReportNumberByStatusMask | None[source]¶

Return the number of DTCs matching a status mask (SID 0x19/0x01).

Parameters:: mask – Unsigned byte containing the requested status bits.
Returns:: DTC count/metadata, or None for suppressed silence. Unknown format identifiers are returned as raw integers instead of being rejected.

Start, stop, or query a routine (SID 0x31).

Parameters:

routine_control_type – Named operation or raw byte.
routine_identifier – Named routine or raw unsigned 16-bit ID.
data – Optional routine-specific request record.

Returns:

Optional result record; None when absent or suppressed. Rust handles pending responses and validates the echoed routine in strict mode.

async request_download(compression_method: int, encryption_method: int, memory_address: bytes | bytearray | memoryview, memory_size: bytes | bytearray | memoryview) → int[source]¶

Begin a client-to-ECU transfer (SID 0x34).

Parameters:

compression_method – Unshifted compression nibble, 0–15; zero is none.
encryption_method – Unshifted encryption nibble, 0–15; zero is none.
memory_address – Big-endian address bytes.
memory_size – Big-endian total byte count.

Returns:

Maximum complete TransferData request size, including SID/counter.

async request_download_alfid(compression_method: int, encryption_method: int, memory_address: int, memory_size: int, address_width: int, size_width: int) → int[source]¶

Begin a download using integer address/size and explicit byte widths.

Parameters:

compression_method – Unshifted nibble, 0–15.
encryption_method – Unshifted nibble, 0–15.
memory_address – Unsigned 64-bit address.
memory_size – Unsigned 64-bit total byte count.
address_width – Address field length, 1–8 bytes.
size_width – Size field length, 1–8 bytes.

Returns:

Maximum complete TransferData request size, including SID/counter.

async request_upload(compression_method: int, encryption_method: int, memory_address: bytes | bytearray | memoryview, memory_size: bytes | bytearray | memoryview) → int[source]¶

Begin an ECU-to-client transfer (SID 0x35).

Parameters:

compression_method – Unshifted nibble, 0–15; zero is none.
encryption_method – Unshifted nibble, 0–15; zero is none.
memory_address – Big-endian address bytes.
memory_size – Big-endian total byte count.

Returns:

Maximum complete TransferData response size, including SID/counter.

async request_upload_alfid(compression_method: int, encryption_method: int, memory_address: int, memory_size: int, address_width: int, size_width: int) → int[source]¶

Begin an upload using integer fields with explicit byte widths.

Parameters:

compression_method – Unshifted nibble, 0–15.
encryption_method – Unshifted nibble, 0–15.
memory_address – Unsigned 64-bit address.
memory_size – Unsigned 64-bit total byte count.
address_width – Address byte count, 1–8.
size_width – Size byte count, 1–8.

Returns:

Maximum complete TransferData response size, including SID/counter.

async transfer_data(block_sequence_counter: int, data: bytes | bytearray | memoryview | None = None) → bytes | None[source]¶

Transfer one block (SID 0x36), validating the echoed counter.

Parameters:

block_sequence_counter – Unsigned wire byte; first block is usually 1.
data – Download data. None requests an upload block.

Returns:

Upload bytes or optional download response data; None when absent.

async request_transfer_exit(data: bytes | bytearray | memoryview | None = None) → bytes | None[source]¶

Finish an upload/download (SID 0x37).

Parameters:: data – Optional service-specific completion record, such as a checksum.
Returns:: Optional ECU completion data, or None when no record is returned.

class automotive.protocols.uds.UDSConfig(*, p2_timeout: float = 0.05, p2_star_timeout: float = 5.0, request_timeout: float | None = None, use_server_timing: bool = True, strict: bool = True)[source]¶

Reusable UDS timing and validation settings; durations are seconds.

Parameters:

p2_timeout – Initial response window, default 0.05 seconds.
p2_star_timeout – Response window after each NRC 0x78, default 5 seconds.
request_timeout – Overall exchange limit including sending and repeated pending responses. None (default) imposes no overall deadline.
use_server_timing – Adopt timings returned by session control, default True.
strict – Enable Rust’s strict response validation, default True. Minimum parsing lengths still apply when False; unknown codes are preserved.

Idle transport receive timeouts are retried within the UDS response window. Transport transmission and frame-reassembly timeouts still fail the request. Configured/server timing includes complete response reception. Durations must be finite and nonnegative; values are otherwise passed directly to Rust.

p2_timeout: float¶

p2_star_timeout: float¶

request_timeout: float | None¶

use_server_timing: bool¶

strict: bool¶

Synchronous API¶

class automotive.sync.protocols.uds.UDSClient(transport: Transport, config: UDSConfig | None = None)[source]¶

A blocking diagnostic client retaining its transport and session timing.

Parameters:

transport – Open synchronous message transport, such as software or native J2534 ISO-TP.
config – Shared timing and validation settings; None uses Rust defaults.

Calls on one transport are serialized by Rust. Results and exceptions match the async client. Ctrl+C interrupts the Python wait; an active Rust exchange drains under the transaction lock before another request can start. Closing the parent interrupts dependent operations. Set request_timeout to bound repeated response-pending messages. Idle receive expiry resumes waiting on the same stream without resending the request or extending P2/P2*. Transport transfer failures still raise errors.

Raises:

NegativeResponseError – The ECU rejected the request; code is its raw NRC.
ProtocolDeviationError – Strict validation failed; response retains the PDU.
TimeoutError – A transport, response, or overall deadline expired.
ValueError – Rust rejected an argument before transmission.
ConnectionError – The connection closed during an exchange.

suppress_positive_responses() → Generator[Self, None, None][source]¶

Suppress positive responses within an ordinary with block.

Nested scopes restore their previous setting, including after exceptions. The scope is local to the calling thread and context. Negative responses still raise; NRC 0x78 requires a final response. Services without a sub-function continue to require positive responses.

Yields:: This synchronous client, optionally bindable with as uds.

Send a custom UDS request and return positive response data.

Parameters:

sid – ServiceIdentifier or raw unsigned byte.
sub_function – Optional raw byte. Bit 7 requests suppression.
data – Optional service-specific bytes following the headers.

Returns:

Response data excluding SID and echoed sub-function, including b”” for an empty response. None means successful suppressed silence; it does not confirm ECU execution.

Rust handles NRC 0x78 and response validation. A pending response makes subsequent silence a timeout rather than successful suppression.

diagnostic_session_control(session_type: SessionType | int) → SessionParameterRecord | None[source]¶

Select a diagnostic session (SID 0x10).

Parameters:: session_type – Named session or raw byte, including suppression flags.
Returns:: Server timing in seconds, or None for suppression/non-strict responses without a timing record. Rust adopts the record when configured.

ecu_reset(reset_type: ResetType | int) → int | None[source]¶

Request an ECU reset (SID 0x11).

Parameters:: reset_type – Named reset or raw byte, including suppression flags.
Returns:: Optional power-down time as a raw wire integer; None when absent or when the positive response is suppressed.

Request a security seed or submit a key (SID 0x27).

Parameters:

access_type – Named access type or raw byte.
data – Optional key or manufacturer-specific request bytes.

Returns:

Seed bytes, or None for SendKey acknowledgement/suppressed silence.

Seed/key calculation remains the caller’s responsibility.

tester_present() → None[source]¶

Send TesterPresent (SID 0x3E), blocking for the configured response window.

A suppression scope accepts initial silence but still handles negative responses and requires a final response after NRC 0x78.

read_data_by_identifier(data_identifier: DataIdentifier | int) → bytes[source]¶

Read a DID (SID 0x22) and return its data record as bytes.

Parameters:: data_identifier – Named DID or raw unsigned 16-bit integer.

The echoed DID is checked in strict mode. No text decoding is applied.

write_data_by_identifier(data_identifier: DataIdentifier | int, data_record: bytes | bytearray | memoryview) → None[source]¶

Write a DID (SID 0x2E) and validate its acknowledgement.

Parameters:

data_identifier – Named DID or raw unsigned 16-bit integer.
data_record – New data record; copied before transmission.

read_memory_by_address(memory_address: bytes | bytearray | memoryview, memory_size: bytes | bytearray | memoryview) → bytes[source]¶

Read memory (SID 0x23) using explicit big-endian byte fields.

Parameters:

memory_address – Big-endian address bytes; leading zeros are retained.
memory_size – Big-endian size bytes; its length determines wire width.

Returns:

Memory data bytes. Use the _alfid variant for integer arguments.

read_memory_by_address_alfid(memory_address: int, memory_size: int, address_width: int, size_width: int) → bytes[source]¶

Read memory using integer address/size with explicit byte widths.

Parameters:

memory_address – Unsigned 64-bit memory address.
memory_size – Unsigned 64-bit byte count.
address_width – Address byte count, 1–8.
size_width – Size byte count, 1–8.

Raises:

ValueError – A width is invalid or the value does not fit it.

Write memory (SID 0x3D) using big-endian address/size byte fields.

Parameters:

memory_address – Big-endian address, retaining leading zeros.
memory_size – Big-endian byte count, retaining its explicit width.
data – Memory bytes to write; must match the requested size.

write_memory_by_address_alfid(memory_address: int, memory_size: int, address_width: int, size_width: int, data: bytes | bytearray | memoryview) → None[source]¶

Write memory with unsigned 64-bit address/size and byte widths 1–8.

Parameters:

memory_address – Numeric memory address.
memory_size – Number of memory bytes to write.
address_width – Address field width in bytes.
size_width – Size field width in bytes.
data – Memory data, copied before transmission.

Rust rejects invalid widths or values that do not fit before sending.

read_dtc_information_number_of_dtc_by_status_mask(mask: int) → DTCReportNumberByStatusMask | None[source]¶

Return the number of DTCs matching a status mask (SID 0x19/0x01).

Parameters:: mask – Unsigned byte containing the requested status bits.
Returns:: DTC count/metadata, or None for suppressed silence. Unknown format identifiers are returned as raw integers instead of being rejected.

Start, stop, or query a routine (SID 0x31).

Parameters:

routine_control_type – Named operation or raw byte.
routine_identifier – Named routine or raw unsigned 16-bit ID.
data – Optional routine-specific request record.

Returns:

Optional result record; None when absent or suppressed. Rust handles pending responses and validates the echoed routine in strict mode.

request_download(compression_method: int, encryption_method: int, memory_address: bytes | bytearray | memoryview, memory_size: bytes | bytearray | memoryview) → int[source]¶

Begin a client-to-ECU transfer (SID 0x34).

Parameters:

compression_method – Unshifted compression nibble, 0–15; zero is none.
encryption_method – Unshifted encryption nibble, 0–15; zero is none.
memory_address – Big-endian address bytes.
memory_size – Big-endian total byte count.

Returns:

Maximum complete TransferData request size, including SID/counter.

request_download_alfid(compression_method: int, encryption_method: int, memory_address: int, memory_size: int, address_width: int, size_width: int) → int[source]¶

Begin a download using integer address/size and explicit byte widths.

Parameters:

compression_method – Unshifted nibble, 0–15.
encryption_method – Unshifted nibble, 0–15.
memory_address – Unsigned 64-bit address.
memory_size – Unsigned 64-bit total byte count.
address_width – Address field length, 1–8 bytes.
size_width – Size field length, 1–8 bytes.

Returns:

Maximum complete TransferData request size, including SID/counter.

request_upload(compression_method: int, encryption_method: int, memory_address: bytes | bytearray | memoryview, memory_size: bytes | bytearray | memoryview) → int[source]¶

Begin an ECU-to-client transfer (SID 0x35).

Parameters:

compression_method – Unshifted nibble, 0–15; zero is none.
encryption_method – Unshifted nibble, 0–15; zero is none.
memory_address – Big-endian address bytes.
memory_size – Big-endian total byte count.

Returns:

Maximum complete TransferData response size, including SID/counter.

request_upload_alfid(compression_method: int, encryption_method: int, memory_address: int, memory_size: int, address_width: int, size_width: int) → int[source]¶

Begin an upload using integer fields with explicit byte widths.

Parameters:

compression_method – Unshifted nibble, 0–15.
encryption_method – Unshifted nibble, 0–15.
memory_address – Unsigned 64-bit address.
memory_size – Unsigned 64-bit total byte count.
address_width – Address byte count, 1–8.
size_width – Size byte count, 1–8.

Returns:

Maximum complete TransferData response size, including SID/counter.

transfer_data(block_sequence_counter: int, data: bytes | bytearray | memoryview | None = None) → bytes | None[source]¶

Transfer one block (SID 0x36), validating the echoed counter.

Parameters:

block_sequence_counter – Unsigned wire byte; first block is usually 1.
data – Download data. None requests an upload block.

Returns:

Upload bytes or optional download response data; None when absent.

request_transfer_exit(data: bytes | bytearray | memoryview | None = None) → bytes | None[source]¶

Finish an upload/download (SID 0x37).

Parameters:: data – Optional service-specific completion record, such as a checksum.
Returns:: Optional ECU completion data, or None when no record is returned.