MessagePack is a library for AVR, SAMD, ESP8266 and ESP32 platforms to pack/unpack values into a compact, self-explanatory binary message.
The main features of the MessagePack library are:
- Compact yet self-explanatory message format
- Targeted to wireless communication
- Support for boolean, short, integer, long, and float numbers and c-strings.
Check the examples folder for working examples of the library.
#include "MessagePack.h"
void send(unsigned char * data, unsigned char length) {
// ...
}
void setup() {
MessagePack * message = new MessagePack();
// Add some values, for instance temperature, humidity and pressure
message->addFloat(25.4);
message->addShort(67);
message->addFloat(1013.45);
// Send message
send(message->pack(), message->length());
}
loop() {}
#include "MessagePack.h"
void parse(unsigned char * data, unsigned char length) {
MessagePack * message = new MessagePack();
// Load the data
message->unpack(data, length);
// Number of elements
unsigned char count = message->count();
Serial.print("Number of values: ");
Serial.println(count);
// Walk elements (only for integer numbers, see example for full functionality)
char buffer[32];
for (unsigned char i=0; i<count; i++) {
unsigned char type = message->type(i);
if (MESSAGE_PACK_BOOLEAN == type) {
snprintf(buffer, sizeof(buffer), "Value #%d is a BOOLEAN: %d\n", i, message->getBoolean(i) ? 1 : 0);
} else if (MESSAGE_PACK_SHORT == type) {
snprintf(buffer, sizeof(buffer), "Value #%d is a SHORT: %u\n", i, message->getShort(i));
} else if (MESSAGE_PACK_INTEGER == type) {
snprintf(buffer, sizeof(buffer), "Value #%d is an INTEGER: %u\n", i, message->getInteger(i));
} else if (MESSAGE_PACK_LONG == type) {
snprintf(buffer, sizeof(buffer), "Value #%d is a LONG: %lu\n", i, message->getLong(i));
}
Serial.print(buffer);
}
}
setup() {}
loop() {
if (Serial.available()) {
// ...
// send the message to the parser routine
parse(data, length);
}
}
This library works under the following assumptions:
- Data is in little-endian format (least significant byte, is at the lowest address)
- Integers have a length of 8, 16 or 32 bits (for SHORT, INTEGER and LONG types)
- Floats are represented in IEEE 754 single-precision format, and have a length of 32 bits
- Booleans are represented in a byte (1 = true, 0 = false)
- Strings are ended by the NULL char (0x00)
Data is binary packed with this format:
- First byte: number of values packed in the string
- N bytes with the information about the data type of each packed value. Each byte have information about 2 packed values, one for each nibble. Data types are coded in this way:
- 0b0000: Null
- 0b0001: Boolean
- 0b0010: Short
- 0b0011: Integer
- 0b0100: Long
- 0b0101: Float
- 0b0110: String
- N bytes of data
The pack string (without spaces) for 17 (short), true (boolean), nil and 452 (integer) are:
03 21 30 11 01 C401
03 is the number of packed values, in this case 3
21 is the type of the first and second packed values: short and boolean
30 is the type of the third and fourth packed values: integer and null
11 is integer 17 (0x11) in hexadecimal 1-byte integer (a.k.a. short)
01 is boolean true
C401 is integer 452 (0x01C4) in 2-bytes little-endian
Total length is 7 bytes. Take note that the nil value is only present in the header and has not representation in the data.
Copyright (C) 2018 by Xose Pérez
The MessagePack library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The MessagePack library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with the MessagePack library. If not, see http://www.gnu.org/licenses/.