tibet-peripheral 0.1.0__tar.gz

tibet_peripheral-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# Python build + cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+venv/

tibet_peripheral-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jasper van de Meent (Humotica) and the AInternet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tibet_peripheral-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: tibet-peripheral
+Version: 0.1.0
+Summary: IP-less peripheral actors for TIBET/AInternet: serial, Bluetooth, BLE, LoRa and smart-device executors bound under a box/root.
+Author-email: Jasper van de Meent <jasper@humotica.nl>, Codex <codex@humotica.nl>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ainternet,arduino,ble,bluetooth,iot,peripheral,rvp,serial,tibet
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# tibet-peripheral
+
+IP-less peripheral actors for TIBET/AInternet.
+
+This package is a sandbox-born skeleton for devices that cannot, should not, or
+must not speak IP themselves: Arduino lights, cheap toys, BLE buttons, LoRa
+sensors, smart devices, RVP peripherals, doorbells, relays, and other physical
+actuators.
+
+The peripheral is not the root of trust. The box/bridge is the cryptographic and
+policy authority. The peripheral is a bound executor that must stay in the
+causal rhythm.
+
+```text
+internet / overlay / cmail / local button
+  -> box or bridge verifies intent, grant, presence, and relation
+  -> tiny peripheral frame over serial / BT / BLE / LoRa
+  -> IP-less device acts
+  -> ACK returns
+  -> bridge emits receipt
+```
+
+## Core Rule
+
+```text
+The peripheral does not have to calculate trust.
+It has to stay in time.
+```
+
+If the tether breaks, the session is dead. When it comes back, it must rebind.
+That makes uptime and sequence continuity part of the safety model.
+
+## What Exists Here
+
+- `tibet_peripheral.protocol` — tiny line frame codec and session guard.
+- `tibet_peripheral.serial_line` — POSIX serial line helper, stdlib only.
+- `tibet_peripheral.bridge` — local HTTP bridge for light control.
+- `examples/arduino/light_node/light_node.ino` — Arduino Uno onboard LED sketch.
+- `docs/ARCHITECTURE.md` — doctrine and binding model.
+- `docs/ROADMAP.md` — route toward real TIBET overlay integration.
+
+## Proof Of Concept
+
+For a classic Arduino Uno R3 / ATmega328P:
+
+```bash
+python3 -m tibet_peripheral.bridge --serial /dev/ttyUSB0
+curl http://127.0.0.1:8765/light/l
+curl http://127.0.0.1:8765/light/on
+curl http://127.0.0.1:8765/light/off
+```
+
+The Arduino has no IP address. The bridge does.
+
+For an already-flashed sketch that reacts to commands but does not print ACK
+lines, start in fire-and-watch mode:
+
+```bash
+python3 -m tibet_peripheral.bridge --serial /dev/ttyUSB0 --no-ack
+```
+
+That proves reachability. For causal receipts, flash the example firmware so the
+device returns `OK ...` after each command.
+
+## Naming
+
+`light.aint` or `jis:peripheral:light:<hash>` names the routed actor. The
+Arduino itself only sees a short session id and monotonic sequence. The public
+`.aint` is a route/identity wrapper owned by the box or app relation, not a
+claim that an 8-bit MCU runs the whole trust stack.

tibet_peripheral-0.1.0/README.md

@@ -0,0 +1,70 @@
+# tibet-peripheral
+
+IP-less peripheral actors for TIBET/AInternet.
+
+This package is a sandbox-born skeleton for devices that cannot, should not, or
+must not speak IP themselves: Arduino lights, cheap toys, BLE buttons, LoRa
+sensors, smart devices, RVP peripherals, doorbells, relays, and other physical
+actuators.
+
+The peripheral is not the root of trust. The box/bridge is the cryptographic and
+policy authority. The peripheral is a bound executor that must stay in the
+causal rhythm.
+
+```text
+internet / overlay / cmail / local button
+  -> box or bridge verifies intent, grant, presence, and relation
+  -> tiny peripheral frame over serial / BT / BLE / LoRa
+  -> IP-less device acts
+  -> ACK returns
+  -> bridge emits receipt
+```
+
+## Core Rule
+
+```text
+The peripheral does not have to calculate trust.
+It has to stay in time.
+```
+
+If the tether breaks, the session is dead. When it comes back, it must rebind.
+That makes uptime and sequence continuity part of the safety model.
+
+## What Exists Here
+
+- `tibet_peripheral.protocol` — tiny line frame codec and session guard.
+- `tibet_peripheral.serial_line` — POSIX serial line helper, stdlib only.
+- `tibet_peripheral.bridge` — local HTTP bridge for light control.
+- `examples/arduino/light_node/light_node.ino` — Arduino Uno onboard LED sketch.
+- `docs/ARCHITECTURE.md` — doctrine and binding model.
+- `docs/ROADMAP.md` — route toward real TIBET overlay integration.
+
+## Proof Of Concept
+
+For a classic Arduino Uno R3 / ATmega328P:
+
+```bash
+python3 -m tibet_peripheral.bridge --serial /dev/ttyUSB0
+curl http://127.0.0.1:8765/light/l
+curl http://127.0.0.1:8765/light/on
+curl http://127.0.0.1:8765/light/off
+```
+
+The Arduino has no IP address. The bridge does.
+
+For an already-flashed sketch that reacts to commands but does not print ACK
+lines, start in fire-and-watch mode:
+
+```bash
+python3 -m tibet_peripheral.bridge --serial /dev/ttyUSB0 --no-ack
+```
+
+That proves reachability. For causal receipts, flash the example firmware so the
+device returns `OK ...` after each command.
+
+## Naming
+
+`light.aint` or `jis:peripheral:light:<hash>` names the routed actor. The
+Arduino itself only sees a short session id and monotonic sequence. The public
+`.aint` is a route/identity wrapper owned by the box or app relation, not a
+claim that an 8-bit MCU runs the whole trust stack.

