Detailed Description

Frame and validate incoming FusionEngine messages.

This class locates and validates FusionEngine messages within a stream of binary data. Data may be stored in an internally allocated buffer, or in an external buffer supplied by the user.

The callback function provided to SetMessageCallback() will be called each time a complete message is received. Any messages that do not pass the CRC check, or that are too big to be stored in the data buffer, will be discarded.

Example usage:

void MessageReceived(const MessageHeader& header, const void* payload) {
  if (header.message_type == MessageType::POSE) {
    auto& contents = *static_cast<const PoseMessage*>(payload);
    ...
  }
}
 
FusionEngineFramer framer(1024);
framer.SetMessageCallback(MessageReceived);
framer.OnData(my_data, my_data_size);

Definition at line 43 of file fusion_engine_framer.h.

#include <point_one/fusion_engine/parsers/fusion_engine_framer.h>

Public Types
using	MessageCallback = void()(const messages::MessageHeader &, const void )

Public Member Functions
	FusionEngineFramer ()=default
	Construct a framer instance with no buffer allocated. More...

	FusionEngineFramer (const FusionEngineFramer &)=delete

	FusionEngineFramer (FusionEngineFramer &&)=delete

	FusionEngineFramer (size_t capacity_bytes)
	Construct a framer instance with an internally allocated buffer. More...

	FusionEngineFramer (void *buffer, size_t capacity_bytes)
	Construct a framer instance with a user-specified buffer. More...

	~FusionEngineFramer ()

size_t	OnData (const uint8_t *buffer, size_t length_bytes)
	Process incoming data. More...

FusionEngineFramer &	operator= (const FusionEngineFramer &)=delete

FusionEngineFramer &	operator= (FusionEngineFramer &&)=delete

void	Reset ()
	Reset the framer and discard all pending data. More...

void	SetBuffer (void *buffer, size_t capacity_bytes)
	Set the buffer to use for message framing. More...

void	SetMessageCallback (MessageCallback callback)
	Specify a function to be called when a message is framed. More...

void	WarnOnError (bool enabled)
	Enable/disable warnings for CRC and "message too large" failures. More...

Private Types
enum	State { State::SYNC0 = 0, State::SYNC1 = 1, State::HEADER = 2, State::DATA = 3 }

Private Member Functions
void	ClearManagedBuffer ()
	Free the buffer_ if it's being managed internally. More...

int32_t	OnByte (bool quiet)
	Process a single byte. More...

uint32_t	Resync ()
	Perform a resynchronization operation starting at `buffer_[1]`. More...

Private Attributes
uint8_t *	buffer_ {nullptr}

MessageCallback	callback_ = nullptr

uint32_t	capacity_bytes_ {0}

uint32_t	current_message_size_ {0}

bool	is_buffer_managed_ = false

uint32_t	next_byte_index_ {0}

State	state_ {State::SYNC0}

bool	warn_on_error_ = true

Member Typedef Documentation

◆ MessageCallback

using point_one::fusion_engine::parsers::FusionEngineFramer::MessageCallback = void (*)(const messages::MessageHeader&, const void*)

Definition at line 45 of file fusion_engine_framer.h.

Member Enumeration Documentation

◆ State

enum point_one::fusion_engine::parsers::FusionEngineFramer::State

strongprivate

Enumerator
SYNC0
SYNC1
HEADER
DATA

Definition at line 135 of file fusion_engine_framer.h.

Constructor & Destructor Documentation

◆ FusionEngineFramer() [1/5]

point_one::fusion_engine::parsers::FusionEngineFramer::FusionEngineFramer ( )

default

Construct a framer instance with no buffer allocated.

Note: You must call SetBuffer() to assign a buffer, otherwise all incoming data will be discarded.

◆ FusionEngineFramer() [2/5]

point_one::fusion_engine::parsers::FusionEngineFramer::FusionEngineFramer ( size_t capacity_bytes )

inlineexplicit

Construct a framer instance with an internally allocated buffer.

Parameters

capacity_bytes The maximum framing buffer capacity (in bytes).

Definition at line 61 of file fusion_engine_framer.h.

◆ FusionEngineFramer() [3/5]

FusionEngineFramer::FusionEngineFramer	(	void *	buffer,
		size_t	capacity_bytes
	)

Construct a framer instance with a user-specified buffer.

Postcondition: buffer must exist for the lifetime of this instance.

Parameters

buffer	The framing buffer to use. Set to `nullptr` to allocate a buffer internally.
capacity_bytes	The maximum framing buffer capacity (in bytes).

Definition at line 95 of file fusion_engine_framer.cc.

◆ ~FusionEngineFramer()

FusionEngineFramer::~FusionEngineFramer ( )

Definition at line 109 of file fusion_engine_framer.cc.

◆ FusionEngineFramer() [4/5]

point_one::fusion_engine::parsers::FusionEngineFramer::FusionEngineFramer ( const FusionEngineFramer & )

delete

◆ FusionEngineFramer() [5/5]

point_one::fusion_engine::parsers::FusionEngineFramer::FusionEngineFramer ( FusionEngineFramer && )

delete

Member Function Documentation

◆ ClearManagedBuffer()

void FusionEngineFramer::ClearManagedBuffer ( )

private

Free the buffer_ if it's being managed internally.

Definition at line 510 of file fusion_engine_framer.cc.

◆ OnByte()

