Mip Parser

Functions for parsing MIP packets. More...

Classes
struct	mip::C::mip_parser
	MIP Parser state. More...

Macros
#define	MIPPARSER_UNLIMITED_PACKETS   0
	Specifies no limit when used as the max_packets argument to mip_parser_parse. More...
#define	MIPPARSER_DEFAULT_TIMEOUT_MS   100
	Specifies the default timeout for a MIP parser, assuming timestamps are in milliseconds. More...

Typedefs
typedef bool(*	mip::C::mip_packet_callback) (void *user, const mip_packet_view *packet, mip_timestamp timestamp)
	Callback function which receives parsed MIP packets. More...
typedef struct mip::C::mip_parser	mip::C::mip_parser
	MIP Parser state. More...

Functions
void	mip::C::mip_parser_init (mip_parser *parser, uint8_t *buffer, size_t buffer_size, mip_packet_callback callback, void *callback_object, mip_timestamp timeout)
	Initializes the MIP parser. More...
bool	mip::C::mip_parser_parse_one_packet_from_ring (mip_parser *parser, mip_packet_view *packet_out, mip_timestamp timestamp)
	Parses a single packet from the internal buffer. More...
size_t	mip::C::mip_parser_parse (mip_parser *parser, const uint8_t *input_buffer, size_t input_count, mip_timestamp timestamp, unsigned int max_packets)
	Parses packets from the input data buffer. More...
void	mip::C::mip_parser_reset (mip_parser *parser)
	Resets the MIP parser. More...
size_t	mip::C::mip_parser_get_write_ptr (mip_parser *parser, uint8_t **const ptr_out)
	Obtain a pointer into which data may be read for processing. More...
void	mip::C::mip_parser_process_written (mip_parser *parser, size_t count, mip_timestamp timestamp, unsigned int max_packets)
	Notify the parser that data has been written to the pointer previously obtained via mip_parser_get_write_ptr(). More...
mip_timestamp	mip::C::mip_parser_timeout (const mip_parser *parser)
	Returns the packet timeout of the parser. More...
void	mip::C::mip_parser_set_timeout (mip_parser *parser, mip_timestamp timeout)
	Changes the timeout of the MIP parser. More...
void	mip::C::mip_parser_set_callback (mip_parser *parser, mip_packet_callback callback, void *callback_object)
	mip_parser_set_callback More...
mip_packet_callback	mip::C::mip_parser_callback (const mip_parser *parser)
	mip_parser_callback More...
void *	mip::C::mip_parser_callback_object (const mip_parser *parser)
	mip_parser_callback More...
mip_timestamp	mip::C::mip_parser_last_packet_timestamp (const mip_parser *parser)
	Gets the timestamp of the last parsed packet. More...
mip_timeout	mip::C::mip_timeout_from_baudrate (uint32_t baudrate)
	Computes an appropriate packet timeout for a given serial baud rate. More...

Detailed Description

Functions for parsing MIP packets.

See Mip Parser

Typical usage:

• Declare a mip_parser struct
• Declare a uint8_t buffer of some size which is at least 512 and a power of 2.
• Determine the packet timeout, e.g. with mip_timeout_from_baudrate().
• Call mip_parser_init(), passing the struct, buffer, buffer size, timeout, and callback function.
• Periodically call mip_parser_parse().

Macro Definition Documentation

MIPPARSER_DEFAULT_TIMEOUT_MS

#define MIPPARSER_DEFAULT_TIMEOUT_MS   100

Specifies the default timeout for a MIP parser, assuming timestamps are in milliseconds.

MIPPARSER_UNLIMITED_PACKETS

#define MIPPARSER_UNLIMITED_PACKETS   0

Specifies no limit when used as the max_packets argument to mip_parser_parse.

Typedef Documentation

mip_packet_callback

typedef bool(* mip::C::mip_packet_callback) (void *user, const mip_packet_view *packet, mip_timestamp timestamp)

Callback function which receives parsed MIP packets.

Parameters

user	A user-specified pointer which will be given the callback_object parameter which was previously passed to mip_parser_init.
packet	A pointer to the MIP packet. Do not store this pointer as it will be invalidated after the callback returns.
timestamp	The approximate time the packet was parsed.

mip_parser

typedef struct mip::C::mip_parser mip::C::mip_parser

MIP Parser state.

Note

This should be considered an "opaque" structure; its members should be considered an internal implementation detail. Avoid accessing them directly as they are subject to change in future versions of this software.

Function Documentation

mip_parser_callback()

mip_packet_callback mip::C::mip_parser_callback

(

const mip_parser *

parser

)

mip_parser_callback

Parameters

parser

Returns

the packet callback function.

mip_parser_callback_object()

void * mip::C::mip_parser_callback_object

(

const mip_parser *

parser

)

mip_parser_callback

Parameters

parser

Returns

the packet callback user data pointer.

mip_parser_get_write_ptr()

size_t mip::C::mip_parser_get_write_ptr	(	mip_parser *	parser,
		uint8_t **const	ptr_out
	)

Obtain a pointer into which data may be read for processing.

Use this function when the source data stream (e.g. a file or serial port) requires that you pass in a buffer when reading data. This avoids the need for an intermediate buffer.

Call mip_parser_process_written() after the data has been read to update the buffer count and process any packets.

uint8_t ptr;
size_t space = mip_parser_get_write_ptr(&parser, &ptr);
size_t used = fread(ptr, 1, space, file);
mip_parser_process_written(&parser, used);

Parameters

parser
ptr_out	A pointer to a pointer which will be set to the buffer where data should be written. Cannot be NULL.

Returns

