CAN Bus Transport

High-throughput, frame-based field bus integration.

CAN bus is a deterministic, broadcast transport designed for real-time systems. MapsMessaging integrates with CAN via native SocketCAN interfaces or supported serial USB-CAN adapters, ingesting frames as fast as the bus and adapter allow.

The bus itself defines throughput, ordering, and arbitration. There is no concept of connection state, retries, or flow control at the transport layer.

MapsMessaging can optionally queue outbound CAN writes. Queued writes are used to protect the bus from uncontrolled application bursts, while still allowing multi-frame protocol messages such as NMEA 2000 fast-packet messages to be handled as complete logical messages.

Features

Native SocketCAN integration
Serial USB-CAN adapter support for Waveshare USB-CAN-A compatible devices
Zero connection setup
Deterministic arbitration at the hardware level
High-frequency frame ingestion
Low latency, low overhead
Optional asynchronous queued writes
Logical-message queueing for multi-frame CAN/NMEA 2000 messages
Configurable outbound bus usage limit
Suitable for embedded and industrial systems

Supported CAN Interfaces

MapsMessaging supports CAN bus access using:

Native SocketCAN interfaces
Serial USB-CAN adapters using the Waveshare USB-CAN-A protocol

SocketCAN is preferred on Linux systems where the CAN interface is exposed as a native network device, such as can0 or can1.

Serial CAN support is intended for USB CAN adapters that expose a serial port and implement the Waveshare USB-CAN-A framing protocol.

At present, serial CAN support is protocol-specific and should not be assumed to work with arbitrary USB CAN adapters.

When to Use CAN Bus

CAN bus is recommended when:

Interfacing with embedded systems or vehicles
Deterministic timing matters more than payload size
The data source controls transmission rate
Reliability is handled at the protocol level, such as NMEA 2000 or J1939
Extremely low overhead is required
Outbound writes must be rate-limited to avoid excessive bus usage

If you need reliable delivery, large payloads, or remote clients, use TCP instead.

When to Use Serial CAN

Serial CAN is recommended when:

Running on Windows or macOS
Using a USB CAN adapter that does not expose SocketCAN
Testing or demonstrating CAN integrations without native CAN hardware
Connecting to CAN from containers where passing through SocketCAN is inconvenient
Using Waveshare USB-CAN-A compatible devices

Use SocketCAN when deploying on Linux systems with native CAN support.

Transport Characteristics

Unlike TCP or UDP, CAN bus:

Is broadcast, not point-to-point
Has no sessions or connections
Uses hardware arbitration, not software flow control
Delivers fixed-size frames
Cannot be back-pressured by the receiver

MapsMessaging reads from the bus as a passive consumer. Inbound traffic is not throttled by MapsMessaging because the CAN bus and attached devices define the inbound frame rate.

Outbound traffic can be queued and rate-limited. This allows MapsMessaging to send protocol messages without allowing application bursts to consume too much of the shared bus.

Endpoint Usage

CAN bus endpoints inherit common settings from EndPointConfigDTO, but most fields are ignored due to the stateless nature of CAN.

SocketCAN Example

- name: "Canbus Interface"
  url: canbus://::/
  deviceName: can1
  protocol: n2k

SocketCAN Example with Queued Writes

- name: "Canbus N2K Interface"
  url: canbus://0.0.0.0/
  protocol: n2k
  auth: default
  deviceName: can1
  queuedWritesEnabled: true
  queueDepth: 128
  bitrateBitsPerSecond: 250000
  maxBusUsagePercent: 20.0
  queueFullPolicy: DROP_OLDEST
  writeFailureBackoffMilliseconds: 100

Serial CAN Example

- name: "Canbus N2K Interface"
  url: canbus://0.0.0.0/
  protocol: n2k
  auth: default
  serial:
    port: com8
    baudRate: 2000000
    dataBits: 8
    stopBits: 1
    parity: n
    flowControl: 0

Notes

url is a logical identifier, not a network address
deviceName is used for native SocketCAN interfaces
serial is used for supported USB serial CAN adapters
protocol determines frame decoding and topic mapping
Serial CAN currently supports adapters compatible with the Waveshare USB-CAN-A serial protocol
Generic serial CAN adapters are not automatically supported unless they use the same framing protocol
Queued write settings only affect outbound frames written by MapsMessaging
Queued write settings do not throttle inbound bus reads

Queued Write Configuration

Queued writes are enabled by default.

When enabled, MapsMessaging does not write every outbound frame immediately from the caller thread. Instead, outbound traffic is submitted as logical CAN messages into a bounded queue. A writer then drains that queue while respecting the configured bus usage limit.

This is important for protocols such as NMEA 2000. A single protocol message may be represented by one CAN frame or by multiple CAN frames. For example, an N2K fast-packet message must be treated as one logical message even though it is physically transmitted as several CAN frames.

Queued writes therefore operate on logical messages, not isolated frames. When the queue accepts, drops, or rejects traffic, it does so for the complete logical message. This avoids sending half of a multi-frame protocol message and leaving other devices on the bus to enjoy the traditional networking experience of wondering what just happened.

Configuration Fields

