J1939 Annotator

CanKing service extension that decodes and annotates J1939 Transport Protocol (TP) traffic.

This extension listens to incoming J1939 frames (29-bit CAN IDs) and enriches them with base J1939 identifier metadata. For TP Connection Management (TP.CM, PGN 0xEC00) and Data Transfer (TP.DT, PGN 0xEB00) frames it also adds TP-specific decode and reassembly state.

It can also be configured to actively participate in CMDT (connection mode) transfers by transmitting CTS and EndAck control frames.

What It Does

Subscribes to received CAN frames with 29-bit IDs (J1939 format).
Tracks TP sessions for both BAM (Broadcast Announce Message) and CMDT (RTS/CTS connection mode).
Reassembles TP payload data from TP.DT packets.
Annotates all J1939 frames with base properties (priority, PGN, source address, destination address).
Adds TP-specific properties on TP.CM / TP.DT frames (control type, transported PGN, progress, payload on completion).
Logs lifecycle events such as measurement start/stop, parse warnings, completed reassemblies, and session expiry.
Optionally participates as an active CMDT receiver by sending CTS windows and EndAck.

Passive Observer Scope

This extension is Rx-only and passive by design.

It observes existing traffic and annotates frames in CanKing.
Out-of-order BAM packets cause session drop.
Out-of-order CMDT packets are tolerated by keeping session state and waiting for expected sequence.

When active_listening is enabled, the extension sends TP.CM CTS and EndAck frames for CMDT transfers.

Note:
This extension never sends segmented messages of its own. It can only receive segmented messages, not transmit.

Frame Properties Added

Depending on frame type and decode state, the extension sets these frame properties:

Property	Set on	Value
`J1939.PGN`	All J1939 frames	Numeric PGN
`J1939.Source`	All J1939 frames	Source address (0–253)
`J1939.Destination`	All J1939 frames	Destination address (0–255)
`J1939.Priority`	All J1939 frames	Priority (0–7)
`J1939.TpControlType`	TP.CM frames (PGN `0xEC00`)	`"BAM"`, `"RTS"`, `"CTS"`, `"EndAck"`, `"Abort"`, or `"Unknown"`
`J1939.TpPGN`	All TP.CM and TP.DT frames	Transported-message PGN
`J1939.TpTotalBytes`	TP.CM BAM, RTS, EndAck frames	Total payload bytes declared in the frame
`J1939.TpNumPackets`	TP.CM BAM, RTS, EndAck frames	Total TP.DT packet count declared in the frame
`J1939.TpMaxPacketsPerCts`	TP.CM RTS frames	Maximum packets per CTS window the sender will accept
`J1939.TpCtsNumPackets`	TP.CM CTS frames	Number of DT packets the sender may transmit in this window
`J1939.TpCtsNextPacket`	TP.CM CTS frames	Sequence number of the first DT packet expected in this window
`J1939.TpAbortReason`	TP.CM Abort frames	Abort reason code
`J1939.TpSeqNo`	TP.DT frames (PGN `0xEB00`)	Sequence number byte (1–255)
`J1939.TpSessionProgress`	TP.DT frames with an active session	`"received/total"` byte count
`J1939.TpReassemblyComplete`	Last TP.DT of a complete message	`"true"`
`J1939.TpPayloadHex`	Last TP.DT of a complete message	Uppercase hex of reassembled payload
`J1939.TpActiveAction`	TP.CM RTS (active mode); TP.DT at window boundary or final packet	`"CTS sent"` or `"EndAck sent"`

Configuration

Configuration is JSON and can be changed at runtime via the CanKing extension config.

Default configuration:

{
  "session_timeout_ms": 750,
  "filter_pgns": [],
  "filter_source_addresses": [],
  "active_listening": false,
  "active_receiver_addresses": [],
  "active_cts_window_size": 255
}

Fields:

session_timeout_ms: T1-style inactivity timeout used for new sessions.
filter_pgns: allow-list of transported PGNs to annotate. Empty list means all PGNs.
filter_source_addresses: allow-list of source addresses to annotate. Empty list means all SAs.
active_listening: enable active CMDT participation (sends CTS and EndAck). Default false.
active_receiver_addresses: local destination addresses this extension may act as receiver for in CMDT. Active mode only sends CTS/EndAck when RTS destination matches one of these.
active_cts_window_size: max packets requested per CTS. Effective value is clamped against sender RTS byte 4 and remaining packets.