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 48 of file fusion_engine_framer.h.

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

Public Types
using	RawMessageCallback = void()(void context, const messages::MessageHeader &header, const void *payload)

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

	FusionEngineFramer (const FusionEngineFramer &)=delete

	FusionEngineFramer (FusionEngineFramer &&)=delete

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

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

P1_EXPORT	~FusionEngineFramer ()

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

FusionEngineFramer &	operator= (const FusionEngineFramer &)=delete

FusionEngineFramer &	operator= (FusionEngineFramer &&)=delete

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

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

P1_EXPORT void	SetMessageCallback (RawMessageCallback callback, void *context)
	Specify a function to be called when a message is framed. More...

P1_EXPORT 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}

uint32_t	capacity_bytes_ {0}

uint32_t	current_message_size_ {0}

bool	is_buffer_managed_ = false

uint32_t	next_byte_index_ {0}

RawMessageCallback	raw_callback_ = nullptr

void *	raw_callback_context_ = nullptr

State	state_ {State::SYNC0}

bool	warn_on_error_ = true

Member Typedef Documentation

◆ RawMessageCallback

using point_one::fusion_engine::parsers::FusionEngineFramer::RawMessageCallback = void (*)(void* context, const messages::MessageHeader& header, const void* payload)

Definition at line 54 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 163 of file fusion_engine_framer.h.

Constructor & Destructor Documentation

◆ FusionEngineFramer() [1/5]

P1_EXPORT 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]

P1_EXPORT 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 72 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 515 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 418 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()

P1_EXPORT void point_one::fusion_engine::parsers::FusionEngineFramer::SetMessageCallback	(	RawMessageCallback	callback,
		void *	context
	)

inline

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

Parameters

callback	The function to be called with the supplied context variable, the message header, and a pointer to the message payload.
context	A context value that will be passed to the callback.

Definition at line 140 of file fusion_engine_framer.h.

◆ WarnOnError()

P1_EXPORT 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 119 of file fusion_engine_framer.h.

Member Data Documentation

◆ buffer_

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

private

Definition at line 178 of file fusion_engine_framer.h.

◆ capacity_bytes_

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

private

Definition at line 179 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 183 of file fusion_engine_framer.h.

◆ is_buffer_managed_

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

private

Definition at line 177 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 182 of file fusion_engine_framer.h.

◆ raw_callback_

RawMessageCallback point_one::fusion_engine::parsers::FusionEngineFramer::raw_callback_ = nullptr

private

Definition at line 173 of file fusion_engine_framer.h.

◆ raw_callback_context_

void* point_one::fusion_engine::parsers::FusionEngineFramer::raw_callback_context_ = nullptr

private

Definition at line 174 of file fusion_engine_framer.h.

◆ state_

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

private

Definition at line 181 of file fusion_engine_framer.h.

◆ warn_on_error_

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

private

Definition at line 176 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

◆ RawMessageCallback

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_

◆ capacity_bytes_

◆ current_message_size_

◆ is_buffer_managed_

◆ next_byte_index_

◆ raw_callback_

◆ raw_callback_context_

◆ state_

◆ warn_on_error_