can_tx_message_handler.c File Reference

Implementation of message handlers for CAN transmit operations. More...

Functions
void	CanTxMessageHandler_initialize (const interface_can_tx_message_handler_t *interface_can_tx_message_handler)
	Stores the dependency-injection interface pointer.
bool	CanTxMessageHandler_datagram_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Transmits one datagram CAN frame, selecting ONLY/FIRST/MIDDLE/LAST automatically.
bool	CanTxMessageHandler_unaddressed_msg_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Transmits one unaddressed (broadcast) OpenLCB CAN frame.
bool	CanTxMessageHandler_addressed_msg_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Transmits one addressed OpenLCB CAN frame, selecting ONLY/FIRST/MIDDLE/LAST automatically.
bool	CanTxMessageHandler_stream_frame (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg_worker, uint16_t *openlcb_start_index)
	Stream transmit handler — not yet implemented, returns true as placeholder.
bool	CanTxMessageHandler_can_frame (can_msg_t *can_msg)
	Transmits a pre-built raw can_msg_t directly to the hardware.

Detailed Description

Implementation of message handlers for CAN transmit operations.

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.

Converts OpenLCB messages to CAN frames with proper fragmentation and framing-bit encoding 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

)

Stores the dependency-injection interface pointer.

Registers the dependency-injection interface for this module.

CanTxMessageHandler_datagram_frame()

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

Transmits one datagram CAN frame, selecting ONLY/FIRST/MIDDLE/LAST automatically.

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_unaddressed_msg_frame()

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

Transmits one unaddressed (broadcast) OpenLCB CAN 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_addressed_msg_frame()

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

Transmits one addressed OpenLCB CAN frame, selecting ONLY/FIRST/MIDDLE/LAST automatically.

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_stream_frame()

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

Stream transmit handler — not yet implemented, returns true as placeholder.

Placeholder for stream protocol transmit (not yet implemented).

CanTxMessageHandler_can_frame()

bool CanTxMessageHandler_can_frame

(

can_msg_t *

can_msg

)

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