From e5b44e092d13386d4e6da99f414246693f003a96 Mon Sep 17 00:00:00 2001 From: neu-rah Date: Thu, 8 Oct 2026 22:28:10 +0000 Subject: [PATCH 1/4] python/onemachine: role_facts, what a kind says about a role, for every consumer A consumer's table is about its protocol's words. What a kind says about a role does not depend on the protocol: the fields it reports and commands, what bounds the command (a light's max), the values and labels, the scale and unit, a text's length, and the arithmetic between a raw integer and a presented value. role_facts(machine, role) reads them from the description and the command and report schemas, and refuses by name a description that does not hold what its kind needs. test/role/facts_check.py holds it to the examples/sila machine (46 checks) and runs in test/role/build.sh. Co-Authored-By: Claude Sonnet 5.5 --- python/onemachine/__init__.py | 2 +- python/onemachine/machine.py | 124 ++++++++++++++++++++++++++++++++++ test/role/build.sh | 5 +- test/role/facts_check.py | 119 ++++++++++++++++++++++++++++++++ 4 files changed, 248 insertions(+), 2 deletions(-) create mode 100644 test/role/facts_check.py diff --git a/python/onemachine/__init__.py b/python/onemachine/__init__.py index de41cb0..87a4ff3 100644 --- a/python/onemachine/__init__.py +++ b/python/onemachine/__init__.py @@ -1,4 +1,4 @@ """OneMachine from Python: a machine's roles, command and report, read from the device's own description (docs/role.md).""" from .schema import Schema, SchemaError, BadHash, BadLength -from .machine import Machine, Description, StreamLink, CtypesLink, LinkError, RoleChanged, OutOfLimits +from .machine import Machine, Description, StreamLink, CtypesLink, LinkError, RoleChanged, OutOfLimits, Facts, KindError, KINDS, role_facts from .tree import Tree, Code, Change, Reading, Stale, OutOfRange, ReadOnly, UnknownCode diff --git a/python/onemachine/machine.py b/python/onemachine/machine.py index 6d9c581..75eade8 100644 --- a/python/onemachine/machine.py +++ b/python/onemachine/machine.py @@ -8,6 +8,7 @@ m.push() # sent; the device applies it at its next cycle boundary m.poll().x.pos_um # the report; `live` is False for a role whose device is not there m.roles['x'].tuned # a role::Tuned role: its parameters can change at run time + f = role_facts(m, 'x') # what the description says about x, read through its kind (below) m.tune.x.max_um = 200000; m.retune() # within the firmware's limits (the `param` values); outside them: OutOfLimits Where a role is (which device, which bus, which channel) is the device's business: the `at` lines are shown to people (m.where), @@ -15,6 +16,9 @@ and keep every command value whose role and field still exist. A role this consumer has written that is gone, or has another kind, raises RoleChanged instead of being retargeted.""" import re, struct, subprocess +from decimal import Decimal +from fractions import Fraction +from collections import namedtuple from .schema import Schema, SchemaError, BadHash OK, BAD_HASH, BAD_LENGTH, BAD_VALUE, UNKNOWN, TOO_LONG = 0, 1, 2, 3, 0x80, 0x81 @@ -219,3 +223,123 @@ def poll(self): def __getattr__(self, name): # m.x is the command of role x if name in ('cmd', 'description', 'tune', 'tune_schema') or name.startswith('_'): raise AttributeError(name) return getattr(self.cmd, name) + + +# ---- what a kind says about its roles, whatever the consumer: which field is reported and commanded, what bounds it, which values it takes, +# how a raw integer is presented. A consumer keeps its protocol's words (types, constraints, units) in its own table and reads these facts. +Kind = namedtuple('Kind', 'report command upper lines') # the report field, the command field (None: report only), the param bounding the command field (0..param), the description lines the kind prints +KINDS = { + 'switch': Kind('on', 'on', None, ()), + 'light': Kind('level', 'level', 'max', ()), + 'discrete': Kind('value', 'value', None, ('value',)), + 'select': Kind('index', 'index', None, ('value',)), + 'analog': Kind('raw', None, None, ('scale', 'unit')), + 'text': Kind('text', 'text', None, ()), + 'scaled': Kind('raw', 'raw', 'max', ('scale', 'unit')), + 'action': Kind('fired', 'fire', None, ()), +} +INT_RANGE = {'u8': (0, 255), 'u16': (0, 65535), 'u32': (0, 2**32 - 1), 'i8': (-128, 127), 'i16': (-32768, 32767), 'i32': (-2**31, 2**31 - 1)} + +class KindError(ValueError): + """A role's description, command or report does not hold what its kind says it does; the message names the role and the thing.""" + +class Facts: + """One role read through its kind (role_facts). Attributes, None or empty where the kind has none: + report, command the report field and the command field (command is None for a report-only kind) + low, high the raw range the kind bounds the command field to: light 0..max, scaled 0..max + values, labels the raw values the role takes, and their labels (a select: parallel tuples) + scale, unit (num, den) and the unit symbol: presented = raw * num / den + size the length of a text role's byte array + report_fields the names of the role's report fields (live, and clamped for a light) + command_type the command field's integer type (u16, ...)""" + def __init__(self, name, kind): + self.name, self.kind, k = name, kind, KINDS[kind] + self.report, self.command = k.report, k.command + self.low = self.high = self.scale = self.unit = self.size = self.command_type = None + self.values, self.labels, self.report_fields = (), (), () + def __repr__(self): return 'Facts(%s %s)' % (self.name, self.kind) + + def presented(self, raw): + """raw -> the presented value, exactly (a Fraction): raw * num / den""" + return Fraction(int(raw) * self.scale[0], self.scale[1]) + def to_raw(self, value): + """presented -> raw: the exact rational of the shortest decimal that round-trips the client's number, times den / num, to the nearest integer, + halves away from zero. Integer arithmetic only: no round(), no float multiply.""" + x = Fraction(Decimal(repr(float(value)))) * self.scale[1] / self.scale[0] + p, q = abs(x.numerator), x.denominator + r = (2 * p + q) // (2 * q) + return -r if x < 0 else r + def label_of(self, raw): + for v, label in zip(self.values, self.labels): + if v == int(raw): return label + raise LinkError('role %s: the report says %d, which no `value` line names' % (self.name, raw)) + def raw_of(self, label): + for v, l in zip(self.values, self.labels): + if l == label: return v + raise KeyError(label) + def pack_text(self, text): + """a text -> the command's byte array: ASCII, NUL-padded (nothing of an older, longer text stays); ValueError outside the buffer or printable ASCII""" + b = text.encode('ascii') + if len(b) > self.size or not all(0x20 <= c <= 0x7e for c in b): raise ValueError('text outside the buffer or printable ASCII') + return list(b) + [0] * (self.size - len(b)) + def unpack_text(self, array): + return bytes(array).split(b'\0', 1)[0].decode('ascii', 'replace') + +def role_facts(m, name): + """The Facts of role `name` of Machine m, or KindError. Checks the description against the kind: only the lines the kind prints, the fields it reports and + commands present with the types it needs, the bound param, distinct values, unique labels, a positive scale for a scaled value, a flag that is unsigned.""" + info = m.roles[name] + if info.kind not in KINDS: raise KindError('role %s is of kind %r; python/onemachine has facts for %s' % (name, info.kind, ', '.join(sorted(KINDS)))) + k, f = KINDS[info.kind], Facts(name, info.kind) + def refuse(why): raise KindError('role %s (%s): %s' % (name, info.kind, why)) + for line, present in (('value', info.values), ('scale', info.scales), ('unit', info.units)): + if present and line not in k.lines: refuse('its description has %s lines, which the %s kind does not print' % (line, info.kind)) + fields = {} + for what, schema, field in (('command', m.command_schema, k.command), ('report', m.report_schema, k.report)): + if field is None: continue + layer = schema.layer(name) + fld = next((x for x in layer.fields if x.name == field), None) if layer else None + if info.kind == 'text': + if fld is None or not fld.n or fld.base != 'u8': refuse('its %s has no u8 array %r' % (what, field)) + elif fld is None or fld.n: refuse('its %s has no scalar %r' % (what, field)) + elif info.kind == 'switch' and fld.base != 'bool': refuse('its %s %r is %s, not bool' % (what, field, fld.base)) + elif info.kind != 'switch' and fld.base not in INT_RANGE: refuse('its %s %r is %s, which is no integer' % (what, field, fld.base)) + fields[what] = fld + f.report_fields = tuple(x.name for x in m.report_schema.layer(name).fields) + if k.command is not None: + f.command_type = fields['command'].base + tlo, thi = INT_RANGE.get(f.command_type, (0, 1)) + if info.kind == 'light': + if k.upper not in info.params: refuse('no param %r in its description, and the %s kind says it bounds %r' % (k.upper, info.kind, k.command)) + lo, hi = 0, info.params[k.upper] + if not (tlo <= lo <= hi <= thi): refuse('bound [%d, %d] does not fit the %s field %r' % (lo, hi, f.command_type, k.command)) + f.low, f.high = lo, hi + elif info.kind in ('discrete', 'select'): + if not info.values: refuse('no %s in its description (`value` lines)' % ('allowed values' if info.kind == 'discrete' else 'values')) + vals = [v for v, _ in info.values] + if info.kind == 'discrete' and any(label is not None for _, label in info.values): refuse('a value has a label, which the discrete kind does not use') + if info.kind == 'select': + unlabelled = [v for v, label in info.values if label is None] + if unlabelled: refuse('value %s has no label' % unlabelled[0]) + if len(set(vals)) != len(vals) or not all(tlo <= v <= thi for v in vals): refuse('values %s are not distinct values of the %s field %r' % (vals, f.command_type, k.command)) + if info.kind == 'select': + labels = [label for _, label in info.values] + if len(set(labels)) != len(labels): refuse('two values have the same label (%s)' % ', '.join(labels)) + f.labels = tuple(labels) + f.values = tuple(vals) + elif info.kind in ('analog', 'scaled'): + for line, d in (('scale', info.scales), ('unit', info.units)): + if set(d) != {k.report}: refuse('the description needs one `%s` line, for the field %r (it has %s)' % (line, k.report, sorted(d) or 'none')) + f.scale, f.unit = info.scales[k.report], info.units[k.report] + if info.kind == 'scaled': + if k.upper not in info.params: refuse('no param %r in its description, and the %s kind says it bounds %r' % (k.upper, info.kind, k.command)) + if f.scale[0] <= 0 or f.scale[1] <= 0: refuse('scale %d/%d is not positive' % f.scale) + hi = info.params[k.upper] + if not (0 <= hi <= thi): refuse('bound [0, %d] does not fit the %s field %r' % (hi, f.command_type, k.command)) + f.low, f.high = 0, hi + elif info.kind == 'text': + if fields['command'].n != fields['report'].n: refuse('its command buffer is %d bytes and its report %d' % (fields['command'].n, fields['report'].n)) + f.size = fields['command'].n + elif info.kind == 'action': + if INT_RANGE[f.command_type][0] != 0: refuse('its command %r (%s) is signed; the flag is 0 or 1 of an unsigned field' % (k.command, f.command_type)) + return f diff --git a/test/role/build.sh b/test/role/build.sh index 494c45d..56a7e1c 100755 --- a/test/role/build.sh +++ b/test/role/build.sh @@ -5,7 +5,7 @@ # rules each rule of role::Machine and the kinds is a compile error with its own message (g++, clang++, avr-g++) # python python/onemachine drives the test machine as a consumer that knows only role names (check.py), across four firmware # variants (rewired, a role added, a role removed), over a pipe and in-process through ctypes (CtypesLink); its Schema against test/state's native peers (check_schema.py); -# examples/python's drive.py against that example's host build +# examples/python's drive.py against that example's host build; python/onemachine's facts for each kind (facts_check.py) against examples/sila's host build # AVR avr-g++ -Os atmega328p in simavr: the role layer's cost per request and per scan, Fixed vs Found vs Pinned, the link, and # role::Tuned (run-time parameters) # HAPI= overrides the HAPI checkout used (default: next to this repo). @@ -73,6 +73,9 @@ if have python3; then if g++ -std=c++17 -O2 -Wall -Wextra -Werror "${F[@]}" ../../examples/python/host/main.cpp -o "$W/exhost" 2>"$W/err"; then python3 ../../examples/python/drive.py --sim "$W/exhost" --check > "$W/ex.out" 2>&1 && ok "examples/python: drive.py against the host build, $(grep -c '^ ok' "$W/ex.out") checks" || bad "examples/python drive.py" "$(grep -E 'FAIL|Error' "$W/ex.out" | head -3)" else bad "examples/python host build" "$(grep -m1 error "$W/err")"; fi + if g++ -std=c++17 -O2 -Wall -Wextra -Werror "${F[@]}" ../../examples/sila/host/main.cpp -o "$W/silahost" 2>"$W/err"; then + python3 facts_check.py "$W/silahost" > "$W/facts.out" 2>&1 && ok "facts_check.py: $(grep -c '^ ok' "$W/facts.out") checks of what a kind says about a role, against examples/sila's host build" || bad "facts_check.py" "$(grep FAIL "$W/facts.out" | head -3)" + else bad "examples/sila host build" "$(grep -m1 error "$W/err")"; fi g++ -std=c++17 -O1 "${F[@]}" -I../state ../state/host_peer.cpp -o "$W/hp" && g++ -std=c++17 -O1 "${F[@]}" -I../state ../state/array_check.cpp -o "$W/ap" && { python3 check_schema.py "$W/hp" "$W/ap" > "$W/sc.out" 2>&1 && ok "check_schema.py: $(grep -c '^ok' "$W/sc.out") checks against the native state peers" || bad "check_schema.py" "$(grep FAIL "$W/sc.out" | head -3)"; } else note python "no python3: the consumer checks did not run"; fi diff --git a/test/role/facts_check.py b/test/role/facts_check.py new file mode 100644 index 0000000..c34fe6f --- /dev/null +++ b/test/role/facts_check.py @@ -0,0 +1,119 @@ +#!/usr/bin/env python3 +"""python/onemachine's facts for a kind (role_facts): facts_check.py +What the description of the examples/sila machine says through each of its eight kinds; the arithmetic between raw and presented values; and each refusal, by name.""" +import os, sys +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '../../python')) +from fractions import Fraction +from onemachine import Machine, StreamLink, KindError, LinkError, role_facts, KINDS +from onemachine.machine import _fnv, OK +from onemachine.schema import Field, Layer + +fails = 0 +def check(what, cond, extra=''): + global fails + print(' %-5s %s%s' % ('ok' if cond else 'FAIL', what, (' ' + str(extra)) if extra and not cond else '')); fails += 0 if cond else 1 + +m = Machine(StreamLink.popen([sys.argv[1]])) +F = {name: role_facts(m, name) for name in m.roles} +check('the eight kinds of the table are the eight roles of the machine', sorted(KINDS) == sorted(r.kind for r in m.roles.values()) and len(F) == 8) + +# ---- the facts of each role +f = F['led']; check('switch: reports and commands `on`, nothing else', (f.report, f.command, f.low, f.high, f.values, f.scale, f.unit, f.size) == ('on', 'on', None, None, (), None, None, None)) +f = F['lamp']; check('light: `level`, bounded 0..max (param lamp max 200)', (f.report, f.command, f.low, f.high, f.command_type) == ('level', 'level', 0, 200, 'u16')) +check('light: its report has `clamped` and `live`', {'level', 'clamped', 'live'} <= set(f.report_fields), f.report_fields) +f = F['step']; check('discrete: `value`, the allowed values in order', (f.command, f.values, f.labels) == ('value', (0, 10, 50, 100), ())) +f = F['mode']; check('select: `index`, values and labels in order', (f.report, f.command, f.values, f.labels) == ('index', 'index', (0, 1, 2), ('off', 'low', 'high'))) +f = F['vin']; check('analog: reports `raw`, no command, scale 5/1023, unit V', (f.report, f.command, f.scale, f.unit, f.low, f.high) == ('raw', None, (5, 1023), 'V', None, None)) +f = F['note']; check('text: `text`, 16 bytes', (f.report, f.command, f.size) == ('text', 'text', 16)) +f = F['duty']; check('scaled: `raw` 0..1000, scale 1/10, unit %', (f.report, f.command, f.low, f.high, f.scale, f.unit) == ('raw', 'raw', 0, 1000, (1, 10), '%')) +f = F['ping']; check('action: reports `fired`, commands `fire`', (f.report, f.command) == ('fired', 'fire')) +check('only the commandable kinds have a command field', sorted(n for n, x in F.items() if x.command is None) == ['vin']) + +# ---- raw <-> presented +d = F['duty'] +check('presented: raw 123 is exactly 12.3', d.presented(123) == Fraction(123, 10)) +edge = [(12.34, 123), (12.35, 124), (12.36, 124), (0.04, 0), (0.05, 1), (99.95, 1000), (100, 1000), (-0.05, -1), (-0.04, 0), (0.15, 2), (0.25, 3)] +check('to_raw: nearest integer of the decimal as written, halves away from zero', all(d.to_raw(v) == r for v, r in edge), [(v, d.to_raw(v), r) for v, r in edge if d.to_raw(v) != r]) +check('to_raw takes the decimal the client wrote (12.35), not the binary double below it', Fraction(12.35) < Fraction(1235, 100) and d.to_raw(12.35) == 124) +v = F['vin'] +check('analog presented: float(presented) is float(raw) * 5 / 1023 for every u16 raw', all(float(v.presented(r)) == float(r) * 5 / 1023 for r in range(65536))) +s = F['mode'] +check('select: label_of / raw_of', (s.label_of(2), s.raw_of('low')) == ('high', 1)) +try: s.label_of(9); check('select: a raw no `value` line names is a LinkError', False) +except LinkError as e: check('select: a raw no `value` line names is a LinkError naming the role', 'mode' in str(e) and '9' in str(e)) +try: s.raw_of('max'); check('select: an unknown label is a KeyError', False) +except KeyError: check('select: an unknown label is a KeyError', True) +n = F['note'] +check('text: packed ASCII, NUL-padded to the buffer, unpacked up to the first NUL', n.pack_text('hi') == [104, 105] + [0] * 14 and n.unpack_text(n.pack_text('hi Rui')) == 'hi Rui' and n.unpack_text([0] * 16) == '') +for what, text in (('17 characters', 'x' * 17), ('non-ASCII', 'hé'), ('a control character', 'a\tb')): + try: n.pack_text(text); check('text: %s is refused' % what, False) + except ValueError: check('text: %s is refused' % what, True) + +# ---- refusals, by name: the machine's own description with one line changed (the hash recomputed), over the same command and report descriptions +base = {op: m.link.call(op)[1].decode() for op in 'mcr'} +lines = [l for l in base['m'].split('\n') if l][2:] +def rehash(ls): + h = 2166136261 + for l in ls: + if not l.startswith('at '): h = _fnv(h, (l + '\n').encode()) + return 'machine 1\nhash %08x\n%s\n' % (h, '\n'.join(ls)) +class Fake: + def __init__(self, text): self.text = text + def call(self, op, payload=b''): + op = op if isinstance(op, str) else chr(op) + return OK, (self.text if op == 'm' else base[op]).encode() +def refused(what, edit, role, *words): + ls = list(lines); edit(ls) + try: + mm = Machine(Fake(rehash(ls))); role_facts(mm, role); check('refused: %s' % what, False) + except KindError as e: check('refused: %s -> %s' % (what, e), role in str(e) and all(w in str(e) for w in words), e) +def sub(ls, old, new): ls[ls.index(old)] = new +def drop(ls, *olds): + for o in olds: ls.remove(o) +def after(ls, line, *new): i = ls.index(line); ls[i + 1:i + 1] = list(new) +refused('a light with no `max` param', lambda ls: drop(ls, 'param lamp max 200'), 'lamp', "'max'", 'level') +refused('a light whose max does not fit its field (70000 in a u16)', lambda ls: sub(ls, 'param lamp max 200', 'param lamp max 70000'), 'lamp', '70000', 'u16') +refused('a discrete with no `value` lines', lambda ls: drop(ls, *[l for l in ls if l.startswith('value step')]), 'step', 'value') +refused('a discrete with a repeated value', lambda ls: sub(ls, 'value step 50', 'value step 10'), 'step', 'not distinct') +refused('a discrete value with a label', lambda ls: sub(ls, 'value step 50', 'value step 50 fifty'), 'step', 'label') +refused('a select value with no label', lambda ls: sub(ls, 'value mode 2 high', 'value mode 2'), 'mode', 'value 2 has no label') +refused('a select with a repeated label', lambda ls: sub(ls, 'value mode 2 high', 'value mode 2 low'), 'mode', 'same label', 'low') +refused('a `unit` line on a switch', lambda ls: after(ls, 'role led switch', 'unit led on V'), 'led', 'unit lines') +refused('a `value` line on a light', lambda ls: after(ls, 'role lamp light', 'value lamp 5 five'), 'lamp', 'value lines') +refused('an analog with no `scale` line', lambda ls: drop(ls, 'scale vin raw 5 1023'), 'vin', 'scale') +refused('an analog whose `unit` is for another field', lambda ls: sub(ls, 'unit vin raw V', 'unit vin other V'), 'vin', 'unit') +refused('a scaled with a scale of 0/10', lambda ls: sub(ls, 'scale duty raw 1 10', 'scale duty raw 0 10'), 'duty', 'not positive') +refused('a scaled with no `max` param', lambda ls: drop(ls, 'param duty max 1000'), 'duty', "'max'") +refused('a scaled whose max does not fit its field', lambda ls: sub(ls, 'param duty max 1000', 'param duty max 70000'), 'duty', '70000') +check('the machine as it is is accepted by every refusal harness', all(role_facts(Machine(Fake(rehash(list(lines)))), n) for n in m.roles)) + +# ---- the field-shape refusals: stub schemas with one field changed +class S: + def __init__(self, **layers): self.l = layers + def layer(self, name): return self.l.get(name) +def layer(*fields): + l = Layer('x'); l.fields = [Field(*x) for x in fields]; return l +class M: + def __init__(self, kind, cmd, rep, **params): + from onemachine.machine import RoleInfo + r = RoleInfo('x', kind); r.params = params + if kind in ('discrete', 'select'): r.values = [(0, 'a' if kind == 'select' else None), (1, 'b' if kind == 'select' else None)] + if kind in ('analog', 'scaled'): r.scales, r.units = {'raw': (1, 1)}, {'raw': 'V'} + self.roles, self.command_schema, self.report_schema = {'x': r}, S(x=cmd), S(x=rep) +live = ('live', 'bool', None) +def shape(what, kind, cmd, rep, *words, **params): + try: role_facts(M(kind, cmd, rep, **params), 'x'); check('refused: %s' % what, False) + except KindError as e: check('refused: %s -> %s' % (what, e), 'role x' in str(e) and all(w in str(e) for w in words), e) +shape('a switch whose command is not a bool', 'switch', layer(('on', 'u8', None)), layer(('on', 'bool', None), live), 'command', 'not bool') +shape('a light with no `level` in its report', 'light', layer(('level', 'u16', None)), layer(('lvl', 'u16', None), live), 'report', "'level'", max=10) +shape('a light whose level is an array', 'light', layer(('level', 'u8', 4)), layer(('level', 'u16', None), live), 'command', 'scalar', max=10) +shape('a light whose level is a bool', 'light', layer(('level', 'bool', None)), layer(('level', 'u16', None), live), 'command', 'bool', 'no integer', max=10) +shape('a text whose command is a u16 array', 'text', layer(('text', 'u16', 4)), layer(('text', 'u8', 4), live), 'command', 'u8 array') +shape('a text whose command and report buffers differ', 'text', layer(('text', 'u8', 4)), layer(('text', 'u8', 8), live), '4 bytes', '8') +shape('an action whose command flag is signed', 'action', layer(('fire', 'i8', None)), layer(('fired', 'u16', None), live), 'signed') +ok = role_facts(M('action', layer(('fire', 'u8', None)), layer(('fired', 'u16', None), live)), 'x') +check('the same action with an unsigned flag is accepted', ok.command_type == 'u8') +try: role_facts(M('axis', layer(), layer()), 'x'); check('refused: a kind the table does not have', False) +except KindError as e: check('refused: a kind the table does not have -> %s' % e, 'axis' in str(e) and 'role x' in str(e)) + +print('FAILED' if fails else 'ok'); sys.exit(1 if fails else 0) From f11effbedce796d765d9e9a4b96acf1f23541494 Mon Sep 17 00:00:00 2001 From: neu-rah Date: Thu, 8 Oct 2026 22:28:10 +0000 Subject: [PATCH 2/4] examples/sila: the gateway reads the kind facts from python/onemachine Its table keeps the SiLA words (type, property, command, parameter); the description's field names, the bounds, values, labels, scale, unit, the text length and the presented/raw arithmetic come from role_facts. The feature definitions it generates are unchanged. Co-Authored-By: Claude Sonnet 5.5 --- examples/sila/gateway.py | 145 ++++++++++++--------------------------- 1 file changed, 42 insertions(+), 103 deletions(-) diff --git a/examples/sila/gateway.py b/examples/sila/gateway.py index 6605634..e603046 100755 --- a/examples/sila/gateway.py +++ b/examples/sila/gateway.py @@ -6,7 +6,9 @@ python3 gateway.py ... --generate write the feature definitions to --fdl-dir (default ./fdl) and stop What it knows about role kinds is one table, KINDS: a kind -> the SiLA words for it. A role of any other kind is refused, naming the kind; so is a -tuned role (tuning is not in the table). The feature definitions (FDL) are generated at start, from the description (role names, field types, params) and the table: +tuned role (tuning is not in the table). What a kind says about a role (the fields it reports and commands, its bounds, values, labels, scale, unit) is read +through python/onemachine (role_facts), the same for every consumer. The feature definitions (FDL) are generated at start, from the description (role names, +field types, params) and the table: switch Feature Property On Boolean, observable <- the report's `on` Command SetOn(On: Boolean) -> the command's `on` @@ -22,7 +24,7 @@ Command SetText(Text: String, the same constraints) -> the command's u8[N]: the ASCII bytes, NUL-padded to N scaled Feature Property Value Real, observable, Unit <- the report's `raw`, presented = raw * num / den (the role's `scale` line) Command SetValue(Value: Real in [0, max*num/den], Unit) -> the command's `raw`: the nearest integer to value*den/num, - halves away from zero, computed from the shortest decimal of the client's double with integer arithmetic (to_raw); + halves away from zero, computed from the shortest decimal of the client's double with integer arithmetic (Facts.to_raw in python/onemachine); the report is what the device holds, so the actual value shows. max is the role's `param max`. action Feature Property Fired Integer, observable <- the report's `fired` (how many times the action ran since boot) Command Fire() -> the command's `fire` is 1 for that one frame, 0 in every other @@ -43,7 +45,7 @@ ONEMACHINE_PY = os.environ.get('ONEMACHINE_PY') or os.path.join(HERE, '..', '..', 'python') if not os.path.isdir(os.path.join(ONEMACHINE_PY, 'onemachine')): sys.exit('gateway: python/onemachine not found at %s: run from a OneMachine checkout or set ONEMACHINE_PY' % ONEMACHINE_PY) sys.path.insert(0, ONEMACHINE_PY) -from onemachine import Machine, StreamLink, SchemaError, LinkError +from onemachine import Machine, StreamLink, SchemaError, LinkError, KindError, role_facts ORIGINATOR = 'io.github.internetofpins' # in every fully qualified feature identifier SERVER_TYPE, SERVER_NAME = 'OneMachineGateway', 'OneMachine SiLA example' @@ -53,35 +55,27 @@ class Refused(ValueError): """The machine has something this gateway has no SiLA words for; it does not guess.""" -# the whole of what this gateway knows about role kinds. kind -> the SiLA words, the description's field names, and (a light) which param bounds the field +# the whole of what this gateway knows about role kinds: kind -> the SiLA words (the type it makes, the property, the command and its parameter). The description's field +# names and the bounds come from python/onemachine's facts for the kind. KINDS = { - 'switch': dict(type='bool', report='on', command='on', prop='On', cmd='SetOn', param='On'), - 'light': dict(type='int', report='level', command='level', prop='Level', cmd='SetLevel', param='Level', upper='max', lower=0), - 'discrete': dict(type='discrete', report='value', command='value', prop='Value', cmd='SetValue', param='Value', lines=('value',)), # the allowed values: the `value` lines - 'select': dict(type='select', report='index', command='index', prop='Value', cmd='SetValue', param='Value', lines=('value',)), # the `value` lines, each with a label - 'analog': dict(type='analog', report='raw', command=None, prop=None, cmd=None, lines=('scale', 'unit')), # report only; the property's name is the unit's - 'text': dict(type='text', report='text', command='text', prop='Text', cmd='SetText', param='Text', lines=()), # a u8[N] field: printable ASCII, NUL-padded - 'scaled': dict(type='scaled', report='raw', command='raw', prop='Value', cmd='SetValue', param='Value', upper='max', lines=('scale', 'unit')), # a raw u16 0..max presented as raw*num/den - 'action': dict(type='action', report='fired', command='fire', prop='Fired', cmd='Fire'), + 'switch': dict(type='bool', prop='On', cmd='SetOn', param='On'), + 'light': dict(type='int', prop='Level', cmd='SetLevel', param='Level'), + 'discrete': dict(type='discrete', prop='Value', cmd='SetValue', param='Value'), + 'select': dict(type='select', prop='Value', cmd='SetValue', param='Value'), + 'analog': dict(type='analog', prop=None, cmd=None, param=None), # report only; the property's name is the unit's + 'text': dict(type='text', prop='Text', cmd='SetText', param='Text'), + 'scaled': dict(type='scaled', prop='Value', cmd='SetValue', param='Value'), + 'action': dict(type='action', prop='Fired', cmd='Fire'), } # unit symbol -> the SiLA Unit constraint (SI base components; factor and offset to the SI unit) and the name of the property that carries it. Only V. UNITS = {'%': dict(prop='Percent', label='%', factor='0.01', offset=0, components=(('Dimensionless', 1),)), 'V': dict(prop='Voltage', label='V', factor=1, offset=0, components=(('Kilogram', 1), ('Meter', 2), ('Second', -3), ('Ampere', -1)))} TEXT_PATTERN = '[ -~]*' # printable ASCII, 0x20..0x7e: what the device keeps (a byte buffer) and a person can read -def to_raw(value, num, den): - """presented -> raw, presented = raw * num / den: the exact rational of the shortest decimal that round-trips the client's double (12.35, not its binary - neighbour 12.3499999...), times den/num, to the nearest integer, halves away from zero. Integer arithmetic only: no round(), no float multiply.""" - x = Fraction(Decimal(repr(float(value)))) * den / num - p, q = abs(x.numerator), x.denominator - r = (2 * p + q) // (2 * q) - return -r if x < 0 else r - def decimal_str(x): """a Fraction as an exact finite decimal string, or None (the SiLA constraint is text: it must say exactly what the bound is)""" d = Decimal(x.numerator) / Decimal(x.denominator) return format(d.normalize(), 'f') if Fraction(d) == x else None -INT_RANGE = {'u8': (0, 255), 'u16': (0, 65535), 'u32': (0, 2**32 - 1), 'i8': (-128, 127), 'i16': (-32768, 32767), 'i32': (-2**31, 2**31 - 1)} def camel(name): if not re.fullmatch(r'[A-Za-z0-9_]+', name) or '' in name.split('_'): raise Refused('role name %r has no SiLA identifier' % name) @@ -90,77 +84,29 @@ def camel(name): return ident def model(m): - """[(role name, feature identifier, kind, row, bounds)] for every role of the machine, or Refused. bounds = (low, high) of the command field, or None.""" + """[(role name, feature identifier, kind, row, bounds)] for every role of the machine, or Refused. bounds = what the kind bounds the command with, in the shape fdl() reads.""" out, seen = [], {'SiLAService': 'the library'} - LINES = ('value', 'scale', 'unit') for name, info in m.roles.items(): if info.kind not in KINDS: raise Refused('role %s is of kind %r; this gateway knows %s' % (name, info.kind, ', '.join(sorted(KINDS)))) if info.tuned: raise Refused('role %s (%s) is tuned: tuning is not in this gateway\'s table' % (name, info.kind)) - k = dict(KINDS[info.kind]) - have = {'value': info.values, 'scale': info.scales, 'unit': info.units} - for line in LINES: - if have[line] and line not in k.get('lines', ()): raise Refused('role %s (%s): its description has %s lines, which the %s row does not use' % (name, info.kind, line, info.kind)) - fields = {} - for what, schema, field in (('command', m.command_schema, k['command']), ('report', m.report_schema, k['report'])): - if field is None: continue - layer = schema.layer(name) - f = next((f for f in layer.fields if f.name == field), None) if layer else None - if k['type'] == 'text': - if f is None or not f.n or f.base != 'u8': raise Refused('role %s (%s): its %s has no u8 array %r' % (name, info.kind, what, field)) - fields[what] = f; continue - if f is None or f.n: raise Refused('role %s (%s): its %s has no scalar %r' % (name, info.kind, what, field)) - if k['type'] == 'bool' and f.base != 'bool': raise Refused('role %s (%s): its %s %r is %s, not bool' % (name, info.kind, what, field, f.base)) - if k['type'] != 'bool' and f.base not in INT_RANGE: raise Refused('role %s (%s): its %s %r is %s, which is no SiLA Integer' % (name, info.kind, what, field, f.base)) - fields[what] = f - bounds = None - if k['type'] == 'int': - if k['upper'] not in info.params: raise Refused('role %s (%s): no param %r in its description, and the table says it bounds %r' % (name, info.kind, k['upper'], k['command'])) - lo, hi = k['lower'], info.params[k['upper']] - tlo, thi = INT_RANGE[fields['command'].base] - if not (tlo <= lo <= hi <= thi): raise Refused('role %s (%s): bound [%d, %d] does not fit the %s field %r' % (name, info.kind, lo, hi, fields['command'].base, k['command'])) - bounds = (lo, hi) - elif k['type'] == 'discrete': - if not info.values: raise Refused('role %s (%s): no allowed values in its description (`value` lines)' % (name, info.kind)) - if any(label is not None for _, label in info.values): raise Refused('role %s (%s): a value has a label, which the discrete row does not use' % (name, info.kind)) - vals = [v for v, _ in info.values] - tlo, thi = INT_RANGE[fields['command'].base] - if len(set(vals)) != len(vals) or not all(tlo <= v <= thi for v in vals): raise Refused('role %s (%s): values %s are not distinct values of the %s field %r' % (name, info.kind, vals, fields['command'].base, k['command'])) - bounds = tuple(vals) - elif k['type'] == 'select': - if not info.values: raise Refused('role %s (%s): no values in its description (`value` lines)' % (name, info.kind)) - unlabelled = [v for v, label in info.values if label is None] - if unlabelled: raise Refused('role %s (%s): value %s has no label' % (name, info.kind, unlabelled[0])) - vals, labels = [v for v, _ in info.values], [label for _, label in info.values] - tlo, thi = INT_RANGE[fields['command'].base] - if len(set(vals)) != len(vals) or not all(tlo <= v <= thi for v in vals): raise Refused('role %s (%s): values %s are not distinct values of the %s field %r' % (name, info.kind, vals, fields['command'].base, k['command'])) - if len(set(labels)) != len(labels): raise Refused('role %s (%s): two values have the same label (%s)' % (name, info.kind, ', '.join(labels))) - bounds = tuple(info.values) - elif k['type'] == 'analog': - if set(info.scales) != {k['report']}: raise Refused('role %s (%s): the description needs one `scale` line, for the field %r (it has %s)' % (name, info.kind, k['report'], sorted(info.scales) or 'none')) - if set(info.units) != {k['report']}: raise Refused('role %s (%s): the description needs one `unit` line, for the field %r (it has %s)' % (name, info.kind, k['report'], sorted(info.units) or 'none')) - symbol = info.units[k['report']] - if symbol not in UNITS: raise Refused('role %s (%s): unit symbol %r is not in this gateway\'s unit table (%s)' % (name, info.kind, symbol, ', '.join(sorted(UNITS)))) - num, den = info.scales[k['report']] - k['prop'] = UNITS[symbol]['prop'] - bounds = (num, den, symbol) - elif k['type'] == 'text': - if fields['command'].n != fields['report'].n: raise Refused('role %s (%s): its command buffer is %d bytes and its report %d' % (name, info.kind, fields['command'].n, fields['report'].n)) - bounds = (fields['command'].n,) - elif k['type'] == 'scaled': - if set(info.scales) != {k['report']}: raise Refused('role %s (%s): the description needs one `scale` line, for the field %r (it has %s)' % (name, info.kind, k['report'], sorted(info.scales) or 'none')) - if set(info.units) != {k['report']}: raise Refused('role %s (%s): the description needs one `unit` line, for the field %r (it has %s)' % (name, info.kind, k['report'], sorted(info.units) or 'none')) - symbol = info.units[k['report']] - if symbol not in UNITS: raise Refused('role %s (%s): unit symbol %r is not in this gateway\'s unit table (%s)' % (name, info.kind, symbol, ', '.join(sorted(UNITS)))) - if k['upper'] not in info.params: raise Refused('role %s (%s): no param %r in its description, and the table says it bounds %r' % (name, info.kind, k['upper'], k['command'])) - num, den = info.scales[k['report']] - if num <= 0 or den <= 0: raise Refused('role %s (%s): scale %d/%d is not positive' % (name, info.kind, num, den)) - hi_raw = info.params[k['upper']]; tlo, thi = INT_RANGE[fields['command'].base] - if not (0 <= hi_raw <= thi): raise Refused('role %s (%s): bound [0, %d] does not fit the %s field %r' % (name, info.kind, hi_raw, fields['command'].base, k['command'])) - lo_s, hi_s = decimal_str(Fraction(0)), decimal_str(Fraction(hi_raw * num, den)) - if hi_s is None: raise Refused('role %s (%s): the presented bound %d*%d/%d is not a finite decimal' % (name, info.kind, hi_raw, num, den)) - bounds = (num, den, symbol, hi_raw, lo_s, hi_s) - elif k['type'] == 'action': - if INT_RANGE[fields['command'].base][0] != 0: raise Refused('role %s (%s): its command %r (%s) is signed; the flag is 0 or 1 of an unsigned field' % (name, info.kind, k['command'], fields['command'].base)) + try: f = role_facts(m, name) + except KindError as e: raise Refused(str(e)) + k = dict(KINDS[info.kind], report=f.report, command=f.command, facts=f) + t, bounds = k['type'], None + if t == 'int': bounds = (f.low, f.high) + elif t == 'discrete': bounds = f.values + elif t == 'select': bounds = tuple(zip(f.values, f.labels)) + elif t in ('analog', 'scaled'): + if f.unit not in UNITS: raise Refused('role %s (%s): unit symbol %r is not in this gateway\'s unit table (%s)' % (name, info.kind, f.unit, ', '.join(sorted(UNITS)))) + num, den = f.scale + if t == 'analog': + k['prop'] = UNITS[f.unit]['prop'] + bounds = (num, den, f.unit) + else: + lo_s, hi_s = decimal_str(Fraction(0)), decimal_str(f.presented(f.high)) + if hi_s is None: raise Refused('role %s (%s): the presented bound %d*%d/%d is not a finite decimal' % (name, info.kind, f.high, num, den)) + bounds = (num, den, f.unit, f.high, lo_s, hi_s) + elif t == 'text': bounds = (f.size,) ident = camel(name) if ident in seen: raise Refused('roles %r and %r are both the feature %s' % (seen[ident], name, ident)) seen[ident] = name @@ -255,15 +201,12 @@ class Impl(sila2.server.FeatureImplementationBase): pass setattr(impl, '_%s_producer_queue' % k['prop'], Queue()) setattr(impl, 'update_' + k['prop'], (lambda v, impl=impl, p=k['prop']: (setattr(impl, '_%s_current_value' % p, v), getattr(impl, '_%s_producer_queue' % p).put(v)))) setattr(impl, k['prop'] + '_on_subscription', lambda *, metadata: None) - raw_of = {label: raw for raw, label in bounds} if k['type'] == 'select' else None - def setter(value, *, metadata, name=name, k=k, raw_of=raw_of, bounds=bounds): + def setter(value, *, metadata, name=name, k=k): + f = k['facts'] with lock: # one frame at a time: a frame carries every role's command - if k['type'] == 'text': - b = value.encode('ascii') # the SiLA edge (Pattern, MaximalLength) has already refused anything else; this is not trusted - if len(b) > bounds[0] or not all(0x20 <= c <= 0x7e for c in b): raise ValueError('text outside the buffer or printable ASCII') - v = list(b) + [0] * (bounds[0] - len(b)) # NUL-padded: nothing of an older, longer text stays - elif k['type'] == 'scaled': v = to_raw(value, bounds[0], bounds[1]) - else: v = bool(value) if k['type'] == 'bool' else raw_of[value] if raw_of else int(value) + if k['type'] == 'text': v = f.pack_text(value) # the SiLA edge (Pattern, MaximalLength) has already refused anything else; this is not trusted + elif k['type'] == 'scaled': v = f.to_raw(value) + else: v = bool(value) if k['type'] == 'bool' else f.raw_of(value) if k['type'] == 'select' else int(value) setattr(getattr(m.cmd, name), k['command'], v) m.push() # once def fire(*, metadata, name=name, k=k): @@ -281,13 +224,9 @@ def publish(): for name, ident, kind, k, bounds in models: v = getattr(getattr(r, name), k['report']) if k['type'] == 'bool': v = bool(v) - elif k['type'] == 'select': - label = dict(bounds).get(int(v)) - if label is None: raise LinkError('role %s: the report says %d, which no `value` line names' % (name, v)) - v = label - elif k['type'] == 'analog': v = float(v) * bounds[0] / bounds[1] - elif k['type'] == 'scaled': v = float(Fraction(int(v) * bounds[0], bounds[1])) - elif k['type'] == 'text': v = bytes(v).split(b'\0', 1)[0].decode('ascii', 'replace') + elif k['type'] == 'select': v = k['facts'].label_of(v) + elif k['type'] in ('analog', 'scaled'): v = float(k['facts'].presented(v)) + elif k['type'] == 'text': v = k['facts'].unpack_text(v) else: v = int(v) if impls[name].last != v: impls[name].last = v; getattr(impls[name], 'update_' + k['prop'])(v) publish() From a52fe087a2dd6a7a511c5b08adf4aa10f8d09c67 Mon Sep 17 00:00:00 2001 From: neu-rah Date: Thu, 8 Oct 2026 22:37:50 +0000 Subject: [PATCH 3/4] examples/mcp: the examples/sila machine served to MCP clients An MCP server (stdio) that reads the machine's description over the link and generates a tool per role: _get, _set or _fire, and status. The schema of each _set is built from the kind and the description (a light's level up to its max, a select's labels, a text's length, a scaled value's bounds in its unit); a value outside it is refused with a tool error naming the parameter and the bound, and nothing is sent. A set returns the value the device holds. The kind facts come from python/onemachine; the table holds the MCP words. Serves the examples/sila machine: no new firmware. Promoted from R&D/OneMachine/mcpConsumer @ fce471e Co-Authored-By: Claude Sonnet 5.5 --- examples/mcp/README.md | 106 +++++++++++++ examples/mcp/requirements.txt | 2 + examples/mcp/server.py | 276 ++++++++++++++++++++++++++++++++++ 3 files changed, 384 insertions(+) create mode 100644 examples/mcp/README.md create mode 100644 examples/mcp/requirements.txt create mode 100644 examples/mcp/server.py diff --git a/examples/mcp/README.md b/examples/mcp/README.md new file mode 100644 index 0000000..37c5b9a --- /dev/null +++ b/examples/mcp/README.md @@ -0,0 +1,106 @@ +# mcp + +The machine of [`examples/sila`](../sila) served to AI assistants over MCP. Claude Code, or any other MCP client, can read and +command every role of the Nano by name, without knowing OneMachine, the pins or the board. Nothing on the board changes: this is +the same firmware as in `examples/sila` (wiring and flashing are described there), and the same machine description feeds both +examples. One machine, two consumers. + +[MCP](https://modelcontextprotocol.io) (the Model Context Protocol) is the way an AI assistant is given tools. A server lists its +tools, each with a name, a description and a JSON Schema for its arguments; the assistant reads them, decides which to call, and the +server returns the result. `server.py` reads the machine's description over the serial link, generates the tools from it and serves +them on standard input and output, so the client starts it as a program. It knows only the kinds in its table: a role of any other +kind is refused at start, naming the role. + +## Run + +``` +pip install -r requirements.txt # mcp and pyserial; Python 3.10 or newer +python3 server.py --port /dev/ttyUSB0 # the Nano's port +``` + +Opening the port resets a Nano: all outputs start off at each start. + +Without the board, the same machine on this computer (from this directory): + +``` +g++ -std=c++17 -I../../../HAPI/include -I../../include ../sila/host/main.cpp -o ../sila/host/machine +python3 server.py --sim ../sila/host/machine +``` + +`python3 server.py --sim ../sila/host/machine --list` prints what a client is told (the instructions and every tool with its schema) +and stops. `--trace FILE` writes every request and response on the link. + +## Add it to Claude Code + +``` +claude mcp add machine -- python3 /path/to/examples/mcp/server.py --port /dev/ttyUSB0 +``` + +Then ask in plain words: "What can this machine do?", "Turn on the LED.", "Set the lamp to half its maximum." + +## What the tools are + +For each role, `_get` reads it. A commandable role also has `_set` with one argument, or `_fire` for an action. +`status` reads every role in one call. The schema is built from the role's kind and its description: + +| role (kind) | tools | argument and its schema | what `_get` returns | +|---|---|---|---| +| `led` (`switch`) | `led_get`, `led_set` | `on`: boolean | `{"on": true}` | +| `lamp` (`light`) | `lamp_get`, `lamp_set` | `level`: integer, 0 to `max` (200) | `{"level": 100, "clamped": false}` | +| `step` (`discrete`) | `step_get`, `step_set` | `value`: integer, one of the `value` lines (0, 10, 50, 100) | `{"value": 50}` | +| `mode` (`select`) | `mode_get`, `mode_set` | `value`: string, one of the labels (off, low, high) | `{"value": "high"}` | +| `vin` (`analog`) | `vin_get` | none: read only | `{"value": 2.49, "unit": "V"}` | +| `note` (`text`) | `note_get`, `note_set` | `text`: string, at most 16 printable ASCII characters | `{"text": "hello"}` | +| `duty` (`scaled`) | `duty_get`, `duty_set` | `value`: number, 0 to 100 (`max` times the `scale` line) | `{"value": 12.4, "unit": "%"}` | +| `ping` (`action`) | `ping_get`, `ping_fire` | none | `{"fired": 3}` | + +How they behave: + +- **A set returns the value the device holds.** The command is sent once, then the report is read after the device has applied it: + `duty_set 12.36` returns 12.4, the device's own resolution. The report is the truth. +- **A value outside the schema is refused, and nothing is sent.** The result is a tool error that names the parameter and the bound + (`level: 250 is above the maximum 200`). The server checks every argument itself, whether or not the client checks the schema. +- **The assistant is told to ask, not to substitute.** The server's instructions say that a value outside a tool's bounds is + refused, and that the assistant should tell the user instead of sending a different value. +- **Nothing is held or resent.** A `_fire` sends its flag in exactly one frame. Whatever the device does when commands stop is the + device's own behaviour. One lock on the link serialises the calls. +- **Every argument is checked, even the ones a schema cannot express:** `text` must be printable ASCII, a `light` must be a whole + number, a boolean is not a number. + +The rules any such consumer follows are in [`docs/consumers.md`](../../docs/consumers.md). What a kind says about a role (the +fields it reports and commands, the bound, the values, the scale) is read through `python/onemachine`; this file holds the MCP words. + +## An expected session + +Claude Code on a Nano, a fresh session with only this server's tools (the answers are shortened; each tool call and its result are the server's own): + +``` +> What can this machine do? + This machine (OneMachine `ba36fc2d`) exposes several controllable roles: + led (switch) – on/off · lamp (light) – level 0–200 · step (discrete) – one of 0, 10, 50, 100 · mode (select) – off, low, high · + vin (analog, read-only) – voltage reading in V · note (text) – up to 16 ASCII characters · duty (scaled) – 0–100%, 0.1 resolution · + ping (action) – fires once, counts how many times it's run since boot +> Turn on the LED. + led_set {"on": true} -> {"on":true} +> Set the lamp to half its maximum. + lamp_set {"level": 100} -> {"level":100,"clamped":false} +> Set the mode to the highest setting. + mode_set {"value": "high"} -> {"value":"high"} +> Write 'hi Rui' on the note. + note_set {"text": "hi Rui"} -> {"text":"hi Rui"} +> What voltage is on vin? + vin_get {} -> {"value":0.21994134897360704,"unit":"V"} (A0 is floating: noise between 0 and 5 V) +> Set the lamp to 300. + That's out of bounds — lamp only accepts 0 to 200. I won't send a different value; let me know what level within that range you'd like. +``` + +Four commands reached the board, one frame each; the last request sent nothing. A client that sends the value anyway gets the tool +error, and the board never sees it; a client that bypasses the server and sends it to the board gets the kind's own behaviour (a +light is clamped to its `max`). + +## What it does not cover + +No network transport and no authentication (the client starts the server and talks to it on standard input and output), no tuned +roles (their limits can change at run time, which a tool schema cannot say), no timeout or safe fall (a value that was set stays +set), no MCP resources or prompts beyond the server's instructions, and no reconnect: if the board is unplugged, the tools return +errors until the server is restarted. diff --git a/examples/mcp/requirements.txt b/examples/mcp/requirements.txt new file mode 100644 index 0000000..35632ad --- /dev/null +++ b/examples/mcp/requirements.txt @@ -0,0 +1,2 @@ +mcp==2.3.0 +pyserial==3.5 diff --git a/examples/mcp/server.py b/examples/mcp/server.py new file mode 100644 index 0000000..730409a --- /dev/null +++ b/examples/mcp/server.py @@ -0,0 +1,276 @@ +#!/usr/bin/env python3 +"""An MCP server (stdio) for a OneMachine machine whose roles are switches, plain lights, discrete integers, selects, analog inputs, text, scaled values +and actions: the machine of examples/sila, or any machine built from those kinds. + + python3 server.py --port /dev/ttyUSB0 a Nano (or any board running the role::Link sketch) on its USB serial port, 115200 + python3 server.py --sim host/device a host build of the machine, over a pipe (no board needed) + python3 server.py ... --trace FILE write every request and response on the link: op, payload hex, status, payload hex + python3 server.py ... --list print the instructions and the tools as JSON and stop (no MCP session) + +What it knows about role kinds is one table, KINDS: a kind -> the MCP words for it (the parameter's name; the schema and the descriptions are built from the +kind's type below). What a kind says about a role (the fields it reports and commands, its bounds, values, labels, scale, unit) is read through python/onemachine +(role_facts), the same for every consumer. A role of a kind not in the table is refused at start, naming the role and the kind; so is a tuned role. The tools are +generated from the machine's description, per role: + + _get every role the role's report, presented (labels, units applied) + _set every commandable state one parameter, from the kind's row; returns the report after the device applied it + _fire an action no parameter; returns the report after the device applied it + status the machine every role's report + + switch on: boolean light level: integer 0..`max` discrete value: integer, enum the `value` lines + select value: string, enum the labels text text: string, maxLength N, ASCII scaled value: number 0..max*num/den (the `scale`, `unit` lines) + analog (no _set) value with its unit action (no parameter) + +A value outside the schema is refused here with a tool error that names the parameter and the bound, and nothing is sent. The MCP SDK's low-level Server +calls the handler without checking arguments against inputSchema, so the check is this file's own. A command is forwarded once (m.push()), then the report is +read once (m.poll()): the link is request/response and the device applies a command before it reads the next request, so the report that follows a push is +the device's state after that command. Nothing is held or resent. Needs mcp and pyserial (requirements.txt) and python/onemachine from this checkout +(ONEMACHINE_PY= to use another).""" +import argparse, json, os, re, sys, threading, time +from decimal import Decimal +from fractions import Fraction + +HERE = os.path.dirname(os.path.abspath(__file__)) +ONEMACHINE_PY = os.environ.get('ONEMACHINE_PY') or os.path.join(HERE, '..', '..', 'python') +if not os.path.isdir(os.path.join(ONEMACHINE_PY, 'onemachine')): sys.exit('server: python/onemachine not found at %s: run from a OneMachine checkout or set ONEMACHINE_PY' % ONEMACHINE_PY) +sys.path.insert(0, ONEMACHINE_PY) +from onemachine import Machine, StreamLink, SchemaError, LinkError, KindError, role_facts + +class Refused(ValueError): + """The machine has something this server has no MCP words for; it does not guess.""" + +# the whole of what this server knows about role kinds: kind -> the type it makes and the name of its parameter +KINDS = { + 'switch': dict(type='bool', param='on'), + 'light': dict(type='int', param='level'), + 'discrete': dict(type='discrete', param='value'), + 'select': dict(type='select', param='value'), + 'analog': dict(type='analog', param=None), + 'text': dict(type='text', param='text'), + 'scaled': dict(type='scaled', param='value'), + 'action': dict(type='action', param=None), +} +TOOL_NAME = re.compile(r'[A-Za-z0-9_-]{1,64}') # the tool names clients accept +SUFFIXES = ('get', 'set', 'fire') + +def number(x): + """a Fraction as the plainest JSON number: an int when whole, else its float""" + return int(x) if x.denominator == 1 else float(x) + +class Role: + """One role of the machine: its tools, its schema, its checks and its presented report. Everything machine-specific is read from the description.""" + def __init__(self, name, kind, row, facts): + self.name, self.kind, self.row, self.f, self.type = name, kind, row, facts, row['type'] + + def settable(self): return self.type != 'analog' + + def top(self): + return self.f.presented(self.f.high) # scaled: the presented upper bound, max * num / den + + def schema(self): + t, f = self.type, self.f + if t == 'bool': return {'type': 'boolean'} + if t == 'int': return {'type': 'integer', 'minimum': f.low, 'maximum': f.high} + if t == 'discrete': return {'type': 'integer', 'enum': list(f.values)} + if t == 'select': return {'type': 'string', 'enum': list(f.labels)} + if t == 'text': return {'type': 'string', 'maxLength': f.size, 'pattern': '^[ -~]*$'} + if t == 'scaled': return {'type': 'number', 'minimum': 0, 'maximum': number(self.top())} + + def describe(self, what): + t, f, n = self.type, self.f, self.name + if what == 'get': + words = {'bool': 'switch): whether it is on.', 'int': 'light): its level and whether the device clamped the last command.', + 'discrete': 'discrete): its value.', 'select': 'select): its value, as a label.', 'text': 'text): its text.', + 'action': 'action): how many times it has run since boot.', + 'analog': 'analog, read only): its reading in ' + str(f.unit) + '.', 'scaled': 'scaled): its value in ' + str(f.unit) + '.'} + return n + ' (' + words[t] + if what == 'fire': return '%s (action): run it once. Returns the count of runs the device holds.' % n + held = ' Returns the value the device holds.' + if t == 'bool': return '%s (switch): set on (true) or off (false).' % n + held + if t == 'int': return '%s (light): set the level, %d to %d.' % (n, f.low, f.high) + held + if t == 'discrete': return '%s (discrete): set the value, one of %s.' % (n, ', '.join(str(v) for v in f.values)) + held + if t == 'select': return '%s (select): set the value, one of %s (the machine\'s order).' % (n, ', '.join(f.labels)) + held + if t == 'text': return '%s (text): set the text, up to %d printable ASCII characters.' % (n, f.size) + held + if t == 'scaled': + return '{} (scaled): set the value in {}, 0 to {}, resolution {}; the device rounds to its resolution.'.format(n, f.unit, number(self.top()), number(Fraction(*f.scale))) + held + + def refuse(self, args): + """(raw command value, None) for an acceptable argument, or (None, the message): which parameter, which bound. Nothing is sent for a message.""" + p, t, f = self.row['param'], self.type, self.f + if t == 'action': return (1, None) if not args else (None, 'unknown argument %r: this tool takes none' % sorted(args)[0]) + extra = sorted(set(args) - {p}) + if extra: return None, 'unknown argument %r: the only parameter is %r' % (extra[0], p) + if p not in args: return None, 'missing parameter %r' % p + v = args[p] + if t == 'bool': + if not isinstance(v, bool): return None, '%s: %r is not a boolean' % (p, v) + return v, None + if t == 'text': + if not isinstance(v, str): return None, '%s: %r is not a string' % (p, v) + if len(v) > f.size: return None, '%s: %d characters, the maximum is %d' % (p, len(v), f.size) + try: return f.pack_text(v), None + except (UnicodeEncodeError, ValueError): return None, '%s: only printable ASCII (0x20 to 0x7e) is accepted' % p + if t == 'select': + if not isinstance(v, str): return None, '%s: %r is not a string' % (p, v) + if v not in f.labels: return None, '%s: %r is not one of %s' % (p, v, ', '.join(f.labels)) + return f.raw_of(v), None + if isinstance(v, bool) or not isinstance(v, (int, float)) or v != v or v in (float('inf'), float('-inf')): return None, '%s: %r is not a number' % (p, v) + if t in ('int', 'discrete'): + if v != int(v): return None, '%s: %r is not an integer' % (p, v) + v = int(v) + if t == 'discrete': + if v not in f.values: return None, '%s: %d is not one of %s' % (p, v, ', '.join(str(x) for x in f.values)) + else: + if v < f.low: return None, '%s: %d is below the minimum %d' % (p, v, f.low) + if v > f.high: return None, '%s: %d is above the maximum %d' % (p, v, f.high) + return v, None + hi = self.top() # scaled: the bounds are on the presented value, as in the schema + x = Fraction(Decimal(repr(float(v)))) # the number as the client wrote it (12.35, not its binary neighbour) + if x < 0: return None, '%s: %r is below the minimum 0' % (p, v) + if x > hi: return None, '%s: %r is above the maximum %s' % (p, v, number(hi)) + return f.to_raw(v), None + + def present(self, layer): + """the report layer as the structured result""" + t, f = self.type, self.f + if t == 'bool': out = {'on': bool(layer.on)} + elif t == 'int': out = {'level': int(layer.level), 'clamped': bool(layer.clamped)} + elif t == 'discrete': out = {'value': int(layer.value)} + elif t == 'select': out = {'value': f.label_of(layer.index)} + elif t == 'analog': out = {'value': float(f.presented(layer.raw)), 'unit': f.unit} + elif t == 'text': out = {'text': f.unpack_text(layer.text)} + elif t == 'scaled': out = {'value': number(f.presented(layer.raw)), 'unit': f.unit} + else: out = {'fired': int(layer.fired)} + if not layer.live: out['live'] = False # the role's device is not there + return out + +def model(m): + """[Role] for every role of the machine, or Refused, naming the role.""" + out, tools = [], {} + for name, info in m.roles.items(): + if info.kind not in KINDS: raise Refused('role %s is of kind %r; this server knows %s' % (name, info.kind, ', '.join(sorted(KINDS)))) + if info.tuned: raise Refused('role %s (%s) is tuned: its limits can change at run time, which a tool schema cannot say' % (name, info.kind)) + try: f = role_facts(m, name) + except KindError as e: raise Refused(str(e)) + for field in (['clamped'] if info.kind == 'light' else []) + ['live']: + if field not in f.report_fields: raise Refused('role %s (%s): its report has no field %r' % (name, info.kind, field)) + role = Role(name, info.kind, KINDS[info.kind], f) + for suffix in SUFFIXES: + if suffix == 'get' or (suffix == 'set' and role.type not in ('analog', 'action')) or (suffix == 'fire' and role.type == 'action'): + tool = '%s_%s' % (name, suffix) + if not TOOL_NAME.fullmatch(tool): raise Refused('role %s: the tool name %r is not %s' % (name, tool, TOOL_NAME.pattern)) + if tool in tools: raise Refused('roles %r and %r are both the tool %s' % (tools[tool], name, tool)) + tools[tool] = name + out.append(role) + if not out: raise Refused('the machine has no roles') + return out + +def tools_of(roles): + """[(tool name, role|None, suffix|'status', description, inputSchema, annotations dict)], all generated""" + empty = {'type': 'object', 'properties': {}, 'additionalProperties': False} + out = [('status', None, 'status', 'Every role\'s report in one call.', empty, dict(read_only_hint=True))] + for r in roles: + out.append(('%s_get' % r.name, r, 'get', r.describe('get'), empty, dict(read_only_hint=True))) + if r.type == 'action': out.append(('%s_fire' % r.name, r, 'fire', r.describe('fire'), empty, dict(read_only_hint=False, idempotent_hint=False))) + elif r.settable(): + p = r.row['param'] + out.append(('%s_set' % r.name, r, 'set', r.describe('set'), + {'type': 'object', 'properties': {p: r.schema()}, 'required': [p], 'additionalProperties': False}, dict(read_only_hint=False, idempotent_hint=True))) + return out + +def instructions_of(m, roles): + return ('OneMachine machine %08x. Roles: %s. Each role has a _get tool; a _set tool takes the new value, a _fire tool runs an action; status reads every role. ' + 'A _set or _fire returns what the device holds afterwards, which is the truth. A value outside a tool\'s bounds is refused: tell the user, do not send a different value.' % (m.description.hash, ', '.join('%s (%s)' % (r.name, r.kind) for r in roles))) + +class Traced: + """Wraps a link and writes every request and response: op, payload hex, status, payload hex (test/state/frame_decode.py decodes them), the host time at which + the request is written, and how long the exchange took.""" + def __init__(self, link, path): self.link, self.f, self.t0 = link, open(path, 'w', buffering=1), time.monotonic() + def call(self, op, payload=b''): + t = time.monotonic() - self.t0 + st, data = self.link.call(op, payload) + self.f.write('%s %s %d %s %.4f %.4f\n' % (op if isinstance(op, str) else chr(op), bytes(payload).hex() or '-', st, data.hex() or '-', t, time.monotonic() - self.t0 - t)) + return st, data + def close(self): self.f.close(); self.link.close() + +def open_link(a): + if a.sim: link = StreamLink.popen([a.sim]) + else: + import serial + port = serial.Serial(a.port, 115200, timeout=2) + time.sleep(2); port.reset_input_buffer() # opening the port resets a Nano: wait for its bootloader to pass + link = StreamLink(port.read, port.write, port.flush) + return Traced(link, a.trace) if a.trace else link + +def serve(m, roles, name='onemachine'): + import anyio, anyio.to_thread + import mcp_types as types + from mcp.server import Server + from mcp.server.stdio import stdio_server + from mcp.shared.exceptions import MCPError + lock = threading.Lock() # one frame at a time: a frame carries every role's command + table = {t[0]: t for t in tools_of(roles)} + + def reply(structured, error=False): + return types.CallToolResult(content=[types.TextContent(text=json.dumps(structured, separators=(',', ':')))], structured_content=structured, is_error=error) + def fail(tool, message): return types.CallToolResult(content=[types.TextContent(text='%s: %s' % (tool, message))], is_error=True) + + def run(tool, role, kind, args): + """the whole of a call, under the lock: refuse or push once, poll once, present""" + if kind in ('get', 'status'): + if args: return fail(tool, 'unknown argument %r: this tool takes none' % sorted(args)[0]) + with lock: r = m.poll() + return reply({x.name: x.present(getattr(r, x.name)) for x in roles} if kind == 'status' else role.present(getattr(r, role.name))) + raw, error = role.refuse(args) + if error: return fail(tool, '%s. Nothing was sent to the device.' % error) + layer_name, field = role.name, role.f.command + with lock: + layer = getattr(m.cmd, layer_name) + before = getattr(layer, field) + setattr(layer, field, raw) + try: + try: m.push() # once + finally: + if kind == 'fire': setattr(layer, field, 0) # the flag is 1 only during one push, and 0 in every other frame + r = m.poll() # the report after the device applied the command + except Exception: + if kind != 'fire': setattr(layer, field, before) # a command that did not go is not kept + raise + return reply(role.present(getattr(r, role.name))) + + async def on_list_tools(ctx, params): + return types.ListToolsResult(tools=[types.Tool(name=n, description=d, input_schema=s, annotations=types.ToolAnnotations(**a)) for n, _, _, d, s, a in table.values()]) + + async def on_call_tool(ctx, params): + entry = table.get(params.name) + if entry is None: raise MCPError(code=types.INVALID_PARAMS, message='unknown tool %r' % params.name) + tool, role, kind = entry[0], entry[1], entry[2] + try: return await anyio.to_thread.run_sync(run, tool, role, kind, dict(params.arguments or {})) + except (SchemaError, LinkError, OSError, ValueError) as e: return fail(tool, 'the machine did not take it: %s' % e) + + server = Server(name, version='0.1', instructions=instructions_of(m, roles), on_list_tools=on_list_tools, on_call_tool=on_call_tool) + async def main(): + async with stdio_server() as (read, write): + await server.run(read, write, server.create_initialization_options()) + anyio.run(main) + +def main(): + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + src = ap.add_mutually_exclusive_group(required=True) + src.add_argument('--port', metavar='SERIAL'); src.add_argument('--sim', metavar='HOST_BINARY') + ap.add_argument('--trace', metavar='FILE') + ap.add_argument('--list', action='store_true', help='print the instructions and tools/list as JSON on stdout and stop (no MCP session)') + a = ap.parse_args() + try: m = Machine(open_link(a)) + except SchemaError as e: sys.exit('server: the binding refuses this machine: %s' % e) + except (LinkError, OSError) as e: sys.exit('server: cannot reach the machine: %s' % e) + try: roles = model(m) + except Refused as e: sys.exit('server: refused: %s' % e) + if a.list: + print(json.dumps({'instructions': instructions_of(m, roles), 'tools': [dict(name=n, description=d, inputSchema=s, annotations=an) for n, _, _, d, s, an in tools_of(roles)]}, indent=1)) + return + print('server: %d roles, %d tools, machine hash %08x' % (len(roles), len(tools_of(roles)), m.description.hash), file=sys.stderr, flush=True) + serve(m, roles) + +if __name__ == '__main__': + main() From 99358991eb45dc56ef3f678e477d80d50af921b7 Mon Sep 17 00:00:00 2001 From: neu-rah Date: Thu, 8 Oct 2026 22:37:50 +0000 Subject: [PATCH 4/4] docs: examples/mcp next to examples/sila; the kind facts are read through python/onemachine consumers.md names examples/mcp as a second worked example and says, in rule 1 and in "Adding a consumer", that a kind's facts come from role_facts while the consumer's table holds the protocol's words. The README lists the example. Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 ++ docs/consumers.md | 11 ++++++++--- examples/sila/README.md | 2 +- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f14524a..99af727 100644 --- a/README.md +++ b/README.md @@ -230,6 +230,8 @@ 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). +- [`examples/mcp`](examples/mcp) — the same machine served to AI assistants over MCP (Claude Code and others), from the same + description: a tool to read and a tool to command each role, with the bounds in the tool's schema. And one on a second bus: diff --git a/docs/consumers.md b/docs/consumers.md index 5aa5ff9..d0a2159 100644 --- a/docs/consumers.md +++ b/docs/consumers.md @@ -6,7 +6,8 @@ industrial controller. The machine is built once and knows none of them; each co 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. +kinds into a SiLA 2 server. [`examples/mcp`](../examples/mcp) serves the same machine to AI assistants over MCP: the same +description, another protocol's words. ## What the machine provides @@ -29,7 +30,10 @@ 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`. + description at connect. What a kind says about a role (the fields it reports and commands, what bounds them, the values, + labels, scale and unit, how a raw integer is presented) is read through `python/onemachine` (`role_facts`), the same for + every consumer; the table holds only the protocol's words. In `examples/sila` the table is `KINDS` in `gateway.py`, in + `examples/mcp` it is `KINDS` in `server.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 @@ -70,7 +74,8 @@ 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. +1. Map each kind you need to the protocol's words: type, constraints, unit, readable or commandable. Write it as the table, + and read the kind's facts from `role_facts` in `python/onemachine` instead of copying them. 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. diff --git a/examples/sila/README.md b/examples/sila/README.md index 069af5c..8050750 100644 --- a/examples/sila/README.md +++ b/examples/sila/README.md @@ -8,7 +8,7 @@ them without knowing OneMachine, the pins or the board. properties you read or subscribe to, and commands you call, each with typed, constrained parameters) over gRPC, and every feature carries an XML definition (FDL) a client can fetch. The gateway (`gateway.py`) reads the machine's description over the serial link, writes one feature per role and serves them. It knows only the kinds in its table: a role of any other kind is -refused, naming the kind. +refused, naming the kind. The same machine is also served to AI assistants over MCP by [`examples/mcp`](../mcp). ## Wiring