Group Object Tables
The kbox-stack GroupObjectTables — registering group objects, capacity limits, address and object lookups, and sizing tables against an ETS download.
The GroupObjectTables is the stack's registry of group objects and the link between
group addresses (from ETS) and your DeviceObjects. It is fully portable.
Accessing
Reach the database through the stack facade:
GroupObjectTables& tables = stack.Tables();Push & capacity
Register a group object by pushing its address into the database. Do this in your logic's constructor (see Group Objects):
stack.Tables().Push(&onOff_);Two compile-time capacity limits bound the database:
| Constant | Value | Meaning |
|---|---|---|
GroupObjectTables::KBOX_MAX_DEVICE_OBJECTS | 100 | max group objects you can Push |
GroupObjectTables::KBOX_MAX_FANOUT | 32 | max group addresses / objects per fan-out lookup |
These are fixed-capacity limits (FixedVec), not dynamic. Pushing more than
KBOX_MAX_DEVICE_OBJECTS objects, or a fan-out wider than KBOX_MAX_FANOUT,
exceeds the reserved storage. Keep your object count and per-address fan-out
within these bounds.
Lookups
Table sizing vs ETS download
The database is not sized by the objects you push — it is sized by the table
sizes you declare in StackParameters (addressTableSize,
associationTableSize, groupObjectTableSize, applicationProgramSize). Those
sizes must be large enough to hold what an ETS download writes into the
device's flash.
If a download brings more address/association/group-object entries than the
declared sizes allow, the stack raises a size error through onStackError
(SEGMET1..4_SIZE_ERROR, MACHINE_STATE_SIZE_ERROR). The device should stop
safely rather than run with a truncated table — see
Integration Contract · Error contract.
Size the tables to the largest ETS project you intend to support. Under-sizing is
caught at download time by onStackError, not silently truncated — but it does
mean that project cannot be commissioned until the firmware sizes are raised.