can_tx_message_handler.h File Reference

Message handlers that convert OpenLCB messages to outgoing CAN frames. More...

Go to the source code of this file.

Data Structures
struct	interface_can_tx_message_handler_t
	Dependency-injection interface for the CAN transmit message handlers. More...

Functions
void	CanTxMessageHandler_initialize (const interface_can_tx_message_handler_t *interface_can_tx_message_handler)
	Registers the dependency-injection interface for this module.
bool	CanTxMessageHandler_addressed_msg_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Transmits one CAN frame for an addressed openlcb_msg_t.
bool	CanTxMessageHandler_unaddressed_msg_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Transmits one CAN frame for an unaddressed (broadcast) openlcb_msg_t.
bool	CanTxMessageHandler_datagram_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Transmits one CAN frame for a datagram openlcb_msg_t (up to 72 bytes total).
bool	CanTxMessageHandler_stream_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Placeholder for stream protocol transmit (not yet implemented).
bool	CanTxMessageHandler_can_frame (can_msg_t *can_msg)
	Transmits a pre-built raw can_msg_t directly to the hardware.

Detailed Description

Message handlers that convert OpenLCB messages to outgoing CAN frames.

Copyright

Copyright (c) 2024, Jim Kueneman All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Handles fragmentation and framing-bit encoding for addressed, unaddressed, datagram, stream, and raw CAN frame types per the OpenLCB CAN Frame Transfer Standard.

Author

Jim Kueneman

Date

4 Mar 2026

Function Documentation

CanTxMessageHandler_initialize()

void CanTxMessageHandler_initialize ( const interface_can_tx_message_handler_t * interface_can_tx_message_handler )

extern

Registers the dependency-injection interface for this module.

Parameters

interface_can_tx_message_handler

Pointer to a populated interface_can_tx_message_handler_t. Must remain valid for the lifetime of the application.

Warning

NOT thread-safe - call during single-threaded initialization only.

transmit_can_frame must not be NULL.

See also

CanTxStatemachine_initialize

Registers the dependency-injection interface for this module.

CanTxMessageHandler_addressed_msg_frame()

bool CanTxMessageHandler_addressed_msg_frame ( openlcb_msg_t * openlcb_msg, can_msg_t * can_msg_worker, uint16_t * openlcb_start_index )

extern

Transmits one CAN frame for an addressed openlcb_msg_t.

Encodes the destination alias into payload bytes 0-1 with framing flags (ONLY / FIRST / MIDDLE / LAST), copies up to 6 payload bytes, and transmits. On success, advances *openlcb_start_index by the number of bytes sent.

Parameters

openlcb_msg	Source message (dest_alias must be valid).
can_msg_worker	Scratch CAN frame buffer used to build the frame.
openlcb_start_index	Current position in the OpenLCB payload; updated on success.

Returns

true if the frame was transmitted, false on hardware failure.

See also

CanTxMessageHandler_unaddressed_msg_frame

Transmits one CAN frame for an addressed openlcb_msg_t.

Algorithm:

1. Write destination alias into payload bytes 0-1.
2. Build the standard-frame identifier (MTI + source alias).
3. Copy up to 6 payload bytes starting at *openlcb_start_index into bytes 2-7.
4. Choose framing bits: ONLY (<= 6 bytes total), FIRST (index < 6), MIDDLE, or LAST.
5. Transmit. On success, advance *openlcb_start_index by bytes copied.
6. Return transmission result.

* @param openlcb_msg          Source message (dest_alias must be valid).
* @param can_msg_worker       Scratch CAN frame buffer.
* @param openlcb_start_index  Current payload position; updated on success.
* 

Returns

true if transmitted, false on hardware failure.

Warning

Index is unchanged on failure — caller must retry.

CanTxMessageHandler_unaddressed_msg_frame()

bool CanTxMessageHandler_unaddressed_msg_frame ( openlcb_msg_t * openlcb_msg, can_msg_t * can_msg_worker, uint16_t * openlcb_start_index )

