Adafruit_NMEA Class Reference

#include <Adafruit_NMEA.h>

Inheritance diagram for Adafruit_NMEA:

Public Member Functions
	Adafruit_NMEA (volatile char *firstBuffer, volatile char *secondBuffer, size_t capacity)
	Create a receiver using two caller-owned buffers. More...
	Adafruit_NMEA (const Adafruit_NMEA &other)=delete
	Copying is disabled to prevent sharing writable receive buffers. More...
Adafruit_NMEA &	operator= (const Adafruit_NMEA &other)=delete
	Assignment is disabled to prevent sharing writable receive buffers. More...
void	reset ()
	Discard partial and completed lines and clear all timestamps. More...
nmea_frame_status_t	feed (uint8_t byte, uint32_t receivedAtMs)
	Feed one byte into this receiver's bounded sentence buffer. More...
nmea_span_t	lastText () const
	Get the latest complete raw line without validating it again. More...
nmea_sentence_t	lastSentence () const
	Get views of the latest complete line, including invalid raw text. More...
uint32_t	sentenceStartedAt () const
	Get the start-marker timestamp of the latest complete line. More...
uint32_t	sentenceReceivedAt () const
	Get the LF timestamp of the latest complete line. More...

Static Public Member Functions
static nmea_sentence_t	validate (const char *data, size_t length)
	Validate a complete, length-bounded NMEA sentence without copying it. More...
static nmea_span_t	nextField (nmea_span_t &remaining)
	Return the next field and advance a bounded field cursor. More...
static nmea_decimal_t	parseDecimal (nmea_span_t field)
	Convert a complete field to an exact signed decimal value. More...
static nmea_number_status_t	validateDecimal (nmea_span_t field, bool allowNegative=true)
	Check an exact decimal without constructing its numeric value. More...
static size_t	buildCommand (char *output, size_t capacity, const char *body, size_t bodyLength)
	Build a checksummed command in caller-provided storage. More...

Detailed Description

Hardware-independent NMEA framing and utilities shared by receiver classes. Receive storage is borrowed, with no heap allocation. Each instance has its own receive state and timestamps; callers must synchronize concurrent use.

Constructor & Destructor Documentation

Adafruit_NMEA() [1/2]

Adafruit_NMEA::Adafruit_NMEA	(	volatile char *	firstBuffer,
		volatile char *	secondBuffer,
		size_t	capacity
	)

Create a receiver using two caller-owned buffers.

Parameters

firstBuffer	First writable receive buffer.
secondBuffer	Second writable receive buffer, not overlapping first.
capacity	Size of each buffer, including space for a NUL terminator.

Both buffers must outlive the receiver and remain exclusively owned by it. NULL pointers, overlapping buffers, or capacity below two bytes disable reception: feed() returns BAD_FORMAT and no buffer is written. Valid buffers are initialized to empty strings. No memory is allocated.

Adafruit_NMEA() [2/2]

Adafruit_NMEA::Adafruit_NMEA ( const Adafruit_NMEA &  other )

delete

Copying is disabled to prevent sharing writable receive buffers.

Parameters

other

Receiver that cannot be copied.

Member Function Documentation

operator=()

Adafruit_NMEA& Adafruit_NMEA::operator= ( const Adafruit_NMEA &  other )

delete

Assignment is disabled to prevent sharing writable receive buffers.

Parameters

other

Receiver that cannot be assigned.

Returns

No value; this deleted operation cannot be called.

reset()

void Adafruit_NMEA::reset

(

)

Discard partial and completed lines and clear all timestamps.

Invalidates every view returned by lastSentence(). Valid receive buffers become empty strings. Invalid storage remains disabled and untouched.

feed()

nmea_frame_status_t Adafruit_NMEA::feed	(	uint8_t	byte,
		uint32_t	receivedAtMs
	)

Feed one byte into this receiver's bounded sentence buffer.

Parameters

byte	Received byte, including any CR/LF characters.
receivedAtMs	Receive time in milliseconds, such as millis().

Returns

INCOMPLETE until LF completes a line, then its validation status. OVERFLOW discards a line that cannot fit including LF and NUL. BAD_FORMAT also indicates invalid storage supplied to the constructor.

Ignore bytes before '$' or '!'. Either start marker restarts assembly, including after overflow. Overflow is reported once; subsequent bytes are ignored until another start marker. Partial and overflowing lines preserve the previous complete line and its timestamps.

Every complete, non-overflowed line replaces lastSentence(), even if its format or checksum is invalid. Its raw text includes LF and is followed by a NUL terminator. The caller must consume each line promptly; there is no queue. No transport access, allocation, or sentence copying occurs.

lastText()

nmea_span_t Adafruit_NMEA::lastText

(

)

const

Get the latest complete raw line without validating it again.

Returns

Borrowed text and its length, or an absent span before completion.

Includes invalid lines and their LF, with a NUL after the stored length. The view expires on the next completed line or reset(). As with lastSentence(), callers must synchronize access with feed().

lastSentence()

nmea_sentence_t Adafruit_NMEA::lastSentence

(

)

const

Get views of the latest complete line, including invalid raw text.

Returns

Validated sentence, or INCOMPLETE with absent spans before a line has completed or after reset(). Overflow does not replace this result.

