can-lite: Protocol Specification

Version: 1.0
Protocol Version Byte: 1
Status: Draft
Date: 2026

1. Abstract

This document specifies the can-lite CAN bus protocol, a lightweight client-server communication protocol operating over CAN 2.0B (29-bit extended identifiers) at up to 1 Mbit/s. The protocol provides a minimal built-in System category with heartbeat, command acknowledgement, status request, and category discovery messages. Applications extend the protocol by registering custom category handlers on the server.

2. Terminology

3. Architecture

The protocol follows a client-server model:

• The client is the sole initiator of commands and queries. It can address multiple servers on the same CAN bus by targeting different node addresses. The client maintains independent sequence counters per server.
• The server passively listens for incoming frames addressed to its node ID (or the broadcast address). It processes commands, dispatches them to the appropriate category handler, and sends acknowledgement responses.
• The topology is one client to many servers. A server serves exactly one client and keeps a single sequence counter; addressing one server from two clients concurrently is not supported and is rejected with a sequence error.
• Both the server and the client automatically transmit heartbeat messages starting from construction. Each side uses the presence or absence of the other’s heartbeats to determine whether its peer is online or offline: the client notifies the application via CanProtocolClientObserver (OnServerOnline(nodeId) / OnServerOffline(nodeId)), and the server via CanProtocolServerObserver (Online() / Offline()).

4. Transport

• Physical layer: CAN 2.0B
• Bit rate: up to 1 Mbit/s (configurable)
• Identifier format: 29-bit extended only; 11-bit frames are silently discarded
• Maximum payload: 8 bytes per frame (CAN 2.0 standard)

4.1 ISO-TP Segmentation (ISO 15765-2)

For payloads exceeding the 8-byte CAN frame limit, can-lite provides an optional ISO-TP transport layer (IsoTpTransportImpl) that implements ISO 15765-2 segmentation and reassembly.

Frame Types

Flow Control Fields

Timing Parameters

The receiver advertises the block size and separation time it is configured with, through IsoTpTransportImpl::Config (default 0 and 0, meaning no pacing), and sends a further Flow Control frame after each complete block. Every frame of a transfer is charged against the receiving server’s rate limit (§12). A node that receives long transfers alongside other traffic should therefore configure a separation time of at least 1000 / limit milliseconds, so that a peer cannot exceed the limit within one transfer.

On FS = Wait, the sender restarts N_Bs and continues waiting rather than aborting immediately; only N_WFTmax consecutive Wait frames (or an N_Bs timeout) abort the transfer.

A Flow Control frame the sender cannot decode — shorter than three bytes, or carrying a reserved Flow Status — aborts the transfer as an unexpected frame. It is deliberately not reported as an overflow, which is a state only the peer can declare.

N_Bs is armed the moment the sender enters the wait-for-Flow-Control state, before the frame is handed to the driver, so a driver that never reports completion still times out rather than leaving the sender wedged.

Unexpected and Failed Transfers

The receiver handles unexpected frames as ISO 15765-2 requires (REQ-CAN-046):

• Ignored:
  • a frame with an unknown protocol control nibble;
  • a single frame whose length is zero, above seven or beyond the frame;
  • a first frame shorter than eight bytes, or declaring fewer than eight bytes;
  • a consecutive frame while no reception is in progress;
  • a consecutive frame shorter than eight bytes that is not the last of the transfer, or a last one too short to hold the bytes still expected, so that frames carrying no data cannot keep a reception alive;
  • a flow control frame.
  None of these disturbs a reception in progress.
• Superseding: a valid single or first frame during a reception ends that reception, reported as an unexpected frame, and is then processed as a new reception.

A transfer that fails, in either direction, is discarded and reported once through the transport’s SetOnAbort callback, which names the identifier the data travelled on and the reason. The channel stays open. The abort callback belongs to the application: neither protocol object installs it, and neither releases channels.

Integration

IsoTpTransportImpl is attached to CanProtocolServer or CanProtocolClient via AttachIsoTpTransport(IsoTpTransport&). When attached, incoming frames are first offered to the ISO-TP layer; if no channel claims the frame, it falls through to normal category dispatch. PDUs reassembled by the transport layer are delivered via the SetOnPduReceived callback.

A channel is a connection with one peer, identified by a receive and a transmit identifier (REQ-CAN-035):

• Frames from the peer arrive on the receive identifier. Everything this node sends to the peer, data and flow control alike, leaves on the transmit identifier. A transmission and a reception can therefore run on one channel at the same time.
• RegisterReceiveChannel(dataId, fcId) opens the channel with dataId as its receive identifier and fcId as its transmit identifier.
• SendPdu(dataId, fcId) sends on dataId and takes flow control from fcId. Sending to a registered peer therefore uses the reversed pair, on the same channel.
• SendPdu for a new pair opens a channel that claims only flow control frames. A pair that shares just one identifier with another channel is refused.
• A channel stays open until the application calls ReleaseChannel with either of its identifiers. Releasing ends any transfer in progress on it without a report.

