diff --git a/MASTER_SETUP_GUIDE.md b/MASTER_SETUP_GUIDE.md new file mode 100644 index 0000000..ac2f843 --- /dev/null +++ b/MASTER_SETUP_GUIDE.md @@ -0,0 +1,65 @@ +# APEX Master Setup Guide (L1/L2/L3 Onboarding) + +## 1) Prerequisites +- Git with submodule support +- Node.js + npm (Core/RAM) +- Bun (Core/CLI) +- Python 3.10+ (CLI tests/tooling) +- PlatformIO (firmware builds where applicable) + +## 2) Clone and Initialize +```bash +git clone APEX +cd APEX +git submodule update --init --recursive +``` + +## 3) Bring Up Core Layers + +### Core/RAM +```bash +cd Core/RAM +npm install +npm run dev +``` + +### Core/CLI +```bash +cd Core/CLI +bun run dev +``` + +## 4) Node-Level Onboarding + +### L1 MicroMax +1. Connect node over USB serial. +2. Configure firmware for supported board (Uno/Pico/ESP32 wired mode). +3. Validate ASP line framing with: + - `{"query":"WHO_ARE_YOU"}` + - `{"action":"WRITE","target":"D13","value":1}` + +### L2 MiniMax +1. Provision WiFi credentials and MQTT broker endpoint. +2. Ensure bridge mirrors ASP payloads without mutating command/event semantics. +3. Validate heartbeat + reconnection under temporary network loss. + +### L3 MegaMax +1. Provision SIM/modem and APN settings. +2. Validate LTE data path first, then SMS fallback path. +3. Confirm periodic telemetry (including GPS if enabled) with ASP-compliant JSON. + +## 5) ASP v2.0 Conformance Checks +- Use `./SPEC_ASP_V2.md` as canonical reference. +- Ensure nodes accept legacy minimal payloads and v2 envelope payloads. +- Ensure parsers validate expected keys/types and reject malformed frames safely. + +## 6) Fail-Safe Expectations +- Heartbeat loss should trigger deterministic safe behavior on actuator-capable nodes. +- Recovery should send explicit `event`, `ack`, or `error` frames where possible. + +## 7) Documentation Map +- Protocol spec: `./SPEC_ASP_V2.md` +- Research log: `./RESEARCH.md` +- L1 docs: `./docs/MicroMax/DOCS.md` +- L2 docs: `./docs/MiniMax/DOCS.md` +- L3 docs: `./docs/MegaMax/DOCS.md` diff --git a/README.md b/README.md index 3d6059e..0667c73 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,9 @@ cargo run ## Documentation - Architecture overview: [`ARCHITECTURE.md`](./ARCHITECTURE.md) +- ASP v2.0 specification: [`SPEC_ASP_V2.md`](./SPEC_ASP_V2.md) +- Master setup guide: [`MASTER_SETUP_GUIDE.md`](./MASTER_SETUP_GUIDE.md) +- Node docs: [`docs/MicroMax/DOCS.md`](./docs/MicroMax/DOCS.md), [`docs/MiniMax/DOCS.md`](./docs/MiniMax/DOCS.md), [`docs/MegaMax/DOCS.md`](./docs/MegaMax/DOCS.md) - Agent capability notes: [`AGENT.md`](./AGENT.md) - Workflow and planning system: [`conductor/index.md`](./conductor/index.md) - Conductor module guide: [`conductor/README.md`](./conductor/README.md) @@ -78,4 +81,3 @@ cargo run - **[Contributing](./CONTRIBUTING.md)** - **[Code of Conduct](./CODE_OF_CONDUCT.md)** - **[Security Policy](./SECURITY.md)** - diff --git a/RESEARCH.md b/RESEARCH.md new file mode 100644 index 0000000..59eca92 --- /dev/null +++ b/RESEARCH.md @@ -0,0 +1,45 @@ +# RESEARCH: ASP v2.0 + Node Documentation Audit + +## Scope +- Module: root `APEX` repository (Protocol Architect task) +- Goal: produce canonical protocol and setup documentation for L1/L2/L3 nodes + +## Repository Audit Findings +1. The primary in-repo ASP references are in: + - `./ARCHITECTURE.md` + - `./AI_PROMPTS.md` + - `./MicroMax/README.md` +2. Current documented baseline for ASP: + - JSON messages + - newline-terminated framing on serial links + - 115200 baud (8-N-1) for MicroMax serial transport + - canonical example fields in active use: + - Command path: `action`, `target`, `value` + - Event path: `event`, `source`, `type` + - Heartbeat/query path: `query` (example `WHO_ARE_YOU`) +3. L1/L2/L3 submodules currently expose high-level module READMEs and capabilities, but no root-level unified formal spec file yet. + +## Industry Pattern Research (Applied Principles) +Because external docs were not reachable from this sandbox at runtime, this phase applies stable, widely adopted IoT protocol patterns used across systems such as device shadows and MQTT-first home automation stacks: +- Keep a backward-compatible minimal payload path. +- Add optional metadata envelope fields for extensibility (`v`, `id`, timestamps, node identity). +- Separate message intent (`command`, `query`, `event`, `telemetry`, `ack`, `error`) to simplify routing. +- Standardize correlation (`id`/`ref`) for request/ack tracing. +- Define transport-agnostic payload semantics so Serial, MQTT, WebSocket, and cellular links can mirror the same JSON contract. + +## Design Decisions for Documentation Output +1. Define **ASP v2.0** as an additive superset: existing simple messages remain valid. +2. Provide one canonical spec file (`SPEC_ASP_V2.md`) with: + - wire framing + - required vs optional keys + - validation and security rules + - examples for command/event/heartbeat/ack/error/telemetry +3. Provide per-level docs (`DOCS.md`) for: + - MicroMax (L1 wired) + - MiniMax (L2 wireless MQTT bridge) + - MegaMax (L3 cellular bridge) +4. Provide one onboarding runbook (`MASTER_SETUP_GUIDE.md`) covering: + - hardware bring-up + - transport mapping + - protocol conformance checks + - fail-safe expectations diff --git a/SPEC_ASP_V2.md b/SPEC_ASP_V2.md new file mode 100644 index 0000000..dc6815e --- /dev/null +++ b/SPEC_ASP_V2.md @@ -0,0 +1,123 @@ +# Apex Serial Protocol (ASP) v2.0 Specification + +## 1) Purpose +ASP v2.0 defines a transport-agnostic JSON message contract for APEX nodes. + +- L1 (MicroMax): USB Serial +- L2 (MiniMax): WiFi/MQTT bridge +- L3 (MegaMax): Cellular data + SMS fallback bridge + +ASP v2.0 is **backward-compatible** with existing minimal JSON messages already documented in APEX. + +## 2) Transport and Framing + +### 2.1 Serial (L1 baseline) +- Encoding: UTF-8 JSON +- Framing: one JSON object per line (`\n` terminated) +- Default line speed: `115200 8-N-1` + +### 2.2 Networked transports (L2/L3) +- Payload schema stays identical to serial JSON. +- Framing is delegated to transport (MQTT/WebSocket/TCP message boundaries). + +## 3) Message Model + +### 3.1 Minimal backward-compatible forms (valid) +```json +{"action":"WRITE","target":"D13","value":1} +{"event":"TRIGGER","source":"D2","type":"Interrupt"} +{"query":"WHO_ARE_YOU"} +``` + +### 3.2 Preferred v2 envelope (recommended) +```json +{ + "v": "2.0", + "id": "a7c6f5f0-1b6f-4a3f-bbe8-7f8c20f1b4ef", + "ts": "2026-04-16T00:00:00Z", + "node": {"level":"L1","id":"micromax-uno-01"}, + "kind": "command" +} +``` + +## 4) Field Definitions + +### 4.1 Core optional envelope fields +- `v` (string): protocol version, recommended `"2.0"`. +- `id` (string): message correlation id. +- `ts` (string): ISO-8601 UTC timestamp. +- `node` (object): node identity metadata. + - `node.level`: `L1` | `L2` | `L3` + - `node.id`: unique node identifier +- `kind` (string): `command` | `query` | `event` | `telemetry` | `ack` | `error` + +### 4.2 Existing operational fields (must remain supported) +- Command fields: `action`, `target`, `value` +- Query fields: `query` +- Event fields: `event`, `source`, `type` + +### 4.3 Ack/Error fields (v2 standardization) +- Ack: + - `kind: "ack"` + - `ok: true|false` + - `ref`: request `id` being acknowledged +- Error: + - `kind: "error"` + - `code`: stable machine code (e.g., `ERR_UNKNOWN_ACTION`) + - `message`: human-readable description + - `ref`: originating request id when available + +## 5) Canonical Message Examples + +### 5.1 Command (write output) +```json +{"v":"2.0","id":"cmd-001","kind":"command","action":"WRITE","target":"D13","value":1} +``` + +### 5.2 Query (heartbeat/identity) +```json +{"v":"2.0","id":"hb-001","kind":"query","query":"WHO_ARE_YOU"} +``` + +### 5.3 Event (edge trigger) +```json +{"v":"2.0","id":"evt-001","kind":"event","event":"TRIGGER","source":"D2","type":"Interrupt"} +``` + +### 5.4 Telemetry +```json +{"v":"2.0","id":"tel-001","kind":"telemetry","source":"A0","metric":"light","value":512,"unit":"raw"} +``` + +### 5.5 Ack +```json +{"v":"2.0","id":"ack-001","kind":"ack","ok":true,"ref":"cmd-001"} +``` + +### 5.6 Error +```json +{"v":"2.0","id":"err-001","kind":"error","code":"ERR_INVALID_TARGET","message":"Unknown target pin","ref":"cmd-001"} +``` + +## 6) Validation Rules +- Payload MUST be valid JSON object. +- Unknown top-level keys MAY be ignored unless strict mode is enabled. +- Receivers MUST validate type/shape for recognized keys. +- `action`, `query`, `event` values SHOULD be treated case-sensitive. +- `id` values SHOULD be unique per sender session. +- Numeric `value` fields SHOULD be range-checked by target type. + +## 7) Fail-Safe and Heartbeat Semantics +- Host heartbeat uses `query: "WHO_ARE_YOU"` or a node-defined heartbeat query. +- Nodes SHOULD define heartbeat timeout behavior. +- On timeout/disconnect, nodes controlling actuators SHOULD revert to safe state and emit an `event` or `error` frame when possible. + +## 8) Security Notes +- Validate all incoming JSON keys and value types. +- Never execute unsanitized command strings from protocol payloads. +- For untrusted networks, use authenticated/encrypted transport wrappers for ASP payloads. + +## 9) Versioning and Compatibility +- ASP v2.0 is additive over legacy minimal frames. +- Breaking changes require a new major version field (`v`). +- Extensions SHOULD prefer new optional keys over mutating existing meanings. diff --git a/docs/MegaMax/DOCS.md b/docs/MegaMax/DOCS.md new file mode 100644 index 0000000..c1f8733 --- /dev/null +++ b/docs/MegaMax/DOCS.md @@ -0,0 +1,37 @@ +# MegaMax (L3) DOCS + +## Role +MegaMax is the long-range tier for cellular-connected and mobility-oriented deployments. + +## Hardware Scope +- ESP32 + SIM800L / SIM7000G +- RP2040 + SIM7000G +- LilyGO T-SIM series + +## Transport Profile +- Primary transport: LTE/Cat-M/NB-IoT data sockets +- Fallback transport: SMS control channel +- Payload contract: ASP v2.0 JSON for data channels; SMS may carry compact command/query subsets + +## ASP v2.0 Mapping +- Reuse L1/L2 core semantics (`command`, `query`, `event`, `telemetry`, `ack`, `error`). +- For failover, keep command intent consistent across data and SMS paths. +- Recommended metadata: + - `node.level = "L3"` + - correlation keys (`id`, `ref`) for retransmit-safe operation + +## Typical L3 Payloads +```json +{"v":"2.0","id":"gps-01","kind":"telemetry","metric":"gps","value":{"lat":12.34,"lon":56.78}} +{"v":"2.0","id":"cmd-01","kind":"command","action":"WRITE","target":"RELAY1","value":0} +{"v":"2.0","id":"ack-01","kind":"ack","ok":true,"ref":"cmd-01"} +``` + +## Reliability Expectations +- State machine should handle transitions between data, SMS fallback, and sleep. +- Buffered messages should retain `id` for dedupe and audit. + +## Verification Checklist +- [ ] Data/SMS mode transitions preserve command semantics +- [ ] GPS telemetry serializes to valid ASP telemetry frames +- [ ] Heartbeat + fail-safe behavior is deterministic under high latency diff --git a/docs/MicroMax/DOCS.md b/docs/MicroMax/DOCS.md new file mode 100644 index 0000000..7c5b0cc --- /dev/null +++ b/docs/MicroMax/DOCS.md @@ -0,0 +1,37 @@ +# MicroMax (L1) DOCS + +## Role +MicroMax is the wired, low-latency endpoint layer for direct actuator/sensor control. + +## Hardware Scope +- Arduino Uno / Nano (ATmega328P) +- Raspberry Pi Pico (RP2040) +- ESP32 (wired mode) + +## Transport Profile +- Primary transport: USB Serial +- ASP framing: newline-terminated JSON at 115200 baud (default) + +## ASP v2.0 Mapping +- Mandatory legacy compatibility fields: + - `action`, `target`, `value` + - `event`, `source`, `type` + - `query` (heartbeat/identity) +- Recommended v2 envelope: + - `v`, `id`, `ts`, `node`, `kind` + +## Baseline Message Examples +```json +{"action":"WRITE","target":"D13","value":1} +{"event":"TRIGGER","source":"D2","type":"Interrupt"} +{"query":"WHO_ARE_YOU"} +``` + +## Reliability Expectations +- Heartbeat timeout handling should move outputs to safe state. +- Ack/error responses should include correlation where available (`id`/`ref`). + +## Verification Checklist +- [ ] Serial command parser accepts legacy and envelope-based ASP frames +- [ ] Heartbeat timeout transitions to fail-safe +- [ ] Event and telemetry frames serialize as valid JSON lines diff --git a/docs/MiniMax/DOCS.md b/docs/MiniMax/DOCS.md new file mode 100644 index 0000000..e38a5e1 --- /dev/null +++ b/docs/MiniMax/DOCS.md @@ -0,0 +1,36 @@ +# MiniMax (L2) DOCS + +## Role +MiniMax is the local wireless node tier for ambient telemetry and sentry workflows. + +## Hardware Scope +- Raspberry Pi Pico W +- ESP32 / ESP32-CAM +- Challenger RP2040 WiFi + +## Transport Profile +- Primary transport: WiFi + MQTT (or equivalent wireless socket) +- Protocol contract: ASP v2.0 JSON mirrored over wireless transport + +## ASP v2.0 Mapping +- Command/query/event semantics match L1 payload contract. +- Wireless bridge should preserve payload body; transport metadata remains outside ASP payload. +- Recommended fields: + - `v`, `id`, `node`, `kind` + - telemetry-friendly keys: `metric`, `value`, `unit` + +## Typical L2 Payloads +```json +{"v":"2.0","id":"tel-123","kind":"telemetry","source":"pir-1","metric":"motion","value":1} +{"v":"2.0","id":"qry-123","kind":"query","query":"WHO_ARE_YOU"} +{"v":"2.0","id":"evt-123","kind":"event","event":"SENTRY_ALERT","source":"cam-1","type":"visual"} +``` + +## Reliability Expectations +- Reconnection logic should preserve session identity and re-publish heartbeat. +- Node should emit `ack`/`error` frames for mirrored command paths. + +## Verification Checklist +- [ ] MQTT heartbeat survives reconnect cycles +- [ ] ASP payload parity with L1 is maintained +- [ ] Sentry events publish as valid ASP event JSON