Views borrow the receive buffer and expire on the next complete line, reset(), or receiver destruction. Address and fields are only available for VALID lines. Validation uses the stored length, not the NUL terminator.

sentenceStartedAt()

uint32_t Adafruit_NMEA::sentenceStartedAt

(

)

const

Get the start-marker timestamp of the latest complete line.

Returns

Supplied receive time in milliseconds, or zero before a line exists. Zero is also a valid timestamp; use lastSentence().status to distinguish it.

sentenceReceivedAt()

uint32_t Adafruit_NMEA::sentenceReceivedAt

(

)

const

Get the LF timestamp of the latest complete line.

Returns

Supplied receive time in milliseconds, or zero before a line exists. Timestamps retain the caller's uint32_t wraparound behavior.

validate()

nmea_sentence_t Adafruit_NMEA::validate ( const char *  data, size_t  length  )

static

Validate a complete, length-bounded NMEA sentence without copying it.

Parameters

data	Readable input buffer; no NUL terminator is required.
length	Number of bytes to inspect, excluding any NUL terminator.

Returns

Status and borrowed spans. Address and fields are absent on failure. Raw text remains available unless data is NULL, which gives absent spans.

Accepts '$' or '!', an ASCII alphanumeric address, optional comma-separated fields, '*', two hex checksum digits, optional CR, and optional LF, in that order. A valid but unknown address is accepted. Embedded start markers, control characters, non-ASCII bytes, and extra trailer bytes are rejected. Missing or invalid hex digits are BAD_FORMAT; a mismatch is BAD_CHECKSUM.

A zero-field message such as "$PQTMVERNO*58" has absent fields. A comma immediately followed by '*' denotes one empty field, with non-NULL data and zero length. Returned views require the input to remain unchanged. This function allocates no memory and has no shared or per-instance state.

nextField()

nmea_span_t Adafruit_NMEA::nextField ( nmea_span_t &  remaining )

static

Return the next field and advance a bounded field cursor.

Parameters

remaining

Start with a copy of a VALID sentence's fields span. Updated in place to refer to the fields after the next comma, or to an absent span after the last field. Its input storage must remain readable.

Returns

Borrowed field text, excluding the comma. Non-NULL data with zero length means an empty field; NULL data means there are no fields left.

Leading, consecutive, and trailing commas preserve empty fields. An absent cursor stays absent on subsequent calls. No text is copied or modified, and no NUL terminator is required. Only the supplied length is inspected. Iterate each cursor in order for one forward scan of its fields.

To mark a cursor exhausted, set remaining.data to NULL. Setting only remaining.length to zero still yields one empty field if data is non-NULL.

parseDecimal()

nmea_decimal_t Adafruit_NMEA::parseDecimal ( nmea_span_t  field )

static

Convert a complete field to an exact signed decimal value.

Parameters

field

Borrowed readable text, with no NUL terminator required.

Returns

Status, integer coefficient, and decimal-place count. Both numeric members are zero on failure. NULL data is MISSING; zero length is EMPTY.

Accepts an optional sign, digits, and at most one decimal point. At least one digit is required. Whitespace, exponents, and non-digit suffixes are rejected. The supplied fractional digit count is retained, including zeros. Coefficients must fit int64_t and decimal-place counts must fit uint8_t. Malformed syntax takes precedence over overflow. No rounding, floating-point conversion, allocation, or input modification occurs.

validateDecimal()

nmea_number_status_t Adafruit_NMEA::validateDecimal ( nmea_span_t  field, bool  allowNegative = true  )

static

Check an exact decimal without constructing its numeric value.

Parameters

field	Borrowed readable text, with no NUL terminator required.
allowNegative	Whether to accept negative nonzero values.

Returns

The same syntax and range status as parseDecimal(). Negative nonzero values give OUT_OF_RANGE when allowNegative is false.

Retains parseDecimal's signed 64-bit coefficient and fractional digit limits, including malformed-syntax precedence. Uses no 64-bit arithmetic or allocation. Negative zero is accepted in either mode.

buildCommand()

size_t Adafruit_NMEA::buildCommand ( char *  output, size_t  capacity, const char *  body, size_t  bodyLength  )

static

Build a checksummed command in caller-provided storage.

Parameters

output	Writable buffer for the complete command and NUL terminator.
capacity	Size of output in bytes, including space for NUL.
body	Readable address and optional comma-separated fields, without '$', '!', '*', control characters, or non-ASCII bytes. No NUL is required.
bodyLength	Number of bytes in body, excluding any NUL terminator.

Returns

Bytes written excluding NUL, or zero on invalid input, overlapping buffers, or insufficient capacity. On failure, output[0] is cleared if output is non-NULL and capacity is nonzero; no other output bytes are changed.

Produces "$<body>*HH\r\n" followed by NUL, using uppercase checksum digits. Requires bodyLength + NMEA_COMMAND_OVERHEAD bytes of storage. The address must be nonempty and ASCII alphanumeric. Zero-field commands are allowed. Arguments, capacity, and body syntax are checked before constructing output. No heap allocation or transport I/O occurs.

---

The documentation for this class was generated from the following files:

• src/Adafruit_NMEA.h
• src/Adafruit_NMEA.cpp