extern

Transmits one CAN frame for an unaddressed (broadcast) openlcb_msg_t.

All 8 payload bytes are available (no destination alias overhead). Multi-frame unaddressed messages are not currently implemented. On success, advances *openlcb_start_index by the number of bytes sent.

Parameters

openlcb_msg	Source message.
can_msg_worker	Scratch CAN frame buffer.
openlcb_start_index	Current payload position; updated on success.

Returns

true if the frame was transmitted, false on hardware failure.

See also

CanTxMessageHandler_addressed_msg_frame

Transmits one CAN frame for an unaddressed (broadcast) openlcb_msg_t.

Algorithm:

1. If payload fits in one frame (<= 8 bytes): copy payload, build identifier, transmit.
2. On success, advance *openlcb_start_index.
3. Assert on oversized payloads – no standard unaddressed message exceeds 8 bytes. PCER-with-Payload uses dedicated CAN MTIs (FIRST/MIDDLE/LAST), not this path.
4. Return transmission result.

* @param openlcb_msg          Source message (no dest_alias needed).
* @param can_msg_worker       Scratch CAN frame buffer.
* @param openlcb_start_index  Current payload position; updated on success.
* 

Returns

true if transmitted, false on hardware failure or oversized payload.

CanTxMessageHandler_datagram_frame()

bool CanTxMessageHandler_datagram_frame ( openlcb_msg_t * openlcb_msg, can_msg_t * can_msg_worker, uint16_t * openlcb_start_index )

extern

Transmits one CAN frame for a datagram openlcb_msg_t (up to 72 bytes total).

Selects the correct datagram frame type (ONLY / FIRST / MIDDLE / LAST) based on the current payload index and total size. On success, advances *openlcb_start_index by the number of bytes sent.

Parameters

openlcb_msg	Source datagram message.
can_msg_worker	Scratch CAN frame buffer.
openlcb_start_index	Current payload position; updated on success.

Returns

true if the frame was transmitted, false on hardware failure.

See also

CanTxMessageHandler_addressed_msg_frame

Transmits one CAN frame for a datagram openlcb_msg_t (up to 72 bytes total).

Algorithm:

1. Copy up to 8 payload bytes from openlcb_msg into can_msg_worker starting at *openlcb_start_index.
2. Choose frame type: ONLY (total <= 8), FIRST (index < 8), MIDDLE (more data remains), LAST.
3. Transmit. On success, advance *openlcb_start_index by bytes copied.
4. Return transmission result.

* @param openlcb_msg          Source datagram message (max 72 bytes).
* @param can_msg_worker       Scratch CAN frame buffer.
* @param openlcb_start_index  Current payload position; updated on success.
* 

Returns

true if transmitted, false on hardware failure.

Warning

Index is unchanged on failure — caller must retry.

CanTxMessageHandler_stream_frame()

bool CanTxMessageHandler_stream_frame ( openlcb_msg_t * openlcb_msg, can_msg_t * can_msg_worker, uint16_t * openlcb_start_index )

extern

Placeholder for stream protocol transmit (not yet implemented).

Parameters

openlcb_msg	Source stream message.
can_msg_worker	Scratch CAN frame buffer.
openlcb_start_index	Current payload position.

Returns

Always true (no-op placeholder).

Warning

Do not use in production until implemented.

Placeholder for stream protocol transmit (not yet implemented).

CanTxMessageHandler_can_frame()

bool CanTxMessageHandler_can_frame ( can_msg_t * can_msg )

extern

Transmits a pre-built raw can_msg_t directly to the hardware.

No OpenLCB processing — frame must be fully constructed before calling. Used for CAN control frames (CID, RID, AMD) during alias allocation.

Parameters

can_msg

Fully-constructed CAN frame to transmit.

Returns

true if the frame was transmitted, false on hardware failure.

See also

CanLoginMessageHandler_state_load_cid07

CanLoginMessageHandler_state_load_rid

CanLoginMessageHandler_state_load_amd