markpact-pololu

URI Router — model TellMesh

Ten dokument opisuje logiczny router URI (UriRouter) używany w markpact-pololu i orchestrowany przez urisys.

Implementacja Python: pakiet urirouter (import uri_router).
Mapa całego mesh: urisys/docs/MESH.md.

Zasada

UriRouter nie routuje pakietów.
UriRouter routuje intencje.

Intencja = operation z capability URI, np. stepper.move_relative, screen.frame.

Warstwy

flowchart LR
  MP[Markpact CO]
  US[urisys orchestration]
  UR[urirouter GDZIE+JAK]
  TR[Transport HTTP MQTT]
  RT[Runtime host ESP32]
  DR[Driver ticcmd I²C]

  MP --> US --> UR --> TR --> RT --> DR
Warstwa Paczka / repo Rola
Markpact markpacts/*.markpact.md CO — capability, flow, policy
urisys tellmesh/urisys wykonanie, approval, flow runner
UriRouter tellmesh/urirouter resolve → target → transport
uricore tellmesh/uricore registry, policy, local dispatch
Transport binding spec + host HTTP, MQTT, (NATS, Zenoh…)
Runtime uritic-host, ESP32 /uri/call edge
Ingress (opcja) nginx / Traefik TLS, reverse proxy — nie semantyka URI

Traefik/Envoy nie zastępują UriRouter.

Jedna koperta

{
  "uri": "stepper://tic-t249/axis/x/command/move-relative",
  "payload": {"steps": 100, "speed_sps": 200, "accel_sps2": 100},
  "context": {
    "approved": true,
    "dry_run": true,
    "environment": "mock",
    "request_id": "lab-01",
    "trace_id": "01H…",
    "deadline_ms": 5000
  }
}
Pole HTTP MQTT (canonical) Status
uri, payload, context wymagane wymagane ✅
request_id, reply_to opcjonalne zalecane ✅ MQTT
trace_id, deadline_ms opcjonalne opcjonalne ✅

Normalizacja koperty: uri_router.envelope.normalize_call_envelope
Spec transportów: markpact-contracts/.../uri-transport-binding.stepper.yaml

Cztery tabele routera

Tabela Źródło w tym repo Loader
Routes markpacts/pololu-tic-t249.stepper.markpact.md urisys manifest
Targets profiles/urisys.runtime.*.yaml URISYS_RESOLVER_CONFIG / edge.config.yaml
Policy Markpact policy + runtime.device_profile uri_control Runtime
Transports binding spec + adapter w Markpact uri_router.transport

Wybór profilu runtime bez zmiany authority URI:

context:
  runtime_profile: esp32-i2c-http-mqtt

Resolver tic-t249.profiles (hybrid) + runtime_profile w uri_router.resolver.

profiles/targets.yaml — deployment (profile sprzętowe, piny, Docker).
profiles/urisys.runtime.*.yaml — resolver — generuj z targets:

make resolver   # → profiles/urisys.runtime.{pc-only,esp32-only,hybrid,mqtt-pc}.yaml

Przepływ wywołania

sequenceDiagram
  participant F as flow / CLI / HTTP
  participant U as urisys
  participant R as uri_router
  participant H as uritic-host

  F->>U: POST /uri/call envelope
  U->>R: resolve_uri(authority)
  R->>R: target_profile + transport
  alt remote
    R->>H: delegate_transport_call
    H-->>R: result
    R-->>U: delegated
  else local
    U->>U: uri_control handler
  end

API (urirouter)

from uri_router import UriRouter

router = UriRouter()
router.load("profiles/urisys.runtime.hybrid.yaml")
router.delegate(
    "stepper://tic-t249-pc/axis/x/query/status",
    {},
    {"approved": True, "dry_run": True},
)

Kompatybilność wsteczna w uricore: uri_control.resolver, uri_control.transport, uri_control.envelope re-eksportują uri_router.

Skala

Poziom Runtime Markpact
ESP32 mini router + driver źródło generacji (marksync → uri_routes.h)
Edge (RPi/PC) uritic-host, urisys-node resolver YAML
Docker compose + labels org.markpact.* mount markpacts/
Cloud urisys orchestrator registry, audit (roadmap)

Powiązane