tibet_peripheral-0.1.0/docs/AINS_LOCAL_REGISTRY.md

@@ -0,0 +1,67 @@
+# Local AINS Registry For Peripherals
+
+`light.aint` does not have to be a central public AINS identity first.
+
+For peripherals, the correct order is:
+
+```text
+local binding -> local route -> optional public alias/window
+```
+
+## Why
+
+A cheap device, toy, button, light, or RVP peripheral often has no secure key and
+no IP address. Publishing it centrally as if it were a full actor lies about the
+floor.
+
+Instead, the box can locally register:
+
+```text
+light.aint = this bound peripheral route under jasper.aint
+```
+
+That local record is enough for:
+
+- cockpit/iab-tui display;
+- overlay route decision;
+- public URL policy mapping;
+- receipts;
+- offline/dormant state.
+
+## Central AINS Role
+
+Central AINS may later publish a discoverable alias:
+
+```text
+jasper-light-<hash>.aint
+```
+
+or a human-friendly temporary alias:
+
+```text
+camp-light-demo.aint
+```
+
+But the central registry should be a directory/window, not the trust root.
+
+## Record Split
+
+Use two records:
+
+1. local AINS/alias entry says the name exists and points to a route record;
+2. route record says how this box can currently reach it.
+
+This avoids pretending that a peripheral has an internet endpoint.
+
+## No-IP Invariant
+
+For this class of actor:
+
+```json
+{
+  "device_ip": null
+}
+```
+
+is a feature, not missing data.
+

tibet_peripheral-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Architecture
+
+## Problem
+
+Smart devices normally become reachable by gaining an IP stack or joining a
+vendor cloud. That expands the attack surface and moves authority away from the
+owner.
+
+TIBET peripheral flips this:
+
+```text
+the bridge is online
+the peripheral is not
+```
+
+The peripheral is reachable through a box/root relation, not through a public
+socket on the device.
+
+## Roles
+
+| Role | Meaning |
+|---|---|
+| Peripheral | Tiny actuator/sensor. May be 8-bit and unable to run modern crypto. |
+| Bridge | Phone/laptop/box carrier with IP/overlay access and local tether to peripheral. |
+| Box/root | Authority for identity, grants, receipts, and policy. |
+| `.aint` | Route/identity name for the peripheral relation, e.g. `light.aint`. |
+
+## Binding
+
+The owner can choose to trust a peripheral enough to read or actuate it.
+
+That binding may come from:
+
+- physical plug-in;
+- Bluetooth pairing;
+- app-based vendor pairing;
+- QR/NFC/tap;
+- local button gesture;
+- serial proof;
+- a signed card or bridge receipt.
+
+The point is not that the peripheral proves everything. The point is that the
+box records: this peripheral is bound under this owner/root and may perform
+these bounded actions while the tether is alive.
+
+## Causal Continuity
+
+For very constrained devices, uptime and tether continuity are part of the
+safety model.
+
+```text
+attached -> alive -> acts in monotonic sequence
+tether breaks -> dormant/unproven
+returns later -> rebind required
+```
+
+A tiny device does not get to silently resume high-trust authority after being
+offline. The bridge should start a new session id and require an explicit
+rebinding gesture or policy decision.
+
+## Why Not Full Crypto On Arduino Uno
+
+ATmega328P is 8-bit, 16 MHz, with 2 KB SRAM. Full Ed25519/X25519/TBZ is possible
+only with painful constraints and is not the right proof.
+
+Better split:
+
+```text
+box/bridge: crypto, policy, relation, receipt
+peripheral: sequence, allowed command, ACK rhythm
+```
+
+For ESP32, nRF52840, RP2040 plus radio, or secure-element boards, a stronger
+device-native key can be added later.
+
+## Public URL
+
+A public URL such as `/light/on` must not mean the peripheral is public. It means
+the public surface reaches a policy gate which may issue a bounded command to a
+bound peripheral.
+
+```text
+public URL -> intent gate -> box policy -> bridge -> peripheral frame -> ACK -> receipt
+```
+

