can_utilities.h File Reference

Utility functions for manipulating can_msg_t frame buffers. More...

Go to the source code of this file.

Functions
void	CanUtilities_clear_can_message (can_msg_t *can_msg)
	Clears identifier, payload_count, and all payload bytes in a can_msg_t.
void	CanUtilities_load_can_message (can_msg_t *can_msg, uint32_t identifier, uint8_t payload_size, uint8_t byte1, uint8_t byte2, uint8_t byte3, uint8_t byte4, uint8_t byte5, uint8_t byte6, uint8_t byte7, uint8_t byte8)
	Loads identifier, payload size, and all 8 data bytes into a can_msg_t.
uint8_t	CanUtilities_copy_node_id_to_payload (can_msg_t *can_msg, uint64_t node_id, uint8_t start_offset)
	Copies a 48-bit node_id_t into 6 payload bytes starting at start_offset.
uint8_t	CanUtilities_copy_openlcb_payload_to_can_payload (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg, uint16_t openlcb_start_index, uint8_t can_start_index)
	Copies payload bytes from an openlcb_msg_t into a can_msg_t.
uint8_t	CanUtilities_append_can_payload_to_openlcb_payload (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg, uint8_t can_start_index)
	Appends CAN payload bytes to the end of an openlcb_msg_t payload.
uint8_t	CanUtilities_copy_64_bit_to_can_message (can_msg_t *can_msg, uint64_t data)
	Copies a 64-bit value into all 8 payload bytes of a can_msg_t (big-endian).
uint8_t	CanUtilities_copy_can_message (can_msg_t *can_msg_source, can_msg_t *can_msg_target)
	Copies identifier and valid payload bytes from source to target can_msg_t.
node_id_t	CanUtilities_extract_can_payload_as_node_id (can_msg_t *can_msg)
	Reads payload bytes 0-5 and returns them as a 48-bit node_id_t (big-endian).
uint16_t	CanUtilities_extract_source_alias_from_can_identifier (can_msg_t *can_msg)
	Returns the 12-bit source alias from bits 0-11 of the CAN identifier.
uint16_t	CanUtilities_extract_dest_alias_from_can_message (can_msg_t *can_msg)
	Returns the 12-bit destination alias from the appropriate location in a can_msg_t.
uint16_t	CanUtilities_convert_can_mti_to_openlcb_mti (can_msg_t *can_msg)
	Converts the CAN frame MTI bits to the corresponding 16-bit OpenLCB MTI.
uint8_t	CanUtilities_count_nulls_in_payloads (openlcb_msg_t *openlcb_msg, can_msg_t *can_msg)
	Counts NULL (0x00) bytes across both an openlcb_msg_t and a can_msg_t payload.
bool	CanUtilities_is_openlcb_message (can_msg_t *can_msg)
	Returns true if the CAN frame carries an OpenLCB message (bit 27 set).

Detailed Description

Utility functions for manipulating can_msg_t frame buffers.

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.

Includes functions for clearing, loading, copying, and extracting data from CAN frames. Also provides MTI conversion and framing-bit helpers used by both the Rx and Tx paths. All functions are stateless — no internal buffers or side effects beyond the pointers passed in.

Author

Jim Kueneman

Date

4 Mar 2026

Function Documentation

CanUtilities_clear_can_message()

void CanUtilities_clear_can_message ( can_msg_t * can_msg )

extern

Clears identifier, payload_count, and all payload bytes in a can_msg_t.

CanUtilities_load_can_message()

void CanUtilities_load_can_message ( can_msg_t * can_msg, uint32_t identifier, uint8_t payload_size, uint8_t byte1, uint8_t byte2, uint8_t byte3, uint8_t byte4, uint8_t byte5, uint8_t byte6, uint8_t byte7, uint8_t byte8 )

extern

Loads identifier, payload size, and all 8 data bytes into a can_msg_t.

All 8 byte parameters must be provided even if payload_size is less than 8.

Parameters

can_msg	Destination buffer.
identifier	29-bit CAN extended identifier.
payload_size	Number of valid payload bytes (0-8).
byte1	Payload byte 1.
byte2	Payload byte 2.
byte3	Payload byte 3.
byte4	Payload byte 4.
byte5	Payload byte 5.
byte6	Payload byte 6.
byte7	Payload byte 7.
byte8	Payload byte 8.

Warning

NULL can_msg causes undefined behavior.

* @param can_msg      Destination buffer.
* @param identifier   29-bit CAN extended identifier.
* @param payload_size Number of valid payload bytes (0-8).
* @param byte1..byte8 Payload bytes in order.
* 

CanUtilities_copy_node_id_to_payload()

uint8_t CanUtilities_copy_node_id_to_payload ( can_msg_t * can_msg, uint64_t node_id, uint8_t start_offset )

extern

Copies a 48-bit node_id_t into 6 payload bytes starting at start_offset.

