Implementation of the sbgECom binary communication protocol. More...

#include <sbgCommon.h>
#include <interfaces/sbgInterface.h>
#include <streamBuffer/sbgStreamBuffer.h>

Data Structures
struct	_SbgEComProtocolPayload

struct	_SbgEComProtocol

Macros
#define	SBG_ECOM_MAX_BUFFER_SIZE (4096)

#define	SBG_ECOM_MAX_PAYLOAD_SIZE (4086)

#define	SBG_ECOM_MAX_EXTENDED_PAYLOAD_SIZE (4081)

#define	SBG_ECOM_SYNC_1 (0xFF)

#define	SBG_ECOM_SYNC_2 (0x5A)

#define	SBG_ECOM_ETX (0x33)

#define	SBG_ECOM_RX_TIME_OUT (450)

Typedefs
typedef struct _SbgEComProtocol	SbgEComProtocol

typedef void(*	SbgEComProtocolFrameCb) (SbgEComProtocol pProtocol, uint8_t msgClass, uint8_t msgId, SbgStreamBuffer pReceivedFrame, void *pUserArg)

typedef struct _SbgEComProtocolPayload	SbgEComProtocolPayload

Functions
void	sbgEComProtocolPayloadConstruct (SbgEComProtocolPayload *pPayload)

void	sbgEComProtocolPayloadDestroy (SbgEComProtocolPayload *pPayload)

const void *	sbgEComProtocolPayloadGetBuffer (const SbgEComProtocolPayload *pPayload)

size_t	sbgEComProtocolPayloadGetSize (const SbgEComProtocolPayload *pPayload)

void *	sbgEComProtocolPayloadMoveBuffer (SbgEComProtocolPayload *pPayload)

SbgErrorCode	sbgEComProtocolInit (SbgEComProtocol pProtocol, SbgInterface pInterface)

SbgErrorCode	sbgEComProtocolClose (SbgEComProtocol *pProtocol)

SbgErrorCode	sbgEComProtocolPurgeIncoming (SbgEComProtocol *pProtocol)

SbgErrorCode	sbgEComProtocolSend (SbgEComProtocol pProtocol, uint8_t msgClass, uint8_t msg, const void pData, size_t size)

SbgErrorCode	sbgEComProtocolReceive (SbgEComProtocol pProtocol, uint8_t pMsgClass, uint8_t pMsgId, void pData, size_t *pSize, size_t maxSize)

SbgErrorCode	sbgEComProtocolReceive2 (SbgEComProtocol pProtocol, uint8_t pMsgClass, uint8_t pMsgId, SbgEComProtocolPayload pPayload)

void	sbgEComProtocolSetOnFrameReceivedCb (SbgEComProtocol pProtocol, SbgEComProtocolFrameCb pOnFrameReceivedCb, void pUserArg)

SbgErrorCode	sbgEComStartFrameGeneration (SbgStreamBuffer pOutputStream, uint8_t msgClass, uint8_t msg, size_t pStreamCursor)

SbgErrorCode	sbgEComFinalizeFrameGeneration (SbgStreamBuffer *pOutputStream, size_t streamCursor)

Detailed Description

Implementation of the sbgECom binary communication protocol.

Author: SBG Systems

Date: 06 February 2013

You will find below, the frame definition used by Ekinox devices.

Frame structure
Fields	SYNC 1	SYNC 2	CMD	LEN	DATA	CRC	ETX
Size in bytes	1	1	2	2	(0-4086)	2	1
Value	0xFF	0x5A	?	?	?	?	0x33

Size in bytes indicates the size of the data field.
The minimum frame size is 9 bytes and the maximum is 512 bytes.

The CRC is calculated on the whole frame without:
SYNC STX CRC and ETX fields.

Copyright: Copyright (C) 2022, SBG Systems SAS. All rights reserved.

License

The MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Macro Definition Documentation

◆ SBG_ECOM_MAX_BUFFER_SIZE

#define SBG_ECOM_MAX_BUFFER_SIZE (4096)

Maximum reception buffer size in bytes.

◆ SBG_ECOM_MAX_PAYLOAD_SIZE

#define SBG_ECOM_MAX_PAYLOAD_SIZE (4086)

Maximum payload size in bytes.

◆ SBG_ECOM_MAX_EXTENDED_PAYLOAD_SIZE

#define SBG_ECOM_MAX_EXTENDED_PAYLOAD_SIZE (4081)

Maximum payload size in an extended frame, in bytes.

◆ SBG_ECOM_SYNC_1

#define SBG_ECOM_SYNC_1 (0xFF)

First synchronization char of the frame.

◆ SBG_ECOM_SYNC_2

#define SBG_ECOM_SYNC_2 (0x5A)

Second synchronization char of the frame.

◆ SBG_ECOM_ETX

#define SBG_ECOM_ETX (0x33)

End of frame byte.

◆ SBG_ECOM_RX_TIME_OUT

#define SBG_ECOM_RX_TIME_OUT (450)