tibet_peripheral-0.1.0/docs/CONFORMANCE.md

@@ -0,0 +1,33 @@
+# Conformance Seeds
+
+## P1: No-IP Peripheral
+
+Given `light.aint` resolves to a peripheral route, the route record must carry
+`device_ip: null`. A conforming implementation must not invent an IP endpoint
+for the device.
+
+## P2: Local Authority
+
+Given a central AINS record exists for `light.aint`, local box route authority
+still decides whether the peripheral is attached and commandable.
+
+## P3: Capability Gate
+
+Given a caller requests `light.set:on`, the gate must deny if the route lacks
+`light.set` or if caller grant/presence is insufficient.
+
+## P4: Public URL Is Policy Surface
+
+Given `/light/on`, the public handler must map to a fixed intent and target. It
+must not forward arbitrary path text to serial.
+
+## P5: Offline Rebind
+
+Given the serial/BT tether breaks, state must become `dormant` or `unproven`.
+Later reappearance must create a new session and require a rebind gesture/policy.
+
+## P6: ACK Ladder
+
+`sent-no-ack` is allowed for reachability demos only. Stronger actions require
+firmware ACK and signed bridge receipt.
+

tibet_peripheral-0.1.0/docs/PUBLIC_URL_DEMO.md

@@ -0,0 +1,48 @@
+# Public URL Demo
+
+The demo sentence:
+
+```text
+ainternet.org/light/on turns on an IP-less light.
+```
+
+The security sentence:
+
+```text
+The URL does not reach the Arduino. It reaches a policy gate that may command a
+locally bound peripheral.
+```
+
+## Flow
+
+```text
+GET /light/on
+  -> route target: light.aint
+  -> intent: light.set:on
+  -> resolve local peripheral route
+  -> check grant/presence/posture
+  -> call local bridge on 127.0.0.1
+  -> write receipt
+```
+
+## Demo JSON
+
+```json
+{
+  "ok": true,
+  "target": "light.aint",
+  "intent": "light.set:on",
+  "device_ip": null,
+  "route": "ainternet.org -> policy gate -> .109 bridge -> usb-serial",
+  "receipt_mode": "sent-no-ack",
+  "note": "peripheral is IP-less; bridge is the carrier"
+}
+```
+
+## Must Not
+
+- Do not expose `127.0.0.1:8766` publicly.
+- Do not let URL path choose arbitrary serial commands.
+- Do not call this a full device identity unless the peripheral holds a key.
+- Do not silently resume after disconnect/reboot.
+

tibet_peripheral-0.1.0/docs/ROADMAP.md

@@ -0,0 +1,48 @@
+# Roadmap
+
+## v0: Local Proof
+
+- USB serial or Bluetooth serial to Arduino Uno.
+- Local HTTP bridge on `127.0.0.1`.
+- Commands: `PING`, `L`, `ON`, `OFF`, `STATUS`.
+- ACK receipt as JSON.
+
+## v0.1: Box Carrier
+
+- Run bridge on `.109`.
+- Expose only localhost.
+- Let IAB/overlay route call the bridge after sealed command verification.
+- Record bridge receipt in the box ledger.
+
+## v0.2: Session Binding
+
+- On attach, create `session_id`.
+- Require boot banner or local gesture.
+- Monotonic sequence enforced by bridge and optionally by firmware.
+- Any disconnect/reboot marks peripheral `dormant/unproven`.
+
+## v0.3: Capability Grants
+
+- Map public actions to grants:
+  - `light.read`
+  - `light.toggle`
+  - `light.set`
+  - `sensor.read`
+- Add relation assurance requirement per action.
+
+## v0.4: Carriers
+
+- USB serial.
+- RFCOMM / HC-05 style Bluetooth serial.
+- BLE GATT characteristic.
+- LoRa serial modem.
+- Android companion app carrier.
+
+## v1: PyPI Candidate
+
+- Remove `Private :: Do Not Upload`.
+- Add formal schemas.
+- Add conformance vectors.
+- Add signed receipt integration.
+- Add examples for ESP32/nRF boards.
+

