serparser

Three class names are defined depending on how the memory buffer is managed (alloc).

// serparser_attach : uses an existing buffer
serparser_attach

// serparser : allocates an internal buffer of N bytes
serparser_local<N>

// serparser_heap : allocates a buffer in the heap
serparser_heap

Constants (Format Type)

These are format types passed as parameters to the begin() initializer. Two types are supported here: ASCII and binary formats.

About Formats

ASCII Format

The ASCII format is a method to represent a binary data sequence as a string.

For example, the byte sequence 00A01301FF123456 is represented in ASCII format as follows. It starts with :, the checksum is B1, and the terminator is [CR:0x0d][LF:0x0a].

:00A01301FF123456B1[CR][LF]

The terminating checksum can be omitted by replacing the checksum and CRLF sequence with X. Although this makes the format more vulnerable to corrupted data, it is useful for quick tests or sending data manually.

:00A01301FF123456X

Definition

Binary Format

The binary format appends a header and checksum to a binary data sequence for transmission.

For example, the byte sequence 00A01301FF123456 is represented in binary format as:

0xA5 0x5A 0x80 0x08 0x00 0xA0 0x13 0x01 0xFF 0x12 0x34 0x56 0x3D

Definition

Methods

Declaration: begin()

// serparser_attach : uses an existing buffer
serparser_attach p1;

uint8_t buff[128];
p1.begin(PARSER::ASCII, buff, 0, 128);


// serparser : allocates an internal buffer of N bytes
serparser p2<128>;
p2.begin(PARSER::ASCII);


// serparser_heap : allocates a buffer on the heap
serparser_heap p3;
p3.begin(PARSER::ASCII, 128);

The declaration specifies the memory allocation class. Since this can be cumbersome, aliases are provided as shown above.

Call the begin() method corresponding to the memory allocation class.

serparser_attach

void begin(uint8_t ty, uint8_t *p, uint16_t siz, uint16_t max_siz)

Uses the format specified by ty (see formats) and the buffer pointed to by p. The total buffer size is max_siz, and the valid data length is specified by siz.

This definition is especially useful when outputting a data sequence in formatted style (see >> operator).

serparser_local<N> - Allocate internal buffer

void begin(uint8_t ty)

Initializes using the format specified by ty (see formats).

serparser_heap - Allocate buffer on heap

void begin(uint8_t ty, uint16_t siz)

Initializes using the format specified by ty and allocates siz bytes on the heap.

get_buf()

BUFTYPE& get_buf()

Returns the internal buffer. The buffer is of type smplbuf<uint8_t, alloc>.

parse()

inline bool parse(uint8_t b)

Processes input characters. Accepts one byte of input at a time and interprets it according to the specified format. For example, in ASCII format, the sequence :00112233X is processed byte-by-byte (:, 0, 0, … X), and the format interpretation is completed upon receiving X.

The parse() parameter is the input byte. It returns true if interpretation has completed.

Example

while (Serial.available()) {
    int c = Serial.read();

    if (SerialParser.parse(c)) {
        // Format parsing complete, b holds the resulting data sequence (smplbuf<uint8_t>)
        auto&& b = SerialParser.get_buf();

        // Below is the processing for the obtained data sequence
        if (b[0] == 0xcc) {
          // ...
        }
    }
}

operator bool()

operator bool()

Returns true if parsing has completed via parse(), otherwise returns false while parsing is in progress.

Example (the parse() example can be rewritten as follows)

while (Serial.available()) {
    int c = Serial.read();

    SerialParser.parse(c);

    if(SerialParser) {
        // Format parsing complete, b holds the resulting data sequence (smplbuf<uint8_t>)
        auto&& b = SerialParser.get_buf();
        // ...
    }
}

<< Operator

Outputs the internal buffer to a stream (e.g., Serial) in formatted style.

Example

uint8_t u8buf[] = { 0x11, 0x22, 0x33, 0xaa, 0xbb, 0xcc };

ser_parser pout;
pout.begin(PARSER::ASCII, u8buf, 6, 6); // Specify 6 bytes from u8buf

Serial << pout;// Output to Serial in formatted style -> :112233AABBCC??[CR][LF]