Serialization APIs

Alpaca

The serialization library is a light wrapper around the third-party alpaca serialization library.

Serialization

The Serialization component provides a simple wrapper with reasonable default options around the Alpaca libarary. The default serialization/deserialization options are configured such that messages / types can be distinguished from each other.

Code examples for the serialization API are provided in the serialization example folder.

Serialization Example
- How to use example
  - Build and Flash

API Reference

Header File

components/serialization/include/serialization.hpp

Macros

__gnu_linux__

Classes

class __serialization_documentation__

Serialization convenience wrapper for espp, providing methods for serializaing structures / classes into containers (such as c-sytle arrays, std::arrays, std::vectors, etc.). and for deserializing such containers into structures / classes.

(De-)Serialization Example

    struct MyStruct {
      uint8_t value; // NOTE: you cannot use int, you must use strongly sized types.
    };
    std::error_code ec;
    MyStruct object{5};
    {
      uint8_t buffer[10];
      auto bytes_written = alpaca::serialize(object, buffer);
      fmt::print("Serialized {}B to c-array (alpaca)\n", bytes_written);
      auto new_object = alpaca::deserialize<MyStruct>(buffer, bytes_written, ec);
      if (!ec && new_object.value == object.value) {
        fmt::print("Deserialized successfully!\n");
      } else {
        fmt::print("Deserialization failed: {}\n", ec.message());
      }
    }
    {
      uint8_t buffer[10];
      auto bytes_written = espp::serialize(object, buffer);
      fmt::print("Serialized {}B to c-array (espp wrapper)\n", bytes_written);
      auto new_object = espp::deserialize<MyStruct>(buffer, bytes_written, ec);
      if (!ec && new_object.value == object.value) {
        fmt::print("Deserialized successfully!\n");
      } else {
        fmt::print("Deserialization failed: {}\n", ec.message());
      }
    }
    {
      std::array<uint8_t, 5> buffer;
      auto bytes_written = espp::serialize(object, buffer);
      fmt::print("Serialized {}B to std::array\n", bytes_written);
      auto new_object = espp::deserialize<MyStruct>(buffer, ec);
      if (!ec && new_object.value == object.value) {
        fmt::print("Deserialized successfully!\n");
      } else {
        fmt::print("Deserialization failed: {}\n", ec.message());
      }
    }
    {
      std::vector<uint8_t> buffer;
      auto bytes_written = espp::serialize(object, buffer);
      fmt::print("Serialized {}B to std::vector\n", bytes_written);
      auto new_object = espp::deserialize<MyStruct>(buffer, ec);
      if (!ec && new_object.value == object.value) {
        fmt::print("Deserialized successfully!\n");
      } else {
        fmt::print("Deserialization failed: {}\n", ec.message());
      }
    }
    {
      std::array<uint8_t, 15> buffer;
      constexpr auto OPTIONS = alpaca::options::fixed_length_encoding;
      auto bytes_written = espp::serialize<OPTIONS>(object, buffer);
      fmt::print("Serialized {}B to std::arary with custom options\n", bytes_written);
      auto new_object = espp::deserialize<OPTIONS, MyStruct>(buffer, ec);
      if (!ec && new_object.value == object.value) {
        fmt::print("Deserialized successfully!\n");
      } else {
        fmt::print("Deserialization failed: {}\n", ec.message());
      }
    }

Complex Structure (De-)Serialization Example

    struct MyStruct {
      uint8_t value;
      std::vector<uint32_t> data;
      std::string name;
    };
    std::error_code ec;
    MyStruct object{42, {1, 3, 3, 7}, "the meaning of life"};
    std::vector<uint8_t> buffer;
    auto bytes_written = espp::serialize(object, buffer);
    fmt::print("Serialized {}B to std::vector\n", bytes_written);
    auto new_object = espp::deserialize<MyStruct>(buffer, ec);
    if (!ec && new_object.value == object.value) {
      fmt::print("Deserialized successfully!\n");
      fmt::print("\tvalue: {}\n"
                 "\tdata:  {}\n"
                 "\tname:  {}\n",
                 new_object.value, new_object.data, new_object.name);
    } else {
      fmt::print("Deserialization failed: {}\n", ec.message());
    }

Note

When defining types to be serialized, you MUST use strictly sized types, such as uint8_t / int8_t or uint32_t or int8_t instead of just int or even size_t.

Note

This class does not really exist or do anything, but it’s the only way I could figure out how to get this documentation built into the system :(