tibet_peripheral-0.1.0/docs/ROOT_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,175 @@
+# Root Implementation Plan
+
+This is the handoff for promoting the live `light.aint` PoC from sandbox bridge
+to box/overlay integration.
+
+Current live proof on `.109`:
+
+```text
+127.0.0.1:8766/light/l
+  -> tibet-peripheral bridge
+  -> /dev/ttyUSB0
+  -> Arduino Uno R3 / ATmega328P
+  -> onboard LED TX/activity
+```
+
+The current Arduino sketch is fire-and-watch: it reacts enough to show TX/serial
+activity, but does not return ACK lines. The bridge therefore runs with
+`--no-ack` and emits `receipt_mode=sent-no-ack`.
+
+## Goal
+
+Make `light.aint` a local-first peripheral actor:
+
+```text
+public or overlay request
+  -> policy/grant gate
+  -> local route resolve: light.aint -> peripheral route
+  -> bridge action: /light/on|off|l|status
+  -> receipt
+```
+
+The Arduino must remain IP-less.
+
+## Core Work
+
+1. Add local peripheral route store.
+
+Suggested path:
+
+```text
+$RUN/peripherals/<aint>.route.json
+```
+
+Record shape:
+
+```json
+{
+  "kind": "org.tibet.peripheral.route.v1",
+  "aint": "light.aint",
+  "owner": "jasper.aint",
+  "bridge": {
+    "url": "http://127.0.0.1:8766",
+    "carrier": "usb-serial",
+    "serial": "/dev/ttyUSB0",
+    "device_ip": null
+  },
+  "state": "attached",
+  "assurance": "local-usb-tether",
+  "capabilities": ["light.read", "light.toggle", "light.set"],
+  "offline_rule": "disconnect_or_reboot_requires_rebind"
+}
+```
+
+2. Teach local AINS/known resolver about peripheral records.
+
+`light.aint` should resolve locally even if it is never published centrally.
+Central AINS may later advertise a route hint, but the authority is local.
+
+Resolver output should make the distinction explicit:
+
+```json
+{
+  "aint": "light.aint",
+  "entity_type": "peripheral",
+  "authority": "local-box-root",
+  "route_kind": "org.tibet.peripheral.route.v1",
+  "device_ip": null,
+  "state": "attached"
+}
+```
+
+3. Add bridge action adapter.
+
+Minimal mapping:
+
+```text
+light.read   -> GET http://127.0.0.1:8766/light/status
+light.toggle -> GET http://127.0.0.1:8766/light/l
+light.set:on -> GET http://127.0.0.1:8766/light/on
+light.set:off -> GET http://127.0.0.1:8766/light/off
+```
+
+4. Add policy gate before action.
+
+Do not let public URL call the bridge directly. Public URL calls a policy gate.
+
+Required checks:
+
+```text
+target resolves locally to peripheral route
+route.state == attached
+caller/owner grant allows capability
+presence/posture requirement for this action satisfied
+bridge URL is localhost or box-owned
+command is in route.capabilities
+```
+
+5. Emit receipts.
+
+Current receipt mode:
+
+```json
+{
+  "target": "light.aint",
+  "device_ip": null,
+  "receipt_mode": "sent-no-ack",
+  "seq": 7,
+  "session": "8391aa2c",
+  "command": "ON"
+}
+```
+
+After firmware ACK:
+
+```json
+{
+  "target": "light.aint",
+  "device_ip": null,
+  "receipt_mode": "ack",
+  "seq": 8,
+  "session": "new-session",
+  "command": "ON",
+  "ack": "OK ON"
+}
+```
+
+6. Offline/rebind rule.
+
+If `/dev/ttyUSB0` disappears, bridge exits, Arduino reboots, or ACK rhythm
+breaks:
+
+```text
+attached -> dormant/unproven
+```
+
+Reattach requires a new session id and a binding gesture:
+
+- physical plug-in event;
+- local button/light gesture;
+- operator confirmation;
+- future BT pairing proof.
+
+## Public URL
+
+`ainternet.org/light/on` is acceptable only as a demo/policy surface:
+
+```text
+GET /light/on
+  -> maps to intent light.set:on
+  -> target light.aint
+  -> policy gate
+  -> local bridge
+```
+
+It must not expose the Arduino or bridge to the network.
+
+## Later
+
+- Flash ACK firmware from `examples/arduino/light_node/light_node.ino`.
+- Add HMAC/counter mode if the peripheral gets a tiny secret.
+- Add BLE/RFCOMM carrier.
+- Add signed bridge receipts.
+- Add conformance vectors for route resolve, no-IP invariant, offline rebind,
+  and public URL policy.
+

tibet_peripheral-0.1.0/examples/arduino/light_node/light_node.ino