How many bytes can be written to the buffer. Due to the use of a cicular buffer, this may be less than the total available buffer space. Do not write more data than specified.

mip_parser_init()

void mip::C::mip_parser_init	(	mip_parser *	parser,
		uint8_t *	buffer,
		size_t	buffer_size,
		mip_packet_callback	callback,
		void *	callback_object,
		mip_timestamp	timeout
	)

Initializes the MIP parser.

Parameters

parser
buffer	Scratch space for the parser to use internally; input data is consumed and fed to this buffer. Cannot be NULL.
buffer_size	Size of buffer, in bytes.
callback	A function to be called when a valid packet is identified. It will be passed an optional user-supplied parameter, a pointer to the packet, and the time the first byte was parsed.
callback_object	An optional user-specified pointer which is directly passed to the callback as the first parameter.
timeout	The timeout for receiving one packet. Depends on the serial baud rate and is typically 100 milliseconds.

mip_parser_last_packet_timestamp()

mip_timestamp mip::C::mip_parser_last_packet_timestamp

(

const mip_parser *

parser

)

Gets the timestamp of the last parsed packet.

This is only valid after a valid packet has been parsed.

This function is provided to allow additional calls to mip_parser_parse() with no input data (buffer=NULL and length=0) when max_packets > 0. The additional calls can use the same timestamp because no new data will be processed.

There are two possible situations after the last call to parse:

1. Either max_packets was reached, meaning at least one packet was parsed, and thus the timestamp is valid, or
2. More data is required, in which case this time may not be valid, but it won't matter because an additional call to parse won't produce a new packet to be timestamped.

mip_parser_parse()

size_t mip::C::mip_parser_parse	(	mip_parser *	parser,
		const uint8_t *	input_buffer,
		size_t	input_count,
		mip_timestamp	timestamp,
		unsigned int	max_packets
	)

Parses packets from the input data buffer.

For every valid MIP packet, the callback function will be called with the packet and timestamp.

Parameters

parser
input_buffer	Pointer to bytes received from the device or file. This buffer may contain non-mip data (e.g. NMEA 0183), which will be ignored. This buffer may be NULL if input_count is 0.
input_count	The number of bytes in the input buffer.
timestamp	The local time the data was received. This is used to check for timeouts and is passed to the callback as the packet timestamp.
max_packets	The maximum number of packets to process. Unprocessed data is left in the internal buffer. If 0, processing runs until no complete packets remain in the buffer.

Returns

The number of bytes left unprocessed from the input buffer. If max_packets is 0, this will also be zero as all of the data will be consumed. Data may still remain in the internal buffer.

Note

If max_packets is 0, then this function is guaranteed to consume all of the input data and the buffer can be reused or discarded afterward. However, if max_packets is nonzero (meaning the number of packets parsed will be limited), then this is no longer guaranteed as the excess data may fill up the internal bufffer. In this case, you must process packets faster than they arrive on average. For bursty data (e.g. GNSS data), use a large internal buffer (see mip_parser_init) to help average out the packet processing load.

The timestamp of parsed packets is based on the time the packet was parsed. When max_packets==0, this is the same as the input timestamp. When max_packets!=0, packets received during an earlier parse call may be timestamped with the time from a later parse call. Therefore, if packet timestamping is critical to your application, avoid using max_packets > 0.

The parser will do its best to ignore non-MIP data. However, it is possible for some binary data to appear to be a MIP packet if it conntains 0x75,0x65, has at least 6 bytes, and has a valid checksum. A 16-bit checksum has a 1 in 65,536 chance of appearing to be valid.

mip_parser_parse_one_packet_from_ring()

bool mip::C::mip_parser_parse_one_packet_from_ring	(	mip_parser *	parser,
		mip_packet_view *	packet_out,
		mip_timestamp	timestamp
	)

Parses a single packet from the internal buffer.

mip_parser_process_written()

void mip::C::mip_parser_process_written	(	mip_parser *	parser,
		size_t	count,
		mip_timestamp	timestamp,
		unsigned int	max_packets
	)

Notify the parser that data has been written to the pointer previously obtained via mip_parser_get_write_ptr().

The write pointer changes after calling this with count > 0. To write more data, call mip_parser_get_write_ptr again.

Parameters

parser
count
timestamp
max_packets

mip_parser_reset()

void mip::C::mip_parser_reset

(

mip_parser *

parser

)

Resets the MIP parser.

Clears the current packet and internal buffer. The parser will be restored as if mip_parser_init had just been called.

Parameters

parser

mip_parser_set_callback()

void mip::C::mip_parser_set_callback	(	mip_parser *	parser,
		mip_packet_callback	callback,
		void *	callback_object
	)

mip_parser_set_callback

Parameters

parser
callback
callback_object

mip_parser_set_timeout()

void mip::C::mip_parser_set_timeout	(	mip_parser *	parser,
		mip_timestamp	timeout
	)

Changes the timeout of the MIP parser.

Parameters

parser
timeout

mip_parser_timeout()

mip_timeout mip::C::mip_parser_timeout

(

const mip_parser *

parser

)

Returns the packet timeout of the parser.

mip_timeout_from_baudrate()

mip_timeout mip::C::mip_timeout_from_baudrate

(

uint32_t

baudrate

)

Computes an appropriate packet timeout for a given serial baud rate.

Note

This function assumes a standard serial port with 10 symbols per byte: 1 start bit, 8 data bits, and 1 stop bit.

Parameters

baudrate

Serial baud rate in bits per second

Returns

A timeout value in ms representing the time it would take to transmit a single mip packet of maximum size at the given baud rate, plus some tolerance.