Updates payload_count to start_offset + 6. Valid start_offset range: 0-2 (must fit 6 bytes into the 8-byte payload).

Parameters

can_msg	Destination buffer.
node_id	48-bit node_id_t to copy.
start_offset	Byte position in payload to begin writing (0-2).

Returns

Bytes written (start_offset + 6), or 0 if start_offset is out of range.

See also

CanUtilities_extract_can_payload_as_node_id

Copies a 48-bit node_id_t into 6 payload bytes starting at start_offset.

Algorithm:

1. Validate start_offset <= 2; return 0 if invalid.
2. Set payload_count to 6 + start_offset.
3. Write 6 bytes MSB-first from node_id into payload[start_offset..start_offset+5].
4. Return payload_count.

* @param can_msg      Destination buffer.
* @param node_id      48-bit @ref node_id_t to copy.
* @param start_offset Byte position in payload to begin writing (0-2).
* 

Returns

Bytes written (start_offset + 6), or 0 if start_offset is out of range.

See also

CanUtilities_extract_can_payload_as_node_id

CanUtilities_copy_openlcb_payload_to_can_payload()

uint8_t CanUtilities_copy_openlcb_payload_to_can_payload ( openlcb_msg_t * openlcb_msg, can_msg_t * can_msg, uint16_t openlcb_start_index, uint8_t can_start_index )

extern

Copies payload bytes from an openlcb_msg_t into a can_msg_t.

Used to fragment a large OpenLCB payload across multiple CAN frames. Updates can_msg payload_count to reflect total bytes written.

Parameters

openlcb_msg	Source OpenLCB message.
can_msg	Destination CAN frame buffer.
openlcb_start_index	Starting index in the OpenLCB payload.
can_start_index	Starting index in the CAN payload (0 or 2).

Returns

Number of bytes copied.

See also

CanUtilities_append_can_payload_to_openlcb_payload

Algorithm:

1. Return 0 if openlcb_msg payload_count is 0.
2. Copy from openlcb_msg->payload[openlcb_start_index] into can_msg->payload[can_start_index..7].
3. Stop when either buffer is exhausted.
4. Set can_msg->payload_count to can_start_index + bytes copied.
5. Return bytes copied.

* @param openlcb_msg         Source OpenLCB message.
* @param can_msg             Destination CAN frame buffer.
* @param openlcb_start_index Starting index in the OpenLCB payload.
* @param can_start_index     Starting index in the CAN payload (0 or 2).
* 

Returns

Number of bytes copied.

See also

CanUtilities_append_can_payload_to_openlcb_payload

CanUtilities_append_can_payload_to_openlcb_payload()

uint8_t CanUtilities_append_can_payload_to_openlcb_payload ( openlcb_msg_t * openlcb_msg, can_msg_t * can_msg, uint8_t can_start_index )

extern

Appends CAN payload bytes to the end of an openlcb_msg_t payload.

Used to reassemble multi-frame CAN messages. Stops when the OpenLCB buffer capacity is reached. Updates openlcb_msg payload_count.

Parameters

openlcb_msg	Destination OpenLCB message.
can_msg	Source CAN frame.
can_start_index	Starting index in the CAN payload.

Returns

Number of bytes copied.

Warning

Buffer overflow is silently truncated — ensure buffer type fits expected payload.

See also

CanUtilities_copy_openlcb_payload_to_can_payload

Algorithm:

1. Get OpenLCB buffer capacity from payload_type.
2. Copy can_msg->payload[can_start_index..payload_count-1] into openlcb_msg payload.
3. Stop when openlcb_msg is full.
4. Return number of bytes copied.

* @param openlcb_msg     Destination OpenLCB message.
* @param can_msg         Source CAN frame.
* @param can_start_index Starting index in the CAN payload.
* 

Returns

Number of bytes copied.

Warning

Overflow is silently truncated when the OpenLCB buffer is full.

See also

CanUtilities_copy_openlcb_payload_to_can_payload

CanUtilities_copy_64_bit_to_can_message()

uint8_t CanUtilities_copy_64_bit_to_can_message ( can_msg_t * can_msg, uint64_t data )

extern

Copies a 64-bit value into all 8 payload bytes of a can_msg_t (big-endian).

Always sets payload_count to 8.

Parameters

can_msg	Destination buffer.
data	64-bit value (e.g. Event ID).

Returns

Always 8.

Copies a 64-bit value into all 8 payload bytes of a can_msg_t (big-endian).

* @param can_msg Destination buffer.
* @param data    64-bit value (e.g. Event ID).
* 

Returns

Always 8.

CanUtilities_copy_can_message()

uint8_t CanUtilities_copy_can_message ( can_msg_t * can_msg_source, can_msg_t * can_msg_target )

extern

Copies identifier and valid payload bytes from source to target can_msg_t.

Does not copy state flags (allocated). Target payload_count is set to match source.

Parameters

can_msg_source	Source buffer.
can_msg_target	Destination buffer.

Returns

