File Persistence (Serialization)

When the project is built with -DENABLE_FILE_PERSISTENCE=ON (compiles with -DUSE_FILE_PERSISTENCE), the serialization layer in serialization.h is available. It provides binary file I/O for entire groups with group- and datapoint-level version validation.

Enabling Persistence

Set "persistence" in groups.json:

{
  "name": "CyclicGroup",
  "persistence": "Cyclic",
  "baseId": "0x5000",
  "version": "2.0.0"
}

Allowed values: "None" (default), "Cyclic", "OnWrite".

The generated GroupDataPointMapping exposes two methods when USE_FILE_PERSISTENCE is defined:

SerializationStatus CyclicGroup.serializeGroup("data/cyclic.bin");
SerializationStatus CyclicGroup.deserializeGroup("data/cyclic.bin");

Version-Aware Upgrade

Each group carries a Version { major, minor, build } and each datapoint carries its own version. During deserialization:

1. The stored group version is compared to the current group version.

2. If they differ and AllowUpgrade is true on the group, deserialization continues and skips individual datapoints whose stored version does not match the current version.

3. If AllowUpgrade is false on the group a version mismatch sets SerializationError::GroupVersion and deserialization stops.

API Reference

struct SerializationStatus

enum class SerializationError : uint8_t

Values:

enumerator None

enumerator GroupVersion

enumerator DatapointVersion

enumerator GroupAndDatapointVersion

enumerator NotAllBytesRead

template<typename Data>
struct Serialization

template<typename Data>
struct Deserialization