@@ -0,0 +1,99 @@
+// tibet-peripheral light node for Arduino Uno R3 / ATmega328P.
+//
+// It is not a crypto node. It is a tiny bound executor. The bridge verifies
+// outer intent and sends only commands this peripheral is allowed to perform.
+
+const int LED_PIN = LED_BUILTIN;
+bool led_on = false;
+String line = "";
+
+void setLed(bool on) {
+  led_on = on;
+  digitalWrite(LED_PIN, on ? HIGH : LOW);
+}
+
+void blinkMany(int count, int onMs, int offMs) {
+  bool restore = led_on;
+  for (int i = 0; i < count; i++) {
+    digitalWrite(LED_PIN, HIGH);
+    delay(onMs);
+    digitalWrite(LED_PIN, LOW);
+    delay(offMs);
+  }
+  digitalWrite(LED_PIN, restore ? HIGH : LOW);
+}
+
+void proofL() {
+  blinkMany(5, 60, 60);
+  delay(220);
+  blinkMany(1, 180, 120);
+}
+
+String field(String s, int idx) {
+  int start = 0;
+  for (int i = 0; i < idx; i++) {
+    start = s.indexOf('|', start);
+    if (start < 0) return "";
+    start++;
+  }
+  int end = s.indexOf('|', start);
+  if (end < 0) end = s.length();
+  return s.substring(start, end);
+}
+
+void handleCommand(String raw) {
+  raw.trim();
+  raw.toUpperCase();
+  String cmd = raw;
+
+  // TPER1|session|seq|cmd|arg, but keep bare-command compatibility.
+  if (raw.startsWith("TPER1|")) {
+    cmd = field(raw, 3);
+  }
+
+  if (cmd == "PING") {
+    Serial.println("OK PONG");
+  } else if (cmd == "L") {
+    proofL();
+    Serial.println("OK L");
+  } else if (cmd == "ON") {
+    setLed(true);
+    Serial.println("OK ON");
+  } else if (cmd == "OFF") {
+    setLed(false);
+    Serial.println("OK OFF");
+  } else if (cmd == "BLINK") {
+    proofL();
+    Serial.println("OK BLINK");
+  } else if (cmd == "STATUS") {
+    Serial.print("OK STATUS ");
+    Serial.println(led_on ? "ON" : "OFF");
+  } else if (cmd.length() == 0) {
+    // ignore empty line
+  } else {
+    Serial.println("ERR UNKNOWN");
+  }
+}
+
+void setup() {
+  pinMode(LED_PIN, OUTPUT);
+  setLed(false);
+  Serial.begin(9600);
+  Serial.println("READY tibet-peripheral light-node v0");
+}
+
+void loop() {
+  while (Serial.available() > 0) {
+    char c = (char)Serial.read();
+    if (c == '\n' || c == '\r') {
+      handleCommand(line);
+      line = "";
+    } else if (line.length() < 80) {
+      line += c;
+    } else {
+      line = "";
+      Serial.println("ERR TOO_LONG");
+    }
+  }
+}
+

tibet_peripheral-0.1.0/examples/light.aint.local-ains.json

@@ -0,0 +1,23 @@
+{
+  "domains": {
+    "light.aint": {
+      "status": "active",
+      "entity_type": "peripheral",
+      "owner": "jasper.aint",
+      "route_record": "examples/light.aint.route.json",
+      "capabilities": [
+        "light.read",
+        "light.toggle",
+        "light.set"
+      ],
+      "route": {
+        "kind": "org.tibet.peripheral.route.v1",
+        "bridge": "local",
+        "carrier": "usb-serial",
+        "box_required": true
+      },
+      "note": "Local registry alias. The box/root remains authority; AINS is a lookup, not the trust root."
+    }
+  }
+}
+

tibet_peripheral-0.1.0/examples/light.aint.route.json

@@ -0,0 +1,32 @@
+{
+  "kind": "org.tibet.peripheral.route.v1",
+  "aint": "light.aint",
+  "owner": "jasper.aint",
+  "subject": {
+    "class": "peripheral",
+    "hardware": "Arduino Uno R3 / ATmega328P",
+    "description": "Onboard LED bound through JTM-T15/.109 serial bridge"
+  },
+  "bridge": {
+    "node": "JTM-T15",
+    "node_hint": "192.168.4.109",
+    "url": "http://127.0.0.1:8766",
+    "carrier": "usb-serial",
+    "serial": "/dev/ttyUSB0",
+    "device_ip": null
+  },
+  "state": "attached",
+  "assurance": "local-usb-tether",
+  "capabilities": [
+    "light.read",
+    "light.toggle",
+    "light.set"
+  ],
+  "offline_rule": "disconnect_or_reboot_requires_rebind",
+  "public_url_policy": {
+    "allowed": true,
+    "example": "/light/on",
+    "note": "public URL reaches a policy gate; the Arduino is not public"
+  }
+}
+