The implementation uses WithStorage for zero-heap construction. All internal components (IsoTpSender, IsoTpReceiver, IsoTpChannelImpl) are non-template classes that receive their PDU buffer storage via infra::WithStorage aliases, following the EMIL convention. An application sizes IsoTpTransportImpl::WithStorage<MaxPduSize, MaxChannels> over the protocol object’s own frame transport, attaches it with AttachIsoTpTransport, and opens each receive channel with RegisterReceiveChannel.

Sending to a category. Sending is the application’s: neither protocol object nor any category calls SendPdu. A PDU addressed to a server category travels on a data identifier built like a command’s (§5): command priority, the category, the message type and the server’s node ID. The receiving protocol object dispatches the reassembled PDU to that category’s segmented handler, through the same admission, sequence and acknowledgement path as a single frame (§11). For a category that validates sequence numbers, the PDU’s first byte is the sequence number. The application reserves it from the client, which is the sequence source; it cancels the reservation if SendPdu refuses the transfer, and returns the number if the transfer is reported through the abort callback. SendPdu’s completion runs only when the transfer succeeds.

Addressing constraint. IsoTpTransportImpl routes frames to channels purely by the literal CAN ID carried in dataId/fcId — the sender’s identity is not otherwise encoded. AttachIsoTpTransport() alone does not register any channel; the application (or a category built on top of it) must explicitly call RegisterReceiveChannel() for each dataId/fcId pair it expects multi-frame traffic on, using IDs that unambiguously identify a single correspondent (e.g. a dedicated node-to-node exchange such as a firmware upload session). A dataId shared by more than one concurrent sender at a time will have their frames interleaved into the same channel; the transport layer does not detect or reject this. Because of this, can-lite does not provide automatic multi-frame support for arbitrary category command/response traffic across many nodes — only the point-to-point case with an explicitly-managed channel is supported.

5. CAN Identifier Layout

All 29 bits of the extended CAN ID are structured as follows:

Bit:  28  27  26  25  24  23  22  21  20  19  18  17  16  15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
     |----- Priority ----|--- Category --|--------- Message Type --------|------------------- Node ID -------------------|
     |   5 bits (0-1F)   |  4 bits (0-F) |         8 bits (0-FF)         |                12 bits (0-FFF)                |

Field Encoding:

raw_id = (priority << 24) | (category << 20) | (message_type << 12) | node_id

6. Priority Levels

Lower numerical values have higher CAN bus arbitration priority.

Emergency priority means more than arbitration. A server admits an emergency command outside the ordinary sequence and rate-limit rules (§11, §12), and every node sends queued emergency frames first, from queue capacity kept for them (REQ-CAN-039, REQ-CAN-040). Priority also decides admission to a full send queue: a frame that finds its share taken displaces the newest queued frame of the lowest priority when that frame is less urgent than itself, and is refused otherwise, so a response or an acknowledgement is never lost to queued heartbeats or telemetry (REQ-CAN-040).

7. Message Categories

The System category is always available. Category 0x1 is defined in a separate extension specification:

• Firmware Upgrade

Applications register additional categories (values 0x2-0xF) by providing CanCategoryServer and CanCategoryClient implementations to CanProtocolServer::RegisterCategory() and CanProtocolClient::RegisterCategory(). Both return false, without registering, if the category’s ID is already registered or if 8 categories are already registered (the System category always occupies one of those 8 slots). See Extending can-lite with categories.

7.1 Reserved Message Type

Message type 0xFE is reserved across all categories for a category error response, carrying a category-specific failure detail that the universal acknowledgement status cannot express.

A category error response is normally followed by a command acknowledgement with status categoryError.

8. Message Catalog

8.1 System (Category 0x0)

8.1.1 Heartbeat (Type 0x01)

Sent at CanPriority::heartbeat. No sequence validation.

Both the server and the client automatically transmit heartbeat messages starting from the moment they are constructed. A heartbeat is sent at least 1 second after the last transmitted message of any kind, by whichever side is sending it. This ensures liveness detection without adding traffic when that side is already actively communicating. The heartbeat acts as a keep-alive: it fires only during periods of silence. The server keeps at most one heartbeat queued or in transmission at a time: while one is pending, neither the timer nor a status request adds another, and the pending one answers them (REQ-CAN-048). The client’s heartbeat is broadcast (node ID 0x000), since the client has no node ID of its own on the bus.

