diff --git a/README.md b/README.md index 0e596d3..f14524a 100644 --- a/README.md +++ b/README.md @@ -229,6 +229,7 @@ And one that serves a machine to lab software: - [`examples/sila`](examples/sila) — one field of each kind (switch, level, discrete, select, analog volts, text, command in presented units, action) served as SiLA 2 features by a Python gateway, from a Nano or on the host with the endpoints simulated. + The rules any such consumer follows are in [`docs/consumers.md`](docs/consumers.md). And one on a second bus: diff --git a/docs/consumers.md b/docs/consumers.md new file mode 100644 index 0000000..5aa5ff9 --- /dev/null +++ b/docs/consumers.md @@ -0,0 +1,77 @@ +# Consumers: serving a machine to another protocol + +A machine speaks one thing: its link. A *consumer* is a program on the other side of that link that presents the machine in +another protocol's terms: a SiLA 2 server for lab software, a broker client for a home-automation system, a node set for an +industrial controller. The machine is built once and knows none of them; each consumer is written once and serves any machine +whose roles it understands. + +[`examples/sila`](../examples/sila) is the worked example: a Python gateway that turns any machine built from its eight role +kinds into a SiLA 2 server. + +## What the machine provides + +Nothing consumer-specific, when the consumer is on the other side of the link. The firmware is built with the link +(`role::Link`) and its roles' kinds; it carries no protocol library, no protocol vocabulary and no generated files. A consumer +gets two things over the link: + +- **The description**, read once at connect (`m`, `c`, `r`): roles, kinds, parameters, field names and types, and the lines a + kind prints about its values (`value`, `scale`, `unit`; see [role.md](role.md#the-consumers-contract)). +- **The frames**, binary and positional, checked by hash, for every command and report. + +Everything the other protocol needs (its own self-description, types, constraints, units, names) is built from those two on +the consumer's side. A machine that a consumer can serve can be served by every other consumer that knows the same kinds, with +no change to its firmware. + +## The rules + +These hold for any consumer; the SiLA gateway is how each looks in practice. + +1. **One table: kind to the protocol's words.** The consumer's knowledge of machines is a table with one row per role kind. A + row is about a kind, never about a machine: "a `light`'s `level` is bounded by its `max` parameter", not "the lamp goes to + 200". Everything machine-specific (role names, limits, allowed values, labels, scales, units, text lengths) is read from the + description at connect. In `examples/sila` the table is `KINDS` in `gateway.py`. + +2. **The protocol's self-description is generated, never written by hand.** The SiLA gateway writes each feature definition + (FDL) from the description at start. Change a limit or a label in the firmware and, after a reconnect, the consumer serves + the new one; nothing to edit, nothing to keep in step. + +3. **What the consumer does not know, it refuses, by name.** A role of a kind not in its table, a description line the kind's + row does not use, a unit symbol not in its unit table: the consumer stops and names the role and the thing. It never guesses + a meaning, and never serves part of a machine silently. + +4. **A binding exposes only what its protocol can represent.** A protocol constraint that a client reads once at connect (a + SiLA minimum or maximum, an allowed set) is generated only from values fixed in the firmware. A value that can change at + run time is a readable value, never a constraint. `examples/sila` meets it by refusing tuned roles: their run-time values + are not served yet. + +5. **Validation at the consumer's edge; the device is the backstop.** Values outside a constraint are refused by the consumer + with the protocol's own error, and nothing reaches the device. A value that reaches the device anyway (a client bypassing + the consumer) is handled by the kind: clamped to its bound, or ignored when not one of its allowed values. Either way the + report carries the value the device holds, and the report is the truth (a command in presented units is rounded to the + nearest raw value and read back as it was applied). + +6. **The consumer holds nothing.** Each command is forwarded once, when the client sends it; nothing is resent, nothing kept + alive on the client's behalf. Whatever the device does when commands stop is the device's own behaviour, unchanged by which + consumer is attached. Commands are serialised on the link, so concurrent client calls cannot interleave in a frame. + +7. **One consumer process serves one machine, with a stable identity.** The SiLA gateway derives its server UUID from its + originator and the machine hash: the same firmware is always the same server, and a different description is a different + server. + +## Adding a kind + +A kind is usable by a consumer once that consumer's table has a row for it. Until then, a machine with a role of that kind is +refused by that consumer, by name. Kinds and consumers grow independently: a new kind is one row in each consumer that wants +it; a new consumer is one table over the kinds that exist. + +When a kind's meaning needs more than its fields and parameters say (which values are allowed, what they are called, what unit +a field is in), the kind prints it in the description (`value`, `scale`, `unit`), so every consumer reads it from the same +place instead of carrying its own copy. + +## Adding a consumer + +1. Map each kind you need to the protocol's words: type, constraints, unit, readable or commandable. Write it as the table. +2. Generate the protocol's self-description from the machine description; check it against the protocol's own schema where one + exists (SiLA: the FDL schema from `sila_base`). +3. Refuse everything outside the table, by name. +4. Check with a client you did not write: an independent implementation of the protocol, against a real machine. diff --git a/docs/role.md b/docs/role.md index ae7efd3..8cc2850 100644 --- a/docs/role.md +++ b/docs/role.md @@ -66,6 +66,8 @@ state descriptions. The command and report hashes cover the role names and the k kinds, parameters and references. The `at` lines (where each role is) are shown to people and are in no hash. The start of the test machine's description (`test/role/machine.h`): +A consumer that presents a machine in another protocol (SiLA 2, for one) is described in [consumers.md](consumers.md). + ``` machine 1 hash a9c67c1d diff --git a/examples/sila/README.md b/examples/sila/README.md index 748728d..069af5c 100644 --- a/examples/sila/README.md +++ b/examples/sila/README.md @@ -73,7 +73,8 @@ c.Duty.SetValue(100.01) # ValidationError: the server refuses it, | `note` (`text`) | `text`, a `u8[16]` array | `Note`: `Text`, `SetText(Text)` | String, MaximalLength 16, Pattern `[ -~]*` (printable ASCII) | | `duty` (`scaled`) | `raw`, with `max`, a `scale` and a `unit` line | `Duty`: `Value`, `SetValue(Value)` | Real, Unit % (dimensionless, factor 0.01), minimum 0, maximum 100 = `max` * 1 / 10 | -The kinds `light` and `switch` are OneMachine's (`role/kinds.h`); the other six are in `src/kinds.h`. The lines a kind prints +The kinds `light` and `switch` are OneMachine's (`role/kinds.h`); the other six are in `src/kinds.h`. The rules any such consumer follows, and how to add a kind or another consumer, are in +[docs/consumers.md](../../docs/consumers.md). The lines a kind prints in the machine description (`value`, `scale`, `unit`) are described in [docs/role.md](../../docs/role.md). One generated definition (`Mode`, trimmed): @@ -105,10 +106,11 @@ description (a role, a label, a unit) is a different server. a tuned role, a description line the kind's row does not use, a unit symbol the unit table (`UNITS`: `V` and `%`) does not have, a label used twice, or a scale whose bound is not a finite decimal: the gateway exits with a message that names the role and the thing. It never guesses. -- **Out of range is refused at the SiLA edge; the device ignores it anyway.** `SetLevel(250)`, `SetValue(7)` on `step`, +- **Out of range is refused at the SiLA edge; the device is the backstop.** `SetLevel(250)`, `SetValue(7)` on `step`, `SetValue('max')` on `mode`, a 17-character or non-ASCII text, `Duty.SetValue(100.01)` or `-0.1` are validation errors - from the server's constraint check: no frame goes to the board. A client that bypasses SiLA and sends such a value to the board - is ignored by the device, which keeps the previous value and reports it. + from the server's constraint check: no frame goes to the board. A client that bypasses SiLA and sends such a value straight to + the board gets what the kind does: `lamp` (a `light`) is **clamped** to its bound (200) and its report says `clamped`; `step`, + `mode`, `note` and `duty` **ignore** the value, keep the previous one and report it. - **A numeric command in presented units is rounded, and the report is the truth.** `Duty.SetValue(12.35)` becomes the raw value 124 (the client's decimal, times 10 / 1, to the nearest integer, halves away from zero) and `Duty.Value` then reads 12.4: the value the device holds. Enumerated fields (`step`, `mode`) are not rounded: anything not in the set is refused.