tibet_peripheral-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling==1.27.0"]   # pin: hatchling >=1.28 emits Metadata-2.5, which older PyPI/pip trip over
+build-backend = "hatchling.build"
+
+[project]
+name = "tibet-peripheral"
+version = "0.1.0"
+description = "IP-less peripheral actors for TIBET/AInternet: serial, Bluetooth, BLE, LoRa and smart-device executors bound under a box/root."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Jasper van de Meent", email = "jasper@humotica.nl" },
+    { name = "Codex", email = "codex@humotica.nl" },
+]
+keywords = ["tibet", "ainternet", "iot", "bluetooth", "ble", "serial", "arduino", "rvp", "peripheral"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications",
+    "Topic :: Home Automation",
+    "Topic :: System :: Hardware",
+]
+dependencies = []
+
+[project.scripts]
+tibet-peripheral = "tibet_peripheral.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tibet_peripheral"]
+

tibet_peripheral-0.1.0/src/tibet_peripheral/__init__.py

@@ -0,0 +1,6 @@
+"""IP-less peripheral actors for TIBET/AInternet."""
+
+from .protocol import Frame, PeripheralSession, SessionError
+
+__all__ = ["Frame", "PeripheralSession", "SessionError"]
+

tibet_peripheral-0.1.0/src/tibet_peripheral/bridge.py

@@ -0,0 +1,105 @@
+"""Local HTTP bridge for an IP-less light peripheral."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import secrets
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Optional
+
+from .protocol import PeripheralSession
+from .serial_line import SerialLine
+
+
+class LightBridge:
+    def __init__(
+        self,
+        serial: SerialLine,
+        actor: str = "light.aint",
+        session_id: str | None = None,
+        wait_ack: bool = True,
+    ) -> None:
+        self.serial = serial
+        self.actor = actor
+        self.wait_ack = wait_ack
+        self.session = PeripheralSession(session_id or secrets.token_hex(4))
+
+    def command(self, cmd: str) -> dict:
+        frame = self.session.next_frame(cmd)
+        # Compatibility: old Arduino sketches may understand bare commands.
+        wire = cmd.upper() if cmd.upper() in {"PING", "L", "ON", "OFF", "BLINK", "STATUS"} else frame.encode()
+        ack = self.serial.line(wire, wait_ack=self.wait_ack)
+        self.session.accept_ack(frame, ack)
+        return {
+            "ok": True,
+            "target": self.actor,
+            "device_ip": None,
+            "receipt_mode": "ack" if self.wait_ack else "sent-no-ack",
+            "session": frame.session,
+            "seq": frame.seq,
+            "command": cmd.upper(),
+            "ack": ack,
+        }
+
+
+BRIDGE: Optional[LightBridge] = None
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, fmt: str, *args: object) -> None:
+        print("%s - %s" % (self.address_string(), fmt % args))
+
+    def _json(self, status: int, body: dict) -> None:
+        data = json.dumps(body, sort_keys=True).encode("utf-8")
+        self.send_response(status)
+        self.send_header("content-type", "application/json")
+        self.send_header("content-length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self) -> None:
+        route = self.path.split("?", 1)[0].rstrip("/")
+        mapping = {
+            "/light/ping": "PING",
+            "/light/l": "L",
+            "/light/blink": "BLINK",
+            "/light/on": "ON",
+            "/light/off": "OFF",
+            "/light/status": "STATUS",
+        }
+        cmd = mapping.get(route)
+        if cmd is None:
+            self._json(404, {"ok": False, "error": "unknown route"})
+            return
+        if BRIDGE is None:
+            self._json(503, {"ok": False, "error": "bridge not ready"})
+            return
+        try:
+            self._json(200, BRIDGE.command(cmd))
+        except Exception as exc:
+            self._json(502, {"ok": False, "target": BRIDGE.actor, "command": cmd, "error": str(exc)})
+
+
+def run_http(serial_path: str, baud: int, host: str, port: int, actor: str, wait_ack: bool = True) -> None:
+    global BRIDGE
+    BRIDGE = LightBridge(SerialLine(serial_path, baud), actor=actor, wait_ack=wait_ack)
+    print(f"tibet-peripheral bridge: http://{host}:{port}/light/l -> {serial_path} as {actor}")
+    ThreadingHTTPServer((host, port), Handler).serve_forever()
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--serial", required=True)
+    ap.add_argument("--baud", type=int, default=9600)
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=8765)
+    ap.add_argument("--actor", default="light.aint")
+    ap.add_argument("--no-ack", action="store_true", help="send command and return without waiting for firmware ACK")
+    args = ap.parse_args(argv)
+    run_http(args.serial, args.baud, args.host, args.port, args.actor, wait_ack=not args.no_ack)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tibet_peripheral-0.1.0/src/tibet_peripheral/cli.py

@@ -0,0 +1,33 @@
+"""CLI entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+
+from .bridge import main as bridge_main
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="tibet-peripheral")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    b = sub.add_parser("bridge")
+    b.add_argument("--serial", required=True)
+    b.add_argument("--baud", type=int, default=9600)
+    b.add_argument("--host", default="127.0.0.1")
+    b.add_argument("--port", type=int, default=8765)
+    b.add_argument("--actor", default="light.aint")
+    b.add_argument("--no-ack", action="store_true")
+    args = ap.parse_args(argv)
+    if args.cmd == "bridge":
+        return bridge_main([
+            "--serial", args.serial,
+            "--baud", str(args.baud),
+            "--host", args.host,
+            "--port", str(args.port),
+            "--actor", args.actor,
+        ] + (["--no-ack"] if args.no_ack else []))
+    raise AssertionError(args.cmd)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tibet_peripheral-0.1.0/src/tibet_peripheral/protocol.py

