API Reference

// KBOX_FLASH_LAYOUT_STORAGE_SIZE == 256u (host upper bound).
struct KnxFlashLayoutStorage {
  alignas(alignof(std::max_align_t)) unsigned char data[KBOX_FLASH_LAYOUT_STORAGE_SIZE];
};

class KnxFlashLayout {
 public:
  IFlash& StackStateView();  // stack machine-state region
  IFlash& UserDataView();    // your own app-data region (SaveUserData/LoadUserData)
  IFlash& CounterView();     // Secure only — Classic returns a valid but fail-closed view
  IFlash& SioKeyView();      // Secure only — Classic returns a valid but fail-closed view
  bool    IsValid() const;   // checked by Stack::Init() — see Integration Contract
};

// Classic — regions: {stack-state, user-data}.
KnxFlashLayout& MakeFlashLayout(KnxFlashLayoutStorage& storage, IFlash& baseFlash,
                                const StackParameters& sp, uint16_t userDataPageCount);

// Secure — regions: {counter, sio-key, stack-state, user-data}.
KnxFlashLayout& MakeFlashLayout(KnxFlashLayoutStorage& storage, IFlash& baseFlash,
                                const StackParameters& sp, const SioSizing& sioSizing,
                                uint16_t userDataPageCount);

// Storage size is chosen at compile time from KNX_APDU_MAX.
// KBOX_STACK_STORAGE_SIZE == 1344u  when KNX_APDU_MAX >= 254
//                        == 952u   otherwise
struct KnxStackStorage {
  alignas(alignof(std::max_align_t)) unsigned char data[KBOX_STACK_STORAGE_SIZE];
};

// Classic (non-secure) stack.
IKnxStack& MakeStack(KnxStackStorage& storage, StackParameters& stackParameters,
                     IBusDriver& busDriver, IWatchDog& watchDog, ILed& knxLed,
                     IClock& clock, ITransmitter& transmitter, IButton& button,
                     KnxFlashLayout& layout);

// Secure stack — same, plus an ISecurity& from MakeSecure(...).
IKnxStack& MakeStack(KnxStackStorage& storage, StackParameters& stackParameters,
                     IBusDriver& busDriver, IWatchDog& watchDog, ILed& knxLed,
                     IClock& clock, ITransmitter& transmitter, IButton& button,
                     KnxFlashLayout& layout, ISecurity& security);

// KBOX_SECURE_STORAGE_SIZE == 1560u when KNX_APDU_MAX >= 254, else 1304u.
struct SecureStackStorage {
  alignas(alignof(std::max_align_t)) unsigned char data[KBOX_SECURE_STORAGE_SIZE];
};

ISecurity& MakeSecure(SecureStackStorage& storage, KnxFlashLayout& layout,
                      const SioSizing& sizing, const SioBuffers& buffers,
                      KnxAddress deviceIA, IClock& clock);

// ─── Classic ────────────────────────────────────────────────────────────
struct KnxDeviceStorage {
  KnxFlashLayoutStorage layout;
  KnxStackStorage       stack;
};

KnxFlashLayout& MakeFlashLayout(KnxDeviceStorage& device, IFlash& baseFlash,
                                const StackParameters& sp, uint16_t userDataPageCount);

IKnxStack& MakeStack(KnxDeviceStorage& device, StackParameters& stackParameters,
                     IBusDriver& busDriver, IWatchDog& watchDog, ILed& knxLed,
                     IClock& clock, ITransmitter& transmitter, IButton& button,
                     KnxFlashLayout& layout);

// Usage:
static KnxDeviceStorage device;
KnxFlashLayout& layout = MakeFlashLayout(device, baseFlash, stackParameters, /*userDataPageCount=*/1u);
IKnxStack& stack = MakeStack(device, stackParameters, busDriver, watchDog, knxLed,
                             clock, transmitter, button, layout);

// ─── Secure — S is a `static constexpr SioSizing` bound as a template ref ──
template <const SioSizing& S>
struct KnxSecureDeviceStorage {
  KnxFlashLayoutStorage layout;
  SecureStackStorage    secure;
  KnxStackStorage       stack;
  SioStorage<S>         sio;
};

template <const SioSizing& S>
KnxFlashLayout& MakeFlashLayout(KnxSecureDeviceStorage<S>& device, IFlash& baseFlash,
                                const StackParameters& sp, uint16_t userDataPageCount);

// deviceIA defaults to KnxAddress(0xFFFFu) — the S-Mode "unprogrammed" address;
// pass your own only if the device ships pre-addressed.
template <const SioSizing& S>
ISecurity& MakeSecure(KnxSecureDeviceStorage<S>& device, KnxFlashLayout& layout,
                      IClock& clock, KnxAddress deviceIA = KnxAddress(0xFFFFu));

template <const SioSizing& S>
IKnxStack& MakeStack(KnxSecureDeviceStorage<S>& device, StackParameters& stackParameters,
                     IBusDriver& busDriver, IWatchDog& watchDog, ILed& knxLed,
                     IClock& clock, ITransmitter& transmitter, IButton& button,
                     KnxFlashLayout& layout, ISecurity& security);

// Usage:
static constexpr SioSizing kSioSizing = {5u, 0u, 16u, 8u, 0u};
static KnxSecureDeviceStorage<kSioSizing> device;
KnxFlashLayout& layout = MakeFlashLayout(device, baseFlash, stackParameters, /*userDataPageCount=*/1u);
ISecurity& secure = MakeSecure(device, layout, clock);  // deviceIA default 0xFFFF
IKnxStack& stack = MakeStack(device, stackParameters, busDriver, watchDog, knxLed,
                             clock, transmitter, button, layout, secure);

// Serialize — a TLV record you Push into and iterate with Next().
class Serializable {
 public:
  virtual Serialized Serialize() = 0;
};

class Serialized {
 public:
  Serialized();
  Serialized(uint8_t* data, uint8_t size);
  void       Push(uint8_t* data, SerializedTypeEnum type, uint8_t size);
  void       Push(Serialized serializedData);
  bool       Valid();
  Serialized Next();
  uint8_t    GetType();
  uint8_t*   GetData();
  uint8_t*   GetPayload();
  uint8_t    GetDataSize();
  uint8_t    GetPayloadSize();
};

// Storage — framed blob persistence over an injected IFlash.
class FlashDataStore {
 public:
  explicit FlashDataStore(IFlash& flash);
  bool     Save(const uint8_t* data, uint16_t size);
  uint16_t Load(uint8_t* out, uint16_t maxSize);
  uint16_t Capacity() const;
};