Functions for parsing MIP packets.
More...
|
| void | mip::C::mip_parser_init (mip_parser *parser, mip_packet_callback callback, void *callback_object, mip_timeout timeout) |
| | Initializes the MIP parser. More...
|
| |
| void | mip::C::mip_parser_parse (mip_parser *parser, const uint8_t *input_buffer, size_t input_length, mip_timestamp timestamp) |
| | Parse packets from a buffer. More...
|
| |
| void | mip::C::mip_parser_flush (mip_parser *parser) |
| | Processes all previously buffered data. More...
|
| |
| void | mip::C::mip_parser_reset (mip_parser *parser) |
| | Resets the MIP parser. More...
|
| |
| uint_least16_t | mip::C::mip_parser_get_write_ptr (mip_parser *parser, uint8_t **ptr_out) |
| | Gets a pointer into which a small amount of data may be written for parsing. More...
|
| |
| mip_timeout | 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_timeout 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_current_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...
|
| |
Functions for parsing MIP packets.
See Mip Parser
Typical usage:
◆ MIP_PARSER_DEFAULT_TIMEOUT_MS
| #define MIP_PARSER_DEFAULT_TIMEOUT_MS 100 |
Specifies the default timeout for a MIP parser, assuming timestamps are in milliseconds.
◆ mip_packet_callback
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
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.
◆ mip_parser_callback()
mip_parser_callback
- Parameters
-
- Returns
- the packet callback function.
◆ mip_parser_callback_object()
| void * mip::C::mip_parser_callback_object |
( |
const mip_parser * |
parser | ) |
|
mip_parser_callback
- Parameters
-
- Returns
- the packet callback user data pointer.
◆ mip_parser_current_timestamp()
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:
- Either max_packets was reached, meaning at least one packet was parsed, and thus the timestamp is valid, or
- 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_flush()
| void mip::C::mip_parser_flush |
( |
mip_parser * |
parser | ) |
|
Processes all previously buffered data.
Call this at the end of reading a binary file to ensure that any trailing packets are fully processed.
- Parameters
-
◆ mip_parser_get_write_ptr()
| uint_least16_t mip::C::mip_parser_get_write_ptr |
( |
mip_parser * |
parser, |
|
|
uint8_t ** |
ptr_out |
|
) |
| |
Gets a pointer into which a small amount of data may be written for parsing.
Generally you should call mip_parser_parse with your input buffer directly. This method may be more efficient for data which arrives in small chunks by avoiding an intermediate buffer. However, for large chunks of data (e.g. reading from a file) it's more efficient to declare a bigger buffer (at least 1024 bytes) and parse that instead.
@caution If you use this function, you must call mip_parser_parse with input_buffer=NULL and input_length equal to the number of bytes written into the parser. Otherwise the data will be lost.
- Parameters
-
| parser | |
| [out] | ptr_out | Pointer to a pointer which will be set to an internal buffer location. |
- Returns
- The maximum number of bytes which may be written to the parser. This will never be more than the maximum MIP packet size.
◆ mip_parser_init()
Initializes the MIP parser.
- Parameters
-
| parser | |
| 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_parse()
| void mip::C::mip_parser_parse |
( |
mip_parser * |
parser, |
|
|
const uint8_t * |
input_buffer, |
|
|
size_t |
input_length, |
|
|
mip_timestamp |
timestamp |
|
) |
| |
Parse packets from a buffer.
The buffer may contain non-mip data (e.g. NMEA 0183) which will be ignored.
- Parameters
-
| parser | |
| input_buffer | Buffer from which to parse packets. If NULL, parses from the internal buffer instead (see mip_parser_get_write_ptr). |
| input_length | Length of data in the buffer. |
| timestamp | Time of arrival of the data to be parsed. This is used to set packets' timestamp and to time out incomplete packets. |
- Note
- The timestamp of a packet is based on the time the packet was parsed. Packets received during an earlier parse call may be timestamped with the time from a later parse call, but will never be timestamped before they were actually received.
-
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 contains the two-byte sequence 0x75, 0x65. This may cause temporary stalls in parsed data if the following bytes suggest that more data is needed to complete the "packet". Once the fake packet times out or enough data is received, real MIP packets received in the meantime will be properly parsed. Note that the 16-bit checksum has a 1 in 65,536 chance of appearing to be valid at random.
◆ 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
-
◆ mip_parser_set_callback()
mip_parser_set_callback
- Parameters
-
| parser | |
| callback | |
| callback_object | |
◆ mip_parser_set_timeout()
Changes the timeout of the MIP parser.
- Parameters
-
◆ mip_parser_timeout()
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.
