openlcb_gridconnect.h File Reference

Bidirectional conversion between CAN messages and GridConnect ASCII format. More...

Go to the source code of this file.

Macros
#define	GRIDCONNECT_STATE_SYNC_START   0
	Parser state: Looking for start of GridConnect message (':X' or ':x')
#define	GRIDCONNECT_STATE_SYNC_FIND_HEADER   2
	Parser state: Collecting 8-character hexadecimal CAN identifier.
#define	GRIDCONNECT_STATE_SYNC_FIND_DATA   4
	Parser state: Collecting data bytes until terminator (';')
#define	GRIDCONNECT_IDENTIFIER_START_POS   2
	Position of first character after ':X' prefix (start of identifier)
#define	GRIDCONNECT_IDENTIFIER_LEN   8
	Length of CAN identifier in GridConnect format (8 hex characters)
#define	GRIDCONNECT_NORMAL_FLAG_POS   10
	Position where 'N' appears (after 8-char identifier)
#define	GRIDCONNECT_DATA_START_POS   11
	Position where data bytes start (after ':X', 8-char ID, and 'N')
#define	GRIDCONNECT_HEADER_LEN   12
	Number of characters before data section (used for length calculation)
#define	MAX_GRID_CONNECT_LEN   29
	Max GridConnect string length: :X(8)N(16); + NUL = 29 bytes.

Typedefs
typedef uint8_t	gridconnect_buffer_t[MAX_GRID_CONNECT_LEN]
	Type definition for GridConnect message buffer.

Functions
bool	OpenLcbGridConnect_copy_out_gridconnect_when_done (uint8_t next_byte, gridconnect_buffer_t *gridconnect_buffer)
	Feeds one byte into the streaming GridConnect parser.
void	OpenLcbGridConnect_to_can_msg (gridconnect_buffer_t *gridconnect_buffer, can_msg_t *can_msg)
	Converts a validated GridConnect string to a can_msg_t.
void	OpenLcbGridConnect_from_can_msg (gridconnect_buffer_t *gridconnect_buffer, can_msg_t *can_msg)
	Converts a can_msg_t to a null-terminated GridConnect string.

Detailed Description

Bidirectional conversion between CAN messages and GridConnect ASCII format.

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 between can_msg_t structures and the GridConnect ASCII wire format (:X<8-hex-ID>N<hex-data>;). Includes a streaming byte-at-a-time parser with automatic error recovery for use over serial or TCP/IP links.

Author

Jim Kueneman

Date

4 Mar 2026

Macro Definition Documentation

GRIDCONNECT_STATE_SYNC_START

#define GRIDCONNECT_STATE_SYNC_START   0

Parser state: Looking for start of GridConnect message (':X' or ':x')

GRIDCONNECT_STATE_SYNC_FIND_HEADER

#define GRIDCONNECT_STATE_SYNC_FIND_HEADER   2

Parser state: Collecting 8-character hexadecimal CAN identifier.

GRIDCONNECT_STATE_SYNC_FIND_DATA

#define GRIDCONNECT_STATE_SYNC_FIND_DATA   4

Parser state: Collecting data bytes until terminator (';')

GRIDCONNECT_IDENTIFIER_START_POS

#define GRIDCONNECT_IDENTIFIER_START_POS   2

Position of first character after ':X' prefix (start of identifier)

GRIDCONNECT_IDENTIFIER_LEN

#define GRIDCONNECT_IDENTIFIER_LEN   8

Length of CAN identifier in GridConnect format (8 hex characters)

GRIDCONNECT_NORMAL_FLAG_POS

#define GRIDCONNECT_NORMAL_FLAG_POS   10

Position where 'N' appears (after 8-char identifier)

GRIDCONNECT_DATA_START_POS

#define GRIDCONNECT_DATA_START_POS   11

Position where data bytes start (after ':X', 8-char ID, and 'N')

GRIDCONNECT_HEADER_LEN

#define GRIDCONNECT_HEADER_LEN   12

Number of characters before data section (used for length calculation)

MAX_GRID_CONNECT_LEN

#define MAX_GRID_CONNECT_LEN   29

Max GridConnect string length: :X(8)N(16); + NUL = 29 bytes.

Typedef Documentation

gridconnect_buffer_t

typedef uint8_t gridconnect_buffer_t[MAX_GRID_CONNECT_LEN]

Type definition for GridConnect message buffer.

Function Documentation

OpenLcbGridConnect_copy_out_gridconnect_when_done()

bool OpenLcbGridConnect_copy_out_gridconnect_when_done ( uint8_t next_byte, gridconnect_buffer_t * gridconnect_buffer )

extern

Feeds one byte into the streaming GridConnect parser.

Uses static state — NOT thread-safe, single context only. Malformed input resets the parser automatically.

Parameters

next_byte	Next byte from the incoming stream.
gridconnect_buffer	Destination for the completed message.

Returns

true when a complete, valid GridConnect message is ready.

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 )

extern

Converts a validated GridConnect string to a can_msg_t.

Input must come from the parser; no format validation is done here.

Parameters

gridconnect_buffer	Completed GridConnect string.
can_msg	Destination CAN message.

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 )

extern

Converts a can_msg_t to a null-terminated GridConnect string.

Output is uppercase hex with leading zeros on the 8-char ID.

Parameters

gridconnect_buffer	Destination buffer (>= MAX_GRID_CONNECT_LEN).
can_msg	Source CAN message.

Warning

Payload count must not exceed 8 or buffer overflow will occur.

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