The client uses received heartbeats to track server liveness. When a heartbeat (or any message) is received from a server, the client considers that server online and resets that server’s timeout timer. If no messages are received from a server within a configurable timeout (default 3 s), the client considers it offline and notifies the application via CanProtocolClientObserver::OnServerOffline(nodeId). Multiple servers (up to 8) can be tracked simultaneously with independent liveness timers.

Symmetrically, the server uses received traffic to track whether its client is still present. Every command the server accepts (re)starts its client timeout timer (default 3 s, Config::clientTimeout). A command is accepted when it is addressed to the server, belongs to a registered category, is a known command type, passes sequence validation where the category requires it (§11), and has a payload its handler accepts. A client heartbeat is an accepted command like any other. A frame the server rate-limits, discards or answers with an error does not restart the timer, so invalid traffic cannot keep a departed client online. The first accepted command after start-up, or after the client went offline, notifies CanProtocolServerObserver::Online(); later ones do not. If the timer expires without a further accepted command, the server notifies CanProtocolServerObserver::Offline(). The two notifications therefore alternate, one per transition.

A server tracks only one client, per REQ-CAN-006.1. The identifier carries the destination node but not the source, so the server cannot tell controllers apart. It assumes a single trusted controller on the bus and treats any accepted command as proof that this controller is present. A bus with several controllers would need a source or session identity in the frame, which this protocol does not define.

8.1.2 Command Acknowledgement (Type 0x02)

Sent by the server at CanPriority::response.

The category byte ensures the client can uniquely identify which command is being acknowledged, since message type values may be reused across categories.

On receiving a sequenceError acknowledgement, the client adopts byte 3 as its next sequence number for that server, so that a single lost frame, or the client’s own sequence state having reset (for example after a restart), does not leave the two sides permanently out of sync — see §11.

If no acknowledgement of any status arrives for a sequence-validated command within a configurable timeout (default 1 s, Config::commandAckTimeout), the client notifies the application via CanProtocolClientObserver::OnCommandAckTimeout(nodeId, category, messageType). The command itself is not retried; the application decides whether and how to retry.

8.1.3 Status Request (Type 0x03)

Sent by the client at CanPriority::command. No sequence validation. Empty payload.

When received, the server responds by transmitting a heartbeat message. This allows the client to quickly confirm the server is online without waiting for the next scheduled heartbeat. One heartbeat answers every status request received while it is still waiting to be sent, so a burst of requests, such as the backlog a bus adapter delivers when a server comes back after a restart, produces one heartbeat rather than one per request and cannot fill the server’s send queue ahead of a command’s response and acknowledgement (REQ-CAN-048).

8.1.4 Category List Request (Type 0x04)

Sent by the client at CanPriority::command. No sequence validation. Empty payload.

When received, the server responds with a Category List Response message containing the IDs of all registered category handlers.

The client keeps one discovery pending at a time, addressed to one server; a request to the broadcast address, or while another is pending, is refused. Only a Category List Response from the server asked completes it. If none arrives within a configurable timeout (default 1 s, Config::discoveryTimeout), the discovery completes without an answer.

8.1.5 Category List Response (Type 0x05)

Sent by the server at CanPriority::response.

Each byte contains the ID of one registered category handler. The System category (0x0) is always included. Categories are listed in registration order. The response is limited to 8 category IDs by the CAN frame payload size. RegisterCategory() enforces this bound at registration time: the 9th and any subsequent registration attempt returns false and the category is not registered, so the response can never truncate.

9. Data Encoding

All multi-byte values are encoded big-endian (network byte order). Each message’s specification states, per floating-point field, which of the two encodings below it uses.

9.1 Encoding Algorithm

fixed_value = clamp(round(float_value × scale_factor), INT_MIN, INT_MAX)
float_value = fixed_value / scale_factor

Values are saturated (clamped) to the target integer range to prevent overflow.

9.2 Single-Precision Floating Point

A field carried without a scale factor occupies 4 bytes and holds the IEEE 754 binary32 bit pattern of the value, encoded as a big-endian uint32. The bytes are identical to those of a uint32 field holding the same bit pattern. No rounding, clamping or substitution is applied: signed zero, subnormals, infinities and NaN payloads arrive bit for bit as they were sent, and a receiver that requires a finite value checks for it itself.

10. Enumeration Tables

10.1 Acknowledgement Status

11. Sequence Number Protocol

