openlcb_gridconnect.c File Reference

Implementation of GridConnect protocol conversion. More...

Functions
bool	OpenLcbGridConnect_copy_out_gridconnect_when_done (uint8_t next_byte, gridconnect_buffer_t *gridconnect_buffer)
	Processes incoming GridConnect byte stream and extracts complete message.
void	OpenLcbGridConnect_to_can_msg (gridconnect_buffer_t *gridconnect_buffer, can_msg_t *can_msg)
	Converts a GridConnect message string to a CAN message structure.
void	OpenLcbGridConnect_from_can_msg (gridconnect_buffer_t *gridconnect_buffer, can_msg_t *can_msg)
	Converts a CAN message structure to GridConnect format string.

Detailed Description

Implementation of GridConnect protocol conversion.

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.

This module implements the GridConnect protocol, a human-readable ASCII encoding of CAN bus messages. The protocol is widely used in OpenLCB systems for serial and TCP/IP communication, debugging, and bridging applications.

Implementation features:

• Stateful streaming parser for byte-by-byte reception
• Automatic error detection and recovery
• Bidirectional conversion between CAN and GridConnect formats
• No dynamic memory allocation
• Single-threaded design (not thread-safe)

The parser state machine handles:

• Message synchronization (finding ':X' start sequence)
• Hexadecimal validation for identifier and data
• Length validation (8-char identifier, even data byte count)
• Automatic error recovery by resetting to start state

GridConnect Protocol Format:

:X<8-hex-ID>N<hex-data>;
 
Example: :X19170640N0501010107015555;
  :       - Start delimiter
  X       - Extended frame indicator
  19170640 - 29-bit CAN identifier (8 hex chars)
  N       - Normal priority flag
  050101... - Data bytes (2 hex chars per byte)
  ;       - End delimiter

Author

Jim Kueneman

Date

4 Mar 2026

See also

openlcb_gridconnect.h - Public interface

can_types.h - CAN message structures

Function Documentation

OpenLcbGridConnect_copy_out_gridconnect_when_done()

bool OpenLcbGridConnect_copy_out_gridconnect_when_done	(	uint8_t	next_byte,
		gridconnect_buffer_t *	gridconnect_buffer )

Processes incoming GridConnect byte stream and extracts complete message.

Feeds one byte into the streaming GridConnect parser.

Algorithm: Implements a three-state parser that processes GridConnect protocol data one byte at a time:

1. SYNC_START: Wait for 'X'/'x', store ':X' prefix, advance to FIND_HEADER
2. SYNC_FIND_HEADER: Collect 8 hex chars for CAN ID, expect 'N' at position 10
3. SYNC_FIND_DATA: Collect hex data until ';', validate even count, copy to output

Use cases:

• Serial port receive interrupt handlers calling once per received byte
• TCP/IP socket data processing with partial packet reception

* @param next_byte Next byte from the incoming GridConnect stream
* @param gridconnect_buffer Pointer to buffer where complete message will be stored
* 

Returns

true when a complete valid GridConnect message has been extracted

false while still collecting data or after recovering from errors

Warning

NOT thread-safe — uses static variables for parser state

See also

OpenLcbGridConnect_to_can_msg - Convert extracted GridConnect to CAN message

OpenLcbGridConnect_to_can_msg()

void OpenLcbGridConnect_to_can_msg	(	gridconnect_buffer_t *	gridconnect_buffer,
		can_msg_t *	can_msg )

Converts a GridConnect message string to a CAN message structure.

Converts a validated GridConnect string to a can_msg_t.

Algorithm:

1. Validate message length is at least GRIDCONNECT_HEADER_LEN
2. Extract 8-char hex identifier via strtoul()
3. Calculate payload byte count from remaining hex characters
4. Extract data bytes in pairs via strtoul()

Use cases:

• Processing received GridConnect messages from serial/TCP
• Converting logged GridConnect data to CAN for replay

* @param gridconnect_buffer Pointer to GridConnect message buffer (null-terminated)
* @param can_msg Pointer to CAN message structure to populate
* 

Warning

Input must be a valid GridConnect message from the parser

Pointers must NOT be NULL

See also

OpenLcbGridConnect_copy_out_gridconnect_when_done - Extract valid messages

OpenLcbGridConnect_from_can_msg - Reverse conversion

OpenLcbGridConnect_from_can_msg()

void OpenLcbGridConnect_from_can_msg	(	gridconnect_buffer_t *	gridconnect_buffer,
		can_msg_t *	can_msg )

Converts a CAN message structure to GridConnect format string.

Converts a can_msg_t to a null-terminated GridConnect string.

Algorithm:

1. Write ":X" start sequence
2. Format 32-bit CAN identifier as 8-char uppercase hex
3. Append "N" normal priority flag
4. Format each payload byte as 2-char uppercase hex
5. Append ";" terminator

Use cases:

• Transmitting CAN messages over serial/TCP connections
• Logging CAN traffic in human-readable format

* @param gridconnect_buffer Pointer to buffer where GridConnect message will be stored
* @param can_msg Pointer to source CAN message structure to convert
* 

Warning

Pointers must NOT be NULL

Payload count must not exceed 8

See also

OpenLcbGridConnect_to_can_msg - Reverse conversion