MIP_SDK v2.0.0-141-g7a72ec3
MicroStrain Communications Library for embedded systems
Loading...
Searching...
No Matches
Macros | Functions
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);
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_wr...
Definition mip_parser.c:381
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.
Definition mip_parser.c:362
Parameters
parser
ptr_outA 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
bufferScratch space for the parser to use internally; input data is consumed and fed to this buffer. Cannot be NULL.
buffer_sizeSize of buffer, in bytes.
callbackA 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_objectAn optional user-specified pointer which is directly passed to the callback as the first parameter.
timeoutThe 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_bufferPointer 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_countThe number of bytes in the input buffer.
timestampThe local time the data was received. This is used to check for timeouts and is passed to the callback as the packet timestamp.
max_packetsThe 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
baudrateSerial 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.