mip_parser.c File Reference

#include "mip_parser.h"
#include "mip_offsets.h"
#include <assert.h>

Macros
#define	MIPPARSER_RESET_LENGTH   1

Functions
void	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.
void	mip_parser_reset (mip_parser *parser)
	Resets the MIP parser.
size_t	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.
bool	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_timestamp	mip_parser_timeout (const mip_parser *parser)
	Returns the packet timeout of the parser.
void	mip_parser_set_timeout (mip_parser *parser, mip_timestamp timeout)
	Changes the timeout of the MIP parser.
void	mip_parser_set_callback (mip_parser *parser, mip_packet_callback callback, void *callback_object)
	mip_parser_set_callback
mip_packet_callback	mip_parser_callback (const mip_parser *parser)
	mip_parser_callback
void *	mip_parser_callback_object (const mip_parser *parser)
	mip_parser_callback
mip_timestamp	mip_parser_last_packet_timestamp (const mip_parser *parser)
	Gets the timestamp of the last parsed packet.
size_t	mip_parser_get_write_ptr (mip_parser *parser, uint8_t **const ptr_out)
	Obtain a pointer into which data may be read for processing.
void	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().
mip_timeout	mip_timeout_from_baudrate (uint32_t baudrate)
	Computes an appropriate packet timeout for a given serial baud rate.

Macro Definition Documentation

MIPPARSER_RESET_LENGTH

#define MIPPARSER_RESET_LENGTH   1

Function Documentation

mip_parser_callback()

mip_packet_callback mip_parser_callback

(

const mip_parser *

parser

)

mip_parser_callback

Parameters

parser

Returns

the packet callback function.

mip_parser_callback_object()

void * 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_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_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_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_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_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_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_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_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_parser_set_timeout	(	mip_parser *	parser,
		mip_timestamp	timeout
	)

Changes the timeout of the MIP parser.

Parameters

parser
timeout

mip_parser_timeout()

mip_timestamp mip_parser_timeout

(

const mip_parser *

parser

)

Returns the packet timeout of the parser.

mip_timeout_from_baudrate()

mip_timeout 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.