aaribaud/ESPSomfy-RTS
0
0
Fork 0
mirror of https://github.com/rstrouse/ESPSomfy-RTS.git synced 2026-10-31 13:52:15 +01:00
Code Issues Projects Releases Packages Wiki Activity

docs: ADRs 0005-0007 for socket protocol 2

Browse source 
ADR 0005: the web UI and Home Assistant talk to the device over one
websocket protocol (ops on loop(), sync with next, a JSON envelope a
binary encoding can reuse, short keys described by a schema).
ADR 0006: two security modes and eleven HTTP routes on port 80.
ADR 0007: the firmware no longer updates itself from GitHub.

ADR 0002 is amended: its single-writer rule stands, but edits now get
one reply and reads no longer go through a ModelSnapshot.
SECURITY_PLAN.md is revised to match, and keeps the token key, login
backoff, CORS and Origin work. PROTOCOL.md starts as an outline, and
GLOSSARY.md gains the socket protocol and security terms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
cjkas 2026-10-22 20:50:33 +02:00
parent 539a49eb77
commit e25747d395
7 changed files with 202 additions and 52 deletions
Download patch file Download diff file Expand all files Collapse all files

35
GLOSSARY.md
View file

@ -113,6 +113,41 @@ _Avoid_: MQTTClass
**Change fan-out**
What sends everything that changed about a shade or group in one pass of `loop()` once: its changed MQTT topics, then one state event.
## Socket protocol
**Op**
A request a client sends over the socket: a command, a read, a model edit or a settings change.
_Avoid_: action, call
**Reply**
The answer to one op, sent only to the client that sent it: done, or an error with a code. Every op gets exactly one.
_Avoid_: response, request result
**Event**
A message the device sends without being asked: a change to a shade, group, room or setting, or a status update. Events come from the change fan-out and go to every client allowed to see them.
_Avoid_: increment, push
**Sync**
How a client catches up with the device: the shade model and status, sent item by item at the client's pace, after which events keep it current. It describes no single moment.
_Avoid_: snapshot (a ModelSnapshot is a copy of one moment), initial load
**Feed**
A stream of events a client subscribes to on its own, such as received remote frames or a frequency scan.
_Avoid_: topic (MQTT's word), room (a room is part of the shade model)
**Schema**
The device's description of the protocol it speaks: what each message type, field and error code is, and what a field is when left out.
## Security
**Security mode**
Whether the device asks for login: *None* (everything open) or *Secured* (a PIN or password).
_Avoid_: Secure Config Only (removed)
**Token**
What logging in returns. It stands for the PIN or password, on one client address, and every request under Secured carries it.
_Avoid_: session, API key (the name of the field it travels in)
## Domain modules
**Domain module**