int32_t FusionEngineFramer::OnByte ( bool quiet )

private

Process a single byte.

Precondition: The byte must be located at buffer_[next_byte_index_ - 1].

Parameters

quiet If true, suppress failure warning messages.

Returns: The total size of all valid, complete messages, 0 if no messages were completed, or <0 CRC or "message too large" error.

Definition at line 195 of file fusion_engine_framer.cc.

◆ OnData()

size_t FusionEngineFramer::OnData	(	const uint8_t *	buffer,
		size_t	length_bytes
	)

Process incoming data.

Parameters

buffer	A buffer containing data to be framed.
length_bytes	The number of bytes to be framed.

Returns: The total size of all valid, complete messages, or 0 if no messages were completed.

Definition at line 155 of file fusion_engine_framer.cc.

◆ operator=() [1/2]

FusionEngineFramer& point_one::fusion_engine::parsers::FusionEngineFramer::operator= ( const FusionEngineFramer & )

delete

◆ operator=() [2/2]

FusionEngineFramer& point_one::fusion_engine::parsers::FusionEngineFramer::operator= ( FusionEngineFramer && )

delete

◆ Reset()

void FusionEngineFramer::Reset ( )

Reset the framer and discard all pending data.

Definition at line 148 of file fusion_engine_framer.cc.

◆ Resync()

uint32_t FusionEngineFramer::Resync ( )

private

Perform a resynchronization operation starting at buffer_[1].

Returns: The total size of all valid, complete messages, or 0 if no messages were completed.

Definition at line 413 of file fusion_engine_framer.cc.

◆ SetBuffer()

void FusionEngineFramer::SetBuffer	(	void *	buffer,
		size_t	capacity_bytes
	)

Set the buffer to use for message framing.

Postcondition: buffer must exist for the lifetime of this instance.

Parameters

buffer	The framing buffer to use. Set to `nullptr` to allocate a buffer internally.
capacity_bytes	The maximum framing buffer capacity (in bytes).

Definition at line 112 of file fusion_engine_framer.cc.

◆ SetMessageCallback()

void point_one::fusion_engine::parsers::FusionEngineFramer::SetMessageCallback ( MessageCallback callback )

inline

Specify a function to be called when a message is framed.

Parameters

callback The function to be called with the message header and a pointer to the message payload.

Definition at line 116 of file fusion_engine_framer.h.

◆ WarnOnError()

void point_one::fusion_engine::parsers::FusionEngineFramer::WarnOnError ( bool enabled )

inline

Enable/disable warnings for CRC and "message too large" failures.

This is typically used when the incoming stream has multiple types of binary content (e.g., interleaved FusionEngine and RTCM messages), and the FusionEngine message preamble is expected to appear in the non-FusionEngine content occasionally.

Parameters

enabled If true, issue warnings on errors.

Definition at line 108 of file fusion_engine_framer.h.

Member Data Documentation

◆ buffer_

uint8_t* point_one::fusion_engine::parsers::FusionEngineFramer::buffer_ {nullptr}

private

Definition at line 146 of file fusion_engine_framer.h.

◆ callback_

MessageCallback point_one::fusion_engine::parsers::FusionEngineFramer::callback_ = nullptr

private

Definition at line 142 of file fusion_engine_framer.h.

◆ capacity_bytes_

uint32_t point_one::fusion_engine::parsers::FusionEngineFramer::capacity_bytes_ {0}

private

Definition at line 147 of file fusion_engine_framer.h.

◆ current_message_size_

uint32_t point_one::fusion_engine::parsers::FusionEngineFramer::current_message_size_ {0}

private

Definition at line 151 of file fusion_engine_framer.h.

◆ is_buffer_managed_

bool point_one::fusion_engine::parsers::FusionEngineFramer::is_buffer_managed_ = false

private

Definition at line 145 of file fusion_engine_framer.h.

◆ next_byte_index_

uint32_t point_one::fusion_engine::parsers::FusionEngineFramer::next_byte_index_ {0}

private

Definition at line 150 of file fusion_engine_framer.h.

◆ state_

State point_one::fusion_engine::parsers::FusionEngineFramer::state_ {State::SYNC0}

private

Definition at line 149 of file fusion_engine_framer.h.

◆ warn_on_error_

bool point_one::fusion_engine::parsers::FusionEngineFramer::warn_on_error_ = true

private

Definition at line 144 of file fusion_engine_framer.h.

The documentation for this class was generated from the following files:

src/point_one/fusion_engine/parsers/fusion_engine_framer.h
src/point_one/fusion_engine/parsers/fusion_engine_framer.cc

Detailed Description

Public Types

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Member Typedef Documentation

◆ MessageCallback

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ FusionEngineFramer() [1/5]

◆ FusionEngineFramer() [2/5]

◆ FusionEngineFramer() [3/5]

◆ ~FusionEngineFramer()

◆ FusionEngineFramer() [4/5]

◆ FusionEngineFramer() [5/5]

Member Function Documentation

◆ ClearManagedBuffer()

◆ OnByte()

◆ OnData()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ Reset()

◆ Resync()

◆ SetBuffer()

◆ SetMessageCallback()

◆ WarnOnError()

Member Data Documentation

◆ buffer_

◆ callback_

◆ capacity_bytes_

◆ current_message_size_

◆ is_buffer_managed_

◆ next_byte_index_

◆ state_

◆ warn_on_error_