Default time out for new frame reception.

Typedef Documentation

◆ SbgEComProtocol

typedef struct _SbgEComProtocol SbgEComProtocol

Forward declaration.

◆ SbgEComProtocolFrameCb

typedef void(* SbgEComProtocolFrameCb) (SbgEComProtocol *pProtocol, uint8_t msgClass, uint8_t msgId, SbgStreamBuffer *pReceivedFrame, void *pUserArg)

Function called each time a valid sbgECom frame is received.

This callback is used to intercept a valid and full sbgECom frame to easily intercept and store raw stream.

Parameters

[in]	pProtocol	sbgECom protocol handle instance.
[in]	msgClass	Received frame message class.
[in]	msgId	Received frame message id.
[out]	pReceivedFrame	Stream buffer initialized for read operations on the whole frame data.
[in]	pUserArg	Optional user supplied argument.

◆ SbgEComProtocolPayload

typedef struct _SbgEComProtocolPayload SbgEComProtocolPayload

Payload.

This class is used to abstract whether some payload is received from a single or multiple frames.

Function Documentation

◆ sbgEComProtocolPayloadConstruct()

void sbgEComProtocolPayloadConstruct ( SbgEComProtocolPayload * pPayload )

Payload constructor.

Parameters

[in] pPayload Payload.

◆ sbgEComProtocolPayloadDestroy()

void sbgEComProtocolPayloadDestroy ( SbgEComProtocolPayload * pPayload )

Payload destructor.

Parameters

[in] pPayload Payload.

◆ sbgEComProtocolPayloadGetBuffer()

const void* sbgEComProtocolPayloadGetBuffer ( const SbgEComProtocolPayload * pPayload )

Get the buffer of a payload.

Parameters

[in] pPayload Payload.

Returns: Payload buffer.

◆ sbgEComProtocolPayloadGetSize()

size_t sbgEComProtocolPayloadGetSize ( const SbgEComProtocolPayload * pPayload )

Get the size of a payload buffer.

Parameters

[in] pPayload Payload.

Returns: Size of the payload buffer, in bytes.

◆ sbgEComProtocolPayloadMoveBuffer()

void* sbgEComProtocolPayloadMoveBuffer ( SbgEComProtocolPayload * pPayload )

Move the buffer of a payload.

If successful, the ownership of the buffer is passed to the caller. Otherwise, the payload is unchanged.

The buffer must be released with free() once unused.

Parameters

[in] pPayload Payload.

Returns: Payload buffer if successful, NULL otherwise.

◆ sbgEComProtocolInit()

SbgErrorCode sbgEComProtocolInit	(	SbgEComProtocol *	pProtocol,
		SbgInterface *	pInterface
	)

Initialize the protocol system used to communicate with the product and return the created handle.

Parameters

[in]	pProtocol	Protocol instance to construct.
[in]	pInterface	Interface to use for read/write operations.

Returns: SBG_NO_ERROR if we have initialized the protocol system.

◆ sbgEComProtocolClose()

SbgErrorCode sbgEComProtocolClose ( SbgEComProtocol * pProtocol )

Close the protocol system.

Parameters

[in] pProtocol A valid protocol instance.

Returns: SBG_NO_ERROR if we have closed and released the protocol system.

◆ sbgEComProtocolPurgeIncoming()

SbgErrorCode sbgEComProtocolPurgeIncoming ( SbgEComProtocol * pProtocol )

Purge the interface rx buffer as well as the sbgECom rx work buffer.

For example, if the program flow has been interrupted, this method can be helpful to discard all trash received data.

WARNING: This method is blocking for 100ms and actively tries to read incoming data.

Parameters

[in] pProtocol A valid protocol instance.

Returns: SBG_NO_ERROR if the incoming data has been purged successfully.

◆ sbgEComProtocolSend()

SbgErrorCode sbgEComProtocolSend	(	SbgEComProtocol *	pProtocol,
		uint8_t	msgClass,
		uint8_t	msg,
		const void *	pData,
		size_t	size
	)

Send data.

If the size is SBG_ECOM_MAX_PAYLOAD_SIZE or less, the data is sent in a single frame. Otherwise, is it fragmented into multiple extended frames, each sent in order, which may block.

Parameters

[in]	pProtocol	A valid protocol instance.
[in]	msgClass	Message class.
[in]	msg	Message ID.
[in]	pData	Data buffer.
[in]	size	Data buffer size, in bytes.

Returns: SBG_NO_ERROR if the frame has been sent.

◆ sbgEComProtocolReceive()

SbgErrorCode sbgEComProtocolReceive	(	SbgEComProtocol *	pProtocol,
		uint8_t *	pMsgClass,
		uint8_t *	pMsgId,
		void *	pData,
		size_t *	pSize,
		size_t	maxSize
	)

Receive a frame.

Parameters

[in]	pProtocol	A valid protocol instance.
[out]	pMsgClass	Message class, may be NULL.
[out]	pMsgId	Message ID, may be NULL.
[out]	pData	Data buffer.
[out]	pSize	Number of bytes received.
[in]	maxSize	Data buffer size, in bytes.

