TinyOrch Design Notes¶

Design Motivation¶

The typical processing pipeline on an embedded SHM node is a sequence of ordered operations:

acquisition → filter → FFT → system identification → damage detection → output results

Traditional approaches hardcode these operations in app_main(). TinyOrch data-fies this process — the flow definition itself is data (a sequence of steps) that can be remotely created, modified, and executed by external Agents or users via MQTT.

Core Design Decisions¶

Compile-Time Type Validation vs Runtime¶

TinyOrch performs validation at tiny_orch_step() definition time:

tiny_orch_step(flow, 0, "raw_0", "butterworth", "filtered")
  ↓
1. bench_get("raw_0") → type TINY_TYPE_F32_ARR
2. bench_get_tool_fn("butterworth") → in_type = TINY_TYPE_F32_ARR
3. TINY_TYPE_F32_ARR == TINY_TYPE_F32_ARR → ✅
4. Save step definition

Errors are exposed at definition time, not at runtime.

Execution Engine¶

tiny_orch_go() iterates through steps in order:

for each step in flow.steps:
  1. bench_get(step.src)        → get data pointer
  2. bench_get_tool_fn(step.tool) → get function pointer
  3. fn(in_ptr, out_ptr)        → execute tool
  4. bench_put(step.dst, ...)   → put back onto bench

Sequential execution; each step must complete before the next begins
On step failure, the flow terminates immediately and transitions to ERROR state
No data copying; fully zero-copy

Flow vs One-Shot Single Step¶

	`go(flow)`	`run(src, tool, dst)`
Definition	Requires prior create + step	No definition needed
Type validation	At definition time	Each invocation
Use case	Repeated fixed pipelines	One-shot debugging or Agent ad-hoc operations

Simple, Reliable State Machine¶

A flow has only 4 states with no intermediate states:

DEFINED → (go executing) → DONE
                          → ERROR

No RUNNING interruptible state (MVP does not implement async execution).

MQTT Remote Orchestration Pattern¶

Typical Agent interaction:

1. BENCH,TOOLS       → discover available tools
2. BENCH,DATA        → discover available data
3. ORCH,CREATE,flow  → create a flow
4. ORCH,STEP,... ×N  → define steps
5. ORCH,GO,flow      → execute
6. ORCH,STATUS,flow  → check status
7. BENCH,DATA        → view results

In this mode, the Agent does not need to know the C API — it can control the entire processing pipeline by sending MQTT commands.

Design Constraints¶

Linear sequential: MVP does not support branching, parallelism, or loops. Steps execute strictly in index order
Synchronous blocking: When go() returns, all steps have completed or an error has occurred
No heap allocation: Flow and step tables are statically allocated at tiny_orch_init()
Sparse steps: Step indices need not be contiguous; unused indices are automatically skipped