Field	Default	Description
`queuedWritesEnabled`	`true`	Enables asynchronous queued writes for outbound CAN traffic.
`queueDepth`	`128`	Maximum number of logical CAN messages held in the outbound queue.
`bitrateBitsPerSecond`	`250000`	CAN bus bitrate used to estimate outbound bandwidth usage.
`maxBusUsagePercent`	`20.0`	Maximum percentage of bus bandwidth MapsMessaging should consume for queued writes.
`queueFullPolicy`	`DROP_OLDEST`	Policy used when the queue is full.
`writeFailureBackoffMilliseconds`	`100`	Delay after a failed write before the writer attempts the next queued message.

Queue Full Policies

queueFullPolicy controls what happens when the outbound queue is full.

Policy	Behaviour
`DROP_OLDEST`	Removes the oldest queued logical message and accepts the new logical message.
`REJECT_NEW`	Rejects the new logical message and leaves the existing queue unchanged.

DROP_OLDEST is useful for telemetry-like traffic where newer state is more valuable than older state.

REJECT_NEW is useful when preserving already accepted messages matters more than accepting the newest message.

Controlled Bus Usage

CAN is a shared bus. Every frame transmitted by MapsMessaging consumes capacity that other devices may need. The queued writer therefore estimates the cost of outbound traffic and spaces writes so that MapsMessaging remains within the configured usage target.

The usage limit is controlled by:

bitrateBitsPerSecond: 250000
maxBusUsagePercent: 20.0

With the default values, MapsMessaging targets no more than 20% of a 250 kbit/s bus for its queued outbound writes.

The limit is not a replacement for CAN hardware arbitration. CAN arbitration still decides which device wins access to the bus at the electrical/protocol level. The MapsMessaging queue is an application-side pacing mechanism that reduces the chance of the server dominating the bus.

This is especially useful when bridging from higher-throughput protocols into CAN. MQTT, AMQP, REST, or internal server processes can produce messages much faster than a CAN or NMEA 2000 network should reasonably accept. Queued writes absorb short bursts and release them at a controlled rate.

What Is Controlled

Queued writes control:

Outbound CAN frames written by MapsMessaging
Burst behaviour from higher-throughput protocols
Multi-frame logical messages as complete units
The approximate share of bus bandwidth used by MapsMessaging writes
Backoff after write failures

Queued writes do not control:

Frames transmitted by other devices
Hardware arbitration
Inbound frame rate
Electrical bus errors
Adapter firmware buffering
Protocol-level retries performed by other devices

Serial CAN Behaviour

When a serial CAN adapter is configured:

The serial port is opened using the configured baud rate and serial parameters
CAN frames are encoded and decoded using the supported adapter protocol
The adapter bridges between serial packets and CAN bus frames
MapsMessaging treats decoded frames the same way as frames received from SocketCAN

Serial CAN adapters introduce an additional conversion layer between the server and the CAN bus. Throughput and latency depend on:

The serial baud rate
Adapter firmware behaviour
USB serial driver performance
CAN bus speed
Host CPU load

Queued writes can still be used with serial CAN adapters. However, the serial adapter may add its own buffering and timing behaviour. For high-throughput Linux deployments, SocketCAN remains the preferred option.

Message Handling Model

Frames are read continuously from the bus
No acknowledgement or retransmission is performed by the CAN transport
Unknown frames may be forwarded as raw payloads, depending on the configured protocol
Decoding and routing are handled by the configured protocol layer
Outbound writes may be queued and rate-limited
Multi-frame outbound protocol messages are queued as logical messages

The server does not throttle reads. If the inbound bus is saturated, that is a bus condition, not a receiver-side flow-control mechanism.

Security Notes

CAN bus has no native authentication or encryption
Physical access equals network access
Use isolated networks or gateways where required
Security must be enforced at higher protocol layers or externally
Bridging from authenticated protocols into CAN should use queue limits to avoid allowing remote clients to flood the bus

Operational Notes

Bus speed and topology define CAN throughput
CPU usage scales with frame rate and decode cost
Multiple consumers can safely read the same SocketCAN interface
Serial CAN devices may not support multiple independent consumers
MapsMessaging does not interfere with arbitration or timing
Queued writes pace outbound traffic before it reaches the CAN interface
Serial adapters may impose buffering or framing limits
Adapter compatibility depends on the serial protocol, not just the physical CAN interface
For NMEA 2000, queue depth should be sized in logical messages, not individual CAN frames
Reducing maxBusUsagePercent lowers MapsMessaging outbound bus share but increases queue drain time
Increasing queueDepth absorbs larger bursts but can increase latency for older queued messages

When NOT to Use CAN Bus

Avoid CAN bus when:

Payloads exceed CAN frame limits
Remote access is required
Encryption or authentication is mandatory
The data source cannot tolerate packet loss
The application expects TCP-style back-pressure or delivery guarantees

Choose CAN bus when you want reality, not comfort.

Features​

Supported CAN Interfaces​

When to Use CAN Bus​

When to Use Serial CAN​

Transport Characteristics​

Endpoint Usage​

SocketCAN Example​

SocketCAN Example with Queued Writes​

Serial CAN Example​

Notes​

Queued Write Configuration​

Configuration Fields​

Queue Full Policies​

Controlled Bus Usage​

What Is Controlled​

Serial CAN Behaviour​

Message Handling Model​

Security Notes​

Operational Notes​

When NOT to Use CAN Bus​