Returns: SBG_NO_ERROR if successful, SBG_NOT_READY if no complete frame has been received, SBG_BUFFER_OVERFLOW if the payload of the received frame couldn't fit into the data buffer.

◆ sbgEComProtocolReceive2()

SbgErrorCode sbgEComProtocolReceive2	(	SbgEComProtocol *	pProtocol,
		uint8_t *	pMsgClass,
		uint8_t *	pMsgId,
		SbgEComProtocolPayload *	pPayload
	)

Receive a frame.

This function is equivalent to sbgEComProtocolReceive() with two exceptions :

the use of a payload object allows handling payloads not limited by the size of a user-provided buffer
the payload object allows direct access to the protocol work buffer to avoid an extra copy per call

Any allocated resource associated with the given payload is released when calling this function.

Because the payload buffer may directly refer to the protocol work buffer on return, it is only valid until the next attempt to receive a frame, with any of the receive functions.

Parameters

[in]	pProtocol	A valid protocol instance.
[out]	pMsgClass	Message class, may be NULL.
[out]	pMsgId	Message ID, may be NULL.
[out]	pPayload	Payload.

Returns: SBG_NO_ERROR if successful, SBG_NOT_READY if no complete frame has been received.

◆ sbgEComProtocolSetOnFrameReceivedCb()

void sbgEComProtocolSetOnFrameReceivedCb	(	SbgEComProtocol *	pProtocol,
		SbgEComProtocolFrameCb	pOnFrameReceivedCb,
		void *	pUserArg
	)

Define the optional function called each time a valid sbgECom frame is received.

This callback is useful to intercept raw sbgECom frames at a low level. You can call this method with NULL parameters to uninstall the callback.

EXPERIMENTAL: This handler is still experimental and API may change in next sbgECom versions.

Parameters

[in]	pHandle	A valid protocol instance.
[in]	pOnFrameReceivedCb	Function to call each time a valid sbgECom frame is received.
[in]	pUserArg	Optional user argument that will be passed to the callback method.

◆ sbgEComStartFrameGeneration()

SbgErrorCode sbgEComStartFrameGeneration	(	SbgStreamBuffer *	pOutputStream,
		uint8_t	msgClass,
		uint8_t	msg,
		size_t *	pStreamCursor
	)

Initialize an output stream for an sbgECom frame generation.

This function is helpful to avoid memory copy compared to sbgEComProtocolSend one.

Only standard frames may be sent with this function.

Parameters

[in]	pOutputStream	Pointer to an allocated and initialized output stream.
[in]	msgClass	Message class.
[in]	msg	Message ID.
[out]	pStreamCursor	The initial output stream cursor that thus points to the beginning of the generated message. This value should be passed to sbgEComFinalizeFrameGeneration for correct operations.

Returns: SBG_NO_ERROR in case of good operation.

◆ sbgEComFinalizeFrameGeneration()

SbgErrorCode sbgEComFinalizeFrameGeneration	(	SbgStreamBuffer *	pOutputStream,
		size_t	streamCursor
	)

Finalize an output stream that has been initialized with sbgEComStartFrameGeneration.

At return, the output stream buffer should point at the end of the generated message. You can thus easily create consecutive SBG_ECOM_LOGS with these methods.

Parameters

[in]	pOutputStream	Pointer to an allocated and initialized output stream.
[in]	streamCursor	Position in the stream buffer of the generated message first byte. This value is returned by sbgEComStartFrameGeneration and is mandatory for correct operations.

Returns: SBG_NO_ERROR in case of good operation.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SBG_ECOM_MAX_BUFFER_SIZE

◆ SBG_ECOM_MAX_PAYLOAD_SIZE

◆ SBG_ECOM_MAX_EXTENDED_PAYLOAD_SIZE

◆ SBG_ECOM_SYNC_1

◆ SBG_ECOM_SYNC_2

◆ SBG_ECOM_ETX

◆ SBG_ECOM_RX_TIME_OUT

Typedef Documentation

◆ SbgEComProtocol

◆ SbgEComProtocolFrameCb

◆ SbgEComProtocolPayload

Function Documentation

◆ sbgEComProtocolPayloadConstruct()

◆ sbgEComProtocolPayloadDestroy()

◆ sbgEComProtocolPayloadGetBuffer()

◆ sbgEComProtocolPayloadGetSize()

◆ sbgEComProtocolPayloadMoveBuffer()

◆ sbgEComProtocolInit()

◆ sbgEComProtocolClose()

◆ sbgEComProtocolPurgeIncoming()

◆ sbgEComProtocolSend()

◆ sbgEComProtocolReceive()

◆ sbgEComProtocolReceive2()

◆ sbgEComProtocolSetOnFrameReceivedCb()

◆ sbgEComStartFrameGeneration()

◆ sbgEComFinalizeFrameGeneration()