@@ -0,0 +1,79 @@
+"""Tiny causal frame protocol for constrained peripherals.
+
+This is deliberately not full TIBET crypto. The bridge/box owns crypto and
+policy. The peripheral receives a small command only after the bridge has
+verified the outer sealed intent. The peripheral proves continuity by staying
+inside a session id and monotonic sequence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+MAGIC = "TPER1"
+MAX_TOKEN = 48
+
+
+class SessionError(ValueError):
+    """Frame failed the local peripheral session guard."""
+
+
+@dataclass(frozen=True)
+class Frame:
+    session: str
+    seq: int
+    cmd: str
+    arg: str = ""
+
+    def encode(self) -> str:
+        for name, value in (
+            ("session", self.session),
+            ("cmd", self.cmd),
+            ("arg", self.arg),
+        ):
+            if "|" in value or "\n" in value or "\r" in value:
+                raise ValueError(f"{name} contains a frame separator")
+            if len(value) > MAX_TOKEN:
+                raise ValueError(f"{name} too long")
+        if self.seq < 0:
+            raise ValueError("seq must be non-negative")
+        return f"{MAGIC}|{self.session}|{self.seq}|{self.cmd.upper()}|{self.arg}\n"
+
+    @classmethod
+    def decode(cls, line: str) -> "Frame":
+        parts = line.strip().split("|")
+        if len(parts) != 5 or parts[0] != MAGIC:
+            raise ValueError("not a TPER1 frame")
+        try:
+            seq = int(parts[2])
+        except ValueError as exc:
+            raise ValueError("bad seq") from exc
+        return cls(parts[1], seq, parts[3].upper(), parts[4])
+
+
+class PeripheralSession:
+    """Fail-closed continuity guard for one attached peripheral."""
+
+    def __init__(self, session: str, allowed: set[str] | None = None) -> None:
+        if not session:
+            raise ValueError("session required")
+        self.session = session
+        self.last_seq = -1
+        self.allowed = allowed or {"PING", "L", "ON", "OFF", "BLINK", "STATUS"}
+
+    def next_frame(self, cmd: str, arg: str = "") -> Frame:
+        cmd = cmd.upper()
+        if cmd not in self.allowed:
+            raise SessionError(f"command not allowed: {cmd}")
+        return Frame(self.session, self.last_seq + 1, cmd, arg)
+
+    def accept_ack(self, frame: Frame, ack: str) -> None:
+        if frame.session != self.session:
+            raise SessionError("ack for wrong session")
+        if frame.seq != self.last_seq + 1:
+            raise SessionError("ack seq is not next")
+        if not ack.startswith("OK"):
+            raise SessionError(f"peripheral rejected command: {ack}")
+        self.last_seq = frame.seq
+

tibet_peripheral-0.1.0/src/tibet_peripheral/route.py

@@ -0,0 +1,51 @@
+"""Peripheral route records.
+
+These records are intentionally local-first. AINS may help find a route, but the
+box/root decides whether a peripheral is bound and what it may do.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class PeripheralRoute:
+    aint: str
+    owner: str
+    bridge_url: str
+    carrier: str
+    device_ip: None = None
+    capabilities: tuple[str, ...] = field(default_factory=tuple)
+    state: str = "attached"
+    assurance: str = "local-tether"
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PeripheralRoute":
+        if data.get("kind") != "org.tibet.peripheral.route.v1":
+            raise ValueError("not a peripheral route v1 record")
+        aint = str(data.get("aint") or "")
+        owner = str(data.get("owner") or "")
+        bridge = data.get("bridge") or {}
+        if not aint or not owner or not bridge.get("url"):
+            raise ValueError("route record missing aint, owner, or bridge.url")
+        return cls(
+            aint=aint,
+            owner=owner,
+            bridge_url=str(bridge["url"]),
+            carrier=str(bridge.get("carrier") or "unknown"),
+            device_ip=None,
+            capabilities=tuple(data.get("capabilities") or ()),
+            state=str(data.get("state") or "attached"),
+            assurance=str(data.get("assurance") or "local-tether"),
+        )
+
+    def can(self, capability: str) -> bool:
+        return capability in self.capabilities
+
+
+def load_route(path: str | Path) -> PeripheralRoute:
+    return PeripheralRoute.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))
+