Number of payload bytes copied.

Does not copy state flags. Target payload_count is set to match source.

* @param can_msg_source Source buffer.
* @param can_msg_target Destination buffer.
* 

Returns

Number of payload bytes copied.

CanUtilities_extract_can_payload_as_node_id()

node_id_t CanUtilities_extract_can_payload_as_node_id ( can_msg_t * can_msg )

extern

Reads payload bytes 0-5 and returns them as a 48-bit node_id_t (big-endian).

Parameters

can_msg

Source buffer. Must have at least 6 valid payload bytes.

Returns

48-bit node_id_t.

See also

CanUtilities_copy_node_id_to_payload

* @param can_msg Source buffer. Must have at least 6 valid payload bytes.
* 

Returns

48-bit node_id_t.

See also

CanUtilities_copy_node_id_to_payload

CanUtilities_extract_source_alias_from_can_identifier()

uint16_t CanUtilities_extract_source_alias_from_can_identifier ( can_msg_t * can_msg )

extern

Returns the 12-bit source alias from bits 0-11 of the CAN identifier.

Parameters

can_msg

Source buffer.

Returns

Source alias (0x000-0xFFF). Valid range is 0x001-0xFFF.

See also

CanUtilities_extract_dest_alias_from_can_message

* @param can_msg Source buffer.
* 

Returns

Source alias (0x000-0xFFF).

See also

CanUtilities_extract_dest_alias_from_can_message

CanUtilities_extract_dest_alias_from_can_message()

uint16_t CanUtilities_extract_dest_alias_from_can_message ( can_msg_t * can_msg )

extern

Returns the 12-bit destination alias from the appropriate location in a can_msg_t.

Addressed messages carry the destination in payload bytes 0-1; datagrams carry it in the identifier. Returns 0 for global (broadcast) frames.

Parameters

can_msg

Source buffer.

Returns

Destination alias (0x001-0xFFF), or 0 if the frame is global.

See also

CanUtilities_extract_source_alias_from_can_identifier

Algorithm:

1. For standard/stream frames: if MASK_CAN_DEST_ADDRESS_PRESENT is set, read alias from payload[0-1].
2. For datagram frames: extract alias from identifier bits 12-23.
3. Otherwise return 0 (global/broadcast frame).

* @param can_msg Source buffer.
* 

Returns

Destination alias (0x001-0xFFF), or 0 if the frame is global.

See also

CanUtilities_extract_source_alias_from_can_identifier

CanUtilities_convert_can_mti_to_openlcb_mti()

uint16_t CanUtilities_convert_can_mti_to_openlcb_mti ( can_msg_t * can_msg )

extern

Converts the CAN frame MTI bits to the corresponding 16-bit OpenLCB MTI.

Handles multi-frame PCER and datagram special cases. Returns 0 for CAN control frames (CID, RID, AMD, etc.) which have no OpenLCB MTI.

Parameters

can_msg

Source buffer.

Returns

16-bit OpenLCB MTI, or 0 for unrecognised or control frames.

See also

CanUtilities_is_openlcb_message

Algorithm:

1. For standard/stream frames: extract bits 12-23 as MTI; map PCER first/middle/last to MTI_PC_EVENT_REPORT_WITH_PAYLOAD.
2. For any datagram frame type: return MTI_DATAGRAM.
3. Otherwise return 0 (CAN control frames have no OpenLCB MTI).

* @param can_msg Source buffer.
* 

Returns

16-bit OpenLCB MTI, or 0 for control frames.

See also

CanUtilities_is_openlcb_message

CanUtilities_count_nulls_in_payloads()

uint8_t CanUtilities_count_nulls_in_payloads ( openlcb_msg_t * openlcb_msg, can_msg_t * can_msg )

extern

Counts NULL (0x00) bytes across both an openlcb_msg_t and a can_msg_t payload.

Used to detect SNIP message completion (exactly 6 NULLs required).

Parameters

openlcb_msg	OpenLCB message with accumulated SNIP data.
can_msg	Current CAN frame being appended.

Returns

Total NULL byte count across both payloads.

Counts NULL (0x00) bytes across both an openlcb_msg_t and a can_msg_t payload.

Used to detect SNIP message completion (exactly 6 NULLs required).

* @param openlcb_msg OpenLCB message with accumulated SNIP data.
* @param can_msg     Current CAN frame being appended.
* 

Returns

Total NULL byte count across both payloads.

CanUtilities_is_openlcb_message()

bool CanUtilities_is_openlcb_message ( can_msg_t * can_msg )

extern

Returns true if the CAN frame carries an OpenLCB message (bit 27 set).

CAN control frames (CID, RID, AMD, AME, AMR) return false.

Parameters

can_msg

Source buffer.

Returns

true for OpenLCB message frames, false for CAN-only control frames.

See also

CanUtilities_convert_can_mti_to_openlcb_mti

Returns true if the CAN frame carries an OpenLCB message (bit 27 set).