esphome::home_io_control::OneWaySequenceStore Class Reference

Per-controller-identity rolling sequence counters, persisted across reboots. More...

#include <oneway_sequence_store.h>

Collaboration diagram for esphome::home_io_control::OneWaySequenceStore:

Public Member Functions
void	add_identity (const uint8_t node_id[NODE_ID_SIZE], uint16_t initial_sequence)
	Register a controller identity and load its persisted counter.
bool	next (const uint8_t node_id[NODE_ID_SIZE], uint16_t &out)
	Reserve and return the next sequence for an identity.
bool	seed (const uint8_t node_id[NODE_ID_SIZE], uint16_t value)
	Force an identity's counter to a specific value and persist it immediately.
bool	peek (const uint8_t node_id[NODE_ID_SIZE], uint16_t &out) const
	The next sequence this identity would hand out, without reserving it.

Detailed Description

Per-controller-identity rolling sequence counters, persisted across reboots.

Keyed on the transmitting node address, not on the command: real capture logs show one remote running a single counter across command types (0x01 → 0x00 → 0x20 at 2416 → 2417 → 2418), so a per-command counter would not match what devices track.

One logical command consumes exactly one sequence. next() is called once, by whatever builds the command — never inside a repeat loop. A 4-frame burst carrying four different sequences is not one command to a device, and burns counter space four times as fast.

Definition at line 71 of file oneway_sequence_store.h.

Member Function Documentation

add_identity()

void esphome::home_io_control::OneWaySequenceStore::add_identity	(	const uint8_t	node_id[NODE_ID_SIZE],
		uint16_t	initial_sequence )

Register a controller identity and load its persisted counter.

Call once per identity at setup. With nothing persisted the counter starts at initial_sequence; otherwise it resumes from whichever of the two is higher. That keeps initial_sequence usable as the day-one remedy for a desynced device — raise it, reflash, and the counter jumps ahead — while making it structurally unable to drag a live counter backwards into replay territory. Use seed() when moving backwards is what you actually mean.

Parameters

node_id	3-byte source address this identity transmits as.
initial_sequence	Value to start from when nothing is persisted, or to jump forward to.

Definition at line 51 of file oneway_sequence_store.cpp.

next()

bool esphome::home_io_control::OneWaySequenceStore::next	(	const uint8_t	node_id[NODE_ID_SIZE],
		uint16_t &	out )

Reserve and return the next sequence for an identity.

Durably reserves before returning: when the in-RAM block is exhausted this persists the end of the next block and syncs it to flash before handing anything back, so a caller can never transmit a value the hub has not already committed to never reusing. A crash between the write and the transmit costs one skipped sequence; the reverse ordering would risk a reuse.

Parameters

node_id	Identity's 3-byte source address.
out	Output: the sequence to transmit.

Returns

false if the address is not a registered identity, or if the reservation could not be persisted — in both cases nothing is handed out and nothing may be transmitted.

Definition at line 76 of file oneway_sequence_store.cpp.

peek()

bool esphome::home_io_control::OneWaySequenceStore::peek	(	const uint8_t	node_id[NODE_ID_SIZE],
		uint16_t &	out ) const

The next sequence this identity would hand out, without reserving it.

Unlike next(), this does not commit to transmitting the value it returns — it does not reserve, persist, or advance the counter.

Parameters

node_id	Identity's 3-byte source address.
out	Output: the sequence next() would return.

Returns

false if the address is not a registered identity.

Definition at line 112 of file oneway_sequence_store.cpp.

seed()

bool esphome::home_io_control::OneWaySequenceStore::seed	(	const uint8_t	node_id[NODE_ID_SIZE],
		uint16_t	value )

Force an identity's counter to a specific value and persist it immediately.

Unlike add_identity(), this may move the counter backwards, which is the whole point — re-seed from a sequence observed on air, or from a user's estimate, when a counter has desynced from the device. Today's documented remedy for a desynced counter is initial_sequence: (docs/home_io_control.md troubleshooting), which goes through add_identity() at boot instead.

Parameters

node_id	Identity's 3-byte source address.
value	Next sequence to hand out.

Returns

false if the address is not registered or the write could not be persisted.

Definition at line 99 of file oneway_sequence_store.cpp.

---

The documentation for this class was generated from the following files:

• components/home_io_control/oneway_sequence_store.h
• components/home_io_control/oneway_sequence_store.cpp