• For command frames that carry a payload, Byte[0] is an unsigned 8-bit sequence counter used for best-effort in-order processing.
• The server accepts the first sequenced command received regardless of sequence value and records it as the reference.
• Each subsequent command should have sequence = (previous + 1) mod 256.
• Out-of-order or duplicated commands are rejected with a sequenceError acknowledgement.
• The recorded sequence advances only when a command is accepted (§8.1.1). A command answered with sequenceError, invalidPayload or unknownCommand leaves it unchanged, so malformed or unrecognised traffic cannot shift the sequence the client’s next command must carry.
• A command sent at emergency priority still carries the sequence byte, but the byte is not checked. The command is accepted whatever the recorded sequence is, so an emergency stop cannot fail with sequenceError. Once it is accepted, the server records its sequence byte as the last accepted one, so the client’s next ordinary command follows on without a sequence error.
• Individual category handlers declare whether they require sequence validation via RequiresSequenceValidation(). Categories that opt out bypass validation entirely.
• When sequence validation is required and the payload is empty (no sequence byte present), the frame is rejected with invalidPayload.
• Heartbeat and status request frames do not use sequence numbers.
• Unrecognized message types within a registered category are rejected with an unknownCommand acknowledgement.
• A sequenceError acknowledgement carries the sequence number the server expected (§8.1.2); the client adopts it as its next sequence number for that server. This recovers a client whose own sequence state has drifted from the server’s (for example, after the client process restarts and its in-memory counter resets to 0 while the server, unaware of the restart, still expects its old counter to continue) without requiring the server to also restart.
• The client takes a number for a server, and records the command as awaiting acknowledgement, before the frame reaches the CAN driver (REQ-CAN-045), so an acknowledgement delivered while the frame is still being sent is matched to it. A command its send queue refuses leaves every counter as it was. A queued command whose frame then fails to leave the node, through a driver failure or displacement by an emergency frame, gives its number back unless a later command to that server has already taken the next one; the loss is reported through the acknowledgement timeout (§8.1.2).
• Sequence numbers are not an authentication or security mechanism and MUST NOT be relied upon to prevent malicious replay on an untrusted CAN bus.

12. Rate Limiting

The server enforces a configurable maximum number of received messages per second (default: 500). Messages received after the limit is reached are silently discarded. The rate counter resets automatically every second via an internal timer.

Frames at emergency priority are charged to a separate budget (default: 20 per second, Config::maxEmergencyMessagesPerSecond), reset by the same timer. Ordinary traffic cannot use up the emergency budget, and emergency traffic does not use the ordinary one. So an emergency stop is still admitted when a flood has exhausted the ordinary limit. Rate limiting is the first check after addressing, so a flood of any kind costs only a counter comparison per frame. The server counts every refusal and every admitted emergency command, and exposes these counts through CanProtocolServer::Statistics() (REQ-CAN-044).

Every accepted frame is charged, including one an ISO-TP channel consumes, so a multi-frame PDU costs one credit per frame it occupies on the bus rather than one credit for the whole transfer. The reassembled PDU is not charged again when it is dispatched.

13. Node Addressing

• Each server has a unique 12-bit node ID (1–4095) set at configuration time.
• Node ID 0x000 is reserved as the broadcast address.
• Frames addressed to the broadcast ID are accepted by all servers.
• Frames addressed to a different node ID are silently discarded.

14. Typical Command Flow

15. Extensibility

Applications extend can-lite by defining additional categories:

1. Define an enum value for the new category (0x2–0xF; 0x1 is reserved for Firmware Upgrade).
2. Implement CanCategoryServer and CanCategoryClient subclasses that handle the message types within that category.
3. Register the handler with the server at construction time.

The server dispatches incoming frames to the matching category handler. Frames with unregistered categories are silently discarded. Frames with a registered category but an unknown message type receive an unknownCommand acknowledgement.

16. Security Considerations

• In-order delivery / duplicate detection: Sequence number validation rejects out-of-order or duplicated commands. This is a best-effort ordering check, not a security mechanism — see §11’s caveat: sequence numbers are transmitted in the clear and MUST NOT be relied upon to prevent malicious replay on an untrusted CAN bus.
• Bus flooding protection: Configurable rate limiting discards excess messages. Emergency-priority traffic has its own budget, so a flood of ordinary frames cannot shut out an emergency stop (§12).
• Trusted controller: The protocol has no source identity. Liveness and sequence state assume a single trusted controller on the bus (§8.1.1).
• Input validation: All payloads are length-checked before parsing. The firmware upgrade client also rejects a status or state outside the range its specification defines (firmware-upgrade.md §5). Elsewhere an enum-valued field is decoded from the wire byte unchecked: an out-of-range value produces a scoped-enum value with no matching enumerator (well-defined per the C++ standard, since these enums have a fixed underlying type) rather than a rejected frame.
• No heap allocation: Fixed-size buffers prevent memory exhaustion.
• Node isolation: Strict node ID filtering prevents cross-node interference.