BMCLI uds

命令名、参数与机器可读字段保持英文，以便直接复制到终端或交给 AI 使用；当前安装版本的精确契约请以 bmcli help ... --format=json 为准。

UDS (ISO 14229) diagnostic services over ISOTP. Daemon workflows maintain endpoint state through uds config get|set.

uds discover

Discover standard 11-bit physical UDS response IDs by transmitting one single-frame request to functional ID 0x7DF. This command runs standalone, requires exclusive hardware access, and refuses to transmit unless the caller passes --allow-functional after user authorization.

bmcli uds discover --channel=10356/1 --allow-functional --dry-run --format=json
bmcli uds discover --channel=10356/1 --allow-functional --format=json
bmcli uds discover --channel=10356/1 --allow-functional --probes=3 --timeout=500 --format=json
bmcli uds discover --channel=10356/1 --allow-functional --data="22 F1 90" --format=json

The default request is TesterPresent (3E 00). --data accepts a documented 1-7 byte UDS request. The default --probes=3 sends three independent requests; an ID is qualified only if it returns a matching UDS response in every probe window. For TesterPresent, 02 7E 00 is matched using the ISO-TP length, so any following CAN padding bytes are ignored. --timeout is the response window for each probe. Matching responses are collected from any 11-bit CAN ID; the implementation does not assume the OBD-only 0x7E8-0x7EF range. The output includes conventionally inferred physical request IDs (`response ID

• 8), so pairs such as 0x791/0x799are represented correctly. Treat inferred IDs as candidates until an ECU identity read confirms the target. If several IDs answer every probe, BMCLI returnsstatus=needs_selectionandselection_required=true`. The caller must show those IDs to the user and must not choose or persist one automatically.

uds config get/set

Read or set daemon UDS endpoint parameters. The configuration persists for subsequent UDS commands while that daemon is running.

bmcli uds config set --channel=10356/0 --request-id=0x7E0 --response-id=0x7E8
bmcli uds config set --channel=10356/0 --request-id=0x7E0 --response-id=0x7E8 --flags=fdf --padding=0xCC
bmcli uds config get --format=json

Option	Required	Description
--channel	set	Channel (e.g. 0, 10356/1)
--request-id	set	TX CAN ID (varies per ECU, e.g. 0x7E0, 0x791)
--response-id	set	RX CAN ID (varies per ECU, e.g. 0x7E8, 0x799)
--flags	set, optional	fdf for CAN FD
--padding	set, optional	ISOTP pad value

There are no defaults for --channel, --request-id, or --response-id. They vary per ECU, and silent defaults would only mask missing parameters with a misleading bus timeout. Always specify them explicitly when setting the configuration.

uds request

Send a UDS request and receive the response. Supports raw hex bytes and named services from loaded UDS XML definitions.

Exit codes (script fail-fast):

• 0: positive response, or a deliberately suppressed response after the request was transmitted successfully.
• 1: negative response, timeout, transport failure, configuration error, or other command failure. Structured JSON fields such as nrc, reason, and message distinguish these cases.

NRC 0x78 (responsePending) handling: if the ECU replies 7F <SID> 78, bmcli does NOT treat it as a final failure — it restarts the P2* wait and reads again for the deferred final response (a new ISOTP message), per ISO 14229-1 §7.5.3. Caps at 30 iterations / 30 s. This matters for real ECUs that stall on session switches (10 02), resets (11 01), or long services (31 01/34/37).

Requires either prior uds config set or --channel, --request-id, and --response-id on this command line. Missing parameters produce a clear error with no silent defaults.

# --- Raw hex ---

# TesterPresent with a normal positive response
bmcli uds request 3E 00

# Ask BMCLI to set suppressPosRspMsgIndicationBit (transmits 3E 80)
bmcli uds request 3E 00 --suppress-positive-response

# ReadDataByIdentifier (VIN)
bmcli uds request 22 F1 90

# DiagnosticSessionControl -> extended session
bmcli uds request 10 03

# ECUReset -> hard reset
bmcli uds request 11 03

# CommunicationControl -> enable RX/TX
bmcli uds request 28 00 01

# RoutineControl -> start routine by identifier
bmcli uds request 31 01 FF 00

# RequestDownload
bmcli uds request 34 00 44 00 00 00 00 00 00 10 00

# TransferData (block sequence 0x01)
bmcli uds request 36 01 AA BB CC DD EE FF

# --- Named services (requires loaded uds.xml) ---

bmcli uds request hardReset
bmcli uds request DiagnosticSessionControl extended
bmcli uds request ReadDataByIdentifier VIN
bmcli uds request ReadDataByIdentifier 0xF190
bmcli uds request CommunicationControl enableRxAndTx
bmcli uds request RoutineControl startRoutine 0xFF00

# --- Options ---

# Dry-run: show built request bytes without sending
bmcli uds request --dry-run 22 F1 90

# Override session parameters for this request
bmcli uds request --timeout=3000 --channel=10356/0 \
  --request-id=0x7E0 --response-id=0x7E8 3E 00

Option	Default	Description
--channel	session	Override channel
--request-id	session	Override TX ID
--response-id	session	Override RX ID
--timeout	5000	Timeout ms
--data	—	Raw hex data (alternative to positional args)
--suppress-positive-response	off	Set bit 7 on a supported subfunction and accept a successfully transmitted request with no positive response
--dry-run	—	Show request bytes without sending

Positional args: hex bytes (3E 80) or service name + parameters.

Suppression is service-aware. BMCLI accepts it only for UDS services whose second request byte is a subfunction. It rejects the option for services such as ReadDataByIdentifier (0x22) so bit 7 cannot silently corrupt the first DID byte. A raw request that already contains the suppression bit, such as 3E 80, is recognized as suppressed even without the option.

uds load

Load UDS service definitions from an XML file.

bmcli uds load --file=res/uds.xml

uds save

Save current UDS definitions to XML.

bmcli uds save --file=output.xml

uds list

List loaded UDS services and their sub-functions.

bmcli uds list
bmcli uds list DiagnosticSessionControl

uds unlock

Perform SecurityAccess (service 0x27) — the request-seed / send-key sequence.

--algo is always a path to an external security DLL/.so (must export GenerateKeyEx or GenerateKeyExOpt). UDS SecurityAccess has no standard algorithm, so bmcli ships no builtins — the OEM algorithm is always provided as a DLL. --level accepts hex (0x11) or decimal (17); it is the SecurityAccess sub-function.

Both 0x27 responses are read with NRC 0x78 (responsePending) retry, so an ECU that defers its reply is handled correctly.

bmcli uds unlock --level=0x11 --algo=res/sa.dll        # Windows DLL
bmcli uds unlock --level=0x11 --algo=./libsecurity.so  # Linux .so

Option	Description
--level	Security access level (UDS sub-function), hex or decimal (required, e.g. 0x11)
--algo	Path to security algorithm DLL/.so (required)
--timeout	Timeout ms (default 5000)

uds download

Transfer a firmware image to ECU memory via services 0x34 (RequestDownload), 0x36 (TransferData), 0x37 (RequestTransferExit). Multi-format, multi-segment:

• Parses Intel HEX (.hex, type 04 ext-linear addresses), Motorola S19 (.s19/.srec, S1/S2/S3), or raw binary (.bin). Use --format=auto to detect by extension/content.
• A multi-segment file is downloaded as separate 34/36/37 cycles per segment.
• The 0x74 response’s maxNumberOfBlockLength is parsed and respected (override with --maxblock). Each 0x36 response is validated (SID + seq); 0x37 is validated too. A wrong-sequence or NRC aborts with a structured, AI-readable error (stage / segment / percent / expect / actual).
• NRC 0x78 (responsePending) on any response is handled transparently.

bmcli uds download --file=firmware.bin --addr=0x08000000
bmcli uds download --file=app.hex --format=auto --alf=0x44 --maxblock=0x0FFF

Option	Description
--file	Firmware file: .bin / .hex / .s19 (required)
--format	auto (default) / bin / hex / s19
--addr	Start address (bin only; hex/s19 use per-segment addresses)
--size	Truncate to N bytes (bin only)
--alf	addressAndLengthFormatIdentifier for 0x34 (default 0x44; high nibble = addr bytes, low = size bytes)
--maxblock	Override the 0x74-negotiated maxNumberOfBlockLength

checksum

Compute a checksum / CRC of a file. This is a general-purpose tool (not part of UDS) — useful for assembling RoutineControl 31 01 02 02 <crc> check requests. Lives under its own top-level category, parallel to convert/database.

--algo follows the same unified resolution rule as uds unlock: builtin name first, else external DLL/.so exporting ComputeChecksum.

bmcli checksum --file=app.hex --algo=crc32-ieee          # builtin
bmcli checksum --file=app.hex --algo=crc32-ieee --segment=0   # one segment only
bmcli checksum --file=app.hex --algo=./compute_checksum.dll   # external DLL
bmcli checksum --self-test                                # validate CRC check values

Option	Description
--file	Input file (required, or use --self-test)
--format	auto (default) / bin / hex / s19
--algo	Builtin name (crc32-ieee, crc16-ccitt, crc16-xmodem, crc16-modbus) or external DLL/.so (default crc32-ieee)
--segment	all (default) or segment index N — compute over one segment
--poly / --init / --xorout	Override CRC parameters (advanced)

Built-in crc32-ieee matches Python zlib.crc32 and the IEEE 802.3 CRC-32 (poly 0x04C11DB7, init 0xFFFFFFFF, reflected, xorout 0xFFFFFFFF; check value 0xCBF43926 for ASCII “123456789”). Output JSON includes both the combined checksum and per-segment CRCs.

The external DLL signature (example/checksum_dll/compute_checksum_impl.c):

int ComputeChecksum(const uint8_t *data, uint32_t dataLen,
                    uint8_t *outChecksum, uint32_t maxOutSize, uint32_t *outSize,
                    uint32_t polynomial, uint32_t initValue, uint32_t xorOutValue,
                    void *userArg);

uds present send / start / stop / status

Manage TesterPresent keep-alive. The default request is 3E 00; BMCLI waits for and validates 7E 00. Add --suppress-positive-response to send 3E 80 and avoid waiting for the deliberately suppressed positive response.

# Finite, validated requests
bmcli uds present send --count=3 --interval=2000

# Finite, suppressed requests
bmcli uds present send --count=10 --interval=2000 --suppress-positive-response

# Daemon-owned keep-alive for a longer diagnostic workflow
bmcli uds present start --interval=2000 --suppress-positive-response
bmcli uds present status --format=json
bmcli uds present stop

send is finite: --count defaults to 1, --interval to 2000 ms, and --timeout to 1000 ms. It may run standalone when all endpoint options are provided, or use daemon session configuration.

start requires the daemon. It snapshots the channel, request ID, response ID, interval, timeout, and suppression mode, then owns one background keep-alive task until stop, daemon shutdown, or fatal daemon cleanup. status reports whether the task is active plus sent, response, failure, and last-result counters. The daemon serializes this task with foreground UDS transactions so ISO-TP request/response pairs cannot overlap on the same BMAPI session. stop is idempotent when no task is active.

Option	Commands	Default	Description
--interval=<milliseconds>	send, start	2000	Period between requests
--count=<N>	send	1	Finite request count
--timeout=<milliseconds>	send, start	1000	Send and positive-response timeout
--suppress-positive-response	send, start	off	Send 3E 80 and do not wait for 7E 00
--channel, --request-id, --response-id	send, start	session	Override or snapshot the UDS endpoint
--dry-run	send, start	off	Resolve the operation without transmitting or starting a task

uds dtc

Read, query, and clear Diagnostic Trouble Codes (UDS services 0x19 / 0x14). DTC codes are 3 bytes (24-bit) per ISO 14229-1.

# List all active DTCs
bmcli uds dtc
bmcli uds dtc active

# Query all DTCs the ECU defines, regardless of status
bmcli uds dtc supported

# Same as above, using hex subfunction code directly
bmcli uds dtc 0x0A

# Get number of DTCs matching a mask (count only, no detail)
bmcli uds dtc count

# List only confirmed DTCs
bmcli uds dtc --mask=0x09

# Query snapshot record IDs
bmcli uds dtc snapshot-id

# Read one snapshot or extended-data record for DTC 0x001234
bmcli uds dtc snapshot --dtc=0x001234 --record=0x01
bmcli uds dtc extended --dtc=0x001234 --record=0x01

# Use record 0xFF when the ECU supports returning all records
bmcli uds dtc snapshot --dtc=0x001234 --record=0xFF

# Clear all DTC groups (the default group is 0xFFFFFF)
bmcli uds dtc clear
bmcli uds dtc clear --group=0xFFFFFF

Subcommand	Hex Alias	UDS Service	Description
(default) / active	0x02	0x19 0x02	List active DTCs with 3-byte codes + status
count	0x01	0x19 0x01	Count of DTCs matching mask
supported	0x0A	0x19 0x0A	All DTCs the ECU supports
snapshot-id	0x03	0x19 0x03	Snapshot record IDs per DTC
snapshot	0x04	19 04 <DTC3> <record>	Snapshot data for a specific DTC and record selector
extended	0x06	19 06 <DTC3> <record>	Extended data for a specific DTC and record selector
clear	—	14 <group3>	Clear a DTC group; FFFFFF selects all groups

Option	Default	Description
--channel	session	Override channel
--mask	0xFF	Status mask filter for active and count
--dtc	required	24-bit DTC for snapshot and extended; hexadecimal notation is recommended
--record	required	Record byte for snapshot and extended; 0xFF requests all records
--group	0xFFFFFF	24-bit group for clear
--timeout	5000	Timeout ms
--request-id / --response-id	session	Override the configured diagnostic IDs

active, count, supported, snapshot-id, snapshot, extended, and clear each have an action-specific machine-readable Help contract. For example, run bmcli uds dtc snapshot --help --format=json before constructing the request. Positional hex aliases remain available for the implemented 0x19 subfunctions; the former --sub option is not accepted.

The positive response to count is interpreted as 59 01 <status-availability> <DTC-format> <count-high> <count-low>. Snapshot and extended-data requests are exactly six bytes, including service and subfunction; no extra status-mask byte is inserted.

---

---

权威来源: bmcli_reference.md in the BMCLI repository. Run bmcli help <category> <action> --format=json for the exact contract of the installed version.