tibet_peripheral-0.1.0/src/tibet_peripheral/serial_line.py

@@ -0,0 +1,72 @@
+"""Small POSIX serial helper, stdlib only."""
+
+from __future__ import annotations
+
+import os
+import select
+import termios
+import time
+
+
+BAUD = {
+    9600: termios.B9600,
+    19200: termios.B19200,
+    38400: termios.B38400,
+    57600: termios.B57600,
+    115200: termios.B115200,
+}
+
+
+class SerialLine:
+    def __init__(self, path: str, baud: int = 9600, timeout: float = 2.0, reset_delay: float = 1.8) -> None:
+        if baud not in BAUD:
+            raise ValueError(f"unsupported baud: {baud}")
+        self.path = path
+        self.timeout = timeout
+        self.fd = os.open(path, os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK)
+        attrs = termios.tcgetattr(self.fd)
+        attrs[0] = 0
+        attrs[1] = 0
+        attrs[2] = termios.CS8 | termios.CREAD | termios.CLOCAL
+        attrs[3] = 0
+        attrs[4] = BAUD[baud]
+        attrs[5] = BAUD[baud]
+        attrs[6][termios.VMIN] = 0
+        attrs[6][termios.VTIME] = 0
+        termios.tcsetattr(self.fd, termios.TCSANOW, attrs)
+        if reset_delay:
+            time.sleep(reset_delay)
+        self.drain()
+
+    def drain(self) -> None:
+        while True:
+            ready, _, _ = select.select([self.fd], [], [], 0)
+            if not ready:
+                return
+            try:
+                if not os.read(self.fd, 4096):
+                    return
+            except BlockingIOError:
+                return
+
+    def line(self, text: str, wait_ack: bool = True) -> str:
+        payload = text if text.endswith("\n") else text + "\n"
+        os.write(self.fd, payload.encode("ascii"))
+        if not wait_ack:
+            return "OK SENT_NO_ACK"
+        end = time.time() + self.timeout
+        buf = b""
+        while time.time() < end:
+            ready, _, _ = select.select([self.fd], [], [], 0.05)
+            if not ready:
+                continue
+            chunk = os.read(self.fd, 1024)
+            if not chunk:
+                continue
+            buf += chunk
+            if b"\n" in buf:
+                return buf.splitlines()[0].decode("ascii", errors="replace").strip()
+        raise TimeoutError(f"no ACK for {text.strip()}")
+
+    def close(self) -> None:
+        os.close(self.fd)

tibet_peripheral-0.1.0/tests/test_protocol.py

@@ -0,0 +1,36 @@
+from tibet_peripheral.protocol import Frame, PeripheralSession, SessionError
+
+
+def test_frame_roundtrip():
+    f = Frame("abcd", 7, "on")
+    assert f.encode() == "TPER1|abcd|7|ON|\n"
+    assert Frame.decode(f.encode()) == Frame("abcd", 7, "ON", "")
+
+
+def test_session_accepts_next_ack():
+    s = PeripheralSession("s1")
+    f = s.next_frame("L")
+    s.accept_ack(f, "OK L")
+    assert s.last_seq == 0
+
+
+def test_session_rejects_bad_ack():
+    s = PeripheralSession("s1")
+    f = s.next_frame("ON")
+    try:
+        s.accept_ack(f, "ERR UNKNOWN")
+    except SessionError:
+        pass
+    else:
+        raise AssertionError("expected SessionError")
+
+
+def test_disallow_command():
+    s = PeripheralSession("s1", allowed={"PING"})
+    try:
+        s.next_frame("ON")
+    except SessionError:
+        pass
+    else:
+        raise AssertionError("expected SessionError")
+

tibet_peripheral-0.1.0/tests/test_route.py

@@ -0,0 +1,31 @@
+import json
+from pathlib import Path
+
+from tibet_peripheral.route import PeripheralRoute, load_route
+
+
+def test_route_loads(tmp_path: Path):
+    p = tmp_path / "light.route.json"
+    p.write_text(json.dumps({
+        "kind": "org.tibet.peripheral.route.v1",
+        "aint": "light.aint",
+        "owner": "jasper.aint",
+        "bridge": {"url": "http://127.0.0.1:8766", "carrier": "usb-serial"},
+        "capabilities": ["light.read", "light.toggle"],
+        "state": "attached",
+    }))
+    route = load_route(p)
+    assert route.aint == "light.aint"
+    assert route.device_ip is None
+    assert route.can("light.toggle")
+    assert not route.can("door.unlock")
+
+
+def test_route_rejects_wrong_kind():
+    try:
+        PeripheralRoute.from_dict({"kind": "x"})
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("expected ValueError")
+