Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
77 changes: 77 additions & 0 deletions docs/consumers.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 2 additions & 0 deletions docs/role.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 6 additions & 4 deletions examples/sila/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):

Expand Down Expand Up @@ -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.
Expand Down
Loading