# Myrmic # Architecture New to the terminology? Start with [Core Concepts](./06_concepts.md). Myrmic's architecture is explained through four views. Each answers one question instead of trying to show the whole system at once. | View | Question | Primary audience | | --- | --- | --- | | **Swarm** | Where does my code run? | Everyone | | **Node** | What runs on a device? | Swarm Admins and contributors | | **Cell** | What does my code experience? | Application developers | | **Failure** | What happens when a Node is lost? | Evaluators and Swarm Admins | A separate stages picture answers: **What arrives when?** ## The structural commitment Myrmic separates three concerns that many systems fuse: - **Authority:** who decides leadership, membership, placement, and the serving role. - **Data:** what survives, including State, Mailboxes, and records. - **Execution:** what currently runs, with one active WebAssembly guest for each Cell. Each concern has its own durability and replication story. > **A Cell becomes sovereign over its Node only when both authority and committed data are replicated.** That is why the roadmap treats them as two distinct properties: Partition Tolerance for authority and Durability for data. ## One question per diagram The Swarm, Node, and Cell views explain the current architecture without mixing in roadmap claims. Failure behaviour is shown separately for the developer preview, Partition Tolerance, and Durability. Roadmap diagrams use amber, dashed elements and include the stage name inside the image. Current-state diagrams use solid elements. ## The views 1. [The Swarm View](./07_architecture/01_the-swarm-view.md) 2. [The Node View](./07_architecture/02_the-node-view.md) 3. [The Cell View](./07_architecture/03_the-cell-view.md) 4. [Failure Behaviour](./07_architecture/04_failure-behaviour.md) 5. [The Six Layers](./07_architecture/05_the-six-layers.md) The [Guarantees](./08_guarantees.md) page, not a diagram, is authoritative for current release behaviour. # Failure Behaviour Failure behaviour is easier to understand when each stage has its own diagram. The [Guarantees](../08_guarantees.md) page remains authoritative for the current release. Partition Tolerance and Durability below are roadmap stages, not preview capabilities. ## Developer Preview - remove and report ![Developer Preview behaviour when a Node is lost](../../images/failure-today.svg) Today, when a Node is lost: - Myrmic detects the departure, - affected deployments are removed, - the failure is reported explicitly, - the Cell is restarted on another qualifying Node if it was deployed with a restart policy, but never resumed - it begins from stored State, not from where it stopped, - State or Mailbox data held only on the lost Node can be lost with it. This is conservative by design. Starting an empty Cell under the old identity would claim continuity that did not actually exist. ## Partition Tolerance - authority survives ![Partition Tolerance behaviour when one of a Cell's voters is lost](../../images/failure-partition-tolerance.svg) **Partition Tolerance is a roadmap stage.** It replicates authority: who may decide and serve. Every Cell has a voter set of several Nodes, and a decision about the Cell is valid once a majority of them — a quorum — has agreed to it. When a voter is lost and the surviving voters still form a majority: - they form a quorum and elect a new leader, who takes the serving role, - fencing allows only one active serving copy, - authority no longer depends on one coordinator. Partition Tolerance does **not** replicate Cell State or Mailboxes. > **Partition Tolerance protects who decides, not what the Cell knows.** ## Durability - committed data survives ![Durability behaviour when the Cell's current Node is lost](../../images/failure-durability.svg) **Durability is a roadmap stage.** It replicates Cell State and Mailboxes across several Nodes; a write is committed once a quorum of them has stored it. When the current Node is lost and a majority remains: - the committed State and Mailbox remain available, - Myrmic selects an eligible Node, - the Cell resumes from committed State under the same SRI. If no majority remains, the Cell halts rather than inventing a new truth. Recovery then requires an explicit action by a Swarm Admin. > **Together, Partition Tolerance and Durability make a Cell sovereign over its Node.** ## Boundaries at every stage - A missing callback means the outcome is unknown. - External side effects need idempotency, deduplication, or fencing. - No stage creates global order across Cells. - Software cannot create physical redundancy for a unique sensor or actuator. ## See also - [Guarantees](../08_guarantees.md) - what the current release promises, and what it doesn't yet - [Roadmap](../09_roadmap.md) - what future stages are intended to add # The Cell View The Cell view answers: > **What happens when my Cell receives a Message?** ![A step-by-step view of message processing inside one Myrmic Cell](../../images/cell-view.svg) ## 1. A Message waits in the Mailbox Commands, Events, callbacks, and timer wake-ups enter the Cell through its Mailbox. The Mailbox separates Message arrival from the moment the Cell is ready to process it. ## 2. One Handler runs The Cell processes one Message at a time. The Handler reads the Cell's State, applies Application logic, and stages any Messages it wants to send. A slow Handler delays the work behind it, so Handlers should remain short. ## 3. The Handler stages one unit of work For a Command Handler, that unit groups: - consuming the inbound Message, - updating the Cell's State, - writing outbound Messages. The current transaction boundary, including what happens if the Handler fails or the destination lives on another Node, is stated on the [Guarantees](../08_guarantees.md) page. ## Messages continue the workflow An outbound Message enters another Cell's Mailbox. A result returns as a callback Message to the caller's Mailbox rather than as a blocking Cell-to-Cell call. ## External effects sit outside HTTP calls, MQTT publishes, and actuator writes sit outside the Cell transaction. Applications must make these effects idempotent, use a sink that supports deduplication or fencing, or accept at-least-once behaviour. ## Two design rules - Make every Handler safe to run twice. - Rely on order inside one Cell, never on a global order across Cells. ## See also - [Messages and Mailboxes](../06_concepts/03_messages-and-mailboxes.md) - how Commands and Events reach a Cell - [Handlers and Transactions](../06_concepts/04_handlers-state-and-transactions.md) - what runs when a Message is consumed # The Node View The Node view answers: > **What runs on a device?** ![OS-based and MCU-based Myrmic Nodes with the same four-part structure](../../images/node-view.svg) Both Node shapes use the same four-part structure: 1. hardware, 2. Signal Layer, 3. Node services, 4. Peer-to-Peer (P2P) Session Hub. The difference is how much platform functionality each Node carries locally. ## OS-based Node An OS-based Node can operate as an Orchestrator or Executor. Its Node services can include: - WebAssembly Cells through Wasmtime, - the Execution plugin, - Self-Organization services, - Data services, - gateways and Application clients. Its Signal Layer runs as a native process connected through inter-process communication (IPC). The P2P Session Hub uses Zenoh. ## MCU-based Node An MCU-based Node operates as an Executor. It runs: - WebAssembly Cells through WAMR with modules compiled ahead of time, - typed clients for platform services, - native Signal Layer tasks that use shared memory. The P2P Session Hub uses `zenoh-nano`. Other Nodes in the swarm can provide orchestration and full Data services. ## Same model, explicit differences Both Node classes expose Cells to the same Application model and peer-to-peer fabric. They do not pretend to have identical resources. Capabilities make the differences explicit, and placement uses those Capabilities when deciding where a Cell can run. > **Not every Node needs to carry every service.** ## See also - [The Six Layers](./05_the-six-layers.md) - the canonical layers every Node runs - [Connecting Physical Systems](../02_why-myrmic/04_connecting-physical-systems.md) - how Cells relate to native drivers and hardware I/O # The Six Layers Myrmic uses one canonical layer model across concepts, architecture, and reference documentation. ![The six canonical Myrmic layers](../../images/six-layers.svg) | Layer | OS-based Node | MCU-based Node | Primary concern | | --- | --- | --- | --- | | **1 · Execution** | Wasmtime Execution plugin | WAMR with modules compiled ahead of time | Cell execution and effects | | **2 · Self-Organization** | Self-Organization plugin | Services provided by the swarm | Membership, authority, placement | | **3 · Data** | Data plugin | Access through typed clients | State, Mailboxes, records | | **4 · Peer-to-Peer (P2P)** | Zenoh session | `zenoh-nano` session | Shared carrier and protocol fabric | | **5 · Transport** | TCP, TLS, BLE | Wi-Fi, BLE | Physical links | | **6 · Signal** | Native process over IPC | Native tasks over shared memory | Hardware-near acquisition and control | ## Important boundaries - The Signal Layer is native on both Node classes. - Gateway and CLI surfaces are ingress clients, not architecture layers. - MCU-based Nodes participate through typed clients rather than carrying the full plugin topology. - Roadmap stages strengthen authority and data guarantees without changing this visible layer model. ## See also - [Architecture](../07_architecture.md) - the four views and the six layers - [Understanding Myrmic](../02_why-myrmic/02_understanding-myrmic.md) - where these six layers fit in the bigger picture # The Swarm View The Swarm view answers one question: > **Where does my code run?** ![Cells distributed across OS-based and MCU-based Nodes in one Myrmic swarm](../../images/swarm-view.svg) ## The Application spans Nodes Myrmic can place the Cells in one Application on different Nodes: - `room/12` runs on an OS-based Node, - `orders` runs on another OS-based Node, - `valve-ctl` runs on an MCU-based Node next to its Signal Layer Capability. They remain one Application even though their execution is distributed. ## Identity is independent of location Cells address each other by a **Stable Resource Identifier (SRI)**. A sender targets `orders`, not the IP address or process currently running it. This keeps Application relationships stable when placement changes. ## Capabilities constrain placement A Cell can run on any reachable Node that provides its declared Capabilities. The `valve-ctl` Cell requires `line-a.signals`, so Myrmic places it with the native Signal Layer module that provides that Capability. The requirement is explicit rather than hidden in deployment scripts. ## One peer-to-peer fabric OS-based and MCU-based Nodes participate in the same peer-to-peer fabric. Browser, CLI, and other external clients reach Cells through application-facing gateways. Cells continue to communicate by SRI. The Swarm view intentionally does not explain authority, data replication, or failure stages. Those questions have their own diagrams. ## See also - [Architecture](../07_architecture.md) - the four views and the six layers - [Nodes and the Swarm](../06_concepts/02_nodes-capabilities-and-the-swarm.md) - the concepts behind this view # Community and Support ## Overview Myrmic is built in the open, and community input helps shape its direction. This page points you to the right place for questions, feedback, and support. ## Contributing Contributions of all sizes matter. You can help by improving docs, sharing demos, or contributing code. - Documentation: fix gaps, clarify steps, add examples. - Demos and examples: show real use cases. - Codebase: bug fixes and improvements. Start here: [Contributing](./14_contribution.md). ## Discussions If you have a question about Myrmic, or want to help others, join the conversation: - [GitHub Discussions](https://github.com/peeriot/myrmic/discussions) - [Discord](https://discord.gg/zExh79pWgj) For reproducible bugs with a minimal repro and logs, open a [GitHub Issue](https://github.com/peeriot/myrmic/issues). ## Social Media Follow Myrmic on [X (@MyrmicOfficial)](https://x.com/MyrmicOfficial) and [YouTube (@MyrmicOfficial)](https://www.youtube.com/@MyrmicOfficial) for updates, demos, and videos. ## Code of Conduct Be respectful and constructive. All contributors follow the project [Code of Conduct](https://github.com/peeriot/myrmic/blob/master/CODE_OF_CONDUCT.md). ## Security Reporting Please report security issues privately, following the [Security policy](https://github.com/peeriot/myrmic/blob/master/SECURITY.md). ## Licensing questions Whether your Cell, pipeline or firmware may stay proprietary, what to pass on when you ship Myrmic, and why contributors accept a CLA: the [Licensing](15_licensing.md) chapter answers the common cases, and [What You Can Build](15_licensing/01_what-you-can-build.md) is a step-by-step guide. If your case is not covered, ask in a [GitHub Discussion](https://github.com/peeriot/myrmic/discussions) - we would rather clarify than have you guess. --- sidebar_label: Core Concepts --- # Core Concepts Eleven concepts carry the Myrmic model. Everything else is detail beneath one of them. | Concept | One-line definition | | --- | --- | | **Application** | The boundary a developer declares and reasons about | | **Cell** | The unit of logic, state, and identity | | **SRN** | A human-readable, hierarchical name chosen for a Cell | | **SRI** | The stable identifier Myrmic derives from an SRN and uses to address the Cell | | **Node** | A device or operating-system process running Myrmic | | **Swarm** | Nodes that have found each other and behave as one system | | **Capability** | A function or resource a Node offers and a Cell requires for placement | | **Message** | A directed Command, a published Event, or a later callback | | **Mailbox** | The named storage path every Message uses | | **Handler** | The Cell's reaction to one Message and its state-transition boundary | | **State** | The Cell's owned memory between interactions | A developer writes the SRN. Myrmic derives the SRI deterministically, so the same SRN produces the same SRI on every Node without a naming registry. ```text SRN: product-order-021:item-011 SRI: 018f3c2e-9d41-7a52-b3ae-5f0c19c47d11 ``` The model fits together in a natural order: > **An Application declares Cells. Each Cell is named by an SRN and addressed by its stable SRI. It runs on a Node inside a swarm, is placed where its required Capabilities exist, receives Messages through its Mailbox, reacts in a Handler, and remembers in its State.** ## Read the model in order 1. [Applications, Cells, and Identity](./06_concepts/01_applications-cells-and-identity.md) 2. [Nodes, Capabilities, and the Swarm](./06_concepts/02_nodes-capabilities-and-the-swarm.md) 3. [Messages and Mailboxes](./06_concepts/03_messages-and-mailboxes.md) 4. [Handlers, State, and Transactions](./06_concepts/04_handlers-state-and-transactions.md) 5. [Where Data Lives](./06_concepts/05_where-data-lives.md) 6. [Recovery Models](./06_concepts/06_recovery-models.md) 7. [Cell Patterns](./06_concepts/07_cell-patterns.md) Concept pages explain what things are. [What Myrmic guarantees today](./08_guarantees.md) states what the current release promises. The [Roadmap](./09_roadmap.md) states what future stages are intended to add. # Applications, Cells, and Identity ## Application An **Application** is the boundary a developer declares and reasons about. It includes Cell classes, instances, bridges, assets, and deployment configuration. The boundary carries no runtime guarantee by itself. Cross-Application dependency management is not currently defined. ## Cell A **Cell** is a self-contained unit of logic, state, and identity. It is the smallest thing Myrmic deploys, addresses, and remembers. ### Stable logical identity An Application can give a Cell a human-readable **Stable Resource Name (SRN)**. Myrmic derives a fixed-size **Stable Resource Identifier (SRI)** from that name. Callers use the SRI, not a network address, port, or Node name. Identity and location are separate concepts. ### WebAssembly module Cell logic is written in Rust and compiled to WebAssembly. OS-based Nodes execute it with Wasmtime. MCU-based Nodes execute modules compiled ahead of time with WAMR. The Node exposes only the functions allowed by the Cell's Capabilities. ### Named handlers A Cell exposes Command and Event handlers discovered from the module. Timers can wake named handlers later or periodically. ### Owned state A Cell owns state under its SRI. State is what the Cell remembers between Messages. The current durability contract is defined on the [Guarantees](../08_guarantees.md) page. ## Class and instance A **Cell Class** is the deployable definition: the WebAssembly binary, build targets, capability requirements, and initialization contract. A **Cell instance** is one running identity created from that class, with its own SRI and state. ## Names and identifiers The mapping from SRN to SRI is deterministic. This means: - the Application chooses the name, - the derivation needs no central naming registry, - any participant that knows the SRN can compute the same SRI, - a Cell can address another Cell it has never previously discovered. ## Creation and lifetime Any Cell may create another Cell. An optional **lease** can make the created Cell's lifetime depend on its creator. This is a strict lifetime relationship, not a supervision or recovery guarantee. ## See also - [Nodes, Capabilities, and the Swarm](./02_nodes-capabilities-and-the-swarm.md) - where Cells run and how placement is decided - [Core Concepts](../06_concepts.md) - the full list of concepts this page belongs to # Cell Patterns Cell patterns are design conventions, not runtime types. They help teams separate canonical state, physical integration, decisions, and external connectivity. Patterns carry no guarantees. | Pattern | Role in the Application | Typical future recovery model | | --- | --- | --- | | **Asset** | Owns canonical state for a machine, zone, room, product, or other thing | Consistent | | **Adapter** | Translates hardware or a device protocol into Commands and Events | Dataflow; Consistent when it owns durable state | | **Agent** | Evaluates conditions, coordinates work, and issues Commands | Consistent or Dataflow, depending on state ownership | | **Bridge** | Connects the swarm to an external server or service over a protocol such as HTTP or MQTT | Convergent by default when recovery models arrive | Recovery models are introduced with Partition Tolerance. The table is design guidance, not current preview behaviour. Myrmic does not claim Convergent availability during a partition until it has demonstrated a declared merge rule. ## Asset Own the canonical state and behaviour of a persistent concept. Other Cells query it, command it, or subscribe to its Events. ## Adapter Translate local signals or protocols into the Cell model. Use capability tags to place the Adapter where the required hardware or native module exists. ## Agent Hold working context, react to Events, evaluate policy, and issue Commands. Keep canonical Asset state outside the Agent where possible. ## Bridge Connect Myrmic to an external system. Forward and translate rather than hiding domain decisions inside the integration boundary. Current HTTP and MQTT Bridges run natively in one designated platform location rather than as ordinary WebAssembly Cell instances. Their integration pattern and future recovery model are separate concerns. ## Composition patterns Common compositions include: - Command and Event segregation, - edge aggregation, - local decision loops, - digital twins, - sagas and long-running coordination. ## See also - [Applications, Cells, and Identity](./01_applications-cells-and-identity.md) - what a Cell is and how it's addressed - [Recovery Models](./06_recovery-models.md) - what happens to a Cell after a restart or Node loss # Handlers, State, and Transactions A **Handler** is a Cell's reaction to one Message. It is also the conceptual boundary for a state transition. ![The Cell processing model](../../images/cell-view.svg) ## One Message at a time Commands, Events, callbacks, and timer wake-ups form one ordered stream for a Cell. One Handler runs at a time. A slow Handler delays everything behind it, including timers, so long-running work should be handed to another Cell. ## The command-handler unit The model groups three operations: - consuming the inbound Message, - changing the Cell's State, - writing outbound Messages. This unit is local to one Node. A destination mailbox whose data lives on another Node remains outside that local transaction boundary until Durability adds support across Nodes. The exact current behaviour after a Handler fails is release-sensitive. It is stated only on the [Guarantees](../08_guarantees.md) page. ## Idempotency is part of the interface The same logical work can reach a Handler more than once. This can happen when a caller sends again, a redeployment overlaps, or a commit does not complete cleanly. Design every Handler so that running it twice is harmless. ## External effects sit outside the transaction HTTP calls, MQTT publishes, and actuator writes leave the Cell transaction. Without a sink that supports request identity, deduplication, or fencing, applications must accept at-least-once effects and design accordingly. ## Back-pressure The in-memory queue between mailbox delivery and the Cell is bounded. When a Cell is slower than its incoming work, delivery pauses and leaves work in persistent storage rather than silently dropping it. The current resource and throughput limits are preview constraints, not performance promises. ## Timers Timers join the same Handler stream. Their durability across a Cell restart is a guarantee question. In the preview, timer and Event positions are process-local. ## See also - [Where Data Lives](./05_where-data-lives.md) - durability and replication for Cell State - [Guarantees](../08_guarantees.md) - what the current release promises, and what it doesn't yet # Messages and Mailboxes Cells communicate through Messages. ## Commands and Events ### Command A **Command** is a directed request to one Cell, addressed by SRI. It expresses intent and may be rejected. ### Event An **Event** is a published fact. Every subscriber reads it independently. One subscriber does not consume it for another. Use a Command when one specific Cell must act. Use an Event when something happened and any interested Cell should know. ## Cells never block on another Cell There is no synchronous Cell-to-Cell call. A Cell dispatches a Command and continues. If it requests a result, that result arrives later as a **callback**, which is an ordinary Message in the caller's own mailbox. External clients can choose to wait. The CLI or gateway may wait for the callback and present a blocking request to the external caller, but the underlying Cell interaction remains asynchronous. ## Delivery tiers A delivery tier states whether the runtime keeps trying to deliver a Message: - **tracked:** pursued until it reaches the destination Cell's current mailbox, without a time bound, - **best-effort:** tried once and not tracked. The delivery tier is independent of whether an external client waits for a result. ## The mailbox pair An inbound Message is recorded before the Cell handles it. The current durability boundary is stated on the [Guarantees](../08_guarantees.md) page. A sender writes to a named outbound mailbox on its Node. The Data Layer synchronizes that mailbox with the named inbound mailbox on the destination side. The sender does not directly mutate the receiver's inbox. This distinction matters because atomic delivery across Nodes is a data-replication problem, not only a local transaction problem. ## External clients use the same application path CLI Commands, gateway requests, and Cell-to-Cell Commands all reach the same addressed Cell model. A Cell should not need different domain logic for each transport surface. The current contract for delivery, duplicates, timeouts, and mailbox durability is versioned on [What Myrmic guarantees today](../08_guarantees.md). ## See also - [Handlers, State, and Transactions](./04_handlers-state-and-transactions.md) - what runs when a Message is consumed - [Core Concepts](../06_concepts.md) - the full list of concepts this page belongs to # Nodes, Capabilities, and the Swarm A **Node** is a device or operating-system process running Myrmic. It executes Cells, exposes local Capabilities, and connects to the swarm. A **swarm** is the set of Nodes that have found each other and behave as one system. Cells address each other by a Stable Resource Identifier (SRI), without knowing which Node currently runs them. ## Two Node shapes ### OS-based Node A Linux-class Node can run plugins for execution, self-organization, and data services, along with gateways and the native Signal Layer. ### MCU-based Node A supported MCU-based Node uses WAMR to execute WebAssembly modules that were compiled ahead of time. It also runs typed platform clients, `zenoh-nano`, and native Signal Layer tasks. The Node shape determines the available Capabilities, not what a Cell means. ## Two Node roles ### Orchestrator Participates in coordination and authority: membership, leadership, and placement. ### Executor Runs Cells and contributes Capabilities without voting. Roles and shapes are distinct. In practice, constrained MCUs act as Executors. ## Swarm Admin A **Swarm Admin** is the person responsible for configuring and monitoring a swarm. This is a user role, not a Node role. ## Capabilities and placement A Node advertises what it offers: - architecture and build platform, - protocols, radios, and device interfaces, - native modules, - Signal Layer taps and outlets, - gateway or data roles. A Cell declares capability tags. Placement matches the two. Capabilities are the basis of placement and the honest limit of portability. The Cell model spans device classes, but Myrmic does not place a Cell where its required functions are unavailable. ## What Cells declare today The developer preview supports capability tags, build platforms, an optional SRI, and initialization arguments. It does **not** yet expose a per-Cell recovery or consistency model. Those declarations arrive with Partition Tolerance. ## See also - [Recovery Models](./06_recovery-models.md) - what happens to a Cell after a restart or Node loss - [The Swarm View](../07_architecture/01_the-swarm-view.md) - where code runs, in diagram form # Recovery Models > **Roadmap concept, introduced with Partition Tolerance** > The current developer preview does not expose a recovery or consistency model for each Cell. Today, Cells declare capability tags. Recovery models are the future declaration axis for authority and recovery behaviour. A recovery model answers how a Cell should behave when the swarm is partitioned or its serving Node disappears. ## Consistent **Consistent** declares that the Cell must not diverge. It may become unavailable when a majority of its voter set cannot be reached. Its additional configuration includes: - an odd replica band, - an action to take after failure. A Consistent Cell can range from one unreplicated instance to a replicated deployment. Replicated data arrives later with Durability. ## Convergent **Convergent** declares that segments may diverge and later reconcile under a defined merge rule. Availability and merge behaviour are not current guarantees. A defensible merge model belongs to the **Secure Swarm** roadmap stage and must be demonstrated before it is claimed. ## Dataflow **Dataflow** declares best-effort stream processing at a stated level. It uses neither replicated authority nor replicated State. ## Restart policy is separate A restart policy answers what happens after a process restart, reboot, or site-wide power loss. That is different from deciding whether authority and data are replicated. The two settings must remain separate. ## Orthogonal concerns A recovery model does not replace: - **capability tags**, which decide where a Cell may run, - **execution shape**, such as continuous stream processing, - **Cell patterns**, which describe the role a Cell plays in the Application. When recovery models arrive, Myrmic will refuse a replicated stream deployment rather than silently degrade it. ## Sovereign Cells A **Sovereign Cell** is a Cell that outlives the Node it runs on. A Consistent Cell becomes sovereign when it has both: - replicated authority from **Partition Tolerance**, - replicated committed data from **Durability**. > **Partition Tolerance decides who may serve. Durability preserves what the Cell knows.** ## See also - [Roadmap](../09_roadmap.md) - what future stages are intended to add - [Guarantees](../08_guarantees.md) - what the current release promises, and what it doesn't yet - [Cell Patterns](./07_cell-patterns.md) - recurring designs for combining Cells, Adapters, Agents, and Bridges # Where Data Lives Myrmic separates three data categories that are easy to confuse. | Data category | What it contains | Current placement policy | | --- | --- | --- | | **Platform metadata** | System and swarm records | Available on every Node | | **Cell classes** | Content-addressed WebAssembly binaries | Available on Linux Nodes | | **Cell data** | Cell state, mailboxes, and Application records | One copy by default; scope replication can be configured explicitly | The [Guarantees](../08_guarantees.md) page is authoritative for the current release. ## Cell data is not execution A Cell may execute on one Node while its State or Mailbox lives on another. This is intentional. Execution, authority, and data are separate concerns. Losing the execution Node and losing the Node that holds the data are therefore different failures. ## Authority replication is not data replication Partition Tolerance replicates authority. It preserves the decisions about who leads a Cell and where it may serve. Partition Tolerance does not replicate the Cell's State. The authority decision can survive even while the Cell's data still exists as one copy. Durability is the roadmap stage that replicates a Cell's State and Mailboxes across several Nodes, so that the Cell's data survives the loss of one of them. ## Default does not mean universal A **Swarm Admin** can configure replication for a data scope with [`myrmic replicate`](../10_reference/02_myrmic-cli/15_replicate.md). That is an operational choice, not a blanket promise made by the preview. Design against the versioned guarantee for the actual deployment. ## See also - [Failure Behaviour](../07_architecture/04_failure-behaviour.md) - what happens when a Node is lost - [Recovery Models](./06_recovery-models.md) - what happens to a Cell after a restart or Node loss - [Roadmap](../09_roadmap.md) - what future stages are intended to add - [`myrmic replicate`](../10_reference/02_myrmic-cli/15_replicate.md) - configure which Nodes replicate which data # Contributing ## Welcome Welcome to the Myrmic contribution guide. This page focuses on improving the documentation and keeping it accurate and usable. ## Why Contribute? Documentation evolves with the product. Contributing to docs is a great entry point for beginners and a way for experienced contributors to clarify complex topics for the community. By improving the docs, you help new users succeed faster and help existing users avoid confusion. Whether you fix a typo, fill a missing topic, or tighten an explanation, your contribution matters. ## GitHub Workflow If you're new to GitHub, read the [GitHub Open Source Guide](https://opensource.guide/how-to-contribute/) to learn how to fork a repository, create a branch, and submit a pull request. ## Where to Contribute Docs and code both live in the [official repository](https://github.com/peeriot/myrmic), with the docs under `doc/chapters/`. If you notice a gap, an unclear step, or a missing topic, you are welcome to open an issue or a pull request. The [contribution guide](https://github.com/peeriot/myrmic/blob/master/CONTRIBUTING.md) is a good place to start. It covers the development setup, the checks CI runs, and the pull request process. ## Review Process Once you submit your contribution, the Myrmic maintainers will review the changes, provide feedback, and merge the pull request when it is ready. If you have questions or need help, leave a comment on your PR. ## Style Guide This section summarizes the writing guidelines used across the Myrmic docs for contributors who are new to technical writing. - Clarity over completeness and one clear way instead of many options. - Write in direct, simple language, active voice, and present tense. - Address the reader as "you" and avoid hype or marketing language. - Use canonical terms consistently and avoid new synonyms. - Use headings and short paragraphs; prefer lists for steps. - Avoid nested lists; use separate headings instead. - Use `TBD` when something is unknown rather than guessing. - Any runnable steps require a technical review. ## Voice Use a consistent voice across the docs. - Write clear, concise sentences and avoid tangents. - Prefer simple words over complex ones. - Use active voice and present tense. - Be explicit when a subject is unclear; repeat it instead of using vague "this". - Use second person (you/your) and gender-neutral language. - Avoid hype or marketing language. ## Getting Help - Ask in [Discord](https://discord.gg/zExh79pWgj) or open a [GitHub Discussion](https://github.com/peeriot/myrmic/discussions). - If you are unsure where to start, ask for a good first issue. ## Licensing of contributions Before your first pull request can be merged, you - or your employer, if you contribute on its behalf - accept the Contributor License Agreement electronically through the CLA bot on GitHub. It keeps ownership with you and enables Myrmic's dual-licensing model. The [Licensing](15_licensing.md) chapter explains the model; [Contributing and the CLA](15_licensing/02_contributing-and-the-cla.md) explains the agreement in plain language. # Developing with AI The documentation is also published as plain text, at two fixed URLs an AI coding assistant can read. - **[llms.txt](https://book.myrmic.dev/llms.txt)** - an index of every page, with a link to each. Small, and a tool that follows links pulls only the pages it needs. - **[llms-full.txt](https://book.myrmic.dev/llms-full.txt)** - the entire documentation in one place. Large, so expect it to fill a good part of a context window. Start with `llms.txt`. Reach for `llms-full.txt` when the tool cannot fetch pages. # Glossary Entries are listed alphabetically. | Term | Definition | |---|---| | Adapter Cell | Bridges hardware or device protocols into Commands and Events. Adapter Cells are bound to Nodes with the required physical access. | | Agent Cell | Implements application-specific behavior on top of Assets and Adapters. Agent Cells observe, decide, and act, and are typically relocatable. | | Application | A named group of Cells deployed and torn down together, declared in an app spec file. | | Asset Cell | Represents a physical or abstract asset and owns its canonical state. Asset Cells are logical and typically relocatable. | | Bridge Cell | Connects the swarm to external systems such as HTTP or MQTT. Bridge Cells are typically deployment-bound to specific network endpoints. | | Capability | A function or resource a Node provides - hardware access, a network endpoint, a platform service. Cells are placed on Nodes that carry the Capabilities and tags they need. | | Cell | A message-driven, stateful Wasm module that exposes command and event handlers, owns its private persistent state, and is loaded dynamically onto an execution runtime in response to a load request. The smallest unit of compute, state, and identity in Myrmic. | | Cell Class | A blueprint associated with a Wasm binary used to instantiate multiple Cells. | | Cell Collective | A group of Asset Cells that behaves as a higher-level entity. There is no dedicated Collective type; it is modeled by parent Asset Cells and their Commands and Events. | | Cell Handler | A function in a Cell that runs in response to something: an initialization, a Command, an Event, or a timer. A Handler runs to completion and commits its work as one unit. | | Cell Instance | A running instance created from a Cell Class with its own SRI and state. | | Command | A directed message that asks a specific Cell to perform an operation or change state. Commands express intent and may be rejected. | | Command Response | A reply to a Command that carries a result, failure, or acknowledgement. | | Data Layer | The shared persistence layer that stores per-Cell state in private scopes and provides transactional durability. It also backs the Cell Mailbox. | | Event | A message that represents a fact that already happened and can be observed by multiple Cells. | | Fuel metering | A compute budget mechanism that limits how many Wasm instructions a module can execute before yielding. | | Host interface | The set of named import modules that the platform exposes to Wasm modules at the sandbox boundary. | | Mailbox | The per-Cell queue that holds inbound Commands and Events until the Cell consumes them. | | Message | The unit of communication between Cells. Message types include Commands, Events, and Command Responses. | | Node | A device or operating-system process running Myrmic. It executes Cells, manages their mailboxes, and provides access to Capabilities and persistence. | | Self-Organization Layer (SOL) | The decentralized control plane responsible for discovery, placement, routing, health, and failover across Nodes. | | SRI | Stable Resource Identifier. The logical identity used to address a Cell regardless of placement, derived deterministically from its SRN. | | SRN | Stable Resource Name. The readable, stable name given to a Cell, such as `application/worker`, from which its SRI is derived. | | State | The private, persistent data a Cell owns, stored in its own scope in the Data Layer and durable across a restart of the Cell's process. | | Swarm | The set of Myrmic Nodes that can reach each other on the network. Nodes join it by discovery, with no explicit join step; names are shared across it. | | zenoh-nano | A custom `no_std` Rust implementation of the Zenoh protocol for embedded devices. | --- sidebar_label: Guarantees --- # What Myrmic Guarantees Today If Cell, Node, or Mailbox is new to you, start with [Core Concepts](./06_concepts.md). Failures in distributed systems are easy to describe imprecisely. This page states what the developer preview promises, so you can build on it. It also states what the preview does **not** promise, so you do not rely on behaviour that is not there. > **Reproduce anything here that matters to you.** This page should be versioned with every release. Because the project is still in preview, ambiguous or release-sensitive behaviour is described conservatively. | Topic | What Myrmic guarantees today | Coming | | --- | --- | --- | | **Tracked delivery** | A tracked Message is pursued until it reaches the Mailbox on the Node where the destination Cell is currently running. Delivery is local to that Node and can be revoked: if the Cell is recreated elsewhere, the Message becomes undelivered again and is pursued anew. There is one copy of the Mailbox by default. Losing its Node also loses the Messages it holds. In 0.5.0, commands sent during a 45-second partition were delivered exactly once after it healed, including across a non-clique topology. | **Durability:** the Mailbox is held by a quorum and survives the loss of one Node. | | **Best-effort delivery** | Tried once. It may never arrive, and the sender is not notified. Addressing a Cell that does not exist produces an immediate error. | - | | **Duplicates** | Myrmic does not intentionally create another copy after a Message reaches the current Mailbox. A Handler can still see the same logical work twice if a caller sends again, a redeployment overlaps, or a commit does not complete cleanly. A Command whose Handler returns an error is redelivered, and the retry is not currently bounded, so a Handler that always fails is retried indefinitely. Make every Handler safe to run twice. | **Durability:** request identity and deduplication for supported client Commands. | | **What commits together** | While a Command Handler runs, one transaction on the Node covers Mailbox consumption, Cell State, and outbound Messages. If the destination Cell's Mailbox lives on another Node, it is outside that local unit. In the current preview, do not assume that every failed Handler has rolled back every part of its work. Write defensively until the release contract confirms the hardened behaviour. | **Durability:** atomic delivery across Nodes. The committed batch for a Consistent Cell is then held by a quorum. | | **External effects** | HTTP calls, MQTT publishes, and actuator writes happen outside the Cell transaction. If surrounding work fails, the effect may already have happened. Make effects idempotent or accept at-least-once behaviour. | **Durability:** effectively-once behaviour only for sinks that support deduplication or fencing. | | **Ordering** | Inside one Cell, there is one ordered stream and one Handler runs at a time. Across Cells, there is no global order at any stage. | - | | **State durability** | Cell State is durable across a process restart. By default, the State is held as one copy, so it is not durable if the Node holding it is lost. Platform metadata is available on every Node, and Cell binaries are available on Linux Nodes. A Swarm Admin can configure replication for a scope, but that is not the default guarantee. In 0.5.0, this durability was verified against `kill -9`, power loss, and a full disk: acknowledged writes survived and the database recovered on the next start. | **Durability:** acknowledged writes to a Consistent Cell are held by a quorum. | | **When a Node is lost** | Affected deployments are removed and reported. A Cell deployed with a restart policy of `always` or `on-error` is then started on another qualifying Node, about 70 seconds after the loss. It is a restart, not a resumption: the new instance begins from whatever State it can reach, and any State that lived only on the lost Node is gone unless it was replicated. A Cell without a restart policy is not restarted. | **Partition Tolerance:** a surviving majority elects a new leader and serving role. **Durability:** the Consistent Cell resumes elsewhere from replicated State. | | **One running copy** | Redeploying a class that has active instances is refused: delete the instance first. Undeploy returns when Myrmic has forgotten the Cell, not when the halt has been acknowledged. | **Partition Tolerance:** fencing enforces one active serving copy. Deploy and stop operations are acknowledged. | | **Waiting and retrying** | Cells do not block on other Cells. They dispatch a Command and receive a later callback. External clients may wait, but a timeout means the outcome is unknown. There is no request identity, so sending again creates a new Command. Timers and Event positions do not survive a Cell restart. | **Durability:** request identity, deduplication, and durable timers. | | **Isolation between Cells** | A Cell cannot read or overwrite another Cell's private data. Its scope is derived from its own identity. Messages between Nodes currently carry no cryptographic proof of the sender, so the preview assumes a trusted network. | **Partition Tolerance or Secure Swarm:** authenticated principals and an authenticated fabric. | | **Execution isolation** | Each Cell runs in a WebAssembly sandbox with private memory and only the functions the Node granted it. Memory isolation is strong. Time and throughput isolation are not hard guarantees in the preview. | - | | **Deployment** | Application deployment is all-or-nothing and rolls back on failure. Unsupported combinations are refused. Tearing down a Cell removes its instance record, so a later deployment creates a new Cell rather than resuming the old one. | **Partition Tolerance:** deploy and undeploy become idempotent and acknowledged. | ## Four rules for writing a Cell 1. **Make every Handler safe to run twice.** Idempotency is part of the interface. 2. **The absence of a callback does not mean the Command failed.** Never compensate on that assumption. 3. **Assume one copy of your State** unless your deployment explicitly configures otherwise. 4. **Order what you need yourself.** There is order inside a Cell and none between Cells. ## Read future claims by stage - **Partition Tolerance** changes the guarantees for authority and for which Cell instance may serve. It does not replicate Cell data. - **Durability** changes the durability of Cell State and Mailboxes. - **Secure Swarm** covers trust, reconfiguration, controlled self-healing, upgrades, and declared merge rules. ## Verification Myrmic's public guarantees are intended to be checked rather than believed. ### Deterministic protocol core The roadmap architecture uses a deterministic, sans-IO protocol core: ```text step(input, context) → effects ``` Time and randomness are injected. The same input and seed can reproduce the same protocol decisions. This supports replayable authority and failure scenarios, but it does not prove faults the harness does not inject. ### Match evidence to the claim Different properties need different evidence: - runnable tests for message, handler, transaction, and deployment behaviour, - seeded scenarios for leadership, fencing, and serving behaviour, - deliberate loss of the Node that holds the only data copy, - staged demonstrations for Partition Tolerance and Durability, - published load tests only when topology, configuration, raw results, and reproduction commands are available. ### Publish mechanisms before numbers The developer preview does not publish unverified throughput, latency, or recovery figures as facts. When measurements are published, they should include: - the exact release, - hardware and Node topology, - workload and state size, - failure injection method, - configuration and replication settings, - raw results and reproduction steps, - known limits. ### A green suite is not the whole contract Tests can verify only the behaviour they exercise. The versioned guarantee page remains the public contract, and each release should connect every row to an observable check. ### Visual honesty Architecture diagrams use: - solid elements for the developer preview, - amber dashed elements labelled with **Partition Tolerance** or **Durability** for future capability. A diagram must not make a roadmap element look like current behaviour. > **Do not just read the claims. Reproduce them.** ## See also - [Failure Behaviour](./07_architecture/04_failure-behaviour.md) - what happens when a Node is lost - [Roadmap](./09_roadmap.md) - what future stages are intended to add # Guides Guides cover individual Myrmic features and concepts. Each guide focuses on one topic - what it is, when to use it, and how to work with it in practice. - [Cells](./05_guides/01_cells.md) - [Commands](./05_guides/02_commands.md) - [Events](./05_guides/03_events.md) - [Message Encoding](./05_guides/04_message-encoding.md) - [Scheduling Handlers](./05_guides/05_scheduling-handlers.md) - [State and Storage](./05_guides/06_state-and-storage.md) - [Operating a Swarm](./05_guides/09_operating-a-swarm.md) - [Observability](./05_guides/10_observability.md) - [Signal Layer](./05_guides/11_signal-layer.md) - [BLE](./05_guides/12_ble.md) # Work with BLE peripherals In some use cases, a cell needs data from a device that communicates exclusively over Bluetooth Low Energy - a sensor tag, a beacon, or any device that advertises and exposes GATT services. The Myrmic SDK gives the cell model the tools to interact with these devices through the `ble` module (`myrmic_sdk::ble`). It provides: - **Discovery** - scanning for peripherals and filtering advertisements - **Connection** - connecting to a peripheral and managing its lifecycle - **Data exchange** - reading, writing, and subscribing to GATT characteristics - **Security** - pairing with peripherals that require a secured link This guide covers each of these in practice and shows how to use them in a cell, with code snippets throughout. > **Note:** This guide is about a cell interacting with a BLE peripheral that is not part of the swarm - not about two Myrmic Nodes communicating over BLE. ## Placement requirement A BLE radio only reaches devices within its own range - the device running the cell and the peripheral must be physically within range of each other. This also means the cell must run on the specific device that has a BLE radio. This requirement is expressed with capability tags: - **Runtime** - each runtime advertises its capabilities through tags set at startup time - for example `ble`, `gps`, or `camera` - describing what the device it runs on has to offer: ```bash myrmic runtimes start --tag ble ``` A runtime built with BLE support advertises the `ble` tag on its own, so for BLE this tag need not be set by hand - see [Prerequisite: a BLE-enabled runtime](#prerequisite-a-ble-enabled-runtime). - **Cell** - a cell declares what it needs to fulfil its function through tags at deploy time. The distributed swarm ensures the cell lands on a device that has the required capabilities to run it, and therefore the right hardware. For a single cell, pass the tag directly to the deploy command: ```bash myrmic deploy my-cell.wasm --tag ble ``` For a full application, declare it per instance in `app_specs.yml`: ```yaml instances: - class: my-cell tags: [ble] ``` Then deploy with: ```bash myrmic deploy app_specs.yml ``` For more details, explanations, and examples see: - [Cell execution and placement](./01_cells.md#cell-execution-and-placement) - how placement tags work in practice - [Cell and application configuration](../10_reference/01_configuration/02_cell-and-application-configuration.md) - the full `app_specs.yml` schema - [`myrmic runtimes start`](../10_reference/02_myrmic-cli/04_runtimes/01_start.md) - starting a runtime with capability tags - [`myrmic deploy`](../10_reference/02_myrmic-cli/05_deploy.md) - deploying cells and applications with placement tags ## Prerequisite: a BLE-enabled runtime A cell can only use BLE on a runtime built with BLE support. Such a runtime advertises the `ble` tag automatically, while a runtime built without it does not and cannot serve BLE cells. ### OS (Linux) The release packages of the `myrmic-cli` do not include BLE support. A BLE-enabled Linux runtime requires a `myrmic-cli` built from source with its `ble` feature - see [Install with BLE support](../01_quickstart/01_installation.md#with-ble-support). ### Embedded (ESP32) The `ble` feature is enabled automatically for `esp32c5` and `esp32c61` firmware, but is off by default for `esp32c6`. A BLE-enabled C6 firmware requires building with the `ble` feature - see [Build a firmware with BLE support](../01_quickstart/02_installation-embedded.md#with-ble-support). With a BLE-enabled runtime in place, the rest of this guide covers how a cell uses the `ble` module. ## Non-blocking by design Cell handlers (commands, events, scheduled handlers and initialization handler) run on a single thread - this means while a handler is running, the cell cannot process other incoming messages. But some BLE interactions - scanning, connecting, reading a characteristic - take time. Waiting for the result inside a cell handler would block the thread and the cell would be unable to handle any other incoming command or event until the interaction completes. For this reason, every operation the SDK provides is non-blocking. The cell starts the operation, registers a callback, and returns immediately. The runtime invokes that callback when the result arrives. A callback names the handler that fires when the result is ready. The handler: - must be annotated with `#[myrmic_sdk::cmd]` - callbacks fire through the same dispatch mechanism as commands - must take the result type for that BLE operation as a parameter ```rust use myrmic_sdk::{Callback, Metadata, Result}; use myrmic_sdk::ble::{scan, DiscoveredDevice, ScanHandle}; // start the scan and name the handler to invoke when a device is found let scan_handle: ScanHandle = scan(Callback::of::(), filter, mode)?; // the runtime invokes this handler when a matching device is discovered #[myrmic_sdk::cmd] fn on_device_found(_md: Metadata, device: DiscoveredDevice) -> Result<()> { /* ... */ } ``` ## Handles Some operations outlive the cell handler that started them - for example a scan that keeps listening for peripherals, a connection that stays up, or a subscription that keeps delivering notifications. To track and control them after that handler returns, the SDK functions that start these operations return a handle. ```rust use myrmic_sdk::{Callback, Metadata, Result}; use myrmic_sdk::ble::{connect, scan, Connection, ScanHandle, Subscription}; let scan_handle: ScanHandle = scan(on_device_found_callback, filter, mode)?; connect(address) .on_connected(on_connected_callback) .on_disconnected(on_disconnected_callback) .initiate()?; #[myrmic_sdk::cmd] fn on_connected(_md: Metadata, connection_handle: Connection) -> Result<()> { let subscription_handle: Subscription = connection_handle .subscribe(characteristic, on_notification_callback)? .map_err(|_| "not notifiable")?; } ``` Each handle gives you control over what was started: - `ScanHandle` - stop the scan - `Connection` - interact with the peripheral and close the connection when done - `Subscription` - stop notification delivery A handle must be stored and persisted in the runtime database - not in a local variable inside a cell handler, since when the handler returns everything it held in memory is gone. Dropping a handle does **not** clean up the resource it represents - the scan keeps running, the connection stays up, the subscription keeps delivering. Without the handle there is no way to stop, disconnect, or unsubscribe. > **Note:** Always free the resources held by handles when they are no longer needed - unsubscribe from notifications, close the connection, then stop scanning. Leaving them open keeps radio resources occupied. See [State and storage](./06_state-and-storage.md) for how to persist handles in the runtime database. ## Scan for a peripheral A scan runs continuously - once started, it listens for BLE advertisements and delivers each matching device to a specified cell handler as it is found. It keeps going until explicitly stopped. It can be narrowed by a filter and configured for the scan mode needed. It is the right starting point for any cell that needs to discover a peripheral before connecting, or that reads data directly from the advertisement without connecting at all. The following example starts a scan and registers a handler for the runtime to call whenever a peripheral is found: ```rust use myrmic_sdk::db::state::State; use myrmic_sdk::{Callback, Metadata, Result}; use myrmic_sdk::ble::{scan, DiscoveredDevice, ScanHandle, ScanMode}; const SCAN: State> = State::new_const("scan"); #[myrmic_sdk::cmd] fn enable(_md: Metadata) -> Result<()> { let scan_handle = scan(Callback::of::(), None, ScanMode::Passive)?; SCAN.save(&Some(scan_handle))?; Ok(()) } #[myrmic_sdk::cmd] fn on_device_found(_md: Metadata, device: DiscoveredDevice) -> Result<()> { // ... Ok(()) } ``` `on_device_found` fires once per advertisement received. The runtime passes it a `DiscoveredDevice` value carrying the discovered peripheral's address and its advertisement - local name, service UUIDs, manufacturer data, and service data. From there, the cell can use the address to initiate a connection, or inspect the payload to decode readings directly - without connecting at all. A cell runs one scan at a time - this means a new scan cannot be started until the current one is stopped. So scanning must be stopped as soon as a match is found or it is no longer needed. ```rust #[myrmic_sdk::cmd] fn on_device_found(_md: Metadata, device: DiscoveredDevice) -> Result<()> { let mut stored = SCAN.load()?.unwrap_or_default(); let Some(scan_handle) = stored.take() else { return Ok(()); }; SCAN.save(&stored)?; scan_handle.stop()?; // ... connect to the peripheral or inspect the advertisement Ok(()) } ``` > **Note:** Stopping the scan does not immediately flush queued advertisements - they continue to arrive until the stop takes effect, so the handler may still fire after stopping. For this reason, the scan handle must be cleared from state before stopping, so any stale call finds nothing to act on. ### Filtering The scan can be narrowed to report only devices that match specific criteria: - by manufacturer - which company made the peripheral. - by name - the name the peripheral advertises. - by service UUID - the Bluetooth service it offers, for example heart rate, temperature, or humidity. These filtering options can be combined to narrow the scan further - a device must satisfy every condition set to be reported. ```rust use myrmic_sdk::ble::{scan, DiscoveryFilter, uuid128, ScanMode}; #[myrmic_sdk::cmd] fn enable(_md: Metadata) -> Result<()> { let filter = DiscoveryFilter { company_id: Some(0x0499), // Ruuvi Innovations, assigned by Bluetooth SIG local_name: Some("RuuviTag Pro".try_into()?), // service_uuid accepts Uuid::Bit16(0x180D) for standard 16-bit Bluetooth services, // or a 128-bit UUID constructed with the uuid128! macro for proprietary ones service_uuid: Some(uuid128!("6E400001-B5A3-F393-E0A9-E50E24DCCA9E")), // Nordic NUS Service }; let scan_handle = scan(Callback::of::(), Some(filter), ScanMode::Passive)?; Ok(()) } ``` ### Scan mode A scan runs in one of two modes - passive or active - depending on whether scan responses need to be requested: - passive - only primary advertisements (`ADV_IND`) are received. Lower power; sufficient for most peripherals. - active - sends scan requests to receive scan responses (`SCAN_RSP`) from peripherals that advertise more data than fits in the primary advertisement. Use active mode only when the peripheral puts data you need in the scan response, at the cost of extra radio airtime. ```rust scan(callback, filter, ScanMode::Passive)?; // or scan(callback, filter, ScanMode::Active)?; ``` ## Connect to a peripheral Once a peripheral is found, a connection can be established with it, giving the cell access to its GATT characteristics for reading, writing, and subscribing to notifications. Here is how that looks in practice: ```rust use myrmic_sdk::ble::{connect, Connection, Disconnect}; #[myrmic_sdk::cmd] fn on_device_found(_md: Metadata, device: DiscoveredDevice) -> Result<()> { // stop the scan first ... connect(device.address) .on_connected(Callback::of::()) .on_disconnected(Callback::of::()) .initiate()?; Ok(()) } #[myrmic_sdk::cmd] fn on_connected(_md: Metadata, connection: Connection) -> Result<()> { // ... Ok(()) } #[myrmic_sdk::cmd] fn on_disconnected(_md: Metadata, disconnect: Disconnect) -> Result<()> { // ... Ok(()) } ``` `connect` takes the peripheral's address - obtained from the scan - and returns a connection builder instance. Two callbacks must be registered on it before trying to initiate the connection: - `on_connected` - fires when the link is up and GATT services are ready, delivering a `Connection` handle for reading, writing, subscribing to characteristics, and disconnecting when done. - `on_disconnected` - fires when the connection attempt fails or the connection link drops. ### Connection established When the link is up and GATT services are ready, `on_connected` receives a `Connection` handle. Through it the cell can read the peripheral's address, look up characteristics, and close the connection when done: ```rust use myrmic_sdk::ble::{Uuid, uuid128}; /// Nordic NUS Service const NUS_SERVICE: Uuid = uuid128!("6E400001-B5A3-F393-E0A9-E50E24DCCA9E"); /// Characteristic for TX /// /// This characteristic is used to receive data from the peripheral const TX_CHAR: Uuid = uuid128!("6E400003-B5A3-F393-E0A9-E50E24DCCA9E"); #[myrmic_sdk::cmd] fn on_connected(_md: Metadata, connection: Connection) -> Result<()> { // a characteristic is identified by two UUIDs: the service it belongs to and its own let characteristic = connection .characteristic(NUS_SERVICE, TX_CHAR) .ok_or("peripheral is missing the expected characteristic")?; // connection.disconnect(); // close the connection when the peripheral is no longer needed Ok(()) } ``` ### Connection failure `on_disconnected` fires whenever the connection ends or the connection attempt fails for some reason. Inspect the reason to know what happened and decide what to do next: ```rust use myrmic_sdk::types::ble::DisconnectReason; #[myrmic_sdk::cmd] fn on_disconnected(_md: Metadata, disconnect: Disconnect) -> Result<()> { match disconnect.reason() { DisconnectReason::ConnectionFailed => {} // the connection attempt failed DisconnectReason::Timeout => {} // the connection attempt timed out DisconnectReason::RemoteClosed => {} // the peripheral closed the connection DisconnectReason::LocalClosed => {} // the cell closed the connection DisconnectReason::Unknown => {} // the connection ended for an unspecified reason } Ok(()) } ``` ### Connecting to a known address When the peripheral's address is already known - from a previous session or hardcoded - a connection can be initiated directly without scanning first: ```rust use myrmic_sdk::ble::{connect, mac_addr_pub, Address}; const PERIPHERAL: Address = mac_addr_pub!("C0:98:E5:42:7A:11"); #[myrmic_sdk::cmd] fn connect_known_address(_md: Metadata) -> Result<()> { connect(PERIPHERAL) .on_connected(Callback::of::()) .on_disconnected(Callback::of::()) .initiate()?; Ok(()) } ``` - `mac_addr_pub!` - for public addresses, assigned by the manufacturer and globally unique. - `mac_addr_rand!` - for random addresses, generated by the device itself. > **Note:** Some adapters require a prior scan before a connection can be established - skipping it will result in `ConnectionFailed`. To be safe, scan first. ## Pair with a peripheral Some peripherals protect sensitive data behind an encrypted link. To access their characteristics, the link must first be secured through pairing. Pairing uses a shared passkey - fixed on the peripheral and registered in the cell. The passkey applies to connections that already exist, so it is registered once the peripheral is connected, not before. ```rust use myrmic_sdk::ble::{connect, set_pair_passkey}; #[myrmic_sdk::cmd] fn on_device_found(_md: Metadata, device: DiscoveredDevice) -> Result<()> { // stop the scan first ... connect(device.address) .on_connected(Callback::of::()) .on_disconnected(Callback::of::()) .initiate()?; Ok(()) } #[myrmic_sdk::cmd] fn on_connected(_md: Metadata, _connection: Connection) -> Result<()> { set_pair_passkey(123_456)?; // the passkey is set on the peripheral - find it in its data sheet Ok(()) } ``` ## Read and write characteristics Once connected, a characteristic can be read to get its current value, or written to send a new one. Both operations are non-blocking - the request is queued and the outcome delivered to a callback when it completes. Reading a characteristic: ```rust use myrmic_sdk::ble::ReadError; use myrmic_sdk::types::ble::ReadOutcome; #[myrmic_sdk::cmd] fn on_connected(_md: Metadata, connection: Connection) -> Result<()> { connection.read(characteristic, Callback::of::())?; Ok(()) } #[myrmic_sdk::cmd] fn on_reading(_md: Metadata, outcome: ReadOutcome) -> Result<()> { match outcome.value { Ok(bytes) => {} // the value as raw bytes Err(ReadError::NotReadable) => {} // the characteristic does not support reading Err(ReadError::BufTooSmall) => {} // internal buffer too small for the value Err(ReadError::RequiresSecurity) => {} // the characteristic requires a paired link } Ok(()) } ``` Writing a characteristic: ```rust use myrmic_sdk::ble::WriteError; use myrmic_sdk::types::ble::WriteOutcome; #[myrmic_sdk::cmd] fn on_connected(_md: Metadata, connection: Connection) -> Result<()> { connection.write(characteristic, &[0x01, 0x00, 0x00, 0x00], Callback::of::())?; Ok(()) } #[myrmic_sdk::cmd] fn on_written(_md: Metadata, outcome: WriteOutcome) -> Result<()> { match outcome.result { Ok(()) => {} // write confirmed Err(WriteError::NotWriteable) => {} // the characteristic does not support writing Err(WriteError::RequiresSecurity) => {} // the characteristic requires a paired link } Ok(()) } ``` Both read and write outcomes tell which characteristic they came from - a single handler can serve multiple characteristics: ```rust fn on_reading(_md: Metadata, outcome: ReadOutcome) -> Result<()> { if outcome.characteristic == TEMPERATURE_CHAR { // handle temperature } else if outcome.characteristic == HUMIDITY_CHAR { // handle humidity } Ok(()) } ``` A write waits for the peripheral to confirm receipt - that is why it takes a callback. Some characteristics do not acknowledge writes at all. For those, `write_no_response` can be used instead - no callback needed: ```rust connection.write_no_response(characteristic, &[0x01])?; ``` ## Subscribe to notifications Instead of polling a characteristic, a cell can subscribe to it and receive each new value as it arrives - the peripheral pushes updates whenever the value changes. To subscribe, pass the characteristic and a callback. Each notification is delivered to that callback: ```rust use myrmic_sdk::ble::{Notification, NotifyError, Subscription}; #[myrmic_sdk::cmd] fn on_connected(_md: Metadata, connection: Connection) -> Result<()> { let subscription = match connection .subscribe(characteristic, Callback::of::())? { Ok(sub) => sub, Err(NotifyError::NotNotifiable) => return Ok(()), // characteristic does not support notifications Err(NotifyError::RequiresSecurity) => return Ok(()), // characteristic requires a paired link Err(NotifyError::BufTooSmall) => return Ok(()), // internal buffer too small }; // persist the subscription handle to state Ok(()) } #[myrmic_sdk::cmd] fn on_notification(_md: Metadata, notification: Notification) -> Result<()> { let data = notification.data(); // the value as raw bytes let characteristic = notification.characteristic(); // which characteristic sent it Ok(()) } ``` Make sure to unsubscribe when notifications are no longer needed: ```rust subscription.unsubscribe()?; ``` For complete working examples, the Myrmic repository on GitHub includes several BLE adapter cells that put everything in this guide into practice - see [BLE adapter examples](https://github.com/peeriot/myrmic/tree/master/examples/ble). ## See also - [How to work with commands](./02_commands.md) - the `Callback` mechanism used throughout this module - [How to schedule handlers](./05_scheduling-handlers.md) - the same handle-must-be-persisted pattern - [How to work with state and storage](./06_state-and-storage.md) - persisting handles across invocations ## Related SDK reference - [BLE scanning and discovery](../10_reference/03_myrmic-sdk/08_bluetooth-low-energy/01_ble-scanning.md) - [BLE connections and service discovery](../10_reference/03_myrmic-sdk/08_bluetooth-low-energy/02_ble-connections.md) - [BLE characteristic reads and writes](../10_reference/03_myrmic-sdk/08_bluetooth-low-energy/03_ble-characteristic-io.md) - [BLE notifications and subscriptions](../10_reference/03_myrmic-sdk/08_bluetooth-low-energy/04_ble-notifications.md) - [BLE pairing](../10_reference/03_myrmic-sdk/08_bluetooth-low-energy/05_ble-pairing.md) # Cells A cell is the fundamental unit of computation in Myrmic - a self-contained Wasm module that runs inside an isolated sandbox. Because cells are Wasm modules, the same binary runs on a Linux host or on embedded hardware like the ESP32. A cell has a defined role: it handles commands, reacts to events, and stores data. Myrmic solutions are composed of cells. Each cell has two identifiers: - **SRN** (Stable Resource Name) - the human-readable name used in the CLI and config files, allowing a better user experience. - **SRI** - the UUID the swarm uses internally to route messages. Each cell instance is created from a **class** - a named blueprint that holds the compiled binary for each target the cell can run on. Many instances can be created from one class, each with its own SRN and its own state. To manage classes, see [`list`](../10_reference/02_myrmic-cli/06_cells/03_classes/01_list.md), [`add`](../10_reference/02_myrmic-cli/06_cells/03_classes/02_add.md), [`delete`](../10_reference/02_myrmic-cli/06_cells/03_classes/03_delete.md), and [`info`](../10_reference/02_myrmic-cli/06_cells/03_classes/04_info.md). The **Myrmic SDK** powers the cell model with the functionality to build scalable solutions - such as inter-cell messaging, data storage, hardware peripherals, scheduling, and integrations with external systems both inbound and outbound. And then there is the **Myrmic CLI**, bringing your cell-driven application to life by providing everything from scaffolding to deployment. This guide covers cells and their basic usage in practice. The SDK's broader capabilities are covered in dedicated guides. ## A cell in code In code, a cell is a Wasm module compiled from a Rust source file. The easiest way to create one is with [`myrmic new`](../10_reference/02_myrmic-cli/01_new.md) - it creates a crate with the cell source and its build configuration, ready to build and run. ```bash myrmic new my-cell ``` The result looks like: ``` my-cell/ Cargo.toml rust-toolchain.toml .gitignore src/ lib.rs ``` `Cargo.toml` wires up the Myrmic SDK dependency and controls the cell's runtime memory - heap size, stack size, and linear memory limits. See [Cell and Application Configuration](../10_reference/01_configuration/02_cell-and-application-configuration.md) for all available options. The cell definition lives inside `src/lib.rs` - it looks like this: ```rust #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Callback, JsonValue, Metadata}; const STATE: State = State::new_const("my-key"); #[myrmic_sdk::init] fn init(md: Metadata) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("starting (id={:?})", md.id).ok(); Ok(()) } #[myrmic_sdk::cmd] fn count(md: Metadata, callback: Option>) -> myrmic_sdk::Result { let value = STATE.load()?.unwrap_or_default(); // `myrmic send` carries no callback, and a nil sender that could not be // answered even if it did. if let Some(callback) = callback && !md.sender.is_nil() { let _ = myrmic_sdk::info!("Returning count {} to (sender={:?})", value, md.sender).ok(); callback.invoke(md.sender, &JsonValue::from(value))?; } else { let _ = myrmic_sdk::info!("Count is {} (no caller to answer)", value).ok(); } Ok(()) } #[myrmic_sdk::cmd] fn increment(md: Metadata) -> myrmic_sdk::Result { let count = STATE.upsert_with(|count| { *count = *count + 1; })?; let _ = myrmic_sdk::info!("Incremented count to {} (sender={:?})", count, md.sender).ok(); Ok(()) } #[myrmic_sdk::cmd] fn decrement(md: Metadata) -> myrmic_sdk::Result { let count = STATE.upsert_with(|count| { *count = *count - 1; })?; let _ = myrmic_sdk::info!("Decremented count to {} (sender={:?})", count, md.sender).ok(); Ok(()) } ``` The code above defines a cell that keeps a counter in state and exposes three commands to read and modify it. Simple on the surface - but there are a few things here worth more explaining. - **No standard library** - Cells run on both Linux hosts and bare-metal embedded hardware, so the Rust standard library is not available. The Myrmic SDK provides alternatives for the things you are most likely to need from the standard library. - **State** - `State` is a typed handle to a state value that persists. It lives on the runtime database - not in Wasm memory. By default it is private to the cell. See [State and Storage](./06_state-and-storage.md) for more information and how to use it. - **Initialization handler** - Runs before the cell handles anything else: on first deploy, and again on restart under the same SRI. Use it for any initialization logic your cell needs - setting up initial state, logging startup info, or running custom business logic before the cell starts handling requests. It can also accept initialization args that are passed at deploy time. Here is an example: ```rust use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct Config { start: i32, step: i32, min: i32, max: i32, } #[myrmic_sdk::init] fn init(_md: Metadata, config: Config) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("starting at {}", config.start).ok(); // do something with config Ok(()) } ``` To pass init args at deploy time, use `--init` or `--init-file` with [`myrmic deploy`](../10_reference/02_myrmic-cli/05_deploy.md), or `init` / `init_file` in the [Application Configuration](../10_reference/01_configuration/02_cell-and-application-configuration.md#application). If your cell has nothing to initialize, omit it entirely. - **Commands and Events** - the cell exposes command and event handlers - functions the runtime calls when work arrives or something happens in the swarm. Covered in detail in [Commands](./02_commands.md) and [Events](./03_events.md). - **Timers** - cells can schedule work to run at a fixed interval or after a delay. Covered in detail in [Scheduling Handlers](./05_scheduling-handlers.md). ## Application As a solution grows, cells and bridges (adapters that translate external protocols like MQTT or HTTP into the swarm) need to be managed together. An application is how Myrmic organizes them - it groups multiple cells and bridges into a single deployable unit defined by a YAML specification file. See [Cell and Application Configuration](../10_reference/01_configuration/02_cell-and-application-configuration.md#application) for the full reference. ## Structuring your project When a project grows beyond a single cell, you need to decide how to organize your cells. There are two approaches: 1. **Multiple cells in one crate** - cells share the same memory config and dependencies. Good for tightly coupled cells. An example for a project structure looks like: ``` my-cells/ Cargo.toml src/ lib.rs ← shared code and cell setup bin/ sensor.rs actuator.rs ``` The relevant entries in `Cargo.toml`: ```toml [[bin]] name = "sensor" path = "src/bin/sensor.rs" [[bin]] name = "actuator" path = "src/bin/actuator.rs" ``` An application configuration for this setup looks like: ```yaml classes: - id: sensor build: path: . target: sensor - id: actuator build: path: . target: actuator instances: - class: sensor srn: greenhouse/sensor-1 # omit srn and the instance is named after its class, here `sensor` - class: actuator srn: greenhouse/pump-1 ``` To build or deploy a single cell from the crate, pass `--target` to select which bin to use - see [`myrmic build`](../10_reference/02_myrmic-cli/03_build.md) and [`myrmic deploy`](../10_reference/02_myrmic-cli/05_deploy.md) for details. 2. **Workspace** - each cell has its own memory config and dependencies. Add a `common` crate for shared types. Good for independent cells. An example of project structure looks like: ``` my-app/ Cargo.toml ← workspace manifest common/ ← shared types Cargo.toml src/lib.rs sensor/ Cargo.toml src/lib.rs actuator/ Cargo.toml src/lib.rs ``` In workspace manifest file: ```toml [workspace] members = ["common", "sensor", "actuator"] ``` An application configuration for this setup looks like: ```yaml classes: - id: sensor build: path: ./sensor - id: actuator build: path: ./actuator instances: - class: sensor srn: greenhouse/sensor-1 # omit srn and the instance is named after its class, here `sensor` - class: actuator srn: greenhouse/pump-1 ``` ## Cell execution and placement A cell does not run on its own - it runs inside the Myrmic runtime. The Myrmic runtime is the process that runs on a device - Linux or embedded - connects it to the swarm, and manages every cell deployed to it: spinning up their Wasm sandboxes, routing messages to the right cells, and handling each cell's lifecycle from deployment to teardown. The Myrmic CLI provides the means to manage runtimes - see [runtimes start](../10_reference/02_myrmic-cli/04_runtimes/01_start.md), [list](../10_reference/02_myrmic-cli/04_runtimes/02_list.md), and [delete](../10_reference/02_myrmic-cli/04_runtimes/03_delete.md). Cells are event-driven. When a command arrives, an event fires, or a timer triggers, the runtime calls the matching handler in the cell. Between calls, the cell is idle. Each cell runs in full isolation - no access to the filesystem, network, or other cells except through what the SDK offers. The result is a heterogeneous swarm - Linux machines alongside embedded devices - each powered by a runtime, each runtime hosting one or more cells, all communicating as if connected directly: ![Myrmic swarm - cells on Linux and ESP32 nodes communicating via commands and events](../../images/03-01-swarm-cells.svg) By default, a deployed cell can land on any available runtime in the swarm. This works for most cells - but in a heterogeneous swarm, some cells need specific hardware or capabilities that only certain devices provide. This is solved with placement tags - information about what a runtime offers and what a cell requires: - a runtime advertises capability tags at startup - a cell declares the tags it requires at deploy time The swarm places the cell only on a matching runtime. Tags and execution behavior are configurable - see [myrmic runtimes start](../10_reference/02_myrmic-cli/04_runtimes/01_start.md), [myrmic deploy](../10_reference/02_myrmic-cli/05_deploy.md), [Cell and Application Configuration](../10_reference/01_configuration/02_cell-and-application-configuration.md#application), and [Runtime Configuration](../10_reference/01_configuration/01_runtime-configuration.md#execution) for all available options. For example, suppose only one machine in the swarm has a camera attached. Start its runtime with a tag that says so: ```bash myrmic runtimes start --tag camera ``` Then deploy the cell that takes pictures, requiring the same tag: ```bash myrmic deploy camera-cell.wasm --tag camera ``` The cell is placed on that machine and no other. If no runtime carries the tag, the cell is not placed at all, rather than landing somewhere it cannot work. A cell is only placed where **all** its required tags are present. Some tags are carried by default: every Linux runtime carries `linux`, and every runtime carries its own runtime id as `@` tag. ## Myrmic CLI You may have noticed throughout this guide that several CLI commands were introduced. The Myrmic CLI offers the necessary means to scaffold, build cells for Linux and embedded targets, deploy, and manage them at runtime. For the full list - with synopsis, options, and usage examples for each command - see the [Myrmic CLI Reference](../10_reference/02_myrmic-cli.md). ## See also - [Commands](./02_commands.md) - how to accept input and pass data between cells - [Events](./03_events.md) - how to publish and subscribe to events - [Schedule Handlers](./05_scheduling-handlers.md) - how to schedule work at a fixed interval or after a delay - [State and Storage](./06_state-and-storage.md) - working with state and storage - Bridges *(TBD)* - adapters that translate external protocols into the swarm - [Cell and Application Configuration](../10_reference/01_configuration/02_cell-and-application-configuration.md) - memory layout and application spec reference - [Myrmic CLI Reference](../10_reference/02_myrmic-cli.md) - full CLI command reference ## Related SDK reference - [Cell initialization](../10_reference/03_myrmic-sdk/01_cell-model/01_cell-initialization.md) - [Cell identity and metadata](../10_reference/03_myrmic-sdk/01_cell-model/02_identity-and-metadata.md) - [Cell classes and spawning](../10_reference/03_myrmic-sdk/04_cell-lifecycle/01_cell-classes-and-spawning.md) - [Cell termination](../10_reference/03_myrmic-sdk/04_cell-lifecycle/02_cell-termination.md) - [Cell monitoring](../10_reference/03_myrmic-sdk/04_cell-lifecycle/03_cell-monitoring.md) # Work with commands ## What is a command A command is a directed request sent to a specific cell, triggering an action. It has a name, a handler, and a payload. This guide puts commands in practice and shows how to work with them. ## Command Handler A command handler is a Rust function annotated with the `#[cmd]` macro provided by the Myrmic SDK. ```rust #[myrmic_sdk::cmd] fn greet(md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("hello from {:?}", md.id).ok(); Ok(()) } ``` `#[cmd]` exports the annotated function as a Wasm command. During deployment, the runtime discovers all exported commands and registers them for invocation. By default, the command name is the handler function name - it is the name callers use to invoke the command. To override the command name, pass the `name` attribute to the macro: ```rust #[myrmic_sdk::cmd(name = "hello")] fn greet(md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { // ... Ok(()) } ``` Every command handler takes `Metadata` as its first argument - it carries context about who called it and which cell is running: ```rust pub struct Metadata { pub id: Sri, // the SRI of this cell pub sender: Sri, // the SRI of the sender; itself for self-calls or timer/BLE triggers; nil when sent externally (e.g. CLI) } ``` ## Command payload A command may require an input payload to fulfil its logic - in that case, add a second argument to the handler function to receive it: ```rust #[myrmic_sdk::cmd] fn set_threshold(_md: Metadata, value: f32) -> myrmic_sdk::Result { // ... Ok(()) } ``` The payload type must implement `Decoder` and `Encoder` - traits the SDK uses to deserialize and serialize the payload. Both rely on [`serde::Serialize`](https://docs.rs/serde/latest/serde/trait.Serialize.html) and [`serde::Deserialize`](https://docs.rs/serde/latest/serde/trait.Deserialize.html), which must also be derived. To understand why and how, see [Message encoding](./04_message-encoding.md). Numeric primitives (`f32`, `u32`, `i32`, `bool` ...), and types provided by the SDK such as `myrmic_sdk::String`, `myrmic_sdk::Bytes`, and `myrmic_sdk::JsonValue` already implement it by default. A command is limited to one payload parameter - if you need multiple fields, wrap them in a struct and derive `myrmic_sdk::Message` to automatically implement `Decoder` and `Encoder`: ```rust use serde::Deserialize; #[derive(Deserialize, myrmic_sdk::Message)] struct WorkItem { id: myrmic_sdk::String, priority: u32, } #[myrmic_sdk::cmd] fn process(_md: myrmic_sdk::Metadata, item: WorkItem) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("processing {} (priority {})", item.id, item.priority).ok(); Ok(()) } ``` ## Invoke a command from the CLI Rather than writing a second cell just to test, the CLI provides [`myrmic send`](../10_reference/02_myrmic-cli/08_send.md) - a command (CLI) that targets a running cell directly from a terminal. It takes the cell SRI, a command name, and an optional payload, and dispatches the command to the target cell: ```bash # No payload myrmic send my-cell greet # JSON payload myrmic send my-cell process '{"id":"item-01","priority":2}' ``` The payload is sent as JSON by default. For a full reference see [`myrmic send`](../10_reference/02_myrmic-cli/08_send.md). ## Invoke a command from one cell to another Now we reach the interesting part - a cell sending commands to another cell. ```rust fn forward() -> myrmic_sdk::Result { let target = myrmic_sdk::Sri::of_path("worker").map_err(|_| "invalid sri")?; let payload = WorkItem { id: myrmic_sdk::String::from("item-01"), priority: 2, }; myrmic_sdk::send(target, "process", &payload)?; Ok(()) } ``` The Myrmic SDK provides the `send` function to invoke commands. It takes the target SRI, the command name, and the payload. `send` is callable from any handler within a cell - a command handler, an event handler, or an initialization handler. A cell can also invoke commands on itself. For commands that take no payload, the SDK provides `myrmic_sdk::Void` - a zero-sized placeholder that signals no data is being sent: ```rust myrmic_sdk::send(target, "greet", &myrmic_sdk::Void)?; ``` ## Dispatch from a command handler `send` is non-blocking - execution continues immediately after each call. All command sends (and event publishes) made during a command handler commit atomically together with any storage operations when the handler completes - nothing is visible to the outside until that point. ## Register a callback to receive a response from a command Commands are fire-and-forget - once dispatched, the execution continues immediately and there is no way to get a value back directly. If a command is expected to produce a result, the solution is to include a callback in the payload. The callee receives it, does its work, and sends the result back through it. On the caller side, the result lands on a dedicated command handler. ```rust use serde::{Deserialize, Serialize}; // Shared type - both sides must use the same definition #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct StatusReply { active: bool, label: myrmic_sdk::String, } ``` The caller sends the callback and handles the result in a dedicated handler: ```rust #[myrmic_sdk::cmd] fn request_status(_md: Metadata) -> myrmic_sdk::Result { let target = myrmic_sdk::Sri::of_path("worker").map_err(|_| "invalid sri")?; let callback = myrmic_sdk::Callback::of::(); // or: Callback::to("on_status")? myrmic_sdk::send(target, "get_status", &callback)?; Ok(()) } #[myrmic_sdk::cmd] fn on_status(_md: Metadata, reply: StatusReply) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("active={} label={}", reply.active, reply.label).ok(); Ok(()) } ``` The callee receives the callback and invokes it with the result: ```rust #[myrmic_sdk::cmd] fn get_status(md: myrmic_sdk::Metadata, callback: myrmic_sdk::Callback) -> myrmic_sdk::Result { let reply = StatusReply { active: true, label: myrmic_sdk::String::from("worker-01"), }; callback.invoke(md.sender, &reply)?; Ok(()) } ``` `Callback` is a type that holds a reference to a handler on the calling cell meant to handle the response. `T` is the reply type that handler accepts. `Callback` provides two ways to create an instance: - `Callback::to("on_status")` - takes the name of the handler to invoke on the caller. - `Callback::of::()` - uses the handler's marker type; the compiler verifies it accepts `T`. ## See also - [How to publish and handle events](./03_events.md) - [Scheduling Handlers](./05_scheduling-handlers.md) - how to schedule work at a fixed interval or after a delay - [Message encoding](./04_message-encoding.md) - [State and Storage](./06_state-and-storage.md) - working with state and storage - [`myrmic send` reference](../10_reference/02_myrmic-cli/08_send.md) ## Related SDK reference - [Commands](../10_reference/03_myrmic-sdk/02_messaging/01_commands.md) - [Callbacks](../10_reference/03_myrmic-sdk/02_messaging/02_callbacks.md) - [Message encoding](../10_reference/03_myrmic-sdk/02_messaging/04_message-encoding.md) # Work with events ## What is an event An event is a message broadcast from one cell to all interested cells, informing them that something happened. It has a name, a handler, and a payload. This guide puts events in practice and shows how to use them. ## Event Handler An event handler is a Rust function annotated with the `#[evt]` macro provided by the Myrmic SDK. ```rust #[myrmic_sdk::evt] fn heartbeat(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { // ... Ok(()) } ``` `#[evt]` exports the annotated function as a Wasm event handler. During deployment, the runtime discovers all exported event handlers and registers them automatically. By default, the event name is the handler function name - it is the name publishers use to broadcast the event. To override the event name, pass the `name` attribute to the macro: ```rust #[myrmic_sdk::evt(name = "heartbeat")] fn on_heartbeat(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { // ... Ok(()) } ``` Every event handler takes `Metadata` as its first argument - it carries context about who published the event and which cell is running: ```rust pub struct Metadata { pub id: Sri, // the SRI of this cell pub sender: Sri, // the SRI of the cell that published the event; nil when published externally (e.g. CLI) } ``` ## Event payload An event may carry a payload - in that case, add a second argument to the handler to receive it: ```rust #[myrmic_sdk::evt] fn temperature_changed(_md: myrmic_sdk::Metadata, value: f32) -> myrmic_sdk::Result { // ... Ok(()) } ``` The payload type must implement `Decoder` and `Encoder` - traits the SDK uses to deserialize and serialize the payload. Both rely on [`serde::Serialize`](https://docs.rs/serde/latest/serde/trait.Serialize.html) and [`serde::Deserialize`](https://docs.rs/serde/latest/serde/trait.Deserialize.html), which must also be derived. To understand why and how, see [Message encoding](./04_message-encoding.md). Numeric primitives (`f32`, `u32`, `i32`, `bool` ...), and types provided by the SDK such as `myrmic_sdk::String`, `myrmic_sdk::Bytes`, and `myrmic_sdk::JsonValue` already implement it by default. An event handler is limited to one payload argument - if you need multiple fields values, wrap them in a struct and derive `myrmic_sdk::Message` to automatically implement `Encoder` and `Decoder`: ```rust use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct TemperatureChanged { sensor_id: myrmic_sdk::String, value: f32, } #[myrmic_sdk::evt] fn temperature_changed(_md: myrmic_sdk::Metadata, event: TemperatureChanged) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("sensor {} reported {:.1}°C", event.sensor_id, event.value).ok(); Ok(()) } ``` ## Publish an event from the CLI Rather than writing a cell just to test, the CLI provides [`myrmic publish`](../10_reference/02_myrmic-cli/09_publish.md) - a tool that broadcasts an event directly from the terminal. It takes an event name and an optional payload, and broadcasts it to all cells with a matching handler: ```bash # No payload myrmic publish heartbeat # JSON payload myrmic publish temperature_changed '{"sensor_id":"sensor-01","value":22.5}' ``` The payload is sent as JSON by default. For a full reference see [`myrmic publish`](../10_reference/02_myrmic-cli/09_publish.md). ## Publish an event from a cell Now we see how a cell publishes an event from within its own handlers. ```rust #[myrmic_sdk::cmd] fn record(_md: myrmic_sdk::Metadata, value: f32) -> myrmic_sdk::Result { let event = TemperatureChanged { sensor_id: myrmic_sdk::String::from("sensor-01"), value, }; myrmic_sdk::publish("temperature_changed", &event)?; Ok(()) } ``` The Myrmic SDK provides the `publish` function to broadcast events. It takes the event name and the payload. `publish` is callable from any handler within a cell - a command handler, an event handler, or an init initialization handler. For events with no payload, the SDK provides `myrmic_sdk::Void` - a zero-sized placeholder that signals no data is being sent: ```rust #[myrmic_sdk::cmd] fn heartbeat(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { myrmic_sdk::publish("heartbeat", &myrmic_sdk::Void)?; Ok(()) } ``` ## Dispatch from an event handler `publish` is non-blocking - execution continues immediately after each call. All event publishes (and command sends) made inside an event handler commit atomically together with any storage operations when the handler completes - nothing is visible to the outside until that point. ## See also - [How to work with commands](./02_commands.md) - [Scheduling Handlers](./05_scheduling-handlers.md) - how to schedule work at a fixed interval or after a delay - [Message encoding](./04_message-encoding.md) - [State and Storage](./06_state-and-storage.md) - working with state and storage - [`myrmic publish` reference](../10_reference/02_myrmic-cli/09_publish.md) ## Related SDK reference - [Events](../10_reference/03_myrmic-sdk/02_messaging/03_events.md) - [Message encoding](../10_reference/03_myrmic-sdk/02_messaging/04_message-encoding.md) # Message Encoding ## Why encoding matters Commands and events are the messages cells use to communicate. Each may carry a payload, a value exchanged between cells. Cells run inside a Wasm sandbox, and for a payload to reach its destination it must cross that boundary. The first problem here is that data can only cross the Wasm sandbox as raw bytes. The second problem is how to translate those bytes - correctly and consistently on both receiver and sender sides. This requires an encoding mechanism that is both efficient and flexible. ## What the SDK provides The Myrmic SDK addresses this through three traits: - `Encoder` - converts a value to bytes - `Decoder` - converts bytes back to a value - `Codec` - defines how values are serialized to bytes Every payload type must implement `Encoder` and `Decoder`. The rest of this guide shows how encoding works depending on the payload type, and how to use each one from a handler, the CLI, and another cell. ## Primitives Primitive types implement `Encoder` and `Decoder` by default. - `u8`, `u16`, `u32`, `u64`, `u128`, `i8`, `i16`, `i32`, `i64`, `i128`, `f32`, `f64`, `bool`, `char` - `myrmic_sdk::String` Their encoded bytes are plain JSON values - `42`, `true`, `"hello"` - so [`myrmic send`](../10_reference/02_myrmic-cli/08_send.md) can pass them directly. A command handler and an event handler that expect a primitive payload: ```rust #[myrmic_sdk::cmd] fn set_threshold(_md: myrmic_sdk::Metadata, value: u32) -> myrmic_sdk::Result { Ok(()) } #[myrmic_sdk::evt] fn on_reading(_md: myrmic_sdk::Metadata, value: f32) -> myrmic_sdk::Result { Ok(()) } ``` Sending from the CLI: ```bash myrmic send my-cell set_threshold 42 myrmic publish on_reading 22.5 ``` Sending from another cell: ```rust myrmic_sdk::send(target, "set_threshold", &42u32)?; myrmic_sdk::publish("on_reading", &22.5f32)?; ``` ## No payload When a command or event carries no data, use `Void`, a type that implements `Encoder` and `Decoder` out of the box. On the handler side, omit the payload argument: ```rust #[myrmic_sdk::cmd] fn ping(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { Ok(()) } ``` To send or publish with no payload from other cells: ```rust myrmic_sdk::send(target, "ping", &myrmic_sdk::Void)?; myrmic_sdk::publish("heartbeat", &myrmic_sdk::Void)?; ``` From the CLI: ```bash myrmic send my-cell ping ``` ## Optional payload A command can be sent both by another cell, with a payload, and from the CLI, without one. Wrap the handler's payload type in `Option` and both callers work: ```rust #[myrmic_sdk::cmd] fn set_threshold(_md: myrmic_sdk::Metadata, value: Option) -> myrmic_sdk::Result { Ok(()) } ``` Sending from another cell: ```rust myrmic_sdk::send(target, "set_threshold", &42u32)?; ``` From the CLI, with no payload at all: ```bash myrmic send my-cell set_threshold ``` `Option` absorbs the empty payload, and nothing else. A non-empty payload is still decoded by the inner type, so a malformed one is rejected rather than quietly treated as absent. This matters most for a `Callback`, whose name has to pass command-name validation: declare it as `Option>` and a command sent without one still reaches the handler, which then has no caller to answer. ## Custom types In production, payloads are rarely a single value. Cells exchange structured data - sensor readings, device states, commands with multiple parameters. For these, the payload needs to be described with custom types. But as mentioned before, for a type to be a payload it must implement `Encoder` and `Decoder` traits. The SDK solves this with `Message`, a derive macro that generates automatically the implementation of both `Encoder` and `Decoder` for the annotated type. As mentioned before, `Codec` defines the encoding format. `Message` also gives control over which one to use. Two available encoding formats are: - `Json` - the default; encodes as human-readable JSON - what the CLI and bridges expect - `Postcard` - compact binary, suited for constrained devices and performance-sensitive cell-to-cell communication `Message` relies on [serde](https://docs.rs/serde) for the actual field serialization - custom types must also derive [`Serialize`](https://docs.rs/serde/latest/serde/trait.Serialize.html) and [`Deserialize`](https://docs.rs/serde/latest/serde/trait.Deserialize.html). Defining a `SensorReading` and choosing a codec: ```rust use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, myrmic_sdk::Message)] #[codec(myrmic_sdk::Json)] // or myrmic_sdk::Postcard struct SensorReading { sensor_id: myrmic_sdk::String, value: f32, } ``` A command handler and an event handler that expect a `SensorReading`: ```rust #[myrmic_sdk::cmd] fn process(_md: myrmic_sdk::Metadata, msg: SensorReading) -> myrmic_sdk::Result { Ok(()) } #[myrmic_sdk::evt] fn on_reading(_md: myrmic_sdk::Metadata, msg: SensorReading) -> myrmic_sdk::Result { Ok(()) } ``` Sending a `SensorReading` from the CLI: ```bash myrmic send my-cell process '{"sensor_id":"sensor-01","value":22.5}' ``` If the struct uses `Postcard` as `Codec`, pass a hex-encoded Postcard payload with `--raw` instead: ```bash myrmic send my-cell process --raw ``` Sending a `SensorReading` from another cell: ```rust myrmic_sdk::send(target, "process", &SensorReading { sensor_id: "sensor-01".into(), value: 22.5, })?; ``` ## Raw bytes In case the payload is pre-encoded or opaque binary, the SDK provides `Bytes`, which carries the payload as raw bytes with no format applied. A command handler that receives raw bytes: ```rust #[myrmic_sdk::cmd] fn upload(_md: myrmic_sdk::Metadata, data: myrmic_sdk::Bytes) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("received {} bytes", data.len()).ok(); Ok(()) } ``` From the CLI, pass a hex-encoded payload with `--raw`: ```bash myrmic send my-cell upload --raw deadbeef ``` Sending image bytes from another cell: ```rust let image: myrmic_sdk::Bytes = capture_frame(); myrmic_sdk::send(target, "upload", &image)?; ``` ## Dynamic JSON When a payload comes from an external source - such as an MQTT bridge forwarding messages from a broker - its shape is not controlled by the cell. For these cases, the SDK provides `JsonValue`, a type that can hold any valid JSON value: objects, arrays, strings, numbers. An event handler receiving a temperature reading from an MQTT bridge: ```rust #[myrmic_sdk::evt] fn on_temperature(_md: myrmic_sdk::Metadata, measurement: myrmic_sdk::JsonValue) -> myrmic_sdk::Result { let celsius = measurement["celsius"].as_f64().unwrap_or(0.0); Ok(()) } ``` To simulate a bridge event from the CLI: ```bash myrmic publish on_temperature '{"celsius":22.5}' ``` Publishing a `JsonValue` from another cell: ```rust let value: myrmic_sdk::JsonValue = /* ... */; myrmic_sdk::publish("on_temperature", &value)?; ``` When the payload shape is known, use a typed struct instead. `JsonValue` is a re-export of [`serde_json::Value`](https://docs.rs/serde_json/latest/serde_json/enum.Value.html). ## See also - [How to work with commands](./02_commands.md) - [How to publish and handle events](./03_events.md) - [CLI Reference](../10_reference/02_myrmic-cli.md) ## Related SDK reference - [Message encoding](../10_reference/03_myrmic-sdk/02_messaging/04_message-encoding.md) - [Commands](../10_reference/03_myrmic-sdk/02_messaging/01_commands.md) - [Events](../10_reference/03_myrmic-sdk/02_messaging/03_events.md) # Observability In complex use cases, Myrmic applications span hundreds of nodes - cells are distributed across runtimes, extensively communicating with each other, processing data, reading from hardware, and writing to storage. All of this happens concurrently across the swarm - but what if something goes wrong? What if you want to understand what is happening inside at any given moment? Observability is a critical part of running a swarm at this scale - it gives you the tools to answer exactly those questions. This guide covers what Myrmic offers out of the box to give you that visibility. For a hands-on walkthrough, see the [Observability tutorial](../04_tutorials/07_observability.md). ## Check what's running The starting point that makes sense before diving into any complex investigation is to check what is running - whether runtimes or cells. The Myrmic CLI provides dedicated commands for this: ### List local runtimes To inspect runtimes started on a machine, `myrmic runtimes list` shows each one and its current status. See [`myrmic runtimes list` reference](../10_reference/02_myrmic-cli/04_runtimes/02_list.md) for synopsis, options and examples. ### List swarm nodes To inspect all runtimes connected across the swarm network, `myrmic network status` lists each node with its identifier, role, and swarm topology. See [`myrmic network status` reference](../10_reference/02_myrmic-cli/07_network/01_status.md) for synopsis, options and examples. ### List running cells To inspect deployed cells or the status of a specific cell, `myrmic cells status` lists all deployed cells - each with its identity, placement, age and restart policy. See [`myrmic cells status` reference](../10_reference/02_myrmic-cli/06_cells/01_status.md) for synopsis, options and examples. ## Logs When something within your distributed Myrmic application goes wrong, the first thing that comes to mind is to check the logs. They reveal what is happening inside the runtime process - every action, large or small - and what your cells are doing at the same time. ### How cells emit logs To emit logs from within a cell, the Myrmic SDK provides five dedicated logging macros - one for each severity level: ```rust use myrmic_sdk::{trace, debug, info, warn, error}; #[myrmic_sdk::cmd] fn on_start(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { let _ = trace!("on_start: entering handler").ok(); let _ = debug!("on_start: handler began").ok(); let _ = info!("cell started").ok(); let _ = warn!("upstream cell not yet available").ok(); let _ = error!("failed to initialize").ok(); Ok(()) } ``` These macros use [`format!`](https://doc.rust-lang.org/std/macro.format.html) internally - use them the same way. ### View logs The CLI provides `myrmic telemetry logs` to inspect log entries from all connected runtimes and their cells. Log entries can be narrowed to a specific trace - traces are covered in the next section. See [`myrmic telemetry logs` reference](../10_reference/02_myrmic-cli/12_telemetry/01_logs.md) for synopsis, options and examples. ### Log verbosity Log verbosity controls how much detail the runtime process and your cells emit. When debugging, you may want more detail to understand what is happening internally. When things are too noisy, you can reduce verbosity for specific components while keeping others at a useful level. There are two ways to control verbosity: - **At startup** - configure the log filter by setting `telemetry.logs.env_filter` in the runtime configuration. See [runtime configuration reference](../10_reference/01_configuration/01_runtime-configuration.md) for details. - **At runtime** - the Myrmic CLI provides `myrmic telemetry set-filter` to apply a new filter across all connected runtimes without a restart. See [`myrmic telemetry set-filter` reference](../10_reference/02_myrmic-cli/12_telemetry/04_set-filter.md) for synopsis, options and examples. ## Traces Logs show what happened on a single runtime and its cells. But in Myrmic, a single operation can involve many cells across the swarm - for example, a command that arrives at one cell may trigger calls to others. Traces capture that journey: every cell involved records a span, and the context travels with each message, linking them into a chain. The Myrmic CLI provides `myrmic telemetry traces` to inspect trace spans - filtering by trace ID narrows results to a specific operation. The same ID can also be passed to `myrmic telemetry logs` to cross-reference related log lines. The output is in the [Trace Event Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview) - a widely supported JSON format readable by any compatible trace viewer, such as [Perfetto](https://ui.perfetto.dev/) or chrome://tracing. See [`myrmic telemetry traces` reference](../10_reference/02_myrmic-cli/12_telemetry/02_traces.md) for synopsis, options and examples. ## Metrics Metrics give you a snapshot of how the swarm is performing. They cover two things: how the runtime process is doing (CPU, memory, disk I/O) and how your cells are behaving (mailbox depth, commands processed, events processed). The Myrmic CLI provides `myrmic telemetry metrics` to inspect current metric values. See [`myrmic telemetry metrics` reference](../10_reference/02_myrmic-cli/12_telemetry/03_metrics.md) for synopsis, options and examples. ## Live debugging So far, all three signals - logs, traces, and metrics - are stored, past telemetry data. Good for history, but sometimes you need to see what is happening across the swarm right now. The Myrmic CLI provides `myrmic telemetry debug` to do exactly that: it reports activity from all connected runtimes and their cells - commands dispatched, events fired, and cell logs emitted - in real time as they occur. See [`myrmic telemetry debug` reference](../10_reference/02_myrmic-cli/12_telemetry/07_debug.md) for synopsis, options and examples. ## Telemetry retention Telemetry data is stored in the data layer - logs, traces, and metrics each in their own dedicated table. Nothing is written there until a retention period is set: with no retention, the `myrmic telemetry` query commands return nothing. Once a retention is set, records are kept for that long and then purged. A retention set with the CLI lives in the running process: after a runtime restart nothing is stored again until you set it once more. A retention in the runtime configuration file applies at every start. There are two ways to set a retention period: - **At startup** - set `telemetry.db_retention` in the runtime configuration. This applies to that specific runtime only. See [runtime configuration reference](../10_reference/01_configuration/01_runtime-configuration.md) for details. - **At runtime** - the Myrmic CLI provides `myrmic telemetry set-db-retention` to apply a retention period across all connected runtimes, and `myrmic telemetry no-db-retention` to clear it. See [`myrmic telemetry set-db-retention` reference](../10_reference/02_myrmic-cli/12_telemetry/05_set-db-retention.md) and [`myrmic telemetry no-db-retention` reference](../10_reference/02_myrmic-cli/12_telemetry/06_no-db-retention.md) for synopsis, options and examples. ## Route telemetry to an OpenTelemetry collector The CLI commands are useful for quick inspection and short debugging sessions. For anything more sustained - long-term storage, alerting, dashboards - you need an external system. Myrmic supports exporting all three signals to any OpenTelemetry-compatible collector, which can route them to tools like Grafana, Jaeger, or Prometheus. To enable it, configure `otel_endpoint` for each - logs, traces, and metrics - under `telemetry` in the runtime configuration. See [runtime configuration reference](../10_reference/01_configuration/01_runtime-configuration.md) for details. Once configured, each runtime pushes its own telemetry to the collector automatically as it is generated. Configure `otel_endpoint` on every runtime you want data from - runtimes without it set will not export. > **Note:** Exporting to an external OpenTelemetry collector requires Myrmic to be built with the `open-telemetry` feature. ## See also - [Observability tutorial](../04_tutorials/07_observability.md) - [Myrmic CLI reference](../10_reference/02_myrmic-cli.md) - [Runtime configuration reference](../10_reference/01_configuration/01_runtime-configuration.md) ## Related SDK reference - [Logging](../10_reference/03_myrmic-sdk/10_logging.md) - [Errors](../10_reference/03_myrmic-sdk/11_error-model.md) - [Cell monitoring](../10_reference/03_myrmic-sdk/04_cell-lifecycle/03_cell-monitoring.md) # Operating a swarm Once your cells are built and deployed, you are operating a swarm: one or more runtimes on a network, joining into a single system, running your cells and holding their data. This guide covers what that looks like in practice - how to tell a runtime is ready, how nodes find each other and where cells land, how the swarm behaves when a node pauses or a clock drifts, what it costs to run, and the rough edges to plan around. This guide is about operating Linux nodes. The figures here are lab measurements on small cloud instances (2 to 4 vCPU, Debian 12 and Ubuntu 24.04); treat them as what to expect on comparable hardware, not as guarantees, and measure your own workload. ## Knowing a runtime is ready `myrmic runtimes start` does not return: it runs the runtime in the foreground until you stop it. The runtime is ready to take deployments once it logs its readiness line, about two seconds after you start it: ```text INFO runtime "default" ready () ``` On the first start you may also see one or two `WARN` lines about missing prior state - these are normal and can be ignored. From another terminal, `myrmic runtimes list` confirms it independently: a runtime it reports as `running` is one you can deploy to. See the [`myrmic runtimes start`](../10_reference/02_myrmic-cli/04_runtimes/01_start.md) and [`myrmic runtimes list`](../10_reference/02_myrmic-cli/04_runtimes/02_list.md) references for synopsis, options and examples. ## Discovery, identity, and placement Runtimes find each other on their own. Every runtime that can reach the others on the network joins one swarm, with no explicit join step, so two machines on the same segment form a swarm whether or not you intended it. `myrmic network status` shows the nodes a runtime currently sees. See the [`myrmic network status` reference](../10_reference/02_myrmic-cli/07_network/01_status.md) for synopsis, options and examples. On a host where multicast is blocked, point the CLI at a Zenoh listener on a runtime instead. This skips multicast discovery for that invocation; repeat `--connect` to provide fallback endpoints: ```bash myrmic --connect tcp/192.0.2.10:7447 cells status ``` The runtime must be configured to listen on that reachable endpoint under its `zenoh` configuration. To keep a set of runtimes on one host apart from the others, for example for testing, give them their own multicast group under `zenoh.scouting.multicast.address` in their configuration, and point the CLI at it with `--multicast-group` (or `DEFAULT_MYRMIC_MULTICAST_GROUP`): ```bash myrmic --multicast-group 239.1.2.3:7446 cells status ``` A separate group only keeps discovery apart; it is not a security boundary. A runtime whose IP address changes rejoins by itself, with no restart, as long as it listens on an unspecified address - `tcp/0.0.0.0:7447` or `tcp/[::]:7447`, and the same under `tls/`. A listen endpoint that carries a host name or a concrete address is resolved once at startup and bound to the address that came back, so after the move it accepts nothing and only a restart clears it. Check which of the two your `zenoh` configuration declares before relying on this. A runtime that qualifies checks the host's addresses on a timer - every ten seconds, unless [`zenoh.scouting.interface_poll_interval`](../10_reference/01_configuration/01_runtime-configuration.md#zenoh-advanced) says otherwise - and once they have moved it re-publishes the addresses it can be reached at, pushes the change to the peers it is still connected to, and rebuilds its discovery sockets. The push and the socket rebuild are independent: a host with no multicast interface at all still re-publishes its addresses. Expect the swarm to settle within a minute of the move: the poll has to notice it, the links to the old address have to expire, and the peers have to find each other again. The runtime reports the outcome at `info`: ```text INFO Zenoh can be reached at: tcp/192.0.2.25:7447 ``` That line is only visible where the log level lets it through, and so is everything else about the move. With neither `telemetry.logs.env_filter` nor `RUST_LOG` set, a runtime logs errors only - nothing about an address change reaches that level, including what goes wrong on the way, which is logged at `warn`: the host offering no usable interface, an address set that came back empty, a discovery socket that could not be rebound. On nodes whose address can move, set the filter to at least `info`, and wherever you narrow it keep these two targets carved out: ```text info,zenoh::net::runtime::interface_monitor=debug,zenoh::net::runtime::orchestrator=info ``` If you silence the transport library with `zenoh=off`, put those two carve-outs after it - `zenoh=off` on its own drops the move entirely. The filter shipped in `swarm/configs/myrmic.jsonnet` and the one the CLI builds for `myrmic runtimes start` both already carry them. Several shapes do not get the full effect, and a node in one of them gives no sign of that: - A listen endpoint declared with a host name or a concrete address, as above, whatever the transport. - Mutual TLS with certificates issued for IP addresses. See [Addresses that change](../11_security.md#addresses-that-change). - A node with gossip scouting turned off (`zenoh.scouting.gossip.enabled: false`), on peers and routers alike. Such a node adopts its new addresses but announces them to nobody, so a peer it is still connected to is never told and has to rediscover it. Gossip is on by default and the shipped configurations leave it on. - Any node running a release that predates the host interface poll, including 0.6.1. A cell's SRN is swarm-wide. The same SRN names the same cell everywhere, so deploying a name that already exists addresses the existing cell rather than creating a second copy. Give distinct cells distinct names. When you deploy, the swarm places the cell on a node that can run it, which is not necessarily the machine you ran the CLI on. `myrmic cells status` shows each deployed cell and the runtime it runs on, so you can see where a deploy landed. See the [`myrmic cells status` reference](../10_reference/02_myrmic-cli/06_cells/01_status.md) for synopsis, options and examples. To constrain where a cell runs, tag the nodes that may host it and require those tags at deploy time with `--tag`. A cell that requires a tag is placed only on a node carrying it. See the [`myrmic deploy` reference](../10_reference/02_myrmic-cli/05_deploy.md) and the [`myrmic tags` reference](../10_reference/02_myrmic-cli/14_tags.md) for details. To keep separate groups of machines from merging into one swarm, put them on separate network segments. Any runtime on the same segment joins, and this preview has no authentication between nodes, so the segment is the trust boundary. See the [Security](../11_security.md) page for the trust assumptions. ## Timing and liveness A node that goes silent is declared lost after roughly 60 to 70 seconds. A shorter pause, under about 45 seconds, is not treated as a loss, so a node that is briefly busy or paused stays in the swarm. Two views update at different speeds. `network status` reflects transport liveness within seconds, while the cell view from `cells status` changes only after the swarm runs its periodic hygiene, so it lags behind. A node can already be gone from `network status` while it still appears under `cells status` for a short while. Messages to an unreachable node are not dropped. Commands wait in the node's mailbox and are delivered once it reconnects. In our tests a healed partition delivered each command exactly once, but deduplication is not yet guaranteed - see [Guarantees](../08_guarantees.md) and write handlers that are safe to run twice. If the node that holds one of the swarm's internal tables (the shared records that track what is deployed and where) disappears, operations that need it - `cells`, `send`, `network status` - can fail for up to a minute while the swarm moves that table to another node. This clears by itself; retrying after a few seconds succeeds. ## Durability and recovery Cell state is durable across a process restart. In 0.4.0, state durability was verified against `kill -9`, power loss, and a full disk: acknowledged writes survived and the database recovered on the next start. By default a cell's state is held as a single copy, so it is durable across a restart of its node but not across the loss of that node. Configure [replication](../10_reference/02_myrmic-cli/15_replicate.md) for a scope if you need state to outlive a node. See the [Guarantees](../08_guarantees.md) page for the exact durability contract. After a hard stop, `myrmic runtimes list` may show a runtime as `stale`: its PID file outlived the process. Starting a runtime of the same name reclaims the entry. Note also that after a hard reset, runtime log lines can lag behind the state that was actually persisted, so trust the recovered database over the tail of the log. ## Clock synchronization Runtimes stamp messages with a hybrid logical clock. A timestamp more than 500 ms ahead of the receiver's own is not dropped: the receiver swaps in its own and forwards the message. Run NTP or PTP on every node and target a second or two rather than milliseconds - real trouble starts around a minute of disagreement, where a node behind the swarm can stop receiving new cells. A runtime's clock only moves forward, so a forward jump lasts until the process restarts and re-seeds it, and correcting a large one can cost the node its running cells while the swarm briefly treats it as having gone away. After correcting a clock that had jumped forward, restart the runtime on that node; rows already written keep their future dates. A node that can run cells also watches its peers' liveness leases and warns when its own clock looks out of step by more than a few seconds in either direction. Only such nodes report or are observed - routers, db-only, mqtt-only and gateway-only nodes do neither. ## Disk and storage A runtime keeps its database, identity and logs under its data directory. See [what Myrmic writes to your machine](../01_quickstart/01_installation.md#what-myrmic-writes-to-your-machine) for the exact locations. Watch free space. If the disk fills, the database enters a state it does not recover from on its own: the runtime keeps reporting success while writes no longer persist, and it must be restarted after space is freed. Monitor free space on nodes that hold data rather than relying on write calls to report the problem. Retained telemetry is the main driver of database growth over time, and retention is off by default. See [Telemetry retention](./10_observability.md#telemetry-retention) for how to set a retention period and what it costs. ## Running in containers A runtime in a container is invisible to the LAN unless it shares the host's network, because swarm discovery relies on reaching peers on the local segment. Run the container with host networking: ```bash docker run --network host ``` Without it, the runtime starts and looks healthy but never joins the swarm on the host's network. ## Running as a service To keep a runtime up across reboots, run it under systemd. Because `myrmic runtimes start` stays in the foreground, a plain service type works: ```ini [Unit] Description=Myrmic runtime After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/bin/myrmic runtimes start Restart=on-failure User=myrmic [Install] WantedBy=multi-user.target ``` Two things differ from an interactive start: - **PID file and data locations.** A service usually runs without `$XDG_RUNTIME_DIR`, so its PID file goes to `$TMPDIR/myrmic-/` instead, and its data directory is that of the service user. See [what Myrmic writes to your machine](../01_quickstart/01_installation.md#what-myrmic-writes-to-your-machine). - **CLI visibility.** `myrmic runtimes list` and `myrmic runtimes stop` only see runtimes started by the same user. A runtime running as another service user is managed with `systemctl`, not with the CLI. For cells to come back when the service restarts, deploy them with a restart policy (`--policy on-error` or `--policy always`) rather than the default `never`. See the [`myrmic deploy` reference](../10_reference/02_myrmic-cli/05_deploy.md) for the policy options. ## Resource footprint A runtime doing nothing but holding one deployed cell is small. Measured on a 4 vCPU instance: | Metric | Idle runtime, one cell | |---|---| | Resident memory (RSS) | ~49 MB | | CPU | ~0.7 % | | Data directory on disk | ~164 KB | Memory grows once the runtime is doing real work, and telemetry retention is the main driver: retained logs and traces are kept for querying rather than dropped. In one three-hour soak with retention enabled, resident memory reached about 84 MB. That is a single sample taken at the end of the run, so read it as an indication that retention pushes memory into the tens of megabytes over hours, not as a precise growth curve. If a runtime's memory matters to you, keep telemetry retention modest and measure it under your own workload. ## Current limitations Three operational states in this preview need a manual restart to clear: - A full disk requires a runtime restart after space is freed (see [Disk and storage](#disk-and-storage)). - A forward clock jump requires a runtime restart after the clock is corrected (see [Clock synchronization](#clock-synchronization)). - An IP address change requires a restart on a node that listens on a named or concrete endpoint rather than an unspecified one, and on a node running mutual TLS with certificates issued for IP addresses, which also needs a re-issued certificate (see [Addresses that change](../11_security.md#addresses-that-change)). A node that listens on `0.0.0.0` or `[::]` rejoins without one; with gossip scouting off it rejoins but tells nobody, so its peers have to rediscover it. See [Discovery, identity, and placement](#discovery-identity-and-placement) for the full list. ## See also - [Observability](./10_observability.md) - [Guarantees](../08_guarantees.md) - [Security](../11_security.md) - [Myrmic CLI reference](../10_reference/02_myrmic-cli.md) - [Runtime configuration reference](../10_reference/01_configuration/01_runtime-configuration.md) # Scheduling Handlers A cell is event-driven - it waits for a command or event to arrive, handles it, then goes idle. Cell handlers run on a single thread, so while a handler is running, the cell cannot process other incoming messages. An infinite loop inside a handler - polling a sensor, for example - would block the cell entirely. For this reason, Myrmic provides the possibility to schedule handlers to run code at a fixed interval or after a delay. The Myrmic SDK provides the means a cell needs to schedule its own handlers and run logic on a schedule. All work the same way: - create a timer - point it at the handler that should fire - store the handle you get back - it is the only way to cancel later - the runtime calls the handler when the time comes They differ only in when and how often the handler fires. This guide covers each scheduling option and shows how to use it. ## Run on a fixed period The first scheduling option fires a handler at a fixed period and keeps going until cancelled or the cell is torn down. It is the right choice for any work that needs to happen on a regular basis - polling a sensor, sending a heartbeat, refreshing a value. The following example starts a timer that fires every 5 seconds: ```rust use core::time::Duration; use myrmic_sdk::db::state::State; const TIMER: State = State::new_const("timer"); #[myrmic_sdk::cmd] fn start_polling(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { let handle = myrmic_sdk::interval( myrmic_sdk::Callback::of::(), // or: Callback::::to("on_tick")? Duration::from_secs(5), ).build()?; TIMER.save(&handle)?; Ok(()) } #[myrmic_sdk::cmd] fn on_tick(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("tick").ok(); Ok(()) } ``` The SDK provides `interval`, it takes: - a callback - names the handler that fires on each tick - a period - sets how often it fires It returns a builder. Call `.build()` to create the timer and get back a handle. The handle: - must be stored so it survives across invocations - dropping it without storing does not stop the timer - it is the only way to cancel later. The handler named in the callback must: - be annotated with `#[myrmic_sdk::cmd]` - scheduled handlers fire through the same dispatch mechanism as commands - take only `Metadata` - should not carry any payload In case the handler needs to run a fixed number of times rather than indefinitely, call `.count(n)` on the builder before `.build()`: ```rust myrmic_sdk::interval(callback, Duration::from_millis(500)) .count(3) .build()?; ``` After the last tick, the timer stops and the stored handle is no longer valid. In case the handler should not start immediately, `interval_at` adds an initial delay before the first tick: ```rust myrmic_sdk::interval_at( callback, Duration::from_secs(10), // initial delay before the first tick Duration::from_secs(5), // period after that ).build()?; ``` ## Run once after a delay The other option fires a handler once after a fixed duration, then stops. It is the right choice for work that should happen after a wait - sending an alert if no response arrives, triggering a one-time action after a delay. The following example arms a watchdog that fires after 30 seconds: ```rust use core::time::Duration; use myrmic_sdk::db::state::State; const TIMEOUT: State = State::new_const("timeout"); #[myrmic_sdk::cmd] fn arm_watchdog(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { let handle = myrmic_sdk::delay( myrmic_sdk::Callback::of::(), // or: Callback::::to("on_timeout")? Duration::from_secs(30), ).build()?; TIMEOUT.save(&handle)?; Ok(()) } #[myrmic_sdk::cmd] fn on_timeout(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { let _ = myrmic_sdk::warn!("watchdog expired").ok(); Ok(()) } ``` The SDK provides `delay`, it takes: - a callback - names the handler that fires - a duration - how long to wait before firing It returns a builder. Call `.build()` to create the timer and get back a handle. After the handler fires, the handle in state is no longer valid - the timer has already run and there is nothing left to cancel. ## Timers and restarts Timers live with the cell instance. A cell that restarts, is redeployed, or moves to another node comes back with no timers - re-arm them from your initialization handler if the schedule has to survive. ## Cancelling a timer As seen in the previous examples, the handle is always stored in state. Storing it serves one purpose - being able to stop whatever was scheduled when the need arises, since dropping it does not stop it - the scheduled handlers keep running with no way to cancel. The handle is of type `TimerHandle` - it exposes `.cancel()`, the only way to stop whatever was scheduled. The following example stops the polling interval: ```rust #[myrmic_sdk::cmd] fn stop_polling(_md: myrmic_sdk::Metadata) -> myrmic_sdk::Result { if let Some(handle) = TIMER.load()? { handle.cancel()?; } Ok(()) } ``` ## Event and command dispatch from a scheduled handler Dispatching commands and events from a scheduled handler is non-blocking - execution continues immediately after each call. All commands and events dispatched from a scheduled handler commit atomically together with any storage operations when the handler completes - nothing is visible to the outside until that point. ## See also - [How to work with commands](./02_commands.md) - [How to publish and handle events](./03_events.md) - [State and Storage](./06_state-and-storage.md) - working with state and storage - [`myrmic send` reference](../10_reference/02_myrmic-cli/08_send.md) ## Related SDK reference - [Delayed handler invocations](../10_reference/03_myrmic-sdk/03_scheduling-and-time/01_delayed-handler-invocations.md) - [Periodic handler invocations](../10_reference/03_myrmic-sdk/03_scheduling-and-time/02_periodic-handler-invocations.md) - [Clock, uptime, and pausing](../10_reference/03_myrmic-sdk/03_scheduling-and-time/03_clock-and-wait.md) # Work with the Signal Layer A cell might need to interact with the physical world. It may need to read the temperature of a room, or switch a light on and off. A cell cannot do this on its own. It runs as a Wasm module inside a sandbox, and that sandbox has no direct access to hardware. The cell cannot directly reach the temperature sensor, and it cannot drive the relay that switches the light. The Signal Layer closes that gap. It knows how the hardware is wired, it does the reading and writing, and it gives the cell an interface to work with. The Myrmic SDK provides the functions a cell uses to reach it. Cells also come and go. They are deployed, replaced and removed while the node they run on stays up throughout, and the hardware work cannot stop each time that happens. The Signal Layer starts when the node starts, as part of the firmware on a microcontroller and as its own process on Linux, before any cell exists, and it keeps reading its sensors and running its loops whether a cell is present or not. That is the second reason the hardware description lives outside the cell: it has to outlive the thing that consumes it. ![Two description files are generated into Signal Layer tasks, which fill the taps and outlets a cell reads and writes through the Myrmic SDK](../../images/signal-layer-overview.svg) For a single pin there is also a direct GPIO interface, provided by the Myrmic SDK. The Signal Layer is for everything beyond that: a device on a bus, a value that needs processing before a cell sees it, or hardware you want to describe once and reuse. ## What a cell sees A cell sees two things: taps and outlets. A **tap** is a named value the cell can read. You choose the names in your pipeline, so a pipeline built around a room sensor might offer `temperature` and `humidity`. A tap is filled in by the Signal Layer, not by the cell. An **outlet** is a named value the cell can write, named the same way. Writing to an outlet is how a cell switches a light on or sets the speed of a fan. There are two kinds of taps you can declare. A **retained** tap always holds the most recent value the pipeline produced, and reading it gives you that value. An **event** tap is a queue of values the pipeline produced: reading it returns and consumes the oldest one, so each event is delivered once. A third kind, batch, is reserved for planned work and cannot be used yet. A cell does not need to know in advance what taps and outlets a node offers. The SDK lets a cell list what is available and decide from there. ## When things happen The Signal Layer reads sensors and writes outlet values to actuators on its own schedule, in loops. The rates of those loops are defined in the pipeline. This means the cell is an observer. It does not decide when a sensor is read. When it writes to an outlet, it does not decide when that value reaches the actuator either. **This is not a real-time system.** If a cell reads a tap twice in quick succession it may get the same value twice, because the loop that fills that tap has not run in between. Every retained tap value carries a timestamp, so a cell can tell a fresh value from one it has already seen. The timestamp counts milliseconds since the node's Signal Layer started, so it is useful for comparing two readings against each other. It is not a wall clock time, and an event tap carries no timestamp at all. ## The pipeline If you think of the parts as building blocks, the pipeline is the building instructions. The pipeline names the parts of the system, says how they are connected, and gives each one its parameters. A sensor produces a value. That value can go to a tap for a cell to read, or into a processing step, or on to an outlet. Two words will keep coming up. A **driver** is the piece of the Signal Layer that knows one kind of device: how to initialise a particular sensor and read it, or how to make a particular actuator act. And the **generator** is the build tool that reads your configuration files and produces the Signal Layer that runs them: tasks inside the firmware on a microcontroller, a standalone process on Linux. Nothing you write in the files is interpreted at run time; the generator turns it into code first. Steps can be chained, so the output of one step becomes the input of the next. Because the output of a step can drive an outlet directly, a pipeline can close the loop by itself. A pipeline that reads a temperature, decides a fan speed and writes it to the fan needs no cell to do the control work. It keeps working even with no cell running at all, and a cell that is running becomes purely an observer. ## What a step is A step is a small piece of processing with one input and one output. A moving average is a step, and so is tracking the smallest or largest value seen. Steps run as native code inside the pipeline's own loop, close to the sensor that feeds them. You can also do some arithmetic inside your cell instead. Prefer a step when the value must keep flowing without a cell, or when the result is needed as fast as the sensor produces it. ## Where each setting belongs There are two files, and knowing which one a setting belongs in is most of the work. The **board file** describes the physical setup: which pin is wired to which sensor pin, the address of a device on a bus. This is fixed by the hardware. A finished product does not rewire itself, so the board file describes the world the pipeline runs in. The **pipeline file** holds everything that can change without touching the wiring, such as how often a sensor is read. The rule is: - If the hardware decides it, it belongs in the board file. - If you could change it without changing the wiring or the circuit board, it belongs in the pipeline file. Each driver, the per-device piece introduced above, declares which settings it has, which of the two files each one belongs in, and a default. A setting you do not write down keeps its default. Settings in the pipeline are given per device, so two sensors on the same board can be read at different rates. ## What you will do Scaffold a project first with `myrmic signal-layer new` (Linux) or `myrmic signal-layer new --firmware=` (ESP32): it writes the board and pipeline files described below and generates the pipeline from them at build time, with no separate generate step. The [First Steps with the Signal Layer](../04_tutorials/04_first-steps-signal-layer.md) tutorial walks the whole path end to end. Then: 1. [Describe your hardware](./11_signal-layer/01_describe-your-hardware.md) in the board file. 2. [Design your pipeline](./11_signal-layer/02_design-your-pipeline.md): the parts, their connections and their parameters. 3. [Read values](./11_signal-layer/03_read-values.md) and [know when hardware fails](./11_signal-layer/04_know-when-hardware-fails.md). 4. [Drive hardware](./11_signal-layer/05_drive-hardware.md) from your cell. 5. [Discover what a node offers](./11_signal-layer/06_discover-what-a-node-offers.md) when you cannot know in advance. 6. [Write your own driver](./11_signal-layer/07_write-your-own-driver.md) for a sensor or actuator that is not supported yet. 7. [Write your own step](./11_signal-layer/08_write-your-own-step.md) to transform values in flight. The pages that follow take these in order. ## Embedded and Linux The pipeline file is portable. The same sources, steps, taps and outlets describe the system on both platforms, and a cell written against a tap does not change when the hardware underneath does. The board file is not portable, and it is not meant to be. It describes one specific board. It names the chip, and it says how each device is reached: on embedded that means the pins a bus uses, and on Linux it means the kernel device path instead. What does carry over is the list of devices, because a sensor keeps the same driver and the same address wherever you plug it in. Both platforms support sensors over I2C and SPI, actuators, and processing steps. The [reference](../10_reference/04_signal-layer/05_running-on-linux.md) states what each platform supports and how the board file differs on Linux. The platforms also run the Signal Layer differently. On embedded it is part of the firmware, so it is there whenever the cell is. On Linux it is a separate process that has to be running before a cell can use it. That difference has one symptom worth knowing. On Linux, if every tap a cell asks for comes back as not present, check that the pipeline process is running before you check the names in your pipeline file. A cell cannot tell the difference between a tap that does not exist and a pipeline that is not there. ## See also - [Signal Layer reference](../10_reference/04_signal-layer.md) - the file formats, drivers and steps ## Related SDK reference - [Signal taps](../10_reference/03_myrmic-sdk/07_signal-io/01_signal-taps.md) - [Signal outlets](../10_reference/03_myrmic-sdk/07_signal-io/02_signal-outlets.md) # Describe your hardware The board file is where you write down what your hardware actually is: which chip, which pins carry which bus, what is wired to it, and where each device sits. This page explains how to write one, and how to work the facts out for a board nobody has described before. Everything else you write is portable. A pipeline moves from a devkit to a custom product without changing, and a cell never knows what it is running on. The board file is the one place where that stops being true, because it is the only file that describes a physical object. ## Two ways in There are two honest ways to write this file, and which one you want depends on what you are describing. If you are describing **a board**, such as a devkit or something you expect to reuse across projects, work subtractively. Open the chip's datasheet and the board's pinout, and strike out every pin that is spoken for or unsafe. What survives is the board's real capability, and you write it down once. If you are describing **a product**, a design whose wiring is fixed and will not change, work additively. You already know what is connected, because you decided it. Add the pins you actually use. Pins nobody wired cannot be used anyway, so a shorter list costs you nothing. Neither is more correct. The subtractive pass takes longer and produces a file that outlives the project; the additive one gets you running today. ## The four things you write A board file has four parts, and they build on each other. Here is a complete one, for a board with a temperature sensor on I²C and a relay on a bare pin. ```yaml id: my-board chip: esp32c6 buses: i2c0: transport: i2c pins: scl: 10 sda: 11 freq_khz: 400 gpios: general_purpose: [3, 18, 19, 20, 21, 22, 23] devices: - id: bme280 driver: bme280 bus: i2c0 hardware: i2c_addr: 0x76 # SDO pulled to GND - id: relay1 driver: gpio-output pins: out: 2 hardware: active_low: false ``` `id` is a name for the board, and `chip` says which microcontroller it is built around. `chip` is not decoration: it decides which pins exist at all. `buses` declares each shared connection and the pins that carry it. The bus name is not free-form: it has to name a real peripheral, so I²C buses are `i2c0` or `i2c1` and SPI buses `spi2` or `spi3`. The generator accepts those four names on any chip, but your chip may not have all of them: the C5, C6 and C61 each expose only one I²C peripheral, so `i2c1` passes validation and then fails when the firmware is compiled. Check your chip before picking the second one. `devices` lists what is connected. Each entry names an `id` you choose, the `driver` that knows how to talk to it, and either the `bus` it hangs off or the pins it is wired to directly. A device with no `bus` is driven straight from GPIO, like the relay above. `gpios.general_purpose` lists the pins exported to cells: a cell reaches these through the GPIO host functions, and nothing else. Every pin the signal layer itself uses is reserved and must not appear here. Bus pins are declared under `buses:` (GPIO10 and GPIO11 above), and a device's own pins are declared under its `pins:` (`relay1` claims GPIO2) - both are owned by the signal layer, so they are absent from the list above. A pin that is neither reserved nor listed here is simply not offered to cells. ## Where the facts come from Three facts have to come from somewhere, and only one of them is visible on the board. **Which pin is which** comes from the board's pinout diagram, or the schematic if the board is your own. Silkscreen is convenient and usually right, but it is not authoritative. Plenty of boards label sparsely, or not at all. **Which pins you must not touch** comes from the chip's datasheet or technical reference manual. This is the subtractive pass, and it is the part worth taking slowly. **A device's address** comes from its own datasheet, and then from how your particular board strapped it. Some devices have a fixed address and there is nothing to decide. Others have configuration pins, and the value depends on whether they were pulled high or low; breakout boards commonly encode this as a solder bridge. This is why the example above carries a comment beside the address. Six months later, `0x76 # SDO pulled to GND` tells you why, and `0x76` alone does not. ## Which pins are actually free The list of pins you can use is always shorter than the list the chip has, and the reasons are not visible in the pin numbers. Your chip's datasheet is the authority. What follows is the kind of thing to look for, not a list that will come out the same on your board. Some pins are genuinely not yours. Your chip reaches its flash over a small group of pins, and on parts with PSRAM the same group usually carries that too. These are ordinary GPIO-numbered pins and the chip will let you configure them, but your firmware is executing out of that flash while it runs, so repurposing them stops the program doing the repurposing. Espressif's tooling reports them as RESERVED for exactly this reason. Which numbers they are differs from chip to chip, so look yours up rather than carrying a range over from another part. Others are a trade-off rather than a prohibition, and this is worth deciding rather than assuming. A peripheral such as USB, or the JTAG debug interface, occupies particular pins for as long as you want that function. If your product does not expose USB, or you debug over something else, those pins are yours to take, and on a pin-starved design that can be the right call. The question is which you need more: the function, or the pins. Some pins are sampled at reset to decide how the chip boots. Those are often usable afterwards, provided whatever you attach does not hold them at the wrong level while the chip is coming up. And some are simply not brought out to a header on your particular board, which is a fact about the board rather than about the chip. Make the trade-off deliberately, because arriving at it by accident is unpleasant. Take the pins the USB peripheral uses without meaning to, and the board stops enumerating over USB the moment your firmware runs, which also means you can no longer flash it the usual way. It looks exactly like a bricked board. It is not: hold the boot pin low while resetting, which on most devkits is a button, and the chip comes up in its bootloader with your firmware not running, at which point you can flash something else. If you took those pins on purpose, that same procedure is simply how you flash the board from now on. A pin left out of `general_purpose` cannot be claimed by a device and is not offered to cells. Bus pins are the exception, and must be left out precisely because the bus declaration reaches them instead. ## Which settings belong here A device's settings are split between this file and the pipeline, and the split is not a matter of taste. If a setting is decided by the physical hardware (an address fixed by a solder bridge, a relay that is wired active-low, the frequency a bus runs at), it belongs here, in the device's `hardware:` block. Changing it would mean changing the board. If a setting could change without touching a wire (how often to sample, a threshold, a smoothing window), it belongs in the pipeline. Drivers declare which of their settings is which, and the rule is enforced rather than suggested: put a setting in `hardware:` that the driver marked as belonging to the application, and generation fails with a message naming the field. You cannot quietly get this wrong. ## Pins you do not claim A pin listed in `general_purpose` and not claimed by any device is handed to cells, which can drive it directly through the GPIO interface. Cells address pins by their real number, so a cell asking for `11` means GPIO11. This is a deliberate escape hatch, not the main road. The reason the Signal Layer exists is that drivers own hardware and cells consume values; a cell toggling a pin itself is for bring-up, a status LED, a one-off. Reach for a driver first. It is safe by construction. A pin claimed by a device is not merely discouraged for cells. It is not offered to them at all, and the generated pipeline moves each exposed pin out of the peripheral set, so a build where both sides tried to own the same pin would not compile. You cannot create a conflict here, whatever you write. What you *can* do is tell the truth badly. `general_purpose` is a claim about your board that nothing is able to check, because no tool knows what you soldered. List a pin that is really wired to a relay you never described as a device, and you have handed that relay to any cell that asks for it. That is the one mistake in this file with no safety net. ## A board nobody has described yet Most boards do not have a description yet, and writing one is usually not a porting effort. How much work it takes depends on the chip, not on the board. If the chip is already supported, no code is involved at all. Everything above is all there is to it: read the pinout, work out which pins are free, declare your buses, list your devices. A new board on a familiar chip is pure configuration, and this is the common case. If the chip is one Myrmic already runs on but the Signal Layer has not been taught, its pin layout needs adding, because `chip` selects a table of which pins exist. That is a small, contained change. If Myrmic does not run on the chip at all, that is a real port, and it reaches well beyond this file: the hardware abstraction layer, the radio and scheduler support, the watchdog, storage. Writing the board file is the last step of that work rather than the first. ## When you get it wrong Mistakes in this file surface in three quite different ways, and it helps to know which kind you are looking at. **Mistakes the generator can see**, it catches before anything is built: a bus pin repeated in the general-purpose list, a device pin missing from it, two devices claiming the same pin, a source naming a device that does not exist, a pin name the driver never declared, a bus id the chip does not have, a pin outside the chip's layout, a setting in the wrong place. These come with specific messages, and they are the easy ones. **Mistakes about a device on a bus** are usually caught by the driver, because a good driver checks it is talking to what it expects. The BME280 driver reads the chip's identity register before anything else, and rejects a response that is not the BME280's. A wrong address, a swapped SDA and SCL, or a sensor that is not powered all land here. You will see this once: ``` [bme280] init failed — sensor Down ``` and then nothing more. The source keeps retrying quietly at its sample period, so the message is not repeated while it stays down. Note what the line does *not* tell you: the driver's own reason is discarded, so you learn that bring-up failed but not why. The name in brackets is the source id from your pipeline, which matches the device name only if you chose the same one. Its tap stays empty rather than holding a stale value, and the pipeline reports the device as down. If it starts working, because you reseat a wire or fix the address, it recovers on its own and says so. The important part is that the *explanation* is printed once, at startup. Miss it and all you have is a tap with nothing in it. **Mistakes about an actuator are not caught at all.** A relay driver told to drive the wrong pin drives the wrong pin, successfully, forever. There is nothing to read back and no error to raise. Sensors can self-diagnose because they can ask a device who it is; a bare output cannot. This is exactly why a feedback-capable output driver exists: it reads the real state from a separate input line rather than inferring it from the value it just wrote. If knowing an actuator's true state matters, that is the driver to reach for. Otherwise your only instrument is the hardware itself. ## See also - [Design your pipeline](./02_design-your-pipeline.md) - building a pipeline - [Board file](../../10_reference/04_signal-layer/02_board-file.md) - the board file format - [Drivers](../../10_reference/04_signal-layer/03_drivers.md) - the available drivers - [Running on Linux](../../10_reference/04_signal-layer/05_running-on-linux.md) - running the Signal Layer on Linux # Design your pipeline The board file says what your hardware is. The pipeline says what to do with it: which devices produce readings, what happens to those readings on the way through, and what a cell is allowed to see and change. If the board file is the parts list, the pipeline is the instructions. Unlike the board file, the pipeline is portable. It names devices, not pins, so the same pipeline runs against any board whose devices match. ## Four parts, and one idea A pipeline has four kinds of entry: **Sources** turn a device into a stream of readings. **Steps** do something to a reading on the way past. **Taps** are the values a cell can read. **Outlets** are the values a cell can write. ![One source reading feeding a tap directly, a moving-average step, and a cadence and fan-curve chain that drives an outlet](../../../images/signal-layer-pipeline.svg) The idea that connects them is that everything you declare has a name, and you wire things together by naming them. There are three forms a reference can take: | Reference | Means | |---|---| | `room_environment.temperature` | an output of the source `room_environment` | | `temp_cadence` | the output of the step `temp_cadence` | | `relay_cmd.contact` | a feedback-capable outlet's read-back of its real state | Wherever a pipeline asks for an input, a source or a tap's origin, it accepts one of those three. The first two are in the diagram above; the third is not, because it only exists for an outlet whose device can read its own state back: such an outlet publishes that read-back as a value, and the feedback section later on this page shows one. An outlet also exposes `.error` in the same form, carrying faults rather than a reading. ## Sources A source binds a device from your board file and says how to run it. ```yaml sources: - id: room_environment device: bme280 config: sample_interval_ms: 1000 osrs_t: X4 filter: X4 ``` `device` has to match a device id in the board file, and `id` is the name you will use to refer to this source's readings. They need not be the same, and `room_environment` says more downstream than `bme280` does. Everything under `config` is a setting the driver marked as belonging to the application: how often to sample, how much to oversample, how hard to filter. Settings fixed by the hardware, like the device's address, are not here. They are in the board file, and putting one in the wrong place is an error rather than a preference. ## Steps A step takes one input, does something, and produces an output under its own name. ```yaml steps: - id: avg_temp op: moving-average input: room_environment.temperature config: window: 8 ``` `op` names the step module. The ones used here are examples rather than the whole set, which the [step reference](../../10_reference/04_signal-layer/04_steps.md) lists in full. A step has exactly **one** input, which keeps the wiring easy to follow, and you build longer chains by pointing one step at another: ```yaml - id: temp_cadence op: cadence input: room_environment.temperature config: every: 4 mode: SampleHold - id: fan_control op: fan-curve input: temp_cadence config: in_min: 25.0 in_max: 40.0 out_min: 0.0 out_max: 1.0 ``` Chains may fan out. Several steps can take the same input, so one cadenced temperature can feed a fan curve and a threshold controller at once. What they may not do is form a loop: the generator sorts the step graph and rejects a cycle, naming the steps involved. The wiring is type-checked. If a step expects an `f32` and you feed it something else, you get told which step, which input and which types, before anything is built. ### Two places to control the rate A source has a sampling interval, and `cadence` can thin a path further downstream. It looks like duplication and it is not: the source rate is one decision, and each branch after a fan-out can make its own. That is the reason the two exist. A pipeline might sample every 500 ms because a cell wants temperature that fresh, while a controller on the same reading only needs to recompute every couple of seconds. Setting the source slower would degrade the cell's view; cadencing the controller's branch costs the cell nothing. A second reason follows from it: filters need samples to work with. A `moving-average` over eight samples is only meaningful if samples arrive often enough for eight of them to describe something. Sampling fast and thinning afterwards keeps that true. A step may also produce nothing for a while. A moving average has no answer until its window fills. When a step yields nothing, whatever it feeds simply is not updated, and a tap downstream of it keeps whatever it held before, and holds nothing at all the first time round. That differs from a failed sensor, where the pipeline actively clears the tap. ## Taps A tap publishes a value under a name a cell can look up. ```yaml taps: - name: temperature kind: retained type: f32 source: room_environment.temperature - name: avg_temperature kind: retained type: f32 source: avg_temp ``` `source` is any of the three reference forms, so a tap can publish a raw driver output, the result of a step, or an outlet's read-back. There are two kinds you will use. A **retained** tap holds the latest value with its timestamp, and reading it does not consume it, which is what you want for a measurement that is simply true right now. An **event** tap is a queue of things that happened, which the reader drains, and is what you want for alarms and state changes where missing one matters. A third kind, `batch`, appears in the format but is reserved for planned work. It is not quietly ignored: declaring one fails generation with `batch taps not yet supported by codegen`. Taps are your cell-facing interface, so choose them deliberately rather than exhaustively. Publish what a cell will actually use. Intermediate values inside a chain do not need to be taps just because they exist, though tapping one is a reasonable way to make a decision visible when you want to see why it was taken. ## Outlets An outlet is a value a cell can write, wired to a device that can act on it. ```yaml outlets: - name: heat_relay type: DigitalState device: relay1 ``` `type` is the value type the device's driver accepts, `DigitalState` for an on/off output and `PwmDuty` for a duty fraction, and it is checked against the driver rather than trusted. A device can be driven by exactly one outlet, so there is never a question of who is writing to it. Outlets report their own failures. Any outlet exposes an error event you can tap, which is how a cell finds out that a write did not take effect: ```yaml taps: - name: relay_fault kind: event type: OutletFault source: heat_relay.error ``` A device wired with a feedback line offers more. Its driver reads the real state back on a separate input, and that read-back is available as a tap source too. It has to be an outlet on a feedback-capable device, so here it is a second outlet on a different relay: ```yaml outlets: - name: relay_cmd type: DigitalState device: relay_fb taps: - name: relay_contact kind: retained type: bool source: relay_cmd.contact ``` `contact` is a genuine read of the feedback line rather than an echo of the last write, which is the whole point of a hybrid driver. Ask a plain output for it and generation fails with `driver declares no status output 'contact'`. ## Deciding where control lives An outlet can also be driven from inside the pipeline, by giving it an `input`: ```yaml outlets: - name: fan_speed type: PwmDuty device: fan1 input: fan_control ``` Now the fan curve drives the fan directly and no cell is involved. The same job could be done by a cell reading a temperature tap and writing `fan_speed` itself, so the interesting question is which to choose. Put the decision **in the pipeline** when it has to be as fast as possible, or has to keep working regardless of any cell. Pipeline logic runs whether a cell is loaded, being replaced, or has crashed, and it does not wait for anything outside the layer. Put the decision **in a cell** when it is a higher-level one, or when it needs something only a cell has: the network, BLE, other devices in the swarm, or history beyond the reading in front of it. The short version is reflexes in the pipeline, judgement in the cell. A reflex consults nothing and must not stop; a judgement weighs context and can afford to be reloaded. This is about behaviour and independence, not about safety. The Signal Layer makes no safety guarantees, and in-layer control should not be chosen on the belief that it does. ## Closing the loop Loops are allowed and useful, in more than one shape. The ordinary one goes through the physical world: an outlet changes something, a sensor notices, and the next reading reflects it. Nothing in the pipeline is circular here, so nothing objects. A tighter one goes through an outlet's read-back. Where a device reports its real state, as `relay_cmd.contact` does, a step can consume that and act on it. Be careful here: a step whose input does not resolve is not reported. It is dropped from the generated pipeline silently, so a typo, or a status field the driver does not have, costs you the step without an error. What is not allowed is a cycle among steps. That is caught during generation, because a step graph that loops has no order to run in. ## What the generator checks Most mistakes in a pipeline are caught before anything is built, and the messages name the entry at fault: a source pointing at a device the board does not have, a reference that resolves to nothing, a type mismatch between what a step wants and what feeds it, an outlet whose value type the driver does not accept, two outlets on one device, duplicate names, a cycle in the step graph, an application setting that belongs in the board file. What it cannot check is intent. Nothing will tell you that a threshold is wrong for your room or that you cadenced away resolution a controller needed. For that, run it and watch. ## See also - [Describe your hardware](./01_describe-your-hardware.md) - describing your hardware - [Read values](./03_read-values.md) - reading values from a cell - [Pipeline file](../../10_reference/04_signal-layer/01_pipeline-file.md) - the pipeline file format - [Drivers](../../10_reference/04_signal-layer/03_drivers.md) - the available drivers - [Steps](../../10_reference/04_signal-layer/04_steps.md) - the available steps # Discover what a node offers Most cells are written against a pipeline you already know. You know there is a tap called `temperature` because you wrote the pipeline file, and the cell simply resolves that name. Some cells cannot work that way. A cell that logs whatever a node produces, or reports what a device is capable of, or gets deployed across boards that are wired differently, has to ask the node what it has rather than assume. That is what the registry is for. The SDK provides the tools needed to ask: counting what a node publishes, and walking the list to get each name and the kind of slot behind it. ## Walking the registry The registry gives you a count and an entry per index: ```rust use myrmic_sdk::tap::{self, Tap, TapKind}; const MAX_NAME: usize = 64; let count = tap::list_len()?; for i in 0..count { let mut name_buf = [0u8; MAX_NAME]; let Some((name_len, kind)) = tap::list_entry(i, &mut name_buf)? else { continue; }; let name = core::str::from_utf8(&name_buf[..name_len]).unwrap_or("?"); myrmic_sdk::info!("{name} is a {kind:?} tap")?; } ``` Names come back as bytes into a buffer you provide, so pick a size and stick to it. Entries are indexed, and an index that no longer exists gives `Ok(None)` rather than an error, so a loop that races a changing registry skips rather than fails. Having a name, you resolve it exactly as you would a name you knew in advance. ## What you learn, and what you do not This is the part that shapes every discovering cell. The registry tells you **two** things about a tap: its name, and its kind. Kind is the shape of the slot, not the shape of the value: `Retained` for a slot holding the latest value, `Event` for a queue you drain. It does **not** tell you the value's type. There is no way to ask whether `temperature` is an `f32` or something else. The pipeline file knows, the generated code knows, and the cell does not. So a discovering cell has to decide what to do about a value whose type it cannot know. There are three honest answers: know the type anyway because the name is a convention you control; try a likely type and cope when you are wrong; or read the raw bytes and make no assumption. Which of those is safe depends entirely on the kind, and the difference is sharp. ## Probing a retained tap is free; probing an event tap is not A retained tap holds its value. Reading it does not consume it, so a failed decode costs you nothing: you tried `f32`, it was not an `f32`, the value is still there and you can move on. Guessing is a perfectly reasonable strategy. ```rust match tap.read_typed::() { Ok(Some((ts, value))) => myrmic_sdk::info!("{name} = {value:.3} at {ts}ms")?, Ok(None) => {} // no value yet Err(_) => {} // did not decode as f32 } ``` A wrong guess fails honestly. The typed read checks your type against the one the tap declared before decoding, so asking for an `f32` from a tap that holds something else returns an error rather than a plausible wrong number. Probing a retained tap is therefore safe for the tap *and* for your conclusions. An event tap is a queue, and a successful take removes the event. A wrong-typed guess is refused before anything is consumed, so guessing no longer destroys data; what a *right* guess consumes is a real event, taken away from whatever cell this node runs. Probing an event tap is safe when you are wrong and intrusive when you are right, which is a strange enough property to remember. When you would rather look without taking, there is nothing for it: taking is the only read an event tap has. Either know the type from the name, or take the raw bytes with `take_event` and decode them yourself. The one event tap whose type is always known is the health tap: `_signal_layer_health` carries a `HealthEvent`, on every pipeline that has sources. ## Outlets enumerate the same way Outlets have the same two functions, with the same shapes: ```rust use myrmic_sdk::outlet::{self, Outlet}; let count = outlet::list_len()?; let Some((name_len, _kind)) = outlet::list_entry(i, &mut name_buf)? else { continue }; ``` Two differences are worth knowing. Outlet entries report their kind using the same type as taps, and today it is always `Retained`, because an outlet is a last-value-wins write slot. The variant exists so a future event-shaped outlet can be added without breaking the interface, so do not read meaning into it yet. And discovering an outlet tells you even less than discovering a tap. You learn that a node can be driven under that name, but not what value type it accepts. A wrong-typed guess is refused, the same check as on taps; but a write of the *declared* type is accepted and acted on, whatever your reason for sending it was. Guessing at an outlet can move hardware. Enumerating outlets is for reporting what a node can do, not for deciding to do it. ## Sizes and limits A registry is small and bounded. Ask for the count rather than assuming, but do not expect to find hundreds of entries: a pipeline publishes what a cell needs, not everything it knows. The health tap counts toward the same budget as the taps you declared, so a pipeline with sources always has at least one entry even if it declares none of its own. Give the name buffer a fixed size that comfortably fits your naming convention. A name longer than the buffer is truncated rather than reported, so a generous buffer costs you a few bytes of stack and saves a confusing bug. ## When not to enumerate If your cell is written for a pipeline you control, resolve the names directly. Enumerating to find a name you already know adds a loop, a buffer, and a class of bug where a rename silently turns into "not found" instead of a compile-time-obvious change. Discovery earns its cost when the cell genuinely does not know what it will find: a logger, a diagnostic, a bridge that forwards whatever a node produces, or a cell you intend to deploy across boards that differ. For everything else, knowing the name is better than finding it. ## See also - [Read values](./03_read-values.md) - reading values from a cell - [Know when hardware fails](./04_know-when-hardware-fails.md) - driver health ## Related SDK reference - [Signal taps](../../10_reference/03_myrmic-sdk/07_signal-io/01_signal-taps.md) - [Signal outlets](../../10_reference/03_myrmic-sdk/07_signal-io/02_signal-outlets.md) # Drive hardware An outlet is the write side of the Signal Layer. A cell writes a value under a name, and the driver bound to that name turns it into something physical: a relay closing, a fan speeding up. The cell never touches the pin. It writes a value to the outlet and the pipeline carries it the rest of the way, which is what makes the same cell work on a board wired differently. The SDK provides the tools needed to do this: resolving an outlet by name and writing a typed value into it. ## Resolve and write Writing mirrors reading. Resolve the name once, then write through the handle. ```rust use myrmic_sdk::outlet::Outlet; use myrmic_sdk::signal_layer::DigitalState; let Some(heater) = Outlet::resolve("heat_relay")? else { myrmic_sdk::warn!("the pipeline publishes no `heat_relay` outlet")?; return Ok(()); }; heater.write_typed(&DigitalState { on: true })?; ``` The type has to match what the pipeline declared for that outlet. A `DigitalState` for an on/off device, a `PwmDuty` for a duty fraction. Get this wrong and you are told, twice. `write_typed` compares your type against the outlet's declared one before anything crosses the boundary, and a mismatch fails with `ApiError::TypeMismatch`. Behind that, the pipeline strictly decodes every arriving payload and refuses one that does not decode exactly into the declared type, so writing a duty fraction to an on/off outlet is an error, not a silently switched relay. The raw `write` skips only the cell-side check; the pipeline's strict decode still stands behind it. As with taps, keep the handle in `InMemory` rather than resolving on every write, and note the encoding buffer is 64 bytes, which every built-in outlet type fits comfortably. ## What a successful write means This is the part worth being precise about. `write_typed` returning `Ok(())` means **the value was stored**. It does not mean the relay has switched. The value lands in the outlet's slot with a timestamp, and a separate task belonging to that device picks it up and applies it on its next tick. That tick is the outlet's `write_interval_ms`, which defaults to 100 ms and is set in the pipeline. So there is a delay of up to one tick between a successful write and anything moving, and the write itself tells you nothing about whether the hardware accepted it. The pipeline re-applies whenever a *new* write arrives, not when the value changes, so writing the same value twice does reach the driver twice. What happens next is up to the driver. The built-in output drivers can rate-limit themselves, refusing to act again within a minimum interval, and the digital one ignores a write asking for the state it is already in. But the interval defaults to **zero, which means off**: unless the board file sets it, nothing is throttled. If your hardware has a switching limit, set it deliberately rather than assuming it is there. ## The example, continued On the [read values](./03_read-values.md) page there is a cell that watches a temperature and logs when it crosses a limit. Here is the same cell switching a heater instead of logging. ```rust use core::time::Duration; use myrmic_sdk::outlet::Outlet; use myrmic_sdk::signal_layer::DigitalState; use myrmic_sdk::tap::Tap; use myrmic_sdk::{Callback, InMemory, Metadata, Result}; static TEMPERATURE: InMemory> = InMemory::empty(); static HEATER: InMemory> = InMemory::empty(); static WAS_HOT: InMemory = InMemory::new(false); const LIMIT_C: f32 = 30.0; #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { myrmic_sdk::interval(Callback::of::(), Duration::from_secs(2)) .build() .map_err(|_| "failed to create timer")?; Ok(()) } #[myrmic_sdk::cmd] fn check(_md: Metadata) -> Result<()> { let reading = TEMPERATURE.with(|slot| { if slot.is_none() { *slot = Tap::resolve("temperature").ok().flatten(); } slot.as_ref().and_then(|tap| tap.read_typed::().ok().flatten()) })?; let Some((_timestamp_ms, celsius)) = reading else { return Ok(()); // nothing to act on this tick }; let hot = celsius > LIMIT_C; let changed = WAS_HOT.with(|was| core::mem::replace(was, hot) != hot)?; if !changed { return Ok(()); // already in the right state; do not rewrite } HEATER.with(|slot| { if slot.is_none() { *slot = Outlet::resolve("heat_relay").ok().flatten(); } if let Some(outlet) = slot.as_ref() { let _ = outlet.write_typed(&DigitalState { on: !hot }); } })?; Ok(()) } ``` The cell writes only on a change, which matters more here than it did when it was logging. A relay switched every two seconds because a value hovers around the limit is a relay wearing out. Notice there is still no hysteresis. The cell flips the moment the reading crosses 30, so a value dithering across the limit still chatters. Fixing that in the cell means tracking two thresholds; the pipeline already has a step that does it. ## When the write does not take effect A write that was stored can still fail at the hardware. If applying the value fails, the pipeline logs it and publishes a fault on the outlet's error tap, which you can read like any other event tap: ```rust let faults = Tap::resolve("relay_fault")?; // declared in the pipeline, source: heat_relay.error ``` The fault says which half broke. `WriteFailed` means the value could not be applied to the device. `ReadFailed` means the driver could not read the device's state back, which only applies to devices wired to report it. A failed apply is retried. The pipeline does not mark the value as applied unless it succeeds, so the next tick tries the same value again, and it keeps trying until it works or a new write replaces it. A cell does not need to implement its own retry. One case is not a failure and so is not retried. When a driver declines a write because it arrived inside its minimum interval, it reports success, and the pipeline records the value as applied. That write is dropped: no fault, no retry, and the hardware never moved. It is the one way a write can be silently lost, and it only happens once the interval is configured. ## Knowing what actually happened A write tells you a value was stored. A fault tells you an attempt failed. Neither tells you the device is in the state you asked for. For that the hardware has to be wired to report back. A device with a feedback input gets its real state published as a tap, read from a separate line rather than inferred from the write: ```yaml taps: - name: relay_contact kind: retained type: bool source: relay_cmd.contact # a second outlet, on a feedback-capable device ``` That tap is a genuine read of the device, so it will disagree with the written value when something is wrong, which is the entire point. A successful write never populates it, and a fault never populates it either: status comes only from a real read-back. If knowing the true state matters, wire the feedback and use a driver that reads it. If it does not, do not pretend the write is confirmation. ## One writer per device A device can be driven by exactly one outlet. Declare two outlets on the same device and generation fails with `device 'x' is already driven by another outlet (single-writer per device)`. This is deliberate. Two writers with no ordering between them would leave the device in whichever state happened to be applied last, and nothing would be wrong enough to report. If two cells need to influence one actuator, have them agree in the layer above and write once. ## Should this be in the pipeline instead? The cell above is a reasonable use of an outlet: it decides something slowly, at a rate a human would care about, and it does not matter if it pauses briefly while the cell is replaced. Change any of those and the answer changes. If the relay has to react as fast as the sensor can report, or has to keep working while a cell is reloaded, the decision belongs in the pipeline as a step driving the outlet directly, with no cell in the path. The [pipeline page](./02_design-your-pipeline.md) covers how to wire that, and the trade is the same one it describes: the pipeline for reflexes, the cell for judgement. ## See also - [Design your pipeline](./02_design-your-pipeline.md) - building a pipeline - [Read values](./03_read-values.md) - reading values from a cell - [Drivers](../../10_reference/04_signal-layer/03_drivers.md) - the available drivers ## Related SDK reference - [Signal outlets](../../10_reference/03_myrmic-sdk/07_signal-io/02_signal-outlets.md) # Know when hardware fails Sensors come loose. A bus goes quiet. A device that answered a moment ago stops answering. The Signal Layer notices, and it tells you in two ways: the reading disappears, and an event says what changed. This page is about the second one. It follows on from reading values, because the question it answers is the one an empty reading leaves open: is there no value yet, or has something broken? The SDK provides the tools needed to hear about this: health arrives on an ordinary event tap, so a cell reads it with the same functions it uses for any other value. ## Three states Every source in a pipeline is in one of three states. **Up.** The driver initialised and its last sample succeeded. This is the ordinary state and the one a pipeline starts in. **Degraded.** A sample failed on a source that had been working. The pipeline clears that source's retained taps, so reads return no value rather than a stale one, and it re-runs the driver's bring-up on the next tick to try to recover. **Down.** Bring-up itself has not succeeded, either at boot or after a failure knocked the source back into bring-up. Nothing has been published, so there is nothing to clear. The two failure states differ in what they tell you. `Degraded` means it worked and then stopped. `Down` means it never got going. A sensor you forgot to wire reports `Down` forever; a sensor whose jumper falls out reports `Degraded` and then keeps trying. Recovery is automatic in both cases. The source re-runs bring-up every tick, and the first successful sample puts it back to `Up`. ![Up moves to Degraded when a sample fails, clearing the retained taps; Degraded moves to Down when bring-up fails on the retry; both recover to Up](../../../images/signal-layer-health.svg) ## Where the state is published Any pipeline with at least one source publishes an event tap called `_signal_layer_health`. You do not declare it; codegen adds it. A pipeline with no sources has no health tap, because there is nothing to report on. Each event carries which source changed and what it changed to: ```rust use myrmic_sdk::signal_layer::{DriverHealth, HealthEvent}; use myrmic_sdk::tap::Tap; let Some(health) = Tap::resolve("_signal_layer_health")? else { return Ok(()); // a pipeline with no sources }; while let Some(event) = health.take_event_typed::()? { match event.state { DriverHealth::Up => myrmic_sdk::info!("source {} recovered", event.source)?, DriverHealth::Degraded => myrmic_sdk::warn!("source {} degraded", event.source)?, DriverHealth::Down => myrmic_sdk::warn!("source {} is down", event.source)?, } } ``` Drain it in a loop, the same as any event tap. Events accumulate between your polls. ## The source is a number, not a name `event.source` is an index, not an identifier. It is the position of the source in your pipeline file, counting from zero, and **nothing maps it back to a name for you**. So if your pipeline lists `room_environment`, `light` and `air_quality` in that order, `source: 1` means `light`. If you insert a source above it, the same sensor becomes `source: 2` and a cell written against the old numbering silently reports the wrong device. Until there is a name in the event, the practical options are to keep the mapping in the cell as a constant and treat the pipeline's source order as an interface, or to report the raw index and resolve it by hand when reading logs. Neither is satisfying. If you take the first, put a comment in the pipeline file saying the order is load-bearing, because nothing else will warn whoever edits it next. ## What silence means There is no way to ask for the current health. The tap carries transitions, not state, and **there is no event at startup**: a pipeline begins by assuming every source is `Up` and only speaks when that changes. Remember the timelines involved: the pipeline starts with the node and runs whether or not any cell is deployed, and cells are placed whenever the swarm decides, possibly much later. For a cell that comes up together with the node, the convention works. No news is good news. For a cell deployed later it is a trap. If a sensor failed an hour before your cell was loaded, the transition happened while nobody was listening, and your cell sees an empty queue that looks exactly like everything being fine. Two things soften this, and neither fixes it. The queue holds the last few events rather than only the newest, so a recent failure may still be waiting when you start. And a source that is `Degraded` keeps failing and recovering, so it will usually announce itself again before long. The reliable signal is the reading itself. If a tap you expect a value from returns nothing, that source is not currently healthy, whatever the event queue says. Use the health events to learn *what* went wrong and *when*; use the empty reading to know *that* something is wrong. ## Events are taken, not observed An event tap is a queue with a single consumer. Taking an event removes it for everyone. That matters here more than for other taps, because health is the sort of thing several cells might want. If two cells both drain `_signal_layer_health`, each sees roughly half the events and neither sees the full picture, with no error to indicate anything is wrong. If more than one cell needs to know about hardware failures, have one cell drain the tap and republish what it learns, rather than having each read the tap directly. The queue also has a bound. When it is full the oldest event is dropped to make room, so a cell that polls slowly during a burst of failures loses the beginning of the story rather than the end. That is the right way round, but it does mean the first thing that went wrong is the first thing you lose. ## What this does not cover Driver health is about the hardware a pipeline talks to. It says nothing about whether the node is reachable, whether cells are running, or whether the device is keeping up. Those are separate questions with their own answers: the runtime's own liveness supervision, and the observability tooling that reports on nodes, cells and logs. A source reporting `Up` means its last sample succeeded. It does not mean the value is correct, only that the device answered. ## See also - [Read values](./03_read-values.md) - reading values from a cell - [Observability](../10_observability.md) - node, cell and log health ## Related SDK reference - [Signal taps](../../10_reference/03_myrmic-sdk/07_signal-io/01_signal-taps.md) # Read values A cell reads the world through taps. It never touches a sensor, a bus or a pin: the pipeline does that and publishes the result under a name, and your cell looks the name up and reads it. The SDK provides the tools needed to do this: resolving a name into a handle, reading the value behind it, and draining events as they arrive. This page covers reading. Everything here is the same on a microcontroller and on Linux, with two differences called out where they matter. ## Resolve once, read often Reading takes two steps. You resolve a name into a handle, then you read through the handle. ```rust use myrmic_sdk::tap::Tap; let Some(tap) = Tap::resolve("temperature")? else { myrmic_sdk::warn!("the pipeline publishes no `temperature` tap")?; return Ok(()); }; if let Some((timestamp_ms, celsius)) = tap.read_typed::()? { myrmic_sdk::info!("temperature is {celsius:.2} at {timestamp_ms}ms")?; } ``` `read_typed` decodes into whatever type you name, so you get the value already in the shape you want, along with the timestamp the pipeline stamped it with. The two empty cases here deserve different reactions, which is why only one of them is logged. A missing *name* means the cell and the pipeline disagree about what exists, so it is worth saying out loud. A missing *value* is ordinary: it just means nothing has arrived yet, and a cell that complains about it on every tick is only making noise. The type you name has to match what the pipeline publishes. A tap declared `type: f32` reads as `f32`. Nothing checks this for you at build time, because the cell and the pipeline are compiled separately, so the pipeline file is the contract. At runtime it is enforced. The typed calls compare the type you name against the one the slot declared, before decoding anything, and a mismatch comes back as `ApiError::TypeMismatch` instead of a value. The decode after the check is strict and refuses leftover bytes, so a type that merely fits the front of the payload does not produce a plausible wrong number either. Only the raw byte reads stay unchecked, by design: whoever decodes them owns the problem. ## Where to keep the handle Resolving is a lookup, so you do not want it in the middle of a tight read loop. Keep the handle in `InMemory`: ```rust use myrmic_sdk::InMemory; static TEMPERATURE: InMemory> = InMemory::empty(); ``` `InMemory` is cell-local storage for exactly this: host resource handles held across handler invocations, never written to the runtime database, gone when the cell restarts. That last part is what you want. A handle from a previous life would mean nothing, so there is no sense in persisting one. Use `State` for values you want to survive a restart, and `InMemory` for handles. If you find yourself trying to persist a `Tap`, that is the signal you have reached for the wrong one. A kept handle can also outlive what it points at. When the pipeline behind it goes away or comes back (on Linux, the pipeline process restarting is exactly this), reads on the old handle fail with `ApiError::Unavailable`, and the error means precisely one thing: resolve again. It is the one failure a cell can act on mechanically, so treat it as routine, not as a crash. ## A cell that does something A cell can do plenty with a value: log it, aggregate it, forward it to other nodes, or act on it. The example below acts on it, because that is where the interesting question sits, the one the previous page was about: when should a cell decide something, and when should the pipeline? ```rust use core::time::Duration; use myrmic_sdk::tap::Tap; use myrmic_sdk::{Callback, InMemory, Metadata, Result}; static TEMPERATURE: InMemory> = InMemory::empty(); static WAS_HOT: InMemory = InMemory::new(false); const LIMIT_C: f32 = 30.0; #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { myrmic_sdk::interval(Callback::of::(), Duration::from_secs(2)) .build() .map_err(|_| "failed to create timer")?; Ok(()) } #[myrmic_sdk::cmd] fn check(_md: Metadata) -> Result<()> { let reading = TEMPERATURE.with(|slot| { if slot.is_none() { *slot = Tap::resolve("temperature").ok().flatten(); } slot.as_ref().and_then(|tap| tap.read_typed::().ok().flatten()) })?; let Some((_timestamp_ms, celsius)) = reading else { return Ok(()); // nothing to act on this tick; not worth logging }; let hot = celsius > LIMIT_C; let changed = WAS_HOT.with(|was| core::mem::replace(was, hot) != hot)?; if changed { myrmic_sdk::info!("temperature crossed {LIMIT_C}: now {celsius:.2}")?; } Ok(()) } ``` Two things about this cell are worth noticing. It only acts on a **change**, not on every reading above the limit. A cell that logs on every tick while the value sits at 30.1 is noise. And this decision belongs in a cell rather than in the pipeline. If it had to switch a relay as fast as possible, or keep working while the cell is being replaced, it would belong in the pipeline instead, as a `hysteresis` step driving an outlet. What makes it a cell's job is that it is slower, and that a cell can do things the pipeline cannot: reach the network, talk to other nodes, or keep history. ## The three kinds of nothing Most of the care in a reading cell goes into telling apart three different empty answers. **The name is not registered.** `Tap::resolve` gives `Ok(None)`. Either the pipeline does not publish that tap, or you spelled it differently from the pipeline file. **The tap exists but holds no value.** `read_typed` gives `Ok(None)`. This is the normal state before the first sample arrives, and it is also what you get when the source has failed: when a driver stops working, the pipeline clears its taps rather than leaving a stale value behind. So an empty read means "no trustworthy value right now", which is the honest answer but not a detailed one. **The event queue is empty.** `take_event_typed` gives `Ok(None)`. Nothing has happened since you last drained it. None of these is an error, and all three are ordinary. An `Err` is different: it means the read itself could not be served. If you need to know *why* a value is missing, read the health tap. Every pipeline with at least one source publishes `_signal_layer_health` as an event tap carrying which source changed state and what it changed to, so a cell can tell "the sensor is down" from "the sensor has not reported yet". ## Timestamps are not a clock Every retained read hands back a timestamp in milliseconds, and it is tempting to treat it as a time of day. It is not. The number is milliseconds since the node started: `embassy_time::Instant` on a microcontroller, and time since process start on Linux. It only ever moves forward, and it says nothing about what the date is. So you can compare two timestamps from the same node to see which reading is newer, and you can subtract them to find out how stale a value is. What you cannot do is turn one into a wall-clock time, or compare a timestamp from one node against a timestamp from another. They do not share an origin. ## Events are consumed as you read them A retained tap holds a value you can read as often as you like. An event tap is a queue, and taking an event removes it. Drain it in a loop: ```rust while let Some(alarm) = tap.take_event_typed::()? { myrmic_sdk::info!("alarm at {}", alarm.value)?; } ``` There is one sharp edge here, and it is worth reading twice. **A wrong type does not cost you the event.** `take_event_typed` checks your type against the slot's declared one before it consumes anything, so a mismatch is refused with the event still queued. What does consume the event first is a payload of the *declared* type that then fails to decode, which means the producer wrote garbage; that one is not retryable. When losing an event would matter, `take_event` hands you the raw bytes to decode yourself, so any failure leaves you holding the payload. `read_typed` and `take_event_typed` decode through a 64-byte scratch buffer. On a microcontroller a larger payload comes back as an error. On Linux it is silently truncated to the first 64 bytes; the strict decode usually catches that, but a truncation landing exactly on a value boundary can still decode. Either way, read into your own buffer with `read_retained` or `take_event` when you expect a payload that size. ## When the pipeline is not there Reads fail differently on the two platforms, and it shows up as how much a cell can tell you. On a microcontroller the pipeline and the cell are the same firmware, so a read is a memory lookup. It cannot really fail, and reading a name that does not exist is simply `Ok(None)`. On Linux the pipeline is a separate process and every read is a round trip to it. If that process is gone or unresponsive, the call is bounded rather than hanging: it gives up after five seconds and reports failure. Two consequences follow. A cell polling quickly against a dead pipeline will stall for that timeout on every attempt, so its poll rate quietly collapses to the timeout. And `Tap::resolve` returning `Ok(None)` cannot be read as "no such tap" with confidence, because an unreachable pipeline produces the same answer. Today a cell cannot distinguish them. A failed read is different. The connection is rebuilt automatically, but handles from before the reconnect stop working, so a read through an old handle returns an error rather than a value. The remedy is simple: on an error, drop the handle and resolve again. The error itself is not very descriptive at the moment, so treat any error from a read as "re-resolve and try again" rather than trying to interpret it. ## How often to read There is no subscribe and no wait. A cell polls, normally from an interval timer as in the example above. Read at the rate you actually need values, and set the source's sample interval in the pipeline to match. Reading faster than the pipeline samples just returns the same value again, and sampling faster than anyone reads spends power for nothing. The two numbers are set in different files, so it is worth checking they agree. ## See also - [Know when hardware fails](./04_know-when-hardware-fails.md) - driver health - [Running on Linux](../../10_reference/04_signal-layer/05_running-on-linux.md) - running the Signal Layer on Linux ## Related SDK reference - [Signal taps](../../10_reference/03_myrmic-sdk/07_signal-io/01_signal-taps.md) - [Transient state](../../10_reference/03_myrmic-sdk/05_state-and-storage/02_transient-state.md) # Write your own driver A driver is the piece that knows one kind of device, a sensor or an actuator: how to wake it, how to ask it for a reading, or how to make it act. Everything else in the Signal Layer is generic, so supporting a new sensor or a new actuator means writing a driver and nothing more. A driver is a small Rust crate: a directory holding `Cargo.toml`, `src/lib.rs` with the logic, and a `descriptor.yaml` telling the generator what it needs and what it produces. `myrmic signal-layer driver my-sensor --bus i2c` (or `--bus spi`) scaffolds all three, already compiling with a stubbed test suite, so you fill in only what is specific to your device; the shipped drivers under `signal-modules/drivers/` are working examples of everything this page describes. You can author a driver inside the repository or, as [Authoring out of the tree](#authoring-out-of-the-tree) below shows, in a directory of your own. Start `src/lib.rs` with `#![cfg_attr(not(test), no_std)]`. Every shipped driver has it, and without it your crate builds on your laptop and fails the moment someone compiles it for a board. ## The rule that shapes everything A driver never knows where it is. It does not know which pin it is on, which board it is running on, or whether it sits on an ESP32 or a Linux box. It is handed what it needs and gets on with it, which is why the same driver crate works on every supported platform without a single conditional. That is not a style preference. It is enforced by the shape of the code: your driver is generic over the hardware it touches, using the `embedded-hal` traits, so it physically cannot reach for a specific pin or a specific chip. Everything below follows from that one idea. ## Sensor drivers: producing values A sensor driver is handed the bus on every call and does not keep it. This is deliberate: a bus is shared between every device on it, so no single driver can own it. ```rust // The register map of your part. const REG_CHIP_ID: u8 = 0xD0; const REG_CTRL: u8 = 0xF4; const REG_VALUE: u8 = 0xFA; const CHIP_ID: u8 = 0x60; pub enum MySensorError { /// The bus itself failed; carries the underlying error. Bus(E), /// A device answered, but it is not the part we expected. WrongChip { found: u8 }, } /// One field per descriptor `outputs` entry, named and typed to match. pub struct MySensorReadings { pub temperature: f32, } pub struct MySensor { cfg: MySensorConfig } impl MySensor { pub async fn init(&mut self, bus: &mut I) -> Result<(), MySensorError> { // Confirm we are talking to the right part before configuring it. let mut id = [0u8; 1]; bus.write_read(self.cfg.i2c_addr, &[REG_CHIP_ID], &mut id) .await .map_err(MySensorError::Bus)?; if id[0] != CHIP_ID { return Err(MySensorError::WrongChip { found: id[0] }); } // One-time configuration: measurement mode, filters, whatever your part needs. bus.write(self.cfg.i2c_addr, &[REG_CTRL, 0b0000_0011]) .await .map_err(MySensorError::Bus) } pub async fn sample( &mut self, bus: &mut I, ) -> Result> { // Read the measurement registers in one transaction. let mut raw = [0u8; 2]; bus.write_read(self.cfg.i2c_addr, &[REG_VALUE], &mut raw) .await .map_err(MySensorError::Bus)?; // Convert raw counts into the unit the descriptor promises (°C here). let temperature = f32::from(i16::from_be_bytes(raw)) / 100.0; Ok(MySensorReadings { temperature }) } } ``` The `cfg` field is the driver's configuration; the next section shows the descriptor it comes from and the struct it fills. Three things to copy from that shape. **The bus is a generic parameter on the method**, not a field on the struct, and it comes from `embedded_hal_async`. Sensor work is asynchronous because a bus transaction takes real time and the runtime has other things to do meanwhile. **The readings are a struct whose fields match the descriptor's `outputs`.** The generator wires `readings.temperature` to whatever the pipeline called it, so the names have to line up. **The error type carries the bus error rather than swallowing it.** A `Bus(E)` variant plus your own domain variants is the pattern, and the `WrongChip` variant above is the one worth copying: checking an identity register during `init` and failing distinctly is what turns a mis-wired sensor into a clear message instead of nonsense readings. The shipped `bme280` driver does exactly this. `init` runs before the first sample and again whenever the pipeline is trying to recover a failed source, so it must be safe to call more than once. ### The sensor's descriptor The generator never sees your Rust source. What it reads is the `descriptor.yaml` next to it (the shipped descriptors under `signal-modules/` are the reference; this one is a minimal sensor's): ```yaml id: my-sensor category: sensor-drivers description: > What the device is and what it measures. requires: buses: - transport: i2c config_schema: i2c_addr: scope: hardware rust_type: u8 default: 0x76 description: "I2C address (SDO to GND = 0x76, SDO to VCC = 0x77)" sample_interval_ms: scope: application rust_type: u64 default: 1000 description: Polling interval in milliseconds outputs: - name: temperature type: f32 unit: "°C" ``` `requires` says what the device needs to be reachable: a bus transport, and optionally named pins the board file will assign. `outputs` names what a sensor produces, and those names are what a pipeline points a tap at. An actuator declares `writes` instead, which the next section covers. `config_schema` is where a driver states its knobs, and the `scope` on each one is load-bearing. `hardware` means the value is a fact about the wiring, so it belongs in the board file. `application` means it can change without touching a wire, so it belongs in the pipeline. Pick the wrong one and the generator rejects the config rather than quietly accepting it in the wrong place, so this is worth getting right the first time. The `cfg` in the sensor snippet above is where these fields land. `MySensorConfig` is not generated; you define it in the driver crate, one field per `config_schema` entry, and the generator emits the code that fills it: board-file values for `hardware` scope, pipeline values for `application` scope, and the descriptor's defaults for whatever neither sets. For the descriptor above, the matching struct is: ```rust /// One field per `config_schema` entry, named and typed to match. pub struct MySensorConfig { /// I2C address: 0x76 with SDO to GND, 0x77 with SDO to VCC. pub i2c_addr: u8, } ``` One field is deliberately missing. `sample_interval_ms` is consumed by the generated sampling loop itself, which ticks at that rate; it is never handed to the driver, so it gets no struct field. Every other `config_schema` entry needs one. ## Actuator drivers: consuming outlet values An actuator driver is the mirror image, and the differences are not arbitrary. ```rust pub struct MyActuator

{ pin: P, cfg: MyActuatorConfig, is_on: bool, last_switch_ms: u64, } impl MyActuator

{ pub fn init(&mut self) -> Result<(), MyActuatorError> { // Drive the pin to a known-safe state before the first write. self.pin.set_low().map_err(MyActuatorError::Pin) } pub fn apply( &mut self, cmd: DigitalState, now_ms: u64, ) -> Result<(), MyActuatorError> { // Protect the hardware: ignore writes arriving faster than it can stand. if now_ms.saturating_sub(self.last_switch_ms) < self.cfg.min_switch_interval_ms { return Ok(()); } // A no-op write is not a switch; don't burn a relay cycle on it. if cmd.on == self.is_on { return Ok(()); } if cmd.on { self.pin.set_high() } else { self.pin.set_low() } .map_err(MyActuatorError::Pin)?; self.is_on = cmd.on; self.last_switch_ms = now_ms; Ok(()) } } ``` **It owns its hardware.** A pin belongs to exactly one device, so the driver takes it and keeps it, which is the opposite of the bus case and for the same reason. **It is synchronous.** Setting a pin or a duty cycle does not wait for anything. **It is given the time.** `apply` receives `now_ms` rather than reading a clock, so the driver stays testable and the runtime keeps control of what time means. ### The actuator's descriptor The descriptor declares `writes` instead of `outputs`: ```yaml writes: type: DigitalState mode: digital requires: optional_pins: [out] ``` `type` is the value the driver accepts and is checked against the outlet that drives it. `mode` tells the generator what kind of hardware to hand over: a plain output for `digital`, a configured PWM channel for `pwm` (pulse-width modulation: a fixed-frequency square wave whose on-fraction the value sets, which is how fan speeds and LED brightness are driven). ### Protect the hardware inside the driver This is the part worth taking seriously. The pipeline re-applies a write whenever a new one arrives, and a cell may write far more often than a device can stand. Nothing upstream knows what your relay can survive, so the limit has to live in the driver. The built-in output drivers can do this: they refuse to act again within a minimum interval, and the digital one additionally ignores a write asking for the state it is already in. But the interval defaults to zero, meaning no limit, so it protects nothing until a board file sets it. What the design does guarantee is *where* the setting lives: it is `hardware` scope, so a pipeline cannot weaken it. If your device has a physical limit, encode it the same way: as a `hardware`-scope config field with a sane default, enforced inside `apply`. A driver that faithfully relays every write to a relay rated for a few hundred thousand operations is not being neutral, it is being negligent. ### Reporting real state A driver whose hardware can report back can expose that too. Add `read_status` and declare the fields as outputs, and the pipeline publishes them as taps alongside the outlet. The rule here is that status comes only from a genuine read. Never infer it from the value you just wrote: the entire value of a feedback line is that it disagrees with you when something has gone wrong. ## The naming contract The naming is a contract, and it runs through the **directory**, not the `id:` field. A board file naming `driver: bme280` makes the generator look in `bme280/` for the descriptor and add a dependency on the crate `bme280-driver`. Keep all three aligned. The `id:` key inside the descriptor is not read at all, so correcting that alone fixes nothing. ## Configuration and defaults Every `config_schema` field needs a default that works, because a board file or pipeline may not mention it. Prefer defaults matching the most common wiring of the part. For a knob with a fixed set of choices, use a typed enum rather than a raw number. The generator maps it, the pipeline reads legibly, and an invalid value is caught during generation rather than producing a device in a strange mode. ## Testing without hardware Nothing in this section goes through the Signal Layer. A driver is a standalone Rust crate, so its tests are ordinary `cargo test` unit tests: no pipeline, no board file, no generator. That is worth saying because it is easy to assume the fake hardware has to be injected from somewhere above, and it does not. The generic parameter *is* the injection point, and where it goes follows the same ownership split as before. An actuator owns its hardware, so the fake goes in at construction: ```rust struct FakePin { high: bool } impl embedded_hal::digital::ErrorType for FakePin { type Error = core::convert::Infallible; } impl embedded_hal::digital::OutputPin for FakePin { fn set_high(&mut self) -> Result<(), Self::Error> { self.high = true; Ok(()) } fn set_low(&mut self) -> Result<(), Self::Error> { self.high = false; Ok(()) } } let mut out = MyActuator::new(&MyActuatorConfig::default(), FakePin { high: false }); out.apply(DigitalState { on: true }, 0).unwrap(); assert!(out.pin.high); ``` A sensor borrows its bus, so the fake goes in per call. Here `embedded-hal-mock` does the work: you declare the transactions you expect and hand the mock to the driver. ```rust use embedded_hal_mock::eh1::i2c::{Mock, Transaction as T}; let mut mock = Mock::new(&txns); // canned register contents driver.init(&mut mock).await.unwrap(); let readings = driver.sample(&mut mock).await.unwrap(); ``` That second form is more useful than it first looks. Because you supply the raw register bytes, you can drive the decoding path with numbers you control: calibration constants from the datasheet, a raw sample, and an assertion about what comes out. The BME280 driver tests this way, including a test that a wrong chip identity is reported as an error rather than decoded as a reading. These are the tests that catch the errors that matter. Whether the wiring is right is a question for the bench; whether your maths is right is a question you can answer at your desk. ## Authoring out of the tree You do not have to work inside the Myrmic checkout. `myrmic signal-layer driver my-sensor --bus i2c --registry-dir ~/sl-modules` scaffolds the crate under `~/sl-modules/drivers/my-sensor`, and a pipeline builds against it by naming that registry directory. In a Linux pipeline's `build.rs` that is the third argument, `build_pipeline("board.yml", "pipeline.yml", Some("../sl-modules"))`; on a firmware pipeline it is `.include("../sl-modules")` on the `esp_firmware_build::pipeline()` builder. Either way, add an ordinary path dependency on the crate. The path is relative to the pipeline crate, and codegen overlays your descriptors onto the shipped set, so a board file and pipeline name your driver exactly as they would a built-in. This is the path for authoring a driver locally, before it is ready to move into the tree. The [module authoring tutorial](../../04_tutorials/05_authoring-signal-layer-modules.md) walks through it end to end. ## Adding it to the tree When a driver has earned its place, it moves into the repository. The repository is one Cargo workspace, and `signal-modules/drivers/*` is a workspace-member glob, so a driver crate placed alongside the others is picked up automatically. It also needs an entry in the root `[workspace.dependencies]`, because the generated pipeline crate refers to it as a workspace dependency; without that, generation emits a `Cargo.toml` that does not resolve. Once that is in place, a board file can name the driver on a device and a pipeline can point at it. From there, the [board file](./01_describe-your-hardware.md) decides where the device is wired and the [pipeline](./02_design-your-pipeline.md) decides what happens to its values. ## See also - [Write your own step](./08_write-your-own-step.md) - writing a step - [Drivers](../../10_reference/04_signal-layer/03_drivers.md) - the available drivers # Write your own step A step is a small Rust crate: a directory holding `Cargo.toml`, `src/lib.rs`, and a `descriptor.yaml`. `myrmic signal-layer step my-step` scaffolds all three, already compiling with a stubbed test suite. You can author it in the repository, under `signal-modules/steps/` next to the shipped ones, or, as [Authoring out of the tree](#authoring-out-of-the-tree) below shows, in a directory of your own. Start its `src/lib.rs` with `#![cfg_attr(not(test), no_std)]`: every shipped step has it, and without it your crate builds on your laptop and fails when someone compiles it for a board. A step is a transform. It takes a value on its way through the pipeline, does something to it, and passes on the result: smoothing a noisy reading, converting a unit, turning a temperature into a fan speed, turning a threshold crossing into an event. If a driver is what knows a device, a step is what knows a calculation. It never touches hardware, and it never talks to anything outside itself. ## The contract A step is one trait: ```rust pub trait ProcessingStep { type Input; type Output; fn step(&mut self, input: Self::Input) -> Option; } ``` That is the whole interface. A value goes in, and either a value comes out or nothing does. Three constraints come with it, and they are the reason steps are cheap to run and easy to test. A step is **synchronous**: no awaiting, because it is called inline on the source's tick. It has **no access to the outside**: no slots, no registry, no shared state, no clock. And it is **self-contained**: everything it needs is its own state and the value it was handed. What a step *may* do is keep state, and most interesting ones do. The trait takes `&mut self` precisely so a step can remember something between calls: a window of past samples, a counter, a flag for whether it has already fired. ### A step must never block This is the constraint with teeth, so it is worth being blunt about the consequence. A step runs inline on its source's task, and on a microcontroller that task shares the main executor with the rest of the pipeline, the cell runtime and the watchdog's feeder. The feeder's scheduling *is* the liveness signal: if that executor stops turning, the feed stops with it. So a step that spins, sleeps, or grinds through a long computation does not merely delay its own pipeline. The executor is cooperative, so a task that never yields is never preempted: everything sharing it stalls, including the heartbeat the watchdog depends on, so the feed is withheld and the device resets. On Linux the outcome is milder but still bad: the step occupies a runtime worker for as long as it runs, and there is no watchdog to rescue anything. Keep `step` to arithmetic over its input and its own state. If a calculation is genuinely expensive, do it in a cell, where taking a while costs only that cell. ## Returning nothing is a normal answer `Option` is not an error channel. It means *no value this time*, and it is how a step says "ask me again later". A moving average returns nothing until its window has filled. A cadence step returns nothing on the samples it is thinning out. An edge trigger returns nothing on every sample that is not a crossing, which is most of them. When a step returns `None`, whatever it feeds is simply not updated: the next step is not called, and a tap downstream keeps whatever it had rather than being cleared. So returning nothing is quiet, not disruptive, and you should reach for it whenever the honest answer is that you do not have one. ## A worked step Here is a whole step, config and all: ```rust use signal_layer_core::ProcessingStep; pub struct ScaleConfig { pub factor: f32, pub offset: f32, } pub struct ScaleState { factor: f32, offset: f32, } impl ScaleState { pub fn new(cfg: ScaleConfig) -> Self { Self { factor: cfg.factor, offset: cfg.offset } } } impl ProcessingStep for ScaleState { /// What the step consumes. type Input = f32; /// What it emits. type Output = f32; fn step(&mut self, input: Self::Input) -> Option { let output = input * self.factor + self.offset; Some(output) } } ``` The two types do not have to match. A step that changes the type is ordinary; the shipped `fan-curve` takes an `f32` reading and emits a `PwmDuty` outlet value (see the [steps reference](../../10_reference/04_signal-layer/04_steps.md)), and the pipeline checks the chain end to end at generation time. The split into a `Config` and a `State` is the convention: the config is what the pipeline declares, the state is what runs. A step that never returns `None` is fine, as this one is; a step whose answer is not always available returns `None` on the calls where it has none. ## The descriptor As with drivers, the generator reads a descriptor and never your source: ```yaml id: scale category: processing-steps description: > Linear transform: multiplies the input by `factor` and adds `offset`. Emits on every sample; there is no warm-up and no state carried between samples. inputs: - name: value type: f32 outputs: - name: scaled type: f32 config_schema: factor: scope: application rust_type: f32 default: 1.0 description: Multiplier applied to the input offset: scope: application rust_type: f32 default: 0.0 description: Added after scaling ``` `inputs` and `outputs` are how the generator type-checks the wiring. If a pipeline feeds your step something that does not match its declared input, generation fails and names both types, which is a far better outcome than a type error surfacing at runtime. Step config is always `scope: application` in practice, and should be. A step is arithmetic, and arithmetic does not depend on how the board is wired, so there is nothing for the board file to say. Note this one is a convention rather than a rule: unlike driver config, a step's scope is not enforced, and a step declaring `hardware` would still be read from the pipeline. If you find yourself wanting it, that is a hint the value belongs to a driver instead. Write the description as if it will be the only thing a reader sees, because on the [steps reference](../../10_reference/04_signal-layer/04_steps.md) it is. Say what the step computes, what each config field does in behavioural terms, and what it emits when it has no answer yet. ## Types, and when to be generic Most steps name concrete types, as the example does: `f32` in, `f32` out. They do not have to match. A step is free to change the type, and some of the more useful ones do: a threshold turns a reading into an event, a curve turns a measurement into a control value. Type conversion is a perfectly good reason for a step to exist. A few steps genuinely do not care what they are carrying. Cadence is one: it decides *whether* to pass a value along, never what the value is, so it is generic and declares no fixed types. That is worth copying when it is true, and worth avoiding when it is not. Being generic to seem flexible costs you the type check that would have caught a mis-wired pipeline. ## Authoring out of the tree You do not have to work inside the Myrmic checkout. `myrmic signal-layer step my-step --registry-dir ~/sl-modules` scaffolds the crate under `~/sl-modules/steps/my-step`, and a pipeline builds against it by naming that registry directory in its `build.rs`: `build_pipeline("board.yml", "pipeline.yml", Some("../sl-modules"))` for a Linux pipeline, or `.include("../sl-modules")` for a firmware one, together with an ordinary path dependency on the crate. The path is relative to the pipeline crate, and codegen overlays your descriptors onto the shipped set, so a pipeline names your step as an `op` exactly as it would a built-in. This is the path for authoring a step locally, before it is ready to move into the tree. The [module authoring tutorial](../../04_tutorials/05_authoring-signal-layer-modules.md) walks through it end to end. ## Adding it to the tree When a step has earned its place, it moves into the repository. Step crates live beside the others under `signal-modules/steps//`, and a step's crate is named exactly its `id`, with no suffix. That differs from drivers, which are always `{id}-driver`, so it is worth checking rather than assuming. Once the crate and its descriptor are in place, a pipeline can name it as an `op` and wire it to anything whose type matches. ## Testing Steps are the easiest thing in the Signal Layer to test, because they are functions with memory and nothing else. No fake hardware, no bus, no pipeline: construct the state and call it. ```rust let mut s = ScaleState::new(ScaleConfig { factor: 2.0, offset: 1.0 }); assert_eq!(s.step(3.0), Some(7.0)); ``` For a step with state, the test that matters is the sequence rather than any single call: that a moving average stays quiet until its window fills, that an edge trigger fires once and not again while the condition holds, that a cadence passes exactly one sample in every four. Those are the behaviours a description promises, and they are cheap to pin down. If you find a step hard to test, it is usually a sign it is doing something a step should not: reaching for time, for a slot, or for the outside world. That work belongs in a driver or a cell. ## See also - [Write your own driver](./07_write-your-own-driver.md) - writing a driver - [Design your pipeline](./02_design-your-pipeline.md) - building a pipeline # State and storage During its lifetime, a cell reads, creates, and modifies data. To choose the right way to store that data, it is important to understand how Myrmic works. Myrmic cells run as Wasm modules. A Wasm module has its own linear memory, but this memory is temporary. It is initialized whenever a handler runs, such as a command, event, or scheduled handler, and it is discarded when the handler finishes. This is a fundamental property of the Wasm execution model: a cell cannot hold data in its own memory across calls. To preserve data between handler invocations, a cell stores it in the database provided by the Myrmic runtime. The database provides persistent and scoped storage and supports retention policies. Stored data is kept as a single copy unless you configure replication with [`myrmic replicate`](../10_reference/02_myrmic-cli/15_replicate.md). The runtime database supports several storage models: key-value, table-row, time series, and RDF. The Myrmic SDK provides the tools needed to work with each model. All storage operations take place within a scope. Before looking at the available storage modes, we will explain how scopes organize data and control access. ## Scope All storage models use scopes, either explicitly or implicitly. A scope organizes data, controls who can access it, and establishes tenancy boundaries. Every piece of data belongs to a scope, and every storage operation takes place within one. A scope is structured as `{namespace}/{database}/{schema}`. There are two scope types: - **Private** - data under this scope is bound to the cell instance. Other cells cannot read or write it. - **Public** - data under this scope is shared and accessible across all cells using the same scope definition. ```rust use myrmic_sdk::db::Scope; // Private - data is bound to this cell instance let scope = Scope::private(); // Private with a custom schema let scope = Scope::private_in(Some("my-schema")); // Public - data is shared across all cells using the same scope let scope = Scope::public("my-namespace"); // Public with custom database and schema let scope = Scope::public_in("my-namespace", Some("my-database"), Some("my-schema")); // Default - equivalent to Scope::private() let scope = Scope::default(); ``` ## Storage Modes ### State A cell often needs to keep a value between handler invocations, such as a counter, threshold, or flag. The Myrmic SDK provides `State` - a simplified interface to the runtime's key-value database. A state handle associates one fixed key with one typed value, which can be a scalar or a structured object. The value is read and written as a complete unit and can be accessed from any handler in the cell. `State` provides the following operations: - [Declare](./06_state-and-storage/01_state.md#declare) - Create a typed state handle and bind it to a key and scope - [Write](./06_state-and-storage/01_state.md#write) - Save a value under the handle's key, replacing any value already stored there - [Read](./06_state-and-storage/01_state.md#read) - Load the stored value, or receive none if no value exists - [Modify](./06_state-and-storage/01_state.md#modify) - Load, change, and save a value in a single operation - [Guard](./06_state-and-storage/01_state.md#guard) - Access a value through a mutable guard that saves it automatically when dropped - [Upsert](./06_state-and-storage/01_state.md#upsert) - Return the stored value, or create and return a default value if none exists Let us see [how to work with state in practice](./06_state-and-storage/01_state.md). ### Key-value Store The key-value store manages many typed values under different keys. The Myrmic SDK provides `Kv` as a typed key-value store handle rooted at a prefix. `Kv` provides the following operations: - [Declare](./06_state-and-storage/02_key-value-store.md#declare) - Create a typed key-value handle and bind it to a prefix and scope - [Write](./06_state-and-storage/02_key-value-store.md#write) - Store a value under a key, replacing any value already stored there - [Read](./06_state-and-storage/02_key-value-store.md#read) - Retrieve the value stored under a key, or receive none if the key does not exist - [Delete](./06_state-and-storage/02_key-value-store.md#delete) - Remove the value stored under a key - [Iterate](./06_state-and-storage/02_key-value-store.md#iterate) - Process entries under the full prefix or a selected sub-prefix - [Keys](./06_state-and-storage/02_key-value-store.md#keys) - Retrieve stored keys without loading their values #### State and key-value comparison `State` and `Kv` both store typed values in the runtime's key-value database. Each value can be a struct and is read or written as a complete unit. The difference is cardinality: - `State` manages one value under one fixed key. - `Kv` manages many values under different keys beneath one prefix. Both interfaces can store the same type: ```rust use myrmic_sdk::db::state::State; use myrmic_sdk::db::tree::Kv; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize)] struct SensorConfig { threshold: f32, enabled: bool, } ``` Use `State` when the cell needs one sensor configuration: ```rust const CONFIG: State = State::new_const("config"); let config = SensorConfig { threshold: 30.0, enabled: true, }; CONFIG.save(&config)?; let config = CONFIG.load()?; ``` This creates one entry: ```text config -> SensorConfig ``` Use `Kv` when the cell needs configurations for multiple sensors: ```rust const CONFIGS: Kv = Kv::new("configs"); let sensor_01 = SensorConfig { threshold: 25.0, enabled: true, }; let sensor_02 = SensorConfig { threshold: 30.0, enabled: false, }; CONFIGS.put("sensor-01", &sensor_01)?; CONFIGS.put("sensor-02", &sensor_02)?; let config = CONFIGS.get("sensor-01")?; ``` This creates multiple entries under the same prefix: ```text configs/sensor-01 -> SensorConfig configs/sensor-02 -> SensorConfig ``` In both cases, `SensorConfig` is typed and read or written as a complete value. The difference is one fixed key per `State` handle versus many keys under a `Kv` prefix. Let us see [how to work with the key-value store in practice](./06_state-and-storage/02_key-value-store.md). ### Table Store The runtime database supports a table model - a named collection of typed entries, each identified by a key. Entries can be inserted with an auto-assigned UUID or an explicit key, looked up by ID, deleted, counted, and iterated in order. The Myrmic SDK provides `Table` as the abstraction for this. `Table` provides the following operations: - [Declare](./06_state-and-storage/03_table-store.md#declare) - Create a typed table handle and bind it to a table name and scope - [Insert](./06_state-and-storage/03_table-store.md#insert) - Store an entry under an automatically assigned UUID or an explicit key - [Get by ID](./06_state-and-storage/03_table-store.md#get-by-id) - Retrieve an entry by its key, or receive none if it does not exist - [Delete](./06_state-and-storage/03_table-store.md#delete) - Remove an entry by its key - [Count](./06_state-and-storage/03_table-store.md#count) - Return the number of entries in the table - [Iterate](./06_state-and-storage/03_table-store.md#iterate) - Process table entries in ascending or descending key order - [Keys](./06_state-and-storage/03_table-store.md#keys) - Iterate over the keys or load all IDs into memory Let us see [how to work with the table store in practice](./06_state-and-storage/03_table-store.md). ### Time-series Store The runtime database supports a time-series model, to store timestamped records - multiple records can belong to the same subject, each capturing a point in time. Each entry is called a **measurement** and is made up of: - a **name** that groups related measurements into a series - **fields** - a list of named, typed values carrying the data - **tags** - optional string metadata attached to the entry - a **timestamp** Each write is additive - it adds a new measurement without affecting previous ones. Measurements are permanent and cannot be deleted. Unlike the other storage models, the SDK does not provide an abstraction layer for the time-series store - all interactions happen directly through functions. The time-series store provides the following operations: - [Write](./06_state-and-storage/04_time-series-store.md#write) - Add a timestamped measurement without changing earlier measurements - [Query](./06_state-and-storage/04_time-series-store.md#query) - Retrieve measurements by name, with optional time-range, limit, and ordering parameters Let us see [how to work with the time-series store in practice](./06_state-and-storage/04_time-series-store.md). ### Semantic Store The runtime database also supports a semantic store - an [RDF](https://www.w3.org/TR/rdf11-concepts/) triple store where data is written and queried with [SPARQL](https://www.w3.org/TR/sparql11-query/). Like the time-series store, the SDK does not provide an abstraction layer - all interactions happen directly through functions. The semantic store provides the following operations: - [Update](./06_state-and-storage/05_semantic-store.md#update) - Insert, modify, or delete RDF triples by executing a SPARQL update - [Select](./06_state-and-storage/05_semantic-store.md#select) - Query RDF data by executing a SPARQL `SELECT` query Let us see [how to work with the semantic store in practice](./06_state-and-storage/05_semantic-store.md). ## Buffers and serialization Working with the time-series and semantic stores feels different from State, Kv, and Table - there are extra buffers to manage in the picture. The reason is that all storage operations cross a boundary between the Wasm cell and the host runtime - and that communication happens through byte buffers. The abstraction the SDK provides for state, key-value, and table storage hides that complexity and manages the buffers for you. That is also why every type stored through them must derive `Serialize` and `Deserialize` from [serde](https://serde.rs), since under the hood encoding and decoding happens at every read and write. Two things to keep in mind: 1. For state, key-value, and table storage - types used as values must derive `Serialize` and `Deserialize`. 2. For the time-series and semantic stores - make sure your buffers are large enough to hold your request and response. ## Exporting and importing data Data stored in the runtime database is persistent - but there are scenarios where you need to move it: taking a snapshot before a migration, restoring after an incident, or seeding a new environment with existing data. The Myrmic CLI provides two commands for this: - `myrmic database export` - snapshots a database scope to a destination - `myrmic database import` - restores a database scope from a source Let us look at some examples of use: 1. Export to a local file: ```bash myrmic database export my-app/my-database/my-schema --target /var/backups/snapshot ``` 2. Export to S3: ```bash myrmic database export my-app/my-database/my-schema --target s3://my-bucket/my-snapshot --region eu-west-1 ``` 3. Restore from a file: ```bash myrmic database import --source /var/backups/snapshot ``` For the full synopsis, explanation, and more examples, see [`myrmic database export`](../10_reference/02_myrmic-cli/13_database/01_export.md) and [`myrmic database import`](../10_reference/02_myrmic-cli/13_database/02_import.md). ## See also - [Cells](./01_cells.md) - introduction to the cell model - [Myrmic CLI reference](../10_reference/02_myrmic-cli.md) ## Related SDK reference - [Storage scopes](../10_reference/03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md) - [Transient state](../10_reference/03_myrmic-sdk/05_state-and-storage/02_transient-state.md) - [Persistent cell state](../10_reference/03_myrmic-sdk/05_state-and-storage/03_persistent-state.md) - [Key-value store](../10_reference/03_myrmic-sdk/05_state-and-storage/04_key-value-store.md) - [Table store](../10_reference/03_myrmic-sdk/05_state-and-storage/05_table-store.md) - [Time-series store](../10_reference/03_myrmic-sdk/05_state-and-storage/06_time-series-store.md) - [Semantic store](../10_reference/03_myrmic-sdk/05_state-and-storage/07_semantic-store.md) - [Blob store](../10_reference/03_myrmic-sdk/05_state-and-storage/08_blob-store.md) # Key-value Store `Kv` is the SDK abstraction for storing many typed values under different keys beneath one prefix. This page explains each operation in detail. ## Declare A store is declared as a handle bound to a prefix and a value type. Declare it as a module-level constant: ```rust use myrmic_sdk::db::tree::Kv; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize)] struct DeviceConfig { // ... } const CONFIGS: Kv = Kv::new("configs"); ``` This binds to the default scope - private to the cell. To use a custom scope, pass it explicitly using `new_in`: ```rust const CONFIGS: Kv = Kv::new_in("configs", Scope::public("my-app")); ``` Every key in the store is rooted at the prefix - the full stored key is `{prefix}/{key}`, for example `configs/sensor-01`. ## Write The store handle exposes a `put` method. It takes a key and a reference to the value, storing it under that key, overwriting any existing value: ```rust CONFIGS.put("sensor-01", &config)?; ``` ## Read The store handle exposes a `get` method. It returns the value stored under that key, or `None` if nothing is there: ```rust match CONFIGS.get("sensor-01")? { Some(config) => { /* use config */ } None => { /* not found */ } } ``` ## Delete The store handle exposes a `delete` method. It removes the entry under that key: ```rust CONFIGS.delete("sensor-01")?; ``` ## Iterate The store handle offers three ways to iterate over its entries. All take a `sub` parameter to control which entries are scanned (`""` for all entries, or a sub-key like `"warehouse-a/"` to narrow). 1. `for_each` - applies a closure to each entry: ```rust CONFIGS.for_each("warehouse-a/", |config| { // handle config })?; ``` Entries that fail to decode are skipped. 2. `iter` - returns a lazy iterator over the entries, surfacing load and decode errors: ```rust for config in CONFIGS.iter("warehouse-a/")? { let config = config?; // handle config } ``` 3. `list` - collects all entries into memory at once: ```rust let configs = CONFIGS.list("warehouse-a/")?; for config in configs { // handle config } ``` Prefer `for_each` or `iter` for large stores - they process entries one at a time and keep memory use low. ## Keys The store handle exposes a `keys` method. It returns all stored keys under a sub-prefix - without loading the values: ```rust let keys = CONFIGS.keys("warehouse-a/")?; for key in keys { // handle key } ``` Passing an empty string returns all keys in the store. ## See also - [How to work with state and storage](../06_state-and-storage.md#key-value-store) - back to the guide - [State](./01_state.md) - one typed value under one fixed key - [Table store](./03_table-store.md) - a named collection of typed entries ## Related SDK reference - [Storage scopes](../../10_reference/03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md) - [Key-value store](../../10_reference/03_myrmic-sdk/05_state-and-storage/04_key-value-store.md) # Semantic Store The semantic store is an [RDF](https://www.w3.org/TR/rdf11-concepts/) triple store, written and queried with [SPARQL](https://www.w3.org/TR/sparql11-query/). The SDK does not provide an abstraction layer for it - all interactions happen directly through the functions below. ## Update SPARQL updates modify the store - they can insert new data, delete existing entries, or both. The SDK provides `sem_update`. It takes a scope, a SPARQL update query, and an optional base IRI: ### Insert This example inserts three temperature sensors into the semantic store, each assigned to a zone in a building. ```rust use myrmic_sdk::db::{sem_update, Scope}; let query = r#" PREFIX ex: INSERT DATA { ex:sensor_01 a ex:TemperatureSensor ; ex:assignedTo ex:zone_a ; ex:status ex:Active . ex:sensor_02 a ex:TemperatureSensor ; ex:assignedTo ex:zone_b ; ex:status ex:Active . ex:sensor_03 a ex:TemperatureSensor ; ex:assignedTo ex:zone_a ; ex:status ex:Inactive . ex:zone_a a ex:Zone ; ex:partOf ex:building_01 . ex:zone_b a ex:Zone ; ex:partOf ex:building_01 . ex:building_01 a ex:Building . } "#; sem_update(Scope::default(), query.into(), None)?; ``` ### Delete This example removes all triples about `sensor_03` from the store. ```rust use myrmic_sdk::db::{sem_update, Scope}; let query = r#" PREFIX ex: DELETE WHERE { ex:sensor_03 ?p ?o . } "#; sem_update(Scope::default(), query.into(), None)?; ``` ## Select SPARQL SELECT queries read from the store. Querying is possible through `sem_select` - it takes a scope and a SPARQL SELECT query, with optional base IRI, limit, and skip, and returns the matching results. This example queries for active temperature sensors in `building_01`, returning each sensor and the zone it is assigned to: ```rust use myrmic_sdk::db::{sem_select, Scope}; let query = r#" PREFIX ex: SELECT ?sensor ?zone WHERE { ?sensor a ex:TemperatureSensor ; ex:status ex:Active ; ex:assignedTo ?zone . ?zone ex:partOf ex:building_01 . } "#; let response = sem_select( Scope::default(), query.into(), None, // base IRI - provide when using relative IRIs instead of PREFIX declarations Some(10), // limit None, // skip )?; for solution in response.solutions { for (variable, value) in response.variables.iter().zip(solution.iter()) { if let Some(val) = value { // variable = "sensor" or "zone" } } } ``` `sem_select` returns results as `SelectResponse`. It holds: - `variables` - the names of the selected variables - `solutions` - one row per result, values in the same order as `variables`. `None` means no value was found for that variable. For the query above, the response would look like: ```rust SelectResponse { variables: vec!["sensor", "zone"], solutions: vec![ vec![Some("http://myrmic/example/sensor_01"), Some("http://myrmic/example/zone_a")], vec![Some("http://myrmic/example/sensor_02"), Some("http://myrmic/example/zone_b")], ], } ``` Both `sem_update` and `sem_select` take an optional `base_iri` parameter - the base IRI for relative IRIs in the query. Pass `None` to skip it. See [Relative IRIs](https://www.w3.org/TR/sparql11-query/#relIRIs). ## See also - [How to work with state and storage](../06_state-and-storage.md#semantic-store) - back to the guide - [Time-series store](./04_time-series-store.md) - timestamped measurements ## Related SDK reference - [Storage scopes](../../10_reference/03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md) - [Semantic store](../../10_reference/03_myrmic-sdk/05_state-and-storage/07_semantic-store.md) # State `State` is the SDK abstraction for storing one typed value under one fixed key. This page explains each operation in detail. ## Declare State is declared as a handle bound to a key and a type. There are two ways to create one: 1. As a module-level constant at compile time - when the key is a fixed string known when writing the code: ```rust use myrmic_sdk::db::state::State; const THRESHOLD: State = State::new_const("threshold"); ``` 2. At runtime-from within a handler-when the key is dynamic and depends on information available only while the program is running: ```rust let state = State::::new(&device_id); ``` Both bind to the default scope - private to the cell. To use a custom scope, pass it explicitly using `new_const_in` or `new_in`: ```rust use myrmic_sdk::db::Scope; // Compile time - private with a custom schema const THRESHOLD: State = State::new_const_in( "threshold", Scope::private_in(Some("config")), ); // Runtime - public, shared across cells using the same scope let state = State::::new_in( &device_id, Scope::public("my-app"), ); ``` ## Write The state handle exposes a `save` method. It takes a reference to the value and writes it to the runtime database under the handle's key, overwriting any existing value. ```rust THRESHOLD.save(&30.0)?; ``` To write under a different key without declaring a separate handle, use `save_to`. It takes the key and a reference to the value: ```rust THRESHOLD.save_to("threshold-zone-a", &30.0)?; ``` ## Read The state handle exposes a `load` method. It reads the value from the runtime database and returns it, or `None` if no value has been stored yet - provide a fallback to handle that case. ```rust let value = THRESHOLD.load()?.unwrap_or(25.0); ``` To read from a different key without declaring a separate handle, use `load_from`. It takes the key and returns the value the same way: ```rust let value = THRESHOLD.load_from("threshold-zone-a")?.unwrap_or(25.0); ``` ## Modify Modifying a stored value is a read-change-write cycle. The state handle provides several methods for this, grouped by how the mutation is expressed. ### Closure A closure-based approach passes the current value by mutable reference, runs the closure on it, and saves the result back. The state handle exposes a `modify` method. It applies the closure to the stored value, saves the result, and returns the updated value - or `None` if nothing was stored: ```rust let updated = THRESHOLD.modify(|value| { *value += 1.0; })?; ``` To apply the closure on a different key, use `modify_at`: ```rust let updated = THRESHOLD.modify_at("threshold-zone-a", |value| { *value += 1.0; })?; ``` ### Guard A guard follows Rust's RAII pattern - it loads the value, lets you mutate it directly, and saves it back automatically when it is dropped. The state handle exposes a `guard` method. It returns a guard only when a value is already stored - `None` if nothing is there: ```rust if let Some(mut guard) = THRESHOLD.guard()? { *guard += 1.0; } ``` To open a guard on a different key, use `guard_at`: ```rust if let Some(mut guard) = THRESHOLD.guard_at("threshold-zone-a")? { *guard += 1.0; } ``` To always get a guard - even when nothing is stored yet - use `guard_or_default`. It falls back to the type's default when nothing is stored and then yields the guard: ```rust let mut guard = THRESHOLD.guard_or_default()?; *guard += 1.0; ``` To do the same on a different key, use `guard_or_default_at`: ```rust let mut guard = THRESHOLD.guard_or_default_at("threshold-zone-a")?; *guard += 1.0; ``` ### Upsert Upsert ensures a value is always present - it returns what is stored, or saves the type's default and returns it if nothing is there. The state handle exposes an `upsert` method: ```rust let value = THRESHOLD.upsert()?; ``` To do the same on a different key, use `upsert_at`: ```rust let value = THRESHOLD.upsert_at("threshold-zone-a")?; ``` To apply a closure before saving - starting from the type's default when nothing is stored - use `upsert_with`. It always runs the closure and returns the updated value: ```rust let value = THRESHOLD.upsert_with(|value| { *value += 1.0; })?; ``` To do the same on a different key, use `upsert_with_at`: ```rust let value = THRESHOLD.upsert_with_at("threshold-zone-a", |value| { *value += 1.0; })?; ``` ## See also - [How to work with state and storage](../06_state-and-storage.md#state) - back to the guide - [Key-value store](./02_key-value-store.md) - many typed values under different keys ## Related SDK reference - [Storage scopes](../../10_reference/03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md) - [Transient state](../../10_reference/03_myrmic-sdk/05_state-and-storage/02_transient-state.md) - [Persistent cell state](../../10_reference/03_myrmic-sdk/05_state-and-storage/03_persistent-state.md) # Table Store `Table` is the SDK abstraction for the table model - a named collection of typed entries, each identified by a key. This page explains each operation in detail. ## Declare A table is declared as a handle bound to a name and a value type. Declare it as a module-level constant: ```rust use myrmic_sdk::db::table::Table; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize)] struct Device { // ... } const DEVICES: Table = Table::new("devices"); ``` This binds to the default scope - private to the cell. To bind to a custom scope, pass it explicitly using `new_in`: ```rust const DEVICES: Table = Table::new_in("devices", Scope::public("my-app")); ``` ## Insert The table handle exposes an `insert` method. It takes a reference to the value and stores it under a runtime-assigned UUID: ```rust DEVICES.insert(&device)?; ``` To assign an explicit key, use `insert_with`: ```rust DEVICES.insert_with("sensor-01", &device)?; ``` ## Get by ID The table handle exposes a `get` method. It returns the entry stored under that key, or `None` if nothing is there: ```rust match DEVICES.get("sensor-01")? { Some(device) => { /* use device */ } None => { /* not found */ } } ``` ## Delete The table handle exposes a `delete` method. It removes the entry under that key: ```rust DEVICES.delete("sensor-01")?; ``` ## Count The table handle exposes a `count` method. It returns the number of entries in the table: ```rust let count = DEVICES.count()?; ``` ## Iterate The table offers three ways to iterate over its entries: 1. `for_each` - applies a closure to each entry in ascending key order: ```rust DEVICES.for_each(|device| { // handle device })?; ``` Entries that fail to decode are skipped. Use `for_each_rev` to iterate in descending order. 2. `iter` - returns a lazy iterator over `(key, value)` pairs, surfacing decode errors: ```rust for entry in DEVICES.iter() { let (key, device) = entry?; // handle key and device } ``` Use `iter_rev` to iterate in descending order. 3. `list` - collects all table entries into memory at once: ```rust let devices = DEVICES.list()?; for device in devices { // handle device } ``` Use `list_rev` to collect in descending order. 4. `to_map` - collects the full table into a `BTreeMap`: ```rust let map = DEVICES.to_map()?; for (key, device) in &map { // handle key and device } ``` Prefer `for_each` or `iter` for large tables - they process entries one at a time and keep memory use low. ## Keys The table handle offers two ways to access its keys: 1. `keys` - returns a lazy iterator over keys in ascending order, surfacing errors: ```rust for key in DEVICES.keys() { let key = key?; // handle key } ``` Use `keys_rev` to iterate in descending order. 2. `ids` - collects all keys into memory at once: ```rust let ids = DEVICES.ids()?; for id in ids { // handle id } ``` Prefer `keys` for large tables - `ids` loads all keys into memory at once and causes higher memory use. ## See also - [How to work with state and storage](../06_state-and-storage.md#table-store) - back to the guide - [Key-value store](./02_key-value-store.md) - many typed values under different keys - [Time-series store](./04_time-series-store.md) - timestamped measurements ## Related SDK reference - [Storage scopes](../../10_reference/03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md) - [Table store](../../10_reference/03_myrmic-sdk/05_state-and-storage/05_table-store.md) # Time-series Store The time-series store holds timestamped measurements. The SDK does not provide an abstraction layer for it - all interactions happen directly through the functions below. ## Write The SDK provides `publish_measurement`. It takes a scope and a measurement and writes it to the store: ```rust use myrmic_sdk::db::{publish_measurement, FieldValue, Measurement, Scope}; let measurement = Measurement { name: myrmic_sdk::String::from("sensor-readings"), tags: myrmic_sdk::vec![], fields: myrmic_sdk::vec![ (myrmic_sdk::String::from("temperature"), FieldValue::F64(22.5)), (myrmic_sdk::String::from("humidity"), FieldValue::F64(60.0)), (myrmic_sdk::String::from("unit"), FieldValue::String(myrmic_sdk::String::from("celsius"))), ], ts: None, // None = host timestamps it now }; publish_measurement(Scope::default(), measurement)?; ``` `Measurement` represents a time-series measurement. It carries the name, fields, tags, and timestamp. Each field is a `(name, FieldValue)` pair - `FieldValue` supports numeric, string, and boolean values. The timestamp is optional - when not set, the runtime stamps the measurement with the time it was stored. ## Query Querying is possible through `find_measurement` - it takes a scope and measurement name, and offers time range filtering, a result limit, and ordering by timestamp. It returns a list of samples: ```rust use myrmic_sdk::db::{find_measurement, FieldValue, Scope, TsOrderBy}; let mut req_buf = [0u8; 256]; let mut resp_buf = myrmic_sdk::vec![0u8; 8192]; let response = find_measurement( Scope::default(), myrmic_sdk::String::from("sensor-readings"), Some(10), // limit; None = no limit Some(1_700_000_000_000u64), // start (ms, inclusive); None = from the beginning Some(1_700_003_600_000u64), // end (ms, exclusive); None = up to now Some(TsOrderBy::TimestampDesc), // TimestampDesc (default) or TimestampAsc; None = default &mut req_buf, &mut resp_buf, )?; for sample in response.samples { let temperature = sample.fields.iter().find_map(|(k, v)| match (k.as_str(), v) { ("temperature", FieldValue::F64(f)) => Some(*f), _ => None, }); } ``` ## See also - [How to work with state and storage](../06_state-and-storage.md#time-series-store) - back to the guide - [Table store](./03_table-store.md) - a named collection of typed entries - [Semantic store](./05_semantic-store.md) - an RDF triple store queried with SPARQL ## Related SDK reference - [Storage scopes](../../10_reference/03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md) - [Time-series store](../../10_reference/03_myrmic-sdk/05_state-and-storage/06_time-series-store.md) # Licensing Myrmic is open source, and it is built so that **what you create on it stays yours**. This page explains the licensing model in plain language. It is a guide, not a legal text: the authoritative documents are the license and exception texts in the repository's [`LICENSES/`](https://github.com/peeriot/myrmic/tree/master/LICENSES) directory and the [`EXCEPTION-SCOPE.md`](https://github.com/peeriot/myrmic/blob/master/EXCEPTION-SCOPE.md) file shipped with each release. ## Three rules 1. **Your code stays your code** as long as it works with Myrmic through the official interfaces. 2. **If you change the Myrmic platform itself, share the change** — publish it under the same license, or obtain a commercial license. 3. **Obligations arise only when you distribute.** Using Myrmic internally, testing, evaluating or running it for yourself creates no disclosure duties. ## What is licensed how | Part of Myrmic | License | What it means for you | |---|---|---| | The platform: runtime, self-organization, data layer, embedded ports, firmware, host side of all interfaces | `GPL-2.0-only` together with the **Myrmic Exception** | Copyleft applies to the platform and to changes you make to it. The Exception makes sure it does not reach your applications | | SDK, interface and contract crates, signal-layer runtime support and bus shims, code generators, standard drivers and steps | `MIT OR Apache-2.0` | Compile them into your own software freely; only the usual permissive notice obligations apply | | Examples, tutorials, templates | `MIT-0` | Copy, adapt and ship without attribution | | Documentation | `CC-BY-4.0` | Reuse with attribution. Code examples in the documentation are additionally available under `MIT-0` | ## Why GPLv2 with an exception A permissive license would let anyone absorb the platform into a closed product. A plain copyleft license would reach into every application built on it. The Myrmic Exception is the middle path: the platform stays open, improvements to it flow back, and the applications, modules and pipelines you build on top are yours to license as you see fit — including proprietary. The Exception also lets Myrmic ship together with Apache-licensed components such as the WebAssembly runtimes, which the GPLv2 alone would not permit. The Exception does not restrict anything the GPLv2 allows; it only adds permissions. Because it grants additional rights and imposes no new restrictions, the combination continues to meet the Open Source Definition. ## Where to look next - **[What you can build](15_licensing/01_what-you-can-build.md)** — a decision guide: find your situation and read the verdict. - **[Contributing and the CLA](15_licensing/02_contributing-and-the-cla.md)** — how contributions work and why we ask for a Contributor License Agreement. - **[LICENSING.md](https://github.com/peeriot/myrmic/blob/master/LICENSING.md)** in the repository — the plain-language guide the project maintains next to the code. ## What you never have to do - Publish your own application code because it runs on or with Myrmic. - Ask us for permission, register, or pay a fee to use Myrmic. - Add a notice for Peeriot to code that our generators produced for you. - Accept the Contributor License Agreement just to *use* Myrmic — it is only needed to *contribute*. ## Trademarks "Myrmic", "EdgeVance" and "Peeriot" are trademarks of Peeriot GmbH. The Myrmic logo and other brand assets are not covered by the software or documentation licenses. A trademark policy describing what you can do with the name and logo will be published separately. Until then, truthful references such as "built on Myrmic" are fine; please ask before using the logo or the name for a product, domain or event. ## License of this documentation Except where otherwise indicated, the Myrmic documentation is licensed under the Creative Commons Attribution 4.0 International License (CC-BY-4.0). Code examples contained in the documentation — the code blocks on these pages — are additionally licensed under the MIT No Attribution License (MIT-0). You may use each such code example under either CC-BY-4.0 or MIT-0, at your option. These licenses do not apply to third-party material identified as such or to trademarks, logos and other brand assets, which remain subject to their respective terms. ## Questions Open a [GitHub Discussion](https://github.com/peeriot/myrmic/discussions) or write to [contact@myrmic.dev](mailto:contact@myrmic.dev). Questions about where the line runs are welcome — answering them is cheaper for everyone than a wrong assumption. # Contributing and the CLA Every contribution to Myrmic — code, documentation, tests, drivers — is welcome, from a typo fix to a new embedded port. Before we can merge your first pull request, we ask you to accept the **Contributor License Agreement (CLA)**. This page explains what it is, why we ask for it, and what it does *not* do. ## Why a CLA Myrmic is dual-licensed. The open platform is available to everyone under GPL-2.0-only together with the Myrmic Exception; Peeriot GmbH additionally offers the same code under commercial terms as part of EdgeVance. The commercial side funds the people who maintain the open one. For that model to work, Peeriot must be able to offer the whole platform — including your contribution — under both sets of terms. A plain "sign-off" (DCO) would confirm you may contribute under the GPL, but it would not allow Peeriot to include your change in the commercially licensed version. The CLA closes exactly that gap, and nothing more. ## What the CLA does - **You keep ownership.** The CLA is a license, not an assignment. Your contribution remains yours; you can use and license it elsewhere however you like. - **You grant Peeriot broad, non-exclusive rights** to use, modify, distribute, sublicense and relicense your contribution — under open-source licenses (which is how it reaches the public project) and under commercial terms. - **You confirm you are entitled to contribute:** that the work is yours, or that you have the rights needed (for example from your employer), and that you have flagged any third-party material. - **Open-source promise:** whatever Peeriot includes in the public project stays available under at least one open-source or open-content license. - **Patent grant:** you license patent claims you hold that your contribution would necessarily infringe — the same kind of grant Apache-2.0 contains — so nobody can contribute code and later sue the people using it. ## What the CLA does not do - It does not transfer copyright or moral rights. - It does not oblige you to maintain or support your contribution. - It does not touch code you write *with* Myrmic — the CLA covers contributions *to* Myrmic only. Using Myrmic never requires it. - It does not lock you in: either side can end the CLA for future contributions at any time; rights already granted for past contributions stay as they are, so the project's history remains clean. ## How it works in practice **One CLA for everyone.** The same agreement covers individuals and organizations. - **You contribute on your own behalf.** Open your first pull request; the CLA bot will comment with a link to the current text of the agreement. Read it, accept it electronically, done. Nothing to print, sign or scan. The acceptance is recorded once and applies to all your future contributions. - **You contribute on behalf of your employer or another organization.** An authorized representative of the organization accepts the CLA and designates the people who may contribute on its behalf. If you contribute solely in that capacity, you do not need to accept the CLA separately — you only accept it yourself if you also contribute in a personal capacity. - **Not sure whether your employer owns your work?** Ask before contributing. If in doubt, the organizational route is the safe one. Pull requests without an accepted CLA cannot be merged — including one-line fixes, since the rule only works if it has no exceptions. ## AI-assisted contributions You may use AI-assisted tools when preparing a contribution. You remain responsible for what you submit: review generated code as you would your own, and make sure you hold the rights the CLA asks you to confirm — in particular, do not include code of unknown provenance. If a contribution contains substantial AI-generated parts, please say so briefly in the pull request description. ## Frequently asked questions **Do I need the CLA to use Myrmic, build on it, or ship products with it?** No. It is only needed to contribute to the Myrmic repositories. **I only fixed a typo. Really?** Yes, but it takes a minute, and you only do it once. **What about the "Not a Contribution" marker?** If you share something in an issue or discussion that you do *not* want treated as a contribution — a code snippet from elsewhere, an idea you want to keep control of — mark it clearly as "Not a Contribution". It then stays outside the CLA. **Which law applies?** German law; Peeriot is a German company. Mandatory consumer-protection rules of your home country remain unaffected. **Where is the CLA text?** The CLA bot links the current version on every pull request that needs it. The text is served from one published copy, so what you read is exactly what you accept. The contribution workflow itself — branches, commits, reviews — is described in [`CONTRIBUTING.md`](https://github.com/peeriot/myrmic/blob/master/CONTRIBUTING.md) and in the [Contribution](../14_contribution.md) chapter of this handbook. # What You Can Build This guide walks you through the questions that decide what the Myrmic licenses ask of you. Find your situation, follow the letters, and read the verdict. It is a plain-language guide, not legal advice; the authoritative texts are the GNU GPL v2, the [Myrmic Exception](https://github.com/peeriot/myrmic/blob/master/LICENSES/LicenseRef-Myrmic-exception-1.0.txt) and the [`EXCEPTION-SCOPE.md`](https://github.com/peeriot/myrmic/blob/master/EXCEPTION-SCOPE.md) of the release you use. ## The short version | You want to… | Verdict | |---|---| | Use Myrmic internally, evaluate it, run it for yourself | Nothing to do. Obligations arise only when you distribute | | Ship your own Cell (WASM), pipeline or module built on the official interfaces — on a gateway, in a firmware image, as a product | **Your code stays yours.** License it as you like, including proprietary | | Ship Myrmic itself (unmodified) together with your product | Pass on the GPL obligations for the platform part: source, notices, and the unmodified `EXCEPTION-SCOPE.md` | | Change the platform and ship the result | Publish your changes under GPL-2.0-only, or obtain a commercial license | | Use the output of the Myrmic code generators | It is yours, without conditions | ## A — Are you distributing? **Distributing** means giving software to someone outside your organization: selling a device with Myrmic on it, offering a download, handing a firmware image to a customer, publishing a container image. - **No** — you run Myrmic yourself, in your own devices, your own network, your own cloud, or you are evaluating it. → **No obligations.** The GPL asks nothing of you until you distribute. This includes offering a service that runs on Myrmic without giving the software itself to your users. - **Yes** → continue with **B**. ## B — What are you distributing? - **B.1 — Unmodified Myrmic**, alone or alongside your product → go to **E**. - **B.2 — A modified Myrmic platform** (you changed code in the GPL zone: runtime, self-organization, data layer, embedded ports, firmware, host side of the interfaces) → **the GPL applies to your changes.** When you distribute, make the source of your modifications available under GPL-2.0-only, or obtain a commercial license. You may extend the Myrmic Exception to your changes or not — that is your choice (Exception, Section 5); if you do not, remove or qualify notices that would suggest it applies. Then also go to **E** for the notices. - **B.3 — Your own application** — a Cell, a signal-layer module, a pipeline, a driver — that works *with* Myrmic → continue with **C**. ## C — Does your application talk to Myrmic only through the official interfaces? The official interfaces are the WASM host interface, the signal-layer IPC protocol and the signal-layer module contract, each defined in the `EXCEPTION-SCOPE.md` of your release. **What must stay unmodified is the interface itself** — the host functions, the protocol, the contract as defined there. The SDK crates that implement them (`myrmic-sdk`, `signal-layer-core`, `signal-layer-ipc`, …) are libraries: use them as published, patch them, or replace them with your own bindings, as long as what crosses the boundary is the unmodified official interface. - **Yes** — your code interacts with the platform only through those interfaces and does not copy, modify or incorporate platform code → continue with **D**. - **No, I changed an interface itself or the runtime** to add functionality my application needs → the interface change is a platform modification; treat it under **B.2**. Your application itself is only covered by the Exception if it uses the unmodified official interfaces. If you have forked Myrmic and extended its interfaces, Peeriot's additional permissions do not automatically cover applications written against your extended interfaces. You can grant your own permissions for your changes — but you cannot enlarge Peeriot's Exception (Section 5.3). *In doubt: propose the interface change upstream so it becomes official in the next release.* - **No, my code reaches into internal APIs or copies platform code** → it is a derivative of the platform; see **B.2**. ## D — How is your application combined with Myrmic? All four forms are expressly permitted by the Myrmic Exception. Your application may be licensed under terms of your choice, including proprietary. - **D.1 — A WASM Cell**, compiled with the SDK, loaded dynamically on an operating-system-based device or AOT-compiled and embedded in a firmware image. → **Yours.** The SDK crates inside your module stay MIT/Apache-2.0 and carry the usual notice obligations. - **D.2 — A firmware image** in which your modules (drivers, steps) are statically linked with the platform. → **Yours.** Building and distributing the combined image is what the Exception is for. For the platform part inside the image, go to **E**. - **D.3 — A generated pipeline program** running as its own process on a Linux device and talking to the platform over IPC. → **Yours.** The generated program consists of your code plus permissive crates; the generator output is yours without conditions. - **D.4 — A plugin loaded into a platform process**, communicating only through an official interface. → **Yours.** Then continue with **E** if you ship the platform along with your application; otherwise you are done. ## E — You ship the platform: what to pass on When you distribute Myrmic platform code — unmodified or modified, alone or inside a firmware image or container — the GPL-2.0-only obligations apply **to the platform part**: 1. **Source code for the platform part** — either included, or a written offer, or (for unmodified releases) a pointer to the exact upstream release. Your own application's source is *not* affected when **C** and **D** apply. 2. **The license texts** — GPL-2.0-only and the Myrmic Exception, as shipped in the release's `LICENSES/` directory. 3. **The unmodified `EXCEPTION-SCOPE.md`** of the release you rely on. Passing it on unchanged is the one condition the Exception attaches to using its permissions. 4. **Existing copyright and license notices** stay in place, including the third-party notices in `NOTICE`. The exception does not require you to publish anything about *your* application, and it does not require you to add attribution to Peeriot in your product beyond keeping the notices. ## F — Third-party components in the same image Combining Myrmic with third-party software is covered in two ways: - Components under an **Approved License** (Apache-2.0, MIT, BSD, MPL-2.0, EPL-2.0 and the others listed in `EXCEPTION-SCOPE.md`) may be combined and distributed with the platform; each keeps its own license. - **Operating-system and hardware-access components** — kernels, libc, drivers, bus and radio libraries used through their documented interface — are Support Components and are covered likewise. For anything else, especially components under licenses not on the list, check compatibility with GPL-2.0-only or ask us; we can add licenses to the list for a release, and additions apply retroactively to that release. ## Worked examples **A start-up ships an ESP32 sensor node with a proprietary filtering step.** The step implements the unmodified signal-layer module contract (the traits and types listed in the release's `EXCEPTION-SCOPE.md`) and is linked into one firmware image with the platform. → **C** yes, **D.2**: the step stays proprietary. **E**: the firmware ships with the platform source (or a pointer to the Myrmic release), the license texts and the release's `EXCEPTION-SCOPE.md`. **An integrator installs Myrmic on an industrial gateway and adds a closed Cell for a customer.** → **D.1**: the Cell is theirs. The unmodified Myrmic on the gateway falls under **B.1/E**; pointing to the upstream release and keeping the notices satisfies it. **A company changes the runtime's scheduling to fit its workload and sells devices with the result.** → **B.2**: the scheduling change is a platform modification. Publish the change under GPL-2.0-only (ideally as an upstream pull request) or obtain a commercial license. **A hobbyist forks Myrmic, adds a new host function and writes Cells against it.** → **C** no: the new host function is a platform modification (**B.2**, GPL applies if distributed), and the fork's extended interface is not an official interface. The fork author may extend the Exception to their own changes but cannot widen Peeriot's Exception to the new interface. The clean route: propose the host function upstream. **A team generates a Linux pipeline project with `linux-codegen` and sells it as part of a closed product.** → Generator output is theirs (Exception, Section 4), the generated program is **D.3**; only the MIT/Apache-2.0 notices of the crates it uses need to travel with it. ## Still unsure? Describe your setup in a [GitHub Discussion](https://github.com/peeriot/myrmic/discussions) or write to [contact@myrmic.dev](mailto:contact@myrmic.dev). Where a real gap shows up, we would rather widen the `EXCEPTION-SCOPE.md` than have you guess. --- hide_table_of_contents: true --- import { DocCards } from '@site/src/components/DocCards/DocCards'; # Overview Myrmic is an open source edge-native runtime for building and operating distributed applications across fleets of devices. It runs application logic as WebAssembly cells - portable, isolated units that deploy and self-organize across embedded and server targets without a separate orchestrator, broker, or manual wiring. The project is developed and maintained by [Peeriot](https://peeriot.io/). export const cards = [ { title: 'Try Myrmic', description: 'Get started with Myrmic and follow step-by-step tutorials covering basic applications and embedded targets.', links: [ { label: 'Quickstart', to: '/docs/quickstart' }, { label: 'Smart Greenhouse', to: '/docs/tutorials/smart-greenhouse' }, { label: 'First Steps on an ESP32', to: '/docs/tutorials/first-steps-embedded' }, { label: 'First Steps with the Signal Layer', to: '/docs/tutorials/first-steps-signal-layer' }, { label: 'Resilient Cells', to: '/docs/tutorials/resilience' }, { label: 'Scaling Your Application', to: '/docs/tutorials/scaling' }, { label: 'Observability', to: '/docs/tutorials/observability' }, ], viewAll: '/docs/tutorials', viewAllLabel: 'View Tutorials', }, { title: 'Why Myrmic', description: 'Learn about the thinking behind Myrmic - the problem it solves and how to think about it.', links: [ { label: 'Rethinking the stack', to: '/docs/why-myrmic/rethinking-the-stack' }, { label: 'Understanding Myrmic', to: '/docs/why-myrmic/understanding-myrmic' }, { label: 'Modelling applications', to: '/docs/why-myrmic/modelling-applications' }, { label: 'Connecting physical systems', to: '/docs/why-myrmic/connecting-physical-systems' }, { label: 'Operating Myrmic', to: '/docs/why-myrmic/operating-myrmic' }, ], viewAll: '/docs/why-myrmic', }, { title: 'Core Concepts', description: 'The vocabulary that carries the Myrmic model - Cells, Nodes, Messages, and more.', links: [ { label: 'Applications, Cells, and Identity', to: '/docs/concepts/applications-cells-and-identity' }, { label: 'Nodes, Capabilities, and the Swarm', to: '/docs/concepts/nodes-capabilities-and-the-swarm' }, { label: 'Messages and Mailboxes', to: '/docs/concepts/messages-and-mailboxes' }, { label: 'Handlers, State, and Transactions', to: '/docs/concepts/handlers-state-and-transactions' }, { label: 'Where Data Lives', to: '/docs/concepts/where-data-lives' }, { label: 'Recovery Models', to: '/docs/concepts/recovery-models' }, { label: 'Cell Patterns', to: '/docs/concepts/cell-patterns' }, ], viewAll: '/docs/concepts', }, { title: 'Guides', description: 'Look up common Myrmic concepts and features and learn how to use them through a short sequence of steps.', links: [ { label: 'Cells', to: '/docs/guides/cells' }, { label: 'Commands', to: '/docs/guides/commands' }, { label: 'Events', to: '/docs/guides/events' }, { label: 'Message Encoding', to: '/docs/guides/message-encoding' }, { label: 'Scheduling Handlers', to: '/docs/guides/scheduling-handlers' }, { label: 'State and storage', to: '/docs/guides/state-and-storage' }, { label: 'Operating a Swarm', to: '/docs/guides/operating-a-swarm' }, { label: 'Observability', to: '/docs/guides/observability' }, { label: 'Signal layer', to: '/docs/guides/signal-layer' }, { label: 'BLE', to: '/docs/guides/ble' }, ], viewAll: '/docs/guides', }, { title: 'Architecture', description: 'How Myrmic actually works, explained through four views and the six canonical layers.', links: [ { label: 'The Swarm View', to: '/docs/architecture/the-swarm-view' }, { label: 'The Node View', to: '/docs/architecture/the-node-view' }, { label: 'The Cell View', to: '/docs/architecture/the-cell-view' }, { label: 'Failure Behaviour', to: '/docs/architecture/failure-behaviour' }, { label: 'The Six Layers', to: '/docs/architecture/the-six-layers' }, ], viewAll: '/docs/architecture', }, { title: 'Application Domains', description: 'What can I use Myrmic for?', links: [ { label: 'Asset-centric software', to: '/docs/target-groups/asset-centric-software' }, { label: 'Connected products', to: '/docs/target-groups/connected-products' }, { label: 'Real-time applications', to: '/docs/target-groups/real-time-applications' }, { label: 'Workflows and agents', to: '/docs/target-groups/workflows-and-agents' }, { label: 'Platform engineering', to: '/docs/target-groups/platform-engineering' }, ], viewAll: '/docs/target-groups', viewAllLabel: 'View Application Domains', }, { title: 'Reference', description: 'CLI, SDK, and architecture reference documentation.', links: [ { label: 'Myrmic CLI', to: '/docs/reference/myrmic-cli' }, { label: 'Myrmic SDK', to: '/docs/reference/myrmic-sdk' }, { label: 'Runtime configuration', to: '/docs/reference/configuration/runtime-configuration' }, { label: 'Cell and application configuration', to: '/docs/reference/configuration/cell-and-application-configuration' }, { label: 'Bridge configuration', to: '/docs/reference/configuration/bridge-configuration' }, { label: 'Signal Layer', to: '/docs/reference/signal-layer' }, ], viewAll: '/docs/reference', }, { title: 'Community', description: 'Join the conversation, contribute, and get support.', links: [ { label: 'Community and Support', to: '/docs/community' }, { label: 'Contributing', to: '/docs/contribution' }, { label: 'Security', to: '/docs/security' }, ], viewAll: '/docs/community', }, ]; # Quickstarts Myrmic offers a new approach for building distributed edge applications. Instead of building application logic and worrying about connectivity - placement - database - observability - Myrmic handles that. You write application logic as cells: small, self-contained Rust programs that compile to WebAssembly and run on Myrmic runtimes across your device swarm. The focus shifts from infrastructure to logic. To deliver that, Myrmic provides developers with three things: - **Myrmic Runtime** - the process you start on a device. It connects to other runtimes in the network peer-to-peer to form a swarm. It runs cells, decides where they are placed in the swarm, routes messages between them, provides a distributed database to store their data, and collects telemetry across the swarm. - **Myrmic SDK** - a full toolkit to build Myrmic cells and applications from the ground up. It provides macros to define cells and their interfaces, and utilities to communicate between them, interact with the runtime database, schedule tasks, access hardware on embedded targets, and logging. - **Myrmic CLI** - the command-line interface tool for developers to create, build, and deploy cells, interact with them, manage Myrmic runtimes, and observe the swarm - in development and production. ## Supported Targets Myrmic Runtime runs on Linux-based systems and a growing set of embedded targets. The following table lists currently supported targets: | Target | Architecture | Embedded Wasm Engine | |---|---|---| | Linux | x86_64 / aarch64 | Wasmtime (JIT) | | ESP32-C5 | RISC-V (rv32imac) | WAMR (AOT) | | ESP32-C6 | RISC-V (rv32imac) | WAMR (AOT) | | ESP32-C61 | RISC-V (rv32imac) | WAMR (AOT) | ## Installation (Linux) To work with Myrmic, you only need to install the Myrmic CLI. The Myrmic SDK is a Rust dependency you add to your cell code. The Myrmic Runtime is managed by the CLI - no separate installation needed. See [Installation](./01_quickstart/01_installation.md) for the system packages you need, installing from a release package on x86_64 and arm64, building from source, and what Myrmic writes to your machine. For embedded targets - building and flashing firmware for ESP32 boards - see [Installation (Embedded)](./01_quickstart/02_installation-embedded.md). ### Verify Installation Confirm the installation succeeded: ```bash myrmic --version ``` ## Your First Cell In this section you will build your first cell and deploy it to a local runtime, then interact with the cell from the CLI. ### 1. Create a new Cell. Create a working directory and navigate into it: ```bash mkdir myrmic-quickstart && cd myrmic-quickstart ``` If you built the CLI from source, create this outside the cloned repository. A cell created inside the myrmic checkout is captured by its Cargo workspace and fails to build with `current package believes it's in a workspace when it's not`. Cells inside your own app workspace are fine (see [Cells](./05_guides/01_cells.md)). Then scaffold the cell, run: ```bash myrmic new counter ``` Expected output: ```text INFO Creating 'counter' ``` This command creates a minimal cell as a Rust crate, using a built-in template to quickly get started and remove the complexity of manual setup. The resulting layout looks like this: ```text counter/ Cargo.toml -- crate named "counter"; depends on myrmic-sdk and serde .gitignore src/ lib.rs -- the Cell code lives here ``` ### 2. Inspect the generated Cell. Open `counter/Cargo.toml`. It looks like this: ```toml [package] name = "counter" version = "0.1.0" edition = "2024" publish = false [package.metadata.myrmic] heap_size = 32_768 [dependencies] myrmic-sdk = "x.x.x" serde = { version = "1", default-features = false, features = ["alloc", "derive"] } ``` Most of that is self explaining except: `heap_size` - sets how much memory this Cell gets: 32 KB, baked into the Wasm binary at build time. See [Cell and application configuration](./10_reference/01_configuration/02_cell-and-application-configuration.md) to understand more. Now open `counter/src/lib.rs`. This is the starter Cell code that was generated: ```rust #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Callback, JsonValue, Metadata}; const STATE: State = State::new_const("my-key"); #[myrmic_sdk::init] fn init(md: Metadata) -> myrmic_sdk::Result { let _ = myrmic_sdk::info!("starting (id={:?})", md.id).ok(); Ok(()) } #[myrmic_sdk::cmd] fn count(md: Metadata, callback: Option>) -> myrmic_sdk::Result { let value = STATE.load()?.unwrap_or_default(); // `myrmic send` carries no callback, and a nil sender that could not be // answered even if it did. if let Some(callback) = callback && !md.sender.is_nil() { let _ = myrmic_sdk::info!("Returning count {} to (sender={:?})", value, md.sender).ok(); callback.invoke(md.sender, &JsonValue::from(value))?; } else { let _ = myrmic_sdk::info!("Count is {} (no caller to answer)", value).ok(); } Ok(()) } #[myrmic_sdk::cmd] fn increment(md: Metadata) -> myrmic_sdk::Result { let count = STATE.upsert_with(|count| { *count = *count + 1; })?; let _ = myrmic_sdk::info!("Incremented count to {} (sender={:?})", count, md.sender).ok(); Ok(()) } #[myrmic_sdk::cmd] fn decrement(md: Metadata) -> myrmic_sdk::Result { let count = STATE.upsert_with(|count| { *count = *count - 1; })?; let _ = myrmic_sdk::info!("Decremented count to {} (sender={:?})", count, md.sender).ok(); Ok(()) } ``` A few things to note about the code: - `#![no_std]` - since Myrmic cells are meant to run on any target - including bare-metal devices where the standard library is not available - cells are built without it. The SDK provides what you need in its place. - `State` - persistent state stored in the runtime database. - `#[myrmic_sdk::init]` - marks the init function. Runs once per deployment of the Cell, before it handles anything else - so redeploying runs it again. - `#[myrmic_sdk::cmd]` - marks a function as a command handler. Myrmic cells are event-driven: they sit idle until a message arrives. Messages are either commands - a request directed at a cell to perform an action - or events. A function marked with this macro is invoked whenever the Cell receives its matching command. Events are not covered here - see the tutorials or the dedicated guide. - `Metadata` - holds the invocation context. It is passed to every handler and provides information such as the identity of the current cell and the identity of the sender. This cell exposes three commands: - `count` - answers the caller with the current count when one sent a callback, and logs it otherwise. - `increment` - increments the count by 1 and logs the result. - `decrement` - decrements the count by 1 and logs the result. ### 3. Build the Cell. Run from the `myrmic-quickstart/` folder: ```bash myrmic build counter ``` Expected output: ```text INFO Attempting to build: .../counter Compiling counter v0.1.0 (.../counter) Finished release [optimized] target(s) in Xs ``` This compiles the Cell to WebAssembly. The binary `counter.wasm` is placed in `counter/target/wasm32v1-none/release/`. ### 4. Start a local runtime. The runtime must be running before you can deploy. Start it in a separate terminal and leave it running for the rest of the steps. ```bash myrmic runtimes start ``` It logs some startup detail and then a readiness line once it is serving: ```text INFO runtime "default" ready () ``` On the first start you may also see one or two `WARN` lines about missing prior state - these are normal and can be ignored. Verify the runtime is running from your original terminal: ```bash myrmic runtimes list ``` Expected output: ```text default running pid= ``` This means that we have a local Myrmic runtime running on the machine. You can also see the swarm from the network's side: ```bash myrmic network status ``` Runtimes that can reach each other on the network automatically join one swarm, with no explicit join step, and cell names (SRNs) are shared across it, so the same name is the same cell on every node. On a single machine that swarm is just this runtime. See [Operating a swarm](./05_guides/09_operating-a-swarm.md) for what this means once more machines are involved. Finally, tell the runtime to keep telemetry. By default a runtime only prints its logs to its own stdout; nothing is stored in the telemetry database that `myrmic telemetry logs` reads until a retention period is set. Run this once - it applies to all connected runtimes immediately and only affects records emitted afterwards: ```bash myrmic telemetry set-db-retention "1h" ``` Expected output: ```text INFO DB retention set to '1h' on all connected nodes ``` Retention lives in the running process. If you restart the runtime you have to set it again, or put `db_retention: "1h"` under a top-level `telemetry:` key in a runtime configuration file - see [Runtime configuration](./10_reference/01_configuration/01_runtime-configuration.md). ### 5. Deploy to the runtime. `myrmic deploy` builds and deploys the cell in one step. ```bash myrmic deploy counter ``` Expected output: ```text INFO deploying cell (srn = counter, sri = ) INFO deployed cell (srn = counter, sri = ) ``` Each cell has two identifiers: an `srn` (Stable Resource Name) - the human-readable name - and an `sri` (Stable Resource Identifier) - a unique identifier used internally by the runtime. The srn is derived from the crate name by default and the sri is derived deterministically from it. The cell is reachable by either. To use a different SRN, pass `--name`: ```bash myrmic deploy counter --name other-name ``` ### 6. Check what is running. Lists all Cells deployed to the runtime. ```bash myrmic cells ``` Expected output: ```text cell sri kind runtime age policy class srn ──── counter ─────────────────────────────────────────────────────────────────────────────────── counter xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx wasm [x]xxxxxxx 0s never counter counter ``` In a terminal this is a live view: it redraws every couple of seconds until you press Ctrl-C. Use `myrmic cells --once` for a single listing - which is also what you get when the output is piped or redirected. `counter` is deployed on the local runtime, which the `runtime` column shows by id, and waiting for commands. ### 7. Call the commands. `myrmic send` sends a command to a cell - it takes the cell identifier and the command name. Call `increment` three times, then ask for the count: ```bash myrmic send counter increment myrmic send counter increment myrmic send counter increment myrmic send counter count ``` `count` answers its caller with a callback when a cell sent one. A send from the terminal carries no callback and nobody to answer, so the cell logs the value instead - which is what the next step looks at. ### 8. Check the logs. The cell logs its state after every command. Check what happened: ```bash myrmic telemetry logs ``` Look for these lines in the output: ```text Incremented count to 1 (sender=...) Incremented count to 2 (sender=...) Incremented count to 3 (sender=...) Count is 3 (no caller to answer) ``` If the output is empty, retention was not set before the commands were sent (see step 4). Set it and send a few more `increment` commands. To confirm the cell itself logged, print the runtime's own log instead - it is written regardless of retention: ```bash myrmic runtimes default logs ``` ### 9. Remove the Cell. ```bash myrmic delete counter ``` Removes the Cell from the runtime. In a terminal this asks which of the cell, its app or its descendants to remove; run non-interactively (a script or a pipe) it will not prompt and needs the choice as a flag - here, `myrmic delete counter --cell`. Expected output: ```text INFO undeployed cell 'counter' (sri xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) ``` Verify it is gone: ```bash myrmic cells ``` Expected output: ```text No cells registered ``` ### 10. Stop the runtime when you are done. ```bash myrmic runtimes stop ``` (`stop` is an alias; `myrmic runtimes --help` lists the command as `delete`.) Expected output: ```text INFO sent SIGTERM to runtime "default" (pid ) ``` ## Getting Help At any point, if you get stuck, you can always get help on [Discord](https://discord.gg/zExh79pWgj) or [GitHub Discussions](https://github.com/peeriot/myrmic/discussions). No question is too small - the community is here for all of them. ## Next Steps - [Tutorials](./04_tutorials.md) - hands-on walkthroughs to go further. - [Guides](./05_guides.md) - learn individual Myrmic features and concepts. # Installation This page installs the **Myrmic CLI** on Linux. The CLI is the only thing you install by hand: - The **Myrmic Runtime** is managed by the CLI - `myrmic runtimes start` brings one up, there is nothing separate to install. - The **Myrmic SDK** is a Rust dependency of your cell crate - `myrmic new` puts it into the generated `Cargo.toml`. On x86_64 and arm64 (64-bit, including a Raspberry Pi on a 64-bit OS) the release package is the shortest path. On any other architecture, [build from source](#install-from-source). ## Prerequisites On a fresh Debian or Ubuntu image, run `sudo apt update` once before the first `apt install` on this page. The commands on this page use `curl`. Most images ship it already - check with `curl -V`. If yours does not: `sudo apt install curl` on Debian and Ubuntu, `sudo dnf install curl` on RHEL, AlmaLinux and Fedora. ### To build cells You need all of these whether you installed the CLI from a package or built it yourself. - **Rust**, via [rustup](https://rustup.rs/): ```sh curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` The installer does not touch the shell it runs in, so make `rustup` available in the current one before you go on (a new shell picks it up by itself): ```sh source "$HOME/.cargo/env" ``` - **The pinned stable toolchain and the `wasm32v1-none` target** are installed for you on the first build. A cell scaffolded by `myrmic new`, on its first `myrmic build`, ships a `rust-toolchain.toml` that prompts `rustup` to auto-install the right toolchain and target. The pinned version is not a technical floor; it is the release tested for the current Myrmic release, and it moves forward with each release. To install these ahead of that first build - on an offline machine, or just to keep the build output quiet - the steps are optional: ```sh rustup toolchain install 1.98.1 rustup target add wasm32v1-none --toolchain 1.98.1 ``` - **A C toolchain.** A cell compiles to WebAssembly, but cargo still compiles and links every dependency's build script as a native binary for your machine. rustup ships no linker, so without one `myrmic build` stops before it starts the build, with `no C linker found`. | Distribution family | Install | |---|---| | Debian, Ubuntu | `sudo apt install build-essential` | | RHEL, AlmaLinux, Fedora | `sudo dnf install gcc` | ### Additionally, to build the CLI from source | Distribution family | Install | |---|---| | Debian, Ubuntu | `sudo apt install cmake git` | | RHEL, AlmaLinux, Fedora | `sudo dnf install cmake git` | `git` clones the repository, and the build shells out to it for the source revision it stamps into the binary. `cmake` is used by a C dependency of the CLI binary. Both package lists above are derived from Myrmic's dependency tree and from installs observed on a handful of images. They are not a minimal set - if your machine already has a working C compiler, `cmake` and `git`, however they got there, that works too. ### Build resources These are lab measurements on small cloud instances, not guaranteed minimums - they move with your CPU, disk and how busy the machine is. - **A cell build takes seconds.** Once the C toolchain is present, `myrmic build` was 9 to 10 seconds on 2 to 4 vCPU, and up to around 30 seconds on a busier host. The first build in a fresh crate also compiles the cell's dependencies, so it is the slow one; later builds are quicker. - **Building the CLI from source is the heavy step**, and wants a few GB of both RAM and disk. On 8 vCPU running alone it took about three and a half minutes, roughly 2 GB peak resident memory and 2.6 GB left in `target/`. On a contended host it takes proportionally longer - around 9 to 10 minutes when three builds shared a 16-thread machine. ## Install from a release package Packages are published on the [releases page](https://github.com/peeriot/myrmic/releases) under the tag `myrmic/v`. Each release carries: | Asset | What it is | |---|---| | `myrmic-cli__.deb` | the CLI; `` is `amd64` (x86_64) or `arm64` (aarch64) | | `myrmic-cli-dbgsym__.deb` | its debug symbols | | four `.rpm` files, two per architecture | the same CLI and its debug symbols, converted from the `.deb`; the converter picks their names, so read them off `SHA256SUMS` | | `myrmic-cli__sbom.spdx.json`, `myrmic-cli__sbom.cdx.json` | the dependency inventory of the build | | `SHA256SUMS` | checksums for every asset above | The package name is `myrmic-cli` and the binary it installs is `/usr/bin/myrmic`. It also puts `NOTICE` and the licence texts under `/usr/share/doc/myrmic-cli/`, where the packaging tool adds a copyright file of its own. There is no systemd unit, no man page and no shell completion - `dpkg -L myrmic-cli` lists the full payload. ### Download The assets hang off the release tag, so the tag is part of the URL. Start with `SHA256SUMS`: it lists every asset of the release by name, which is also how you learn what the RPMs are called - the converter picks those names, nothing in the pipeline records them. Replace `` with the release you want: ```bash version='' base=https://github.com/peeriot/myrmic/releases/download/myrmic/v$version curl -fLO "$base/SHA256SUMS" cat SHA256SUMS ``` `-f` matters: without it curl saves GitHub's 404 page under the asset's name and still exits 0, so a typo in `$version` gets you a `SHA256SUMS` that reads `Not Found`. With it, curl prints the error and exits non-zero. Then fetch the package you want from the same place: Debian, Ubuntu: ```bash arch="$(dpkg --print-architecture)" curl -fLO "$base/myrmic-cli_${version}_${arch}.deb" ``` RHEL, AlmaLinux, Fedora: ```bash curl -fLO "$base/" ``` ### Verify the download With the package and `SHA256SUMS` in the same directory: ```bash sha256sum --ignore-missing -c SHA256SUMS ``` `SHA256SUMS` lists every asset of the release. Without `--ignore-missing`, `sha256sum` prints `FAILED open or read` for each asset you did not download, and exits non-zero. ### Install Debian, Ubuntu: ```bash sudo apt install "./myrmic-cli_${version}_${arch}.deb" ``` RHEL, AlmaLinux, Fedora: ```bash sudo dnf install "./" ``` The `.deb` line reuses the `$version` and `$arch` you set above. For the RPM, pass the name you read off `SHA256SUMS`. If you would rather not type it out, a glob covers the release suffix the converter picked: ```bash sudo dnf install "./myrmic-cli-${version}"-*."$(uname -m)".rpm ``` ### Distributions The `.deb` declares `libc6 (>= 2.17)` on both architectures, and the release pipeline checks the binary against that floor before anything is published, so the floor cannot drift. glibc 2.17 is the oldest glibc Rust itself supports, so every distribution the commands on this page work on meets it - Debian 9 or newer, Ubuntu 16.04 or newer, RHEL 8 or newer, and every 64-bit Raspberry Pi OS. The package you downloaded states it too: ```bash dpkg-deb -f "myrmic-cli_${version}_${arch}.deb" Depends ``` Installing the package has been observed to work on Ubuntu 22.04 and 24.04, Debian 12, and AlmaLinux 9 and 10. Other distributions that meet the floor should work as well, but have not been checked. Below the floor, `apt` refuses the `.deb` with a `libc6` dependency error naming the version your system has. The RPMs carry the same floor as per-symbol requirements such as `libc.so.6(GLIBC_2.17)(64bit)`, so `dnf` refuses them below it as well; `rpm -qp --requires .rpm` shows them. Below the floor, build from source. ### 32-bit ARM No package is published for 32-bit ARM (armhf, for example a 32-bit Raspberry Pi OS). There, build from source. ## Install from source Install the C toolchain and the two extra packages from [Prerequisites](#prerequisites) first, then: ```bash git clone https://github.com/peeriot/myrmic.git cd myrmic cargo build --release --bin myrmic ``` The binary is at `target/release/myrmic`. Put it on your `PATH`, or install it directly: ```bash cargo install --path swarm/myrmic-cli/ ``` To export logs, traces and metrics to tools such as Grafana or Jaeger over OTLP, add `--features open-telemetry` to either command. See the [Observability tutorial](../04_tutorials/07_observability.md). ### With BLE support To run cells that talk to Bluetooth Low Energy peripherals, the CLI has to be built with its `ble` feature. The release packages are built without it, so BLE support on Linux requires building from source. It links against the system D-Bus library to reach the BlueZ stack, so install its development headers first: | Distribution family | Install | |---|---| | Debian, Ubuntu | `sudo apt install libdbus-1-dev` | | RHEL, AlmaLinux, Fedora | `sudo dnf install dbus-devel` | Then install the CLI with the feature: ```bash cargo install --path swarm/myrmic-cli/ --features ble ``` Without the feature, BLE support is compiled out of the runtime, so it does not advertise `ble` and cannot serve BLE cells. See [Work with BLE peripherals](../05_guides/12_ble.md) for how a cell uses BLE. ## Verify the installation ```bash myrmic --version ``` ## What Myrmic writes to your machine | Location | Contents | |---|---| | `~/.local/share/myrmic/` | runtime identities in `runtimes/.yaml`, and one directory per runtime holding its database (`/db`) and its rotating logs (`/logs/runtime..log`, rotated daily, 7 kept) | | `$XDG_RUNTIME_DIR/myrmic/` | the PID file of each running runtime | Those are the persistent locations at their defaults. A runtime can be given a database directory and a log directory of its own, and `myrmic runtimes start --tmp` keeps the database in memory instead. `$XDG_DATA_HOME` overrides the data directory when it is set. When `$XDG_RUNTIME_DIR` is not set - which is common for a process started by systemd - PID files go to `$TMPDIR/myrmic-/`, which is `/tmp/myrmic-/` unless `$TMPDIR` says otherwise. `` is `$USER`, or `$LOGNAME` if that is unset - and if neither is set, the directory is just `myrmic`. Builds and deploys also unpack scratch directories under `$TMPDIR` (`myrmic-nest-/`, `myrmic-spawn-/`), and a runtime using the signal layer opens a socket at `/run/peeriot/signal-layer.sock` or `$XDG_RUNTIME_DIR/peeriot-signal-layer.sock`. ## Uninstall If a runtime is running, stop it first - with nothing running the command exits with an error, which is harmless here: ```bash myrmic runtimes stop ``` Remove the CLI: ```bash sudo apt remove myrmic-cli # Debian, Ubuntu sudo dnf remove myrmic-cli # RHEL, AlmaLinux, Fedora ``` If you installed it with `cargo install`: ```bash cargo uninstall myrmic-cli ``` Neither removes what Myrmic wrote to your machine. To remove that as well: ```bash [ -n "${XDG_DATA_HOME:-$HOME}" ] && rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/myrmic" [ -n "$XDG_RUNTIME_DIR" ] && rm -rf "$XDG_RUNTIME_DIR/myrmic" rm -rf "${TMPDIR:-/tmp}/myrmic-${USER:-$LOGNAME}" "${TMPDIR:-/tmp}/myrmic" ``` The first line deletes the runtime database - everything your cells stored is in there. The last two cover both PID locations. The guards on the first two lines matter, because an unguarded version of either deletes a root-anchored path when its variables are unset: `rm -rf "$XDG_RUNTIME_DIR/myrmic"` reads as `/myrmic`, and `rm -rf "${XDG_DATA_HOME:-$HOME/.local/share}/myrmic"` reads as `/.local/share/myrmic` when neither `$XDG_DATA_HOME` nor `$HOME` is set. ## Next [Quickstart](../01_quickstart.md) - build, deploy and call your first cell. --- sidebar_label: Installation (Embedded) --- # Installation (Embedded) This page adds what you need to work with ESP32 boards: building and flashing Myrmic **firmware**, and compiling your own **cells** for the board. Firmware is a native RISC-V binary - a Node that runs on the bare-metal chip and joins the swarm - so unlike a cell it is not compiled to WebAssembly. You build it with `myrmic build` and write it to a board with `myrmic flash`. Cells stay WebAssembly, but to run on the device they are ahead-of-time compiled to native RISC-V with `wamrc`; that tool is the one piece you build by hand, covered under [wamrc](#wamrc-the-cell-aot-compiler) below. Everything on the [Installation](./01_installation.md) page comes first: the **Myrmic CLI**, Rust via rustup, and the C toolchain. This page assumes the CLI is already on your `PATH` (`myrmic --version` works) and only covers the extra pieces the embedded target needs. ## Supported chips | Chip | Architecture | Wasm engine | Connects over | |---|---|---|---| | ESP32-C5 | RISC-V (rv32imac) | WAMR (AOT) | native USB-Serial-JTAG | | ESP32-C6 | RISC-V (rv32imac) | WAMR (AOT) | native USB-Serial-JTAG | | ESP32-C61 | RISC-V (rv32imac) | WAMR (AOT) | native USB-Serial-JTAG | All three connect over their native USB-Serial-JTAG: plug the board's **USB** port into your machine and it enumerates as a USB CDC-ACM device, `/dev/ttyACM*` on Linux. Many devkits also carry a second, **UART** port through an onboard USB-to-UART bridge, which comes up as `/dev/ttyUSB*`. Either port can flash the board; the examples here use the USB port (`/dev/ttyACM*`). ## Prerequisites On a fresh Debian or Ubuntu image, run `sudo apt update` once before the first `sudo apt install` on this page. ### Clang, for the embedded Wasm runtime The firmware embeds the WAMR WebAssembly runtime, whose C sources are cross-compiled to the chip's RISC-V target as part of the build. That step uses **clang** - the C compiler the build invokes for the bare-metal target, since a host `gcc` cannot cross-compile to `riscv32imac` - and **libclang**, which the binding generator loads at build time. Without them the first `myrmic build` stops with `failed to find tool "clang"`. | Distribution family | Install | |---|---| | Debian, Ubuntu | `sudo apt install clang libclang-dev` | | RHEL, AlmaLinux, Fedora | `sudo dnf install clang clang-devel` | `clang` and `libclang-dev` are LLVM components, and `libclang-dev` pulls in the LLVM runtime it needs; the heavier `llvm-dev` package (with `llvm-config` and the LLVM static libraries) is **not** required for the firmware - it is only needed to build [wamrc](#wamrc-the-cell-aot-compiler) later. The host C toolchain from the [Installation](./01_installation.md) page (`build-essential`) is still required as well; it compiles the build scripts that run on your machine. `cmake`, `pkg-config`, `libudev-dev` and a separate RISC-V GCC are **not** needed - the firmware links with the `rust-lld` linker that ships inside the Rust toolchain, and `myrmic flash` has its flasher built in (see below). ### The embedded Rust toolchain Firmware compiles for `riscv32imac-unknown-none-elf` with the same pinned stable toolchain as cells. You do not install it by hand: a firmware crate scaffolded by `myrmic new --firmware`, on its first `myrmic build`, ships a `rust-toolchain.toml` that prompts `rustup` to auto-install the toolchain and the target. You will see a line like `the missing active toolchain 1.98.1 has been auto-installed` the first time. As with cells, the pinned version is the release tested for the current Myrmic release and moves forward with each release. To install it ahead of that first build - on an offline machine, or just to keep the build output quiet - the steps are optional: ```sh rustup toolchain install 1.98.1 rustup target add riscv32imac-unknown-none-elf --toolchain 1.98.1 ``` #### Building on a nightly toolchain If a firmware crate pins a nightly toolchain in its `rust-toolchain.toml` instead, `myrmic build` and `myrmic flash` notice and pass `-Z build-std=core,alloc`, so `core` and `alloc` are built from source with the firmware's own flags. That needs the `rust-src` component on the nightly toolchain. ### wamrc, the cell AOT compiler Firmware is only half of embedded. To run one of your own cells on the board, Myrmic ahead-of-time compiles the cell's WebAssembly to native RISC-V with **wamrc**, the WAMR AOT compiler - both `myrmic build --platform riscv32imac` and `myrmic deploy --platform riscv32imac` call it. Building and flashing firmware does not, so if that is all you do you can skip this section. wamrc is not packaged anywhere; you build it once from the WAMR sources, against the LLVM your distribution already ships. Only wamrc is compiled - not LLVM - so this is a short build, but the LLVM packages it links against are a few hundred megabytes to download. Myrmic requires **wamrc 2.4.4** exactly and rejects any other version. WAMR 2.4.4 is built against **LLVM 18**, which is what Ubuntu 24.04 installs as its default `llvm-dev` - so on 24.04 there is no version to choose. Install the build tools: | Distribution family | Install | |---|---| | Debian, Ubuntu | `sudo apt install build-essential cmake ninja-build llvm-dev` | | RHEL, AlmaLinux, Fedora | `sudo dnf install gcc-c++ cmake ninja-build llvm-devel` | The one value to get right is the LLVM directory the build links against. It must be the `llvm-dev` you just installed, not some other `llvm-*` directory that happens to exist - a leftover runtime-only directory (for example one holding just `libc++`) has no CMake config and fails late and cryptically. List what you have with `ls -d /usr/lib/llvm-*`; on Ubuntu 24.04 it is `/usr/lib/llvm-18`. Then build wamrc and put it on your `PATH`: ```bash curl -fsSL https://github.com/bytecodealliance/wasm-micro-runtime/archive/refs/tags/WAMR-2.4.4.tar.gz | tar -xz src="$PWD/wasm-micro-runtime-WAMR-2.4.4" mkdir -p "$src/core/deps/llvm" ln -sfn /usr/lib/llvm-18 "$src/core/deps/llvm/build" # the llvm-dev you installed cmake -S "$src/wamr-compiler" -B wamrc-build -G Ninja -DCMAKE_BUILD_TYPE=Release cmake --build wamrc-build sudo install -m 755 wamrc-build/wamrc /usr/local/bin/wamrc ``` Verify the version - it must read exactly `2.4.4`, or `myrmic build` refuses it: ```bash wamrc --version ``` ```text wamrc 2.4.4 ``` Two things about the result. wamrc links LLVM dynamically, so it stays on the machine that built it - it is not a binary you can copy to another node, and removing the LLVM runtime it links (`libllvm18`) breaks it. And Myrmic only checks that `wamrc` is on your `PATH`: `/usr/local/bin` above is on `PATH` by default, so if you install it elsewhere (for example `~/.cargo/bin`) make sure that directory is on `PATH`. `llvm-dev`, `cmake` and `ninja-build` are only needed to *build* wamrc, not to run it, so once it is on your `PATH` you can remove them to reclaim the space (`llvm-dev` and its LLVM development files are the bulk of it): ```bash sudo apt remove llvm-dev cmake ninja-build && sudo apt autoremove ``` wamrc keeps working afterwards because the LLVM runtime it links, `libllvm18`, stays behind: `libclang-dev` from the Clang step above depends on it, so `autoremove` leaves it in place. Two caveats. If you built wamrc on a machine that does *not* have the firmware prerequisites, nothing else holds `libllvm18` and `autoremove` would take it, breaking wamrc - keep `libllvm18` (or just keep `llvm-dev`) there. And leave `cmake` and `ninja-build` if other tooling on the machine uses them; many Rust crates build C dependencies with CMake. ### git The scaffolded firmware pins its ESP SDK crates to git revisions, so the first build fetches them from GitHub (the `esp-hal`, `wamr-rust-sdk` and related repositories). Install `git` if it is not already present - it is the same package the [Installation](./01_installation.md) page lists for building the CLI from source. | Distribution family | Install | |---|---| | Debian, Ubuntu | `sudo apt install git` | | RHEL, AlmaLinux, Fedora | `sudo dnf install git` | ### Serial access, for flashing `myrmic flash` talks to the board over its serial port; the flasher is compiled directly into the CLI, requiring no extra packages to be installed. What it needs is permission to open the port. On Linux the serial devices belong to the `dialout` group, so add yourself to it once: ```bash sudo usermod -aG dialout "$USER" ``` Log out and back in for the new group to take effect. Until then, and on systems without that group, `myrmic flash` can only reach the board when run with elevated privileges. ## Build a firmware With the prerequisites in place, scaffold a firmware crate, build it, and flash it. `--firmware` selects the chip; a bare `--firmware` defaults to `esp32c6`, and a specific chip takes the `=` form: ```bash myrmic new --firmware=esp32c6 my-node ``` Expected output: ```text INFO Creating firmware 'my-node' for esp32c6 ``` Build it. The first build is the slow one: it auto-installs the toolchain (above), fetches the ESP SDK crates, and compiles the WAMR runtime from source. On a small cloud instance that first build took around one and a half to two minutes once the toolchain was downloaded; later builds, with everything cached, are seconds. ```bash cd my-node myrmic build ``` Expected output (trimmed): ```text INFO Building esp32c6 firmware: .../my-node/Cargo.toml Updating git repository `https://github.com/peeriot/esp-hal.git` Compiling my-node v0.1.0 (.../my-node) Finished `release` profile [optimized] target(s) in Xs INFO Firmware: .../my-node/target/riscv32imac-unknown-none-elf/release/my-node INFO Partition table: .../partitions.generated.csv INFO Flash with: myrmic flash .../my-node ``` A successful `myrmic build` is also how you confirm the toolchain is complete: it needs no board attached, so you can verify the whole embedded setup before any hardware arrives. Then plug in the board and flash it: ```bash myrmic flash ``` `myrmic flash` connects to the board first (to read its flash size), then builds and writes the image, and the board resets into it. Add `--monitor` to stream the board's serial output afterwards, and `--port /dev/ttyACM0` to name the port when more than one board is attached. With no board connected the command stops at the connect step - which is the expected result when you are only checking the tooling: ```text ERROR No serial ports could be detected (Make sure you have connected a device to the host system. If the device is connected but not listed, try using the `--list-all-ports` flag.) ``` ### With BLE support To run cells that talk to Bluetooth Low Energy peripherals, the firmware has to be built with its `ble` feature, which enables the NimBLE host stack: - It is enabled automatically for the `esp32c5` and `esp32c61` chips - no extra flag is needed, so `myrmic build` already includes BLE. - It is off by default for `esp32c6`, so a C6 firmware silently skips the entire BLE path unless the feature is added explicitly. Add the feature when building a C6 firmware: ```bash myrmic new --firmware=esp32c6 my-node cd my-node myrmic build --features ble myrmic flash --features ble --monitor ``` Without the feature, BLE support is compiled out of the firmware, so it does not advertise `ble` and cannot serve BLE cells. See [Work with BLE peripherals](../05_guides/12_ble.md) for how a cell uses BLE. ## Next - [`myrmic new`](../10_reference/02_myrmic-cli/01_new.md), [`myrmic build`](../10_reference/02_myrmic-cli/03_build.md) - the full command reference; [`myrmic signal-layer new`](../10_reference/02_myrmic-cli/16_signal-layer/01_new.md) scaffolds a firmware with a Signal Layer pipeline (`--firmware esp32c6`). - [First Steps on an ESP32](../04_tutorials/03_first-steps-embedded.md) - flash this firmware to a board and deploy your first cell onto it. - [First Steps with the Signal Layer](../04_tutorials/04_first-steps-signal-layer.md) - scaffold a pipeline, a cell, and a firmware, and run them together. # Reference Reference is the complete technical documentation for Myrmic. Use it to look up CLI commands, configuration options, and SDK APIs. - [Configuration](./10_reference/01_configuration.md) - [Myrmic CLI](./10_reference/02_myrmic-cli.md) - [Myrmic SDK](./10_reference/03_myrmic-sdk.md) - [Signal Layer](./10_reference/04_signal-layer.md) # Configuration Reference documentation for all Myrmic configuration files. - [Runtime Configuration](./01_configuration/01_runtime-configuration.md) - [Cell and Application Configuration](./01_configuration/02_cell-and-application-configuration.md) - [Bridge Configuration](./01_configuration/05_bridge-configuration.md) # Bridge Configuration A bridge is a special cell that connects the swarm to the outside world. There are two bridge types: - **MQTT** - connects to an external MQTT broker. - **HTTP** - connects to an external HTTP service. Bridges are defined and configured using a **YAML specification file** that is passed to the [myrmic deploy](../02_myrmic-cli/05_deploy.md) in two ways: - Standalone - deploy the bridge directly by passing the specification file to the command. - As part of an application suite - by referencing the bridge definition file inside the application spec file. See [Cell and Application Configuration](./02_cell-and-application-configuration.md#classes). Both bridge types have different configuration options - covered in the sections below. ## MQTT Bridge Connects to an external MQTT broker. The cell can send commands to the bridge to publish messages on an MQTT topic, and receive events from the bridge when the broker pushes a message in. The configuration file for MQTT bridge has the following fields. - `name` - **Required.** Name of the bridge cell. - `broker_url` - **Required.** Alias: `broker`. MQTT broker URL. - `ingress` - **Required.** Alias: `ingresses`. List of inbound subscriptions - each MQTT message received on a subscribed topic is published as a swarm event. - `id` - **Required.** The swarm event name published when a message arrives on this topic. - `topic` - **Required.** MQTT topic to subscribe to. - `qos` *(optional)* - QoS level. Accepts `0`, `1` or `2`. Defaults to `0`. - `payload` - **Required.** Maps the MQTT message payload to a field in the event type. Uses the `${type:name}` format - `name` is a field name in the event type, `type` is the encoding (`string`, `json`, or `bytes`). See [Template Syntax](#template-syntax). - `egress` - **Required.** Alias: `egresses`. List of outbound publishers - each entry defines a command the bridge cell accepts and triggers as an MQTT publish. - `id` - **Required.** The command name a cell sends to trigger this publish. - `topic` - **Required.** MQTT topic to publish to. Use a static string, or embed `${type:name}` format to insert values from the input into the topic, where `name` is a field name in the command input type, `type` accepts `string`, `json`, `bool`, or a numeric type - or `${db:namespace/database/schema@key}` to read directly from the swarm key-value store. See [Template Syntax](#template-syntax). - `qos` *(optional)* - QoS level. Accepts `0`, `1` or `2`. Defaults to `0`. - `payload` - **Required.** Maps a field from the command input type to the MQTT message payload. Uses the `${type:name}` format - `name` is a field name in the command input type, `type` is the encoding (`string`, `json`, or `bytes`). See [Template Syntax](#template-syntax). **Example:** ```yaml name: my-mqtt-bridge broker_url: mqtt://localhost:1883 ingress: - id: temperature_reading topic: sensors/temperature qos: 1 payload: "${string:reading}" egress: - id: set_threshold topic: devices/${string:device_id}/threshold qos: 1 payload: "${json:config}" ``` The example above defines a bridge cell that sits between an MQTT broker and the swarm, carrying messages both ways: - **Inbound** - each reading the broker pushes to `sensors/temperature` becomes a swarm event any cell can subscribe to. - **Outbound** - a cell can set one device's threshold by sending the bridge a command, which it publishes to `devices//threshold` - the device id is taken from the command's payload. ## HTTP Bridge Connects to an external HTTP service. The cell sends a command to the bridge, which makes an HTTP request and returns the response. The configuration file has the following fields. - `name` - **Required.** Name of the bridge cell. - `base_url` - **Required.** Base URL of the HTTP service. - `types` *(optional)* - Named types that endpoints can reference by name using [Template Syntax](#template-syntax) - giving your cell typed request and response values. - `definitions` - Map of type name to JSON Schema definition. See [JSON Schema](https://json-schema.org/). - `endpoints` - **Required.** List of HTTP endpoints exposed to the swarm. - `id` - **Required.** The command name a cell sends to trigger this endpoint. - `request` - **Required.** Outbound request configuration. - `method` - **Required.** HTTP method (e.g. `GET`, `POST`). - `path` - **Required.** URL path. Use a static string, or embed `${type:name}` format to insert values from the input into the path, where `name` is a field name in the command input type, or a type name from `types.definitions` for `json`. `type` accepts `string`, `json`, `bool`, or a numeric type - or `${db:namespace/database/schema@key}` to read directly from the swarm key-value store. See [Template Syntax](#template-syntax). - `query` *(optional)* - Query parameters to include in the request. Add one entry per parameter - the key is the parameter name, the value is a static string or an embedded `${type:name}` format, where `name` is a field name in the command input type, or a type name from `types.definitions` for `json`. `type` accepts `string`, `json`, `bool`, or a numeric type - or `${db:namespace/database/schema@key}` to read directly from the swarm key-value store. Empty by default. See [Template Syntax](#template-syntax). - `headers` *(optional)* - Request headers to include in the request. Add one entry per header - the key is the header name, the value is a static string or an embedded `${type:name}` format, where `name` is a field name in the command input type, or a type name from `types.definitions` for `json`. `type` accepts `string`, `json`, `bool`, or a numeric type - or `${db:namespace/database/schema@key}` to read directly from the swarm key-value store. Empty by default. See [Template Syntax](#template-syntax). - `body` *(optional)* - Request body. Maps a field from the command input type to the HTTP request body. Uses the `${type:name}` format - `name` is a field name in the command input type, or a type name from `types.definitions` for `json`. `type` is the encoding (`string`, `json`, or `bytes`). No body by default. See [Template Syntax](#template-syntax). - `timeout_ms` *(optional)* - Request timeout in milliseconds. No timeout by default. - `response` - **Required.** Maps each HTTP status code the endpoint can return to a variant of a generated reply enum. Must be present - use `{}` for an endpoint with no described responses. Each key is a numeric HTTP status code (e.g. `200`, `404`), named as a reply variant by its canonical reason (`200` → `Ok`, `404` → `NotFound`). The reply enum always also gets an `Unknown(u16)` variant, produced for any status the endpoint returns that isn't listed here; it carries the raw status code. Each status's value is either a body template string, or a map: - **body shorthand** - A `${type:name}` body template (`type` is `string`, `json`, or `bytes` - for `json`, `name` can also be a type from `types.definitions`); the variant carries just that body. `200: "${json:result}"` is shorthand for `200: { body: "${json:result}" }`. - `headers` *(optional)* - Response headers to surface on the variant. Add one entry per header - the key is the header name, the value uses `${string:name}` - `name` names the field on the variant. Empty by default. See [Template Syntax](#template-syntax). - `body` *(optional)* - Maps the HTTP response body to the variant's `body` field. Uses the `${type:name}` format - `type` is the encoding (`string`, `json`, or `bytes`), `name` is a field name on the reply variant - for `json`, can also be a type from `types.definitions`. Omit for a status with no body. See [Template Syntax](#template-syntax). **Example:** ```yaml name: my-http-bridge base_url: http://localhost:8080 types: definitions: Device: type: object required: [id, name] properties: id: { type: string } name: { type: string } endpoints: - id: store_reading request: method: POST path: /api/devices/${string:device_id}/readings headers: Authorization: "Bearer ${db:p/secrets/tokens@api_key}" body: "${json:reading}" timeout_ms: 5000 response: 200: headers: x-request-id: "${string:request_id}" body: "${json:result}" 404: "${json:error}" - id: get_device request: method: GET path: /api/devices/${string:device_id} headers: Authorization: "Bearer ${db:p/secrets/tokens@api_key}" timeout_ms: 5000 response: 200: "${json:Device}" 404: "${json:error}" ``` The example above defines an HTTP bridge cell that exposes two endpoints of an external HTTP service to the swarm. A cell sends one of these commands to the bridge: - **`store_reading`** - the bridge posts the reading to `/api/devices//readings` - the device id is taken from the command's payload. - **`get_device`** - the bridge fetches one device from `/api/devices/` and returns it as a typed value. For both, the bridge reads the bearer token from the swarm key-value store and puts it in the `Authorization` header of the request. ## Template Syntax From inside your cell, a bridge looks like any other cell - you send commands to it and receive events from it. But behind the scenes, the bridge has to translate those commands and events to and from raw MQTT messages or HTTP requests. Something has to describe that mapping - which field becomes the topic, which becomes the payload, how to decode an incoming message into an event field. Template syntax is how you define that translation, directly in the config. The format is `${type:name}`: - `type` - how the value is encoded or decoded (`string`, `json`, `bytes`, or a numeric type). For HTTP bridges with `types` defined, `${json:name}` can reference a type name from `types.definitions`. - `name` - the field name in the command input, event type, or HTTP reply variant. Direction determines what `name` refers to: - **Outbound** (egress `topic` and `payload`, HTTP request `path`, `query`, `headers`, `body`) - `name` is a field name in the command input type. - **Inbound** (ingress `payload`, HTTP response `headers`, `body`) - `name` is a field name in the event type for MQTT ingress, or on the reply variant for HTTP. A second format, `${db:namespace/database/schema@key}`, reads a value directly from the swarm's distributed key-value store at runtime. Supported in MQTT egress `topic`, HTTP request `path`, `query`, and `headers`. ## See Also - [Cell and Application Configuration](./02_cell-and-application-configuration.md) - how to reference a bridge from an application specification - [Myrmic CLI Reference](../02_myrmic-cli.md) - full reference for all CLI commands # Cell and Application Configuration This page covers how to configure Cells and application suites during the build and the deployment process. To read more about build and deploy commands, see [`myrmic build`](../02_myrmic-cli/03_build.md) and [`myrmic deploy`](../02_myrmic-cli/05_deploy.md). ## Single Cell A Cell is configured in two stages, each covering different aspects: build time and deployment time. 1. During **deployment** using flags passed to the CLI deploy command - covers options like capability tags, name, and Cell SRI. See the [deploy command reference](../02_myrmic-cli/05_deploy.md) for details. 2. During the **build** process through the `Cargo.toml` file of the Cell's crate, using the `[package.metadata.myrmic]` section. This section is included in the Cell's manifest when scaffolded by the myrmic CLI. It controls the Cell's memory layout - heap, stack, and linear memory limits. The section accepts four fields that define how much memory the Cell gets, and the values of these fields are compiled into the cell's Wasm binaries and can't be changed at runtime, the fields are the following: - `heap_size` *(optional)* - Sets the amount of heap memory available to the cell during runtime in bytes. Can also be set through the `WASM_SDK_HEAP_SIZE` environment variable. Defaults to `32768` (32 KB). - `stack_size` *(optional)* - Sets the amount of stack memory available to the cell during runtime in bytes. Defaults to `32_768`. - `initial_memory` *(optional)* - Sets the amount of initial linear memory allocated to the cell at startup in bytes. Defaults to `131_072`. - `max_memory` *(optional)* - Sets the maximum amount of linear memory the Cell can use, in bytes. Defaults to `131_072`. **Example:** ```toml [package.metadata.myrmic] heap_size = 32_768 stack_size = 8_192 initial_memory = 131_072 max_memory = 262_144 ``` A crate with several cargo targets can give each target its own settings. Keys in `[package.metadata.myrmic.lib]` apply to the library, and keys in `[package.metadata.myrmic.bin.]` apply to that binary; either overrides the package-level value of the same key. A table for a binary the crate doesn't declare is an error. **Example:** ```toml [package.metadata.myrmic] heap_size = 32_768 [package.metadata.myrmic.lib] heap_size = 65_536 [package.metadata.myrmic.bin.sensor-node] firmware = "esp32" ``` A firmware crate sets `firmware = "esp32"` (aliases: `firmware-family`, `family`) instead of the memory keys. Its own cargo features pick the chip, and `myrmic flash` refuses an image built for a different chip than the attached board's. The chip names `esp32c5`, `esp32c6` and `esp32c61` are still accepted, but are deprecated. > **Note:** For workspaces there is no way to configure memory at the workspace level - only through the `Cargo.toml` of each member Cell. ## Application An application groups multiple Cells that belong together into a single unit that is built and deployed together. It is defined through a **YAML application specification file** passed to the myrmic CLI build and deploy commands. The file defines which Cells and bridges to build (`classes`) and which instances to deploy (`instances`). The YAML application specification file accepts the following top-level keys: ### `name` *(optional)* - Unique name used to identify the application in the swarm. Defaults to the spec file's parent directory name. ### `classes` A list of buildable classes. Each entry has an `id` and is either a **cell** (built from a crate) or a **bridge** (described by a spec file). `build` and `spec` are mutually exclusive. - `id` - **Required.** Identifier for the class, referenced from `instances`. - `build` - Cell classes. Build configuration; a bare string is taken as the crate path. Omitting both `build` and `spec` builds the crate in the app-specs folder (`path: "."`) with automatic target selection. - `path` *(optional)* - Aliases: `source`, `directory`, `dir`. Path to the Cell's `Cargo.toml` or source directory. Defaults to `.`. - `target` *(optional)* - A single cargo target: `lib` or a target name. A class produces exactly one artifact, so at most one target may be named. Omit to auto-select (sole binary, else sole library). - `platforms` *(optional)* - One or a list of build platforms: `linux`, `esp32c5`, `esp32c6`, `esp32c61`. Defaults to `linux`. - `spec` - Bridge classes. Aliases: `http`, `mqtt`, `cell`. Path to the bridge specification YAML file, relative to the app-specs file. ### `instances` A list of instances to deploy. Each entry references exactly one entry from `classes`: - `class` - References a cell `classes` entry by `id`. - `bridge` - References a bridge `classes` entry by `id`. - `srn` *(optional)* - SRN to deploy this instance under. Defaults to the referenced class id. - `tags` *(optional)* - Capability tags the target runtime must advertise - controls which runtimes this Cell is placed on. Defaults to an empty list, meaning it deploys to any runtime. - `init` *(optional)* - **Cell instances only.** Arguments delivered to the Cell's initialization handler on deploy. Encoded as JSON by default; a value that isn't valid JSON is sent as a JSON string. - `init_file` *(optional)* - **Cell instances only.** Path to a file relative to the app-spec directory, whose raw bytes are delivered verbatim to the Cell's initialization handler. - `restart` *(optional, work in progress)* - **Cell instances only.** Restart policy for the Cell this instance deploys. Either a bare policy name or a mapping that also tunes the crash-loop bounds - see [`restart`](#restart) below. Defaults to `never`. > `class` and `bridge` are mutually exclusive, and the referenced class must be of the matching kind. > > `init` and `init_file` are mutually exclusive. > > `init`/`init_file`/`restart` apply only to cell instances. Bridges have no restart policy. > > It is possible to deploy one class under different SRIs by listing multiple instances that reference it. #### `restart` > **Work in progress** > Restart policies are being developed as part of the Basic Cell stage and are not yet covered by the [guarantee contract](../../08_guarantees.md). A restart is not continuity: Cell State and Mailboxes are held as one copy by default, so a Cell restarted after Node loss does not resume from where it stopped. See the [roadmap](../../09_roadmap.md) for the stages that add replicated authority and data. The policy name is one of: - `never` (the default) - a dead Cell stays dead. - `on-error` (also spelled `onerror`) - restart on an abnormal exit: a crash, a spawn failure, Node loss, or a non-zero stop code. A clean self-stop is terminal. - `always` - restart on any exit. Only an operator terminate or a cascade teardown is terminal. Written as a bare string, the crash-loop bounds keep their defaults. Written as a mapping, the bounds can be tuned: - `type` - **Required.** The policy name. - `max` *(optional)* - Maximum number of restarts within `window` before the Cell is left dead. Defaults to `5`. - `window` *(optional)* - Length of the crash-loop window, as a human-readable duration (`30s`, `500ms`, `1m`). Defaults to `60s`. - `delay` *(optional)* - Pause between an exit and the next restart, as a human-readable duration. Defaults to `1s`. ```yaml instances: - class: my-cell-class-id-1 restart: always - class: my-cell-class-id-2 restart: type: on-error max: 3 window: 30s delay: 2s ``` Passing `--policy` to [`myrmic deploy`](../02_myrmic-cli/05_deploy.md) replaces the `restart` declared by every instance in the file; each instance whose declared policy is discarded is named in a warning. To read more about the bridge specification format and how to configure them, see [Bridge Configuration](./05_bridge-configuration.md). **Examples:** ```yaml name: my-app classes: - id: my-cell-class-id-1 build: path: ./my-cell-1 platforms: - linux - esp32c6 - id: my-cell-class-id-2 build: path: ./my-cell-2 platforms: esp32c6 - id: my-mqtt-bridge spec: my-mqtt_bridge.yml instances: - class: my-cell-class-id-1 srn: my-cell-1 tags: [my-tag-1] - class: my-cell-class-id-2 srn: my-cell-2 tags: [my-tag-2] - bridge: my-mqtt-bridge srn: bridge.mqtt ``` ## See Also - [Runtime Configuration](./01_runtime-configuration.md) - runtime configuration - [Bridge Configuration](./05_bridge-configuration.md) - MQTT and HTTP bridge specification format - [Myrmic CLI Reference](../02_myrmic-cli.md) - full reference for all CLI commands - [`myrmic gateway`](../02_myrmic-cli/10_gateway.md) - how a cell gets served over HTTP # Runtime Configuration A Myrmic runtime can be configured in two ways: - By passing a YAML file at startup. - Through CLI flags when running the start command. This covers a reduced set of options compared to the YAML file. Both options are applied at startup with `myrmic runtimes start`. See [myrmic runtimes start](../02_myrmic-cli/04_runtimes/01_start.md) for details and examples. When starting a runtime without a config file or CLI flags, it starts with built-in defaults. A restart is required to apply a configuration change, except for `telemetry.db_retention` and `telemetry.logs.env_filter`, which can be changed on a running runtime. This page covers configuration through the YAML file. It is structured as top-level sections, each controlling a specific aspect of the runtime. ## `zenoh` *(advanced)* Since Myrmic uses Zenoh as its transport layer. Configure it directly under the `zenoh` key - mode, peer discovery, transport, and connectivity. For the fields Zenoh itself documents, see the [Zenoh default config reference](https://github.com/eclipse-zenoh/zenoh/blob/main/DEFAULT_CONFIG.json5). Myrmic runs a fork of Zenoh, so that document does not list every key a runtime accepts. The fork-only keys are documented here: - `scouting/interface_poll_interval` *(optional)* - How often the runtime re-reads the host's network interfaces, in milliseconds. This is what lets a runtime notice that its own IP address changed and re-announce itself without a restart - see [Operating a swarm](../../05_guides/09_operating-a-swarm.md#discovery-identity-and-placement) for what it does and which nodes it does not help. Defaults to `10000`. `0` turns the poll off for the life of the process, and a later change to a running runtime cannot turn it back on. The value must be a non-negative whole number: a float or a negative number is rejected at parse time, so a runtime started with one does not come up, and a write of one to a running runtime is refused. ## `execution` Configures the execution behavior. - `mailbox_poll_interval_ms` *(optional)* - How often the runtime checks for new inbound messages, in milliseconds. Defaults to `5000`. - `mailbox_batch_size` *(optional)* - Number of event rows fetched per mailbox poll interval. Defaults to `8`. - `tags` *(optional)* - Capability tags this runtime advertises. Controls which Cells are placed on this runtime. Tags set here are combined with any additional tags passed via the CLI at startup. Defaults to none. - `max_fuel_per_handler` *(optional)* - Compute budget the runtime grants to each handler invocation - limits how many wasm instructions a single handler invocation may execute before it is interrupted. Every invocation gets its own fresh budget, independent of the Cell and of previous invocations. See [External Links](#external-links) for the underlying wasmtime fuel mechanism. Defaults to unlimited. - `fuel_yield_interval` *(optional)* - Number of fuel units a Cell consumes before yielding to the async scheduler, letting other tasks run. See [External Links](#external-links) for the underlying wasmtime fuel mechanism. Defaults to `1000`. - `init_timeout_secs` *(optional)* - How long to wait for a Cell to initialize, in seconds. If exceeded, initialization fails and the entire deployment is rolled back. Defaults to `10.0`. ## `db` Configures storage behavior. - `directory` *(optional)* - Path to the directory where data is stored on disk. If omitted, the runtime uses a persistent database under its data folder (`~/.local/share/myrmic//db` on Linux). Start the runtime with [`runtimes start --tmp`](../02_myrmic-cli/04_runtimes/01_start.md) for an in-memory database that is lost on restart. - `gc_interval` *(optional)* - Garbage collection scan interval. Accepts [humantime](https://docs.rs/humantime/latest/humantime/) duration strings (e.g. `"100ms"`, `"30s"`, `"1min"`). Defaults to `"60s"`. - `tx_idle_timeout` *(optional)* - How long an RPC transaction may sit unused before the store rolls it back. Accepts [humantime](https://docs.rs/humantime/latest/humantime/) duration strings. Defaults to `"5min"`. - `load_from` *(optional)* - Loads files from disk into the database as blobs at startup. Each entry accepts: - `path` - **Required.** File or directory to read. If a directory, all files inside are loaded. - `scope` *(optional)* - The scope the files are stored under, in `namespace/database/schema` format. Defaults to `p/p/d`. - `prefix` *(optional)* - Prepended to each filename to form the database key. Must start and end with `/`. Defaults to `/`. e.g. a file named `token` with `prefix: "/secrets/"` is stored at key `/secrets/token`. - `max_depth` *(optional)* - When `path` is a directory, controls how deep to recurse. By default all files at any depth are loaded. ## `gateway` When this section is present, the runtime also runs an embedded gateway - it starts and stops together with the runtime - providing an entry point for external clients to the swarm, to send commands and publish events over HTTP and WebSocket, and serving static web assets. - `port` *(optional)* - TCP port the embedded gateway listens on. Defaults to `8080`. To run the gateway as its own process independently of a runtime, use [`myrmic gateway`](../02_myrmic-cli/10_gateway.md) instead. ## `onboarding` When this section is present, the runtime also runs the onboarding installer, which onboards new devices from onboarding requests, one request at a time. Up to 8 requests wait while one is running; when more arrive, the oldest waiting request is dropped. An empty section (`onboarding: {}`) enables it with the defaults. - `timeout` *(optional)* - How long a single onboarding may take before the installer abandons it and serves the next request. Accepts [humantime](https://docs.rs/humantime/latest/humantime/) duration strings (e.g. `"30s"`, `"5min"`). Defaults to `"5min"`. ## `orchestration` Configures the self-organization behavior. - `init_timeout_secs` *(optional)* - How long the Self Organization Layer waits for a runtime to confirm a deployment, in seconds. If exceeded, the entire deployment is rolled back. Defaults to `15.0`. ## `telemetry` Configures where logs go, how they are formatted, and whether telemetry is exported to an OpenTelemetry collector. - `db_retention` *(optional)* - How long telemetry data is retained in the database. Accepts [humantime](https://docs.rs/humantime/latest/humantime/) duration strings (e.g. `"1h"`, `"7d"`). Setting it also turns DB storage on: if omitted, no telemetry is written to the database and the `myrmic telemetry` query commands return nothing. Can be changed at runtime with [myrmic telemetry set-db-retention](../02_myrmic-cli/12_telemetry/05_set-db-retention.md). - `logs` *(optional)* - `format` *(optional)* - Log line format printed to stdout. Accepts `FULL`, `COMPACT`, `PRETTY`, or `JSON`. Defaults to `FULL`. See the [tracing-subscriber format reference](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/format/index.html). - `env_filter` *(optional)* - Controls which logs are printed. Can be changed at runtime without a restart - see [myrmic telemetry set-filter](../02_myrmic-cli/12_telemetry/04_set-filter.md). Uses [EnvFilter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) syntax: `target=level` or just `level` (e.g. `"info"`, `"swarm=debug,warn"`). If not set, the `RUST_LOG` environment variable is used instead. - `otel_endpoint` *(optional)* - OpenTelemetry endpoint for log export. If omitted, logs are not exported. - `metrics` *(optional)* - `otel_endpoint` *(optional)* - OpenTelemetry endpoint for metrics export. If omitted, metrics are not exported. - `traces` *(optional)* - `otel_endpoint` *(optional)* - OpenTelemetry endpoint for trace export. If omitted, traces are not exported. > If a high level section is omitted, its default configuration is used. ## Example ```yaml execution: mailbox_poll_interval_ms: 200 mailbox_batch_size: 16 tags: [my-flag-1, my-flag-2, my-flag-3] db: directory: ./my-db-data load_from: - path: ./secrets scope: "p/secrets/tokens" prefix: "/secrets/" gateway: port: 8080 telemetry: logs: format: JSON env_filter: "info,swarm=debug" otel_endpoint: "http://localhost:4317" metrics: otel_endpoint: "http://localhost:4317" traces: otel_endpoint: "http://localhost:4317" ``` ## See Also - [Myrmic CLI Reference](../02_myrmic-cli.md) - full reference for all CLI commands - [Cell and Application Configuration](./02_cell-and-application-configuration.md) - Cells and Applications Configuration ## External Links - [wasmtime `Store::set_fuel`](https://docs.rs/wasmtime/43.0.2/wasmtime/struct.Store.html#method.set_fuel) - how a fuel budget is set on a wasm store - [wasmtime `Store::fuel_async_yield_interval`](https://docs.rs/wasmtime/43.0.2/wasmtime/struct.Store.html#method.fuel_async_yield_interval) - yielding to the async scheduler at a fuel interval - [wasmtime deterministic fuel](https://docs.wasmtime.dev/examples-interrupting-wasm.html#deterministic-fuel) - background on interrupting wasm execution with fuel --- sidebar_label: Myrmic CLI --- # Myrmic CLI The Myrmic CLI is the command-line tool for creating, building, deploying, and interacting with Myrmic cells and applications. ## Synopsis ``` myrmic [OPTIONS] COMMAND [ARGS] myrmic --help myrmic --version ``` ## Environment Variables The following environment variables control the behavior of the `myrmic` command-line tool. | Variable | Description | Used by | |---|---|---| | `CARGO` | Path to the `cargo` executable. Defaults to `cargo` on `PATH`. | [`build`](02_myrmic-cli/03_build.md), [`deploy`](02_myrmic-cli/05_deploy.md) | | `DEFAULT_MYRMIC_MULTICAST_GROUP` | Multicast group (`

:`) to discover runtimes on instead of the default `224.0.0.224:7446`, like `--multicast-group`. An explicit `--multicast-group` takes precedence. | every command that talks to the swarm | | `XDG_RUNTIME_DIR` | Controls where PID files are stored. | [`runtimes start`](02_myrmic-cli/04_runtimes/01_start.md), [`runtimes list`](02_myrmic-cli/04_runtimes/02_list.md), [`runtimes delete`](02_myrmic-cli/04_runtimes/03_delete.md) | | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` | S3 credentials. | [`database export`](02_myrmic-cli/13_database/01_export.md), [`database import`](02_myrmic-cli/13_database/02_import.md) | | `AWS_REGION` / `AWS_DEFAULT_REGION` | AWS region for S3. Falls back to `us-east-1`. | [`database export`](02_myrmic-cli/13_database/01_export.md), [`database import`](02_myrmic-cli/13_database/02_import.md) | ## Commands Below is the full list of `myrmic` commands, each with a dedicated reference page covering its synopsis, options, and examples. ### Setup - [`new`](02_myrmic-cli/01_new.md) - Scaffold a new cell or ESP32 firmware crate. - [`signal-layer new`](02_myrmic-cli/16_signal-layer/01_new.md) - Scaffold a Signal Layer pipeline project, on Linux or into an ESP32 firmware. Aliases: `sl new` - [`signal-layer driver`](02_myrmic-cli/16_signal-layer/02_driver.md) - Scaffold a Signal Layer driver module. Aliases: `sl driver` - [`signal-layer step`](02_myrmic-cli/16_signal-layer/03_step.md) - Scaffold a Signal Layer processing step module. Aliases: `sl step` ### Build - [`platforms`](02_myrmic-cli/02_platforms.md) - List available build platforms. - [`build`](02_myrmic-cli/03_build.md) - Build a cell, workspace, or application suite. ### Runtime - [`runtimes start`](02_myrmic-cli/04_runtimes/01_start.md) - Start a runtime instance. Aliases: `run` - [`runtimes list`](02_myrmic-cli/04_runtimes/02_list.md) - List runtime instances. - [`runtimes delete`](02_myrmic-cli/04_runtimes/03_delete.md) - Stop one or more runtime instances. Aliases: `stop`, `remove`, `rm` ### Deploy & Manage - [`deploy`](02_myrmic-cli/05_deploy.md) - Deploy cells, application suites, or bridges. - [`cells status`](02_myrmic-cli/06_cells/01_status.md) - List or inspect deployed cells. Aliases: `cell` - [`cells teardown`](02_myrmic-cli/06_cells/02_teardown.md) - Tear down a deployed cell. - [`cells classes list`](02_myrmic-cli/06_cells/03_classes/01_list.md) - List registered cell classes. Aliases: `class` - [`cells classes add`](02_myrmic-cli/06_cells/03_classes/02_add.md) - Register a cell class. - [`cells classes delete`](02_myrmic-cli/06_cells/03_classes/03_delete.md) - Remove a cell class. Aliases: `remove`, `rm` - [`cells classes info`](02_myrmic-cli/06_cells/03_classes/04_info.md) - Show details of a cell class. - [`network status`](02_myrmic-cli/07_network/01_status.md) - Show swarm nodes. Aliases: `nodes`, `info` - [`tags`](02_myrmic-cli/14_tags.md) - Add and remove tags on nodes. Aliases: `tag` - [`replicate`](02_myrmic-cli/15_replicate.md) - Configure which nodes replicate which data. Aliases: `replicas`, `replica`, `rep` - [`gateway`](02_myrmic-cli/10_gateway.md) - Start a swarm gateway node. - [`delete`](02_myrmic-cli/11_delete.md) - Remove a deployed cell or application. Aliases: `rm`, `stop` ### Interact - [`send`](02_myrmic-cli/08_send.md) - Send a command to a deployed cell. Aliases: `command`, `cmd` - [`publish`](02_myrmic-cli/09_publish.md) - Publish an event into the swarm. Aliases: `event`, `pub` ### Telemetry - [`telemetry logs`](02_myrmic-cli/12_telemetry/01_logs.md) - Print log records from the swarm. - [`telemetry traces`](02_myrmic-cli/12_telemetry/02_traces.md) - Export swarm traces as JSON. - [`telemetry metrics`](02_myrmic-cli/12_telemetry/03_metrics.md) - Print the latest metric values from the swarm. - [`telemetry set-filter`](02_myrmic-cli/12_telemetry/04_set-filter.md) - Change the log filter on all connected swarm nodes. - [`telemetry set-db-retention`](02_myrmic-cli/12_telemetry/05_set-db-retention.md) - Set the telemetry database retention period. - [`telemetry no-db-retention`](02_myrmic-cli/12_telemetry/06_no-db-retention.md) - Disable telemetry database retention. - [`telemetry debug`](02_myrmic-cli/12_telemetry/07_debug.md) - Stream live debug information of commands, events and logs from the swarm. ### Database - [`database export`](02_myrmic-cli/13_database/01_export.md) - Export a database scope to a snapshot. Aliases: `db export` - [`database import`](02_myrmic-cli/13_database/02_import.md) - Restore a snapshot into a database scope. Aliases: `db import` # myrmic build ## Name `myrmic build` - build a cell, workspace, firmware, or application suite ## Synopsis ``` myrmic build [OPTIONS] [PATH] ``` ## Description Build a cell crate, a workspace of cells, or an application suite from source. `PATH` specifies what to build: - A cell crate directory - compiles the cell to a `.wasm` binary in the crate's `target` directory. - A cell crate `Cargo.toml` - same as above, specified explicitly. - A workspace directory - compiles all member crates to `.wasm` binaries in the workspace's `target` directory. - A workspace `Cargo.toml` - same as above, specified explicitly. - A `.yml` / `.yaml` application specification file - builds every cell class defined in the specification and bundles the compiled binaries and application metadata into a `.nest` bundle placed in the working directory. - A firmware crate directory - a crate whose `[package.metadata.myrmic]` sets `firmware = "esp32"` compiles to an ESP firmware image (ELF plus a generated partition table). `--platform` is ignored (the crate's cargo features pick the chip; `myrmic flash` refuses an image built for a different chip than the board's); `--name` sets the runtime name baked into the image. A crate scaffolded with `myrmic signal-layer new --firmware` also generates its Signal Layer pipeline at build time. If `PATH` is not provided, the current directory is used. All cell builds run in release mode for the `wasm32v1-none` target using `cargo +1.98.1` internally. Firmware builds use the same toolchain for the `riscv32imac-unknown-none-elf` target. A cell or firmware crate that pins its own toolchain in a `rust-toolchain.toml` builds with that pin instead, and when the pin is a nightly toolchain, `-Z build-std=core,alloc` is added. Set the `CARGO` environment variable to use a specific `cargo` binary. To learn about the application specification file, see [Cell and Application Configuration](../01_configuration/02_cell-and-application-configuration.md). ## Options `--platform PLATFORMS` Build for the specified platforms. Multiple platforms may be specified as a comma-separated list. Defaults to `linux`. See [`myrmic platforms`](02_platforms.md) for the full list. Ignored for application suite builds (set `platform` per cell class in the application specification instead). `--target TARGET` Cargo target to build, accepts `lib` or the name of a binary declared in `Cargo.toml`. When omitted, auto-selects: - Exactly one binary - use it. - No binaries, exactly one library - use the library. - Otherwise - returns an error. Applies to cell crate and cell workspace builds. Ignored for app suite builds - use `target` per class in the app spec instead. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Build a cell: ```bash myrmic build ./my-cell ``` 2. Build for multiple platforms: ```bash myrmic build --platform linux,riscv32imac ``` 3. Build a workspace (all member crates): ```bash myrmic build ./my-workspace ``` 4. Build an application suite from a specification file: ```bash myrmic build ./my-app/app_specs.yml ``` 5. Select a specific cargo target: ```toml [lib] name = "my-cell" [[bin]] name = "server" ``` ```bash myrmic build --target lib # build the library target myrmic build --target server # build the binary named "server" ``` # myrmic cells classes add ## Name `myrmic cells classes add` - Register a cell class manually ## Synopsis ``` myrmic cells classes add [OPTIONS] [NAME] ``` ## Description Creates a cell class from a binary artifact, or adds an artifact to an existing class. Classes are normally created automatically by [`myrmic deploy`](../../05_deploy.md) - use this command to register pre-built artifacts directly. ## Options `--wasm PATH` Path to a `.wasm` binary to register as the class artifact. Mutually exclusive with `--aot`. `--aot PATH` Path to an AOT-compiled binary. Requires `--platform` and `--meta`. `--meta PATH` Path to the AOT metadata file. `--platform PLATFORM` Target platform for the AOT artifact. Accepted values: - `riscv32imac` - Espressif RISC-V chips (ESP32-C5, ESP32-C6, ESP32-C61). Also accepted: `esp32c5`, `esp32_c5`, `esp32c6`, `esp32_c6`, `esp32c61`, `esp32_c61`. `--force` Overwrite the existing wasm binary if the class already has one registered. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Register a class from a wasm binary: ```bash myrmic cells classes add my-cell --wasm ./my-cell.wasm ``` 2. Register a class with an AOT artifact: ```bash myrmic cells classes add my-cell --aot ./my-cell.aot --meta ./my-cell.meta --platform esp32c6 ``` # myrmic cells classes delete ## Name `myrmic cells classes delete` - Remove a cell class Aliases: `remove`, `rm` ## Synopsis ``` myrmic cells classes delete [NAME] ``` ## Description Removes the cell class identified by `NAME` from the data layer. Fails if the class has any instances. Delete all instances first. ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Remove a class: ```bash myrmic cells classes delete my-cell-class ``` # myrmic cells classes info ## Name `myrmic cells classes info` - Show details for a cell class ## Synopsis ``` myrmic cells classes info [NAME] ``` ## Description Show details for the cell class identified by `NAME`, including the hash of its registered wasm binary and any AOT artifacts with their target platform, compiled binary hash, and metadata file hash. ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Show class details: ```bash myrmic cells classes info my-cell-class ``` # myrmic cells classes list ## Name `myrmic cells classes list` - List registered cell classes ## Synopsis ``` myrmic cells classes list ``` ## Description List all cell classes registered in the swarm. Each entry shows the class name and the hash of its registered wasm binary, and any AOT artifacts with the target platform, the hash of the compiled native binary, and the hash of the metadata file. ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. List all registered classes: ```bash myrmic cells classes ``` # myrmic cells status ## Name `myrmic cells status` - List and inspect deployed cells ## Synopsis ``` myrmic cells status [OPTIONS] [SRI/SRN]... myrmic cells [OPTIONS] [SRI/SRN]... ``` ## Description List all registered cells, or inspect specific ones by passing one or more SRIs (UUID) or SRN names. Each match is rendered with its whole spawn subtree. If no `SRI/SRN` is provided, all deployed cells are listed. `status` is the default subcommand, so `myrmic cells` accepts the same arguments directly. In a terminal the listing is live: it refreshes every `--interval` until interrupted with Ctrl+C, and the last state stays on screen afterwards. A cell that appears - or comes back with a new generation after a respawn - fades in green; a cell that disappears fades out struck through in red before its row goes. If a refresh fails, the previous listing stays up and the error is shown above it until the next refresh succeeds. When the output is not a terminal (piped into another command, say) the listing is printed once, as if `--once` had been given. ## Output One row per registered cell, indented into its spawn tree; without arguments the rows are grouped by application: - `cell` - the cell's own name segment. - `sri` - the cell's unique id. - `kind` - `wasm`, `bridge`, or `N/A` for a cell that is claimed but not yet deployed. - `runtime` - the execution runtime the cell is placed on, shown as the first 8 characters of its id, or more when 8 are not enough to tell it apart from another runtime in the listing. The characters that make it unique are highlighted in a terminal and bracketed outside one, as in `[8]30d3436` - the brackets mark the unique prefix, here the single leading character, not a count. - `age` - how long the current incarnation has been placed; a respawn resets it. - `policy` - the restart policy in force, as [`myrmic deploy --policy`](../05_deploy.md) spells it: `never`, `on-error` or `always`. Only root cells carry one, and a wasm root deployed without a policy shows `never`. A root that is being restarted shows the policy it comes back under even while its `kind` reads `N/A`: the stored spec outlives the placement row, and the restart replays it. The column lags at both ends of a cell's life - a first deploy reads `—` while the cell is still being placed and can read `never` for one refresh before an `on-error` or `always` policy is stored, and a teardown erases the spec just before it removes the row, so an `always` root can read `never` on its way out. `—` means there is no restart policy to read for that row: a spawned cell and a bridge are never restarted by policy, and a row that has not finished registering has nothing to read. - `class` - the cell class the instance was created from. - `srn` - the cell's full human-readable name. A chain that cannot be walked back to a named root keeps its known tail behind `…/`. `—` in any column means the row has no value to show there. ## Options `--once` Print the listing once and exit instead of refreshing until interrupted. `--interval DURATION` Time between refreshes while live, e.g. `500ms`, `2.5s`, `1m`. Defaults to `2.5s`. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Watch all registered cells: ```bash myrmic cells ``` 2. Inspect a specific cell: ```bash myrmic cells status my-cell ``` 3. Print the listing once, for a script or a quick look: ```bash myrmic cells --once ``` # myrmic cells teardown ## Name `myrmic cells teardown` - Undeploy a cell and erase its instance ## Synopsis ``` myrmic cells teardown [OPTIONS] [SRI/SRN] ``` ## Description Purges a running cell identified by its SRI (UUID) or SRN name. Unlike [`myrmic delete`](../11_delete.md), which only stops the cell, teardown also removes the instance record from the data layer, so redeploying after a teardown starts the cell as if it were brand new. ## Options `--remove-class` Also remove the cell class from the data layer after teardown, if no other instances still reference it. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. teardown a cell and remove the class if no other instances use it: ```bash myrmic cells teardown my-cell --remove-class ``` # myrmic database export ## Name `myrmic database export` - Export a database scope to a snapshot Aliases: `db export` ## Synopsis ``` myrmic database export [OPTIONS] [SCOPE] ``` ## Description Exports a database `SCOPE` to a snapshot. The snapshot can be written to: - a local file path. - a file URI. - an S3 URI. A [SCOPE] is a way to organize and split the data space, it also identifies a specific dataset in the distributed swarm storage, should be provided in this format `namespace/database/schema`. For S3 targets, credentials are read from the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, with optional support for `AWS_SESSION_TOKEN`. Despite their names, these variables can also provide credentials for non-AWS, S3-compatible services, such as MinIO, Google Cloud Storage, and IBM Cloud Storage. The target bucket must exist before you run this command. ## Options `--target URI` Specifies the snapshot destination. Required. Accepts: - a local file path. - a file URI ``file://...``. - an S3 URI (`s3://bucket/key`). `--region REGION` AWS region. S3 only. Falls back to `AWS_REGION`, `AWS_DEFAULT_REGION` environment variables, if not set then `us-east-1`. `--endpoint URL` Overrides the S3 API endpoint. Use for S3-compatible services such as MinIO or LocalStack. S3 only. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Export a scope using a file URI: ```bash myrmic database export my-namespace/my-database/my-schema --target file:///var/backups/snapshot ``` 2. Export a scope to AWS S3 with an explicit region: ```bash myrmic database export my-namespace/my-database/my-schema --target s3://my-bucket/my-snapshot --region eu-west-1 ``` 5. Export a scope to a local MinIO instance: ```bash myrmic database export my-namespace/my-database/my-schema --target s3://my-bucket/my-snapshot --endpoint http://localhost:9000 ``` # myrmic database import ## Name `myrmic database import` - Restore a snapshot into a database scope Aliases: `db import` ## Synopsis ``` myrmic database import [OPTIONS] [SCOPE] ``` ## Description Restores a snapshot into a database scope. The snapshot can be read from: - a local file path. - a file URI. - an S3 URI. A `SCOPE` is a way to organize and split the data space, it also identifies a specific dataset in the distributed swarm storage, should be provided in this format `namespace/database/schema`. > **Note:** Snapshots record the scope they were exported from, So `SCOPE` here is a way to override it, it is optional and if not passed the one recorded in the snapshot is used For S3 sources, credentials are read from environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN`. The bucket must exist before running this command. ## Options `--source URI` Specifies the snapshot source. Required. Accepts: - a local file path. - a file URI ``file://...``. - an S3 URI (`s3://bucket/key`). `--region REGION` AWS region. S3 only. Falls back to `AWS_REGION`, `AWS_DEFAULT_REGION` environment variables, if not set then `us-east-1`. `--endpoint URL` Overrides the S3 API endpoint. Use for S3-compatible services such as MinIO or LocalStack. S3 only. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Restore a snapshot file URI into a different scope than the one it was exported from: ```bash myrmic database import my-namespace/my-database/my-schema --source file:///var/backups/snapshot ``` 2. Restore a snapshot from AWS S3 with an explicit region: ```bash myrmic database import --source s3://my-bucket/my-snapshot --region eu-west-1 ``` 6. Restore a snapshot from a local MinIO instance: ```bash myrmic database import --source s3://my-bucket/my-snapshot --endpoint http://localhost:9000 ``` # myrmic delete ## Name `myrmic delete` - Stops a deployed cell or application Aliases: `rm`, `stop` ## Synopsis ``` myrmic delete [OPTIONS] [TARGET] ``` ## Description Stops a deployed cell or application. - If `TARGET` is an application name - stops the entire application and all its cells. - If `TARGET` is a cell SRI or SRN - stops the cell instance. Deleting a cell that belongs to an application is not allowed. To purge a cell and its instance data, use [`myrmic cells teardown`](06_cells/02_teardown.md) instead. ## Options In a terminal, `delete` asks what to remove when the target could mean more than one thing (the cell, the application it belongs to, or its descendants). Run without a terminal it does not prompt; pass the choice as one of these flags, or the command stops with `refusing to prompt without a terminal`. `--cell` Delete just this cell. `--app` Delete the whole application the target belongs to, and all its cells. `--branch` Delete the cell together with its descendants. `--children` Delete the target's descendants but keep the target itself. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Delete a cell: ```bash myrmic delete my-cell ``` 2. Delete an application and all its cells: ```bash myrmic delete my-app ``` # myrmic deploy ## Name `myrmic deploy` - Deploy cells, application suites, or bridges ## Synopsis ``` myrmic deploy [OPTIONS] [PATH] ``` ## Description Deploy cells, application suites, or bridges to the swarm. `PATH` specifies what to deploy: - A `.wasm` binary - deploys the cell directly, without building. - A `.nest` bundle - deploys a pre-built application suite directly. - A `.yml` / `.yaml` bridge configuration file - deploys an MQTT or HTTP bridge. - A cell crate directory or `Cargo.toml` - builds the cell and deploys it. - A workspace directory or `Cargo.toml` - builds all member crates and deploys them. - A `.yml` / `.yaml` application specification file - builds every cell class and deploys all instances atomically. If one instance fails, the entire deployment is rolled back. When deploying from source (a crate, workspace, or app spec), the command builds automatically - no need to run `myrmic build` first. If `PATH` is not provided, the current directory is used. To learn about the bridge configuration file, see [Bridge Configuration](../01_configuration/05_bridge-configuration.md). To learn about the application specification file, see [Cell and Application Configuration](../01_configuration/02_cell-and-application-configuration.md). ## Options `--name SRN` (alias: `--srn`) Sets the SRN (name) the deployment is registered under; the cell's SRI is derived from it. A UUID is rejected - the SRI cannot be set directly. How it is applied depends on what is being deployed: - **Cell** - used as the cell's SRN. Defaults to the crate name when deploying from source. For a `.wasm` binary it defaults to the **file name including its extension**, so `./counter.wasm` registers as `counter.wasm` and later commands must use that exact name; pass `--name` to give the cell a clean SRN. - **`.nest` bundle** - ignored; names are read from the bundle metadata. - **Bridge** - overrides the bridge name from the given configuration file. - **Workspace** - used as a prefix for each crate (``). Defaults to each crate's own name. - **Application specification file** - ignored; names are taken from the specification file. `--tag TAG` / `-t TAG` Adds a placement requirement tag to the deployment. Can be specified multiple times. Ignored for application suite deployments (use the `tags` field in the specification file) and `.nest` bundles (tags are in the bundle metadata). `--platform PLATFORMS` Build for the specified platforms before deploying. Multiple platforms may be specified as a comma-separated list. Defaults to `linux`. See [`myrmic platforms`](02_platforms.md) for the full list. Every platform produces the same wasm binary; embedded platforms additionally produce an AOT-compiled artifact, which is registered alongside the wasm so the cell can be placed on a matching runtime. Use `--tag` to require such a placement. Applies to cell crate and cell workspace deployments. Ignored for app suite deployments (set `platform` per class in the app spec instead), `.nest` bundles, and `.wasm` binaries, which are deployed as-is. `--target TARGET` Cargo target to build: `lib` or the name of a binary declared in `Cargo.toml`. When omitted, auto-selects: - Exactly one binary - use it. - No binaries, exactly one library - use the library. - Otherwise - error and name one explicitly. Applies to cell crate and cell workspace deployments. Ignored for app suite deployments - use `target` per class in the app spec instead. `--init PAYLOAD` Initialization arguments delivered to the cell's initialization handler on deploy. Encoded as JSON by default - a value that is not valid JSON is automatically wrapped as a JSON string. Pass `--raw` to deliver raw bytes instead. Only applies to single-cell (`.wasm` or crate) deploys - set `init` per instance in the app spec for application suites. `--raw` Decodes the `--init` payload as a hex string (an optional `0x` prefix is allowed) and delivers those raw bytes as-is, bypassing JSON encoding. Use this when the initialization handler expects a non-JSON wire format. Requires `--init`. `--init-file PATH` Path to a file that contains the initialization arguments passed to the cell's initialization handler. The file content format must match what the cell's initialization handler expects - JSON by default. Mutually exclusive with `--init`. Only applies to single-cell (`.wasm` or crate) deploys - set `init_file` per instance in the app spec for application suites. `--policy POLICY` Restart policy for the root cells this deployment creates. One of: - `never` (the default) - a dead root stays dead. - `on-error` (also spelled `onerror`) - restart on an abnormal exit: a crash, a spawn failure, node loss, or a non-zero stop code. A clean self-stop is terminal. - `always` - restart on any exit. Only an operator terminate or a cascade teardown is terminal. The crash-loop bounds keep their defaults (at most 5 restarts per 60s, 1s apart). To tune them, declare [`restart`](../01_configuration/02_cell-and-application-configuration.md#restart) per instance in the app spec instead. Only roots are restarted - a cell spawned by another cell recovers through its parent's cell-lost handler, not this policy. How it is applied depends on what is being deployed: - **Cell**, **workspace**, **`.nest` bundle** - applied to every root the deployment creates. - **Application specification file** - applied to every instance, replacing any `restart` the specification declares. Each instance whose declared policy is discarded is named in a warning. - **Bridge** - ignored with a warning; bridges have no restart policy. `-v` / `--verbose` - Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Deploy a cell under a specific name: ```bash myrmic deploy ./my-cell --name my-cell-name ``` 2. Deploy a cell with placement tags: ```bash myrmic deploy ./my-cell --tag my-tag-1 --tag my-tag-2 ``` 3. Deploy a `.wasm` binary (give it a clean SRN with `--name`, or it registers as `my-cell.wasm`): ```bash myrmic deploy ./my-cell.wasm --name my-cell ``` 4. Deploy an application suite: ```bash myrmic deploy ./my-app/app_specs.yml ``` 5. Deploy a pre-built application suite: ```bash myrmic deploy ./my-app/myrmic.nest ``` 6. Deploy an MQTT or HTTP bridge: ```bash myrmic deploy ./my-bridge.yml ``` 7. Deploy a cell with init arguments: ```bash myrmic deploy ./my-cell --init '{"greeting":"hello"}' ``` 8. Deploy a cell with raw (non-JSON) init arguments: ```bash myrmic deploy ./my-cell --init 0xdeadbeef --raw ``` 9. Deploy a cell with init arguments from a file: ```bash myrmic deploy ./my-cell --init-file ./init ``` 10. Deploy a cell built for an embedded platform: ```bash myrmic deploy ./my-cell --platform riscv32imac --tag esp32c6 ``` 11. Deploy a cell that is restarted after a crash: ```bash myrmic deploy ./my-cell --policy on-error ``` # myrmic gateway ## Name `myrmic gateway` - Start a swarm gateway node ## Synopsis ``` myrmic gateway [OPTIONS] ``` ## Description Start a minimal swarm gateway node. The gateway exposes the swarm to the external world - it provides HTTP and WebSocket endpoints for external clients to send commands and publish events to cells, and serves static web assets from the blob store. A gateway can also run embedded inside a Myrmic runtime - see [runtime configuration](../01_configuration/01_runtime-configuration.md#gateway). The gateway serves no application of its own. Cells declare how they should be served, and every gateway in the network picks the routes up from the shared route registry and serves them alike. ### Cell-declared routes A cell declares the routing configuration by calling `myrmic_sdk::gateway::mount`, usually from its `init` handler: ```rust #[myrmic_sdk::init] fn init(md: Metadata) -> myrmic_sdk::Result<()> { let assets = myrmic_sdk::gateway::assets(md.id); assets.put("/index.html", include_bytes!("../dist/index.html"))?; myrmic_sdk::gateway::mount("/chat") .api("/api") // HTTP: GET opens the event stream, POST sends a message .ws("/ws") // WebSocket upgrade path .index("/index.html") .bind() .map_err(<&'static str>::from)?; Ok(()) } ``` Serving assets is as easy as just uploading them to the blob-store, with a convenience function via (`myrmic_sdk::gateway::assets`). The cell can populate the store however it likes. (compiled in with `include_bytes!`, fetched from another cell, or written at runtime.) The lifetime of the routing configuration is tied to the cell that declared it. If the owning cell goes, the routing config does as well. By default, mounts are first-come. A cell may re-mount its own path freely, but mounting a path another cell holds will fail. A common pitfall is when embedding assets into the cell, you might need to increase the memory limits acoordingly (see [Cell and Application Configuration](../01_configuration/02_cell-and-application-configuration.md)). ### Routing configuration As mentioned, the default configuration for a gateway acts on a first-come basis. The gateway can, however, declare a routing file, which is monitored, and acts as an authority. It can declare which cell owns which routes, and OIDC configuration. ```json { "routes": { "/chat": { "srn": "chatty", "oidc": { "application_base_url": "https://chat.example.org", "issuer": "https://id.example.org/realms/myrmic", "client_id": "chatty", "client_secret": "…", "scopes": [ "openid", "profile", "email" ] } } } } ``` When a `routes` block is declared, it acts as an allow-list. Only serving mounts that appear in this block. This permits the gateway administator to control what resources should be accessible. The `srn` pins it to a specific cell, but can be omitted. The `oidc` block enables OIDC support for that route, and will only permit users that have the correct permissions. ## Options `-p` / `--port PORT` TCP port to bind the gateway on. Defaults to `8080`. `--routing PATH` Path to the routing configuration as described above. Without it, there's no restrictions in place. `--over-https` Serve behind HTTPS: session cookies are marked `Secure`, so browsers only send them back over TLS. Set this whenever a TLS terminator sits in front of the gateway. `--session-inactivity DURATION` How long a session may sit idle before it expires, written as a human duration (`30s`, `2m`, `1h`). Defaults to two minutes, and is never shorter than two seconds. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Start the gateway on the default port: ```bash myrmic gateway ``` 2. Start the gateway on a custom port: ```bash myrmic gateway --port 9090 ``` 3. Serve only the routes in a configuration file, behind a TLS terminator, with a longer idle window: ```bash myrmic gateway --routing ./routing.json --over-https --session-inactivity 15m ``` # myrmic network status ## Name `myrmic network status` - Show swarm nodes Aliases: `info` ## Synopsis ``` myrmic network status [OPTIONS] myrmic network [OPTIONS] ``` ## Description Lists all connected hosts in the swarm, their identifiers, roles and the swarm topology. Since the swarm uses [Zenoh](https://zenoh.io) for messaging, runtimes appear as peers or routers depending on how they were configured at startup - see [`zenoh` in the runtime configuration](../../01_configuration/01_runtime-configuration.md#zenoh-advanced). `status` is the default subcommand, so `myrmic network` accepts the same arguments directly. In a terminal the listing is live: it refreshes every `--interval` until interrupted with Ctrl+C, and the last state stays on screen afterwards. A node that joins fades in green; a node that leaves fades out struck through in red before its row goes. If a refresh fails, the previous listing stays up and the error is shown above it until the next refresh succeeds. When the output is not a terminal (piped into another command, say) the listing is printed once, as if `--once` had been given. ## Options `--once` Print the listing once and exit instead of refreshing until interrupted. `--interval DURATION` Time between refreshes while live, e.g. `500ms`, `2.5s`, `1m`. Defaults to `2.5s`. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Watch the swarm nodes: ```bash myrmic network ``` 2. Print the nodes once: ```bash myrmic network status --once ``` # myrmic new ## Name `myrmic new` - Scaffold a new cell or ESP32 firmware crate ## Synopsis ``` myrmic new [OPTIONS] ``` ## Description Create a new crate at `PATH`, wired up against peeriot's `myrmic_sdk` and pinned to the myrmic version in use. What is scaffolded depends on `--firmware`: | Flags | Scaffolds | |---|---| | *(none)* | A **cell** crate — a `Cargo.toml`, a `.gitignore`, and a minimal counter cell in `src/lib.rs`. | | `--firmware[=]` | An **ESP32 firmware** crate with the chip as its default feature, and that chip's `partitions.toml`. Build and flash it with [`myrmic build`](03_build.md) / `myrmic flash`. | Signal Layer projects and modules are scaffolded by [`myrmic signal-layer`](16_signal-layer/01_new.md) instead. ## Options `-f`, `--firmware[=]` Scaffold a firmware crate instead of a cell. `` is one of `esp32c5`, `esp32c6`, `esp32c61`, and becomes the crate's default chip feature; the manifest itself targets the whole family (`firmware = "esp32"`). The value requires the `=` form (`--firmware=esp32c6`); a bare `--firmware` defaults to `esp32c6`. `--sdk ` (alias `--repo`) Where the generated crate resolves the SDK crates from. Accepts a path to a local checkout (path dependencies — no network) or a version/revision (a git or registry dependency). Defaults to the revision the CLI was built from. `-n`, `--name ` Set the crate name inside `Cargo.toml`. Defaults to the directory name from `PATH`. `--timeout ` How long to wait before giving up, e.g. `2s`, `500ms`, `1m30s`. `-v` / `--verbose` Verbose mode; repeat (`-vv`) for more detail. `-h`, `--help` Print help information. ## Examples Create a cell: ```bash myrmic new my-cell ``` Scaffold an ESP32-C6 firmware: ```bash myrmic new --firmware=esp32c6 my-fw ``` ## See also - [First Steps with the Signal Layer](../../04_tutorials/04_first-steps-signal-layer.md) - a tutorial that scaffolds a pipeline, a cell, and a firmware. - [`myrmic signal-layer new`](16_signal-layer/01_new.md) - a Signal Layer pipeline project, on Linux or into an ESP32 firmware. - [`myrmic build`](03_build.md), [`myrmic deploy`](05_deploy.md) # myrmic platforms ## Name `myrmic platforms` - List available build platforms ## Synopsis ``` myrmic platforms [OPTIONS] ``` ## Description List all build platforms available in this version of the CLI. Each line shows the platform name and any accepted aliases. Use any platform listed here with `--platform` in [`myrmic build`](03_build.md) and [`myrmic deploy`](05_deploy.md). ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Check which platforms are available before building: ```bash myrmic platforms ``` # myrmic publish ## Name `myrmic publish` - Publish an event Aliases: `event`, `pub` ## Synopsis ``` myrmic publish [OPTIONS] [NAME] [PAYLOAD] ``` ## Description Publish an event. Unlike [`myrmic send`](08_send.md), publish is a broadcast - it is not targeted at a specific cell and does not wait for a response. - `NAME` - required. Specifies the event name. - `PAYLOAD` - optional. Specifies data to publish with the event. How the value is encoded is described in [Payload Encoding](#payload-encoding). ## Options `--raw` Decodes the payload as a hex string (an optional `0x` prefix is allowed) and publishes those raw bytes as-is, bypassing JSON encoding. Use this when the event handler expects a non-JSON wire format. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Payload Encoding By default, the payload is sent as JSON. A value that is not valid JSON is automatically wrapped as a JSON string: | Input | Sent as | | --------------- | ------------------------------ | | `{"count": 1}` | JSON object `{"count":1}` | | `[1, 2, 3]` | JSON array `[1,2,3]` | | `42` | JSON number `42` | | `true` | JSON boolean `true` | | `hello` | JSON string `"hello"` | Pass `--raw` to publish raw bytes instead. The payload is decoded as a hex string (an optional `0x` prefix is allowed) and the resulting bytes are sent as-is, with no JSON encoding. ## Examples 1. Publish an event with no payload: ```bash myrmic publish my_event ``` 2. Publish an event with a JSON object payload: ```bash myrmic publish my_event '{"count": 10}' ``` 3. Publish an event with raw bytes from a hex string: ```bash myrmic publish my_event 0xdeadbeef --raw ``` # myrmic replicate ## Name `myrmic replicate` - Configure which nodes replicate which data Aliases: `replicas`, `replica`, `rep` ## Synopsis ``` myrmic replicate [OPTIONS] [IDENTIFIER] myrmic replicate --file PATH [--prune] ``` ## Description > **Work in progress** > Replication sets replicate a Cell's *data*, not the Cell. The Cell keeps running in one place; after Node loss it does not resume by itself, and this command is not yet covered by the [guarantee contract](../../08_guarantees.md). What it gives you today is the manual failover the [roadmap](../../09_roadmap.md) describes: the data survives the Node, and the Cell can be redeployed where a replica lives. Configures replication sets. An entry pairs something to replicate - an application, a cell, or a scope - with the tags of the nodes that should hold a replica. A node holds a replica when it carries any one of an entry's tags, so the configuration never names a node; it names what a node must be. Which tags a node carries comes from `tags` in its [runtime configuration](../01_configuration/01_runtime-configuration.md) and from [`myrmic tags`](14_tags.md), so retagging a node changes what it replicates without touching the replication sets. With no arguments, lists every configured replication set. Given an identifier but no `--tag`/`--exclude`, shows just that entry. ### Identifiers `IDENTIFIER` names what to replicate. Its shape decides how it is read: - `app:` - every scope of every cell registered to the application ``. Membership is resolved by each node when it applies the configuration, not when the entry is written, so a cell deployed into the application later is picked up without reconfiguration. - A UUID - a cell's SRI, taken verbatim. - Anything else, such as `chatty` or `chatty/server` - a cell's SRN path, folded to its SRI. A path with an empty segment, such as `chatty/`, is rejected. - `scope:`, `scope:/`, or `scope://` - a slice of the [scope hierarchy](../03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md), named directly. A cell entry, whether written as SRI or SRN, covers the cell's own data: its private scope under every schema. Data in a public scope is shared between cells and belongs to none of them, so it is not covered by any cell entry - name it with `scope:` instead. An entry written as an SRN is stored under the cell's SRI, but keeps the name you typed for display. ### Output The listing has one row per target, with the tags configured for it: ``` TARGET TAGS app:chatty region-1, region-2 chatty/server @6483ae05b2c94f10a7d1c35e0f2b8946 scope:application-data/metrics @a0b1c2d3e4f50617 (provisional) ``` A tag marked `(provisional)` is not configured. It names a node that promoted itself into a replica for that scope because no configured replica could be located. It shares the target's row so that a divergence from intent is visible at a glance. With nothing configured and no provisional custody, the command prints `no replication sets configured`. ## Options `--tag TAG` / `-t TAG` A tag of the nodes that should hold a replica. Can be specified multiple times. Added to the tags the entry already has. Requires an identifier. System tags are accepted here: `@` pins a replica to that one runtime. Match is exact, so write the full runtime id as [`myrmic tags`](14_tags.md) shows it. `--exclude TAG` / `-e TAG` A tag to stop replicating on. Can be specified multiple times. Removing an entry's last tag drops the entry. Requires an identifier. `--file PATH` / `-f PATH` Apply a file of `identifier: [tag, ...]` entries, in YAML or JSON. Each identifier's tags replace whatever was configured for it; an empty list drops the entry. Identifiers the file does not mention are left alone. Cannot be combined with an identifier, `--tag`, or `--exclude`. `--prune` With `--file`, also drop every entry the file does not mention. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. All changes of one invocation are written in a single transaction, so a partial apply cannot leave the network disagreeing about what it should be replicating. ## Examples 1. List every replication set: ```bash myrmic replicate ``` 2. Replicate a whole application on the nodes of a region: ```bash myrmic replicate app:chatty -t region-1 ``` 3. Replicate one cell, named by its SRN, on two regions: ```bash myrmic replicate chatty/server -t region-1 -t region-2 ``` 4. Pin a cell's replica to one runtime: ```bash myrmic replicate chatty/server -t @6483ae05b2c94f10a7d1c35e0f2b8946 ``` 5. Replicate a public scope shared by several cells: ```bash myrmic replicate scope:application-data/metrics -t region-1 ``` 6. Stop replicating an application on a region: ```bash myrmic replicate app:chatty -e region-2 ``` 7. Show one entry: ```bash myrmic replicate app:chatty ``` 8. Apply a file and drop every entry it does not mention: ```yaml # replicas.yml app:chatty: [region-1, region-2] chatty/server: ['@6483ae05b2c94f10a7d1c35e0f2b8946'] scope:application-data/metrics: [region-1] ``` ```bash myrmic replicate -f replicas.yml --prune ``` # myrmic runtimes delete ## Name `myrmic runtimes delete` - Stop one or more runtime instances Aliases: `stop`, `remove`, `rm` ## Synopsis ``` myrmic runtimes delete [OPTIONS] [NAME]... ``` ## Description Stop one or more runtime instances by NAME. If a runtime process is gone but its PID file remains, the stale file is removed and a warning is printed. ## Options `--pid-path PATH` For advanced usage, specifies the location of runtime PID files. Use this if you started your runtime with a custom `--pid-path`. Defaults to `$XDG_RUNTIME_DIR/myrmic/` when set, otherwise `/myrmic-/`. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Stop multiple runtimes: ```bash myrmic runtimes delete runtime-1 runtime-2 ``` # myrmic runtimes list ## Name `myrmic runtimes list` - List Myrmic runtime instances ## Synopsis ``` myrmic runtimes list [OPTIONS] ``` ## Description List runtime instances started by the Myrmic CLI. Shows the name, status (`running`, `stale`, or `invalid`), and PID of each. ## Options `--pid-path PATH` For advanced usage, specifies the location of runtime PID files. Pass a directory to list all of them, or a specific `.pid` file to inspect a single one. Use this if you started your runtime with a custom `--pid-path`. Defaults to `$XDG_RUNTIME_DIR/myrmic/` when set, otherwise `/myrmic-/`. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. List all runtime instances: ```bash myrmic runtimes list ``` # myrmic runtimes start ## Name `myrmic runtimes start` - Start a Myrmic runtime Aliases: `run` ## Synopsis ``` myrmic runtimes start [OPTIONS] [PATH] ``` ## Description Start a Myrmic runtime. Runs in the foreground by default. Once the runtime can run cells, it logs a readiness line: ```text INFO runtime "" ready () ``` `PATH` is an optional YAML configuration file for the runtime. If not provided, the runtime starts with the built-in default configuration. See [Runtime Configuration](../../01_configuration/01_runtime-configuration.md) for all options available in the configuration file. ## Options `--name NAME` Sets the runtime instance name. Defaults to `default`. `--tag TAG` / `-t TAG` Adds a capability tag to this runtime instance. Can be specified multiple times to add multiple tags. Merged with any tags in the configuration file. `--detached` / `-d` Start the runtime as a background daemon. The command returns once the runtime is ready, so a deploy right after it can place cells on it. If the runtime exits before it is ready, the command fails and names the directory with its logs. `--pid-path PATH` For advanced usage, specifies the location of the runtime PID file. Pass a directory to place it inside as `.pid`, or a specific path to use as the PID file directly. Defaults to `$XDG_RUNTIME_DIR/myrmic/` when set, otherwise `/myrmic-/`. `--tmp` Use an ephemeral in-memory database that is discarded when the runtime stops. Overrides any database directory set in the configuration file. Without this, the runtime uses a persistent database under the data folder, keyed by its stable node id. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Start a runtime with a custom name in the background: ```bash myrmic runtimes start --name my-runtime --detached ``` 2. Start a runtime with capability tags: ```bash myrmic runtimes start --tag my-tag-1 --tag my-tag-2 ``` 3. Start a runtime from a configuration file: ```bash myrmic runtimes start ./my-runtime.yml ``` 4. Start a throwaway runtime with an in-memory database: ```bash myrmic runtimes start --tmp ``` # myrmic send ## Name `myrmic send` - Send a command to a deployed cell Aliases: `command`, `cmd` ## Synopsis ``` myrmic send [OPTIONS] [SRI/SRN] [NAME] [PAYLOAD] ``` ## Description Send a command to a deployed cell. Commands are fire-and-forget - no response is returned. - `SRI/SRN` - required. Identifies the target cell, either by its SRI (UUID) or by its SRN name. - `NAME` - required. Specifies the command to invoke. - `PAYLOAD` - optional. Specifies data to pass to the command. How the value is encoded is described in [Payload Encoding](#payload-encoding). A trace ID is printed - use it with [`myrmic telemetry traces`](12_telemetry/02_traces.md) to trace the request. ## Options `--raw` Decodes the payload as a hex string (an optional `0x` prefix is allowed) and sends those raw bytes as-is, bypassing JSON encoding. Use this when the command handler expects a non-JSON wire format. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Payload Encoding By default, the payload is sent as JSON. A value that is not valid JSON is automatically wrapped as a JSON string: | Input | Sent as | | --------------- | ------------------------------ | | `{"count": 1}` | JSON object `{"count":1}` | | `[1, 2, 3]` | JSON array `[1,2,3]` | | `42` | JSON number `42` | | `true` | JSON boolean `true` | | `hello` | JSON string `"hello"` | Pass `--raw` to send raw bytes instead. The payload is decoded as a hex string (an optional `0x` prefix is allowed) and the resulting bytes are sent as-is, with no JSON encoding. ## Examples 1. Send a command with no payload: ```bash myrmic send my-cell ping ``` 2. Send a JSON object payload: ```bash myrmic send my-cell my_command '{"count": 10}' ``` 3. Send a bare string - it is wrapped as a JSON string automatically: ```bash myrmic send my-cell greet ada ``` 4. Send raw bytes from a hex string, bypassing JSON encoding: ```bash myrmic send my-cell my_command 0xdeadbeef --raw ``` # myrmic signal-layer driver ## Name `myrmic signal-layer driver` - Scaffold a Signal Layer driver module Aliases: `myrmic sl driver` ## Synopsis ``` myrmic signal-layer driver [OPTIONS] --bus ``` ## Description Create a driver module: the crate that talks to a device on a bus and produces the taps a pipeline reads. It is created at `/drivers/` as the crate `-driver`, with a `descriptor.yaml` declaring the driver's configuration and taps, a `src/lib.rs` holding the driver skeleton for the bus, and a stubbed test suite that runs with `cargo test`. `ID` is the module id (`bme280`), not a path; where the crate goes is `--registry-dir`. A module with the id of a driver shipped with myrmic overlays the shipped one wherever its registry is included. A pipeline uses the module by pointing its `build.rs` at the registry directory (`.include("../my-modules")`) and adding the crate to its `Cargo.toml`; the command prints the dependency line to add. ## Options `--bus ` The bus the driver talks over: `i2c` or `spi`. Picks the driver template. Required. `--registry-dir ` Base directory the module is placed under, as `drivers/`. Defaults to the current directory. `-v` / `--verbose` Verbose mode; repeat (`-vv`) for more detail. `-h`, `--help` Print help information. ## Examples Scaffold an I2C driver into a module registry and run its stubbed tests: ```bash myrmic signal-layer driver bme280 --bus i2c --registry-dir ~/my-modules cd ~/my-modules/drivers/bme280 && cargo test ``` ## See also - [Write your own driver](../../../05_guides/11_signal-layer/07_write-your-own-driver.md) - what to fill in after scaffolding. - [Drivers](../../04_signal-layer/03_drivers.md) - the descriptor format and the driver contract. - [`signal-layer new`](01_new.md) - the pipeline project that uses the module. # myrmic signal-layer new ## Name `myrmic signal-layer new` - Scaffold a Signal Layer pipeline project Aliases: `myrmic sl new` ## Synopsis ``` myrmic signal-layer new [OPTIONS] ``` ## Description Create a pipeline project at `PATH`: a `board.yml` describing the hardware, a `pipeline.yml` describing what runs on it, and a crate whose `build.rs` generates the pipeline from the two at build time. Where the pipeline runs depends on `--firmware`: | Flags | Scaffolds | |---|---| | *(none)* | A **Linux pipeline** project: a standalone tokio binary. Build it with [`myrmic build`](../03_build.md), or run it with `cargo run`. | | `--firmware[=]` | An **ESP32 firmware** for the chip with the pipeline generated into its image, plus the chip's `partitions.toml`. Build and flash it with [`myrmic build`](../03_build.md) and `myrmic flash`. | Every scaffold starts with a headless `sim-source` device, so it builds and runs with no hardware attached. The crate depends on every driver and step shipped with myrmic, so any pipeline written against them compiles; only the modules the pipeline uses end up in the binary. Modules of your own come from [`signal-layer driver`](02_driver.md) and [`signal-layer step`](03_step.md). ## Options `-f`, `--firmware[=]` Generate the pipeline into an ESP32 firmware for `` (`esp32c5`, `esp32c6`, `esp32c61`) instead of a Linux pipeline project. The value requires the `=` form (`--firmware=esp32c5`); a bare `--firmware` defaults to `esp32c6`. `--sdk ` (alias `--repo`) Where the generated project resolves the myrmic and Signal Layer crates from. Accepts a path to a local checkout (path dependencies, no network) or a version/revision (a registry or git dependency). Defaults to the revision the CLI was built from. `-n`, `--name ` Set the crate name inside `Cargo.toml`. Defaults to the directory name from `PATH`. `-v` / `--verbose` Verbose mode; repeat (`-vv`) for more detail. `-h`, `--help` Print help information. ## Examples Scaffold a Linux pipeline against a local checkout and run it: ```bash myrmic signal-layer new my-pipeline --sdk ~/myrmic cd my-pipeline && cargo run ``` Scaffold an ESP32-C6 firmware with the pipeline in its image, then flash it: ```bash myrmic sl new --firmware=esp32c6 my-node --sdk ~/myrmic myrmic flash my-node --monitor ``` ## See also - [First Steps with the Signal Layer](../../../04_tutorials/04_first-steps-signal-layer.md) - a tutorial that scaffolds a pipeline, a cell and a firmware. - [Describe your hardware](../../../05_guides/11_signal-layer/01_describe-your-hardware.md) and [Design your pipeline](../../../05_guides/11_signal-layer/02_design-your-pipeline.md) - what to put in the two YAML files. - [`signal-layer driver`](02_driver.md), [`signal-layer step`](03_step.md) - modules of your own. - [Signal Layer reference](../../04_signal-layer.md) - the `board.yml` and `pipeline.yml` formats. # myrmic signal-layer step ## Name `myrmic signal-layer step` - Scaffold a Signal Layer processing step module Aliases: `myrmic sl step` ## Synopsis ``` myrmic signal-layer step [OPTIONS] ``` ## Description Create a step module: the crate that processes the taps of drivers or other steps into new taps. It is created at `/steps/` as the crate ``, with a `descriptor.yaml` declaring the step's configuration, inputs and outputs, a `src/lib.rs` holding the step skeleton, and a stubbed test suite that runs with `cargo test`. The crate depends on `signal-layer-core`, resolved through `--sdk`. `ID` is the module id (`moving-average`), not a path; where the crate goes is `--registry-dir`. A module with the id of a step shipped with myrmic overlays the shipped one wherever its registry is included. A pipeline uses the module by pointing its `build.rs` at the registry directory (`.include("../my-modules")`) and adding the crate to its `Cargo.toml`; the command prints the dependency line to add. ## Options `--registry-dir ` Base directory the module is placed under, as `steps/`. Defaults to the current directory. `--sdk ` (alias `--repo`) Where the module resolves `signal-layer-core` from. Accepts a path to a local checkout (a path dependency, no network) or a version/revision (a registry or git dependency). Defaults to the revision the CLI was built from. `-v` / `--verbose` Verbose mode; repeat (`-vv`) for more detail. `-h`, `--help` Print help information. ## Examples Scaffold a step into a module registry, against a local checkout, and run its stubbed tests: ```bash myrmic signal-layer step moving-average --registry-dir ~/my-modules --sdk ~/myrmic cd ~/my-modules/steps/moving-average && cargo test ``` ## See also - [Write your own step](../../../05_guides/11_signal-layer/08_write-your-own-step.md) - what to fill in after scaffolding. - [Steps](../../04_signal-layer/04_steps.md) - the descriptor format and the step contract. - [`signal-layer new`](01_new.md) - the pipeline project that uses the module. # myrmic tags ## Name `myrmic tags` - Add and remove tags on nodes Aliases: `tag` ## Synopsis ``` myrmic tags [OPTIONS] [NODE]... ``` ## Description Adds and removes tags on running nodes, without restarting them. A node has one set of tags, and it decides two things: which cells may be placed on it (a cell requiring `gpu` only runs on a node carrying `gpu`), and which data it replicates, since a replication set names the tags of the nodes that should hold a replica. A node's configuration gives it the tags it starts with — `tags` in the [runtime configuration](../01_configuration/01_runtime-configuration.md), or `--tag` on [`runtimes start`](04_runtimes/01_start.md). This command carries tags on top of those and drops tags it should not have. Changes are stored per node rather than per plugin, and reach a running node on their own: a Linux runtime applies one within seconds, an embedded node on its next registration round. Until a node has picked a change up, this command shows it as `(pending)` or `(removing)` rather than as fact. With no arguments, lists every node on the network and its tags. Given nodes but no `--tag`/`--exclude`, shows just those nodes. `NODE` names a node by the name it registered under, by its runtime id, or by any unique prefix of that id. A leading `@` is accepted on all three, matching how a replication set pins to one node. Repeat it to retag several nodes at once; all of the changes are written in a single transaction. Tags naming what a node *is* — its platform (`linux`, `esp32c6`), its hardware (`ble`, `gpio`, `psram`), its own `@` — are facts rather than preferences. They can never be removed, and a node keeps them however it is tagged. Excluding one is recorded but has no effect, and the tag keeps its `(removing)` marker for as long as the exclusion stands: only the node knows which of its tags are facts, so this command cannot tell a removal a node has yet to apply from one it will always refuse. `--reset` clears such an exclusion. ## Options `--tag TAG` / `-t TAG` A tag the nodes should carry. Can be specified multiple times. `--exclude TAG` / `-e TAG` A tag the nodes should not carry, whatever its origin — including one from the node's configuration file. Can be specified multiple times. Excluding a tag records that the node must not carry it, rather than merely undoing an earlier `--tag`. Use `--reset` to discard the changes entirely. `--reset` Forget every tag change made to the named nodes, leaving them with the tags their configuration gives them. Cannot be combined with `--tag` or `--exclude`. `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. List every node and its tags: ```bash myrmic tags ``` 2. Tag two nodes as belonging to a region: ```bash myrmic tags -t hello -t region-1 @node-1 @node-2 ``` 3. Stop a node from being treated as part of a region: ```bash myrmic tags -e region-2 @node-3 ``` 4. Show one node, addressed by a prefix of its runtime id: ```bash myrmic tags @6483ae05 ``` 5. Return a node to the tags its configuration gives it: ```bash myrmic tags --reset @node-1 ``` ## See Also - [`network status`](07_network/01_status.md) - shows the same nodes alongside their kind and topology. - [`runtimes start`](04_runtimes/01_start.md) - sets the tags a runtime starts with. # myrmic telemetry debug ## Name `myrmic telemetry debug` - Stream and print live activity from the swarm ## Synopsis ``` myrmic telemetry debug [OPTIONS] ``` ## Description Connects to the swarm and streams live debug information about commands, events, and log records from the swarm cells. Records are printed as they arrive, sorted by timestamp. A command or event waits for the log records around it so it can be sorted between them, for at most a second; then it is printed anyway. Use it during development to get live visibility into what is happening inside the swarm. Each record is one of three types: - **Event** - it holds the event event name, a payload, and a trace ID. - **Command** - it holds the command name, the receiving cell identifier, a payload, and a trace ID. A command is shown while its row is still in the target cell's mailbox; once the cell's handler has consumed it, the command appears through the log lines that handler emits instead. - **Log** - it hold the log level and message. Command and event payloads are decoded as JSON if possible, then as a string, then as raw bytes. ## Options `--id SRI/SRN` Switch to cell view - streams commands and logs for the given cell only, identified by its SRI (UUID) or SRN name. Events are not shown because they are global broadcasts not addressed to any specific cell. `--timeout DURATION` Stop streaming after the given duration, accepts humantime duration string - e.g. `30s`, `5min`, `1h`. When omitted the stream runs until stopped by the user. `--json` Print each debug record as a JSON object. Useful for programmatic processing with tools like [jq](https://jqlang.org). `--level LEVEL` Temporarily raise the log level of cell logs on all connected nodes to `LEVEL` (e.g. `DEBUG`) for the duration of the stream. Only the cell log targets are changed - the rest of the active filter is left untouched - and the previous filter is restored when the stream ends. The command prints the filter it applied and the one it restored. `-v` / `--verbose` Global flag. Controls the CLI's own output verbosity, not the debug stream. `-h`, `--help` Prints help information. ## Examples 1. Stream events and logs from all cells: ```bash myrmic telemetry debug ``` 2. Stream commands and logs for a specific cell, stop after 30 seconds, pipe into jq: ```bash myrmic telemetry debug --id asset.object.0 --timeout 30s --json | jq . ``` # myrmic telemetry logs ## Name `myrmic telemetry logs` - Print log records from the swarm ## Synopsis ``` myrmic telemetry logs [OPTIONS] ``` ## Description Print log records from the swarm's distributed telemetry database. Logs are emitted by cells and swarm nodes - each record includes a timestamp, severity level, and message. ## Options `-t` / `--trace-id TRACE_ID` Filters output to records belonging to a specific trace - for example, the trace ID printed by [`myrmic send`](../08_send.md). `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Print all log records from the swarm: ```bash myrmic telemetry logs ``` 2. Filter logs to a specific trace: ```bash myrmic telemetry logs --trace-id 15f2af9ffee663762108dfec6d7de906 ``` # myrmic telemetry metrics ## Name `myrmic telemetry metrics` - Print the latest metric values from the swarm ## Synopsis ``` myrmic telemetry metrics [OPTIONS] ``` ## Description Print the latest value of every OpenTelemetry metric from the swarm's distributed telemetry database - cell metrics (commands processed, mailbox size) and runtime metrics (CPU, memory, disk). ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Print all current metric values: ```bash myrmic telemetry metrics ``` # myrmic telemetry no-db-retention ## Name `myrmic telemetry no-db-retention` - Disable telemetry database retention ## Synopsis ``` myrmic telemetry no-db-retention [OPTIONS] ``` ## Description Stops writing telemetry to the swarm's internal DB across all connected nodes - this is the default state of a runtime. Applies to data emitted after this command runs - existing records are not affected. Use this when the swarm should not spend storage on telemetry; to record again, run [`myrmic telemetry set-db-retention`](./05_set-db-retention.md). ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Disable automatic data expiry: ```bash myrmic telemetry no-db-retention ``` # myrmic telemetry set-db-retention ## Name `myrmic telemetry set-db-retention` - Set the telemetry database retention period ## Synopsis ``` myrmic telemetry set-db-retention [OPTIONS] [RETENTION] ``` ## Description Turns on telemetry storage in the swarm's internal DB and sets how long records are kept, across all connected nodes. Without a retention period (the default) nothing is written to the DB, so this command - or `db_retention` in the runtime configuration - is required before [`myrmic telemetry logs`](./01_logs.md), `traces`, `metrics`, or [`debug`](./07_debug.md) show anything. Applies only to data inserted after this command runs - the already existing records are not affected. The value is not persisted across a runtime restart. `RETENTION` accepts humantime duration string - e.g. `7d`, `1year 6months`. ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Set the retention period to one year and six months: ```bash myrmic telemetry set-db-retention "1year 6months" ``` # myrmic telemetry set-filter ## Name `myrmic telemetry set-filter` - Change the log filter on all connected swarm nodes ## Synopsis ``` myrmic telemetry set-filter [OPTIONS] [FILTER] ``` ## Description Changes the active log filter on all connected swarm nodes without a restart. `FILTER` uses the [`tracing`](https://docs.rs/tracing) crate's [`EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) format - level and target expressions, e.g. `info` or `debug,zenoh=off`. `FILTER` **replaces** the node's whole filter; it is not merged into the one the node started with. A plain `zenoh=off` therefore also silences the two targets that report a node moving to a new address, which the shipped configurations carve out on purpose. Carry them with it: ```text debug,zenoh=off,zenoh::net::runtime::interface_monitor=debug,zenoh::net::runtime::orchestrator=info ``` See [Addresses that change](../../../11_security.md#addresses-that-change) for what those targets report. ## Options `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Set the log level to info: ```bash myrmic telemetry set-filter "info" ``` 2. Set debug logging and silence the `zenoh` crate, apart from the targets that report an address change: ```bash myrmic telemetry set-filter "debug,zenoh=off,zenoh::net::runtime::interface_monitor=debug,zenoh::net::runtime::orchestrator=info" ``` # myrmic telemetry traces ## Name `myrmic telemetry traces` - Export swarm traces as JSON ## Synopsis ``` myrmic telemetry traces [OPTIONS] ``` ## Description Export OTel spans from the swarm's distributed telemetry database as JSON, viewable in [Perfetto](https://ui.perfetto.dev) or Chrome's `chrome://tracing`. ## Options `-t` / `--trace-id TRACE_ID` Filters output to spans belonging to a specific trace - for example, the trace ID printed by [`myrmic send`](../08_send.md). `-v` / `--verbose` Verbose mode, shows more detail about what the command is doing. Useful for debugging. Can be set to `-vv` for even more detail. `-h`, `--help` Prints help information. ## Examples 1. Export all traces: ```bash myrmic telemetry traces ``` 2. Export spans for a specific trace: ```bash myrmic telemetry traces --trace-id 15f2af9ffee663762108dfec6d7de906 ``` --- sidebar_label: Myrmic SDK --- # Myrmic SDK The Myrmic SDK is the Rust library for writing cells. Each page covers one topic: what it is for, the operations it offers, an example, and how it behaves. Use it when you know what you want to do and need the exact operations, behavior, or limits. ## Cell model - [Cell initialization](03_myrmic-sdk/01_cell-model/01_cell-initialization.md) - Prepare a cell before it starts handling messages. - [Cell identity and metadata](03_myrmic-sdk/01_cell-model/02_identity-and-metadata.md) - Address a cell by its identity, and read the metadata of each handler invocation. ## Messaging - [Commands](03_myrmic-sdk/02_messaging/01_commands.md) - Receive and send directed, named messages between cells. - [Callbacks](03_myrmic-sdk/02_messaging/02_callbacks.md) - Name a handler to receive the answer to a command. - [Events](03_myrmic-sdk/02_messaging/03_events.md) - Publish named messages and receive them through event handlers. - [Message encoding](03_myrmic-sdk/02_messaging/04_message-encoding.md) - Encode typed payloads, raw bytes, empty messages, and custom wire formats. ## Scheduling and time - [Delayed handler invocations](03_myrmic-sdk/03_scheduling-and-time/01_delayed-handler-invocations.md) - Schedule a command handler to run once after a delay and cancel it when required. - [Periodic handler invocations](03_myrmic-sdk/03_scheduling-and-time/02_periodic-handler-invocations.md) - Invoke a command handler on a recurring period, optionally after an initial delay. - [Clock, uptime, and pausing](03_myrmic-sdk/03_scheduling-and-time/03_clock-and-wait.md) - Read the current time, read how long a node has been running, and pause a handler. ## Cell lifecycle - [Cell classes and spawning](03_myrmic-sdk/04_cell-lifecycle/01_cell-classes-and-spawning.md) - Declare child classes and create supervised or detached cells at runtime. - [Cell termination](03_myrmic-sdk/04_cell-lifecycle/02_cell-termination.md) - Terminate another cell or deliberately stop the current cell. - [Cell monitoring](03_myrmic-sdk/04_cell-lifecycle/03_cell-monitoring.md) - Receive structured notifications when a supervised child cell is lost. - [Runtime environment](03_myrmic-sdk/04_cell-lifecycle/04_runtime-environment.md) - Read the effective tag set and id of the runtime hosting the cell. ## State and storage - [Storage scopes](03_myrmic-sdk/05_state-and-storage/01_storage-scopes.md) - Scope every operation on the runtime database, private to one cell or public and shared. - [Transient state](03_myrmic-sdk/05_state-and-storage/02_transient-state.md) - Hold a value in the cell's WebAssembly memory for as long as the cell runs. - [Persistent cell state](03_myrmic-sdk/05_state-and-storage/03_persistent-state.md) - Store, load, mutate, and upsert one typed value that lives in the persistent runtime database. - [Key-value store](03_myrmic-sdk/05_state-and-storage/04_key-value-store.md) - Store many typed values beneath a shared prefix, and read them by prefix. - [Table store](03_myrmic-sdk/05_state-and-storage/05_table-store.md) - Keep a named collection of values of one type, each under a key, and read them in key order. - [Time-series store](03_myrmic-sdk/05_state-and-storage/06_time-series-store.md) - Append timestamped measurements and query samples by series, range, limit, and order. - [Semantic store](03_myrmic-sdk/05_state-and-storage/07_semantic-store.md) - Run SPARQL update and select queries over RDF triples. - [Blob store](03_myrmic-sdk/05_state-and-storage/08_blob-store.md) - Store, read, list, rename, and delete binary content held under file-like paths. ## External systems - [Gateway routes](03_myrmic-sdk/06_external-systems/01_gateway-routes.md) - Expose a swarm to HTTP clients under a URL path, over plain HTTP or a WebSocket. - [Gateway assets](03_myrmic-sdk/06_external-systems/02_gateway-assets.md) - Serve static files from a cell's blob storage on a gateway route. - [Bridges](03_myrmic-sdk/06_external-systems/03_bridges.md) - Connect a cell to an MQTT broker or an HTTP service outside the swarm. ## Signal Layer (I/O) - [Signal taps](03_myrmic-sdk/07_signal-io/01_signal-taps.md) - Read a Signal Layer input by name, either its latest value or its queued events. - [Signal outlets](03_myrmic-sdk/07_signal-io/02_signal-outlets.md) - Drive a device through a named Signal Layer output, writing a typed value or raw bytes. ## Bluetooth Low Energy - [BLE scanning and discovery](03_myrmic-sdk/08_bluetooth-low-energy/01_ble-scanning.md) - Scan for peripherals, filter advertisements, and stop an active scan. - [BLE connections and service discovery](03_myrmic-sdk/08_bluetooth-low-energy/02_ble-connections.md) - Establish a peripheral connection, inspect discovered services, and disconnect explicitly. - [BLE characteristic reads and writes](03_myrmic-sdk/08_bluetooth-low-energy/03_ble-characteristic-io.md) - Read and write GATT characteristics through a host-managed connection. - [BLE notifications and subscriptions](03_myrmic-sdk/08_bluetooth-low-energy/04_ble-notifications.md) - Subscribe to GATT notifications, receive payloads through callbacks, and unsubscribe. - [BLE pairing](03_myrmic-sdk/08_bluetooth-low-energy/05_ble-pairing.md) - Secure a link with a passkey when a peripheral requires it. ## Hardware - [GPIO](03_myrmic-sdk/09_gpio.md) - Acquire numbered pins, perform digital I/O, and wait for levels or edges. ## Diagnostics - [Logging](03_myrmic-sdk/10_logging.md) - Log a message at one of five levels. - [Errors](03_myrmic-sdk/11_error-model.md) - See how a handler fails, what an error carries, and what the runtime rolls back. # BLE characteristic reads and writes > **Availability:** Linux and embedded runtimes, on a node with Bluetooth hardware > > **Build-time requirement:** The Myrmic runtime has to be compiled with BLE support: > > - [Install the CLI with the `ble` feature on Linux](../../../01_quickstart/01_installation.md#with-ble-support) > - [Build the ESP32 firmware with the `ble` feature](../../../01_quickstart/02_installation-embedded.md#with-ble-support) A peripheral publishes its data as characteristics, grouped into services, so a characteristic is named by two UUIDs: its service, and its own. A cell reads a characteristic to get its value, and writes one to set it. Reading and writing do not block the cell's handler. The call returns immediately, and the outcome arrives to a specified handler. ## When to use Read or write a characteristic once a connection exists and the characteristic has been found. Subscribe instead when the peripheral should send each new value as it produces it, rather than being asked every time. ## Operations - Look up a characteristic on a connection. - Read its value, and receive the outcome in a handler. - Write a value, and receive the outcome in a handler. - Write a value without waiting for a confirmation. ## Example ```rust use myrmic_sdk::ble::{Characteristic, Connection, Uuid}; use myrmic_sdk::types::ble::{ReadOutcome, WriteOutcome}; use myrmic_sdk::{Callback, Metadata}; fn exchange(connection: &Connection, service: Uuid, char_uuid: Uuid) -> myrmic_sdk::Result { // Only characteristics found while connecting can be looked up. let target: Characteristic = connection .characteristic(service, char_uuid) .ok_or("characteristic not discovered")?; // If the connection is already gone, this returns an error and // read_complete never runs. connection.read(target, Callback::of::())?; connection.write(target, &[0x01], Callback::of::())?; // Nothing reports the outcome of this one, including its failure. connection.write_no_response(target, &[0x00])?; Ok(()) } #[myrmic_sdk::cmd] fn read_complete(_md: Metadata, outcome: ReadOutcome) -> myrmic_sdk::Result { // The outcome names the characteristic, so one handler can serve several. match outcome.value { Ok(bytes) => myrmic_sdk::info!("read {} bytes", bytes.len())?, Err(error) => myrmic_sdk::error!("read failed: {error:?}")?, } Ok(()) } #[myrmic_sdk::cmd] fn write_complete(_md: Metadata, outcome: WriteOutcome) -> myrmic_sdk::Result { if let Err(error) = outcome.result { myrmic_sdk::error!("write failed: {error:?}")?; } Ok(()) } ``` ## Behavior ### Normal Every outcome names the characteristic it came from, so one handler can serve several of them. A write that reports its outcome waits for the peripheral to confirm it. A write without a confirmation does not, and succeeding only means the runtime took the request. ### Errors The outcome of a read or a write reports either that the characteristic does not allow it, or that it needs a paired link first. ### Limits A write without a confirmation reports nothing, not even a refusal. Neither runtime sets a maximum value size, a deadline, or a retry. A cell that needs a deadline or a retry has to implement it itself. The embedded runtime handles one Bluetooth request at a time, so the next one waits for it. The Linux runtime runs them concurrently, so their outcomes can reach the handlers in a different order than the calls. A characteristic belongs to the connection it was looked up on. Once that connection ends, reads and writes on it fail. ## API documentation For read and write signature, see [`Connection`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.Connection.html) and [`Characteristic`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.Characteristic.html). # BLE connections and service discovery > **Availability:** Linux and embedded runtimes, on a node with Bluetooth hardware > > **Build-time requirement:** The Myrmic runtime has to be compiled with BLE support: > > - [Install the CLI with the `ble` feature on Linux](../../../01_quickstart/01_installation.md#with-ble-support) > - [Build the ESP32 firmware with the `ble` feature](../../../01_quickstart/02_installation-embedded.md#with-ble-support) A connection links a cell to a Bluetooth peripheral. It carries the peripheral's address and the GATT services and characteristics found while connecting. ## When to use Use a connection when a cell has to read, write, or subscribe to a peripheral's characteristics. Scan first when the address is not known yet. ## Operations - Start a connection to an address, naming a handler for success and one for failure. - Look up a characteristic by its service UUID and its own UUID. - Read the connected peripheral's address. - Disconnect. ## Example ```rust use myrmic_sdk::ble::{uuid128, Address, Connection, Disconnect, Uuid}; use myrmic_sdk::types::ble::DisconnectReason; use myrmic_sdk::{Callback, InMemory, Metadata}; /// Nordic NUS service, and the characteristic the peripheral sends on. const NUS_SERVICE: Uuid = uuid128!("6E400001-B5A3-F393-E0A9-E50E24DCCA9E"); const TX_CHAR: Uuid = uuid128!("6E400003-B5A3-F393-E0A9-E50E24DCCA9E"); static CONNECTION: InMemory> = InMemory::empty(); fn connect(address: Address) -> myrmic_sdk::Result { myrmic_sdk::ble::connect(address) .on_connected(Callback::of::()) .on_disconnected(Callback::of::()) // Returns once the attempt has started. The outcome arrives at one of // the two handlers above. .initiate()?; Ok(()) } #[myrmic_sdk::cmd] fn connected(_md: Metadata, connection: Connection) -> myrmic_sdk::Result { // A characteristic is named by two UUIDs: its service, and its own. let _characteristic = connection .characteristic(NUS_SERVICE, TX_CHAR) .ok_or("the peripheral has no such characteristic")?; // Reads, writes, and subscriptions all need this, so it is kept. CONNECTION.with(|slot| *slot = Some(connection))?; Ok(()) } #[myrmic_sdk::cmd] fn stop(_md: Metadata) -> myrmic_sdk::Result { // This does not trigger the `on_disconnected` handler. if let Some(connection) = CONNECTION.with(Option::take)? { connection.disconnect()?; } Ok(()) } #[myrmic_sdk::cmd] fn disconnected(_md: Metadata, disconnect: Disconnect) -> myrmic_sdk::Result { match disconnect.reason() { // The attempt never got a link. DisconnectReason::ConnectionFailed => myrmic_sdk::warn!("could not connect")?, // The peripheral closed the link. DisconnectReason::RemoteClosed => myrmic_sdk::warn!("the peripheral left")?, // This node closed it, without the cell asking. DisconnectReason::LocalClosed => myrmic_sdk::warn!("the node closed the link")?, other => myrmic_sdk::warn!("disconnected: {other:?}")?, } CONNECTION.with(|slot| *slot = None)?; Ok(()) } ``` ## Behavior ### Normal Connecting does not block the cell's handler. The call returns immediately and the outcome arrives later: the specified success handler runs when the link is up and its services are ready, and the specified failure handler runs when the attempt fails or a live link drops. The services and characteristics are found while connecting, and a lookup searches only those. ### Errors Starting fails when either handler is missing, and when the runtime cannot use the Bluetooth adapter. A failure after that point reaches the failure handler with a reason: the attempt failed, the peripheral closed the link, or the cell's own node closed it. ### Limits Letting go of a connection does not disconnect the peripheral. A connection stops working when the runtime restarts. The embedded runtime allows one connection at a time on a node, and refuses another. The Linux runtime allows any number. On the embedded runtime, starting a scan closes an open connection, and the failure handler runs with the reason that the cell's own node closed it. Some runtimes require a scan before a connection, and refuse a direct attempt. Scanning first works everywhere. ## API documentation For every connection method and disconnect reason, see [`connect`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/fn.connect.html), [`ConnectBuilder`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.ConnectBuilder.html), [`Connection`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.Connection.html) and [`Disconnect`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.Disconnect.html). # BLE notifications and subscriptions > **Availability:** Linux and embedded runtimes, on a node with Bluetooth hardware > > **Build-time requirement:** The Myrmic runtime has to be compiled with BLE support: > > - [Install the CLI with the `ble` feature on Linux](../../../01_quickstart/01_installation.md#with-ble-support) > - [Build the ESP32 firmware with the `ble` feature](../../../01_quickstart/02_installation-embedded.md#with-ble-support) With a subscription, a connected peripheral pushes each new value of a characteristic instead of the cell polling it. Subscribing registers a handler, and each value is delivered to it. ## When to use Subscribe for values the peripheral produces on its own. Read the characteristic instead when the cell needs a value only occasionally. ## Operations - Subscribe to a characteristic already looked up on a connection. - Receive each value in a handler, with the characteristic it came from. - Unsubscribe. ## Example ```rust use myrmic_sdk::ble::{Characteristic, Connection, Notification, Subscription}; use myrmic_sdk::{Callback, InMemory, Metadata}; // Unsubscribing later needs this, so it outlives the handlers invocation. static SUBSCRIPTION: InMemory> = InMemory::empty(); fn subscribe(connection: &Connection, characteristic: Characteristic) -> myrmic_sdk::Result { let subscription = connection .subscribe(characteristic, Callback::of::())? .map_err(|_| "the peripheral refused the subscription")?; SUBSCRIPTION.with(|slot| *slot = Some(subscription))?; Ok(()) } #[myrmic_sdk::cmd] fn notification(_md: Metadata, notification: Notification) -> myrmic_sdk::Result { // Each notification carries the characteristic it came from, so one handler // can serve several. myrmic_sdk::info!( "{:?}: {} bytes", notification.characteristic(), notification.data().len() )?; Ok(()) } #[myrmic_sdk::cmd] fn stop(_md: Metadata) -> myrmic_sdk::Result { // Taken out of memory first, so a late value finds nothing to unsubscribe. if let Some(subscription) = SUBSCRIPTION.with(Option::take)? { subscription.unsubscribe()?; } Ok(()) } ``` ## Behavior ### Normal Subscribing blocks the cell's handler until the subscription is set up. The values arrive later. Each value the peripheral sends triggers the handler, carrying the characteristic and the raw bytes. Values stop arriving when the cell unsubscribes and when the connection ends. ### Errors Subscribing fails when: - the connection or the characteristic is gone - the characteristic cannot be subscribed to - the characteristic needs a paired link first - the runtime has no room for another subscription ### Limits Unsubscribing is the cell's job: dropping the handle leaves the subscription running. The embedded runtime allows eight subscriptions on a node. The Linux runtime sets no limit. The embedded runtime drops a value when the cell's queue is full. The Linux runtime holds the value until there is space in the cell's queue, which delays the values behind it. Unsubscribing does not discard values already queued, so the notification handler can still run afterwards. ## API documentation For the subscribe function signature and the notification type, see [`Connection`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.Connection.html), [`Subscription`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.Subscription.html) and [`Notification`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.Notification.html). # BLE pairing > **Availability:** Linux and embedded runtimes, on a node with Bluetooth hardware > > **Build-time requirement:** The Myrmic runtime has to be compiled with BLE support: > > - [Install the CLI with the `ble` feature on Linux](../../../01_quickstart/01_installation.md#with-ble-support) > - [Build the ESP32 firmware with the `ble` feature](../../../01_quickstart/02_installation-embedded.md#with-ble-support) Some peripherals keep their characteristics behind a secured link. Pairing with a passkey secures it. ## Operations - Pair with a passkey. ## Example ```rust use myrmic_sdk::ble::{mac_addr_pub, Address, Connection, Disconnect}; use myrmic_sdk::{Callback, Metadata}; const SENSOR: Address = mac_addr_pub!("C0:98:E5:42:7A:11"); fn connect_sensor() -> myrmic_sdk::Result { myrmic_sdk::ble::connect(SENSOR) .on_connected(Callback::of::()) .on_disconnected(Callback::of::()) .initiate()?; Ok(()) } #[myrmic_sdk::cmd] fn connected(_md: Metadata, _connection: Connection) -> myrmic_sdk::Result { // Pairing needs the connection, so it happens here and not before. myrmic_sdk::ble::set_pair_passkey(123_456)?; Ok(()) } #[myrmic_sdk::cmd] fn disconnected(_md: Metadata, _reason: Disconnect) -> myrmic_sdk::Result { Ok(()) } ``` ## Behavior ### Normal Pairing happens immediately, on the connections that already exist. The embedded runtime pairs its one connection, and the Linux runtime pairs every connection the cell holds. ### Errors Pairing fails when: - no peripheral is connected - the runtime cannot register the passkey - the peripheral rejects the pairing, as when the passkey is wrong ### Limits On the Linux runtime one passkey is stored for the whole node. Any cell that sets a passkey overwrites the stored value, and every pending pairing uses the new one. ## API documentation For the pairing function, see [`set_pair_passkey`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/fn.set_pair_passkey.html). # BLE scanning and discovery > **Availability:** Linux and embedded runtimes, on a node with Bluetooth hardware > > **Build-time requirement:** The Myrmic runtime has to be compiled with BLE support: > > - [Install the CLI with the `ble` feature on Linux](../../../01_quickstart/01_installation.md#with-ble-support) > - [Build the ESP32 firmware with the `ble` feature](../../../01_quickstart/02_installation-embedded.md#with-ble-support) Scanning finds nearby Bluetooth peripherals. The runtime listens for their advertisements and delivers each one to a handler the cell names. Filtering is optional. Scanning does not block the cell's handler and advertisements arrive at a specified handler as they are found. ## When to use Use scanning when a cell has to find a peripheral before connecting to it, or reads what a peripheral advertises without connecting at all. Connect directly when the peripheral's address is already known. ## Operations - Start a scan, and stop it. - Filter by company, by exact local name, or by service UUID. - Scan passively or actively. - Receive each advertisement in a handler, with the peripheral's address and what it advertised. ## Example ```rust use myrmic_sdk::ble::{DiscoveredDevice, DiscoveryFilter, ScanHandle, ScanMode}; use myrmic_sdk::{Callback, InMemory, Metadata}; // The scan outlives the invocation that started it, so its handle is kept in // the cell's memory. static SCAN: InMemory> = InMemory::empty(); fn start_scan() -> myrmic_sdk::Result { // Every condition set has to match for a peripheral to be reported. let filter = DiscoveryFilter { company_id: Some(0x0499), local_name: Some("RuuviTag Pro".try_into()?), service_uuid: None, }; // Active, so peripherals are asked for a scan response as well. let handle = myrmic_sdk::ble::scan( Callback::of::(), Some(filter), ScanMode::Active, )?; SCAN.with(|slot| *slot = Some(handle))?; Ok(()) } #[myrmic_sdk::cmd] fn device_found(_md: Metadata, device: DiscoveredDevice) -> myrmic_sdk::Result { myrmic_sdk::info!("found {}", device.address)?; Ok(()) } #[myrmic_sdk::cmd] fn stop_scan(_md: Metadata) -> myrmic_sdk::Result { // Taken out of memory first, so a late advertisement finds nothing to stop. if let Some(handle) = SCAN.with(Option::take)? { handle.stop()?; } Ok(()) } ``` ## Behavior ### Normal The runtime applies the filter, so only matching peripherals reach the cell. A local name has to match exactly, including its case. A passive scan receives only the primary advertisement. An active scan also asks each peripheral for a scan response, which carries what did not fit in the primary one. A cell runs one scan at a time, and starting another replaces it. Stopping the scan is the cell's job: dropping the handle leaves the scan running. On the embedded runtime a scan and a connection cannot run at the same time. Connecting stops the scan, and starting a scan closes the connection. ### Errors Scanning fails when the runtime cannot use the Bluetooth adapter. ### Limits The Linux runtime supports active scanning only, so a cell that asks for a passive scan gets an active one. An advertisement is bounded, and anything past the bound is dropped rather than reported: a local name of 32 bytes, 4 service UUIDs each 16-bit or 128-bit, 27 bytes of manufacturer data, and 27 bytes of service data. An advertisement is also dropped when the cell's queue is full, so a slow handler loses reports. Stopping does not discard advertisements already queued, so the handler can still run afterwards. A handle does not identify its scan. Stopping with an old handle stops whichever scan is running now. ## API documentation For the filter and scan mode type, see [`scan`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/fn.scan.html), [`ScanHandle`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/ble/struct.ScanHandle.html), [`DiscoveryFilter`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.DiscoveryFilter.html) and [`ScanMode`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/enum.ScanMode.html). # Cell classes and spawning > **Availability:** Linux runtime only A cell class is the deployable definition of a cell: its WebAssembly binary. A running cell can spawn a child from any class registered in the swarm, and each child is a separate instance with its own identity and state. ## When to use Spawn a cell when you only know at runtime that you need it, such as one cell per device a scan finds. Deploy a cell up front when it is always there. ## Operations - Refer to a class. - Spawn a child from that class. - Name the child, or let the runtime name it. - Pass the child an initialization payload. - Require the child to run on a node carrying particular tags. - Set how long the child survives silence from its parent. - Set how long its node may be silent before the child is declared lost. - Spawn the child so it outlives its parent. ## Example ```rust use core::time::Duration; use myrmic_sdk::Metadata; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct WorkerConfig { device: myrmic_sdk::String, } // The deployment resolves this name to the class, so the parent never embeds it. const WORKER: myrmic_sdk::ClassHandle = myrmic_sdk::declare!("worker"); #[myrmic_sdk::cmd] fn add_worker(_md: Metadata) -> myrmic_sdk::Result { let worker = WORKER .new() // Optional. Naming the child gives it the same identity every time. .name("worker-1") // Optional. Decoded by the child's initialization handler. .payload(&WorkerConfig { device: "sensor-1".into() }) // Optional. Only a node carrying this tag may run it. .tag("accelerator") // Optional. If this parent goes quiet, the child is killed after this // long. A longer time lets the child survive a parent restart. .grace(Duration::from_secs(30)) // Optional. If the child's node goes quiet for this long, the child is // declared dead and this parent is told. .deadline(Duration::from_secs(60)) // Optional. The child then outlives this parent, neither is told when // the other is lost, and the grace above no longer applies. // .detached() .spawn()?; myrmic_sdk::info!("spawned {worker}")?; Ok(()) } ``` ## Behavior ### Normal A child's identity comes from its parent and the name it was given, so the same name always means the same child. Spawning that name again fails rather than creating a second one. Letting the runtime name the child produces a new one each time. A child stops when its parent stops, and its loss is reported to that parent. A detached child does neither, and the grace setting does not apply to it. An initialization payload must match what the child's initialization handler expects, and is encoded like any other message. A spawn takes effect immediately. If the handler that spawned the child then fails, its writes and messages are rolled back, but the child stays. ### Errors Spawning fails when: - the class cannot be resolved - the child's identity is already in use - no available node carries the required tags - encoding or deployment fails ## API documentation For every builder option and spawn error, see [`declare`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.declare.html), [`ClassHandle`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.ClassHandle.html), [`SpawnBuilder`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.SpawnBuilder.html) and [`SpawnError`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/enum.SpawnError.html). # Cell monitoring > **Availability:** Linux runtime only A monitor handler tells a parent that one of its supervised children was lost. The notification names the child and explains why. ## When to use Use a monitor handler when a parent must react to a child ending, whether that was deliberate or not. Use commands, callbacks, or events for ordinary application data between cells. ## Operations - Declare the cell's monitor handler. - Read which child was lost, and the local name it was given when spawned. - Distinguish why it was lost: it stopped, it crashed, it was terminated, its node was lost, or it never started. - Read the exit code a child reported when it stopped itself. ## Example ```rust use myrmic_sdk::Metadata; use myrmic_sdk::monitor::{CellLost, LostReason}; #[myrmic_sdk::monitor] fn on_cell_lost(_md: Metadata, loss: CellLost) -> myrmic_sdk::Result { // The name given at spawn, absent when the runtime named the child. Its // identity is always in loss.cell. let child = loss.local_name.as_deref().unwrap_or("unnamed"); match loss.reason { // Stopped itself, so it reached a final state of its own. LostReason::Stopped { code } => { myrmic_sdk::info!("child {} finished: {:?}", child, code)?; } // Ended on its own without stopping, so it may be worth replacing. LostReason::Crashed => { myrmic_sdk::warn!("child {} crashed", child)?; } // Removed by this cell or an ancestor, so no replacement is wanted. LostReason::Terminated => { myrmic_sdk::info!("child {} was terminated", child)?; } // Its node went silent, so the work has to move elsewhere. LostReason::NodeLost => { myrmic_sdk::warn!("child {} lost with its node", child)?; } // Never ran, so spawning again needs the cause fixed first. LostReason::SpawnFailed => { myrmic_sdk::error!("child {} never started: {}", child, loss.cell)?; } } Ok(()) } ``` ## Behavior ### Normal A loss notification arrives through the parent's mailbox, so it survives the parent's node restarting. It is consumed when the handler succeeds, and stays queued for another delivery when the handler fails. The same loss may be reported more than once, so recovery must tolerate a repeat. A notification can arrive before the child has finished being removed, and a child lost with its node is only presumed gone. A child spawned as independent never reports its loss to its former parent, and a root cell has no parent to report to. Only the child itself is reported, never the descendants removed with it. ### Limits A cell can declare only one monitor handler, because the runtime looks for a single entry point by name. A cell that declares none has its notifications dropped. The notification carries no sender; the lost cell is named in the payload. ## API documentation See the API documentation for [`myrmic_sdk::monitor`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/monitor/index.html), which covers the notification type and every loss reason. # Cell termination > **Availability:** Linux runtime only A cell can remove itself or one of its descendants. It can also stop itself and report an optional exit code to its parent. ## When to use Use termination when a cell must remove itself or a descendant. Use self-stop when the cell has reached a deliberate final state of its own. ## Operations - Terminate a cell, identified by either its UUID or its SRN path. - Stop the current cell. - Stop the current cell and report an exit code to its parent. ## Example ```rust use myrmic_sdk::Metadata; #[myrmic_sdk::cmd] fn shut_down(_md: Metadata) -> myrmic_sdk::Result { // The target may be written as a UUID or as an SRN path. myrmic_sdk::terminate_cell("myapp/gateway/worker-1")?; // Reports the code to this cell's parent. Passing nothing reports no code. myrmic_sdk::stop_self(Some(0)); // Nothing after this line is guaranteed to run. Ok(()) } ``` ## Behavior ### Normal Terminating a cell also removes its descendants, except any that were spawned as independent. A cell may only terminate itself or one of its own descendants. Stopping the current cell does the same to its descendants. When the cell has a parent, that parent is told the child stopped, along with the exit code if one was given. Only the named cell's loss is reported, never the descendants removed with it. Removing a cell does not delete what it stored. Termination takes effect immediately. If the handler that asked for it then fails, its writes and messages are rolled back, but the cell is gone. ### Errors Termination fails when: - the target cannot be found, whether the name is malformed or no such cell exists - the target is not the caller or one of its descendants - removing its deployment or its registration fails ### Limits A cell that stops itself is not removed on the spot. The call returns at once and the removal follows on its own, so the cell can be cut off at any point after it and code following the call may never run. Complete any state changes and outgoing messages before stopping, and never rely on that code for cleanup or correctness. ## API documentation For exact signatures and every error, see [`terminate_cell`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.terminate_cell.html), [`stop_self`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.stop_self.html) and [`TerminateError`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/enum.TerminateError.html). # Runtime environment > **Availability:** Linux and embedded runtimes A cell can read facts about the runtime hosting it: the runtime's effective tag set and its id. These describe where the cell landed, not the cell itself. ## When to use Read the runtime tags when a cell must adapt to where it runs, such as choosing a GPIO pin by board or a timer period by whether its node is battery powered. Read the runtime id when a cell needs a stable name for its current host, for instance to report it or to pin later work to the same node. ## Operations - Read the effective tag set of the runtime hosting this cell. - Read the id of the runtime hosting this cell. ## Example ```rust use myrmic_sdk::Metadata; #[myrmic_sdk::cmd] fn describe_host(_md: Metadata) -> myrmic_sdk::Result { // The same tags self-organization uses to place cells. let tags = myrmic_sdk::runtime_tags()?; if tags.iter().any(|t| t == "embedded") { myrmic_sdk::info!("running on an embedded node")?; } // Stable for the lifetime of the runtime process. let id = myrmic_sdk::runtime_id()?; myrmic_sdk::info!("hosted by runtime {id}")?; Ok(()) } ``` ## Behavior ### Normal The tags are the same set self-organization uses to place cells: the runtime's configured tags, any operator retags, and the intrinsic hardware and platform tags, such as `embedded` or the board and soc name. The runtime id is a Zenoh id. It is stable for the lifetime of the runtime process, and is the value a deploy pins to through the `@` system tag. ### Limits The tag set is read at the moment of the call. A cell placed on another node, or a node retagged after the call, sees a different set, so nothing read here can be assumed to hold later. The runtime id names the current host, not the cell. It changes if the cell is later placed on another runtime, and is not preserved across a runtime restart. ## API documentation For exact signatures and every error, see [`runtime_tags`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.runtime_tags.html) and [`runtime_id`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.runtime_id.html). # Cell initialization > **Availability:** Linux and embedded runtimes An initialization handler prepares a cell before it starts handling messages. The runtime calls it once, and the cell handles nothing until it returns. ## When to use Use an initialization handler when a cell must read data passed at deployment, create initial persistent state, register routes, or schedule work before it handles messages. Omit it when the cell has no setup work. Use a command, event, or monitor handler for work that happens after initialization. ## Operations - Declare one function as the cell's initialization handler. - Receive data passed at deployment as a typed value, or none at all. ## Example ```rust use myrmic_sdk::Metadata; use serde::{Deserialize, Serialize}; // The type is decoded from data passed at deployment // serializable in both directions. #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct Config { sample_period_ms: u64, } #[myrmic_sdk::init] fn init(md: Metadata, config: Config) -> myrmic_sdk::Result { // The metadata carries this cell's own identity. myrmic_sdk::info!("starting {} with period {}", md.id, config.sample_period_ms)?; Ok(()) } ``` ## Behavior ### Normal The runtime calls the handler once, when the cell starts. It supplies the cell's own identity, the data passed at deployment, and for a spawned cell the identity of the cell that spawned it. A root cell has no spawning cell, so that identity is empty. The data is decoded before the handler runs. A handler that declares no payload accepts none. The handler is expected to finish its setup and return. It is not a long-running process. ### Errors Initialization fails when the data passed at deployment does not match the declared type, when a handler that declares no payload receives data anyway, or when the handler itself returns an error. ## API documentation See [`init`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/attr.init.html) in the API documentation. # Cell identity and metadata > **Availability:** Linux and embedded runtimes A cell's identity has two forms: an SRN, the readable name it is deployed under, such as `myapp/fleet`, and an SRI, a UUID that is derived from the SRN. Neither is a network address or a port. The runtime uses the SRI internally. The SRN is human readable, so it is the form users work with when interacting with cells, through the CLI or in the app manifest file. Every handler (command, event or initialization) takes metadata as its first argument. It is what the runtime says about the invocation: the SRI of the cell being invoked, and the SRI of whoever triggered it. ## Operations - Read the SRI of the running cell from the invocation metadata. - Read the SRI of the sender from the same metadata. - Turn a string that names a cell, whether a UUID or an SRN path, into an SRI. - Derive an SRI from an SRN path. - Derive the SRI a child will get from the name it will be spawned under. - Convert an SRI to a UUID and back. ## Example ```rust use myrmic_sdk::{Metadata, Sri, String}; #[myrmic_sdk::cmd] fn inspect(md: Metadata, cell: String) -> myrmic_sdk::Result { // A nil sender means no cell triggered this invocation. if md.sender.is_nil() { myrmic_sdk::info!("{} was invoked externally", md.id)?; } // The payload came from outside, so it may be a UUID or an SRN path. let named = Sri::from_target(&cell) .map_err(|_| "neither a UUID nor a valid SRN path")?; // This SRN is written in the code, so deriving it is enough. let fleet = Sri::of_path("myapp/fleet") .map_err(|_| "invalid SRN path")?; // The SRI this child will get once it is spawned. let sensor = fleet.child("sensor-1") .map_err(|_| "invalid child name")?; // An SRI is a UUID underneath, and converts both ways. let sensor = Sri::from(sensor.as_uuid()); myrmic_sdk::info!("target {named}, sensor {sensor}")?; Ok(()) } ``` ## Behavior ### Normal At initialization the sender is the cell that spawned this one, and is nil only for a root cell. Afterwards it is nil for a command from the CLI, the session's SRI for a command through the gateway, so the cell can reply to it, and the cell's own SRI for a scheduled invocation. A string that parses as a UUID is taken as an SRI unchanged. Anything else is derived as an SRN path. The cell derives an SRI itself internally, without including the runtime. Deriving the same SRN path always produces the same SRI. ### Errors Deriving fails when a segment of the SRN is not a valid name, such as an empty segment or one with a disallowed character. ### Limits An SRI names a cell, not a place. Holding one does not prove that the cell exists, is running, or can be reached. An SRI cannot be turned back into its SRN. Metadata carries those two SRIs and nothing else: not the cell's SRN, not the name of the message being handled, nothing about the payload. ## API documentation For every constructor and conversion, see [`Metadata`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.Metadata.html) and [`Sri`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.Sri.html). # Errors A handler fails only when its code returns an error, either by propagating the error from a call that engages the runtime or by returning an error explicitly. A failed call to the runtime returns `ApiError`, an enum, so the code can match a case and decide what to do. A handler returns `myrmic_sdk::Result`, whose error is a `&'static str`. Across the WebAssembly boundary a handler can only return a number, so the SDK stores the string separately. The runtime logs a handler's failure at error level with the returned string as the message. ## Example ```rust use myrmic_sdk::{ApiError, Metadata, String}; #[myrmic_sdk::cmd] fn stamp(_md: Metadata, label: String) -> myrmic_sdk::Result { if label.is_empty() { // Returned on the cell's own logic. return Err("a label is required"); } // `ApiError` converts into the handler's error type, so `?` propagates it. let taken_at = myrmic_sdk::now()?; // The error type is `&'static str`, so it takes a literal and nothing else. let uptime = myrmic_sdk::uptime().map_err(|_| "the node's uptime is unavailable")?; myrmic_sdk::info!("{label} at {taken_at:?}, node up for {uptime:?}")?; Ok(()) } fn describe(error: ApiError) -> &'static str { match error { // Worth retrying: the runtime cannot serve the call yet. ApiError::NotReady => "not ready", // The rest will fail again. ApiError::Usage => "incorrect use", ApiError::Serde(context) => context, ApiError::TimedOut => "timed out", ApiError::BufferTooSmall => "buffer too small", ApiError::SemQuery => "invalid query", // Every code the SDK does not name arrives here. ApiError::UnknownErrorCode(code) => { let _ = code; "unknown" } } } ``` ## Behavior ### Normal The failure is logged at error level, with the returned string as the message. The runtime rolls back part of what the handler did. Rolled back: - everything written to storage - every command and event the handler sent - the message the handler was given Left in place: - every cell the handler spawned, and every cell it terminated - every timer it armed or cancelled - everything it logged - everything it wrote to an outlet, a pin, or a Bluetooth peripheral Afterwards, what happens to the invocation depends on what it was: - **a command** - delivered again, so a command handler has to be idempotent - **an event** - not delivered again, so the event is lost - **a scheduled invocation** - lost, and the schedule keeps running - **a monitor notification** - delivered again - **initialization** - the deployment fails with that error message, and the cell does not start ## API documentation For every error variant, see [`ApiError`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/enum.ApiError.html). For the handler's result type, see [`Result`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/type.Result.html). # Bridges > **Availability:** Linux runtime only A bridge connects a cell to a system outside the swarm: an MQTT broker or an HTTP service. The bridge is declared in a specification file, and the cell reaches it through a client generated from that file. ## Key concepts A specification file names a broker for MQTT, or a base URL for HTTP, and lists what can be exchanged: - for MQTT, the ingress topics the cell receives and the egress topics it publishes - for HTTP, the endpoints with their method, path and body To understand and learn how to write a bridge specification file, see [Bridge configuration](../../01_configuration/05_bridge-configuration.md). ## Operations - Generate a client and its types from one or more specification files. - Bind a client to the bridge it talks to. - Publish to an egress topic, or call an HTTP endpoint with a callback for its reply. - Receive an MQTT ingress topic in an event handler. ## Example ```rust use myrmic_sdk::{Callback, Metadata}; // Read at compile time. Each file's name becomes its client's name. myrmic_sdk::import!("../specs/http_bridge.yml"); myrmic_sdk::import!("../specs/mqtt_bridge.yml"); #[myrmic_sdk::cmd] fn fetch(_md: Metadata) -> myrmic_sdk::Result { // The name the bridge was deployed under. let client = HttpBridgeClient::new("myapp/http-bridge"); // Returns once the command is sent. The response reaches the callback. client.fetch_data("some-payload".into(), Callback::of::())?; Ok(()) } #[myrmic_sdk::cmd] fn fetched(_md: Metadata, reply: FetchDataReply) -> myrmic_sdk::Result { myrmic_sdk::info!("{}", reply.result)?; Ok(()) } // An ingress topic arrives as an event, named after its id in the file. #[myrmic_sdk::evt] fn receive_request(_md: Metadata, event: ReceiveRequest) -> myrmic_sdk::Result { let client = MqttClient::new("myapp/mqtt-bridge"); // Publishing to an egress topic. Nothing comes back. client.publish_response(PublishResponse { data: event.data })?; Ok(()) } ``` ## Behavior ### Normal A specification file is read while the cell is compiled. A call sends a command to the bridge cell, which then talks to the outside system. Success means the command was sent, not that the system answered. An HTTP reply comes back to the callback the call named. An MQTT publishing has no reply. ### Errors A specification file that does not parse fails the build. Publishing to a topic or calling an endpoint fails when the bridge's name is not valid, or when the corresponding command cannot be sent. ### Limits A client is bound to one bridge instance, named when the client is built. A wrong name fails at the call, not at compile time. ## API documentation For the macro, see [`import!`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.import.html). For the reply handle an HTTP call takes, see [`Callback`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.Callback.html). # Gateway assets > **Availability:** Linux runtime only A gateway route can serve files from a cell's blob storage. ## When to use Serve files when an HTTP client needs to download them, such as a user interface or data a cell produced. Use the message API when that client needs to send commands or events instead. ## Operations - Open the asset store belonging to a cell. - Store each file at the path it is served from. - Serve those files as part of a route, naming an index, a fallback, or another scope. ## Example ```rust use myrmic_sdk::gateway::Fallback; use myrmic_sdk::Metadata; #[myrmic_sdk::init] fn init(md: Metadata) -> myrmic_sdk::Result { let assets = myrmic_sdk::gateway::assets(md.id); assets.put("/index.html", include_bytes!("../dist/index.html"))?; myrmic_sdk::gateway::mount("/app") // Switches on file serving, and serves this file at /app/. .index("/index.html") // The default: a path matching no file gets the index, which is what a // single-page app needs. Use Fallback::None for a 404 instead. .fallback(Fallback::Spa) // In case the files live in another scope rather than this cell's own. // .scope(Scope::public("shared-assets")) .bind()?; Ok(()) } ``` ## Behavior ### Normal A cell's files are deleted when the cell is undeployed. If it is lost with its node instead, the files are not deleted. Writing to a path that already holds a file replaces what the gateway serves. The route does not need registering again. ### Errors Storing a gateway asset fails when: - the scope is invalid - storage cannot be reached ### Limits Nothing checks that the index file exists. A missing one returns a not-found on the first request for it. A cell that uses the gateway does not start on an embedded node. It fails to load, before any handler runs. ## API documentation See the API documentation for [`myrmic_sdk::gateway`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/gateway/index.html), which covers every route option. # Gateway routes > **Availability:** Linux runtime only A gateway route makes a Myrmic swarm reachable to HTTP clients under a URL path. A client sends commands and events into the swarm and reads the replies, over plain HTTP or a WebSocket. ## When to use Use a gateway when an HTTP client outside the swarm has to reach a cell. Use commands or events when one cell has to reach another. ## Operations - Describe a route under a URL path the cell will own. - Add the cell's message API, a WebSocket endpoint, or both. - Register the route. - Remove a route. ## Example ```rust use myrmic_sdk::Metadata; #[myrmic_sdk::init] fn init(_md: Metadata) -> myrmic_sdk::Result { // "control", "/control" and "/control/" all mean the same path. myrmic_sdk::gateway::mount("/control") // At /control/api. .api("/api") // At /control/ws. .ws("/ws") // Nothing is reachable until this succeeds. .bind()?; Ok(()) } #[myrmic_sdk::cmd] fn get_status(md: Metadata) -> myrmic_sdk::Result { // When the command arrived through the gateway, md.sender is the client's // session, so a command sent back to it reaches that client. myrmic_sdk::send(md.sender, "status", &true)?; Ok(()) } #[myrmic_sdk::cmd] fn go_offline(_md: Metadata) -> myrmic_sdk::Result { // The same path the route was registered under. myrmic_sdk::gateway::unmount("/control")?; Ok(()) } ``` ## Behavior ### Normal Registering and removing a route join the handler's transaction: they take effect when the handler returns successfully, and are rolled back if it fails. A path belongs to the cell that claimed it first. That cell can register it again, which replaces the old one. Another cell trying fails. On the **API** path: - a GET opens a stream, whose first message hands back a session id - a POST sends one command or event, with that session id in a header - replies arrive on the stream, not in the POST's response On the **WebSocket** path, one connection carries both directions, and needs no session id of its own. A command goes to the cell the client names, or to the cell that owns the route when none was named. An event goes to every cell that handles it. A route stops working when the cell that owns it is gone, whether it was undeployed or lost with its node. ### Errors Registering fails when: - the path is invalid - nothing was added to serve - another cell owns the path - the runtime cannot register it Removing fails when: - the path is invalid - the cell has no such route registered - the route is owned but another cell ### Limits A cell that uses the gateway does not start on an embedded node. It fails to load, before any handler runs. ## API documentation See the API documentation for [`myrmic_sdk::gateway`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/gateway/index.html), which covers every builder method and error. # GPIO > **Availability:** embedded runtime only GPIO gives a cell direct access to numbered digital pins on an embedded node. A pin can be read, driven high or low, or waited on for a level or an edge. ## Operations - Ask for a numbered pin. - Read whether a pin is high or low. - Drive a pin high or low. - Wait until a pin is high or low, or until it changes. ## Example The cell's crate needs `embedded-hal` as a dependency, for the read and write traits. ```rust use embedded_hal::digital::{InputPin, OutputPin}; use myrmic_sdk::gpio::{Gpio4, Gpio5, Wait}; use myrmic_sdk::{Metadata, Result}; #[myrmic_sdk::cmd] fn mirror_button(_md: Metadata) -> Result<()> { // None for a pin this node does not offer. let Some(mut button) = Gpio4::try_get() else { return Err("GPIO 4 is unavailable"); }; let Some(mut led) = Gpio5::try_get() else { return Err("GPIO 5 is unavailable"); }; // Read the button and drive the indicator to the level just read. if button.is_high().map_err(|_| "cannot read GPIO 4")? { led.set_high().map_err(|_| "cannot drive GPIO 5")?; } else { led.set_low().map_err(|_| "cannot drive GPIO 5")?; } // Nothing else runs on this node until the button changes level. button.wait_for_any_edge().map_err(|_| "cannot wait on GPIO 4")?; Ok(()) } ``` ## Behavior ### Normal Asking for a pin only checks that the node offers it. The pin is never reserved, so it can be used from anywhere in the cell. A read reports the level at that moment. A write returns once the node has written the pin. Waiting for a level returns at once if the pin is already at it. Waiting for a change always waits. For example, a pin that is already high does not satisfy a wait for a rise: it has to go low and high again. ### Errors A read, a write, or a wait fails when the node does not offer the pin. Nothing tells the cell any more than that. ### Limits Waiting has no timeout and cannot be cancelled. Until it returns, the cell does nothing else, and the node cannot serve any other call - including deploying or deleting a cell. A node offers only the pins its chip has and nothing else already uses. Electrical limits, pull resistors, drive strength, and safe pin use depend on the board and lie outside this API. ## API documentation See the API documentation for [`myrmic_sdk::gpio`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/gpio/index.html), which covers the pin types and the blocking wait trait. # Logging > **Availability:** Linux and embedded runtimes A cell logs what happened while it ran. Each line goes to the node's logger. ## Operations - Log a message at one of five levels: trace, debug, info, warn, error. ## Example ```rust use myrmic_sdk::{LogLevel, Metadata}; #[myrmic_sdk::cmd] fn log_everything(md: Metadata) -> myrmic_sdk::Result { myrmic_sdk::trace!("a trace message")?; myrmic_sdk::debug!("a debug message")?; myrmic_sdk::info!("an info message")?; myrmic_sdk::warn!("a warning message")?; myrmic_sdk::error!("an error message")?; // The same as info!, with the level chosen in code. myrmic_sdk::log(&myrmic_sdk::format!("logged by {}", md.id), LogLevel::Info)?; Ok(()) } ``` ## Behavior ### Normal A log is not part of the handler's transaction. A handler that fails and is rolled back still leaves its lines in the log. The runtime's log config decides what happens to a log line: which levels get through, how it is printed, and whether it is exported or stored. ### Errors Logging fails when the runtime cannot be reached, and when the message is not a valid UTF-8 string. ### Limits A log message is readable outside the cell, so keep secrets and sensitive data out of it. ## API documentation For the level macros, see [`trace!`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.trace.html), [`debug!`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.debug.html), [`info!`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.info.html), [`warn!`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.warn.html) and [`error!`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.error.html). For logging without a macro, see [`log`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.log.html), [`LogLevel`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/enum.LogLevel.html) and [`format!`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/macro.format.html). # Callbacks > **Availability:** Linux and embedded runtimes A command returns nothing to its sender. A callback is a reference to one of the sender's own command handlers, sent along with the command, so the receiver can call it back with an answer. The runtime uses callbacks the same way elsewhere: a timer, a Bluetooth scan, and a characteristic read each take one and invoke it when they have something to deliver. ## When to use Use a callback when the receiver of a command should answer the caller. Use an event instead for something any interested cell may react to. ## Operations - Create a callback naming one of your own command handlers. - Create a callback from a command name, when no handler is in scope. - Include a callback in a command payload. - Invoke a callback to answer the caller. ## Example ```rust use myrmic_sdk::{Callback, Metadata, Sri}; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct StatusReply { active: bool, } // On the receiving cell. #[myrmic_sdk::cmd] fn get_status(md: Metadata, reply: Callback) -> myrmic_sdk::Result { // Sends a command back to the caller. A second invoke would not compile, // because this one consumes the callback. reply.invoke(md.sender, &StatusReply { active: true }) } // On the calling cell. #[myrmic_sdk::cmd] fn on_status(_md: Metadata, reply: StatusReply) -> myrmic_sdk::Result { myrmic_sdk::info!("active={}", reply.active)?; Ok(()) } // Also on the calling cell. #[myrmic_sdk::cmd] fn request_status(_md: Metadata) -> myrmic_sdk::Result { // The receiver's identity, derived from its name. let receiver = Sri::of_path("myapp/worker").map_err(|_| "not a valid SRN path")?; // Callback::of takes the payload type from on_status, so the receiver // can only answer with a StatusReply. myrmic_sdk::send(receiver, "get_status", &Callback::of::()) } ``` ## Behavior ### Normal A callback carries the name of a command handler on the cell that created it. Invoking it sends that command, so an answer is an ordinary command rather than a value returned to the caller. The original command can finish before the answer arrives. Only a command handler can be named. Everything a command handler does commits atomically when it completes, including an answer it sent, so nothing is visible outside until then. ### Errors Creating a callback from a name fails when the name is invalid. Invoking a callback fails when the answer cannot be encoded, when no cell exists at the caller's identity, or when the runtime rejects the request. An invocation from the CLI carries a nil sender, so there is nothing to answer; one through the gateway carries the session's SRI and can be answered. Check for it before invoking. A handler that declares a bare `Callback` payload never gets that far when the command arrives without a payload, which is what `myrmic send ` puts on the wire: the decode fails before the handler body runs. Declare the payload as `Option>` to handle both kinds of caller. See [Message encoding](../../../05_guides/04_message-encoding.md#optional-payload). ### Limits A callback carries no request identifier, so a cell with several requests in flight has to put its own in the payload. ## API documentation For both ways to build a callback and the invoke signature, see [`Callback`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.Callback.html). # Commands > **Availability:** Linux and embedded runtimes A command is a named message sent to one cell to ask it to do something. The command name selects a handler on that cell. ## When to use Use a command when the sender knows which cell should act. Use a callback alongside it when the sender also needs a reply. Use an event instead when announcing something that happened, without choosing which cells react. ## Operations - Declare a handler for a command name. - Receive a typed payload in that handler, or none. - Send a command to a cell, with a payload or without one. ## Example ```rust use myrmic_sdk::{Metadata, Sri}; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct WorkItem { priority: u32, } // The handler's own name is the command name unless it is overridden here. #[myrmic_sdk::cmd(name = "process")] fn process_item(_md: Metadata, item: WorkItem) -> myrmic_sdk::Result { myrmic_sdk::info!("priority={}", item.priority)?; Ok(()) } fn dispatch(worker: Sri) -> myrmic_sdk::Result { // Returns once the runtime has accepted the send, not once the handler ran. myrmic_sdk::send(worker, "process", &WorkItem { priority: 2 }) } ``` ## Behavior ### Normal Sending does not wait for anyone. A success means the runtime accepted the command, not that the receiving cell ran it. The payload is decoded before the handler runs. A handler that declares no payload accepts none. Everything a command handler does commits atomically when it completes, including any command it sent, so nothing is visible outside until then. What happens depends on the outcome: - **The handler succeeds.** Its work commits and the command is done with. - **The handler fails or traps.** Nothing it did takes effect, and the command is delivered again. - **The cell has no handler for that name.** The command is discarded and logged on the node, and the sender is never told. ### Errors Sending fails when the command name is invalid, when the payload cannot be encoded, when no cell exists at that identity, or when the runtime rejects the request. A command name may contain only ASCII letters, digits, and underscores, and may not be empty or contain whitespace. ## API documentation See [`cmd`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/attr.cmd.html) and [`send`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.send.html) in the API documentation. # Events > **Availability:** Linux and embedded runtimes An event is a named message that any number of cells can receive. The publisher does not choose who reacts to it. ## When to use Use an event when the publisher should not know or choose the recipients. Use a command when one specific cell should perform an operation. ## Operations - Declare a handler for an event name. - Receive a typed payload in that handler, or none. - Publish an event, with a payload or without one. ## Example ```rust use myrmic_sdk::Metadata; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, myrmic_sdk::Message)] struct TemperatureChanged { value: f32, } // Declaring this handler is what subscribes the cell to the event. #[myrmic_sdk::evt(name = "temperature_changed")] fn on_temperature(_md: Metadata, event: TemperatureChanged) -> myrmic_sdk::Result { myrmic_sdk::info!("temperature={}", event.value)?; Ok(()) } fn announce(value: f32) -> myrmic_sdk::Result { myrmic_sdk::publish("temperature_changed", &TemperatureChanged { value }) } ``` ## Behavior ### Normal Declaring a handler subscribes the cell to that event name. There is no subscription call, and a cell cannot subscribe to an event it has no handler for. A cell only receives events published after it was deployed. An event published while no cell is subscribed is not delivered later. Publishing does not wait for anyone. A success means the runtime accepted the event, not that a cell received or handled it. The payload is decoded before the handler runs. A handler also receives the publisher's identity, which is empty when the event came from outside a cell. Everything an event handler does commits atomically when it completes, including any event it published, so nothing is visible outside until then. What happens depends on the outcome: - **The handler succeeds.** Its work commits. - **The handler fails or traps.** Nothing it did takes effect, but the event is not delivered again. ### Errors Publishing fails when the event name is invalid, when the payload cannot be encoded, or when the runtime rejects it. An event name may contain only ASCII letters, digits, and underscores, and may not be empty or contain whitespace. An event whose payload does not match the type a handler declares is skipped and logged on the node. The handler never runs for it. ## API documentation See [`evt`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/attr.evt.html) and [`publish`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.publish.html) in the API documentation. # Message encoding > **Availability:** Linux and embedded runtimes Message encoding turns a value into bytes for sending, and turns received bytes back into a value. Both sides must use the same format, and the same shape of data. With JSON the field names travel with the value; with the binary format they do not, so a different type of the same shape decodes without complaint into the wrong value. ## Operations - Declare a type as a message, so it can be sent and received. - Choose the encoding format a message uses. - Encode or decode a value yourself. - Send a payload whose shape is not fixed. - Send bytes with no encoding applied. - Send no payload at all. - Accept a payload that may be absent. ## Example ```rust use myrmic_sdk::{Bytes, Metadata}; use serde::{Deserialize, Serialize}; // JSON is the default, so this attribute could be left out. #[derive(Serialize, Deserialize, myrmic_sdk::Message)] #[codec(myrmic_sdk::Json)] struct Reading { sensor: myrmic_sdk::String, value: f64, } // The binary format is worth choosing where payload size matters. #[derive(Serialize, Deserialize, myrmic_sdk::Message)] #[codec(myrmic_sdk::Postcard)] struct CompactReading { value: i16, } // A handler names the type it expects, and receives it already decoded. #[myrmic_sdk::cmd] fn on_reading(_md: Metadata, reading: Reading) -> myrmic_sdk::Result { myrmic_sdk::info!("{} = {}", reading.sensor, reading.value)?; Ok(()) } // A handler taking bytes receives the payload exactly as it was sent. #[myrmic_sdk::cmd] fn on_image(_md: Metadata, image: Bytes) -> myrmic_sdk::Result { myrmic_sdk::info!("{} bytes", image.len())?; Ok(()) } // A handler with no payload parameter accepts an empty payload only. #[myrmic_sdk::cmd] fn on_ping(_md: Metadata) -> myrmic_sdk::Result { Ok(()) } // A handler with an optional payload accepts an empty payload as None. #[myrmic_sdk::cmd] fn on_threshold(_md: Metadata, threshold: Option) -> myrmic_sdk::Result { myrmic_sdk::info!("{threshold:?}")?; Ok(()) } ``` ## Behavior ### Normal Declaring a type as a message gives it both encoding and decoding, using JSON unless another format is chosen. Sending and receiving encode and decode for you, so most code never does either itself. Bytes pass through unchanged, which suits content the application already has in its final form, such as an image. A handler that takes no payload accepts an empty one only. Sending it a payload is rejected rather than quietly ignored. A handler whose payload type is wrapped in `Option` accepts an empty payload as `None`. Only the empty payload is absorbed: a non-empty one is still decoded by the inner type, so a malformed payload is rejected rather than treated as absent. ### Errors Encoding fails when the value cannot be represented in the chosen format. Decoding fails when the bytes were produced by a different format, or do not match the type the handler declares. ### Limits The type's name is not sent, so a mismatch between the two sides is not detected for you. Adding, removing, or renaming a field can leave existing senders and receivers unable to read each other. ## API documentation For the derive's options and the traits behind it, see [`Message`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/derive.Message.html), [`Codec`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/trait.Codec.html), [`Encoder`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/trait.Encoder.html) and [`Decoder`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/trait.Decoder.html). # Clock, uptime, and pausing > **Availability:** Linux and embedded runtimes A cell can read the current time, read how long its node has been running, and pause for a duration. ## When to use Pause only when the running handler cannot proceed for a certain period. Use a timer to delay invoking a handler, or to invoke it periodically. ## Operations - Read the current time, as a duration since the Unix epoch. - Read how long the node has been running. - Pause for a duration. ## Example ```rust use core::time::Duration; use myrmic_sdk::Metadata; #[myrmic_sdk::cmd] fn inspect_time(_md: Metadata) -> myrmic_sdk::Result { let current_time = myrmic_sdk::now()?; let running_for = myrmic_sdk::uptime()?; if running_for < Duration::from_secs(1) { myrmic_sdk::wait(Duration::from_millis(10))?; } myrmic_sdk::info!("time {current_time:?}, up for {running_for:?}")?; Ok(()) } ``` ## Behavior ### Normal The current time comes from the node's swarm-synchronised clock, so timestamps taken on different nodes can be compared and ordered. Uptime counts from when the node started and only ever moves forward. It resets when the node restarts, and uptimes from two nodes cannot be compared. A pause runs for its full duration and then succeeds. Nothing cancels or interrupts it, and nothing limits how long a handler may take. While a cell is paused it does nothing else. Commands, events, replies, and scheduled invocations all queue behind it. ### Errors Reading the current time fails on an embedded node whose clock has not yet synchronised with the swarm. Pausing fails only when the duration is malformed. ## API documentation See [`now`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.now.html), [`uptime`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.uptime.html) and [`wait`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.wait.html) in the API documentation. # Delayed handler invocations > **Availability:** Linux and embedded runtimes A cell can schedule a delayed invocation of one of its command handlers. The handler that schedules it carries on and returns as usual, and nothing is blocked while the time passes. ## When to use Use a delayed invocation for timeouts, deferred cleanup, and one-time retries. Use a periodic timer when the work should repeat rather than happen once. ## Operations - Schedule a delayed invocation of a command handler. - Keep it, so a later invocation can cancel it. - Cancel one that has not run yet. ## Example ```rust use core::time::Duration; use myrmic_sdk::db::state::State; use myrmic_sdk::{Callback, Metadata, TimerHandle}; // It outlives the invocation that scheduled it, so it is stored. const TIMEOUT: State = State::new_const("timeout"); #[myrmic_sdk::cmd] fn arm(_md: Metadata) -> myrmic_sdk::Result { // Naming the handler is what decides which one is invoked. let timer = myrmic_sdk::delay( Callback::of::(), Duration::from_secs(30), ) .build()?; TIMEOUT.save(&timer) } #[myrmic_sdk::cmd] fn stop(_md: Metadata) -> myrmic_sdk::Result { if let Some(timer) = TIMEOUT.load()? { // Cancelling uses it up, so it cannot be cancelled twice. timer.cancel()?; } Ok(()) } #[myrmic_sdk::cmd] fn on_timeout(_md: Metadata) -> myrmic_sdk::Result { myrmic_sdk::warn!("timeout expired")?; Ok(()) } ``` ## Behavior ### Normal Once the time has passed, the runtime calls the named handler as a fresh invocation, with the usual metadata and no payload. Only a command handler that takes no payload can be called this way. The delayed invocated handler cannot see anything from the handler that scheduled it. Whatever it needs must be stored first. Scheduling takes effect immediately. If that handler then fails, its writes and messages are rolled back, but the schedule stays. ### Errors Scheduling fails when the cell has no handler of that name, or when it already has five scheduled invocations. Cancelling fails when the invocation has already run or has already been cancelled. ### Limits A cell may have five scheduled invocations at once. Delayed and periodic ones share that count. Delays are rounded down to whole milliseconds, so anything under a millisecond runs immediately. Dropping the handle does not cancel the invocation, and once it has run there is nothing left to cancel. ## API documentation For exact signatures and the handle's methods, see [`delay`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.delay.html) and [`TimerHandle`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.TimerHandle.html). # Periodic handler invocations > **Availability:** Linux and embedded runtimes A cell can schedule repeated invocations of one of its command handlers, on a period. ## When to use Use a periodic timer for polling, heartbeats, refreshes, and recurring retries. Use a delayed invocation when the work should happen once. ## Operations - Schedule a command handler to run repeatedly. - Delay the first tick. - Stop after a fixed number of ticks. - Cancel the schedule. ## Example ```rust use core::time::Duration; use myrmic_sdk::db::state::State; use myrmic_sdk::{Callback, Metadata, TimerHandle}; // It outlives the invocation that scheduled it, so it is stored. const POLL: State = State::new_const("poll"); #[myrmic_sdk::cmd] fn start(_md: Metadata) -> myrmic_sdk::Result { let handle = myrmic_sdk::interval_at( Callback::of::(), // Optional first delay. Plain interval starts at once instead. Duration::from_secs(60), // The period: one tick every five seconds. Duration::from_secs(5), ) // Optional. Those five seconds start when the handler finishes, not when // the tick begins. .fixed_delay() // Optional. Stops after three ticks; without it, repeats until cancelled. .count(3) .build()?; POLL.save(&handle) } #[myrmic_sdk::cmd] fn stop(_md: Metadata) -> myrmic_sdk::Result { if let Some(handle) = POLL.load()? { // Cancelling uses it up, so it cannot be cancelled twice. handle.cancel()?; } Ok(()) } #[myrmic_sdk::cmd] fn poll(_md: Metadata) -> myrmic_sdk::Result { myrmic_sdk::info!("poll")?; Ok(()) } ``` ## Behavior ### Normal Each tick invokes the handler with the usual metadata and no payload. Only a command handler that takes no payload can be scheduled this way. The countdown to the next tick starts either when the current tick begins, or when its handler finishes. Counting from the start keeps a steady rate. If the handler takes longer than the period, invocations pile up in the cell's queue, which holds ten on Linux and eight on embedded targets. Once it is full: - the embedded runtime drops one and skips the periods it missed - the Linux runtime delivers it late rather than losing it Counting from the handler leaves a full period between runs, so nothing piles up. Scheduling takes effect immediately. If that handler then fails, its writes and messages are rolled back, but the schedule stays. ### Errors Scheduling fails when the cell has no handler of the specified name, when a tick count of zero is asked for, or when it already has five scheduled invocations. Cancelling fails when the schedule has already finished or has already been cancelled. ### Limits A cell may have five scheduled invocations at once. Periodic and delayed ones share that count. Periods and initial delays are rounded down to whole milliseconds, so anything under a millisecond runs immediately. Dropping the handle does not cancel the schedule, and once a counted schedule has finished there is nothing left to cancel. ## API documentation For exact signatures and the handle's methods, see [`interval`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.interval.html), [`interval_at`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/fn.interval_at.html) and [`TimerHandle`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.TimerHandle.html). # Signal outlets > **Availability:** embedded runtime only An outlet is a named output in the Signal Layer. A cell writes it by name, and never names the device behind it. ## Key concepts The Signal Layer is built from a pipeline file, which declares each outlet's name, the type of its value, and the device it drives. Only one outlet may drive a device. An outlet the pipeline computes itself cannot be written by a cell, and a cell looking it up finds nothing. Only the outlets the pipeline leaves open are open to a cell. ## When to use Use an outlet to drive a device through a named interface, without knowing which pin it uses. Use GPIO to drive the pin directly. GPIO exists on the embedded runtime only. ## Operations - List the outlets a node offers. - Look up an outlet by name. - Write a typed value, or bytes already encoded. ## Example ```rust use myrmic_sdk::outlet::{list_entry, list_len, Outlet}; use myrmic_sdk::signal_layer::DigitalState; use myrmic_sdk::{Codec, Postcard}; use myrmic_sdk::Metadata; #[myrmic_sdk::cmd] fn set_relay(_md: Metadata, on: bool) -> myrmic_sdk::Result { // Every outlet open to this cell. A name comes back as bytes. for index in 0..list_len().map_err(|_| "listing outlets failed")? { let mut bytes = [0u8; 32]; let Some((len, _)) = list_entry(index, &mut bytes).map_err(|_| "listing outlets failed")? else { continue; }; let name = core::str::from_utf8(&bytes[..len]).map_err(|_| "an outlet name was not text")?; myrmic_sdk::info!("outlet {name}")?; } // A name the pipeline does not leave open resolves to nothing, rather than // failing. let Some(outlet) = Outlet::resolve("relay_cmd").map_err(|_| "outlet lookup failed")? else { return Ok(()); }; // The value has to match the type the pipeline declared for this outlet. // It is encoded into a 64-byte buffer, so a larger value fails here. outlet .write_typed(&DigitalState { on }) .map_err(|_| "writing the outlet failed")?; // The same command encoded by the cell instead. The bytes go straight to // the runtime, so their size is the cell's own business. let bytes = Postcard::encode(&DigitalState { on }).map_err(|_| "encoding failed")?; outlet .write(&bytes) .map_err(|_| "writing the outlet failed")?; Ok(()) } ``` ## Behavior ### Normal A write replaces the outlet's previous command. What the driver then does is the driver's business: it may clamp the value, or refuse to act on it yet. A write that succeeds means the Signal Layer took the command. It does not mean the device reached that state. Read a tap for that. A write takes effect at once. A handler that fails afterwards does not undo it. ### Errors Looking up or writing an outlet fails when: - the Signal Layer cannot be reached - the outlet is no longer available - the bytes cannot be decoded as the type the pipeline declared ### Limits Writing a typed value encodes it into a 64-byte buffer, so a larger value fails. Writing bytes hands them over directly, with no limit. A node holds at most 8 outlets. A cell that uses an outlet cannot start on a Linux node. It fails while being loaded, before any handler runs. ## API documentation See the API documentation for [`myrmic_sdk::outlet`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/outlet/index.html), which covers both write operations and the discovery helpers. # Signal taps > **Availability:** Linux and embedded runtimes A tap is a named input from the Signal Layer. A cell reads it by name, and never names the sensor or driver the value comes from. ## Key concepts The Signal Layer is built from a pipeline file, which declares each tap's name, its kind, and the type of its value. A cell looks a tap up and reads it, and declares nothing itself. A tap is one of two kinds: - **retained** holds the latest value. Reading it does not consume it, so the same value comes back until a new one arrives. - **event** holds a queue of values. The cell takes them one at a time, and each value is handed out once. A tap is never pushed to a cell. The cell reads when it chooses, and a queue that is not read loses its oldest values. ## When to use Use a tap to read a signal through a named interface, without knowing which pin it comes from. A tap read never blocks the handler. Use GPIO to read the pin directly, or to wait for it to change. GPIO exists on the embedded runtime only, and waiting for a pin stops the cell and every other call to the runtime on that node until it changes. ## Operations - Look up a tap by name. - Read the latest retained value, as a type or as raw bytes. - Take the next queued value, as a type or as raw bytes. ## Example ```rust use myrmic_sdk::tap::Tap; use myrmic_sdk::signal_layer::HealthEvent; use myrmic_sdk::Metadata; #[myrmic_sdk::cmd] fn poll_signals(_md: Metadata) -> myrmic_sdk::Result { // A name the pipeline does not offer resolves to nothing, rather than // failing. let Some(temperature) = Tap::resolve("temperature").map_err(|_| "tap lookup failed")? else { return Ok(()); }; // The timestamp comes with the value, and nothing comes back before the // first value has arrived. if let Some((at, value)) = temperature .read_typed::() .map_err(|_| "reading the tap failed")? { myrmic_sdk::info!("{value} at {at}")?; } let Some(health) = Tap::resolve("_signal_layer_health").map_err(|_| "tap lookup failed")? else { return Ok(()); }; // An event tap is drained until it is empty. Whatever is not taken now // waits for the next time this handler runs. while let Some(event) = health .take_event_typed::() .map_err(|_| "taking an event failed")? { myrmic_sdk::info!("{:?}", event.state)?; } Ok(()) } ``` ## Behavior ### Normal A retained value carries a timestamp counted in milliseconds by the Signal Layer. It is not the clock a cell reads, and it resets when the Signal Layer restarts. A retained read gives nothing back before the first value arrives. An event read gives nothing back when the queue is empty. ### Errors Looking up or reading a tap fails when: - the Signal Layer cannot be reached - the tap is no longer available - a retained value is read from an event tap, or an event is taken from a retained one - the value cannot be decoded as the type asked for - the value is larger than 64 bytes, which the embedded runtime refuses and the Linux runtime cuts short Taking an event removes it before the cell decodes it, so a value that fails to decode is lost. Take raw bytes when that is unacceptable. ### Limits A value read as a type has to fit in 64 bytes. Read raw bytes for anything larger. A node holds at most 16 taps. An event tap holds 8 values. Past that, a new value drops the oldest. ## API documentation See the API documentation for [`myrmic_sdk::tap`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/tap/index.html), which covers every read operation and the tap kinds. # Blob store > **Availability:** Linux and embedded runtimes The blob store holds large binary content, such as files, under file-like paths. A store handle is bound to one scope. ## Operations - Declare a store on a scope. - Store content at a path. - Store several paths at once. - Read the content at a path, all of it or a range. - Read the size at a path without reading the content. - List every path in the scope. - Delete a path, or rename it. ## Example ```rust use myrmic_sdk::db::store::BlobStore; use myrmic_sdk::db::Scope; use myrmic_sdk::Metadata; #[myrmic_sdk::cmd] fn install_assets(_md: Metadata) -> myrmic_sdk::Result { let store = BlobStore::new(Scope::private()); // A path always starts with one slash, so "index.html" and "/index.html" // are the same file. store.put("/index.html", b"")?; // Several at once, each stored like the call above. store.upload(&[ ("/app.js", b"console.log(1)".as_slice()), ("/app.css", b"body{}".as_slice()), ])?; store.rename("/index.html", "/home.html")?; // The size alone, without reading the content. let size = store.size_of("/home.html")?.unwrap_or_default(); // The whole file. Nothing at the path returns nothing, not an error. let _page = store.get("/home.html")?; // Or a piece of it, for a file too large to hold at once. let _head = store.get_range("/home.html", 0, 512)?; for path in store.list()? { myrmic_sdk::info!("{path} of {size} bytes")?; } // Deleting a path that is not there does not raise an error. store.delete("/app.css")?; Ok(()) } ``` ## Behavior ### Normal Every operation applies to the store's one scope and reaches nothing outside it, even when another scope holds the same path or the same content. Storing content at a path replaces what was there. Storing, renaming, and deleting take effect when the handler returns successfully, together with everything else it wrote, and are rolled back if the handler fails. Renaming or deleting a path changes only the name. The content is not copied, moved, or removed. ### Errors Every operation fails when the scope is invalid or storage cannot be reached. Beyond that: - Storing fails when the path, with its scope, does not fit in 1 KiB. - Listing fails when the paths do not fit in 8 KiB. - Renaming fails when the path it starts from does not exist. ### Limits Reading a whole file holds all of it in the cell's memory, so a large file can exhaust it. Read a range instead. Nothing ever deletes stored content. Once its last path is gone it cannot be reached any more, and it stays on the node. ## API documentation See the API documentation for [`myrmic_sdk::db::store`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/store/index.html), which covers every blob store operation. # Key-value store > **Availability:** Linux and embedded runtimes A key-value store keeps many values of one type beneath a shared prefix. Each value has its own key below that prefix. ## When to use Use a key-value store for a collection whose names are hierarchical and worth scanning, such as one entry per device. Use a table when entries need explicit identifiers, a count, or ordered traversal. ## Operations - Declare a typed store under a prefix, fixed at compile time, and which scope it belongs to. - Store a value, read it, or remove it. - Collect the keys under a prefix without reading their values. - Read the values under a prefix, with a callback, as an iterator, or all at once. ## Example ```rust use myrmic_sdk::db::tree::Kv; use myrmic_sdk::Metadata; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize)] struct DeviceConfig { enabled: bool, } const CONFIGS: Kv = Kv::new("configs"); #[myrmic_sdk::cmd] fn enable(_md: Metadata) -> myrmic_sdk::Result { let config = DeviceConfig { enabled: true }; // A slash joins the prefix to the key, so this is stored under // "configs/warehouse-a/sensor-01". CONFIGS.put("warehouse-a/sensor-01", &config)?; // A callback over a narrower prefix. Every key is loaded first, then the // values are lazy loaded one at a time. A value that cannot be read or // decoded is skipped and nothing is reported. CONFIGS.for_each("warehouse-a", |config| { let _ = config; })?; // An iterator instead. It lazy loads the same way, and each failure reaches // the caller. for value in CONFIGS.iter("warehouse-a")? { let _config = value?; } // Nothing is lazy loaded here: every value is held in memory at once. let _all = CONFIGS.list("warehouse-a")?; // The keys alone, all of them in memory, without reading any value. Either // way, a key removed while reading is skipped. let _keys = CONFIGS.keys("warehouse-a")?; Ok(()) } ``` ## Behavior ### Normal A store fixes the value's type, its prefix, and its scope. An empty prefix selects everything in the store, and nothing outside it. ### Errors Storage access, encoding, decoding, and communication with the runtime can all fail. ### Limits Each value is read through a fixed buffer of 8 KiB, and a listing of keys through one of 16 KiB, so anything larger cannot be read back. Writing has no such limit. ## API documentation See the API documentation for [`myrmic_sdk::db::tree`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/tree/index.html), which covers every store operation and its iterator. # Persistent cell state > **Availability:** Linux and embedded runtimes Persistent state keeps one typed value under one key in the runtime database. The value stays available from one handler to the next, and across restarts of the cell. ## When to use Use persistent state for a single value that has to survive the cell restarting, such as a counter or a setting. Use a key-value store or a table when the data holds many entries. Use transient state for values that should not survive a restart. ## Operations - Declare a handle for a key, fixed at compile time or built while running. - Declare which scope the value belongs to. Without one, it is the cell's private scope. - Read, write, modify, or borrow the value, at the handle's key or another. ## Example ```rust use myrmic_sdk::db::state::State; use myrmic_sdk::db::Scope; use myrmic_sdk::Metadata; // No scope, so this value is private to the cell. const COUNT: State = State::new_const("count"); // The same type in a public scope, shared with other cells. const TOTAL: State = State::new_const_in("total", Scope::public("application-data")); #[myrmic_sdk::cmd] fn record(_md: Metadata) -> myrmic_sdk::Result { // Reads, changes, and writes in one step, starting from zero if unset. let count = COUNT.upsert_with(|count| *count += 1)?; // Borrowed, then written back explicitly, so a failure is not lost. let mut total = TOTAL.guard_or_default()?; *total += 1; total.save()?; // The same handle, a different key. COUNT.save_to("last-count", &count)?; Ok(()) } #[myrmic_sdk::cmd] fn report(_md: Metadata) -> myrmic_sdk::Result { // An absent key reads as nothing, not as an error. let count = COUNT.load()?.unwrap_or_default(); myrmic_sdk::info!("counted {count}")?; Ok(()) } ``` ## Behavior ### Normal A handle fixes the value's type and its scope. Its key is the one every operation uses unless given another. The value is encoded and decoded whole, every time it crosses into the runtime. Changing a value in place is therefore a read, a change, and a write, not an in-database update. Every storage call a handler makes joins one transaction, which commits when the handler returns successfully and rolls back when it returns an error or traps. ### Errors Encoding, decoding, storage access, and communication with the runtime can all fail. ### Limits Reading uses a fixed buffer of 8 KiB, so a value larger than that cannot be read back. Writing has no such limit, so a cell can store a value it can no longer read. ## API documentation See the API documentation for [`myrmic_sdk::db::state`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/state/index.html), which covers every operation on a state handle, and its guard. # Semantic store > **Availability:** Linux and embedded runtimes The semantic store keeps data as RDF triples: a subject, a predicate, and an object. A cell writes and reads them with SPARQL. ## Operations - Write and update triples. - Read triples. ## Example ```rust use myrmic_sdk::db::{Scope, sem_select, sem_update}; use myrmic_sdk::Metadata; const ASSETS: Scope = Scope::public("assets"); #[myrmic_sdk::cmd] fn record_status(_md: Metadata) -> myrmic_sdk::Result { sem_update( ASSETS, "INSERT DATA { . }".into(), // No base, so every IRI has to be absolute. None, ) .map_err(|_| "the update failed")?; let response = sem_select( ASSETS, "SELECT ?sensor ?status WHERE { ?sensor ?status . }".into(), None, Some(10), None, ) .map_err(|_| "the query failed")?; for solution in &response.solutions { for (variable, value) in response.variables.iter().zip(solution) { // Some rows may have no value for a selected variable. if let Some(value) = value { // variable is "sensor" or "status". myrmic_sdk::info!("{variable} = {value}")?; } } } Ok(()) } ``` ## Behavior ### Normal An update or a select runs in the scope it names. An update takes effect when the handler returns successfully, together with everything else it wrote, and is rolled back if the handler fails. A select returns at most 100 rows unless it asks for more. ### Errors A query fails when the SPARQL is invalid, a read is not a select, an IRI is bad, storage is unavailable, or the result is too large to fit. A query too long to encode fails before the runtime is called. ### Limits The query text has to fit in 1000 bytes. A select's rows have to fit in 1000 bytes too. Anything larger fails. For now an update can insert triples, delete them, do both at once, and create, clear or drop a graph. `LOAD` is not supported: it fails, and `LOAD SILENT` does nothing. ## API documentation For exact signatures and the response type, see [`sem_update`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/fn.sem_update.html), [`sem_select`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/fn.sem_select.html) and [`SelectResponse`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/struct.SelectResponse.html). # Storage scopes > **Availability:** Linux and embedded runtimes Every operation on the runtime database takes place within a scope. A scope decides where data belongs and who can reach it, and it guarantees tenancy. A scope is either private, holding data bound to a cell alone, or public, holding data shared by every cell that uses it. A scope is written `namespace/database/schema`. ## Operations - Declare a private scope, and optionally its schema. - Declare a public scope, and optionally its database and schema. - Pass a scope to any storage operation. ## Example ```rust use myrmic_sdk::db::state::State; use myrmic_sdk::db::Scope; use myrmic_sdk::Metadata; // Private: bound to this cell. Only the schema can be declared, because the // runtime uses the rest for the cell's identity. const OWN: Scope = Scope::private_in(Some("readings")); // Public: shared by every cell using it. Both parts can be declared. const SHARED: Scope = Scope::public_in("application-data", Some("metrics"), Some("v1")); const LOCAL: State = State::new_const_in("count", OWN); const TOTAL: State = State::new_const_in("count", SHARED); #[myrmic_sdk::cmd] fn record(_md: Metadata) -> myrmic_sdk::Result { // The same key in two scopes is two separate values. LOCAL.upsert_with(|count| *count += 1)?; TOTAL.upsert_with(|count| *count += 1)?; Ok(()) } ``` ## Behavior ### Normal The runtime resolves a private scope from the cell's own SRI, so no cell can reach another cell's. It fixes the namespace and the database, which is why only the schema is left to declare. ### Errors A declared part of a scope may not be empty. A cell may not use a namespace the system keeps for itself. ### Limits A public scope separates data; it does not protect it. Two cells using the same one overwrite each other freely. ## API documentation For every constructor, see [`Scope`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/struct.Scope.html). # Table store > **Availability:** Linux and embedded runtimes A table is a named collection of values of one type. Each entry has a key, chosen by the caller or generated by the runtime. ## When to use Use a table for a named collection whose entries need keys, a count, or reading in key order. ## Operations - Declare a typed table, fixed at compile time, and which scope it belongs to. - Insert a value under a key of your own, or let the runtime generate one. - Read a value, remove one, or count the entries. - Read the entries or the keys in either direction, with a callback, as an iterator, or all at once. ## Example ```rust use myrmic_sdk::db::table::Table; use myrmic_sdk::Metadata; use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize)] struct Device { label: myrmic_sdk::String, } const DEVICES: Table = Table::new("devices"); #[myrmic_sdk::cmd] fn register(_md: Metadata) -> myrmic_sdk::Result { let device = Device { label: "sensor 01".into() }; // Choosing the key is what makes the entry addressable later. DEVICES.insert_with("sensor-01", &device)?; // Letting the runtime choose one does not say what it chose. DEVICES.insert(&device)?; // An absent entry reads as nothing rather than as an error. if let Some(saved) = DEVICES.get("sensor-01")? { let _ = saved.label; } // A callback, in key order. A value that cannot be decoded is skipped // silently, while a failed read stops the traversal. DEVICES.for_each(|device| { let _ = device; })?; // An iterator instead, in reverse key order. It lazy loads one entry per // step, and each failure reaches the caller. for entry in DEVICES.iter_rev() { let (_key, _device) = entry?; } // Nothing is lazy loaded here: the whole table is held in memory at once. let _all = DEVICES.list()?; let _by_key = DEVICES.to_map()?; // The keys alone, lazy loaded, without reading any value. for key in DEVICES.keys() { let _key = key?; } // Or all the keys at once. let _ids = DEVICES.ids()?; let _total = DEVICES.count()?; Ok(()) } ``` ## Behavior ### Normal A table fixes the value's type, its name, and its scope. Entries are ordered by their encoded key, never by a field inside the value, and can be read in either direction. ### Errors Encoding, decoding, storage access, and traversal can all fail. ### Limits Each value is read through a fixed buffer of 4 KiB, so anything larger cannot be read back. Inserting has no such limit. Reading a table costs one call to the runtime per entry, whichever form is used. Letting the runtime generate a key does not tell the caller what it generated, so choose the key whenever the entry has to be reached again. ## API documentation See the API documentation for [`myrmic_sdk::db::table`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/table/index.html), which covers every table operation and its iterators. # Time-series store > **Availability:** Linux and embedded runtimes The time-series store keeps timestamped measurements. Each sample belongs to a named series and carries tags and typed fields. ## When to use Use the time-series store for measurements, and observations that are read back by time range. ## Operations - Publish a measurement into a series, with tags, fields, and an optional timestamp. - Query one series, narrowing by start time, end time, a result limit, and order. ## Example ```rust use myrmic_sdk::db::{FieldValue, Measurement, Scope, find_measurement, publish_measurement}; use myrmic_sdk::Metadata; #[myrmic_sdk::cmd] fn record(_md: Metadata, value: f64) -> myrmic_sdk::Result { publish_measurement( Scope::private(), Measurement { name: "sensor-readings".into(), tags: myrmic_sdk::vec![("room".into(), "kitchen".into())], fields: myrmic_sdk::vec![("temperature".into(), FieldValue::F64(value))], // Left out, so the runtime stamps the sample as it arrives. ts: None, }, ) .map_err(|_| "publishing the measurement failed")?; // The caller passes in both buffers, so their size is the caller's to // manage. let mut req = [0u8; 256]; let mut resp = myrmic_sdk::vec![0u8; 8192]; let found = find_measurement( Scope::private(), "sensor-readings".into(), // The newest ten samples: no bounds, and newest first by default. Some(10), None, None, None, &mut req, &mut resp, ) .map_err(|_| "reading the measurements failed")?; myrmic_sdk::info!("{} samples", found.samples.len())?; Ok(()) } ``` ## Behavior ### Normal A sample is identified by its series and its timestamp, not by its tags. Publishing that pair again means a query returns only the last sample published. A query's start time is inclusive and its end time is exclusive. Results come back newest first unless ascending order is asked for, and each sample carries its timestamp, tags, and fields. ### Errors Encoding, scope validation, storage access, and communication with the runtime can all fail. ### Limits Publishing encodes the scope, series name, tags, and fields into a single buffer of 100 bytes, and anything over that total fails. A query reads into buffers the caller passes in, so sizing them is up to the caller. Set a limit, or a start and end time, to keep the result small. Nothing deletes a sample. There is no delete operation, and a cell's data carries no expiry, so a series grows for as long as the cell keeps publishing. ## API documentation For exact signatures, and the measurement and field types, see [`publish_measurement`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/fn.publish_measurement.html), [`find_measurement`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/fn.find_measurement.html), [`Measurement`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/struct.Measurement.html) and [`FieldValue`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/db/enum.FieldValue.html). # Transient state > **Availability:** Linux and embedded runtimes Transient state holds a value in the cell's WebAssembly memory rather than the runtime database, so it needs no encoding. ## When to use Use transient state for a value that is cheap to rebuild and does not need to outlive the cell. Use persistent state or a store when the value has to survive the cell restarting. ## Operations - Declare a value in the cell's memory. - Read or change it inside a closure. - Borrow it instead, for as long as the caller needs. ## Example ```rust use myrmic_sdk::ble::ScanHandle; use myrmic_sdk::{InMemory, Metadata}; // A scan handle means nothing to another cell and cannot be stored. static SCAN: InMemory> = InMemory::empty(); fn keep(handle: ScanHandle) -> myrmic_sdk::Result { // Replaces whatever was there. Later invocations see this value. SCAN.with(|slot| *slot = Some(handle)) } #[myrmic_sdk::cmd] fn stop_scan(_md: Metadata) -> myrmic_sdk::Result { // Held for the rest of the function, so the handle can be taken out and // used while the slot stays borrowed. let mut slot = SCAN.try_borrow_mut()?; if let Some(handle) = slot.take() { handle.stop()?; } Ok(()) } ``` ## Behavior ### Normal A value set by one of the cell's handlers - initialization, command, event, or monitor - is still there for the next, for as long as the cell runs. ### Errors A borrow taken while the value is already borrowed fails with an error rather than panicking. ### Limits The value is gone whenever the cell starts again. ## API documentation For every method on the handle, see [`InMemory`](https://docs.myrmic.dev/myrmic_sdk/git/myrmic_sdk/struct.InMemory.html). # Signal Layer Reference for the Signal Layer: the two files that describe a system, and the modules they can name. - [Pipeline file](./04_signal-layer/01_pipeline-file.md) - sources, steps, taps and outlets, the payload types they can carry, and the limits. - [Board file](./04_signal-layer/02_board-file.md) - chip, buses, pins and devices, and which settings belong here rather than in the pipeline. - [Drivers](./04_signal-layer/03_drivers.md) - every driver in the tree, what it reads or writes, and what it can be configured with. - [Steps](./04_signal-layer/04_steps.md) - every processing step, its input and output types, and its configuration. - [Running on Linux](./04_signal-layer/05_running-on-linux.md) - the pipeline process, the socket, and what differs from embedded. For how to use any of it, see the guide: [Work with the Signal Layer](../05_guides/11_signal-layer.md). The driver and step pages are generated from the module descriptors, so they cannot drift from what is in the tree. # Board file The board file describes one physical board: which chip, which pins carry which bus, and what is wired to it. It is the only file in the Signal Layer that is not portable. In a scaffolded project it is named `board.yml`, on both Linux and embedded. ```yaml id: esp32c6-devkit chip: esp32c6 buses: i2c0: transport: i2c pins: { scl: 10, sda: 11 } freq_khz: 400 spi2: transport: spi pins: { sclk: 19, mosi: 20, miso: 21 } freq_khz: 1000 gpios: general_purpose: [0, 1, 2, 3, 14, 18, 23] devices: - id: bme280 driver: bme280 bus: i2c0 hardware: i2c_addr: 0x76 - id: loopback driver: spi-loopback bus: spi2 pins: cs: 22 ``` ## Top level | Key | Required | Meaning | |---|---|---| | `id` | yes | A name for the board | | `chip` | yes | Which microcontroller, or `linux` | | `buses` | yes | Shared connections, keyed by bus id | | `gpios` | yes | Which pins this board makes available | | `devices` | yes | What is connected | ## `buses` | Key | Required | Meaning | |---|---|---| | `transport` | yes | `i2c` or `spi` | | `pins` | yes | Role to GPIO number, e.g. `scl`, `sda`, `sclk`, `mosi`, `miso` | | `freq_khz` | yes | Bus clock, must be greater than 0 | | `mode` | no | SPI mode 0-3, SPI only | The bus id must name a real peripheral: `i2c0` or `i2c1` for I²C, `spi2` or `spi3` for SPI. The generator accepts all four on any chip, but your chip may not have them all. On the C5, C6 and C61 there is only one I²C peripheral, so `i2c1` validates and then fails at compile time. An SPI bus must declare `sclk` and `mosi`. A device on an SPI bus must declare a `cs` pin, which is the one pin name not taken from the driver's descriptor. Bus ids name the chip's peripherals on embedded: `i2c0` (and `i2c1` only where the chip has one), and `spi2` or `spi3` for the user SPI buses. On Linux the id is a free name. `chip:` accepts `esp32c5`, `esp32c6`, `esp32c61` or `linux`. Any other value fails, with the list of supported chips named in the error. A chip outside that list cannot be added by configuration for now. On Linux, a bus carries a `dev_path` instead of pins: `/dev/i2c-1` for I²C, `/dev/spidev0.0` for SPI (with `pins: {}`). An SPI device's `pins.cs` stays a GPIO line number, driven by the Signal Layer itself. ## `gpios.general_purpose` The pins this board exports to cells. A cell reaches these through the GPIO host functions and addresses them by their real GPIO number; nothing else is offered. Two rules, both enforced: - **Bus pins must not appear here.** They are declared under `buses` and are reserved for the bus. - **Device pins must not appear here.** A pin a device claims under its `pins:` is reserved for that device, exactly like a bus pin. Every pin the signal layer uses is reserved and kept out of this list, so the list is only the pins left free for cells. Pins outside the chip's known layout are rejected. Note the layout is the set of pins the runtime can expose, which is narrower than the chip's full GPIO count, so some otherwise usable pins cannot carry a device. ## `devices` | Key | Required | Meaning | |---|---|---| | `id` | yes | Name the pipeline uses to refer to this device | | `driver` | yes | Directory name from the [drivers reference](./03_drivers.md) | | `bus` | no | Bus id; omit for a device driven straight from GPIO | | `pins` | no | Role to GPIO number, using the roles the driver declares | | `hardware` | no | Settings the driver declared as `scope: hardware` | Pin role names must be declared in the driver's descriptor, except `cs` on an SPI bus. A GPIO may be claimed by only one device. `id` and `driver` must both be valid Rust identifiers, as must every bus id. ## Where a setting goes Each driver marks every setting it accepts with a scope, and the scope decides the file: | Scope | Belongs in | Typical example | |---|---|---| | `hardware` | this file, under `hardware:` | an I²C address fixed by a solder bridge | | `application` | the pipeline, under `config:` | how often to sample | Putting one in the wrong file is rejected, and the message names the field. A key that matches no setting at all is silently ignored, so a typo in a setting name is not reported. # Drivers A driver is what knows one device. A board file names a driver on a device; a pipeline then reads that device as a source or writes to it through an outlet. Every driver in the tree is listed below. A device's `driver:` value is its directory name, and the crate it resolves to is that name plus `-driver`. ## Sensor drivers These produce values a pipeline can tap. | Driver | Reads over | Publishes | Extra pins | |---|---|---|---| | `ads1115` | I2C | `ain0` (f32, V), `ain1` (f32, V), `ain2` (f32, V), `ain3` (f32, V) | - | | `bme280` | I2C | `temperature` (f32, °C), `pressure` (f32, hPa), `humidity` (f32, %RH) | - | | `bmp180` | I2C | `temperature` (f32, °C), `pressure` (f32, hPa) | - | | `ccs811` | I2C | `eco2` (f32, ppm), `tvoc` (f32, ppb) | `nint` | | `lsm6dso32` | SPI | `accel_x` (f32, g), `accel_y` (f32, g), `accel_z` (f32, g), `gyro_x` (f32, dps), `gyro_y` (f32, dps), `gyro_z` (f32, dps), `temperature` (f32, °C) | - | | `sim-source` | I2C | `value` (f32) | - | | `spi-loopback` | SPI | `echo_ok` (f32), `counter` (f32) | - | | `veml7700` | I2C | `lux` (f32, lux) | - | | `wsen-itds` | I2C | `accel_x` (f32, g), `accel_y` (f32, g), `accel_z` (f32, g) | - | ## Output drivers These consume a command written to an outlet. | Driver | Command | Mode | Pins | Reports back | |---|---|---|---|---| | `gpio-output-feedback` | `DigitalState` | digital | `out`, `feedback` | `contact` | | `gpio-output` | `DigitalState` | digital | `out` | nothing | | `pwm-output` | `PwmDuty` | pwm | `out` | nothing | ## Each driver in detail ### `ads1115` Texas Instruments ADS1115 16-bit 4-channel ADC over I2C. Reads all four single-ended channels (AIN0-AIN3) and reports voltages. **Requires** - bus: I2C **Publishes** | Name | Type | Unit | |---|---|---| | `ain0` | `f32` | V | | `ain1` | `f32` | V | | `ain2` | `f32` | V | | `ain3` | `f32` | V | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `i2c_addr` | board file | `u8` | `72` | | `fs_mv` | pipeline | `FullScale` | `Mv2048` | | `data_rate` | pipeline | `DataRate` | `Sps128` | | `sample_interval_ms` | pipeline | `u64` | `1000` | ### `bme280` Bosch BME280 environmental sensor — temperature, pressure, and humidity over I2C. **Requires** - bus: I2C **Publishes** | Name | Type | Unit | |---|---|---| | `temperature` | `f32` | °C | | `pressure` | `f32` | hPa | | `humidity` | `f32` | %RH | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `i2c_addr` | board file | `u8` | `118` | | `osrs_t` | pipeline | `Oversampling` | `X1` | | `osrs_p` | pipeline | `Oversampling` | `X1` | | `osrs_h` | pipeline | `Oversampling` | `X1` | | `filter` | pipeline | `Filter` | `Off` | | `t_sb` | pipeline | `Standby` | `Ms0_5` | | `sample_interval_ms` | pipeline | `u64` | `1000` | ### `bmp180` Bosch BMP180 temperature and barometric pressure sensor over I2C. **Requires** - bus: I2C **Publishes** | Name | Type | Unit | |---|---|---| | `temperature` | `f32` | °C | | `pressure` | `f32` | hPa | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `i2c_addr` | board file | `u8` | `119` | | `oss` | pipeline | `Oversampling` | `Single` | | `sample_interval_ms` | pipeline | `u64` | `1000` | ### `ccs811` ScioSense CCS811 indoor air quality sensor over I2C. Reports equivalent CO2 (eCO2) and total volatile organic compounds (TVOC). **Requires** - bus: I2C; pins: `nint` **Publishes** | Name | Type | Unit | |---|---|---| | `eco2` | `f32` | ppm | | `tvoc` | `f32` | ppb | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `i2c_addr` | board file | `u8` | `90` | | `meas_mode` | pipeline | `MeasMode` | `Every1s` | | `sample_interval_ms` | pipeline | `u64` | `10000` | ### `gpio-output-feedback` Hybrid digital output with intrinsic feedback: drives a relay/output on the `out` pin (consuming a DigitalState Outlet) AND reads the device's real state from a separate `feedback` input pin (e.g. a relay's auxiliary contact). The status comes only from the real pin read — never inferred from the command write (SDS A1 / OUT-09). **Requires** - pins: `out`, `feedback` **Publishes** | Name | Type | Unit | |---|---|---| | `contact` | `bool` | - | **Accepts** - `DigitalState` in `digital` mode **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `active_low` | board file | `bool` | `false` | | `min_switch_interval_ms` | board file | `u64` | `0` | | `feedback_active_low` | board file | `bool` | `false` | ### `gpio-output` Digital on/off GPIO output (relay, LED, valve, …). Consumes a DigitalState Outlet and drives a single GPIO high/low, honouring active-low wiring. **Requires** - pins: `out` **Accepts** - `DigitalState` in `digital` mode **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `active_low` | board file | `bool` | `false` | | `min_switch_interval_ms` | board file | `u64` | `0` | ### `lsm6dso32` STMicroelectronics LSM6DSO32 6-axis IMU over SPI. Reports 3-axis acceleration (g), 3-axis angular rate (dps), and die temperature. **Requires** - bus: SPI **Publishes** | Name | Type | Unit | |---|---|---| | `accel_x` | `f32` | g | | `accel_y` | `f32` | g | | `accel_z` | `f32` | g | | `gyro_x` | `f32` | dps | | `gyro_y` | `f32` | dps | | `gyro_z` | `f32` | dps | | `temperature` | `f32` | °C | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `accel_odr` | pipeline | `Odr` | `Hz104` | | `gyro_odr` | pipeline | `Odr` | `Hz104` | | `accel_scale` | pipeline | `AccelScale` | `G4` | | `gyro_scale` | pipeline | `GyroScale` | `Dps250` | | `sample_interval_ms` | pipeline | `u64` | `1000` | ### `pwm-output` PWM duty-cycle output (fan, pump, dimmable LED, …). Consumes a PwmDuty Outlet (a 0.0–1.0 duty fraction) and drives a PWM channel. The driver clamps to its configured range as a non-negotiable floor. **Requires** - pins: `out` **Accepts** - `PwmDuty` in `pwm` mode **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `min_duty` | board file | `f32` | `0.0` | | `max_duty` | board file | `f32` | `1.0` | | `min_update_interval_ms` | board file | `u64` | `0` | ### `sim-source` Synthetic deterministic source for hardware-in-the-loop tests. Satisfies the driver contract but ignores the bus and emits a bounded sawtooth ramp, so the dataplane HIL suite can assert on exact tap values, moving-average output, and threshold-trigger alarms without any physical sensor. **Requires** - bus: I2C **Publishes** | Name | Type | Unit | |---|---|---| | `value` | `f32` | - | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `start` | pipeline | `f32` | `0.0` | | `step` | pipeline | `f32` | `1.0` | | `max` | pipeline | `f32` | `100.0` | | `sample_interval_ms` | pipeline | `u64` | `500` | ### `spi-loopback` SPI loopback test source. Each sample full-duplex-transfers an incrementing byte pattern and reports whether the echo matched: with MOSI wired to MISO it proves the whole SPI path (bus, mode, clock, chip-select) on real hardware; without the jumper it reads 0. Not a sensor — the SPI counterpart of sim-source for bring-up and HIL tests. **Requires** - bus: SPI **Publishes** | Name | Type | Unit | |---|---|---| | `echo_ok` | `f32` | - | | `counter` | `f32` | - | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `transfer_len` | pipeline | `u8` | `8` | ### `veml7700` Vishay VEML7700 ambient light sensor over I2C. **Requires** - bus: I2C **Publishes** | Name | Type | Unit | |---|---|---| | `lux` | `f32` | lux | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `i2c_addr` | board file | `u8` | `16` | | `gain` | pipeline | `Gain` | `X1` | | `integration_time` | pipeline | `IntegrationTime` | `Ms100` | | `sample_interval_ms` | pipeline | `u64` | `1000` | ### `wsen-itds` Würth Elektronik WSEN-ITDS 3-axis MEMS accelerometer over I2C. **Requires** - bus: I2C **Publishes** | Name | Type | Unit | |---|---|---| | `accel_x` | `f32` | g | | `accel_y` | `f32` | g | | `accel_z` | `f32` | g | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `i2c_addr` | board file | `u8` | `24` | | `full_scale_g` | pipeline | `FullScale` | `G2` | | `odr` | pipeline | `Odr` | `Hz100` | | `power_mode` | pipeline | `PowerMode` | `Normal` | | `sample_interval_ms` | pipeline | `u64` | `100` | # Pipeline file The pipeline file says what a node does with its hardware: which devices produce readings, what happens to those readings, and what a cell can see and change. It names devices, not pins, so the same pipeline runs against any board whose devices match. In a project scaffolded by `myrmic signal-layer new` it is named `pipeline.yml`. ```yaml pipeline: id: basic-sensors sources: [] steps: [] taps: [] outlets: [] ``` Only `pipeline.id` is required. The four lists all default to empty. ## `sources` Binds a device from the board file and runs it. | Key | Required | Meaning | |---|---|---| | `id` | yes | Name used to refer to this source's readings | | `device` | yes | A device `id` from the board file | | `config` | no | Settings the driver declared as `scope: application` | `sample_interval_ms` is accepted in `config` on every sensor source. It is not part of the driver's own configuration: the pipeline uses it to set the loop rate. When it is omitted, the driver's descriptor default applies, which differs per device. ## `steps` Transforms a value on its way through. | Key | Required | Meaning | |---|---|---| | `id` | yes | Name used to refer to this step's output | | `op` | yes | Which step module, from the [steps reference](./04_steps.md) | | `input` | yes | What feeds it | | `config` | no | Settings the step declared | A step has exactly one input. Several steps may share one input, so a value can fan out. ## `taps` Publishes a value under a name a cell can resolve. | Key | Required | Meaning | |---|---|---| | `name` | yes | The name a cell resolves | | `kind` | yes | `retained` or `event` | | `type` | yes | The declared payload type | | `source` | yes | What produces the value | `retained` holds the latest value with a timestamp and reading does not consume it. `event` is a queue the reader drains, and carries no timestamp. A third kind, `batch`, is reserved for planned work. Declaring one fails generation with `batch taps not yet supported by codegen`. ## `outlets` Exposes a value a cell, or a step, can write. | Key | Required | Meaning | |---|---|---| | `name` | yes | The name a cell resolves | | `type` | yes | The value type the driver accepts | | `device` | yes | A device `id` from the board file | | `input` | no | A step whose output drives this outlet with no cell involved | | `config` | no | Settings for the outlet | `write_interval_ms` in `config` sets how often the device's task applies the latest value. It defaults to **100 ms** and must be at least 1. A device may be driven by exactly one outlet. ## What can be referenced Wherever a `source:` or an `input:` is expected, one of these forms is accepted: | Form | Refers to | |---|---| | `.` | one of a driver's published outputs | | `` | the output of a step | | `.` | a read-back from a device that reports its state | | `.error` | faults from that outlet, as `OutletFault` | ## Payload types These are the type names accepted in a tap's or outlet's `type` field. | Type | Used for | |---|---| | `f32`, `f64` | measurements | | `u8`, `u16`, `u32`, `u64`, `usize` | counts and raw values | | `i32`, `i64` | signed values | | `bool` | on/off state, such as a contact read-back | | `DigitalState` | value for an on/off output | | `PwmDuty` | value for a duty-cycle output | | `ThresholdAlarm` | event from a threshold step | | `OutletFault` | event from an outlet's `.error` | | `HealthEvent`, `DriverHealth` | source health, on `_signal_layer_health` | A tap's declared type is checked twice: against what produces it during generation, and against what a cell asks for at runtime. The typed SDK calls compare their type with the declared one before decoding and fail with a type-mismatch error; payloads are decoded strictly, refusing trailing bytes. Only the raw byte reads and writes bypass the cell-side check. ## Limits | Limit | Value | |---|---| | Taps per pipeline | 16, of which 1 is reserved for `_signal_layer_health` when the pipeline has any source | | Outlets per pipeline | 8 | | Events held per event tap | 8, oldest dropped when full | ## Reserved names Names beginning with `_` are reserved for taps the generator injects. Today that is `_signal_layer_health`, added automatically to any pipeline with at least one source. # Running on Linux On a microcontroller the Signal Layer is part of the firmware, so it is there whenever a cell is. On Linux it is a separate process, and that difference is the whole of this page. The pipeline runs as a standalone process that opens the buses, applies the steps, and serves named values to the runtime over a Unix-domain socket. It has to be running before a cell can read anything. ## Socket path Both sides resolve the socket path with the same function, so no configuration is needed when they run as the same user. The rule, in order: 1. If `/run/peeriot/` exists and is writable by the effective user, use `/run/peeriot/signal-layer.sock`. 2. Otherwise, if `$XDG_RUNTIME_DIR` is set, use `$XDG_RUNTIME_DIR/peeriot-signal-layer.sock`. 3. Otherwise fail closed. There is deliberately no `/tmp` fallback. The socket is protected only by filesystem permissions, mode `0660`, and a path under `/tmp` would be reachable by any user on the machine. There is no runtime override. Control the path by setting `XDG_RUNTIME_DIR` or by making `/run/peeriot/` writable. The two sides fail differently when no path resolves. The pipeline process aborts, because a pipeline nobody can reach is not useful. The runtime keeps running and reports taps as unavailable. The pipeline removes the socket file when it stops. A crash leaves the file behind: a runtime connecting to it is refused and reports the taps as unavailable, and the next pipeline start removes the stale file before binding. ## Connection behaviour The runtime connects lazily, on a cell's first tap call. If the pipeline is not running, resolving a tap returns "not found" and reads return unavailable, which are the same answers a cell already handles for a name that does not exist. **A cell therefore cannot distinguish a missing tap from a missing pipeline.** Reconnection is also lazy. The host retries on the next tap call after the socket becomes reachable, so a cell that has stopped calling will not reconnect on its own. Every call is bounded at five seconds. A cell polling a stalled pipeline will stall with it for that long per call. Handles do not survive a reconnect. After the connection is rebuilt, a read through a handle issued before it returns an error, and the cell should resolve the name again. ## One caution on startup The socket is created before the buses are opened, and a failure to open a bus is fatal. So a pipeline that is about to abort can briefly present a listening socket. A cell connecting in that window will succeed and then find the pipeline gone. ## What Linux supports | | Embedded | Linux | |---|---|---| | Sensors over I²C | yes | yes | | Sensors over SPI | yes | yes | | Actuators (outlets) | yes | yes | | Processing steps | yes | yes | | Batch taps | reserved | reserved | The board file differs too: on Linux a bus names a kernel device path instead of pins - `/dev/i2c-1` for I²C, `/dev/spidev0.0` for SPI - and `chip:` is `linux`. An SPI device still declares its chip-select as a GPIO under `pins.cs`, exactly as on embedded: the kernel's own chip-select is disabled and the Signal Layer drives the line itself around each transfer. The device list carries over unchanged, because a sensor keeps the same driver and the same address wherever it is plugged in. # Steps A step transforms a value on its way through a pipeline. A pipeline names one with `op:`, which is both the directory below and the crate name, with no suffix. There are 7 steps in the tree. | Step | Takes | Produces | Configuration | |---|---|---|---| | `cadence` | any | same as input | `every`, `mode` | | `fan-curve` | `f32` | `PwmDuty` | `in_min`, `in_max`, `out_min`, `out_max` | | `hysteresis` | `f32` | `DigitalState` | `on_threshold`, `off_threshold` | | `max-value` | `f32` | `f32` | - | | `min-value` | `f32` | `f32` | - | | `moving-average` | `f32` | `f32` | `window` | | `threshold-trigger` | `f32` | `ThresholdAlarm` | `threshold`, `fire_below` | ## Each step in detail ### `cadence` Cadence a path: pass one of every `every` samples, controlling how often the downstream (typically an Outlet) is recomputed and written. On the ticks between samples it either drops the value (Decimate) or re-emits the last sampled value (SampleHold). Type-transparent (generic over the value it carries), so it declares no fixed input/output type. Type-transparent: it declares no fixed input or output type and passes through whatever it carries. **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `every` | pipeline | `u32` | `1` | | `mode` | pipeline | `CadenceMode` | `Decimate` | ### `fan-curve` Feed-forward transfer function mapping an input reading (e.g. temperature) to a PWM duty via a linear curve, clamped to the output range. Drives a PWM Outlet directly. Threshold/hysteresis's continuous counterpart — no PID. | | Name | Type | |---|---|---| | in | `value` | `f32` | | out | `command` | `PwmDuty` | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `in_min` | pipeline | `f32` | `0.0` | | `in_max` | pipeline | `f32` | `100.0` | | `out_min` | pipeline | `f32` | `0.0` | | `out_max` | pipeline | `f32` | `1.0` | ### `hysteresis` Two-threshold hysteresis controller for feed-forward actuator control. Turns ON when the input rises to/above `on_threshold` and OFF when it falls to/below `off_threshold`, emitting a DigitalState only on a transition (edge). Drives a digital Outlet directly. | | Name | Type | |---|---|---| | in | `value` | `f32` | | out | `command` | `DigitalState` | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `on_threshold` | pipeline | `f32` | `0.0` | | `off_threshold` | pipeline | `f32` | `0.0` | ### `max-value` Running maximum: keeps the largest value seen so far and emits it on every sample, so the output is monotonically non-decreasing. Seeded at negative infinity, so the very first sample is always its own maximum: there is no warm-up, and the step always emits, never nothing. Unconfigurable and time-independent, with no window, decay or reset, so a single outlier pins the output high for the lifetime of the pipeline. | | Name | Type | |---|---|---| | in | `value` | `f32` | | out | `max` | `f32` | **Configuration** _No configuration._ ### `min-value` Running minimum: keeps the smallest value seen so far and emits it on every sample, so the output is monotonically non-increasing. Seeded at positive infinity, so the very first sample is always its own minimum: there is no warm-up, and the step always emits, never nothing. Unconfigurable and time-independent, with no window, decay or reset, so a single outlier pins the output low for the lifetime of the pipeline. | | Name | Type | |---|---|---| | in | `value` | `f32` | | out | `min` | `f32` | **Configuration** _No configuration._ ### `moving-average` Arithmetic mean over a sliding window of the last `window` samples, summed afresh from a ring buffer on every sample so no running accumulator can drift. Emits nothing at all until the window has filled: the first `window - 1` samples yield no value, and every sample after that yields the mean of the most recent `window`. It never emits a partial-window average or a placeholder, so anything downstream is simply not updated during the warm-up, and once filled it never returns to that state. `window` is silently clamped to 1..=64, so 0 becomes 1 (each sample passed through as its own average) and anything above 64 becomes 64. | | Name | Type | |---|---|---| | in | `value` | `f32` | | out | `average` | `f32` | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `window` | pipeline | `usize` | `8` | ### `threshold-trigger` Edge-triggered threshold alarm. Emits one ThresholdAlarm on each transition into the trigger region and nothing otherwise, neither while the input stays there nor when it leaves, so there is no cleared event and a consumer cannot learn from this step when the condition ends. Re-entering fires again, and with no hysteresis band or dwell time an input dithering across the threshold re-fires on every crossing (use `hysteresis` where that matters). `fire_below` picks the side: `false` (the default) makes the region `value > threshold`, `true` makes it `value < threshold`. Both comparisons are strict, so a sample equal to `threshold` never fires. The step starts inactive, so a first sample already inside the region counts as a transition. The alarm carries the sample that fired it and the configured threshold. | | Name | Type | |---|---|---| | in | `value` | `f32` | | out | `alarm` | `ThresholdAlarm` | **Configuration** | Field | Where it is set | Type | Default | |---|---|---|---| | `threshold` | pipeline | `f32` | `0.0` | | `fire_below` | pipeline | `bool` | `false` | # Roadmap Myrmic is released as a developer preview. The current preview already implements a number of key concepts, and these are being expanded with additional features. This page gives an overview of the current state, of the final goal, and of the stages in between. Rather than publish dates, this roadmap names the **guarantee each stage closes** and the **demonstration that proves it**. A stage is complete when users can reproduce its demonstration, not when a date arrives. ## The Current Implementation: Basic Cell One runtime for stateful distributed applications: - Cells with durable identities, addressed by a Stable Resource Identifier (SRI), - tracked and best-effort delivery through Mailboxes, - WebAssembly isolation from Linux systems down to supported MCUs, - placement by capability tags, - a generated native Signal Layer for sensors and actuators, - failure handling that is conservative and predictable. When a Node is lost, its deployments are removed and the loss is reported. The preview does not claim that a Cell automatically resumes elsewhere with its State intact. What a Swarm Admin can already do is configure replication of a Cell's data to selected Nodes [by hand](./10_reference/02_myrmic-cli/15_replicate.md). This gives a basic form of failover today: the data survives the Node, and the Cell can be redeployed where a replica lives. **Try it:** run the quickstart, place a Cell by capability tags, and compare what happens after Node loss with the guarantee page. ## The Final Goal: Sovereign Cells Today a Cell lives and dies with its Node. The final goal of the roadmap is to turn that around: a **Sovereign Cell** is a Cell that outlives the Node it runs on. Its identity, its authority, and its data are all replicated, so that losing any single Node changes *where* the Cell runs, but not *whether* it runs, *what* it knows, or *who* it is. Application code is written once, against a Cell, and the Swarm takes care of keeping that Cell alive. Two properties make a Cell sovereign: - **Partition tolerance.** The Swarm keeps working correctly when a Node disappears or the network splits into parts that cannot reach each other. For every Cell there is, at all times, exactly one place that may decide and serve — never none, and never two. For the developer this means no split-brain, no coordinator that has to be kept alive, and lifecycle operations that either take effect once or report that they did not. - **Durability.** Everything a Cell has acknowledged survives the loss of a Node, and the Cell resumes on another Node with exactly the State it had. For the developer this means no hand-written replication or recovery logic inside the application: **kill a Node, keep the Cell.** Both properties come with one deliberate limit. If a Consistent Cell loses its majority, it halts rather than inventing a new truth. Recovery then requires a deliberate action by a Swarm Admin. > **Basic Cell + Partition Tolerance + Durability = Sovereign Cells.** A Cell whose authority and data are both replicated can outlive its Node. Partition Tolerance alone preserves the decision about who may serve, while the Cell's data can still be lost with its Node; only with Durability does the Cell's State itself survive. Finally, a Swarm in production also has to withstand adversaries and change: Nodes and Cells must prove who they are, Nodes must join and leave while Cells keep running, and upgrades need defined semantics. These concerns form the last stage of the roadmap, **Secure Swarm**. ## The Roadmap Stages The stages below are ordered by dependency: each builds on the guarantees of the one before it, and each is complete when its demonstration can be reproduced. ![Myrmic roadmap from Basic Cell through Partition Tolerance and Durability to Secure Swarm](../images/roadmap-stages.svg) ### Partition Tolerance - replicate authority The decisive step towards partition tolerance is deciding who has authority over each Cell. Authority means the right to make the runtime decisions about a specific Cell — which Node may run it, whether a deploy or stop has taken effect, and which of two copies is the real one. The mechanism that assigns this authority must satisfy two conditions: it must be fully decentralised, with no coordinator Node that all others depend on, and it must itself survive failures — a Node loss or a partition cannot leave any Cell without a way to reach a decision. The current proposal is to obtain this through a **quorum-based** approach. Every Cell instance is assigned a small group of Nodes, its voter set. A decision about that Cell is valid only once a majority of its voter set — a quorum — has agreed to it, and the voter set elects one of its members as leader to propose decisions and collect votes. Because the voter set is per Cell, authority is per Cell as well: different Cells can be governed by different Nodes. Leadership, membership, and serving authority thus stop depending on one coordinator and become majority decisions. This mechanism does **not** replicate Cell State or Mailboxes: it preserves the decision about who may serve while the Cell's data still exists in one place. The quorum-based approach adds: - authority held by a voter set of several Nodes, not by one coordinator, - a leader elected by each Cell's voter set, - fencing, so that only one copy of a Cell is ever actively serving, - recovery models declared by Cells, - deploy and undeploy operations that are idempotent and acknowledged. Together these five properties enable what we call Partition Tolerance: no single Node holds the decisions about a Cell, a split network cannot produce two serving copies, and every lifecycle operation either takes effect once or reports that it did not. Partition Tolerance is a runtime cutover, not a side-by-side feature flag: once a Swarm runs it, every Cell is governed this way. **Demonstration**: stop the Node that currently leads a Cell. Leadership moves to another voter within seconds, and no Cell serves twice. The scenario can be replayed from a seed. ### Durability - replicate data Durability makes **what the Cell knows** survive. The Cell's committed State and Mailboxes are replicated across several Nodes, and a write is acknowledged only once a majority of them has stored it. Every write operation that a Consistent Cell has acknowledged therefore survives the loss of one Node, and the Cell can resume on another eligible Node with exactly the State it had. The replicated data approach adds: - atomic delivery of Messages across Nodes, - request identity and deduplication, - durable timers, - Cell resume with committed State after Node loss. Together these properties enable what we call **Durability**: nothing a Cell has acknowledged is lost with a single Node, and the Cell comes back where a copy of its data lives. **Demonstration:** **Kill a Node. Keep the Cell.** ### Secure Swarm - operate with trust Secure Swarm makes the Swarm **trustworthy to run in production**. Sovereign Cells survive failures; Secure Swarm adds what a Swarm Admin needs to trust the Nodes they run on and to keep the Swarm running over time: - an authenticated fabric with a full key lifecycle, so that Nodes and Cells carry cryptographic proof of where they come from, - membership reconfiguration, so that Nodes can join or leave a Cell's voter set without stopping the Cell, - controlled self-healing, - upgrade semantics, - Convergent Cells with a declared, defensible merge rule. ## Durability is research before engineering Only the first two steps towards Durability have a fixed order: measure what the Data Layer guarantees today, then choose the consistency target. Everything after that depends on the evidence. Every proposed design must survive review, and two have already been rejected. The roadmap will not publish dates or performance numbers before the corresponding design and evidence exist. ## See also - [Guarantees](./08_guarantees.md) - what the current release promises, and what it doesn't yet - [Architecture](./07_architecture.md) - the four views and the six layers # Security This page covers the security mechanisms the developer preview implements today. ## Transport Authentication and Encryption Myrmic Nodes can authenticate each other and protect the traffic between them with mutual TLS. It is configured on the Zenoh transport link, where `enable_mtls` turns on certificate verification in both directions and `verify_name_on_connect` requires the name a Node is reached by to appear in the Subject Alternative Name of the certificate it presents, with endpoints declared under the `tls/` scheme. Each Node presents its own certificate chain for both listening and connecting. A Node accepting a connection validates the client's chain against the configured root alone. A Node dialling one validates the server's chain against the configured root **and** the public Web PKI root list, which the transport seeds the trust store with before adding your root, so the set of anchors accepted in the dialling direction is wider than the one you configured - see [Addresses that change](#addresses-that-change) below for what that costs when the name check is off. The Zenoh session runs inside that link, so traffic between two directly connected Nodes is encrypted and integrity-protected, and because Zenoh relays hop by hop a forwarding Node terminates the link and handles what it passes on in the clear. Mutual TLS is off in the default configuration and is turned on per deployment. Issuing the certificates is the deployment's responsibility, because the preview ships no CA service, and `swarm/tutorials/mTLS/` brings up a complete multi-node environment with a locally created CA hierarchy that stands in for one. ## Addresses that change A Node that changes its IP address rejoins the swarm on its own, without a restart - provided its listen endpoint is not bound to an address the host has just given up. Which listen shapes those are is a property of the transport and holds with or without mutual TLS. Mutual TLS then adds a second condition, because the name a dialler verifies is the host part of the endpoint it dialled, and there is no separate setting that overrides it. > This describes the runtime release that carries the host interface poll. Release 0.6.1 does not have it: a Node there does not notice an address change at all and needs a restart whatever its listen endpoint looks like. **Listen on an unspecified address.** `tls/0.0.0.0:7447` or `tls/[::]:7447` is the shape that survives a move. The socket is bound to no particular host address, so it keeps accepting once the host's addresses change, and the Node recomputes the addresses it announces from the interfaces it holds at that moment. Put the Node's DNS name in the Subject Alternative Name of its certificate, and the same name in the `connect` endpoints of the peers that have to reach it: when the link drops those peers redial by name, resolution follows the Node to its new address, and the name check passes. This is the supported shape for any deployment whose Nodes can change address, and it needs name resolution that follows the Node - whatever answers for that name has to return the new address, or diallers keep going to the old one. **A listen endpoint that carries a name or an address does not survive.** `tls/node-7.example.internal:7447` and `tls/192.0.2.10:7447` are the same case in the transport: the endpoint is resolved once, at start, and the socket is bound to the concrete address that came back. Once the host gives that address up the socket is still open and accepts nothing, and the Node goes on announcing a locator that no longer reaches it. Nothing rebinds the listener; only a restart does. Declaring the name on the listen endpoint therefore buys nothing - the name belongs in the certificate and in the diallers' `connect` endpoints, not in the listen endpoint. `swarm/tutorials/mTLS/` uses named listen endpoints throughout, which is fine for its containers because their addresses do not move, and is not a shape to copy for Nodes whose addresses do. **Certificates issued for IP addresses keep the restart requirement, even behind a surviving listener.** This is a supported shape rather than an oversight, but it gains nothing from a Node surviving an address change. A Node listening on an unspecified address announces itself as IP literals, so after a move it announces addresses its certificate has no `iPAddress` entry for, and a peer dialling one of them fails the handshake. Nothing about the certificate changed - what the peer expects did. Clearing that means issuing a certificate for the new address and restarting the Node with it. The failure surfaces in the dialler's log, under the target `zenoh::net::runtime::orchestrator`, as `Unable to connect to ...!` carrying rustls' `NotValidForNameContext` - printed as `certificate not valid for name "..."; certificate is only valid for ...`. Grep for `certificate not valid for name`, and note that it needs a filter that lets that target through at `warn`; see [Operating a swarm](./05_guides/09_operating-a-swarm.md#discovery-identity-and-placement). The same mechanism is the one caveat on the supported shape. What a Node announces are IP literals whatever its certificate says, so a peer that learned the Node only by gossip or scouting dials a literal and fails the name check against a DNS-only certificate. That is why the peers that must reach a mobile Node carry its name in their own `connect` endpoints: those redials are by name and are unaffected. Adding `iPAddress` entries to the certificate makes the gossiped locators diallable too, but only until the next move, which puts you back in the restart-requiring shape above. The outbound direction is unaffected either way. A Node accepting a connection validates the client's chain, its validity and its `clientAuth` extended key usage, and never compares a name to the peer's address, so a moved Node can still dial out and be authenticated. `verify_name_on_connect: false` switches the name check off and makes every shape survive a move as far as the certificate is concerned. It is an escape hatch, never a supported shape for a deployment whose addresses change. With the check off, a dialler accepts any unexpired certificate that chains to an anchor in its trust store, and that store holds the whole public Web PKI alongside your configured root: **any certificate issued by any publicly trusted CA - not only by your root - can impersonate any Node to any dialler**, and no extended key usage is checked either. The name check is the only thing tying a certificate to the peer you meant to reach, and a Node on the discovery plane can already steer a dial to an address of its choosing. This is how the transport has always behaved; the address-change work did not introduce it and does not change it. ## Network trust in the default configuration With mutual TLS off, which is the default, the network segment is the trust boundary. Any runtime that can reach the others on the segment joins the same swarm, with no explicit join step and no authentication, and messages between Nodes carry no cryptographic proof of the sender. Treat the segment as trusted: keep runtimes on a network you control, and use a dedicated segment to keep separate groups of machines from merging into one swarm. Turning on mutual TLS narrows that boundary to the holders of a certificate issued under your root. ## Cell Isolation Every Cell runs as a WebAssembly module inside a runtime that mediates its access to the Node. On OS-based Nodes that runtime is Wasmtime, and on supported MCUs it is WAMR, compiled ahead of time and executed in place from flash. In both cases the module reaches the host only through the host-call families its runner links into it, which include Cell commands and events, timers, the data layer, and the Signal Layer taps and outlets. Neither target links WASI, so a Cell has no ambient access to the filesystem, to sockets, to processes, or to the host clock, and it addresses its own linear memory alone. On OS-based Nodes the runtime meters guest instruction execution with Wasmtime fuel, so the computation a Cell performs is bounded by the fuel its runner grants it. ## Coming The security work still ahead, including an authenticated fabric with a full key lifecycle so that Nodes and Cells carry cryptographic proof of where they come from, is the **Secure Swarm** stage of the [Roadmap](./09_roadmap.md). --- sidebar_label: Application Domains --- # Application Domains Myrmic provides one edge-first application model, but different teams reach it through different problems. Choose the path closest to what you are building. Each page separates what the developer preview demonstrates from what the roadmap stages — Partition Tolerance, Durability, and Secure Swarm — are designed to add. ## Asset-centric software ### Make every asset a first-class application participant For teams whose software view of a machine, building, room, energy system, or other asset is scattered across telemetry, databases, gateways, and rule engines. [Explore asset-centric software](./03_target-groups/01_asset-centric-software.md) ## Connected products ### Build the product, not another proprietary device platform For product teams that need reusable application logic across device generations without giving up native hardware performance. [Explore connected products](./03_target-groups/02_connected-products.md) ## Real-time applications ### Give every room, session, and match a durable home For teams whose real-time concepts outlive the WebSocket process currently serving them. [Explore real-time applications](./03_target-groups/03_real-time-applications.md) ## Workflows and agents ### Give long-running work a place to live For systems that need durable context, timers, asynchronous continuation, and explicit recovery semantics. [Explore workflows and agents](./03_target-groups/04_workflows-and-agents.md) ## Platform engineering ### Give developers one stateful application primitive For platform teams supporting developers who repeatedly rebuild state, messaging, scheduling, placement, and recovery. [Explore platform engineering](./03_target-groups/05_platform-engineering.md) ## Different entry points, one platform Across all five groups: - long-lived concepts become addressable Cells, - state and behaviour stay together, - Commands, Events, and callbacks connect the application, - capability tags guide placement, - the Signal Layer keeps hardware-near work native, - the same model spans OS-based and MCU-based Nodes, - stronger authority and data guarantees arrive in explicit roadmap stages. ## See also - [Why Myrmic](./02_why-myrmic.md) - the mission behind Myrmic - [Concepts](./06_concepts.md) - the vocabulary every other page assumes - [Guarantees](./08_guarantees.md) - what the current release promises, and what it doesn't yet - [Roadmap](./09_roadmap.md) - what future stages are intended to add --- sidebar_label: Asset-Centric Software --- # Make every asset a first-class application participant Physical assets exist continuously. Their software representation often does not. State is split across telemetry, gateways, database records, rule engines, and remote services. The application must reconstruct the asset from scattered streams and records. ## The Myrmic approach Model each asset as a Cell with stable identity and State, while keeping the physical boundary explicit. ```text sensor or actuator ↓ native Signal Layer ↓ Adapter Cell placed by capability tags ↓ Commands and Events Asset Cell ``` The Signal Layer acquires and processes data close to the asset. The Adapter translates local signals into the application model. The Asset Cell owns canonical state, policy, and behaviour. ## What the preview demonstrates - stable identity for the asset, - local native signal processing, - placement by capability tags, - Cell State and Mailboxes held as one copy by default, - one interface for other Cells, CLI clients, and web applications, - explicit delete-and-report behaviour after Node loss. ## What the roadmap adds Partition Tolerance introduces the **Consistent** recovery model and replicated authority, so the decision about which Node serves an Asset Cell survives Node loss. Durability replicates the Asset Cell's State and Mailboxes, so the Cell itself can resume on an eligible Node with the State it had. Together, those two properties make the Asset Cell a Sovereign Cell: it outlives the Node it runs on. ## Good fits - machines and production assets, - buildings and rooms, - energy systems, - technical infrastructure, - distributed equipment fleets, - non-safety-critical local automation. ## Boundary Myrmic is not a certified safety controller. Keep hard-real-time and functional-safety functions in systems designed for them. ## See also - [Application Domains](../03_target-groups.md) - the other entry points Myrmic supports - [Connecting Physical Systems](../02_why-myrmic/04_connecting-physical-systems.md) - how Cells relate to native drivers and hardware I/O - [Recovery Models](../06_concepts/06_recovery-models.md) - what happens to a Cell after a restart or Node loss --- sidebar_label: Connected Products --- # Build the product, not another proprietary device platform Connected-product teams increasingly have to build connectivity, state, local processing, gateways, hardware integration, and separate stacks for every device class. They are often forced to choose between portable software that hides valuable hardware differences and hardware-specific software that is difficult to reuse. ## The Myrmic approach Separate the stable product contract from its native implementation. ```text portable product logic WebAssembly Cells ↓ Capability contract ↓ native implementation for each target Signal Layer · drivers · optimized Rust ``` Cells contain product state, modes, configuration, messaging, and user-facing behaviour. Native Rust handles drivers, hardware-near processing, diagnostics, and target optimization. ## What the preview demonstrates - one Cell model across Linux and supported bare-metal Nodes, - explicit capability tags, - native Signal Layer implementations, - placement by capability tags, - browser and CLI access through the same application interfaces, - explicit documentation of what happens after Node loss, without implying continuity. ## What the roadmap adds Partition Tolerance replicates authority and uses fencing to allow one active serving copy. Durability replicates Cell data and lets a Consistent product Cell resume after Node loss. ## Good fits - connected devices and appliances, - gateways and controllers, - building and energy products, - specialized equipment, - product families spanning several hardware targets. ## See also - [Application Domains](../03_target-groups.md) - the other entry points Myrmic supports - [Understanding Myrmic](../02_why-myrmic/02_understanding-myrmic.md) - the swarm and node model behind this approach - [Signal Layer](../02_why-myrmic/04_connecting-physical-systems.md) - how Cells relate to native drivers and hardware I/O --- sidebar_label: Platform Engineering --- # Give developers one stateful application primitive Platform teams often standardize deployment while each application team still invents its own combination of state, messaging, scheduling, placement, and recovery. ## The Myrmic approach Offer the Cell as the shared primitive for stateful applications. Application teams define state, handlers, Commands, Events, timers, Application boundaries, and capability tags. The platform team operates Nodes, data roles, orchestration, gateways, and policy. ## What the preview demonstrates - one stateful programming model, - stable logical addressing, - mailbox-based messaging, - placement by capability tags, - OS-based and MCU-based Nodes in one swarm, - explicit documentation of what happens after Node loss, - an inspectable open-source stack. ## What the roadmap adds - per-Cell recovery models, - replicated authority, - fencing that permits one active serving copy, - replicated Cell State and Mailboxes, - Cell resume after Node loss, - request identity and durable timers. ## Start an evaluation 1. Choose one repeated stateful pattern. 2. Implement it as a Cell. 3. Define its capability tags. 4. Reproduce the documented behaviour for Messages, State, and Node loss. 5. Decide whether Partition Tolerance, Durability, and Secure Swarm close a real platform gap. > **Standardize the application model, not only the deployment pipeline.** ## See also - [Application Domains](../03_target-groups.md) - the other entry points Myrmic supports - [Concepts](../06_concepts.md) - the vocabulary every other page assumes - [Guarantees](../08_guarantees.md) - what the current release promises, and what it doesn't yet --- sidebar_label: Real-Time Applications --- # Give every room, session, and match a durable home Rooms, sessions, and matches outlive the processes serving their current connections. Teams often split identity and state across WebSocket servers, caches, databases, brokers, and recovery jobs. ## The Myrmic approach Model each long-lived real-time concept as a Cell. ```text browser clients ↓ WebSocket gateway ↓ room or match Cell state · Commands · Events · timers ``` The Cell owns membership, history, rules, and behaviour. Browser clients use the same Commands and Events as other Cells. ## What the preview demonstrates - stable Cell identity, - mailbox-based messaging, - one ordered stream of Handler invocations within each Cell, - dynamic Cell creation, - WebSocket access and packaged web assets, - Cell State held as one copy by default, - explicit behaviour after Node loss rather than hidden recovery assumptions. The Chatty example demonstrates sessions, history, presence, and message fan-out without any Signal Layer dependency. ## What the roadmap adds Partition Tolerance uses fencing to allow one active serving role and adds acknowledged lifecycle operations. Durability replicates State and Mailboxes across Nodes, so Consistent rooms or matches can survive Node loss. Durability also adds request identity and durable timers. > **Connections are temporary. The room is not.** ## See also - [Application Domains](../03_target-groups.md) - the other entry points Myrmic supports - [Modelling Applications](../02_why-myrmic/03_modelling-applications.md) - how to think in Cells when designing an application - [Guarantees](../08_guarantees.md) - what the current release promises, and what it doesn't yet --- sidebar_label: Workflows and Agents --- # Give long-running work a place to live Workflows and agents need state that survives individual requests and workers. Today that state is often spread across queues, scheduler entries, database rows, callback correlation, and retry code. ## The Myrmic approach Represent each workflow or agent as a Cell. The Cell keeps context, receives Commands and Events, schedules continuation, and can create child Cells for delegated work. Results return as callbacks into the caller's mailbox. ## What the preview demonstrates - stable identity and Cell State, - one ordered stream of work, - callbacks and process-local timers, - placement by capability tags, - dynamic Cell creation and optional lifetime leases, - explicit timeout and retry semantics. ## What the roadmap adds - Partition Tolerance introduces the Consistent recovery model and fencing for one active serving copy. - Durability adds replicated State, durable timers, request identity, deduplication, and Cell resume after Node loss. ## Boundary Myrmic does not provide an AI model or inference engine. It provides state, messaging, placement, and lifecycle around an agent. ## See also - [Application Domains](../03_target-groups.md) - the other entry points Myrmic supports - [Messages and Mailboxes](../06_concepts/03_messages-and-mailboxes.md) - how Commands and Events reach a Cell - [Roadmap](../09_roadmap.md) - what future stages are intended to add # Tutorials Tutorials are hands-on walkthroughs that teach Myrmic by doing. Unlike guides - which explain individual concepts - tutorials take you through a complete task from start to finish, leaving you with a working result and a deeper understanding of how things fit together. - [Smart Greenhouse](./04_tutorials/01_smart-greenhouse.md) - Build a five-cell application on one computer - mock sensor, pump, grow bed, agent, and dashboard - with a live web frontend served by the Myrmic gateway. - [Resilience](./04_tutorials/02_resilience.md) - Run the greenhouse's sensor and grow-bed across three runtimes, kill nodes, and learn how placement tags, restart policies and `myrmic replicate` decide whether a cell - and its state - comes back. - [First Steps on an ESP32](./04_tutorials/03_first-steps-embedded.md) - Flash Myrmic firmware to a bare ESP32-C6 so it joins your swarm, then deploy the counter cell onto the board and drive it from the CLI - no Signal Layer, no wiring. - [First Steps with the Signal Layer](./04_tutorials/04_first-steps-signal-layer.md) - Build a pipeline that produces a value and a cell that reads it, then move the same cell from a Linux machine onto an ESP32-C6 with one command. - [Authoring Signal Layer modules](./04_tutorials/05_authoring-signal-layer-modules.md) - Write your own Signal Layer step and driver as standalone crates, test them at your desk, and use them in a pipeline without touching the Myrmic tree. - [Scaling Your Application](./04_tutorials/06_scaling.md) - Let root cells spawn grow-beds and sensors at runtime from a dashboard button, pair them by name, and see who brings a lost child back when a node dies. - [Observability](./04_tutorials/07_observability.md) - Set up and use Myrmic's observability stack: logs, traces, and metrics. # Authoring Signal Layer modules The Signal Layer ships drivers and steps for common parts, but sooner or later you will want one it does not have: a sensor nobody has written a driver for, or a calculation no shipped step does. This tutorial writes both, a step and a driver, and uses them in a pipeline without touching the Myrmic repository. `myrmic signal-layer` scaffolds each module as a small standalone crate, already compiling and with its tests passing, so the work is filling in the parts only you know: the arithmetic for a step, the register map for a driver. ## What you build You create a small module registry of your own, a directory holding `drivers/` and `steps/`, and put two modules in it: - a **step** that transforms a value on its way through a pipeline, and - a **driver** for an I2C sensor. Then you point a Linux pipeline at that registry, wire both modules in, and run it. The step runs live over the synthetic `sim-source` from [First Steps](04_first-steps-signal-layer.md); the driver is written and unit-tested here, and reading it live is a matter of having the sensor. This is the path for authoring a module locally, before it is ready to move into the Myrmic tree or into a shared module library. Nothing here changes your checkout. ## What you need - The `myrmic` CLI and the Rust toolchain, per [Installation](../01_quickstart/01_installation.md). - A clone of the Myrmic repository, so the scaffolds can resolve the SDK. Clone it and point `myrmic signal-layer` there once: ```bash git clone https://github.com/peeriot/myrmic.git ~/myrmic export PEERIOT_MYRMIC_SDK=~/myrmic # the path to your clone ``` Or pass `--sdk ~/myrmic` to `myrmic signal-layer step` and `myrmic signal-layer new`; a driver crate depends on nothing from the SDK, so `driver` has no such flag. The flag wins if you set both. - A Linux machine. Everything here builds and runs with no attached hardware: the step is pure arithmetic, the driver is tested against a mock bus, and the pipeline reads the synthetic `sim-source`. You do not need to have done [First Steps](04_first-steps-signal-layer.md) first, but it is the gentler introduction to pipelines, taps and `sim-source`, and this tutorial reuses all three. ## The parts 1. [A step](05_authoring-signal-layer-modules/01_a-step.md): scaffold a processing step, learn the `ProcessingStep` contract, and test it. 2. [A driver](05_authoring-signal-layer-modules/02_a-driver.md): scaffold an I2C sensor driver, fill in its register map, and test it against a mock bus. 3. [Using them](05_authoring-signal-layer-modules/03_using-them.md): point a pipeline at your registry, wire both modules in, and build and run it. The [Write your own driver](../05_guides/11_signal-layer/07_write-your-own-driver.md) and [Write your own step](../05_guides/11_signal-layer/08_write-your-own-step.md) guides are the reference for everything this tutorial does by example. # Part 2: A driver A driver knows one device: how to wake it, and how to ask it for a reading. Everything else in the Signal Layer is generic, so supporting a new sensor means writing a driver and nothing else. This part writes one for an I2C temperature sensor. ## Scaffold it A driver is tied to a bus, and you name it explicitly: `--bus i2c` or `--bus spi`. There is no default, because the two are different code. ```bash myrmic signal-layer driver thermo --bus i2c --registry-dir ~/sl-modules ``` This lands `thermo` next to the deadband step, under `drivers/` this time: ```text ~/sl-modules/ drivers/thermo/{Cargo.toml, descriptor.yaml, src/lib.rs} steps/deadband/... ``` As before, the scaffold compiles and its tests pass out of the box: ```bash cd ~/sl-modules/drivers/thermo cargo test ``` ## The rule that shapes a driver A driver never knows where it is: not which pin, not which board, not whether it runs on an ESP32 or a Linux box. It is handed the bus on every call and gets on with it. That is enforced by the shape of the code: the driver is generic over the bus using the `embedded-hal` traits, so it physically cannot reach for a specific pin or chip. The same crate then works on every platform with no conditionals. ## What the scaffold gives you The generated `src/lib.rs` is a complete, illustrative I2C driver you edit into your own. Its shape: - A **`ThermoConfig`**: one field per `config_schema` entry. A `scope: hardware` field (like an I2C address) is a fact about the wiring and comes from the board file; a `scope: application` field is a knob the pipeline sets. - A **`ThermoReadings`**: one field per `outputs` entry in the descriptor, named and typed to match. Codegen wires `readings.temperature` to whatever the pipeline calls it, so the names must line up. - A **`ThermoError`**: a `Bus(E)` variant that carries the bus error, plus a domain variant. The `From` impl lets `?` lift a bus error. - **`new` / `init` / `sample`**: `new` is infallible and touches no bus; `init` verifies the sensor answers with the identity it should and configures it; `sample` reads one measurement. `init` is idempotent, because the runtime re-runs it to recover a sensor after a bus glitch. ## Fill it in Replace `src/lib.rs` with the sensor you are actually writing. This one reads a signed 16-bit temperature in units of 1/256 C from one register, and checks a `WHO_AM_I` register during `init` so a mis-wired bus fails with a clear error instead of nonsense readings: ```rust #![cfg_attr(not(test), no_std)] //! thermo: a minimal, illustrative I2C temperature sensor driver. use embedded_hal_async::i2c::I2c; const REG_WHO_AM_I: u8 = 0x0F; const WHO_AM_I: u8 = 0xBA; const REG_CTRL: u8 = 0x20; const CTRL_ENABLE: u8 = 0x01; const REG_TEMP: u8 = 0x00; pub struct ThermoConfig { pub i2c_addr: u8, } impl Default for ThermoConfig { fn default() -> Self { Self { i2c_addr: 0x48 } } } #[non_exhaustive] pub struct ThermoReadings { pub temperature: f32, } #[non_exhaustive] #[derive(Debug)] pub enum ThermoError { Bus(E), InvalidId(u8), } impl From for ThermoError { fn from(err: E) -> Self { Self::Bus(err) } } pub struct Thermo { cfg: ThermoConfig, } impl Thermo { #[must_use] pub fn new(cfg: &ThermoConfig) -> Self { Self { cfg: ThermoConfig { i2c_addr: cfg.i2c_addr } } } pub async fn init(&mut self, bus: &mut I) -> Result<(), ThermoError> { let mut id = [0u8; 1]; bus.write_read(self.cfg.i2c_addr, &[REG_WHO_AM_I], &mut id).await?; if id[0] != WHO_AM_I { return Err(ThermoError::InvalidId(id[0])); } bus.write(self.cfg.i2c_addr, &[REG_CTRL, CTRL_ENABLE]).await?; Ok(()) } pub async fn sample(&mut self, bus: &mut I) -> Result> { let mut raw = [0u8; 2]; bus.write_read(self.cfg.i2c_addr, &[REG_TEMP], &mut raw).await?; let temperature = f32::from(i16::from_be_bytes(raw)) / 256.0; Ok(ThermoReadings { temperature }) } } #[cfg(test)] mod tests { use super::*; use embedded_hal_mock::eh1::i2c::{Mock, Transaction as T}; use futures::executor::block_on; const ADDR: u8 = 0x48; #[test] fn init_and_sample() { // 25.0 C is 25.0 * 256 = 6400 = 0x1900. let mut mock = Mock::new(&[ T::write_read(ADDR, vec![REG_WHO_AM_I], vec![WHO_AM_I]), T::write(ADDR, vec![REG_CTRL, CTRL_ENABLE]), T::write_read(ADDR, vec![REG_TEMP], vec![0x19, 0x00]), ]); let mut dev = Thermo::new(&ThermoConfig::default()); block_on(async { dev.init(&mut mock).await.unwrap(); let reading = dev.sample(&mut mock).await.unwrap(); assert_eq!(reading.temperature, 25.0); }); mock.done(); } #[test] fn wrong_chip_id_returns_error() { let mut mock = Mock::new(&[T::write_read(ADDR, vec![REG_WHO_AM_I], vec![0x00])]); let mut dev = Thermo::new(&ThermoConfig::default()); block_on(async { let err = dev.init(&mut mock).await.unwrap_err(); assert!(matches!(err, ThermoError::InvalidId(0x00))); }); mock.done(); } } ``` The tests are the ones that catch what matters. You supply the raw register bytes, so you can drive the decoding path with numbers you control: a raw sample in, an assertion about the temperature out, and a check that a wrong identity is reported as an error rather than decoded as a reading. Whether the wiring is right is a question for the bench; whether your maths is right is one you answer here. ## Match the descriptor Update `descriptor.yaml` to the one output and the one hardware knob this sensor has: ```yaml id: thermo category: sensor-drivers description: > Illustrative I2C temperature sensor: one temperature reading in degrees C. requires: buses: - transport: i2c outputs: - name: temperature type: f32 unit: "°C" config_schema: i2c_addr: scope: hardware rust_type: u8 default: 0x48 description: "I2C address" sample_interval_ms: scope: application rust_type: u64 default: 1000 description: Polling interval in milliseconds ``` `sample_interval_ms` gets no `ThermoConfig` field: it drives the generated sampling loop, which ticks at that rate, and is never handed to the driver. Every other `config_schema` entry needs a matching field. ```bash cargo test ``` An SPI sensor is the same shape with `--bus spi`: the driver is generic over the `SpiDevice` trait instead, and the descriptor declares `transport: spi`. [Next](03_using-them.md), you point a pipeline at your registry and run both modules. # Part 1: A step A step is a transform: a value goes in, and either a value comes out or nothing does. It knows a calculation, never a device, and it keeps only its own state. That makes it the easiest module to write, so it is where we start. ## Scaffold it Pick a directory to keep your modules in; it does not have to exist yet. The `step` command creates it and places a step under `steps/` inside it, which is the layout a pipeline will later read: ```bash myrmic signal-layer step deadband --registry-dir ~/sl-modules ``` ```text INFO Creating Signal Layer step 'deadband' in ~/sl-modules/steps/deadband INFO Add `deadband = { path = "~/sl-modules/steps/deadband" }` to a pipeline's dependencies and point its build.rs at `~/sl-modules` to build with it. ``` That second line is Part 3; ignore it for now. You have a standalone crate: ```text ~/sl-modules/steps/deadband/ Cargo.toml descriptor.yaml src/lib.rs ``` It already compiles and its test passes. Prove it before you touch anything: ```bash cd ~/sl-modules/steps/deadband cargo test ``` ## What the scaffold gives you `src/lib.rs` opens with `#![cfg_attr(not(test), no_std)]`: a step runs on a microcontroller too, so it cannot use the standard library. Below that is the shape every step has. - A **`DeadbandConfig`**: the knobs a pipeline sets, one field per `config_schema` entry in `descriptor.yaml`. - A **`DeadbandState`**: the step's own memory. The naming is a convention, the config is what the pipeline declares and the `State` is what runs; codegen instantiates `DeadbandState` (the `State` suffix is how it finds it). - An **`impl ProcessingStep for DeadbandState`**: the whole interface. ```rust pub trait ProcessingStep { type Input; type Output; fn step(&mut self, input: Self::Input) -> Option; } ``` The `Option` is the important part. Returning `None` is not an error; it means "no value this time", and whatever the step feeds simply is not updated. A step that returns `None` until it has something worth emitting is doing exactly what it should. ## Make it your own The scaffold ships a rolling-average example. Replace `src/lib.rs` with a *deadband*: a step that passes a value through only when it has moved by at least `delta` since the last one it emitted, and stays quiet otherwise. It keeps one thing in state (the last value it emitted) and uses `None` for every sample that has not moved far enough. ```rust #![cfg_attr(not(test), no_std)] //! deadband step: passes a value through only when it has moved by at least //! `delta` since the last one it emitted, and stays quiet otherwise. use signal_layer_core::ProcessingStep; #[derive(Clone, Copy)] pub struct DeadbandConfig { pub delta: f32, } impl Default for DeadbandConfig { fn default() -> Self { Self { delta: 1.0 } } } pub struct DeadbandState { delta: f32, last: Option, } impl DeadbandState { #[must_use] pub fn new(cfg: DeadbandConfig) -> Self { Self { delta: cfg.delta, last: None } } } impl ProcessingStep for DeadbandState { type Input = f32; type Output = f32; fn step(&mut self, input: f32) -> Option { let moved = match self.last { Some(last) => (input - last).abs() >= self.delta, None => true, }; if moved { self.last = Some(input); Some(input) } else { None } } } #[cfg(test)] mod tests { use super::*; #[test] fn emits_only_on_a_move_past_the_deadband() { let mut step = DeadbandState::new(DeadbandConfig { delta: 2.0 }); assert_eq!(step.step(10.0), Some(10.0)); // the first sample always emits assert_eq!(step.step(11.0), None); // within the deadband, stays quiet assert_eq!(step.step(12.5), Some(12.5)); // moved by >= 2.0 assert_eq!(step.step(12.6), None); } } ``` The test is the point. A step's behaviour is a *sequence*, and the sequence is what a description promises: quiet until the value moves, one emission on the move, quiet again. You pin that down at your desk, with no pipeline and no hardware. ## Match the descriptor Codegen never reads your Rust; it reads `descriptor.yaml`. The generated one describes the rolling-average example, so update it to match the deadband: one `f32` input, one `f32` output, and the `delta` knob. Every `config_schema` field maps to a `DeadbandConfig` field of the same name and type. ```yaml id: deadband category: processing-steps description: > Passes a value through only when it has moved by at least `delta` since the last one it emitted; stays quiet (emits nothing) otherwise. inputs: - name: value type: f32 outputs: - name: result type: f32 config_schema: delta: scope: application rust_type: f32 default: 1.0 description: Minimum change from the last emitted value before emitting again ``` Run the test once more to confirm the edit compiles: ```bash cargo test ``` That is a complete step. [Next](02_a-driver.md) you write a driver, which is more involved because it talks to real hardware. If you only needed a step, skip to [Using them](03_using-them.md). # Part 3: Using them You have two modules in `~/sl-modules`: the `deadband` step and the `thermo` driver. Now you point a pipeline at that directory so its build picks them up, alongside the modules that ship with myrmic. Nothing in your Myrmic checkout changes; the registry stays entirely your own. ## Scaffold a pipeline beside the registry Create the pipeline next to `~/sl-modules`, so a short relative path reaches it: ```bash cd ~ myrmic signal-layer new tut-pipeline ``` That is the standalone Linux pipeline from [First Steps](../04_first-steps-signal-layer.md): a `board.yml`, a `pipeline.yml`, and a crate that builds them at compile time. Its `board.yml` already declares a `sim-source` device, which is all the step needs. ## Point the build at your registry The generated `build.rs` reads `board.yml` and `pipeline.yml` and, optionally, a directory of your own modules. Give it your registry (its third argument is a path relative to the pipeline crate): ```rust // tut-pipeline/build.rs linux_codegen::build_pipeline("board.yml", "pipeline.yml", Some("../sl-modules")); ``` Then declare the two crates you will use as ordinary path dependencies, so they end up in the binary. A driver crate is named `-driver`; a step crate is named its bare `id`: ```toml # tut-pipeline/Cargo.toml, under [dependencies] deadband = { path = "../sl-modules/steps/deadband" } thermo-driver = { path = "../sl-modules/drivers/thermo" } ``` That is the whole of the local-dir workflow: a registry directory of modules, named on the build, and each crate a dependency. A firmware pipeline is identical, with `.include("../sl-modules")` on its `esp_firmware_build::pipeline()` builder instead of the third argument. ## Wire in the step and run it Add the step to `pipeline.yml`. It runs over the synthetic `sim` source, so this runs with no hardware. A step is named on the pipeline by its descriptor `id` (`deadband`), and its output tap reads the step by the `id` you give the step in the pipeline: ```yaml pipeline: id: tut-pipeline sources: - id: sim device: sim config: sample_interval_ms: 500 start: 0.0 step: 10.0 max: 100.0 steps: - id: filtered op: deadband input: sim.value config: delta: 5.0 taps: - name: filtered kind: retained type: f32 source: filtered ``` Build it with `myrmic build`, the same command as for a cell or firmware, and run the binary it reports: ```bash cd ~/tut-pipeline myrmic build export XDG_RUNTIME_DIR=/run/user/$(id -u) # only if your shell has none ./target/release/tut-pipeline ``` ```text Pipeline `tut-pipeline` running. Press Ctrl-C to stop. [INFO sim_source_driver] [sim-source] init OK (synthetic) ``` Your `deadband` step is now compiled into a running pipeline, filtering the ramp `sim` produces and serving the result as the `filtered` tap. A cell reads it exactly as it read the taps in First Steps. ## Wire in the driver The driver is the same, with one honest caveat: reading it live needs the sensor. Declare it in `board.yml` on the I2C bus, at the address your wiring uses: ```yaml # tut-pipeline/board.yml, under devices: - id: thermo driver: thermo bus: i2c0 hardware: i2c_addr: 0x48 ``` Add a source that reads it, and a tap for the temperature, to `pipeline.yml`: ```yaml sources: # ... the sim source above, plus: - id: thermo device: thermo config: sample_interval_ms: 1000 taps: # ... the filtered tap above, plus: - name: temperature kind: retained type: f32 source: thermo.temperature ``` `myrmic build` again. It compiles: codegen found `thermo` in your registry, checked the pipeline against its descriptor, and wired `thermo.temperature` to the tap. Running it now opens `/dev/i2c-1` and talks to the sensor, so it needs the real part on the bus; on a Raspberry Pi with the sensor wired, this is a live temperature tap. Without the sensor, leave the `thermo` source out and the pipeline runs on `sim` alone, as above. ## Where this goes next You wrote a step and a driver, tested both at your desk, and ran them from a pipeline without touching the Myrmic tree. When a module has earned its place, it moves into `signal-modules/` in the repo (or a shared module library) and becomes available to everyone by name, with no registry path. The [Write your own driver](../../05_guides/11_signal-layer/07_write-your-own-driver.md) and [Write your own step](../../05_guides/11_signal-layer/08_write-your-own-step.md) guides cover that step and the full module reference. # First Steps on an ESP32 In this tutorial you take a blank ESP32-C6, flash it with Myrmic runtime firmware so it joins your swarm as a node, and then deploy a *cell* onto it - the counter cell the CLI scaffolds - and drive it from your keyboard. No sensors, no wiring: the shortest path from a bare board to your own code running on the microcontroller. Along the way you learn what firmware is and how it differs from a cell, how a board joins the swarm, how a cell is ahead-of-time compiled and placed onto a device, and how to send it commands and read its logs. ## What you need - The `myrmic` CLI and the Rust toolchain it builds cells with, per [Installation](../01_quickstart/01_installation.md). - The embedded toolchain: the `riscv32imac-unknown-none-elf` Rust target (auto-installed on the first firmware build) and `wamrc` 2.4.4 on your `PATH`, the ahead-of-time compiler cells are compiled with for the device. See [Installation (Embedded)](../01_quickstart/02_installation-embedded.md) for that one-time setup - this tutorial needs nothing beyond it. - An ESP32-C6 devkit and a machine to flash it from. - WiFi credentials for the network that machine is on. The board discovers the swarm by multicast; a fallback for networks that block it is in Step 2. Nothing here needs a clone of the Myrmic repository: the scaffolded cell and firmware pin their dependencies to git revisions and fetch them on the first build. You will use two terminals: | Terminal | Runs | |---|---| | Terminal 1 | your working shell: start the runtime, scaffold, deploy, send | | Terminal 2 | `myrmic flash --monitor` - the board's live serial output | --- ## Step 1 - Start a runtime The CLI talks to the swarm through a *runtime*, a Myrmic process. On one machine that single runtime *is* your swarm, and it is what the board will join. In Terminal 1, start one in the background with a throwaway in-memory database: ```bash myrmic runtimes start -d -n dev --tmp ``` Expected output: ```text INFO runtime "dev" pid file: /run/user/1000/myrmic/dev.pid INFO Starting runtime "dev"(ec1bcf44056d4d338e254167b8c20ba9) ``` Leave it running. Everything else in Terminal 1 - `deploy`, `network`, `send` - reaches the swarm through it. --- ## Step 2 - Scaffold and flash the firmware *Firmware* is a native RISC-V binary: a node that runs on the bare-metal chip and joins the swarm. Unlike a cell it is not WebAssembly, and it is *flashed*, never deployed. `myrmic new --firmware` scaffolds a firmware crate; `=esp32c6` selects the chip. On Terminal 2: ```bash myrmic new --firmware=esp32c6 ~/esp-tutorial/my-node ``` Expected output: ```text INFO Creating firmware 'my-node' for esp32c6 ``` Now build and flash it. The WiFi credentials are baked into the firmware at compile time, so set them in the environment first, then flash in **Terminal 2** with `--monitor` to stream the serial output afterwards: ```bash cd ~/esp-tutorial/my-node export WIFI_SSID="your-network" WIFI_PASS="your-password" myrmic flash --monitor ``` The first build is the slow one: it auto-installs the embedded toolchain, fetches the ESP SDK crates, and compiles the WAMR runtime from source. `myrmic flash` then connects to the board, writes the image sized to the device's flash, and resets into it: ```text Chip type: esp32c6 (revision v0.2) Features: WiFi 6, BT 5 MAC address: 10:51:db:01:fa:3c INFO Building esp32c6 firmware: .../my-node/Cargo.toml Finished `release` profile [optimized] target(s) in 41s INFO Flashing .../my-node... App/part. size: 2,274,192/3,080,192 bytes, 73.83% INFO Flashed; the board is booting ``` The board finds the runtime the same way the CLI does: by scouting the local network. On an ordinary flat network (board and computer on one router) that simply works. Expected in the serial output, in this order: ```text INFO - Wifi connected to ConnectedInfo { ssid: "your-network", ... } INFO - Got IP: 192.168.1.60 INFO - Scouting for Zenoh nodes... INFO - Using Zenoh node at 192.168.1.68:46747 INFO - clock synced to swarm time (1789666899s since epoch) INFO - Registering exec runtime with info: ExecRuntimeInfo { id: RuntimeId(796d3cfa01db5110), name: Some("ESP32-C6"), capabilities: ExecutionCapabilities { tags: [CapabilityTag("esp32c6"), CapabilityTag("esp32"), CapabilityTag("riscv32imac"), CapabilityTag("embedded"), CapabilityTag("wifi-myrmic"), CapabilityTag("gpio"), ...] } } ``` >If your network blocks multicast, give the firmware the runtime's address at build time instead by setting `TCP_DIRECT_ADDR` to the computer's address and the runtime's listen port before flashing. >```bash > export WIFI_SSID="your-network" WIFI_PASS="your-password" TCP_DIRECT_ADDR="192.168.1.68:46747" > myrmic flash --monitor >``` Read those last three lines as the board joining: it found the runtime your computer anchors, synced to swarm time, and registered itself as a place to run cells. Leave the monitor streaming in Terminal 2. --- ## Step 3 - See the board in the swarm Back in Terminal 1, list the swarm nodes: ```bash myrmic network ``` Expected output - two nodes now, the board and your `dev` runtime: ```text Discovered 2 node(s) # name kind id tags 0 ESP32-C6 esp32c6 [7]96d3cfa esp32c6, esp32, riscv32imac, embedded, wifi-myrmic, gpio, @796d3cfa01db5110 1 dev linux [e]c1bcf44 @ec1bcf44056d4d338e254167b8c20ba9, linux ``` The board joined as `ESP32-C6`, carrying platform *tags* - facts about what the node is, not preferences: `esp32c6`, `riscv32imac`, `embedded`, and so on. The `esp32c6` tag is how you will pin a cell to the board in Step 5. The same tags show under: ```bash myrmic tags ``` ```text NODE ID TAGS ESP32-C6 [7]96d3cfa esp32c6, esp32, riscv32imac, embedded, wifi-myrmic, gpio, @796d3cfa01db5110 dev [e]c1bcf44 @ec1bcf44056d4d338e254167b8c20ba9, linux ``` --- ## Step 4 - Scaffold the cell A *cell* is a Rust crate compiled to WebAssembly and run on a runtime. Scaffold the canonical one - the counter: ```bash myrmic new ~/esp-tutorial/counter ``` Expected output: ```text INFO Creating 'counter' ``` You do not write a line of Rust in this tutorial. The scaffold already defines commands over a durable count kept in the cell's private state - `increment`, `decrement`, and `count`, which logs the current value: ```rust #[myrmic_sdk::cmd] fn increment(md: Metadata) -> myrmic_sdk::Result { let count = STATE.upsert_with(|count| { *count = *count + 1; })?; let _ = myrmic_sdk::info!("Incremented count to {} (sender={:?})", count, md.sender).ok(); Ok(()) } ``` That is the same cell that runs on a Linux runtime. Nothing about it is embedded-specific; the target is chosen at deploy time, not written into the code. --- ## Step 5 - Deploy the cell onto the board Deploy the cell for the device platform `riscv32imac`. That rebuilds it and ahead-of-time compiles it with `wamrc`. Your Linux runtime is in the swarm too and could host the cell, so `--tag esp32c6` pins the placement to the board. One flag matters here: `--timeout`. A cell's first deployment to a board transfers the compiled module over the network and writes it into the device's flash, which takes longer than the CLI's default wait. Give it room - a redeploy of the *same* module skips the transfer and returns at once, so the longer timeout only ever costs you on the first deploy or a slow network: ```bash myrmic deploy ~/esp-tutorial/counter --platform riscv32imac --tag esp32c6 --timeout 90s ``` Expected output - `wamrc` compiles the module, then the runtime confirms placement on the board: ```text Compile success, file .../counter/target/counter.aot was generated. INFO deploying cell (srn = counter, sri = 5d883103-6382-5d16-9a0c-d70fd0565cb6) INFO deployed cell (srn = counter, sri = 5d883103-6382-5d16-9a0c-d70fd0565cb6, runtime = 796d3cfa01db5110) ``` The serial monitor in Terminal 2 shows the board's side - it receives the module, loads it into its WAMR runtime, and registers the cell: ```text INFO - [db] Requesting WASM metadata... INFO - WASM module found. Loading into WAMR... INFO - WAMR engine initialized INFO - WASM Module instantiated INFO - Registering the Cell ``` See where the cell landed: ```bash myrmic cells status ``` ```text cell sri kind runtime age policy class srn ──── counter ───────────────────────────────────────────────────────────────────────── counter 5d883103-6382-5d16-9a0c-d70fd0565cb6 wasm [7]96d3cfa 9s never counter counter ``` The `runtime` column is the proof: `[7]96d3cfa` is the board's id, not `dev`. The cell is running on the microcontroller. --- ## Step 6 - Drive the cell Send it a command. `increment` takes no reply, so the CLI just prints a trace id and confirms the runtime accepted it: ```bash myrmic send counter increment myrmic send counter increment ``` ```text INFO trace ID = 5675f09fddf7e9aa19ac2efae3f3a296 INFO successfully sent command ``` Watch the serial monitor in Terminal 2 react to each one. The sender is nil because the command came from the CLI, not another cell: ```text INFO - module log: Incremented count to 1 (sender=Sri(00000000-0000-0000-0000-000000000000)) INFO - module log: Incremented count to 2 (sender=Sri(00000000-0000-0000-0000-000000000000)) ``` Ask the cell for its count. Sent from the CLI there is no caller to answer, so it logs the value rather than returning it: ```bash myrmic send counter count ``` ```text INFO - module log: Count is 2 (no caller to answer) ``` The count is state the cell persisted on the board: send `increment` again, or `decrement`, and the value moves from where it left off. You have deployed your own cell to an ESP32 and driven it from your keyboard, without wiring a single pin. --- ## What Have You Learned - *Firmware* is a native binary flashed to the chip; a *cell* is WebAssembly deployed onto a runtime. The board runs firmware and hosts cells. - The CLI reaches the swarm through a runtime, and a flashed board joins that swarm over WiFi as a node carrying an `esp32c6` tag. - A cell is written once and targeted at deploy time: `--platform riscv32imac` ahead-of-time compiles it with `wamrc`, and `--tag esp32c6` places it on the board rather than the Linux runtime. - A first deployment to a board transfers the module into flash, so it needs a longer `--timeout`; redeploying the same module skips the transfer. - `myrmic send` drives a deployed cell, and `myrmic flash --monitor` shows the board's own logs as it handles each command. ## Next Step - [First Steps with the Signal Layer](./04_first-steps-signal-layer.md) - give the board sensors and actuators, and read them from a cell over named taps and outlets. - [`myrmic deploy`](../10_reference/02_myrmic-cli/05_deploy.md) and [`myrmic new`](../10_reference/02_myrmic-cli/01_new.md) - the full command reference. # First Steps with the Signal Layer In this tutorial you build the smallest complete Signal Layer system: a pipeline that produces a value, a cell that reads it, and then the payoff — moving that cell from a Linux machine onto an ESP32 with one command, without changing a line of it. You write two small YAML files and about thirty lines of Rust. `myrmic signal-layer new` and `myrmic new` scaffold the rest, and everything else is generated at build time. ![The Signal Layer runs drivers and steps as native code on the target machine; a cell in the WebAssembly runtime reads sensor values through a tap and drives actuators through an outlet. This tutorial builds the tap (read) side.](../../images/signal-layer-tap-outlet.png) ## What you build A simulated sensor publishes a climbing value twice a second. A `moving-average` step smooths it. Both numbers are offered as *taps*, named values a cell can read. Your cell reads them every second and logs them. The point of the exercise is what does *not* change along the way. The pipeline file and the cell run on a Linux machine first, and on an ESP32-C6 after. Only the *board file*, the description of the physical machine, differs between the two. ## What you need To use the Signal Layer you must clone the Myrmic repository. The scaffolding commands (`myrmic signal-layer new` for a pipeline, `myrmic new` for a cell) create the skeleton of every project in this tutorial, and they have to know where your clone is. Tell them once, with an environment variable: ```bash export PEERIOT_MYRMIC_SDK=~/myrmic # the path to your clone ``` Set this in the shell you run the tutorial from, before the first scaffold. It is read only when a project is created, so setting it afterwards will not fix a project you already created. Delete that project and create it again. The other option is to add `--sdk ~/myrmic` to every scaffolding command. If you set both, the flag wins. **Part 1 and 2, the Linux half:** - A Linux machine. The simulated sensor is synthetic and never touches the I²C bus, so this tutorial needs no I²C hardware and no `/dev/i2c-*` node. (A Raspberry Pi works too — it is where the real-sensor follow-ups in *What's next* would run.) - The `myrmic` CLI and the Rust toolchain it builds cells with, per [Installation](../01_quickstart/01_installation.md). The *Install from source* path also leaves you the checkout referenced above (called `~/myrmic` here). **Part 3, the ESP32 half:** - An ESP32-C6 devkit and a machine to flash it from (that machine also needs the repo checkout). - The embedded toolchain: the RISC-V Rust target (auto-installed on the first firmware build) and `wamrc`, the ahead-of-time compiler cells are compiled with for the device. See [Installation (Embedded)](../01_quickstart/02_installation-embedded.md) for that one-time setup - this tutorial needs nothing beyond it. - WiFi credentials for the network the Linux machine is on. The device discovers the runtime by multicast; a fallback for networks that block it is in Part 3. ## The parts 1. [The pipeline](04_first-steps-signal-layer/01_the-pipeline.md): describe the machine and the dataflow, scaffold the pipeline, and watch it run. 2. [The cell](04_first-steps-signal-layer/02_the-cell.md): start a runtime, write a thermometer cell, and read the taps. 3. [The transfer](04_first-steps-signal-layer/03_the-transfer.md): put the same pipeline onto an ESP32-C6 and move the same cell onto it. Along the way, the [Signal Layer guide](../05_guides/11_signal-layer.md) explains every concept this tutorial uses; the [reference](../10_reference/04_signal-layer.md) holds the full file formats. # Part 2 - The Cell This is Part 2 of [First Steps with the Signal Layer](../04_first-steps-signal-layer.md). The pipeline from Part 1 is running and serving two taps. Now you start a runtime, write a cell that reads them, and watch the values flow. --- ## Step 1 - Start a runtime A runtime hosts cells. In a **new terminal** (the pipeline stays running in its own), start one and leave it up: ```bash myrmic runtimes start ``` Starting a runtime and confirming it with `myrmic runtimes list` are covered in [the quickstart](../../01_quickstart.md). The part that matters here: the runtime is named `default` and announces itself on the local network, so everything that joins the swarm later — including the ESP32 in Part 3 — finds it by that announcement, with no address to write down. ## Step 2 - Scaffold the cell ```bash myrmic new ~/sl-tutorial/thermometer ``` This builds against the same `PEERIOT_MYRMIC_SDK` checkout from the [prerequisites](../04_first-steps-signal-layer.md) (or pass `--sdk `). The scaffold is a small counter example. Replace `thermometer/src/lib.rs` entirely: ```rust //! Tutorial cell: reads the Signal Layer taps once a second and logs them. #![no_std] use core::time::Duration; use myrmic_sdk::tap::Tap; use myrmic_sdk::{ApiError, Callback, InMemory, Metadata, Result}; // Resolve each tap once and reuse the handle. `InMemory` is cell-local state // that outlives a single handler call but is never persisted. static VALUE_TAP: InMemory> = InMemory::empty(); static AVG_TAP: InMemory> = InMemory::empty(); #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { myrmic_sdk::info!("thermometer starting").ok(); // The handle is only needed to cancel the timer; the timer itself keeps // running without it. let _timer = myrmic_sdk::interval(Callback::of::(), Duration::from_secs(1)) .fixed_delay() .build() .map_err(|_| "timer failed")?; Ok(()) } /// Read a tap through its cached handle: resolve it the first time, reuse it /// after, and drop it if the pipeline reconnected so the next tick re-resolves. fn read(cache: &InMemory>, name: &str) -> Result> { let mut slot = cache.try_borrow_mut()?; if slot.is_none() { *slot = Tap::resolve(name)?; } let result = match slot.as_ref() { Some(tap) => tap.read_typed::(), None => return Ok(None), // not offered on this node }; match result { Ok(reading) => Ok(reading), Err(ApiError::Unavailable) => { *slot = None; // stale handle after a reconnect; re-resolve next tick Ok(None) } Err(err) => Err(err.into()), } } /// Timer target: read both taps and log what the pipeline is publishing. #[myrmic_sdk::cmd] fn sample(_md: Metadata) -> Result<()> { match (read(&VALUE_TAP, "sim_value")?, read(&AVG_TAP, "sim_avg")?) { (Some((ts, value)), Some((_, avg))) => { myrmic_sdk::info!("t={} value={} avg={}", ts, value, avg).ok(); } _ => { myrmic_sdk::info!("taps not ready yet").ok(); } } Ok(()) } ``` The cell resolves each tap once and reuses the handle. Since `Tap::resolve` is a host call, the `read` helper caches the handle in an `InMemory` slot (cell-local state that lives as long as the cell instance but is never persisted) and only resolves again when the slot is empty. `read` answers with nothing in three cases: the tap is not offered on this node (`resolve` found nothing), it holds no value yet (`read_typed` found nothing), or a pipeline reconnect left the handle stale (`ApiError::Unavailable`), in which case it drops the handle so the next tick resolves a fresh one. The [reading guide](../../05_guides/11_signal-layer/03_read-values.md) explains the kinds of nothing. The scaffold pins `myrmic-sdk` to your checkout, so the cell and the runtime cannot drift apart. ## Step 3 - Deploy `deploy` builds the cell and starts it on the swarm in one step (it defaults to the `linux` platform): ```bash cd ~/sl-tutorial/thermometer myrmic deploy . --name thermometer ``` ```text INFO deploying cell (srn = thermometer, sri = e6f23498-14fb-50d0-8a2a-2baff1b07f22) INFO deployed cell (srn = thermometer, sri = e6f23498-14fb-50d0-8a2a-2baff1b07f22) ``` Then look at where the cell landed: ```bash myrmic cells status ``` ```text cell sri kind runtime age policy class srn thermometer e6f23498-... wasm [c]91d1706 3s never thermometer thermometer ``` The `runtime` column shows the first characters of the runtime's id; right now that is the runtime on this machine. Remember the shape of this row — in Part 3 that column is the proof that the cell moved. ## Step 4 - Watch it read The runtime records what every cell logs in its built-in telemetry database, and the `myrmic telemetry` CLI reads it back, with no log files and no Grafana. The database keeps entries only within a retention window, and none is set by default, so turn one on first: ```bash myrmic telemetry set-db-retention 1h ``` Then read the logs: ```bash myrmic telemetry logs ``` It prints the stored entries oldest-first, colour-coded by severity, each with a timestamp, its trace id, and the line the cell logged. It is a snapshot, not a live stream: run it again to see the lines added since. Retention takes effect from the moment you set it, so what you see is what the cell has logged since, one reading per second: ```text INFO [2026-09-10T14:07:18.500+02:00] | trace_id = 25975cd9... | t=18500 value=40 avg=25 INFO [2026-09-10T14:07:19.500+02:00] | trace_id = 3bcc1f04... | t=19500 value=60 avg=45 INFO [2026-09-10T14:07:20.500+02:00] | trace_id = e566233f... | t=20500 value=80 avg=65 INFO [2026-09-10T14:07:21.500+02:00] | trace_id = d74e864c... | t=21500 value=100 avg=85 INFO [2026-09-10T14:07:22.500+02:00] | trace_id = e0560768... | t=22500 value=10 avg=50 ``` The value climbs (that is the simulated sensor) and the average trails it by the four-sample window (that is the `moving-average` step doing its job). The simulated value is a sawtooth: it wraps from 100 back to 0, and for the next few seconds the average takes the plunge in steps. That dip is the moving average being correct, not broken: `(80 + 100 + 10 + ...) / 4` is simply lower. Your cell is reading live values out of the Signal Layer through the SDK, over the socket from Part 1. One thing to know before you restart anything: a deployed cell does not survive its runtime being deleted. If you stop the runtime and start fresh, deploy the cell again. # Part 1 - The Pipeline This is Part 1 of [First Steps with the Signal Layer](../04_first-steps-signal-layer.md). You describe your machine and your dataflow in two small files, scaffold a pipeline process from them, and watch it come alive. Everything happens on the Linux machine. --- ## Step 1 - Scaffold the project `myrmic signal-layer new` creates a standalone Linux pipeline project — the two YAML files you will edit, and a `build.rs` that generates the pipeline from them at build time. `myrmic sl new` is the short spelling: ```bash myrmic signal-layer new ~/sl-tutorial/first-steps cd ~/sl-tutorial/first-steps ``` ```text INFO Creating Linux pipeline 'first-steps' ``` This builds against the `PEERIOT_MYRMIC_SDK` checkout from the [prerequisites](../04_first-steps-signal-layer.md); add `--sdk ` here if you did not set it. ## Step 2 - The board file `board.yml` describes the physical machine: which chip, which buses, which devices. The scaffold writes one for a Linux host with a synthetic sensor: ```yaml id: first-steps chip: linux # I2C buses by their Linux character device. buses: i2c0: transport: i2c pins: {} freq_khz: 400 dev_path: /dev/i2c-1 gpios: general_purpose: [] devices: - id: sim driver: sim-source bus: i2c0 ``` Three things worth pausing on: - **`pins: {}` is required**, even though pins mean nothing on Linux. The schema is shared with the embedded platforms, where pins are the whole point. - **The bus is named `i2c0` deliberately.** On Linux the name is free. On an ESP32 the bus id names the chip's peripheral, and the C6 has an `I2C0` and no `I2C1`. Keeping `i2c0` here keeps the two board files parallel, and Part 3 will thank you. - **`sim-source` is a real driver that fakes a sensor.** It emits a deterministic climbing value and never touches the bus it is bound to. It still must be bound to one in the file, but nothing opens that bus unless a driver actually transacts on it — and `sim-source` never does, so the pipeline runs with no I²C hardware and no `/dev/i2c-*` node. ## Step 3 - The pipeline file `pipeline.yml` describes the dataflow, and unlike the board file it is portable. The scaffold starts you with one source and one tap; add a `moving-average` step and a second tap so there is something to smooth. The finished file: ```yaml pipeline: id: first-steps sources: - id: sim device: sim config: sample_interval_ms: 500 start: 0.0 step: 10.0 max: 100.0 steps: - id: avg op: moving-average input: sim.value config: window: 4 taps: - name: sim_value kind: retained type: f32 source: sim.value - name: sim_avg kind: retained type: f32 source: avg ``` One source, sampled twice a second, climbing in steps of ten and wrapping at a hundred. One step, averaging the last four samples; a step's output is named by its `id`, so the second tap reads `source: avg`. Two taps: the raw value and the smoothed one. Note that the pipeline references the *device* `sim` from the board file, never the bus; that is what will let it move to another machine unchanged. ## Step 4 - Build and run it Build it with `myrmic build`, the same command you use for a cell or firmware, so there is one build command across the whole tutorial. The generated project's `build.rs` turns `board.yml` + `pipeline.yml` into the pipeline at compile time. ```bash myrmic build ``` ```text INFO Building Linux signal-layer pipeline: ~/sl-tutorial/first-steps Finished `release` profile [optimized] target(s) INFO Pipeline: ~/sl-tutorial/first-steps/target/release/first-steps ``` That leaves a self-contained binary at `target/release/first-steps`. It is an ordinary program; running it needs nothing from Cargo. Start it: ```bash ./target/release/first-steps ``` ```text Pipeline `first-steps` running. Press Ctrl-C to stop. [INFO sim_source_driver] [sim-source] init OK (synthetic) ``` If instead the pipeline panics on start with `no socket path available`, your shell has no `XDG_RUNTIME_DIR`. On a normal desktop login it is set for you and you will not see this; it is often unset over SSH or on a headless box (a Raspberry Pi included). Set it and re-run — and because the runtime in Part 2 reaches the pipeline over the same socket, set it the same in every terminal you use here (or add the line to your shell profile): ```bash export XDG_RUNTIME_DIR=/run/user/$(id -u) ``` The pipeline is now sampling the simulated sensor twice a second, feeding the average, and serving both taps on a Unix socket at `$XDG_RUNTIME_DIR/peeriot-signal-layer.sock`. Nothing is reading them yet. Leave it running; that is Part 2's job. # Part 3 - The Transfer This is Part 3 of [First Steps with the Signal Layer](../04_first-steps-signal-layer.md), and the reason the first two exist. The pipeline and the cell are running on the Linux machine. Now the same pipeline goes onto an ESP32-C6, and the same cell moves onto it, unchanged. Make sure the embedded toolchain is installed - the `riscv32imac-unknown-none-elf` Rust target and `wamrc` 2.4.4 on your `PATH`. See [Installation (Embedded)](../../01_quickstart/02_installation-embedded.md) for the one-time setup. --- ## Step 1 - Scaffold the firmware pipeline On embedded, the pipeline is compiled *into the firmware* rather than run as its own process. `myrmic signal-layer new --firmware` scaffolds that firmware with the pipeline compiled in: ```bash myrmic signal-layer new --firmware=esp32c6 ~/sl-tutorial/first-steps-c6 cd ~/sl-tutorial/first-steps-c6 ``` As in Parts 1 and 2, this uses the `PEERIOT_MYRMIC_SDK` checkout from the [prerequisites](../04_first-steps-signal-layer.md); add `--sdk ` if you did not set it. The scaffold writes a `board.yml` for the C6 — pins instead of a device path: ```yaml id: first-steps-c6 chip: esp32c6 buses: i2c0: transport: i2c pins: scl: 10 sda: 11 freq_khz: 400 gpios: general_purpose: [0, 1, 2, 3, 14, 18, 19, 20, 21, 22, 23, 27] devices: - id: sim driver: sim-source bus: i2c0 ``` Compare it to the Linux `board.yml` from Part 1. The chip changed, and the bus is reached by pins instead of a device path. The device list is identical. On the ESP32 the bus id `i2c0` is not a free name: it selects the chip's `I2C0` peripheral, and naming it `i2c1` fails the build, because the C6 has no such peripheral. The **pipeline is portable** — copy the `pipeline.yml` you finished in Part 1 over the scaffold's, byte for byte: ```bash cp ~/sl-tutorial/first-steps/pipeline.yml ~/sl-tutorial/first-steps-c6/pipeline.yml ``` That the same `pipeline.yml` drives both machines is the whole point. ## Step 2 - Build, flash, and watch it join `myrmic flash` builds the firmware and writes it to the board; the WiFi credentials are baked in at compile time, and `--monitor` streams the serial output afterwards: ```bash export WIFI_SSID="your-network" WIFI_PASS="your-password" myrmic flash ~/sl-tutorial/first-steps-c6 --monitor ``` The device finds the runtime the same way the CLI does: by scouting the local network. On an ordinary flat network (both machines on one router) that simply works. If your network blocks multicast, give the firmware the runtime's address instead — restart the Part 2 runtime with a pinned port and set the address at build time: ```yaml # ~/sl-tutorial/runtime.yml — restart the runtime with: myrmic runtimes start ~/sl-tutorial/runtime.yml zenoh: listen: endpoints: peer: ["tcp/[::]:7447"] ``` ```bash export TCP_DIRECT_ADDR="192.168.178.109:7447" # the Linux machine's address and pinned port myrmic flash ~/sl-tutorial/first-steps-c6 --monitor ``` Expected in the serial output, in this order: ```text INFO - [tap] Registry initialised (3 taps) INFO - [sim-source] init OK (synthetic) INFO - Wifi connected to ConnectedInfo { ssid: "your-network", ... } INFO - clock synced to swarm time (...) INFO - Registering exec runtime with info: ExecRuntimeInfo { ..., name: Some("ESP32-C6"), ... } ``` Read that log as the story it is: the same pipeline came up (two taps plus the health tap), the same simulated sensor started, and then the device joined the swarm your Linux runtime is running and offered itself as a place to run cells. ## Step 3 - Move the cell The cell is still on the Linux runtime, and a cell exists in one place at a time. Deploy it again under the same name, this time for the device platform `riscv32imac` (the ESP32-C6): that rebuilds it and ahead-of-time compiles it with `wamrc`. The Linux runtime is still in the swarm and could host the cell too, so `--tag esp32c6` pins the placement to the C6 and moves the cell onto it: ```bash myrmic deploy ~/sl-tutorial/thermometer --name thermometer --platform riscv32imac --tag esp32c6 ``` Nothing in `thermometer/src/lib.rs` changed. Look at where it landed now: ```bash myrmic cells status ``` ```text cell sri kind runtime age policy class srn thermometer e6f23498-... wasm [7]96d60de 4s never thermometer thermometer ``` The `runtime` column moved from the Part 2 row: it is the ESP32's id now, not the Linux machine's. That column is the proof - the same cell is running on the microcontroller. Watch it read the device's own taps in the serial monitor: ```text INFO - t=6992 value=40 avg=25 INFO - t=7992 value=60 avg=45 ``` The cell you wrote for a Raspberry Pi is now reading a simulated sensor on an ESP32, over the same tap names, having changed not one line. The board file was the only thing that differed between the two machines, and the CLI generated everything else from it. ## What's next - Swap `sim-source` for a real sensor: wire it to the bus, change the `driver:` and set the bus `dev_path` (Linux) or pins (embedded) in `board.yml`. The [Signal Layer guide](../../05_guides/11_signal-layer.md) walks through drivers, steps, actuators, and health. - The full file formats are in the [Signal Layer reference](../../10_reference/04_signal-layer.md); the scaffolding flags are in [`myrmic new`](../../10_reference/02_myrmic-cli/01_new.md). # Observability In this tutorial you learn to see what a Myrmic swarm is doing: which log lines a cell wrote, how a command travelled through the system, and how much work and memory a runtime spends. You do it twice - first with nothing but the Myrmic CLI, then with a Grafana stack that receives the same data over OpenTelemetry. The application under observation is deliberately small: the `counter` cell from the [Quickstart](../01_quickstart.md). It is enough to produce every kind of signal, and it keeps the attention on the tooling rather than on the cells. ## What is Observability and Why Does it Matter? Observability answers the question: *"What is my swarm actually doing right now?"* A running swarm is a distributed system - multiple nodes communicating over a P2P layer. Without observability you are flying blind: when something goes wrong (a cell stalls, a message loop spikes latency, memory climbs) there is no way to diagnose it from the outside. Myrmic exposes three complementary signals: | Signal | What it tells you | Part 1 (CLI) | Part 2 (Grafana) | |--------|-------------------|---|---| | **Logs** | Timestamped text events from every node and every cell | `myrmic telemetry logs` | Loki | | **Traces** | Distributed call trees showing how work flows through cells | `myrmic telemetry traces` | Tempo | | **Metrics** | Numerical counters and gauges (memory, message counts, …) | `myrmic telemetry metrics` | Prometheus | Each signal can go to one or both destinations: - **Internal DB** - every runtime stores its telemetry in the swarm's distributed database, and the `myrmic telemetry` CLI queries it from any node without extra infrastructure. Storage is **off by default**: nothing is written until a retention period is set. Every `myrmic` binary has this. - **OpenTelemetry (OTel) export** - a runtime pushes its own signals to an OTel collector, which forwards them to tools such as Grafana. This needs a `myrmic` binary built with the `open-telemetry` feature and an endpoint configured per signal. Both destinations receive everything the runtime's log filter lets through, and that is a lot of data on a swarm that runs for days. Part 1 shows how the retention period bounds what is kept on the node; Part 2 how the filter bounds what leaves it. ## How the Tutorial is Organised **Part 1** works with the `myrmic` you already have - the release package or a plain source build - and covers everything the CLI offers: the configuration that turns storage on, the `myrmic telemetry` commands for logs, traces and metrics, changing the log filter and the retention at runtime, and the live debug stream. **Part 2** builds on Part 1. The configuration file grows by three lines, the runtime is restarted with it, and the trace IDs you learned to follow in the CLI are the ones you look up in Grafana. Part 2 starts with a **rebuild of the CLI**: the released packages and the default source build do not contain the OTel exporter. Building takes several minutes - if you plan to continue to Part 2, you can start the build described at the beginning of it while working through Part 1. Terminals used throughout: | Terminal | Runs | |---|---| | Terminal 1 | the Myrmic runtime | | Terminal 2 | your working shell: deploy, send, `myrmic telemetry …` | | Terminal 3 | `myrmic telemetry debug` - the live stream (Part 1, Step 6) | ## Prerequisites - Completed the [Quickstart](../01_quickstart.md). The tutorial reuses its `counter` cell: the `myrmic-quickstart/` directory with the built `counter` crate should still exist. If not, run `myrmic new counter` and `myrmic build counter` again. - No runtime running - stop any leftover with `myrmic runtimes stop`. Part 1 starts one from a configuration file. - *Part 2 only:* the Myrmic repository cloned locally, the Rust toolchain via [rustup](https://rustup.rs/), the packages listed under [Install from source](../01_quickstart/01_installation.md#install-from-source), and Docker with Docker Compose. ## Tutorial Parts 1. [The CLI](./07_observability/01_the-cli.md) - turn telemetry storage on, generate activity with the counter, and inspect logs, traces and metrics from the command line - **learning how the runtime records telemetry and how the `myrmic telemetry` commands read it.** 2. [The Grafana Stack](./07_observability/02_the-grafana-stack.md) - rebuild the CLI with OpenTelemetry support, start the Grafana stack, and export the same signals to it - **learning how OTel export is configured per runtime and how to find your data in Loki, Tempo and Prometheus.** # Part 1 - The CLI This is Part 1 of the [Observability](../07_observability.md) tutorial. You configure a runtime to keep its telemetry, produce some activity with the Quickstart's `counter` cell, and read logs, traces and metrics with the `myrmic telemetry` commands. Everything here works with the `myrmic` you already have. --- ## Step 1 - Configure the Runtime By default a Myrmic runtime prints its logs to stdout and stores nothing. Telemetry is configured in the `telemetry` section of the runtime configuration file (YAML) - a top-level key, next to `execution`, `db` and `gateway`. In Terminal 2, in your `myrmic-quickstart/` directory, create `my-runtime.yml`: ```yaml telemetry: # Turn on storage in the internal DB and keep records this long (humantime syntax). # Without it nothing is stored and the `myrmic telemetry` query commands show nothing. db_retention: "1h" logs: # Which log records are emitted - to stdout and to the DB. # The same filter decides which spans are recorded, so it also controls traces. # Syntax (tracing EnvFilter): = or just , comma separated. # "info" - info and above from every target (cells included) # "info,zenoh=off" - the same, without the transport library # "debug,h2=warn,zenoh=off" - debug overall, quieter libraries # A bare "zenoh=off" also silences the address-change reporting - see the note below. # If omitted, the RUST_LOG environment variable is used instead. env_filter: "info" # Format of the log lines printed to stdout. No effect on what is stored. # FULL - timestamp + level + target + fields (default) # COMPACT - shorter single-line output # PRETTY - human-friendly multi-line output, good for development # JSON - machine-readable JSON, good for log aggregators format: "FULL" ``` The [Runtime Configuration reference](../../10_reference/01_configuration/01_runtime-configuration.md#telemetry) lists the remaining keys; Part 2 adds three of them. > **Why `info` and not `swarm=info,warn`?** A target filter such as `swarm=info,warn` keeps the runtime's own `swarm::…` lines and drops everything else at INFO. Cells log under the target `sorg_execution::wasm::host_functions::logging`, and the spans of your command handlers live outside the `swarm` crate too - so with that filter the DB receives the runtime's chatter but **no cell log lines and no traces**. Start with `info`; if the transport library is too noisy, use `info,zenoh=off`. > **Silencing `zenoh` also silences an address change.** A node reports that its own IP address moved under `zenoh::net::runtime::interface_monitor` and `zenoh::net::runtime::orchestrator`, so any filter carrying a plain `zenoh=off` drops it. Keep the carve-out after it - `info,zenoh=off,zenoh::net::runtime::interface_monitor=debug,zenoh::net::runtime::orchestrator=info` - on nodes whose address can move. The filter in `swarm/configs/myrmic.jsonnet` and the one `myrmic runtimes start` builds already do. See [Addresses that change](../../11_security.md#addresses-that-change). > **Note:** the runtime only checks the *top level* of the file. A misspelt key inside `telemetry` - `filter` instead of `env_filter`, say - is ignored without any message. --- ## Step 2 - Start the Runtime In Terminal 1, from `myrmic-quickstart/`, start a runtime with that file and leave it running: ```bash myrmic runtimes start my-runtime.yml ``` Wait for the readiness line: ```text INFO runtime "default" ready () ``` From now on every log record, span and metric the runtime and its cells emit is written to the internal DB. Nothing from before this point is stored - `db_retention` only applies to records emitted while it is set. --- ## Step 3 - Generate Some Activity Back in Terminal 2. Deploying a cell produces its first log line (the `init` handler logs `starting`). To get traces you need a cell to handle a message - each command a cell processes produces a trace, and the CLI prints the trace ID of every command it sends. ```bash # Deploy the Quickstart counter myrmic deploy counter # Send three commands - each one produces a trace and a log line in the cell myrmic send counter increment myrmic send counter increment myrmic send counter increment ``` Each `send` prints the trace ID of the command it just sent: ```text INFO trace ID = b73cb3c74ef51f9e08eb767027963788 INFO successfully sent command ``` Keep one of those IDs at hand - the next steps use it to follow a single command through logs and traces. --- ## Step 4 - Read Logs, Traces and Metrics The `myrmic telemetry` subcommands query the internal DB directly. Each one has a page in the [CLI reference](../../10_reference/02_myrmic-cli.md); this step shows what they return for the activity of Step 3. ### Logs ```bash myrmic telemetry logs ``` Shows the stored log records sorted by time, colour-coded by severity. Each row has the severity, a timestamp, and the message; a row that belongs to a trace shows the trace ID inline. Among the runtime's own lines you will find the counter's: ```text INFO [2026-09-08T22:26:07.676+02:00] | trace_id = 890a395a726e3e028f32f084585d870c | starting (id=Sri(5d883103-…)) INFO [2026-09-08T22:26:07.695+02:00] | trace_id = b73cb3c74ef51f9e08eb767027963788 | Incremented count to 1 (sender=Sri(00000000-…)) INFO [2026-09-08T22:26:07.707+02:00] | trace_id = 87850ecddbe587e05622fd76ea073b2f | Incremented count to 2 (sender=Sri(00000000-…)) INFO [2026-09-08T22:26:07.721+02:00] | trace_id = f70b5a24c9cefdf6169cd129af82bf66 | Incremented count to 3 (sender=Sri(00000000-…)) ``` The trace IDs are the ones `myrmic send` printed in Step 3. Pass one of them to see only the records of that command: ```bash myrmic telemetry logs --trace-id b73cb3c74ef51f9e08eb767027963788 ``` > **`DEBUG`/`TRACE` records are hidden by default.** `myrmic telemetry logs` reuses the CLI's own `-v` > verbosity flag to decide which stored severities to print. `ERROR`, `WARN` and `INFO` always show; > `DEBUG` needs `-v` and `TRACE` needs `-vv` - provided the runtime's filter let them through when they > were recorded (Step 1, and [Step 5](#step-5---change-the-filter-and-the-retention-at-runtime) below): > > ```bash > myrmic telemetry logs -v # also DEBUG > myrmic telemetry logs -vv # also TRACE > ``` > > This only affects `logs`. `myrmic telemetry traces` always dumps every stored span. ### Traces ```bash myrmic telemetry traces > trace.json ``` Writes all stored spans as a JSON array in the [Trace Event Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview) (the Chrome trace format). Open https://ui.perfetto.dev/ and drop `trace.json` on it to browse the spans on a timeline. Each `increment` from Step 3 is one trace: a span named `increment` in the category `cell_task::message_handler`, plus a span for the cell's log line (category `wasm_log`) linked to it. The export contains *every* recorded span, and a runtime records far more than your handlers - after a few minutes most of the file is runtime and transport spans. When you are after one command, export just its trace: ```bash myrmic telemetry traces --trace-id b73cb3c74ef51f9e08eb767027963788 > one-trace.json ``` ### Metrics ```bash myrmic telemetry metrics ``` Prints the **latest snapshot** of every metric: name and value on one line, attributes indented below. Byte values are shown as human-readable sizes. Metrics are exported in intervals, so this prints **nothing during the first minute** after the runtime started - run it again after that. For the counter you will find, among some 50 metric families: ```text cell_commands_processed 3 host=cell_interaction cmd=increment kind=command pid=974858 sri=5d883103-6382-5d16-9a0c-d70fd0565cb6 process.memory.usage 79.9 MiB host=c85a171750954bacbc9bf2f07caf77d4 pid=974858 ``` --- ## Step 5 - Change the Filter and the Retention at Runtime Both settings from Step 1 can be changed **without restarting any node**. The new value is broadcast to all connected nodes and takes effect within a few seconds. ### The log filter ```bash # Everything at DEBUG, except the transport library - but keeping address-change reporting myrmic telemetry set-filter "debug,zenoh=off,zenoh::net::runtime::interface_monitor=debug,zenoh::net::runtime::orchestrator=info" # Back to normal myrmic telemetry set-filter "info" ``` Filter syntax follows the `tracing` crate's [`EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html) format, and the filter decides what is stored *and* which spans are recorded. Two things to know before you type `debug`: - A bare `debug` floods the DB - the runtime's internal DEBUG lines arrive at hundreds of rows per second. Exclude the transport (`zenoh=off` plus the carve-out) as above, or raise only the cells' level with `myrmic telemetry debug --level DEBUG` (Step 6), which restores the filter when it exits. - `swarm=debug,warn` does **not** show you more of your cells. Cell log lines are emitted under the target `sorg_execution::wasm::host_functions::logging`, so a target filter on `swarm` leaves them - and their traces - out. If you need a target filter, include both: `swarm=info,sorg_execution=info,warn`. ### The DB retention ```bash # Keep only the last 15 minutes of data myrmic telemetry set-db-retention "15min" # Keep 1 day and 30 minutes myrmic telemetry set-db-retention "1day 30min" # Stop storing telemetry in the DB (the default) myrmic telemetry no-db-retention ``` Each command answers with `DB retention set to '…' on all connected nodes`. A value set this way lives in the running processes only: after a runtime restart the configuration file's `db_retention` applies again, or nothing if it has none. Only records emitted after a retention is set are kept. The retention period is also the storage bound on the node: every log record and span the filter lets through is written to the runtime's database until it expires, and a runtime at `info` accumulates a lot within a day - at `debug`, hundreds of rows per second. On a device with little disk, keep the retention short, or turn it on only while you investigate. Before you go on, make sure storage is on again: ```bash myrmic telemetry set-db-retention "1h" ``` --- ## Step 6 - The Live Debug Stream The commands so far inspect data that has already been recorded. `myrmic telemetry debug` stays running and streams activity **as it happens**, until you press Ctrl-C or a `--timeout` elapses. Open Terminal 3 and start it: ```bash myrmic telemetry debug --timeout 60s ``` The stream shows three things, in timestamp order: **events**, as an `EVENT= payload=, trace_id=` line, the **commands** sent to a cell, as a `COMMAND= receiver_sri=, trace_id=` line, and the **log lines of cells**, as `[time] LEVEL message`. From Terminal 2, publish an event and send a command: ```bash myrmic publish rain 20 myrmic send counter increment ``` Terminal 3 shows the event - no cell handles `rain`, an event is shown regardless - then the command, and then the counter's log line, the moment its handler runs: ```text INFO starting debug stream [2026-09-11T12:54:53.870000000Z] EVENT=rain payload=20, trace_id=25aa6a45-b026-0521-8be4-7a3e2c7bc3c7 [2026-09-11T12:55:00.904000000Z] COMMAND=increment receiver_sri=5d883103-6382-5d16-9a0c-d70fd0565cb6, trace_id=6921abc0-aeb1-2bf7-94f7-f2ab55788df1 [2026-09-11T12:55:00.907105589Z] INFO Incremented count to 1 (sender=Sri(00000000-0000-0000-0000-000000000000)) INFO debugging ends after timeout ``` Unlike `myrmic telemetry logs`, the stream is not gated by `-v`: every severity a cell emits is shown. Payloads are printed as JSON if they parse as JSON, otherwise as a string, otherwise as raw hex bytes. A `COMMAND` line is shown while the command's row is still in the target cell's mailbox, so a command whose handler has already consumed it appears through that handler's log lines instead; the [reference page](../../10_reference/02_myrmic-cli/12_telemetry/07_debug.md) has the full record layout. Useful flags: ```bash # Only the commands and log lines of one cell (SRI or SRN); events are not shown in this mode myrmic telemetry debug --id counter --timeout 30s # One JSON object per line, e.g. to pipe into jq myrmic telemetry debug --json # Raise the cells' log level to DEBUG for the duration of the stream, leaving the # runtime's own targets alone; the previous filter is restored on exit myrmic telemetry debug --level DEBUG ``` `--level` prints what it changed: `raised cell log level to 'DEBUG' (filter: 'info,swarm::embedded=DEBUG,sorg_execution::wasm::host_functions::logging=DEBUG')`, and `restored filter to 'info'` when the stream ends. This is usually the fastest way to answer "what is my swarm doing right now" while you reproduce an issue, rather than reproducing it first and then digging through `logs` and `traces` afterwards. --- ## Troubleshooting **The runtime does not start: `unable to parse configuration file […]: unknown field`** : The file has a key the runtime does not know at the top level - for example `myrmic:` wrapped around `telemetry`. `telemetry` is itself a top-level key (Step 1). **`myrmic telemetry logs` answers `No log records found within the database; Did you set a retention period?`** : Nothing is stored by default. Set `db_retention` in the configuration file or run `myrmic telemetry set-db-retention "1h"`, then generate new activity - only records emitted after the retention is set are kept. A retention set with the command is lost when the runtime restarts; the configuration file's value is not. **Logs are there, but no cell log lines, and `myrmic telemetry traces` prints `[]`** : The filter is too narrow. A target filter such as `swarm=info,warn` keeps only the runtime's own crate; cells log under `sorg_execution::wasm::host_functions::logging` and the handler spans are outside `swarm` too, so neither is recorded. Use `info` (or `info,zenoh=off,zenoh::net::runtime::interface_monitor=debug,zenoh::net::runtime::orchestrator=info`). **`myrmic telemetry metrics` prints nothing** : Metrics are exported in intervals; the first snapshot appears about a minute after the runtime started. If it stays empty, the retention is not set (see above). **A `DEBUG` or `TRACE` log I expect isn't showing up in `myrmic telemetry logs`** : Two independent filters are in play. First, the runtime's `env_filter` (or `myrmic telemetry set-filter`) controls what is recorded at all - at `"info"`, `DEBUG`/`TRACE` records are never stored. Second, `myrmic telemetry logs` hides `DEBUG`/`TRACE` severities by default - pass `-v` (`DEBUG`) or `-vv` (`TRACE`) to the command itself, e.g. `myrmic telemetry logs -v --trace-id `. `myrmic telemetry debug --level DEBUG` handles both at once for cell logs. **Too much noise in logs** : Use `myrmic telemetry set-filter "info,zenoh=off,zenoh::net::runtime::interface_monitor=debug,zenoh::net::runtime::orchestrator=info"` at runtime to quieten the transport library without restarting, keeping the targets that report an address change. Avoid a bare `debug` - it stores hundreds of rows per second. --- ## What Have You Learned - A runtime stores telemetry only while a retention period is set - `db_retention` in the configuration file, or `myrmic telemetry set-db-retention` at runtime. The command's value does not survive a restart; the file's does. - The `telemetry` section is a top-level key of the runtime configuration. Its `logs.env_filter` decides what is recorded - log records *and* spans - so a filter that excludes the cells' target silently removes cell logs and traces. - `myrmic send` prints a trace ID; `myrmic telemetry logs --trace-id` and `myrmic telemetry traces --trace-id` follow that one command through the swarm. - `logs` hides `DEBUG`/`TRACE` unless you pass `-v`/`-vv`; `traces` exports everything in the Trace Event Format; `metrics` shows the latest snapshot and needs about a minute after start. - `set-filter` and `set-db-retention` reach all connected nodes within a few seconds, without a restart. - `myrmic telemetry debug` streams events and cell log lines live; `--level` raises the cells' log level for the duration of the stream. ## Next Step Everything you saw lives in the swarm's own database and is read with the CLI. In [Part 2 - The Grafana Stack](./02_the-grafana-stack.md) the same runtime exports the same signals to Loki, Tempo and Prometheus - after a rebuild of the CLI with OpenTelemetry support. # Part 2 - The Grafana Stack This is Part 2 of the [Observability](../07_observability.md) tutorial. The runtime from Part 1 starts exporting its logs, traces and metrics over OpenTelemetry to a local Grafana stack, and you find the counter's activity again in Loki, Tempo and Prometheus. It continues where [Part 1](./01_the-cli.md) left off: `my-runtime.yml` exists in `myrmic-quickstart/` and the runtime is running in Terminal 1. Two things change: the `myrmic` binary, and three lines of configuration. --- ## Step 1 - Build Myrmic with OpenTelemetry Support The OTel exporter is opt-in at compile time. The released packages and the default source build from the Installation page do not contain it: with an endpoint configured they start normally, print no warning, and export nothing. So the first step is a build with the `open-telemetry` feature. Install the packages listed under [Install from source](../../01_quickstart/01_installation.md#install-from-source) on the Installation page, then in Terminal 2, from the root of the cloned repository: ```bash cargo install --path swarm/myrmic-cli/ --features open-telemetry ``` This builds the CLI and puts it at `~/.cargo/bin/myrmic`. The first `cargo` call also installs the Rust toolchain pinned in the repository's `rust-toolchain.toml` if you do not have it yet - that takes a minute and prints a few `warn:` lines from rustup, which are harmless. The build itself takes several minutes (see [Build resources](../../01_quickstart/01_installation.md#build-resources)); you can go on with Step 2 while it runs. When it is done, make sure the `myrmic` you run from now on is that one: ```bash which myrmic ``` It must print the cargo install location (usually `~/.cargo/bin/myrmic`), not `/usr/bin/myrmic` from the package. If the package wins, put `~/.cargo/bin` first in your `PATH` or uninstall the package. (`myrmic --version` does not tell the two apart - both print the same version and commit.) > **In a real swarm** the exporter runs inside each runtime and sends only that runtime's own telemetry. A runtime built without the feature, or without an endpoint, contributes nothing to Grafana, and no other node sends on its behalf - so this rebuild and the configuration of Step 3 apply to every runtime you want to see. The internal DB of Part 1 is different: it is replicated across the swarm, which is why the CLI shows all nodes from any one of them. --- ## Step 2 - Start the Grafana Stack For local testing, a ready-made Docker Compose file is provided under `docker/otel-stack/` in the repository. It starts: | Service | Purpose | Default address | |---------|---------|-----------------| | **OpenTelemetry Collector** | Receives OTel data from Myrmic | `localhost:4317` (gRPC), `localhost:4318` (HTTP) | | **Grafana Tempo** | Stores and queries distributed traces | internal | | **Grafana Loki** | Stores and queries log streams | internal | | **Prometheus** | Stores and queries metrics | internal | | **Grafana** | Visualization UI for all of the above | `http://localhost:3000` | ### Install Docker **Ubuntu** ships the Docker engine and the Compose v2 plugin in its own repositories: ```bash sudo apt install docker.io docker-compose-v2 ``` **Debian** does not have a `docker-compose-v2` package. Either install Docker Engine and the Compose plugin from [Docker's own apt repository](https://docs.docker.com/engine/install/debian/), or use Debian's packages, which give you the older standalone Compose v1: ```bash sudo apt install docker.io docker-compose ``` Verify the installation: ```bash docker --version docker compose version # Compose v2 plugin: "docker compose" with a space docker-compose --version # Compose v1: "docker-compose" with a hyphen ``` The stack works with both. The commands on this page use the v2 form `docker compose …`; with v1, type `docker-compose …` instead. For other platforms, follow the [official Docker installation guides](https://docs.docker.com/engine/install/). #### Optional: Rootless Mode By default Docker requires root privileges. Running it in rootless mode improves security by not exposing the Docker daemon as root: ```bash sudo apt install uidmap curl -fsSL https://get.docker.com/rootless | sh ``` After the script completes, follow the printed instructions to add the rootless socket to your environment. Commands like `docker compose up` will then work without `sudo`. See the [rootless Docker docs](https://docs.docker.com/engine/security/rootless/) for more. ### Start the Stack ```bash cd /docker/otel-stack docker compose up -d ``` The `-d` flag detaches the stack so it runs in the background. Omit it to see the stack's own log output inline. Grafana is then accessible at **http://localhost:3000** (no login required in the default dev config). ### Stop the Stack Not now - when you are done with the tutorial: ```bash docker compose down # stop containers, keep recorded data docker compose down -v # stop containers AND delete all recorded data (clean slate) ``` --- ## Step 3 - Add the Export Endpoints Export is configured **per signal**: each of `logs`, `metrics` and `traces` has its own `otel_endpoint`, and a signal without one is not exported. Add the three endpoints to the `my-runtime.yml` from Part 1 - everything else stays as it is: ```yaml telemetry: db_retention: "1h" logs: env_filter: "info" format: "FULL" otel_endpoint: "http://localhost:4317" # NEW - the collector's gRPC port metrics: otel_endpoint: "http://localhost:4317" # NEW traces: otel_endpoint: "http://localhost:4317" # NEW ``` Keep `db_retention`: the `myrmic telemetry` commands from Part 1 keep working next to Grafana. The `env_filter` matters as much as in Part 1 - it decides what is exported, spans included. With `swarm=info,warn` Loki would receive only the runtime's own lines and Tempo would stay empty. > **Mind the volume.** A runtime that exports telemetry sends *everything* its filter lets through: every log line, every span, every metric interval, for the runtime itself as much as for your cells. On a running swarm that adds up to gigabytes in the collector's storage within days, and to constant network traffic from every exporting node. Keep `env_filter` at `info` or narrower in production, exclude noisy targets such as `zenoh`, and remember that `db_retention` stores the same data a second time on the node itself - drop it or keep it short once Grafana is in place. The compile-time feature alone costs nothing; the data flows only once endpoints are configured. --- ## Step 4 - Restart the Runtime and Generate Activity The configuration is read at start, and the running runtime is still the old binary. In Terminal 1, stop it with Ctrl-C (or `myrmic runtimes stop` from Terminal 2) and start it again - with the new `myrmic` and the extended file: ```bash myrmic runtimes start my-runtime.yml ``` Only telemetry emitted from now on is exported. The counter is gone too: a cell with the default restart policy is not brought back when its runtime stops (the [Resilience](../02_resilience.md) tutorial covers restart policies), and `myrmic cells` answers `No cells registered`. In Terminal 2, deploy it again and produce fresh activity: ```bash myrmic deploy counter myrmic send counter increment myrmic send counter increment myrmic send counter increment ``` Note the trace IDs again. The internal DB still receives everything, as in Part 1: ```bash myrmic telemetry logs ``` If Terminal 1 shows `opentelemetry_sdk` lines with `ExportError`, the runtime is exporting but cannot reach the collector - check the stack with `docker compose ps` in `docker/otel-stack/`. No such lines and nothing in Grafana usually means the runtime was started with a `myrmic` without the feature (Step 1). --- ## Step 5 - Inspect Telemetry in Grafana Open **http://localhost:3000**. The main tool for ad-hoc inspection is the **Explore** view, accessible from the left sidebar (compass icon). In Explore you pick a data source from the dropdown at the top - Loki for logs, Tempo for traces, Prometheus for metrics - and then build queries interactively. See the [Grafana Explore documentation](https://grafana.com/docs/grafana/latest/explore/) for a general introduction. Every runtime reports itself as the service **`swarm`** - the name of the runtime's core crate. It is the `service_name` label in Loki and the service in Tempo. ### Logs Logs are stored in [Loki](https://grafana.com/docs/loki/latest/) and queried using [LogQL](https://grafana.com/docs/loki/latest/query/). 1. Open **Explore** and select **Loki** from the data source dropdown at the top of the page. ![Loki source selection](../../../images/grafana-logs.png) 2. In the query builder that appears, click **+ Add label filter** and set `service_name = swarm`. You can add further filters - for example `level = ERROR` to show only errors (the labels Loki has are `service_name`, `level`, `job` and `exporter`). When ready, click **Run Query** in the top-right corner. ![Log results](../../../images/grafana-logs-view.png) Log lines are shown newest-first in the results panel below the query builder. Each line shows the timestamp, log level badge, and message. You can expand any entry to see all attached key-value attributes. The counter's `Incremented count to …` lines from Step 4 are there next to the runtime's own. 3. Any log entry that belongs to a distributed trace will show a **Tempo** button on the right side of the row. Clicking it opens the full trace directly - this is the fastest way to go from a log message to the trace that produced it. > **Tip:** If you already know a trace ID (from `myrmic send` or `myrmic telemetry logs`), paste it into the LogQL query as `{service_name="swarm"} |= ""` to see only log lines from that trace. The exported log body is JSON with the ID in a `traceid` field, so `{service_name="swarm"} | json | traceid = ""` works as well. ### Traces Traces are stored in [Grafana Tempo](https://grafana.com/docs/tempo/latest/) and queried using [TraceQL](https://grafana.com/docs/tempo/latest/traceql/). Traces can be reached two ways: - **From a log entry**: click the **Tempo** button next to any log line that has a trace ID (see above). - **Directly**: open **Explore**, select **Tempo** from the data source dropdown, then either paste a trace ID printed by `myrmic send`, or use the **Search** tab and filter by service name `swarm`. Each `increment` from Step 4 is a trace whose root span is `cell_task::message_handler`; the cell's log line is a `wasm_log` span. Traces show up within about a minute of the command. ![Tempo source selection](../../../images/grafana-tempo.png) The trace view renders a timeline of spans. Each row is one span - a unit of work inside a single node. In Myrmic, spans typically appear sequentially: a parent span finishes before the spans it triggered appear, reflecting the asynchronous, message-driven nature of the system rather than a synchronous call stack. The horizontal position and width of each bar show when a span started and how long it took, making it easy to see the order of operations and spot latency between steps. Clicking a span expands a detail panel showing all its attributes. ![Trace view](../../../images/grafana-tempo-view.png) ### Metrics Metrics are stored in [Prometheus](https://prometheus.io/docs/introduction/overview/) and queried with [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/). See the [Grafana Prometheus data source docs](https://grafana.com/docs/grafana/latest/datasources/prometheus/) for Grafana-specific query options. Two ways to explore metrics: **Metrics Drilldown** (easiest for exploration): open the **Drilldown** app from the left sidebar. It lists all metric names reported by the runtime, grouped by prefix - `cell_…` for cell metrics such as `cell_commands_processed_total` and `cell_mailbox_depth_…`, `process_…` and `system_…` for the runtime process. Click any metric to see its current value, a time-series graph, and a breakdown by label. No PromQL knowledge required. As with the CLI, the first values arrive about a minute after the runtime started. ![Metrics Drilldown](../../../images/grafana-metrics-drilldown.png) **Explore view** (for precise queries): open **Explore** and select **Prometheus** as the data source. Type a metric name in the query field - Grafana will autocomplete from the known metric list. From here you can apply PromQL functions such as `rate()` for per-second rates. ![Prometheus in Explore](../../../images/grafana-explore-metrics.png) Results appear as a time-series graph and a table of raw data points below. Use the time range picker in the top-right corner to zoom in on a specific incident window. ![Metrics result](../../../images/grafana-explore-metrics-view.png) --- ## Troubleshooting **No data in Grafana** : Three things must be true: the stack is up (`docker compose ps` in `docker/otel-stack/`), the `otel_endpoint` keys are set per signal (`logs`, `metrics`, `traces`) in the runtime configuration, and the runtime was started with a `myrmic` built with `--features open-telemetry`. A binary without the feature starts normally, prints nothing about export and exports nothing - check `which myrmic` (Step 1). A binary *with* the feature that cannot reach the collector logs `opentelemetry_sdk` lines with `ExportError` on its stdout. **Logs in Grafana but no traces** : Almost always the filter. A target filter such as `swarm=info,warn` excludes the cells' log target and the handler spans; `env_filter: "info"` gives you the traces within a minute. **Only the runtime's lines in Loki, none from the counter** : Same cause - see above. Cells log under `sorg_execution::wasm::host_functions::logging`, which a filter on `swarm` leaves out. **Grafana shows stale / old data only** : If you restarted the runtime without cleaning volumes, old data may still be present. Run `docker compose down -v` in `docker/otel-stack/` to wipe everything and start fresh. **OTel collector connection refused** : Confirm the Docker stack is up (`docker compose ps` in `docker/otel-stack/`) and that port `4317` is not blocked by a firewall. The runtime keeps working and keeps retrying; the failed batches are dropped. --- ## What Have You Learned - The OTel exporter is a compile-time feature: `--features open-telemetry`. The released packages do not have it, and a binary without it silently ignores the endpoints. - Export is configured per signal with `otel_endpoint` under `logs`, `metrics` and `traces`, and per runtime - each runtime exports only what it emits itself, so every node you want in Grafana needs the feature and the endpoints. - The `env_filter` from Part 1 also decides what is exported, spans included. - Configuration is read at start: adding endpoints means a restart, and only telemetry emitted afterwards reaches the collector. The internal DB and the `myrmic telemetry` commands keep working alongside. - In Grafana the runtime is the service `swarm`; a trace ID from `myrmic send` finds the same command in Loki and Tempo that `myrmic telemetry logs --trace-id` showed in Part 1. - Volume is governed per runtime by the filter and the retention: keep `env_filter` narrow, exclude noisy targets, and drop or shorten `db_retention` once Grafana is in place so the data is not stored twice. ## Where to Go From Here - The [Observability guide](../../05_guides/10_observability.md) summarises everything the CLI offers and when to use which command. - The [Runtime Configuration reference](../../10_reference/01_configuration/01_runtime-configuration.md#telemetry) lists the remaining telemetry keys, including the batch settings that govern the export overhead. - The [Smart Greenhouse](../01_smart-greenhouse.md) gives you a multi-cell application whose command hops make far more interesting traces than a single counter. # Resilience In this tutorial you take two cells from the [Smart Greenhouse](./01_smart-greenhouse.md) - the mock sensor and the grow-bed - and run them across three Myrmic runtimes standing in for three machines. Then you start killing runtimes and watch what the swarm does about it. You learn three things that together make up *resilience* in Myrmic today: where a cell may run (placement tags), what happens to a cell when its runtime dies (restart policy), and what happens to its **state** - which is a separate question, and the one that matters most. > **Preview version.** What this tutorial shows is the *manual* approach available today: you decide with the CLI where a cell may run, whether it is restarted, and on which nodes copies of its state are kept. A more robust approach, in which the swarm keeps a cell and its state alive by itself, with faster response time, is on the [Roadmap](../09_roadmap.md). Nothing here is part of the [guarantee contract](../08_guarantees.md) yet. ![Three machines, one greenhouse](../../images/resilience-topology.svg) ## The Setting Picture a real greenhouse with three computers: | Runtime | Stands for | Tags | Runs | |---|---|---|---| | `node1` | the Raspberry Pi wired to the soil probe at the bed | `soil-probe` | `moisture-sensor` | | `node2` | a spare box in the back room | `compute` | `grow-bed`, or a copy of its state | | `node3` | a second spare box | `compute` | `grow-bed`, or a copy of its state | The sensor can only run where the probe is wired in - on `node1`. The grow-bed is pure software and can run on either spare box. Software cannot make a unique probe redundant; it *can* make the state derived from it redundant. That difference is the whole tutorial. Ideally you would have three machines. You do not need them: three runtimes on one computer behave exactly the same, and that is what you will use here. ## Prerequisites - Completed [Part 1](./01_smart-greenhouse/01_the-mock-sensor.md) and [Part 3](./01_smart-greenhouse/03_the-grow-bed.md) of the Smart Greenhouse: the `moisture-sensor` and `grow-bed` crates exist in your `greenhouse/` directory and build. - For the finale, the complete Smart Greenhouse, including its `app_specs.yml` from [Part 6](./01_smart-greenhouse/06_the-finale.md). - No Myrmic runtime running. If one is, stop it: `myrmic runtimes delete `. You will use two terminals: | Terminal | Runs | |---|---| | Terminal 1 | your working shell: start and kill runtimes, deploy, send | | Terminal 2 | `myrmic subscribe` - a live view of the events | ## Tutorial Parts 1. [The Sensor and Its Node](./02_resilience/01_the-sensor-and-its-node.md) - start three tagged runtimes, pin the sensor to one, kill that runtime and bring it back - **learning how placement tags and a restart policy work.** 2. [The Grow-Bed and Its State](./02_resilience/02_the-grow-bed-and-its-state.md) - deploy the grow-bed, find out where its state is kept, kill the node it runs on, and see when the state survives - and how to make that likely - **learning that a cell's state lives in one place unless you ask for copies.** 3. [The Whole Greenhouse](./02_resilience/03_the-whole-greenhouse.md) - add a fourth runtime for the pump, fold placement and restart into the application specification and replicate the whole application - **learning how the pieces fit together in one deployment.** # Part 2 - The Grow-Bed and Its State This is Part 2 of the [Resilience](../02_resilience.md) tutorial. You deploy the grow-bed on the spare boxes, find out where the swarm keeps its state, and kill the node it runs on - twice. The first time, whether the bed remembers is a matter of luck. The second time, you have made it likely. Along the way you learn the most important fact about state in Myrmic today: unless you ask for copies, it exists in **one**. ![One copy: the bed's state is kept on a node of the swarm's choosing](../../../images/resilience-one-copy.svg) --- ## Step 4 - Deploy the Grow-Bed The grow-bed is pure software. It may run on either spare box, and never on the Raspberry Pi: ```bash myrmic deploy grow-bed -t compute --policy always ``` ```text INFO deploying cell (srn = grow-bed, sri = fd02ce9b-180a-540e-8f18-c8f59eeb4a05) INFO deployed cell (srn = grow-bed, sri = fd02ce9b-180a-540e-8f18-c8f59eeb4a05) ``` ```bash myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── grow-bed ────────────────────────────────────────────────────────────────────────────────────────────────────────── grow-bed fd02ce9b-180a-540e-8f18-c8f59eeb4a05 wasm [4]f741c9b 6s always grow-bed grow-bed ──── moisture-sensor ─────────────────────────────────────────────────────────────────────────────────────────────────── moisture-sensor 365d6cfe-e9c2-5914-bfed-3a17d4ecd6da wasm [1]12a7f3f 14s always moisture-sensor moisture-sensor ``` Here the grow-bed landed on `node3`; yours may say `node2`. Either is right - the swarm picks one of the qualifying nodes. What it will never say for the grow-bed is `node1`. Point Terminal 2 at the bed instead of the sensor: ```bash myrmic subscribe bed_state ``` ```text [2026-09-06T18:58:53.954Z] event=bed_state sender=fd02ce9b-... payload=75 bytes { "moisture": 62.399895, "pump_on": false, "target_high": 75.0, "target_low": 55.0 } ``` The sensor on `node1` publishes, the grow-bed on `node3` reacts - across two runtimes, without either cell knowing or caring. The targets are the grow-bed's built-in defaults: 55 to 75. Those defaults are what the bed knows *without* any memory. To tell later whether its memory survived, you need a value that is not the default. Raise the upper target: ```bash myrmic send grow-bed set_target '{"low": 55, "high": 88}' ``` Terminal 2 now shows `"target_high": 88.0` on every `bed_state`. That **88** is your marker. Whenever you see 75 again, the bed has lost its memory. --- ## Step 5 - Where Is the Bed's State? The grow-bed's state - moisture, pump flag, targets - is stored in Myrmic's distributed database, the *data layer*. The default behaviour today is a single copy of that state, and since this is a distributed system, that copy may or may not be on the node the cell runs on. To check where it is, ask: ```bash myrmic replicate ``` ```text TARGET TAGS scope:CELLS/365d6cfe-e9c2-5914-bfed-3a17d4ecd6da/p @ca157d28d8cf44689a97832a30327a8c (provisional) scope:CELLS/@events/bed_state @4f741c9b645144daa3d0e8776399c7bf (provisional) scope:CELLS/@events/moisture @4f741c9b645144daa3d0e8776399c7bf (provisional) scope:CELLS/fd02ce9b-180a-540e-8f18-c8f59eeb4a05/p @ca157d28d8cf44689a97832a30327a8c (provisional) scope:tele @ca157d28d8cf44689a97832a30327a8c ``` `myrmic replicate` is the command that decides which nodes hold copies of which data. You have not used it yet, so every row is marked `(provisional)`: the swarm had to put the data *somewhere* and picked a node on its own. The rows are keyed by the cell's `sri`, so first look up the grow-bed's. Piping the listing prints it once instead of opening the live view, so `grep` gets a single listing to filter: ```bash myrmic cells | grep grow-bed ``` ```text grow-bed fd02ce9b-180a-540e-8f18-c8f59eeb4a05 wasm [4]f741c9b 2m always grow-bed grow-bed ``` Now find that `sri` in the listing above: the row `scope:CELLS/fd02ce9b-.../p`. Its `TAGS` column names exactly one node, by id: `@ca157d28...`. Look that id up in `myrmic network status`: it is `node2`. So the grow-bed *runs* on `node3` while its state is *kept* on `node2`. That is neither a mistake nor a special case. **Where a cell runs and where its state is kept are two separate decisions, and they do not have to agree.** The swarm should place the cell by its tags and place its data where it best serves the application as a whole, so the two can end up on different nodes, as they did here. Until you say otherwise, the data placement is the swarm's own choice - and it is one copy, on one node. In your swarm the copy may sit on any of the three nodes, including the one running the bed. Write down which one it is - you will need it in the next step. --- ## Step 6 - Kill the Node Running the Bed Find the process id of the node the bed runs on - `node3` here - and kill it: ```bash myrmic runtimes list kill -9 ``` Terminal 2 goes quiet: the bed is gone, nobody publishes `bed_state`. The sensor keeps publishing `moisture` into the void. Wait. **After about 70 seconds** the swarm gives `node3` up, notices the grow-bed's restart policy, and starts it again on the only other node that qualifies: ```bash myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── grow-bed ────────────────────────────────────────────────────────────────────────────────────────────────────────── grow-bed fd02ce9b-180a-540e-8f18-c8f59eeb4a05 wasm [c]a157d28 9s always grow-bed grow-bed ──── moisture-sensor ─────────────────────────────────────────────────────────────────────────────────────────────────── moisture-sensor 365d6cfe-e9c2-5914-bfed-3a17d4ecd6da wasm [1]12a7f3f 36m always moisture-sensor moisture-sensor ``` Same `sri`, new runtime: the grow-bed now runs on `node2`. The cell is back. Now look at Terminal 2 for the question that matters - what does it *remember*? There are two possible answers, and Step 5 told you which one you will get: - **The state was kept on a different node than the one you killed.** Then the bed comes back with `"target_high": 88.0`. It moved, and its memory came with it, because the memory was never on the dead node in the first place. - **The state was kept on the node you killed.** Then the bed comes back with `"target_high": 75.0`. The cell was restarted; its one copy of state was on the dead node and is gone with it. The value you set cannot be recovered. In the walk-through the state was on `node2`, so the bed came back with 88. Had it landed on `node3` when it was written, the same kill would have produced 75. Nothing you did as a developer made the difference; the swarm's choice of node did. That is the honest summary of the preview's default: the state of a cell has **one copy**, and whether it survives the loss of a node is luck. Bring `node3` back before going on: ```bash myrmic runtimes start -n node3 --tag compute --detached ``` --- ## Step 7 - Make the Cell State Resilient If one copy makes survival a matter of luck, the fix is more copies. Tell the swarm that the grow-bed's data is to be kept on every node tagged `compute`: ```bash myrmic replicate grow-bed -t compute ``` ```text TARGET TAGS grow-bed compute scope:CELLS/365d6cfe-e9c2-5914-bfed-3a17d4ecd6da/p @ca157d28d8cf44689a97832a30327a8c (provisional) ... ``` Read the new first row: *the grow-bed's data is held by every node tagged `compute`* - that is `node2` and `node3`, and never `node1`. Both spare boxes now hold a copy, and the provisional single copy has been superseded. Notice what the command did **not** ask for: a node name. A replication set names what a node must *be*, not which node it is. Add a fourth spare box tagged `compute` tomorrow and it starts holding a copy without you touching this configuration. Give the swarm a few seconds to copy the data over, then set your marker again, in case it was lost in Step 6: ```bash myrmic send grow-bed set_target '{"low": 55, "high": 88}' ``` Now repeat Step 6: find the node the bed runs on, kill it, wait **about 70 seconds**. ```text [2026-09-06T19:34:59.524Z] event=bed_state sender=fd02ce9b-... payload=75 bytes { "moisture": 62.597828, "pump_on": false, "target_high": 88.0, "target_low": 55.0 } ``` **88.** The bed is on the other spare box and remembers, and this time it is not luck: whichever `compute` node died, the other one held a copy of everything the bed had ever saved. Bring the killed node back; because the replication set says so, it resumes holding a copy of the bed's state without further configuration. ![Replicated: the bed's state is on both compute nodes, so the bed comes back with it](../../../images/resilience-replicated.svg) --- ## What Have You Learned - A cell's state lives in the swarm's database, on a node the swarm picks - **independently of where the cell runs**. `myrmic replicate` shows which; `(provisional)` means you did not choose it. - By default there is **one copy**. Kill the node holding it and the state is gone, even though `--policy always` brings the cell back within about 70 seconds. Kill any other node and the state survives - by luck, not design. - `myrmic replicate -t ` keeps a copy on every node with that tag. With copies on both spare boxes, losing either one leaves the bed's memory intact. - Restart policy and replication answer different questions: "does the cell come back?" and "does the cell remember?". You need both. Next: [Part 3 - The Whole Greenhouse](./03_the-whole-greenhouse.md), where this becomes one file and one command. # Part 1 - The Sensor and Its Node This is Part 1 of the [Resilience](../02_resilience.md) tutorial. You start three runtimes that stand in for three machines, pin the sensor to the one with the probe, and then kill that runtime. Along the way you learn about *placement tags* - how a cell says where it may run - and *restart policies* - what the swarm does when a cell's runtime dies. --- ## Step 1 - Start Three Runtimes A runtime carries *tags*: words that describe what the machine is or has. Some it gets for free - every Linux runtime carries `linux`, and every runtime carries its own id as `@`. Others you give it when you start it. A cell, in turn, can *require* tags, and it is only ever placed on a runtime that carries all of them. In Terminal 1, start the three runtimes. Each gets a name and one tag. `--detached` puts them in the background so one terminal is enough: ```bash myrmic runtimes start -n node1 --tag soil-probe --detached myrmic runtimes start -n node2 --tag compute --detached myrmic runtimes start -n node3 --tag compute --detached ``` Expected output, once per runtime: ```text INFO runtime "node1" pid file: /run/user/1000/myrmic/node1.pid INFO Starting runtime "node1"(112a7f3f15aa4f7ead00258a4c8c609a) ``` Give them a few seconds to find each other, then look at the swarm: ```bash myrmic network status ``` ```text Discovered 3 node(s) # name kind id tags 0 node1 linux [1]12a7f3f soil-probe, @112a7f3f15aa4f7ead00258a4c8c609a, linux 1 node2 linux [c]a157d28 compute, @ca157d28d8cf44689a97832a30327a8c, linux 2 node3 linux [4]f741c9b compute, @4f741c9b645144daa3d0e8776399c7bf, linux ``` Three nodes, one swarm. `node1` is the only one that carries `soil-probe`; `node2` and `node3` both carry `compute`. Keep this table in mind: the `id` column is how the swarm names a node, and you will translate ids back to names more than once. --- ## Step 2 - Pin the Sensor to Its Node Go to your greenhouse workspace and deploy the sensor. Two new flags appear: ```bash cd greenhouse myrmic deploy moisture-sensor -t soil-probe --policy always ``` ```text INFO deploying cell (srn = moisture-sensor, sri = 365d6cfe-e9c2-5914-bfed-3a17d4ecd6da) INFO deployed cell (srn = moisture-sensor, sri = 365d6cfe-e9c2-5914-bfed-3a17d4ecd6da) ``` - `-t soil-probe` is the cell's *requirement*. Only `node1` carries that tag, so only `node1` qualifies - the probe is wired to that machine and nowhere else. - `--policy always` is the cell's *restart policy*: if the cell stops for any reason other than you removing it, the swarm starts it again. The default is `never`. ```bash myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── moisture-sensor ─────────────────────────────────────────────────────────────────────────────────────────────────── moisture-sensor 365d6cfe-e9c2-5914-bfed-3a17d4ecd6da wasm [1]12a7f3f 14s always moisture-sensor moisture-sensor ``` In a terminal `myrmic cells` is a live view that redraws every couple of seconds until you press Ctrl-C; add `--once` for a single listing instead - which is also what you get when the output is piped or redirected. The `runtime` column says `[1]12a7f3f` - `node1`, as it must. Open Terminal 2 and listen to it: ```bash myrmic subscribe moisture ``` ```text [2026-09-06T18:12:33.728Z] event=moisture sender=365d6cfe-... payload=8 bytes 59.79998 [2026-09-06T18:12:34.730Z] event=moisture sender=365d6cfe-... payload=8 bytes 59.39998 ``` One reading a second, the mock weather slowly drying the soil. --- ## Step 3 - Kill the Node, Bring It Back Now pull the plug on the Raspberry Pi. Find `node1`'s process id and kill it the way a power cut would, with no chance to shut down cleanly: ```bash myrmic runtimes list ``` ```text INFO 3 local runtime(s) node1 running pid=99396 node2 running pid=99413 node3 running pid=99430 ``` ```bash kill -9 99396 ``` Terminal 2 falls silent at once. The sensor ran on `node1` and `node1` is gone; there is nothing left to publish. Wait as long as you like - nothing changes. The sensor has a restart policy, but restarting it means placing it on a runtime that carries `soil-probe`, and there is no such runtime in the swarm right now. `myrmic cells` will stop listing the sensor after about a minute, once the swarm has given `node1` up; `myrmic network status` shows two nodes. A restart policy cannot conjure up hardware. Now the electrician arrives. Start `node1` again, with the same name and tag: ```bash myrmic runtimes start -n node1 --tag soil-probe --detached ``` Watch Terminal 2. **About 20 seconds** after the runtime is up, the readings resume: ```text [2026-09-06T18:13:19.431Z] event=moisture sender=365d6cfe-... payload=9 bytes 63.799995 [2026-09-06T18:13:20.433Z] event=moisture sender=365d6cfe-... payload=9 bytes 63.399994 ``` Nobody redeployed anything. The swarm remembered that the sensor should be running, saw a runtime with `soil-probe` reappear, and put the sensor back on it - that is `--policy always` doing its job. `myrmic cells` lists it again, with a fresh `age`. You may notice the reading jumped - from the high 50s before the kill to the mid 60s after. That is the mock sensor's own doing: its startup code resets the simulation to 65 %. Whether a cell's *memory* survives a restart is a bigger question than this cell can answer, and it is the subject of Part 2. --- ## What Have You Learned - A runtime carries **tags**, some automatic (`linux`, `@`), some given at start (`--tag`). A cell **requires** tags with `-t`, and is only placed on a runtime that carries all of them. - A requirement pins a cell to hardware. The sensor lives on `node1` because the probe does; no other node ever qualifies. - `--policy always` makes the swarm restart a cell that stopped for any reason other than being removed. If no qualifying runtime exists, it waits; when one appears, the cell is back within a few seconds. - `myrmic cells` tells you where each cell runs; `myrmic network status` translates the runtime id to a name; `myrmic runtimes list` gives you the process id to kill. Next: [Part 2 - The Grow-Bed and Its State](./02_the-grow-bed-and-its-state.md), where the cell can move - and its memory may not follow. # Part 3 - The Whole Greenhouse This is the last part of the [Resilience](../02_resilience.md) tutorial. You add a fourth runtime for the pump, fold what you did by hand - placement tags and restart policies - into the application specification, bring the whole greenhouse up with one command, and replicate the application as a whole. --- ## Step 8 - Placement and Restart in the App Spec You have been deploying cells one at a time with flags. An application ships as one file - you built that file in the Smart Greenhouse finale. Remove the two hand-deployed cells and the cell-level replication set first: ```bash myrmic delete --cell grow-bed myrmic delete --cell moisture-sensor myrmic replicate grow-bed -e compute ``` The full greenhouse has a second piece of hardware: the pump. In a real installation it is a relay wired to its own Raspberry Pi, so the pump cell can only run there. Start a fourth runtime standing in for that machine, with a tag that says what it has: ```bash myrmic runtimes start -n motor_rpi --tag motor --detached ``` Then edit `greenhouse/app_specs.yml`. The `classes` section is unchanged; each instance gains a `tags` line and a `restart` line: ```yaml name: greenhouse classes: - id: moisture-sensor build: ./moisture-sensor - id: pump build: ./pump - id: grow-bed build: ./grow-bed - id: dashboard build: ./dashboard - id: irrigation-agent build: ./irrigation-agent instances: - class: moisture-sensor tags: [soil-probe] restart: always - class: pump tags: [motor] restart: always - class: grow-bed tags: [compute] restart: always - class: dashboard tags: [compute] restart: always - class: irrigation-agent tags: [compute] restart: always ``` The sensor is pinned to the probe and the pump to the motor; everything else may run on either spare box and comes back if its box dies. Deploy it: ```bash myrmic deploy app_specs.yml myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ─────────────────────────────────────────────────────────────────────────────────────────────────────────── dashboard 884f63a0-83ed-52fe-b67c-2bcfb6df378c wasm [4]f741c9b 8s always dashboard dashboard grow-bed fd02ce9b-180a-540e-8f18-c8f59eeb4a05 wasm [c]a157d28 8s always grow-bed grow-bed irrigation-agent 9f2172bd-73ff-5dba-a7a7-33b0e8756faa wasm [c]a157d28 8s always irrigation-agent irrigation-agent moisture-sensor 365d6cfe-e9c2-5914-bfed-3a17d4ecd6da wasm [1]12a7f3f 8s always moisture-sensor moisture-sensor pump 4e9ba24d-b959-57bf-9b71-73500c8e5495 wasm [7]7b3e0a2 8s always pump pump ``` The sensor sits on `node1` and the pump on `motor_rpi`. The other three are spread over `node2` and `node3` - here grow-bed and agent on one, dashboard on the other. Your split may differ; what cannot differ is that none of the three is on `node1` or `motor_rpi`. ![The finished layout: sensor on node1, pump on motor_rpi, the rest spread over the compute nodes, state replicated on both](../../../images/resilience-app.svg) --- ## Step 9 - Replicate the Application One thing does **not** live in the app spec: replication. Which nodes hold copies of which data is a decision about the swarm, made with the CLI, and it stays in place across redeployments of the application. Replicate the whole application at once: ```bash myrmic replicate app:greenhouse -t compute ``` ```text TARGET TAGS app:greenhouse compute ... ``` `app:greenhouse` covers every cell of the application - the ones deployed now, and any you add to the file later. Every cell's state is now on both spare boxes; kill either box and the cells on it come back on the other within about 70 seconds, remembering everything. Try it: point Terminal 2 at `myrmic subscribe bed_state,watering_started,watering_stopped` and pull a plug. --- ## Step 10 - Clean Up ```bash myrmic delete greenhouse --app myrmic replicate app:greenhouse -e compute myrmic runtimes delete node1 node2 node3 motor_rpi ``` --- ## What Have You Built A greenhouse that survives losing a machine: - The **sensor** and the **pump** are each pinned to the one machine that has their hardware (`soil-probe`, `motor`). If that machine dies, the cell stops - no software can help with that - and comes back by itself when the machine is back. - The **grow-bed**, and every other software-only cell, may run on either spare box (`compute`), restarts on the other one when its box dies (`restart: always`), and remembers what it knew because its state was on both (`myrmic replicate ... -t compute`). - Placement and restart travel with the application in `app_specs.yml`; replication is configured on the swarm with `myrmic replicate`. ## What Have You Learned - **State has one copy by default**, on a node the swarm picks independently of where the cell runs. A restart policy brings a cell back; only replication makes its memory likely to survive. - **Tags do double duty.** The same words decide where a cell may run and where its data may be kept. `compute` kept the bed and its copies off `node1` throughout. - **Name what a node must be, not which node it is.** A tag-based replication set follows nodes as they come and go. - **Expect about a minute.** Noticing a dead node and restarting its cells takes around 70 seconds in the current release; a cell that can only run on one node comes back a few seconds after that node does. > **Preview version.** Everything in this tutorial is the *manual* approach: you chose the tags, the restart policy and the replication set by hand, and the swarm did exactly that and no more. A cell does not resume mid-handler - the copy of a moment ago is what comes back - and none of this is yet part of the [guarantee contract](../../08_guarantees.md). The [Roadmap](../../09_roadmap.md) describes the stages that turn today's configuration into something the swarm does by itself, robustly: keeping a cell, its authority and its state alive across the loss of a node without an operator in the loop. ## Where to Go Next - [`myrmic replicate`](../../10_reference/02_myrmic-cli/15_replicate.md) - the full reference: replicating a single cell, an application, or a shared scope; files; pinning to a node. - [`restart`](../../10_reference/01_configuration/02_cell-and-application-configuration.md#restart) - the restart policies and their crash-loop bounds. - [Guarantees](../../08_guarantees.md) and [Failure Behaviour](../../07_architecture/04_failure-behaviour.md) - what the current release promises when a node is lost, and what is coming. # Scaling Your Application Every cell you have deployed so far was a **root**: listed in `app_specs.yml`, deployed by the CLI, one instance per line. A real greenhouse does not work like that. Beds are added over the season and sensors are screwed to whichever Raspberry Pi is nearest, and nobody wants to edit a file and redeploy for each one. In this tutorial a root cell **spawns** other cells at runtime, and you learn what that means for identity, placement, and what happens when a node dies. > **Preview version.** Restart policies apply to root cells only. A spawned cell is not restarted by the swarm; its parent is told that it was lost and decides what to do. This tutorial shows how to make that decision with the tools available today. The [Roadmap](../09_roadmap.md) describes how supervision becomes something the swarm does by itself. ![The dashboard at the end of the tutorial: six beds with live readings, and the two forms that add a bed or a sensor to a sector](../../images/scaling-dashboard.png) ![Three roots, any number of beds and sensors](../../images/scaling-topology.svg) ## Prerequisites - Completed the [Smart Greenhouse](./01_smart-greenhouse.md): you know what the grow-bed and the sensor do, and how the dashboard reaches the browser. - Completed [Resilience](./02_resilience.md): you know what placement tags, restart policies and `myrmic replicate` do. - No Myrmic runtime running. If one is, stop it: `myrmic runtimes delete `. You will use three terminals: | Terminal | Runs | |---|---| | Terminal 1 | your working shell: start and kill runtimes, deploy, send | | Terminal 2 | `myrmic subscribe` or `myrmic telemetry debug` - a live view | | Terminal 3 | the gateway, from Part 4 on | The finished code is in the repository under `examples/scaling-greenhouse`. The tutorial builds it in a fresh `scaling/` workspace so nothing you do here touches your Smart Greenhouse. ## Tutorial Parts 1. [A Root That Spawns](./06_scaling/01_roots-that-spawn.md) - build a bare grow-bed and a bed root, and spawn three beds from the CLI into two sectors - **learning how one cell creates another, and where it runs.** 2. [Bringing Beds Back](./06_scaling/02_bringing-beds-back.md) - kill the node a bed runs on, then the node the root runs on, and teach the root to bring its beds back - **learning how a parent is told about a lost child and how it rebuilds its tree after its own restart.** 3. [One Sensor per Bed](./06_scaling/03_one-sensor-per-bed.md) - build a sensor root, spawn one mock sensor per bed from the CLI, and pair each bed with its own sensor by name - **learning how spawned cells find each other and how a cell filters a broadcast event.** 4. [The Dashboard](./06_scaling/04_the-dashboard.md) - put the greenhouse on a web page with two inputs that add beds and sensors from the browser - **learning how a browser sends commands into the swarm through the gateway.** # Part 2 - Bringing Beds Back This is Part 2 of the [Scaling Your Application](../06_scaling.md) tutorial. You kill the node a bed runs on and teach the bed root to bring the bed back; then you kill the node the root runs on and see what that does to the beds - **learning how a parent is told about a lost child, and how it rebuilds its tree after its own restart.** It continues where [Part 1](./01_roots-that-spawn.md) left off: four runtimes, the root and three beds running, Terminal 2 on `myrmic subscribe bed_state`. --- ## Step 6 - Copies First You are about to kill nodes, so remember the lesson of the [Resilience](../02_resilience.md) tutorial before you do: a cell's state has one copy by default, on a node the swarm picks. That is true for the beds' moisture, and it is true for the bed root's list of beds. Ask for copies on every node - all four carry the automatic `linux` tag - and give the swarm half a minute to make them: ```bash myrmic replicate app:greenhouse -t linux ``` ```text TARGET TAGS app:greenhouse linux scope:CELLS/72fdd5d5-ca6b-54af-b017-c624f8b8b1d7/p @d40df21caca94c98be184fee8a7645d3 (provisional) scope:CELLS/777e343f-cc44-5964-850d-9302dbd591ee/p @4f741c9b645144daa3d0e8776399c7bf (provisional) ... ``` The first row is your entry; the `provisional` rows below it are the single copies the swarm had placed on its own, one per cell, which the entry now supersedes. The entry covers every cell of the application, the beds that exist and the beds the root spawns later. Check the root's data once the copies are in place: ```bash myrmic database status bed-root --active ``` ```text INFO probed; collecting answers for up to 10s (stops 2s after the last)... CELLS/ec2709f8-5e11-5ca8-a152-5d195d73a00a/p in sync 4 node(s) 112a7f3f full 6 head(s), latest 2026-09-08T15:04:16.311905247Z 4f741c9b full 6 head(s), latest 2026-09-08T15:04:16.311905247Z ca157d28 full 6 head(s), latest 2026-09-08T15:04:16.311905247Z d40df21c full 6 head(s), latest 2026-09-08T15:04:16.311905247Z ``` Without this step, the rest of the part would still *run* - but the beds would forget their moisture, and in Step 9 the restarted root would find an empty list, because the only copy of it died with its node. --- ## Step 7 - A Bed Is Lost What happens when the node a bed runs on dies? The swarm notices, after about a minute, that the node has stopped renewing its lease. It removes the bed from the registry, and it sends the bed's **parent** a notification: `cell_lost`, with the child's name and the reason. Then it does nothing else. A spawned cell has no restart policy - you saw the `—` in Part 1 - so whether the bed comes back is entirely the parent's decision. In Part 1's root that decision is not made at all: a cell that declares no handler for the notification simply drops it. Fifteen lines fix that. Add one import at the top of `bed-root/src/lib.rs`: ```rust use myrmic_sdk::monitor::{CellLost, LostReason}; ``` and this handler at the end of the file: ```rust /// The swarm tells a parent when one of its children is gone. #[myrmic_sdk::monitor] fn child_lost(_md: Metadata, loss: CellLost) -> Result<()> { // Only losses worth repairing: the node died, or the bed crashed. if !matches!(loss.reason, LostReason::NodeLost | LostReason::Crashed) { return Ok(()); } let beds = BEDS.load()?.unwrap_or_default(); let name = loss.local_name.as_deref().unwrap_or(""); let Some(bed) = beds.iter().find(|b| format!("bed-{}", b.index) == name) else { return Ok(()); }; myrmic_sdk::warn!("{name} lost; respawning in '{}'", bed.sector)?; if let Err(err) = spawn_bed(bed.index, &bed.sector) { myrmic_sdk::warn!("{name} could not be respawned: {}", <&str>::from(err))?; } Ok(()) } ``` `child_lost`, marked `#[myrmic_sdk::monitor]`, is the handler the swarm calls with the notification. It looks the lost bed up in the list by name and calls the `spawn_bed` you wrote in Part 1, with the same name and the same sector - the same identity, so the bed finds its state. Not every loss deserves a respawn. `NodeLost` and `Crashed` do. `Terminated` means the root or an operator removed the bed on purpose; `Stopped` means the bed ended itself; `SpawnFailed` means it never came up, so spawning again would fail again. The handler returns `Ok` for those. One rule about the name: the function may be called anything except `on_cell_lost`, which is used internally. Deploy the new root. A running application is not modified in place, so remove it first: ```bash myrmic delete greenhouse --app myrmic deploy app_specs.yml myrmic cells ``` If the deploy answers `class 'bed-root' has active instances`, the removal is still settling; wait a few seconds and run it again. ```text cell sri kind runtime age policy class srn ──── greenhouse ─────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 2s always bed-root bed-root ``` The beds are gone: deleting the application removed them, and this root does not create beds on its own. Ask for one in sector B: ```bash myrmic send bed-root add_bed '"sectorB"' myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ───────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 6s always bed-root bed-root └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [4]f741c9b 4s — grow-bed bed-root/bed-4 ``` `bed-4`, not `bed-1`. Deleting the application removed the cells, not their data: the new root has the same identity as the old one, so it found the list `[1, 2, 3]` where the old one left it and continued counting. Keep that in mind for Step 9. Now watch the root while you pull the plug on `bed-4`'s node. Cell logs are only kept while a retention period is set, so switch that on first. In Terminal 2: ```bash myrmic telemetry set-db-retention 1h myrmic telemetry debug --id bed-root ``` In Terminal 1, `bed-4` runs on `[4]f741c9b`, which is `node3` in the table from Step 1. Find its process id and kill it: ```bash myrmic runtimes list kill -9 ``` For about a minute nothing happens; `myrmic cells` still shows `bed-4` on `node3`. Then, in Terminal 2: ```text [2026-09-08T15:06:54.298000000Z] COMMAND=__sys_cell_lost receiver_sri=ec2709f8-5e11-5ca8-a152-5d195d73a00a, payload=0x1022bffd66... [2026-09-08T15:06:54.300313464Z] WARN bed-4 lost; respawning in 'sectorB' ``` The command's row is still in `bed-root`'s mailbox while the stream reads it, which is why the `COMMAND` line shows up here. A command a handler has already consumed appears through that handler's log lines instead. In Terminal 1: ```bash myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ───────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 1m always bed-root bed-root └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [d]40df21c 6s — grow-bed bed-root/bed-4 ``` Same name, same SRI, a fresh `age`, and a new home: `[d]40df21c` is `node4`, the other sector B node. The notification took 64 seconds to arrive - the time the swarm gives a silent node before declaring it dead - and the respawn took a second. Bring `node3` back so that both sectors are whole again: ```bash myrmic runtimes start -n node3 --tag sectorB --detached ``` --- ## Step 8 - The Root Is Lost The root runs on `node1`. What if *that* node dies? The root is a root with `restart: always`, so the swarm brings it back. But its beds are children of the root that died. Kill `node1` and keep `myrmic cells` running every ten seconds: ```bash myrmic runtimes list kill -9 ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ───────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 3m always bed-root bed-root └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [d]40df21c 2m — grow-bed bed-root/bed-4 ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ─────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [4]f741c9b 9s always bed-root bed-root ``` The root is back, on `node3`, and the tree under it is empty. `bed-4` was on `node4`, a perfectly healthy node, and it is gone anyway. Two things happened, in this order: 1. **The bed was stopped by its own runtime**, about fifty seconds after the kill and *before* the root was redeployed. A child belongs to one incarnation of its parent, and its runtime keeps checking that the parent is alive. When the parent's node had been silent for longer than the grace period, the runtime stopped the bed - a child does not outlive its parent. Had the parent come back sooner, the outcome would have been the same: the runtime also stops a child whose parent has been replaced by a new incarnation. 2. **Nobody was told.** The root that could have received a `cell_lost` for `bed-4` was dead itself, and the new root never knew `bed-4` existed. The monitor handler is for a child lost while its parent lives; it does not run here. So a root restart takes the whole tree down with it, and the monitor handler alone does not build it back up. The new root still knows which beds existed, though: the list is in its state, and the state survived. Bring `node1` back before the next step: ```bash myrmic runtimes start -n node1 --tag sectorA --detached ``` --- ## Step 9 - Rebuild From the List The root already remembers every bed it created. All it has to do when it starts is make sure each one is running. Two more imports at the top of `bed-root/src/lib.rs`: ```rust use core::time::Duration; use myrmic_sdk::{Callback, ClassHandle, Metadata, Result, SpawnError, String, Vec, format}; ``` then this block after `spawn_bed`: ```rust /// How long to wait before trying again when a bed could not be spawned. const RETRY: Duration = Duration::from_secs(20); /// Runs `ensure` again after `RETRY`. fn retry_later() -> Result<()> { let _ = myrmic_sdk::delay(Callback::of::(), RETRY) .build() .map_err(|_| "timer failed")?; Ok(()) } /// Runs on every start of the root, the first deploy and every restart. /// Spawning is deploying and takes a moment, and the root is not up until /// `init` returns - so the rebuild is scheduled, not done here. #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { let _ = myrmic_sdk::delay(Callback::of::(), Duration::from_secs(1)) .build() .map_err(|_| "timer failed")?; Ok(()) } /// Timer target: makes sure every bed in the list is running. A bed that /// already runs is fine; a bed that cannot be spawned right now is tried /// again later. #[myrmic_sdk::cmd] fn ensure(_md: Metadata) -> Result<()> { myrmic_sdk::info!("ensure: running")?; let mut missing = false; for bed in BEDS.load()?.unwrap_or_default() { match spawn_bed(bed.index, &bed.sector) { Ok(()) => myrmic_sdk::info!("bed-{} spawned", bed.index)?, Err(SpawnError::AlreadyExists) => { myrmic_sdk::info!("bed-{} already running", bed.index)? } Err(err) => { myrmic_sdk::warn!("bed-{} not running: {}", bed.index, <&str>::from(err))?; missing = true; } } } if missing { retry_later()?; } Ok(()) } ``` and one line in `child_lost`, right after the warning that a bed could not be respawned: ```rust retry_later()?; ``` `ensure` walks the list and spawns every bed. A bed that already runs answers `AlreadyExists`, which is treated as success, so calling it twice is harmless. A bed that cannot be spawned right now - its whole sector is down, say, or the swarm is still cleaning up after a lost node - is reported, and `retry_later` schedules another `ensure` twenty seconds later. The monitor handler falls back to the same retry, so from now on no refused respawn is final: the root keeps trying, one attempt every twenty seconds, until every bed in the list is running; then the timer is simply not re-armed. `init` runs on every start of the root - the first deploy and every restart - and it does *not* run the loop directly. Spawning is deploying, and a deploy takes a moment; the root itself does not count as deployed until `init` returns. Spawning in `init` would make the root's own deploy wait for its children's deploys, and time out. So `init` schedules the `ensure` command one second later, and returns at once. Deploy the new root, and look at the tree a few seconds later: ```bash myrmic delete greenhouse --app myrmic deploy app_specs.yml myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ───────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 8s always bed-root bed-root ├─ bed-1 777e343f-cc44-5964-850d-9302dbd591ee wasm [c]a157d28 7s — grow-bed bed-root/bed-1 ├─ bed-2 f1356c6d-8603-5fa5-a659-35764d15a3bf wasm [4]f741c9b 6s — grow-bed bed-root/bed-2 ├─ bed-3 72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 wasm [1]12a7f3f 6s — grow-bed bed-root/bed-3 └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [d]40df21c 6s — grow-bed bed-root/bed-4 ``` All four beds, one second after the root, without a single `add_bed`. The list said four, so there are four - `bed-1` to `bed-3` included, which have not run since Step 7. The layout of your greenhouse is not in `app_specs.yml`; it is in the root's state. Give the beds a value to remember and the copies half a minute to catch up. Then look up which node hosts `bed-root` now - `node1` in the table above, but yours may differ - and kill it, with Terminal 2 freshly started on `myrmic telemetry debug --id bed-root`: ```bash myrmic publish moisture 55.0 ``` ```bash myrmic runtimes list kill -9 ``` A minute passes. Then Terminal 2 - if it stays silent once the root has moved, stop the debug stream and start it again: ```text [2026-09-08T15:17:02.057626945Z] INFO ensure: running [2026-09-08T15:17:02.102211980Z] INFO bed-1 spawned [2026-09-08T15:17:02.143541072Z] INFO bed-2 spawned [2026-09-08T15:17:02.184028208Z] INFO bed-3 spawned [2026-09-08T15:17:02.226429182Z] INFO bed-4 spawned ``` and Terminal 1: ```text cell sri kind runtime age policy class srn ──── greenhouse ───────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [4]f741c9b 5s always bed-root bed-root ├─ bed-1 777e343f-cc44-5964-850d-9302dbd591ee wasm [c]a157d28 3s — grow-bed bed-root/bed-1 ├─ bed-2 f1356c6d-8603-5fa5-a659-35764d15a3bf wasm [d]40df21c 3s — grow-bed bed-root/bed-2 ├─ bed-3 72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 wasm [c]a157d28 3s — grow-bed bed-root/bed-3 └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [4]f741c9b 3s — grow-bed bed-root/bed-4 ``` The root is on `node3`, every bed is back with a fresh `age` - including `bed-1` and `bed-3`, which ran on healthy nodes and were stopped with their old parent - and each bed stayed in its sector. Had Terminal 2 been on `myrmic subscribe bed_state` instead, it would have shown each bed announce itself as it started: ```text [2026-09-08T15:17:02.099Z] event=bed_state sender=777e343f-cc44-5964-850d-9302dbd591ee payload=27 bytes { "index": 1, "moisture": 55.0 } ``` The body is seconds old; the memory is from before the kill, read from one of the copies you asked for in Step 6. Bring the killed node back, with its own name and tag: ```bash myrmic runtimes start -n node1 --tag sectorA --detached ``` --- ## What Have You Learned - **A lost child is reported, not restarted.** The swarm sends the parent a `cell_lost` with the child's name and a reason; a `#[monitor]` handler decides. Respawn for `NodeLost` and `Crashed`; leave `Terminated`, `Stopped` and `SpawnFailed` alone. - **A child does not outlive its parent.** When the root's node dies, its runtime-hosted children are stopped within about a minute, on healthy nodes too, and no notification reaches anyone. The monitor handler cannot cover this case. - **The list rebuilds the tree.** `ensure` turns the root's list into running cells idempotently, and `init` schedules it on every start. Deleting and redeploying the application, or losing the root's node, both end with the same tree. - **A refused respawn is not final.** `ensure` and the monitor handler both fall back to a timer, so a bed whose sector is down comes back when the sector does. - **Never spawn in `init`.** A deploy waits for `init`; `init` must not wait for deploys. Schedule the work one second later. - **Copies first.** The root's list and the beds' moisture are cell state with one copy by default. `myrmic replicate` is what made the restarted root find its list and the respawned beds find their readings. - **Expect about a minute** for a dead node to be given up, then a second for the tree to be back. Next: [Part 3 - One Sensor per Bed](./03_one-sensor-per-bed.md), where every bed gets a sensor of its own. # Part 3 - One Sensor per Bed This is Part 3 of the [Scaling Your Application](../06_scaling.md) tutorial. You build a **sensor root** that spawns one mock sensor per probe, and you pair each bed with its own sensor - **learning how spawned cells find each other by name alone, and how a cell filters a broadcast event down to its partner.** It continues where [Part 2](./02_bringing-beds-back.md) left off: four runtimes, the root and four beds running, copies on every node. --- ## Step 10 - The Sensor Root Remember the end of Part 1: you published one `moisture` reading and every bed took it. Events are delivered by name, to every cell that handles that name, so with real sensors every bed would hear every probe in the greenhouse. A bed needs its own sensor, and it needs to ignore the others. First the sensors. The mock sensor from the Smart Greenhouse does exactly what a probe should - publish `moisture` once a second - and nothing in it changes. Copy it over, and scaffold the root that will spawn it: ```bash cp -r ../greenhouse/moisture-sensor . myrmic new sensor-root ``` The sensor root is the bed root of Part 2 with two words changed: it spawns the `moisture-sensor` class instead of `grow-bed`, and it calls its children `sensor-`. Everything else - the list, `ensure`, the retry, the monitor handler - is the same pattern doing the same job. Replace the content of `sensor-root/src/lib.rs` with: ```rust //! Sensor root: creates one moisture-sensor child per probe and brings lost sensors back. #![no_std] use core::time::Duration; use myrmic_sdk::db::state::State; use myrmic_sdk::monitor::{CellLost, LostReason}; use myrmic_sdk::{Callback, ClassHandle, Metadata, Result, SpawnError, String, Vec, format}; /// The class to spawn sensors from, resolved when the application is deployed. const SENSOR: ClassHandle = myrmic_sdk::declare!("moisture-sensor"); /// One sensor this root has created: its index and the sector it runs in. #[derive(serde::Serialize, serde::Deserialize)] struct Sensor { index: u32, sector: String, } /// The sensors this root has created. const SENSORS: State> = State::new_const("sensors"); /// Spawns `sensor-` on a node of `sector`. fn spawn_sensor(index: u32, sector: &str) -> core::result::Result<(), SpawnError> { SENSOR .new() .name(format!("sensor-{index}")) .tag(sector) .spawn() .map(|_| ()) } /// How long to wait before trying again when a sensor could not be spawned. const RETRY: Duration = Duration::from_secs(20); /// Runs `ensure` again after `RETRY`. fn retry_later() -> Result<()> { let _ = myrmic_sdk::delay(Callback::of::(), RETRY) .build() .map_err(|_| "timer failed")?; Ok(()) } /// Runs on every start of the root, the first deploy and every restart. /// Spawning is deploying and takes a moment, and the root is not up until /// `init` returns - so the rebuild is scheduled, not done here. #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { let _ = myrmic_sdk::delay(Callback::of::(), Duration::from_secs(1)) .build() .map_err(|_| "timer failed")?; Ok(()) } /// Timer target: makes sure every sensor in the list is running. A sensor that /// already runs is fine; a sensor that cannot be spawned right now is tried /// again later. #[myrmic_sdk::cmd] fn ensure(_md: Metadata) -> Result<()> { myrmic_sdk::info!("ensure: running")?; let mut missing = false; for sensor in SENSORS.load()?.unwrap_or_default() { match spawn_sensor(sensor.index, &sensor.sector) { Ok(()) => myrmic_sdk::info!("sensor-{} spawned", sensor.index)?, Err(SpawnError::AlreadyExists) => { myrmic_sdk::info!("sensor-{} already running", sensor.index)? } Err(err) => { myrmic_sdk::warn!("sensor-{} not running: {}", sensor.index, <&str>::from(err))?; missing = true; } } } if missing { retry_later()?; } Ok(()) } /// Creates the next sensor in a sector: `myrmic send sensor-root add_sensor '"sectorA"'`. #[myrmic_sdk::cmd] fn add_sensor(_md: Metadata, sector: String) -> Result<()> { let mut sensors = SENSORS.load()?.unwrap_or_default(); let index = sensors.last().map_or(1, |last| last.index + 1); // A failed handler is delivered again; a refused spawn should not be retried. if let Err(err) = spawn_sensor(index, §or) { myrmic_sdk::warn!( "sensor-{index} in '{sector}' refused: {}", <&str>::from(err) )?; return Ok(()); } sensors.push(Sensor { index, sector }); SENSORS.save(&sensors)?; myrmic_sdk::info!("added sensor-{index}")?; Ok(()) } /// The swarm tells a parent when one of its children is gone. #[myrmic_sdk::monitor] fn child_lost(_md: Metadata, loss: CellLost) -> Result<()> { // Only losses worth repairing: the node died, or the sensor crashed. if !matches!(loss.reason, LostReason::NodeLost | LostReason::Crashed) { return Ok(()); } let sensors = SENSORS.load()?.unwrap_or_default(); let name = loss.local_name.as_deref().unwrap_or(""); let Some(sensor) = sensors .iter() .find(|s| format!("sensor-{}", s.index) == name) else { return Ok(()); }; myrmic_sdk::warn!("{name} lost; respawning in '{}'", sensor.sector)?; if let Err(err) = spawn_sensor(sensor.index, &sensor.sector) { myrmic_sdk::warn!("{name} could not be respawned: {}", <&str>::from(err))?; retry_later()?; } Ok(()) } ``` One difference is worth a look: `spawn_sensor` passes no `.payload(...)`. The sensor's `init` declares no argument, and a cell that declares none must receive none, so the root hands it nothing. The sensor does not know which bed it feeds, and it does not need to. The pairing is the bed's business. --- ## Step 11 - The Bed Listens to One Sensor The pairing rule is the naming: `sensor-` feeds `bed-`. A child's identity is derived from its parent's name and its own, so `bed-3` can compute the identity of `sensor-root/sensor-3` from the index it was spawned with - nobody has to tell it. Three changes to `grow-bed/src/lib.rs`. Import `Sri` and `format`: ```rust use myrmic_sdk::{Metadata, Result, Sri, format, publish}; ``` Add a second piece of state, next to `BED`: ```rust /// The one sensor this bed listens to. const SENSOR: State = State::new_const("sensor"); ``` Compute and store it in `init`, before the bed's own state: ```rust let sensor = Sri::of_path(&format!("sensor-root/sensor-{index}")).map_err(|_| "bad name")?; SENSOR.save(&sensor)?; ``` And make the `moisture` handler check who is talking: ```rust #[myrmic_sdk::evt] fn moisture(md: Metadata, value: f32) -> Result<()> { if SENSOR.load()? != Some(md.sender) { return Ok(()); } ... ``` `md.sender` is the identity of the cell that published the event, stamped by the runtime - a sender cannot forge it. Every bed still receives every `moisture` event, because that is what a handler for `moisture` means; the bed returns early for all but its partner's. The complete file is at the end of this part. Why filter instead of listening to a per-bed event such as `moisture_3`? Because a cell's event handlers are fixed when it is compiled: `#[evt]` exports one function per event name, and the runtime discovers those exports when the cell is deployed. There is no runtime subscribe. The handler is where the choice is made. At tutorial scale the cost is one state read per bed per reading; at a thousand sensors it would be time to let the sensor *address* its bed instead, with a command to the bed's SRI, computed by the same naming rule. --- ## Step 12 - Deploy and Pair Two classes and one instance join `app_specs.yml`: ```yaml name: greenhouse classes: - id: bed-root build: ./bed-root - id: sensor-root build: ./sensor-root - id: grow-bed build: ./grow-bed - id: moisture-sensor build: ./moisture-sensor instances: - class: bed-root restart: always - class: sensor-root restart: always ``` Remove and deploy, as before: ```bash myrmic delete greenhouse --app myrmic deploy app_specs.yml myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ──────────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 9s always bed-root bed-root ├─ bed-1 777e343f-cc44-5964-850d-9302dbd591ee wasm [c]a157d28 8s — grow-bed bed-root/bed-1 ├─ bed-2 f1356c6d-8603-5fa5-a659-35764d15a3bf wasm [d]40df21c 8s — grow-bed bed-root/bed-2 ├─ bed-3 72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 wasm [1]12a7f3f 7s — grow-bed bed-root/bed-3 └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [4]f741c9b 7s — grow-bed bed-root/bed-4 sensor-root 904b6b3b-8411-5ff5-8f0d-56555e49b75e wasm [4]f741c9b 9s always sensor-root sensor-root ``` The four beds are back on their own, as in Part 2, now with the new grow-bed code; the sensor root is up with nothing under it. Give each bed its sensor, in the bed's sector: ```bash myrmic send sensor-root add_sensor '"sectorA"' myrmic send sensor-root add_sensor '"sectorB"' myrmic send sensor-root add_sensor '"sectorA"' myrmic send sensor-root add_sensor '"sectorB"' myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ──────────────────────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 15s always bed-root bed-root ├─ bed-1 777e343f-cc44-5964-850d-9302dbd591ee wasm [c]a157d28 14s — grow-bed bed-root/bed-1 ├─ bed-2 f1356c6d-8603-5fa5-a659-35764d15a3bf wasm [d]40df21c 14s — grow-bed bed-root/bed-2 ├─ bed-3 72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 wasm [1]12a7f3f 14s — grow-bed bed-root/bed-3 └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [4]f741c9b 14s — grow-bed bed-root/bed-4 sensor-root 904b6b3b-8411-5ff5-8f0d-56555e49b75e wasm [4]f741c9b 15s always sensor-root sensor-root ├─ sensor-1 152b9c54-519c-55e4-b828-ecc811f5325c wasm [c]a157d28 6s — moisture-sensor sensor-root/sensor-1 ├─ sensor-2 880e731a-aa75-5bab-9377-73b271c5643a wasm [d]40df21c 6s — moisture-sensor sensor-root/sensor-2 ├─ sensor-3 025bda92-5332-557a-a2a7-ef8d8933c4a5 wasm [1]12a7f3f 6s — moisture-sensor sensor-root/sensor-3 └─ sensor-4 b86e8291-adb5-55e3-b058-1352fc57b966 wasm [4]f741c9b 6s — moisture-sensor sensor-root/sensor-4 ``` Two trees now. The sensors sit in the sectors you asked for; whether a sensor shares a node with its bed is the swarm's choice and does not matter - the pairing is by name, not by place. Look at the beds in Terminal 2: ```bash myrmic subscribe bed_state ``` ```text [2026-09-08T18:56:12.734Z] event=bed_state sender=777e343f-cc44-5964-850d-9302dbd591ee payload=32 bytes { "index": 1, "moisture": 54.599945 } [2026-09-08T18:56:12.735Z] event=bed_state sender=f1356c6d-8603-5fa5-a659-35764d15a3bf payload=32 bytes { "index": 2, "moisture": 54.599945 } [2026-09-08T18:56:12.829Z] event=bed_state sender=72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 payload=32 bytes { "index": 3, "moisture": 54.599945 } [2026-09-08T18:56:13.677Z] event=bed_state sender=22bffd66-a421-5ddb-8f3e-6530c8fd010a payload=32 bytes { "index": 4, "moisture": 55.799946 } ``` Each bed reports once a second, when *its* sensor reads. The values are close because the four mock sensors started within the same second and follow the same simulated weather; what tells them apart is the timing, and the `sender`. Now do what you did at the end of Part 1 - play a sensor from the CLI: ```bash myrmic publish moisture 1.0 ``` Nothing. Terminal 2 keeps showing the sensors' readings, and no bed ever reports `1.0`. Every bed received the event - the CLI publishes like any other sender - and every bed dropped it, because the sender was not its partner. In Part 1 the same command moved all the beds at once. --- ## The Complete Code The grow-bed, as it stands after this part: ```rust //! Grow-bed asset: the canonical state of one bed of plants, fed by one sensor. #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Metadata, Result, Sri, format, publish}; /// What the bed knows - also the payload of the `bed_state` event. #[derive(serde::Serialize, serde::Deserialize, myrmic_sdk::Message)] struct Bed { index: u32, moisture: f32, } const BED: State = State::new_const("bed"); /// The one sensor this bed listens to. const SENSOR: State = State::new_const("sensor"); /// The bed root passes the bed's index when it spawns us. `sensor-` /// under `sensor-root` is our sensor, and its identity follows from the name. #[myrmic_sdk::init] fn init(_md: Metadata, index: u32) -> Result<()> { let sensor = Sri::of_path(&format!("sensor-root/sensor-{index}")).map_err(|_| "bad name")?; SENSOR.save(&sensor)?; let bed = BED.load()?.unwrap_or(Bed { index, moisture: 0.0, }); BED.save(&bed)?; publish("bed_state", &bed) } /// A new reading from any sensor: keep it only if it comes from ours. #[myrmic_sdk::evt] fn moisture(md: Metadata, value: f32) -> Result<()> { if SENSOR.load()? != Some(md.sender) { return Ok(()); } let mut bed = BED.load()?.ok_or("bed not initialised")?; bed.moisture = value; BED.save(&bed)?; publish("bed_state", &bed) } ``` The sensor, unchanged from the Smart Greenhouse: ```rust //! Mock soil-moisture sensor: publishes a `moisture` reading every second. //! The simulated moisture swings between a dry and a wet bound, the way real //! soil follows the weather. //! //! Part 1 of the Smart Greenhouse tutorial. #![no_std] use core::time::Duration; use myrmic_sdk::db::state::State; use myrmic_sdk::{Callback, Metadata, Result, publish}; /// Simulated soil moisture, in percent. const MOISTURE: State = State::new_const("moisture"); /// Direction of the swing: `true` while the simulated weather is wetting. const RISING: State = State::new_const("rising"); #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { MOISTURE.save(&65.0)?; // The handle could cancel the timer later; this sensor measures forever. let _ = myrmic_sdk::interval(Callback::of::(), Duration::from_secs(1)) .build() .map_err(|_| "timer failed")?; Ok(()) } /// Timer target: the simulation advances one step, then the reading is /// published. The value swings: it dries down to 50%, turns, wets up to 80%. #[myrmic_sdk::cmd] fn measure(_md: Metadata) -> Result<()> { let mut moisture = MOISTURE.load()?.unwrap_or(65.0); let mut rising = RISING.load()?.unwrap_or_default(); if moisture <= 50.0 { rising = true; } else if moisture >= 80.0 { rising = false; } let delta = if rising { 1.2 } else { -0.4 }; moisture = (moisture + delta).clamp(0.0, 100.0); MOISTURE.save(&moisture)?; RISING.save(&rising)?; publish("moisture", &moisture) } /// A rain shower adds a one-time amount of moisture. #[myrmic_sdk::evt] fn rain(_md: Metadata, amount: f32) -> Result<()> { let mut moisture = MOISTURE.load()?.unwrap_or(65.0); moisture = (moisture + amount).clamp(0.0, 100.0); MOISTURE.save(&moisture) } ``` --- ## What Have You Learned - **The same root pattern, twice.** A list, `spawn_`, `add_`, `ensure` with a retry, a monitor handler. The sensor root is the bed root with the class and the names changed. - **A child receives only what its `init` declares.** The sensor takes no payload, so the root passes none. - **Pairing by name.** `bed-3` derives the identity of `sensor-root/sensor-3` from its own index, with `Sri::of_path`. No configuration, no lookup, no message. - **Events are delivered by name; the handler chooses.** Handlers are fixed at compile time, so a cell narrows a broadcast by checking `md.sender`, which the runtime stamps. At large scale, an addressed command is the alternative. - **Redeploying the application rebuilt the beds by itself.** The roots' lists are in their state, and the state outlives the application. Next: [Part 4 - The Dashboard](./04_the-dashboard.md), where the greenhouse grows from a web page. # Part 1 - A Root That Spawns This is Part 1 of the [Scaling Your Application](../06_scaling.md) tutorial. You build a grow-bed that knows nothing but its own state, and a **bed root** that creates grow-beds on request, in the sector of the greenhouse you name. You spawn three beds from the CLI and see them as a tree in `myrmic cells` - **learning how one cell creates another, and where the new cell runs.** --- ## Step 1 - Start Four Runtimes Picture a greenhouse with two sectors, each with two computers. In Terminal 1: ```bash myrmic runtimes start -n node1 --tag sectorA --detached myrmic runtimes start -n node2 --tag sectorA --detached myrmic runtimes start -n node3 --tag sectorB --detached myrmic runtimes start -n node4 --tag sectorB --detached ``` Give them a few seconds to find each other: ```bash myrmic network status ``` ```text Discovered 4 node(s) # name kind id tags 0 node1 linux [1]12a7f3f sectorA, @112a7f3f15aa4f7ead00258a4c8c609a, linux 1 node2 linux [c]a157d28 sectorA, @ca157d28d8cf44689a97832a30327a8c, linux 2 node3 linux [4]f741c9b sectorB, @4f741c9b645144daa3d0e8776399c7bf, linux 3 node4 linux [d]40df21c sectorB, @d40df21caca94c98be184fee8a7645d3, linux ``` --- ## Step 2 - A New Workspace The cells of this tutorial start as simplified copies of the Smart Greenhouse cells and grow part by part, so they get a directory of their own: ```bash mkdir scaling && cd scaling myrmic new grow-bed myrmic new bed-root ``` --- ## Step 3 - The Grow-Bed The grow-bed is the asset from the Smart Greenhouse, reduced to what this part needs: a state and one event handler. Replace the content of `grow-bed/src/lib.rs` with: ```rust //! Grow-bed asset: the canonical state of one bed of plants. #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Metadata, Result, publish}; /// What the bed knows - also the payload of the `bed_state` event. #[derive(serde::Serialize, serde::Deserialize, myrmic_sdk::Message)] struct Bed { index: u32, moisture: f32, } const BED: State = State::new_const("bed"); /// The bed root passes the bed's index when it spawns us. #[myrmic_sdk::init] fn init(_md: Metadata, index: u32) -> Result<()> { let bed = BED.load()?.unwrap_or(Bed { index, moisture: 0.0, }); BED.save(&bed)?; publish("bed_state", &bed) } /// A new reading: remember it and announce the bed's state. #[myrmic_sdk::evt] fn moisture(_md: Metadata, value: f32) -> Result<()> { let mut bed = BED.load()?.ok_or("bed not initialised")?; bed.moisture = value; BED.save(&bed)?; publish("bed_state", &bed) } ``` One thing is new compared with the Smart Greenhouse grow-bed: `init` takes an argument. A cell that is *spawned* can be handed a value by the cell that spawns it, and the runtime decodes it into the type the handler declares - here a `u32`, the bed's index. The bed keeps it in its state so that its `bed_state` events say which bed is talking. The rest you know. `BED` is the bed's state, `moisture` is the handler for the sensor's event, and every change is announced on `bed_state`. --- ## Step 4 - The Bed Root So far every cell you deployed was a **root**: one line under `instances` in `app_specs.yml`, deployed by the CLI. Adding a bed meant editing the file and deploying again. The bed root moves that job into the swarm: it creates a grow-bed whenever it is asked to, in the sector it is asked for. Replace the content of `bed-root/src/lib.rs` with: ```rust //! Bed root: creates one grow-bed child per bed. #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{ClassHandle, Metadata, Result, SpawnError, String, Vec, format}; /// The class to spawn beds from, resolved when the application is deployed. const GROW_BED: ClassHandle = myrmic_sdk::declare!("grow-bed"); /// One bed this root has created: its index and the sector it runs in. #[derive(serde::Serialize, serde::Deserialize)] struct Bed { index: u32, sector: String, } /// The beds this root has created. const BEDS: State> = State::new_const("beds"); /// Spawns `bed-` on a node of `sector`. fn spawn_bed(index: u32, sector: &str) -> core::result::Result<(), SpawnError> { GROW_BED .new() .name(format!("bed-{index}")) .tag(sector) .payload(&index) .spawn() .map(|_| ()) } /// Creates the next bed in a sector: `myrmic send bed-root add_bed '"sectorA"'`. #[myrmic_sdk::cmd] fn add_bed(_md: Metadata, sector: String) -> Result<()> { let mut beds = BEDS.load()?.unwrap_or_default(); let index = beds.last().map_or(1, |last| last.index + 1); // A failed handler is delivered again; a refused spawn should not be retried. if let Err(err) = spawn_bed(index, §or) { myrmic_sdk::warn!("bed-{index} in '{sector}' refused: {}", <&str>::from(err))?; return Ok(()); } beds.push(Bed { index, sector }); BEDS.save(&beds)?; myrmic_sdk::info!("added bed-{index}")?; Ok(()) } ``` Three lines carry the idea. `declare!("grow-bed")` names the **class** to create beds from. A class is a deployed Wasm binary; the application registers it under the id `grow-bed` in the next step, and `myrmic deploy` patches the class's identity into the bed root's binary when the application is deployed. The root never contains the bed's code. `spawn_bed` creates one bed with `GROW_BED.new().name(...).tag(...).payload(...).spawn()`. `.name("bed-1")` gives the child a fixed name, and the child's identity is derived from its parent's identity and that name - `bed-root/bed-1` is the same cell every time, which matters in the next part. `.tag(sector)` is the placement requirement you know from the Resilience tutorial, now decided at runtime from the command's argument: the bed runs only on a node carrying that tag. `.payload(&index)` is the value the bed's `init` receives. The helper is worth its own function because the next part calls it from more than one place. `BEDS` is the root's memory: for every bed it created, the index and the sector. It is ordinary cell state, one small list, and it is what gives the next bed the next number. One habit to pick up right away: when the spawn fails, the handler logs a warning and returns `Ok`. A handler that returns an error is *not consumed* - the command is delivered again - and retrying a spawn that was just refused would not help. --- ## Step 5 - Deploy and Grow Create `scaling/app_specs.yml`: ```yaml name: greenhouse classes: - id: bed-root build: ./bed-root - id: grow-bed build: ./grow-bed instances: - class: bed-root restart: always ``` `grow-bed` appears under `classes` and not under `instances`: the application registers the class so that it can be spawned from, and deploys no bed of its own. The root gets `restart: always`, as every root in a real deployment should - if its runtime dies, the swarm brings it back. Deploy: ```bash myrmic deploy app_specs.yml myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ─────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 2s always bed-root bed-root ``` One root, no beds. The root has no tag requirement, so it landed wherever the swarm chose - `node1` here. Ask for three beds, two in sector A and one in sector B: ```bash myrmic send bed-root add_bed '"sectorA"' myrmic send bed-root add_bed '"sectorB"' myrmic send bed-root add_bed '"sectorA"' myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ───────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 3s always bed-root bed-root ├─ bed-1 777e343f-cc44-5964-850d-9302dbd591ee wasm [c]a157d28 3s — grow-bed bed-root/bed-1 ├─ bed-2 f1356c6d-8603-5fa5-a659-35764d15a3bf wasm [4]f741c9b 3s — grow-bed bed-root/bed-2 └─ bed-3 72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 wasm [1]12a7f3f 3s — grow-bed bed-root/bed-3 ``` `myrmic cells` draws a tree now. The beds hang under the root, and their SRNs are paths: `bed-root/bed-1`. Read the `runtime` column against the node table from Step 1: `bed-1` and `bed-3` asked for `sectorA` and sit on `node2` and `node1`; `bed-2` asked for `sectorB` and sits on `node3`. Your split inside a sector may differ; a bed never crosses into the other sector. And compare the two `policy` columns: the root says `always`, the beds say `—`. A spawned cell has no restart policy of its own - what happens to it when things go wrong is its parent's business, and a later part's subject. Ask for a bed in a sector that does not exist: ```bash myrmic send bed-root add_bed '"sectorC"' myrmic cells ``` Nothing changes: no node carries `sectorC`, the spawn is refused, the root logs a warning, and the list stays at three. The command was consumed all the same - that is the `return Ok(())` in the handler at work. Now give the beds something to remember. In Terminal 2, listen to them; in Terminal 1, play the sensor by hand: ```bash myrmic subscribe bed_state ``` ```bash myrmic publish moisture 42.5 ``` ```text [2026-09-08T14:00:15.112Z] event=bed_state sender=f1356c6d-8603-5fa5-a659-35764d15a3bf payload=27 bytes { "index": 2, "moisture": 42.5 } [2026-09-08T14:00:15.113Z] event=bed_state sender=777e343f-cc44-5964-850d-9302dbd591ee payload=27 bytes { "index": 1, "moisture": 42.5 } [2026-09-08T14:00:15.113Z] event=bed_state sender=72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 payload=27 bytes { "index": 3, "moisture": 42.5 } ``` Terminal 2 may first show a few older `bed_state` events - the ones the beds published when they started, with `"moisture": 0.0` - and on a fresh swarm the new readings can take up to half a minute to arrive while the storage for a brand-new event settles. If nothing comes, publish once more. All three beds answered, on three different nodes, and all three now hold 42.5. That is how events work: `moisture` is delivered to every cell with a `moisture` handler, wherever it runs. Each bed has its own state - the `sender` values are the beds' identities from the table above - but they all heard the same reading. In a real greenhouse each bed has its own sensor, and a bed should listen to its own. That is the next part's problem. --- ## What Have You Learned - A cell can **spawn** another cell from a class the application registered. `declare!` names the class, `.name()` fixes the child's identity, `.tag()` decides where it may run, `.payload()` hands it a value for `init`. - A placement tag can come from **user input at runtime**. The spec never said where the beds go; the command did. - A spawned cell shows up **under its parent** in `myrmic cells`, with a path for an SRN and no restart policy of its own. - The root **remembers what it created** in ordinary state; the platform does not keep that list for it. - A handler that returns an error is **delivered again** - return `Ok` after logging a failure that a retry cannot fix. - Events are delivered **by name**, to every cell that handles them, across nodes. Three beds, one reading. Next: [Part 2 - Bringing Beds Back](./02_bringing-beds-back.md), where nodes start dying. # Part 4 - The Dashboard This is the last part of the [Scaling Your Application](../06_scaling.md) tutorial. You put the greenhouse on a web page again - and this time the page has two inputs: one that adds a bed, one that adds a sensor, each in the sector you type - **learning how a browser sends commands into the swarm through the gateway.** It continues where [Part 3](./03_one-sensor-per-bed.md) left off: four beds, four sensors, both roots running. --- ## Step 13 - A Dashboard That Talks Back The Smart Greenhouse dashboard only *showed* the swarm: the cell mirrored an event into a JSON file, the gateway served the file, the page polled it. That half stays. The new half is the reverse direction: the page sends `add_bed` and `add_sensor` to the roots, through the same gateway. ```bash myrmic new dashboard ``` Replace the content of `dashboard/src/lib.rs` with: ```rust //! Dashboard adapter: serves the greenhouse page and relays its buttons to the roots. #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Metadata, Result, Vec, gateway}; /// Payload of a grow-bed's `bed_state` event. Declared here as well as in the /// grow-bed: cells share wire formats, not Rust types. #[derive(Clone, serde::Serialize, serde::Deserialize, myrmic_sdk::Message)] struct BedState { index: u32, moisture: f32, } /// The latest state of every bed heard from, by index. const BEDS: State> = State::new_const("beds"); #[myrmic_sdk::init] fn init(md: Metadata) -> Result<()> { gateway::assets(md.id).put("/index.html", include_bytes!("../assets/index.html"))?; gateway::mount("/greenhouse") .index("/index.html") // GET opens a session, POST sends a command: the page's two buttons. .api("/api") .bind() .map_err(<&'static str>::from)?; Ok(()) } /// Every `bed_state` refreshes that bed's entry and rewrites `beds.json`. #[myrmic_sdk::evt] fn bed_state(md: Metadata, bed: BedState) -> Result<()> { let mut beds = BEDS.load()?.unwrap_or_default(); match beds.iter_mut().find(|b| b.index == bed.index) { Some(slot) => *slot = bed, None => { beds.push(bed); beds.sort_by_key(|b| b.index); } } BEDS.save(&beds)?; let json = serde_json::to_vec(&beds).map_err(|_| "json")?; gateway::assets(md.id).put("/beds.json", &json) } ``` Two things differ from the Smart Greenhouse dashboard. The read model is a list, one entry per bed, because there are many beds now; every `bed_state` replaces its bed's entry and rewrites `beds.json`. And the mount gains `.api("/api")`: a path on which the gateway accepts messages from the browser and drops them into cells' mailboxes. The cell does nothing for that path - it only declares it. Add `serde_json` to `dashboard/Cargo.toml`, and give the cell the memory a baked-in page needs: ```toml [package.metadata.myrmic] heap_size = 65_536 initial_memory = 262_144 max_memory = 262_144 [dependencies] myrmic-sdk = ... # as generated serde = { version = "1", default-features = false, features = ["alloc", "derive"] } serde_json = { version = "1", default-features = false, features = ["alloc"] } ``` Now the page. Create `dashboard/assets/index.html` with: ```html Smart Greenhouse

Smart Greenhouse

connecting to the gateway...

``` The reading half is the Smart Greenhouse loop, polling `beds.json` every two seconds. The writing half is new, and worth following once: 1. `GET /greenhouse/api` opens a stream. Its first message is `{"type":"ready","session":"..."}`: the gateway has created a **session** for this browser tab. While the stream is open, the session is alive. 2. A command is a `POST` to the same path, with the session id in the `X-Gateway-Session` header and a small JSON envelope: the target cell as an SRN, the command name, and the payload as base64. The payload itself is what `myrmic send` would take - here the JSON string `"sectorA"`. 3. The gateway resolves the SRN, checks that the cell exists, and puts the command in its mailbox. The response is `202 Accepted`; the command runs in the swarm, and the page learns the outcome the same way anyone does - by watching the swarm change. The page names its targets `bed-root` and `sensor-root`. It can, because they are roots with fixed names from `app_specs.yml`; it never handles a UUID. --- ## Step 14 - Grow the Greenhouse From the Browser Add the dashboard to `app_specs.yml` - a class and a root instance: ```yaml - id: dashboard build: ./dashboard ``` ```yaml - class: dashboard restart: always ``` Remove and deploy, and start the gateway in Terminal 3 and leave it running: ```bash myrmic delete greenhouse --app myrmic deploy app_specs.yml ``` ```bash myrmic gateway ``` ```bash myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ──────────────────────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 11s always bed-root bed-root ├─ bed-1 777e343f-cc44-5964-850d-9302dbd591ee wasm [1]12a7f3f 10s — grow-bed bed-root/bed-1 ├─ bed-2 f1356c6d-8603-5fa5-a659-35764d15a3bf wasm [d]40df21c 9s — grow-bed bed-root/bed-2 ├─ bed-3 72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 wasm [c]a157d28 9s — grow-bed bed-root/bed-3 └─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [4]f741c9b 9s — grow-bed bed-root/bed-4 dashboard 884f63a0-83ed-52fe-b67c-2bcfb6df378c wasm [c]a157d28 11s always dashboard dashboard sensor-root 904b6b3b-8411-5ff5-8f0d-56555e49b75e wasm [4]f741c9b 11s always sensor-root sensor-root ├─ sensor-1 152b9c54-519c-55e4-b828-ecc811f5325c wasm [1]12a7f3f 10s — moisture-sensor sensor-root/sensor-1 ├─ sensor-2 880e731a-aa75-5bab-9377-73b271c5643a wasm [d]40df21c 10s — moisture-sensor sensor-root/sensor-2 ├─ sensor-3 025bda92-5332-557a-a2a7-ef8d8933c4a5 wasm [c]a157d28 9s — moisture-sensor sensor-root/sensor-3 └─ sensor-4 b86e8291-adb5-55e3-b058-1352fc57b966 wasm [4]f741c9b 9s — moisture-sensor sensor-root/sensor-4 ``` Both trees came back on their own, as they do by now, and the dashboard is a third root. Open the browser: ```text http://localhost:8080/greenhouse/ ``` Four bed cards with moving readings, and below them the two forms. Type `sectorB` into both, press **Add bed**, then **Add sensor**. A fifth card appears saying *no sensor yet*; a few seconds later it shows a reading. In Terminal 1: ```bash myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ──────────────────────────────────────────────────────────────────────────────────────────────────────── bed-root ec2709f8-5e11-5ca8-a152-5d195d73a00a wasm [1]12a7f3f 25s always bed-root bed-root ├─ bed-1 777e343f-cc44-5964-850d-9302dbd591ee wasm [1]12a7f3f 24s — grow-bed bed-root/bed-1 ├─ bed-2 f1356c6d-8603-5fa5-a659-35764d15a3bf wasm [d]40df21c 24s — grow-bed bed-root/bed-2 ├─ bed-3 72fdd5d5-ca6b-54af-b017-c624f8b8b1d7 wasm [c]a157d28 24s — grow-bed bed-root/bed-3 ├─ bed-4 22bffd66-a421-5ddb-8f3e-6530c8fd010a wasm [4]f741c9b 23s — grow-bed bed-root/bed-4 └─ bed-5 a8e580cb-81d5-595e-b715-452ca176e4b6 wasm [d]40df21c 11s — grow-bed bed-root/bed-5 dashboard 884f63a0-83ed-52fe-b67c-2bcfb6df378c wasm [c]a157d28 25s always dashboard dashboard sensor-root 904b6b3b-8411-5ff5-8f0d-56555e49b75e wasm [4]f741c9b 25s always sensor-root sensor-root ├─ sensor-1 152b9c54-519c-55e4-b828-ecc811f5325c wasm [1]12a7f3f 24s — moisture-sensor sensor-root/sensor-1 ├─ sensor-2 880e731a-aa75-5bab-9377-73b271c5643a wasm [d]40df21c 24s — moisture-sensor sensor-root/sensor-2 ├─ sensor-3 025bda92-5332-557a-a2a7-ef8d8933c4a5 wasm [c]a157d28 24s — moisture-sensor sensor-root/sensor-3 ├─ sensor-4 b86e8291-adb5-55e3-b058-1352fc57b966 wasm [4]f741c9b 23s — moisture-sensor sensor-root/sensor-4 └─ sensor-5 3bc2a4a0-90f6-523c-b9d7-b2d93278c3d7 wasm [4]f741c9b 7s — moisture-sensor sensor-root/sensor-5 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── — 2b2ae79a-589a-42de-966d-a0c0c6920890 N/A — 14s — — — ``` `bed-5` and `sensor-5`, both in sector B, both created from a browser. The button went browser → gateway → `bed-root`'s mailbox → `add_bed` → `spawn_bed`: the same path `myrmic send` took in Part 1, with a different client at the front. The nameless row below the rule is your browser tab: the gateway registers each open session as a placeholder cell so that cells can address replies to it, and the row disappears half a minute or so after the tab is closed. And the file the page polls now has five entries: ```text [{"index":1,"moisture":55.399963},{"index":2,"moisture":54.99996},{"index":3,"moisture":55.399963},{"index":4,"moisture":55.399963},{"index":5,"moisture":62.19999}] ``` Everything you did in Parts 1 to 3 still holds for beds made this way. Kill the node under `bed-5` and the bed root brings it back; kill the node under the bed root and the list, now with five entries, rebuilds the tree. --- ## Step 15 - Clean Up ```bash myrmic delete greenhouse --app myrmic replicate app:greenhouse -e linux myrmic telemetry no-db-retention myrmic runtimes delete node1 node2 node3 node4 ``` Stop the gateway with Ctrl-C in Terminal 3. --- ## What Have You Built A greenhouse that grows while it runs: - Two **roots that spawn** - one for beds, one for sensors - each remembering a short list and turning it into running cells: on request, after a loss, and after their own restart. - **Children with fixed identities**, so that a respawn is a resume and a bed can find its sensor by name alone. - **Placement from user input**: the sector typed into a command or a form decides where the new cell runs. - A **dashboard that talks back**, sending commands to cells it names by SRN through the gateway. The layout of the greenhouse - how many beds, how many sensors, which sector - is nowhere in `app_specs.yml`. It lives in the roots' state, replicated, and the swarm rebuilds it from there. ## What Have You Learned - A page reaches the swarm through the gateway's **API path**: `GET` opens a session, `POST` sends an envelope with the target's SRN, the command name and a base64 payload. - The gateway does for the browser what `myrmic send` does for the terminal: it drops a command into a mailbox. Nothing in the cells knows the difference. - An open browser session is visible in `myrmic cells` as a placeholder row. - Spawning, respawning and rebuilding do not care who asked. A bed added from a form is a bed like any other. > **Preview version.** Everything in this tutorial is supervision done *by your code* with the primitives available today: fixed names, `on_cell_lost`, a list in state, `myrmic replicate`. A restart policy applies to roots only, and none of this is yet part of the [guarantee contract](../../08_guarantees.md). The [Roadmap](../../09_roadmap.md) describes how supervising a tree becomes something the swarm does by itself. ## Where to Go Next - [Cell classes and spawning](../../10_reference/03_myrmic-sdk/04_cell-lifecycle/01_cell-classes-and-spawning.md) and [Cell monitoring](../../10_reference/03_myrmic-sdk/04_cell-lifecycle/03_cell-monitoring.md) - every spawn option, every loss reason. - [Gateway routes](../../10_reference/03_myrmic-sdk/06_external-systems/01_gateway-routes.md) - the API and WebSocket paths. - [`myrmic replicate`](../../10_reference/02_myrmic-cli/15_replicate.md) - replicating an application, a cell, or a scope. - [Failure Behaviour](../../07_architecture/04_failure-behaviour.md) - what happens when a node is lost, in detail. # Smart Greenhouse In this tutorial you build a complete Myrmic application on a single computer: a smart greenhouse that keeps the soil of a grow bed inside a target moisture range - and a live web dashboard to watch it work. You will write five cells, wire them together with events and commands, and drive the whole thing from the Myrmic CLI. Along the way you will use most of the CLI's day-to-day functionality: scaffolding, building, deploying, listing cells, sending commands, publishing and subscribing to events, serving a web frontend through the gateway, reading logs, and tearing everything down again. No hardware is required - the sensor is mocked in software. ## What You Will Build Five cells, one per role: | Cell | Pattern | Responsibility | |---|---|---| | `moisture-sensor` | Adapter (mocked) | Publishes a `moisture` reading every second. The mock value swings between dry and wet, standing in for real weather and soil physics. | | `pump` | Adapter (actuator) | Accepts `start` / `stop` commands and announces its state on the `pump_state` event. Knows nothing about plants or policy. | | `grow-bed` | Asset | Owns the canonical state of one bed of plants: latest moisture, pump status, and the moisture range the plants want. Announces every change on the `bed_state` event. | | `dashboard` | Adapter (gateway) | Mirrors `bed_state` into a JSON snapshot and serves the web page at `/greenhouse` through the gateway. Owns no truth, makes no decisions. | | `irrigation-agent` | Agent | The only cell that makes decisions: reads the bed's `bed_state` and drives the pump with hysteresis. | The roles follow the [cell patterns](../06_concepts/07_cell-patterns.md): **assets own state, adapters own actuation, agents own decisions**. The layering is strict: the raw `moisture` event is a detail of the sensor adapter, consumed only by the asset; everyone else - the agent included - reads the grow-bed's canonical `bed_state`. Nothing commands the pump except the agent, and the grow-bed commands nothing at all - if you later reuse it in an application without irrigation, it carries no dead weight. And the sensor and the pump do not know each other at all: in the real world they are connected by soil and water, not by software. ```text moisture (event) bed_state (event) moisture-sensor ──────────────► grow-bed ────────┬────────► irrigation-agent (canonical state) │ │ ▲ ▼ │ pump_state (event)│ dashboard │ start / stop │ │ latest.json │ (commands) │ ▼ │ │ myrmic gateway ◄─ browser│ pump ◄──────────────────────────┘ ``` To facilitate the visualization and understanding, we will use several terminals: | Terminal | Runs | |---|---| | Terminal 1 | the Myrmic runtime | | Terminal 2 | your working shell: scaffold, build, deploy, send | | Terminal 3 | `myrmic subscribe` - a live view of the events flying around | | Terminal 4 | the gateway | ## Prerequisites - The Myrmic CLI installed and the Rust toolchain set up - complete the [Quickstart](../01_quickstart.md) first if you have not. - A web browser. ## Tutorial Parts 1. [The Mock Sensor](./01_smart-greenhouse/01_the-mock-sensor.md) - start the runtime, scaffold your first cell, and build a mock sensor - **learning how cells publish and subscribe to events.** 2. [The Pump](./01_smart-greenhouse/02_the-pump.md) - build the actuator that waters the bed - **learning how to use cell commands.** 3. [The Grow-Bed](./01_smart-greenhouse/03_the-grow-bed.md) - build the Asset Cell that owns the bed's canonical state - **learning how to model and share structured state.** 4. [The Irrigation Agent](./01_smart-greenhouse/04_the-irrigation-agent.md) - automate the watering decision - **learning how cells send commands to each other.** 5. [The Dashboard](./01_smart-greenhouse/05_the-dashboard.md) - put the bed on a web page served through the gateway - **learning how cells face the browser.** 6. [The Finale](./01_smart-greenhouse/06_the-finale.md) - play with the swarm, tear it down, and bring it all back with one command - **learning how `app_specs.yml` ships an application as one unit.** The complete code of the tutorial can be found in the Myrmic repository on GitHub at [`examples/greenhouse`](https://github.com/peeriot/myrmic/tree/master/examples/greenhouse). Reach for it if you get stuck or something does not behave as expected - but building it yourself is the point of the tutorial. # Part 5 - The Dashboard This is Part 5 of the [Smart Greenhouse](../01_smart-greenhouse.md) tutorial. You put the bed in the browser - learning how a cell serves a web page through the gateway. It continues where [Part 4](./04_the-irrigation-agent.md) left off: all four cells are deployed and the greenhouse is watering itself. --- ## Step 7 - The Dashboard Everything the greenhouse knows still lives inside the swarm - and browsers do not speak what the swarm speaks, they speak HTTP. The bridge between the two worlds is the myrmic **gateway**: an HTTP server that cells register their routes on. To put the bed on a web page we build one more cell, following the same pattern as the pump: an adapter. The pump adapts a motor; the dashboard, along with the gateway, adapts the browser. One thing to be clear about up front: the dashboard cell does not *run* the gateway. The gateway is its own process (it gets Terminal 4 in a moment); the cell registers its routes on it and fills the store the gateway serves from. Tear the cell down and its routes and files disappear with it - the gateway keeps running. ```bash myrmic new dashboard ``` Replace the content of `dashboard/src/lib.rs` with: ```rust //! Dashboard adapter: serves the greenhouse web page through the gateway. //! It mirrors the grow-bed's `bed_state` into a small JSON snapshot that the //! page polls. It owns no truth and makes no decisions. #![no_std] use myrmic_sdk::{Metadata, Result, format, gateway}; /// Payload of the grow-bed's `bed_state` event. #[derive(serde::Serialize, serde::Deserialize, myrmic_sdk::Message)] struct BedState { moisture: f32, pump_on: bool, target_low: f32, target_high: f32, } #[myrmic_sdk::init] fn init(md: Metadata) -> Result<()> { gateway::assets(md.id).put("/index.html", include_bytes!("../assets/index.html"))?; gateway::mount("/greenhouse") .index("/index.html") .bind() .map_err(<&'static str>::from)?; Ok(()) } /// Every `bed_state` update becomes a fresh `latest.json` for the page to poll. #[myrmic_sdk::evt] fn bed_state(md: Metadata, bed: BedState) -> Result<()> { let json = format!( r#"{{"moisture":{:.1},"pump_on":{},"target_low":{},"target_high":{}}}"#, bed.moisture, bed.pump_on, bed.target_low, bed.target_high ); gateway::assets(md.id).put("/latest.json", json.as_bytes()) } ``` Reading it top to bottom: - The cell declares its *own* `BedState` struct matching the event's JSON fields - cells share wire formats, not Rust types. Each side owns its definition. - `gateway::assets(md.id)` - the cell's private blob store for static files. Anything written there is served by the gateway once the cell mounts a route. At init the cell uploads the web page into it. - `gateway::mount("/greenhouse")` - claims the URL prefix on the gateway. `.index("/index.html")` serves that file at the mount root and enables static serving for everything else in the store. See the [gateway reference](../../10_reference/02_myrmic-cli/10_gateway.md) for the full mount API (APIs, WebSockets, fallbacks). - The `bed_state` handler is the whole application logic of this cell: every announcement from the asset is rewritten as `latest.json` in the store. The file is a *read model* - a derived copy optimized for display. The truth stays in the grow-bed; delete this cell and no information is lost. Now create the web page at `dashboard/assets/index.html`: ```html Smart Greenhouse

Smart Greenhouse - Grow Bed 1

Soil moisture: --%
Pump: --
Target range: --
``` The page is deliberately plain: a loop that fetches `latest.json` every 2 seconds and writes the values into the DOM. No framework, no build step. One thing to know before deploying: `include_bytes!` bakes the page into the Wasm binary, and a cell's memory is a fixed budget declared in its `Cargo.toml`. Our small page still fits the default budget - but if yours grows (more markup, some CSS, an embedded image), the build stops with: ```text rust-lld: error: initial memory too small, bytes needed ``` If that happens, give the cell more room in `dashboard/Cargo.toml`: ```toml [package.metadata.myrmic] heap_size = 65_536 initial_memory = 262_144 max_memory = 262_144 ``` See [Cell and application configuration](../../10_reference/01_configuration/02_cell-and-application-configuration.md) for what these values mean. Now deploy: ```bash myrmic deploy dashboard ``` Time to open the doors. The gateway is the swarm's HTTP entry point - start it in Terminal 4 and leave it running: ```bash myrmic gateway ``` The default port is 8080 (`--port` changes it). Open your browser at: ```text http://localhost:8080/greenhouse/ ``` There is the bed: the moisture value updating as the mock's weather swings, the target range from the asset, the pump state. And the page is not just showing the weather - watch long enough and you will see Part 4's agent at work: the pump indicator flipping to RUNNING at the low target and off again at the high one, with nobody at the keyboard. Follow the data on its round trip: sensor → `moisture` event → grow-bed → `bed_state` event → dashboard → `latest.json` in its store → gateway → HTTP → browser. No cell ever runs a web server; the dashboard just writes files and the gateway serves them. --- ## What Have You Learned - The gateway is the swarm's HTTP entry point. Cells do not run it - they register routes on it, and the routes and files live and die with the cell. - `gateway::assets(...)` is a per-cell blob store; whatever a cell writes there, the gateway serves over HTTP once the cell mounts a route with `.index(...)` or `.assets()`. - A dashboard keeps a *read model*: a derived copy of the asset's state, optimized for display. The truth stays in the asset - deleting the dashboard loses nothing. - `include_bytes!` bakes files into the Wasm binary - and larger binaries need more memory, configured in `[package.metadata.myrmic]`. ## Next Step The greenhouse is complete: measured, remembered, decided, displayed. In [Part 6 - The Finale](./06_the-finale.md) you play with the running system, tear it down, and bring it all back with a single command. # Part 6 - The Finale This is the last part of the [Smart Greenhouse](../01_smart-greenhouse.md) tutorial. You play with the running system, tear it down - and then bring the whole application back with a single command, learning how `app_specs.yml` binds five cells into one deployable unit. --- ## Step 8 - Play with the Swarm Everything is event-driven, so you can perturb the system from the CLI and watch the cells react - in Terminal 3 and in the browser at the same time. Point Terminal 3 at the interesting events: ```bash myrmic subscribe bed_state,watering_started,watering_stopped ``` **Let it rain.** Publish a `rain` event, like in Part 1: ```bash myrmic publish rain 20 ``` The sensor adds 20 percentage points on the next tick. If the pump was running, the agent notices the jump past the high target and shuts it off - watch `watering_stopped` arrive in Terminal 3 and the pump indicator go off in the browser. **Replant the bed.** Tell the grow-bed its new plants want wetter soil: ```bash myrmic send grow-bed set_target '{"low": 65, "high": 78}' ``` The grow-bed stores the new range and announces it on `bed_state`, and both subscribers react at once: the dashboard shows the new targets, and the agent - seeing the bed below its new low - starts the pump within a tick or two. One command, four cells involved, all visible in the browser. Curious what else is flying around? Subscribe to everything: ```bash myrmic subscribe ``` --- ## Step 9 - Tear It All Down Before the finale, a look behind the curtain. Every deployed cell came from a *class* - the built Wasm binary, content-addressed by hash: ```bash myrmic cells classes list ``` Now dismantle the greenhouse, cell by cell. `teardown` removes a cell and, with `--remove-class`, its class: ```bash myrmic cells teardown irrigation-agent --remove-class myrmic cells teardown dashboard --remove-class myrmic cells teardown grow-bed --remove-class myrmic cells teardown pump --remove-class myrmic cells teardown moisture-sensor --remove-class ``` Note the order: the agent goes first. It is the only cell that *acts*, so removing it first leaves nothing sending surprise commands while the rest is dismantled. Verify the swarm is empty: ```bash myrmic cells ``` ```text No cells registered ``` Leave the runtime and the gateway running - we are not done. --- ## Step 10 - One File, One Command You built the greenhouse the developer's way: five times `myrmic new`, five deploys, one cell at a time, watching each piece come alive. But that is not how an application ships. An application is one unit - and Myrmic describes it in one file: the **application specification**. Create `app_specs.yml` in the `greenhouse/` directory, next to the five crates: ```yaml name: greenhouse classes: - id: moisture-sensor build: ./moisture-sensor - id: pump build: ./pump - id: grow-bed build: ./grow-bed - id: dashboard build: ./dashboard - id: irrigation-agent build: ./irrigation-agent instances: - class: moisture-sensor - class: pump - class: grow-bed - class: dashboard - class: irrigation-agent ``` `classes` says what to build, `instances` says what to run. An instance's SRN defaults to its class id - which is why the agent still finds the pump under the name `pump`. The same file can also pin platforms, pass init arguments, place cells on specific runtimes via tags, or run several instances of one class - see [Cell and application configuration](../../10_reference/01_configuration/02_cell-and-application-configuration.md). Now resurrect the entire greenhouse with one command: ```bash myrmic deploy app_specs.yml ``` The CLI builds all five cells and deploys them as the application `greenhouse`. Look at the swarm: ```bash myrmic cells ``` ```text cell sri kind runtime age policy class srn ──── greenhouse ────────────────────────────────────────────────────────────────────────────── dashboard 884f... wasm [8]30d3436 20s never dashboard dashboard grow-bed fd02... wasm [8]30d3436 20s never grow-bed grow-bed irrigation-agent 9f21... wasm [8]30d3436 20s never irrigation-agent irrigation-agent moisture-sensor 365d... wasm [8]30d3436 20s never moisture-sensor moisture-sensor pump 4e9b... wasm [8]30d3436 20s never pump pump ``` Press Ctrl-C to leave the live view. The five cells are grouped under one application name now. Refresh the browser: the dashboard is back, the readings tick, and within a couple of minutes the agent waters the bed - the whole machine, from one file. And because the swarm knows the five belong together, they also leave together: ```bash myrmic delete greenhouse --app ``` ```text INFO deleted application 'greenhouse' ``` That is the full circle. Stop the gateway (Ctrl-C in Terminal 4) and the runtime: ```bash myrmic runtimes stop ``` --- ## What Have You Built Five cells, four patterns, one application: - A **mock sensor** (adapter) that publishes events on the runtime's scheduler. - A **pump** (adapter) that exposes commands and announces its state. - A **grow-bed** (asset) that owns the canonical state and shares it as structured events. - An **irrigation agent** that holds all the business logic and commands the pump. - A **dashboard** (adapter, gateway) that puts the bed in the browser. Along the way you used the CLI as a full participant in the swarm - publishing, subscribing, sending commands, reading logs - and finished by shipping the whole thing as one unit. Every piece was deployed, evolved, and redeployed while the rest kept running: that is the everyday feel of developing on a swarm. ## Where to Go Next - **Watch the swarm's internals** - traces of every command hop, including the agent's decisions, in the [Observability tutorial](../07_observability.md). - **A richer gateway frontend** - the dashboard here polls a static file; the gateway also streams events to the browser and accepts commands from it. See the [gateway reference](../../10_reference/02_myrmic-cli/10_gateway.md) and the `chatty` example in the repository. - **Revisit the patterns** - the [cell patterns](../../06_concepts/07_cell-patterns.md) page names what you just practiced: assets own state, adapters own actuation, agents own decisions. # Part 3 - The Grow-Bed This is Part 3 of the [Smart Greenhouse](../01_smart-greenhouse.md) tutorial. You build the **Asset Cell** that owns the canonical state of the bed - learning how to model structured state and share it on the network. It continues where [Part 2](./02_the-pump.md) left off: the runtime is running in Terminal 1, the sensor and the pump are deployed, and Terminal 3 is your event window. --- ## Step 5 - Create the Grow-Bed The swarm now has two devices talking - and a question nobody can answer: *how is grow bed 1 doing?* The sensor knows a number, the pump knows a motor; neither knows the bed. This is what the **Asset** pattern is for: one cell owns the canonical state of one real-world thing. Everyone who wants to know about the bed asks the bed - never the sensor. That indirection is what lets you later swap the mock for real hardware, or average three sensors into one bed, without touching anything downstream. The [cell patterns](../../06_concepts/07_cell-patterns.md) concept page describes the full family. Scaffold the third cell: ```bash myrmic new grow-bed ``` Replace the content of `grow-bed/src/lib.rs` with: ```rust //! Grow-bed asset: owns the canonical state of one bed of plants - the latest //! moisture reading, the pump status, and the moisture range the plants want. //! Every change is announced on the `bed_state` event. It commands nothing: //! actuation belongs to the pump adapter, decisions to the irrigation agent. #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Metadata, Result, publish}; /// Canonical state of the bed - also the payload of the `bed_state` event. #[derive(serde::Serialize, serde::Deserialize, myrmic_sdk::Message)] struct Bed { moisture: f32, pump_on: bool, target_low: f32, target_high: f32, } impl Default for Bed { fn default() -> Self { Self { moisture: 0.0, pump_on: false, target_low: 55.0, target_high: 75.0, } } } const BED: State = State::new_const("bed"); /// The moisture range the plants in this bed want, settable at runtime. #[derive(serde::Serialize, serde::Deserialize, myrmic_sdk::Message)] struct TargetRange { low: f32, high: f32, } #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { // Seed the default only on first deploy; a redeployed bed keeps its state. if BED.load()?.is_none() { BED.save(&Bed::default())?; } Ok(()) } /// A new sensor reading: update the canonical state and announce it. #[myrmic_sdk::evt] fn moisture(_md: Metadata, value: f32) -> Result<()> { let mut bed = BED.load()?.unwrap_or_default(); bed.moisture = value; BED.save(&bed)?; publish("bed_state", &bed) } /// The pump announced a state change: record and announce it. #[myrmic_sdk::evt] fn pump_state(_md: Metadata, on: bool) -> Result<()> { let mut bed = BED.load()?.unwrap_or_default(); bed.pump_on = on; BED.save(&bed)?; publish("bed_state", &bed) } /// Domain command: this bed now grows plants that want a different range. #[myrmic_sdk::cmd] fn set_target(_md: Metadata, range: TargetRange) -> Result<()> { let mut bed = BED.load()?.unwrap_or_default(); bed.target_low = range.low; bed.target_high = range.high; BED.save(&bed)?; publish("bed_state", &bed) } ``` Reading it top to bottom: - `#[derive(..., myrmic_sdk::Message)]` - the `Message` derive gives a struct a wire encoding (JSON by default), so it can travel as an event or command payload. The [Message Encoding](../../05_guides/04_message-encoding.md) guide covers the codecs. - `State` - the same persistent state you know from Parts 1 and 2, now holding a struct. The [State and Storage](../../05_guides/06_state-and-storage.md) guide shows what else the cell database offers (key-value trees, tables). - The two `#[evt]` handlers are where the asset earns its keep: it listens to the adapters, folds their raw signals into one canonical picture, and announces every change on `bed_state`. From here on, the raw `moisture` event is a detail between the sensor and the asset - everyone else reads `bed_state`. - `set_target` is the bed's only command, and it is a *domain* command: it exists because the bed can be replanted with plants that want a different range. Watering is deliberately not here - a bed of plants does not water itself. Deploy it and check the swarm: ```bash myrmic deploy grow-bed myrmic cells ``` Three cells now. Point Terminal 3 at the asset's announcements: ```bash myrmic subscribe bed_state ``` Expected output (one per sensor tick - and structs arrive as readable JSON): ```text [2026-08-26T17:51:06.487Z] event=bed_state sender=fd02ce9b-... payload=75 bytes { "moisture": 63.399994, "pump_on": false, "target_high": 75.0, "target_low": 55.0 } ``` Now replant the bed. `myrmic send` accepts a JSON payload, and the cell decodes it straight into the typed `TargetRange`: ```bash myrmic send grow-bed set_target '{"low": 65, "high": 78}' ``` Watch Terminal 3: the very next `bed_state` carries the new targets. One thing that changed, one place that knows it, everyone informed. --- ## What Have You Learned - The **Asset** pattern: one cell owns the canonical state of one real-world thing. Consumers read the asset, not the device adapters - so devices can be swapped without touching anything downstream. - `State` holds structs as easily as scalars; struct state needs `serde` with `default-features = false`, because cells are `no_std`. - The `myrmic_sdk::Message` derive gives a struct a wire encoding (JSON by default), so events and commands can carry structured payloads. - `myrmic send` takes a JSON payload - `'{"low": 65, "high": 78}'` - and the receiving handler gets it as a typed struct. - An asset folds raw device signals into one canonical picture and announces every change as an event of its own. ## Next Step The bed now knows how it is doing and what it wants - but nobody acts on it yet. In [Part 4 - The Irrigation Agent](./04_the-irrigation-agent.md) we hire the decision-maker. # Part 4 - The Irrigation Agent This is Part 4 of the [Smart Greenhouse](../01_smart-greenhouse.md) tutorial. You automate the watering decision - learning how cells send commands to each other, and where an application's business logic belongs. It continues where [Part 3](./03_the-grow-bed.md) left off: the runtime is running in Terminal 1, the sensor, the pump, and the grow-bed are deployed, and Terminal 3 is your event window. --- ## Step 6 - Create the Irrigation Agent Part 2 ended with a job offer: someone has to watch the moisture and drive the pump, and so far that someone is you. Time to delegate. The **Agent** pattern is where decisions live: a cell that evaluates conditions and issues commands - and the *only* place in the application that does. The division of labor is now complete: sensors measure, assets remember, adapters act, agents decide. Keeping all business logic in one cell means you can later replace the watering policy - smarter scheduling, weather forecasts, machine learning - by swapping a single cell, while sensor, pump, and grow-bed stay untouched. The [cell patterns](../../06_concepts/07_cell-patterns.md) page describes the full family. Our policy is deliberately simple, but it is a real controller's policy: **hysteresis**. Two thresholds instead of one - start watering when the bed's moisture drops below its low target, stop only when it climbs above the high one. The gap between them keeps the pump from chattering on and off around a single set point. And note what the agent reads: the grow-bed's `bed_state` - never the raw sensor. The bed's state already carries the target range, so the agent stores almost nothing itself: just a flag remembering whether it is mid-watering. ```bash myrmic new irrigation-agent ``` Replace the content of `irrigation-agent/src/lib.rs` with: ```rust //! Irrigation agent: the only cell that makes decisions. It reads the //! grow-bed's canonical state - never the raw sensor - and drives the pump //! adapter with hysteresis: start below the bed's low target, stop above the //! high one, so the pump never chatters around a single set point. #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Metadata, Result, Sri, Void, publish, send}; const PUMP: &str = "pump"; /// Hysteresis flag: are we in the middle of a watering cycle? const WATERING: State = State::new_const("watering"); /// Payload of the grow-bed's `bed_state` event. #[derive(serde::Serialize, serde::Deserialize, myrmic_sdk::Message)] struct BedState { moisture: f32, pump_on: bool, target_low: f32, target_high: f32, } #[myrmic_sdk::evt] fn bed_state(_md: Metadata, bed: BedState) -> Result<()> { let watering = WATERING.load()?.unwrap_or_default(); if !watering && bed.moisture < bed.target_low { pump("start")?; WATERING.save(&true)?; publish("watering_started", &bed.moisture)?; } else if watering && bed.moisture > bed.target_high { pump("stop")?; WATERING.save(&false)?; publish("watering_stopped", &bed.moisture)?; } Ok(()) } fn pump(command: &str) -> Result<()> { let pump = Sri::of_path(PUMP).map_err(|_| "invalid pump srn")?; send(pump, command, &Void) } ``` Reading it top to bottom: - The agent declares its *own* `BedState` struct matching the event's JSON fields - the same declaration the grow-bed has, deliberately duplicated. Cells share wire formats, not Rust types; each side owns its definition and can evolve independently. - `send(sri, command, &payload)` - the cell-side counterpart of the `myrmic send` you used in Part 2. Any cell can command any other; the [Commands](../../05_guides/02_commands.md) guide covers the details. - `Sri::of_path("pump")` - resolves a cell's SRN to its SRI, so the agent can address the pump by name. - `Void` - the explicit "no payload", for commands like `start` that need no arguments. - The agent also *publishes* - `watering_started` and `watering_stopped`. Decisions are announcements too: anyone (a logger, an alarm, a statistics cell) can react to them, and you can watch them from the CLI. Deploy it: ```bash myrmic deploy irrigation-agent ``` Now watch the handover of your job. Point Terminal 3 at the decision events: ```bash myrmic subscribe bed_state,watering_started,watering_stopped ``` When the weather swing next takes the moisture below the bed's low target, the agent acts: ```text [2026-08-26T18:05:30.557Z] event=watering_started sender=9f2172bd-... payload=8 bytes 54.99996 ``` And from then on, the `bed_state` events show `"pump_on": true` - until the moisture climbs past the high target and a `watering_stopped` arrives. The cycle repeats, forever, with nobody at the keyboard. One more look proves who is in charge now. In Part 2, the pump's log showed `external` as the sender. Check it again: ```bash myrmic telemetry logs ``` ```text INFO [...] | trace_id = | pump started (sender=Sri(9f2172bd-...)) ``` The sender is the irrigation agent's SRI. Same pump, same command, a different caller - and the pump never knew the difference. --- ## What Have You Learned - The **Agent** pattern: all business logic lives in one cell - sensors measure, assets remember, adapters act, agents decide. Swap the agent and the policy changes; nothing else moves. - Cells command each other with `send(sri, command, &payload)` - the cell-side counterpart of `myrmic send` - and `Sri::of_path` resolves a name to an address. `Void` is the explicit "no payload". - Hysteresis: two thresholds with a gap keep an actuator from chattering around a single set point. - Agents announce their decisions as events, so the rest of the swarm - and you, via `myrmic subscribe` - can follow along. - `md.sender` told the story: the same `start` command, once from your CLI session, now from the agent - and the pump could not care less. ## Next Step The greenhouse runs itself - but only terminal windows can see it. In [Part 5 - The Dashboard](./05_the-dashboard.md) we put the bed in the browser: a cell that serves a web page through the gateway. # Part 1 - The Mock Sensor This is Part 1 of the [Smart Greenhouse](../01_smart-greenhouse.md) tutorial. You start the runtime, scaffold your first cell, and build a mock soil-moisture sensor that publishes a reading every second - and reacts to the weather. Along the way you will learn about *cell events*: how cells publish them and how they subscribe to them. --- ## Step 1 - Start the Runtime Everything in Myrmic happens inside a *runtime*: the process that runs your cells, stores their state, and routes every message between them. On a real installation one runtime runs on every device of the swarm; today the whole swarm is one runtime on your computer. Open Terminal 1, start it, and leave it running: ```bash myrmic runtimes start ``` The runtime now occupies this terminal - that is fine, it is its job. Everything else happens elsewhere. Open Terminal 2, your working shell for the rest of the tutorial, and check that the runtime is alive: ```bash myrmic runtimes list ``` Expected output: ```text default running pid= ``` There it is: a running swarm of one machine, with nothing deployed yet. Let us give it something to run. --- ## Step 2 - Create the Workspace and Your First Cell In Terminal 2, create a directory for the application and scaffold your first cell: ```bash mkdir greenhouse && cd greenhouse myrmic new moisture-sensor ``` Expected output: ```text INFO Creating 'moisture-sensor' ``` Take a moment to look at what `myrmic new` generated: ```text greenhouse/ └── moisture-sensor/ ├── Cargo.toml -- the crate manifest ├── .gitignore └── src/ └── lib.rs -- the cell's code ``` A cell is nothing exotic: it is a small Rust crate that compiles to WebAssembly. Two things in the scaffold are Myrmic-specific: - In `Cargo.toml`, the `[package.metadata.myrmic]` section configures the cell's memory (for now just `heap_size` - how much heap the cell gets at runtime), and the `myrmic-sdk` dependency provides the macros and host functions cells are built from. - `src/lib.rs` contains a small counter demo - the same one the [Quickstart](../../01_quickstart.md) walks through. We will replace it entirely in the next step. --- ## Step 3 - Create the Mock Sensor Our first cell simulates a soil-moisture sensor. A real greenhouse would read the value from hardware through the signal layer; here a small simulation stands in: the moisture swings between a dry bound and a wet bound, the way real soil follows the weather - dry spells and wet fronts taking turns. That distinction matters less than you might think: to the rest of the swarm the interface is identical either way - a `moisture` event, once per second. ### Publish a reading every second Replace the content of `moisture-sensor/src/lib.rs` with: ```rust //! Mock soil-moisture sensor: publishes a `moisture` reading every second. //! The simulated moisture swings between a dry and a wet bound, the way real //! soil follows the weather. #![no_std] use core::time::Duration; use myrmic_sdk::db::state::State; use myrmic_sdk::{Callback, Metadata, Result, publish}; /// Simulated soil moisture, in percent. const MOISTURE: State = State::new_const("moisture"); /// Direction of the swing: `true` while the simulated weather is wetting. const RISING: State = State::new_const("rising"); #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { MOISTURE.save(&65.0)?; // The handle could cancel the timer later; this sensor measures forever. let _ = myrmic_sdk::interval(Callback::of::(), Duration::from_secs(1)) .build() .map_err(|_| "timer failed")?; Ok(()) } /// Timer target: the simulation advances one tick, then the reading is /// published. The value swings: it dries down to 50%, turns, wets up to 80%. #[myrmic_sdk::cmd] fn measure(_md: Metadata) -> Result<()> { let mut moisture = MOISTURE.load()?.unwrap_or(65.0); let mut rising = RISING.load()?.unwrap_or_default(); if moisture <= 50.0 { rising = true; } else if moisture >= 80.0 { rising = false; } let delta = if rising { 1.2 } else { -0.4 }; moisture = (moisture + delta).clamp(0.0, 100.0); MOISTURE.save(&moisture)?; RISING.save(&rising)?; publish("moisture", &moisture) } ``` Reading it top to bottom: - `State`, `State` - the cell's persistent memory. Cells can be restarted or moved to another device; whatever is in `State` survives, because it lives in the runtime's database, not in the Wasm module instance. - `#[myrmic_sdk::init]` - runs when the cell is deployed. It seeds the moisture at 65% and schedules the measurements. - `myrmic_sdk::interval(...)` - we have to emit one reading per second, and in Myrmic you do not block a cell with an endless loop: while a cell is handling a message, it cannot respond to another one. For anything periodic you use the runtime's scheduler instead - `interval` asks it to invoke the `measure` handler every second. `measure` is an ordinary `#[cmd]` handler; to the cell, the scheduler is just one more sender of commands. See the [Scheduling Handlers](../../05_guides/05_scheduling-handlers.md) guide for the details (one-shot timers, cancellation, and more). - `publish("moisture", &moisture)` - broadcasts an event to the whole swarm. The sensor does not know or care who listens. That indifference is the core of the architecture: the next steps will add listeners without touching this cell again. Deploy it (`myrmic deploy` builds and deploys in one step): ```bash myrmic deploy moisture-sensor ``` Expected output: ```text INFO deploying cell (srn = moisture-sensor, sri = ) INFO deployed cell (srn = moisture-sensor, sri = ) ``` Ask the swarm what is running: ```bash myrmic cells ``` The sensor cell appears, addressed by two identifiers: the `srn` (its human-readable name, derived from the crate name) and the `sri` (the unique id the runtime uses internally, derived from the srn). Right now the sensor cell is already measuring - once per second, into the void, because nobody is listening yet. In a terminal `myrmic cells` is a live view: it redraws every couple of seconds until you press Ctrl-C. Add `--once` for a single listing instead - which is also what you get when the output is piped or redirected. So let us listen. Open Terminal 3 and subscribe to the `moisture` event: ```bash myrmic subscribe moisture ``` Expected output (a new reading every second, moisture slowly falling): ```text INFO subscribed to: moisture (ctrl-c to stop) [2026-08-26T15:18:34.366Z] event=moisture sender=365d6cfe-... payload=9 bytes 64.6 [2026-08-26T15:18:35.367Z] event=moisture sender=365d6cfe-... payload=8 bytes 64.199997 ``` Terminal 3 is now your window into the application - leave it running for the rest of the tutorial. The sensor works; publishing is half of the story. ### Subscribe to an event Cells do not only publish events - they can react to them too. Weather exists, so let us teach the sensor about rain. Add this handler at the end of `moisture-sensor/src/lib.rs`: ```rust /// A rain shower adds a one-time amount of moisture. #[myrmic_sdk::evt] fn rain(_md: Metadata, amount: f32) -> Result<()> { let mut moisture = MOISTURE.load()?.unwrap_or(65.0); moisture = (moisture + amount).clamp(0.0, 100.0); MOISTURE.save(&moisture) } ``` `#[myrmic_sdk::evt]` is the mirror image of `publish` - and note that **the name of the function is the name of the event**: declaring `fn rain(...)` subscribes this cell to every `rain` event on the network, no matter who publishes it. There is no broker to configure and no subscription list to maintain; the handler *is* the subscription. The [Events](../../05_guides/03_events.md) guide covers the model in depth. Now redeploy the modified cell. Your first instinct might be to run `myrmic deploy moisture-sensor` again - try it: ```text Caused by: class 'moisture-sensor' has active instances and cannot be modified ``` The runtime protects a running cell: its code (its *class*) cannot be swapped underneath it. To replace a modified cell, delete the running instance first, then deploy: ```bash myrmic delete moisture-sensor --cell myrmic deploy moisture-sensor ``` `--cell` says which kind of target you mean. Without it, `myrmic delete` asks - and in a script, or anywhere without an interactive terminal, it refuses rather than guessing. Glance at Terminal 3: the readings resume from 65% - not because state does not survive (it does), but because our `init` deliberately reseeds it on every deploy. A fresh pot of soil for every experiment. Time for the first bit of magic. The CLI can publish events exactly like a cell can. Make it rain, from Terminal 2: ```bash myrmic publish rain 20 ``` Watch Terminal 3: within a second the moisture jumps up by 20 points, then the weather swing carries on from wherever that lands: ```text [2026-08-26T16:34:02.921Z] event=moisture sender=365d6cfe-... payload=8 bytes 61.399994 [2026-08-26T16:34:03.925Z] event=moisture sender=365d6cfe-... payload=8 bytes 81.39999 ``` Nothing was wired, no endpoint was called - you published an event, and the sensor's `rain` handler picked it up like any other subscriber would. --- ## What Have You Learned - A Myrmic swarm is made of *runtimes*; `myrmic runtimes start` brings one up and `myrmic runtimes list` shows it. - A *cell* is a small `no_std` Rust crate compiled to WebAssembly; `myrmic new` scaffolds one, `myrmic deploy` builds and deploys it, and `myrmic cells` shows what is running. Cells are addressed by a human-readable `srn` and a unique `sri`. - Cells keep their data in `State` - persistent memory that lives in the runtime's database and survives restarts. - Cells never block: no endless loops. Periodic work is scheduled with `interval`, which invokes an ordinary command handler on the runtime's clock. - Cells communicate through *events*: `publish` broadcasts without knowing the listeners, and an `#[evt]` handler subscribes - the name of the function is the name of the event. - A running cell's code cannot be swapped in place: `myrmic delete`, then `myrmic deploy` again. - The CLI is a first-class participant in the swarm: `myrmic subscribe` listens to events, and `myrmic publish` emits them, exactly like a cell would. ## Next Step The sensor measures, but nothing in the greenhouse can *act* yet. In [Part 2 - The Pump](./02_the-pump.md) we add the first actuator - a cell that receives commands. # Part 2 - The Pump This is Part 2 of the [Smart Greenhouse](../01_smart-greenhouse.md) tutorial. You build the greenhouse's first actuator - the irrigation pump - and learn about *cell commands*: how a cell exposes them, and how to send them from the CLI. It continues where [Part 1](./01_the-mock-sensor.md) left off: the runtime is running in Terminal 1, the moisture sensor is deployed and publishing, and Terminal 3 is subscribed to its readings. --- ## Step 4 - Create the Pump So far the greenhouse can only *observe*. To act on the world - to actually water the bed - it needs an actuator. Ours is a pump, and it introduces the second messaging primitive of Myrmic. Events, as you saw in Part 1, are broadcasts: the publisher does not know who listens. A pump is the opposite situation. "Turn on" is not an announcement to whoever cares - it is a request addressed to *one specific cell*, and exactly that cell should act on it. For this, Myrmic has **commands**. ### Expose commands with `#[cmd]` In Terminal 2, from the `greenhouse/` directory, scaffold the second cell: ```bash myrmic new pump ``` Then replace the content of `pump/src/lib.rs` with: ```rust //! Pump adapter: `start` and `stop` drive the irrigation motor, and the //! current state is announced on the `pump_state` event. The pump knows //! nothing about plants or watering policy. #![no_std] use myrmic_sdk::db::state::State; use myrmic_sdk::{Metadata, Result, publish}; const RUNNING: State = State::new_const("running"); #[myrmic_sdk::init] fn init(_md: Metadata) -> Result<()> { RUNNING.save(&false)?; publish("pump_state", &false) } #[myrmic_sdk::cmd] fn start(md: Metadata) -> Result<()> { RUNNING.save(&true)?; let _ = myrmic_sdk::info!("pump started (sender={:?})", md.sender).ok(); publish("pump_state", &true) } #[myrmic_sdk::cmd] fn stop(md: Metadata) -> Result<()> { RUNNING.save(&false)?; let _ = myrmic_sdk::info!("pump stopped (sender={:?})", md.sender).ok(); publish("pump_state", &false) } ``` The new pieces: - `#[myrmic_sdk::cmd]` - marks a command handler, and the naming rule is the same one you learned for events: **the name of the function is the name of the command**. This cell answers to `start` and `stop`, and nothing else. Where an `#[evt]` handler receives whatever anyone broadcasts, a `#[cmd]` handler runs only when someone addresses *this* cell directly. The [Commands](../../05_guides/02_commands.md) guide covers the model in depth. - `md.sender` - every handler receives `Metadata`, and for a command the sender identifies who asked. The pump logs it with `myrmic_sdk::info!`; you will see those log lines in a moment. - `publish("pump_state", ...)` - a good adapter announces what it does. The pump does not know who cares that it started - it just says so, on `start`, on `stop`, and once at `init` so the initial state is on the network too. This is the two primitives working together: commands go in, events come out. Notice what the pump does *not* contain: no moisture, no thresholds, no plants. An actuator adapter does what it is told and reports its state - deciding *when* to pump is someone else's job, and that separation is what will let us swap the decision-maker later without touching this cell. Deploy it and check the swarm: ```bash myrmic deploy pump myrmic cells ``` Two cells now, each with its own `srn`: `moisture-sensor` and `pump`. ### Send commands via the CLI You already know that the CLI can publish and subscribe to events like any cell. It can send commands too. First, make Terminal 3 watch the pump as well - restart the subscription with both events: ```bash myrmic subscribe moisture,pump_state ``` Now, from Terminal 2, command the pump: ```bash myrmic send pump start ``` `myrmic send` takes the target cell and the command name. In Terminal 3 the pump announces itself: ```text [2026-08-26T17:02:11.482Z] event=pump_state sender=4e9ba24d-... payload=4 bytes true ``` And the pump logged who asked. Look for it in the runtime logs: > **First time here?** Telemetry is only stored while a DB retention period is set, and a runtime starts without one. Run `myrmic telemetry set-db-retention "1h"` once, then `myrmic send pump start` again - only records emitted afterwards are stored. ```bash myrmic telemetry logs ``` ```text INFO [...] | trace_id = | pump started (sender=Sri()) ``` That `sender` is your CLI session - at the moment, it is labeled as `external`. You can now start and stop the pump on command. In a real greenhouse, that watering would show as an increase of moisture, by way of actual water and actual soil; in ours, the weather swing stands in for all of the physics. Either way, someone still has to decide *when* to water - and right now, that someone is you. Hold that thought: it is exactly the job we will automate. --- ## What Have You Learned - Myrmic has two messaging primitives: *events* are broadcasts to whoever listens; *commands* are requests addressed to one specific cell. - `#[cmd]` exposes a command handler, and the name of the function is the name of the command - the same rule events follow. - `md.sender` tells a command handler who asked; commands are never anonymous. `myrmic_sdk::info!` log lines show up in `myrmic telemetry logs`. - The CLI sends commands with `myrmic send ` - alongside `publish` and `subscribe`, it can act as any side of a conversation in the swarm. - A good adapter cell is dumb on purpose: commands go in, state events come out, and no application logic lives inside. ## Next Step The sensor measures, the pump waters, and you are the only thing connecting them. Before we automate that decision, the application needs one place that knows the *state of the bed* as a whole. In [Part 3 - The Grow-Bed](./03_the-grow-bed.md) we build it: the **Asset Cell**. --- sidebar_label: Why Myrmic --- **A NEW CATEGORY OF APPLICATION RUNTIME** # Build software where the world actually happens. Software is moving closer to where people live and work, into products, machines, buildings, and local operations. But shipping reliable applications for this world still means combining runtimes, messaging, state, placement, hardware integration, and device-specific stacks. We believe this needs a new category of software, built on a different set of assumptions: - Physical entities should be active participants in software systems, not merely passive data sources for remote applications. - Bare-metal microcontrollers (MCUs) should be first-class participants in distributed applications. - Resilience should be an out-of-the-box capability, not a complex infrastructure task. - Portable application logic should coexist with native, hardware-optimized execution. - Software should organize, coordinate, and recover itself, without requiring a third-party operator to keep it running. - Infrastructure should remain open, inspectable, and under the control of the people who run it. Myrmic turns these principles into an **open, edge-first application runtime**. Edge-first means starting with where data, users, devices, and physical processes actually are. It does not mean edge-only. Local, central, and cloud infrastructure all remain valid wherever they fit the application. Myrmic applications are built from **Cells**: small, stateful units of computation with stable identities. A **Node** is a device or operating-system process running Myrmic. Myrmic addresses each Cell by a **Stable Resource Identifier (SRI)**, not by the Node currently running it. A **Command** asks one Cell to act. An **Event** announces something that happened. Both reach Cells through **Mailboxes**, which hold Messages until a Cell handles them. A Cell also owns **State** and declares the **Capabilities** it needs. A Capability is a function or resource provided by a Node. > **Build around the Cell, not the Node that happens to run it.** > **Developer Preview** > Myrmic is ready to explore, test, and challenge. Stable Cell identity, mailbox-based messaging, placement by capability tags, mixed Linux and MCU deployments, WebAssembly isolation, and native signal processing are available today. Current failure behaviour is deliberately conservative: when a Node is lost, affected deployments are removed and reported. Cell state and mailboxes are held as one copy by default. > [Read what Myrmic guarantees today](./08_guarantees.md) ## One swarm. Different devices. One application environment. A Myrmic **swarm** is a network of Nodes that behaves as one application environment. The **Signal Layer** is Myrmic's native layer for acquisition, processing, and control. ![Cells distributed across OS-based and MCU-based Nodes in one Myrmic swarm](../images/swarm-view.svg) - OS-based Nodes can execute Cells and provide orchestration, data services, gateways, and native services. - MCU-based Nodes can execute Cells compiled ahead of time. They can also expose specialized signal processing through the Signal Layer. - Cells are addressed by a Stable Resource Identifier, or **SRI**, without knowing where they run. - A **Capability** is a function or resource a Node provides. Capability tags connect Cell requirements to eligible Nodes. ## What Myrmic provides today ### A stateful Cell model Cells combine identity, logic, state, Commands, Events, timers, and lifecycle. Each Cell handles one ordered stream of work, one handler at a time. ### Mailbox-based messaging Commands and Events pass through named mailboxes. Tracked delivery keeps pursuing a message until it reaches the destination Cell's current mailbox. Best-effort delivery is tried once. The current durability boundary is stated on the [Guarantees](./08_guarantees.md) page. ### Placement by capability tags Nodes advertise what they provide. Cells declare capability tags. Myrmic places Cells only on Nodes that satisfy those requirements. ### Linux and bare-metal participation OS-based Nodes use Wasmtime. Supported MCU-based Nodes use WAMR with modules compiled ahead of time. Both participate in the same peer-to-peer fabric and use the same Cell model. ### Native physical integration The Signal Layer runs natively on both Node classes. It connects drivers, signal processing, taps, and outlets while application logic remains isolated in WebAssembly. ### Predictable failure behaviour The preview does not claim that a Cell automatically continues after Node loss. Myrmic removes and reports the affected deployment. Cell state and mailboxes use one copy by default, so losing the Node that holds them can also lose that data. ## What the roadmap adds Myrmic is building toward **Sovereign Cells**: Cells that outlive the Node they run on, because their authority and committed data no longer depend on one Node. Two properties deliver this capability: - **Partition Tolerance** keeps the Swarm working correctly when a Node disappears or the network splits. For every Cell there is always exactly one place that may decide and serve — never none, and never two. - **Durability** keeps everything a Cell has acknowledged, so the Cell can resume on another eligible Node with exactly the State it had. > **Basic Cell + Partition Tolerance + Durability = Sovereign Cells.** Partition Tolerance alone preserves the decision about who may serve; only with Durability does the Cell's State itself survive. A last stage, **Secure Swarm**, adds what a production Swarm needs beyond surviving failures: authenticated Nodes and Cells, Nodes that join and leave while Cells keep running, and defined upgrade semantics. The roadmap is organized around guarantees and reproducible demonstrations, not dates. [Explore the roadmap](./09_roadmap.md) ## Follow the system from purpose to operation ### [Rethinking the Stack](./02_why-myrmic/01_rethinking-the-stack.md) **Why does this need to exist?** Understand the shift toward software that runs closer to its users, data, and physical context, and why the current stack makes that unnecessarily difficult. ### [Understanding Myrmic](./02_why-myrmic/02_understanding-myrmic.md) **What is the product?** See how Cells, Nodes, the swarm, Capabilities, native execution, and the six architecture layers form one coherent system. ### [Modelling Applications](./02_why-myrmic/03_modelling-applications.md) **How do I model applications?** Learn how Applications, Cells, stable identity, Commands, Events, callbacks, state, Capabilities, and Cell patterns fit together. ### [Connecting Physical Systems](./02_why-myrmic/04_connecting-physical-systems.md) **How does it reach the physical world?** Connect portable application logic to sensors, actuators, drivers, and local processing through the native Signal Layer. ### [Operating Myrmic](./02_why-myrmic/05_operating-myrmic.md) **How does it run in practice?** Understand Node roles, placement, data locations, gateways, what happens after Node loss, observability, and the path to Sovereign Cells. ## Start with your problem Different teams enter Myrmic through different needs: modelling physical assets, building connected products, running real-time rooms, coordinating workflows and agents, or providing a stateful platform primitive. [Explore the application domains](./03_target-groups.md) ## Put the preview to work Start with one Cell. Run a mixed swarm. Connect a real signal pipeline. Stop a Node and compare what happens with the published guarantee contract. The preview is the right time to expose unclear APIs, missing Capabilities, weak operational behaviour, and unsupported topologies. > **Run it. Challenge it. Reproduce the claims that matter to you.** ## See also - [Core Concepts](./06_concepts.md) - the vocabulary every other page assumes - [Architecture](./07_architecture.md) - how Myrmic actually works, view by view - [Guarantees](./08_guarantees.md) - what the current release promises, and what it doesn't yet - [Roadmap](./09_roadmap.md) - what future stages are intended to add # Connecting Physical Systems Portable application logic and hardware-near execution have different needs. Myrmic keeps product and application behaviour in WebAssembly Cells while drivers, signal processing, and physical I/O run as native Rust. > **WebAssembly is the application boundary, not the hardware driver model.** ## The Signal Layer The Signal Layer is Myrmic's native subsystem for: - sensor acquisition, - actuator control, - driver lifecycle and recovery, - local filtering and transformation, - named taps and typed outlets. It runs on both Node classes: - as a native process connected through IPC on OS-based Nodes, - as native tasks using shared memory on MCU-based Nodes. ## Flow-based authoring, native execution A pipeline describes sources, processing steps, taps, and outlets in YAML. ```text source → processing steps → tap → Cell Cell → outlet → native driver → actuator ``` A generator combines the pipeline with the board or Node description, emits Rust, and compiles it into the target. The graph is not interpreted at runtime. Processing steps execute inside native source tasks without a separate task or message hop for every step. > **Describe the flow declaratively. Run it as native code.** Myrmic does not currently include a graphical pipeline editor. ## Taps and outlets A **tap** is a named, typed value or event exposed to Cells. An **outlet** is a named, typed command endpoint consumed by a native output driver. Cells can depend on semantic contracts such as: ```text room.temperature motor.status fan.speed ``` The Cell does not need to know which sensor, bus, board, or driver implements the contract. ## Signal Layer modules become Node Capabilities A compiled pipeline is installed with a specific Node. Its taps, outlets, protocols, and native functions become Capabilities that Node advertises. Cells declare capability tags. Placement brings the Cell to a compatible Node. This makes physical location explicit without leaking concrete hardware into application logic. ## Bare-metal Nodes are first-class participants A supported MCU can: - execute WebAssembly Cells compiled ahead of time, - run the Signal Layer directly on bare metal, - expose local sensor, actuator, radio, and protocol Capabilities, - communicate with Cells across the swarm. The MCU does not need to run the complete platform. Data, orchestration, and gateway roles can live on other Nodes. ## From local signals to application state A useful separation is: ```text sensor or actuator ↓ native Signal Layer ↓ Adapter Cell placed by capability tags ↓ Commands and Events Asset or Agent Cells ``` The local Adapter stays close to the physical Capability. Canonical state, policy, and coordination can remain independent of that hardware location. ## Preferred integration path New GPIO- and I²C-based integrations should use Signal Layer drivers, taps, and outlets. Direct low-level runtime interfaces remain compatibility or escape-hatch mechanisms rather than the default application architecture. BLE is broader than a single signal pipeline and may remain a connectivity Capability. ## Scope Myrmic is not a PLC, hard-real-time controller, or certified functional-safety system. Keep safety-critical control and guaranteed safe-state behaviour in systems designed and certified for them. ## See also - [Cell Patterns](../06_concepts/07_cell-patterns.md) - recurring designs for combining Cells, Adapters, Agents, and Bridges - [The Node View](../07_architecture/02_the-node-view.md) - how a Node runs native Rust and WebAssembly side by side # Modelling Applications Myrmic applications are built from **Cells**: small, isolated units of logic, state, and identity. A Cell represents something that persists, such as a room, workflow, agent, device, machine, tenant, or asset. It does not represent the temporary process serving it. > **The interaction is temporary. The Cell is the stable application concept.** ## Applications define the reasoning boundary An **Application** is the declared boundary for a set of Cell classes, instances, bridges, assets, and deployment settings. The boundary is organizational, not a guarantee. Cross-Application dependencies are not automatically inferred or managed. ## Cells combine identity, logic, and state A Cell Class is a WebAssembly module plus its declared requirements. A Cell instance has its own State and Stable Resource Identifier (SRI). An Application can assign a human-readable Stable Resource Name (SRN). Myrmic derives the SRI deterministically, so any participant that knows the SRN can address the same logical Cell without a location registry. ## Commands, Events, and callbacks - A **Command** directs intent to one Cell. - An **Event** publishes a fact to any interested subscribers. - A **callback** is an ordinary message delivered later to the caller's own mailbox. Cell-to-Cell work is asynchronous: a Cell dispatches and continues. External clients, including the CLI and gateway, may wait for the later callback and present that wait as a blocking request. Cells themselves never block on another Cell. ## Mailboxes decouple messages from live connections Messages pass through named outbound and inbound mailboxes synchronized by the Data Layer. This lets a Cell receive work without requiring sender and receiver to be live at the same instant. The exact durability and delivery contract is versioned on [What Myrmic guarantees today](../08_guarantees.md). ## Handlers define state transitions A Cell processes one ordered stream of work, one handler at a time. Conceptually, a command handler groups: - consuming the inbound message, - changing the Cell's state, - producing outbound messages. External effects such as HTTP calls, MQTT publishes, or actuator writes sit outside that unit and need their own idempotency or fencing strategy. ## Capabilities guide placement today The current Application specification declares capability tags, build platforms, an optional SRI, and initialization arguments. A Node advertises what it can provide. Myrmic places the Cell only where its requirements are available. ## Recovery models arrive with Partition Tolerance The preview does not expose a per-Cell recovery or consistency model. The **Partition Tolerance** stage introduces three declarations: - **Consistent** - consistency first; may halt instead of diverging, - **Convergent** - designed to reconcile divergent state under a declared merge rule, - **Dataflow** - best-effort stream processing at a declared level. Restart policy is a separate concern from replication. See [Recovery Models](../06_concepts/06_recovery-models.md) and the [Roadmap](../09_roadmap.md). ## Cell patterns provide design vocabulary Asset, Adapter, Agent, and Bridge are application patterns, not runtime types or guarantees. They help teams separate canonical state, physical integration, decision logic, and external connectivity. ## See also - [Core Concepts](../06_concepts.md) - the full Cell, Mailbox, and Node vocabulary - [Connecting Physical Systems](./04_connecting-physical-systems.md) - how Cells relate to native drivers and hardware I/O # Operating Myrmic A **swarm** is a network of Myrmic Nodes that behaves as one system. Myrmic lets different device classes participate while keeping their roles and limits explicit. The developer preview is intended for evaluation. Operate it against the published guarantee contract, not against assumptions about future continuity. ## Nodes have shapes and roles A **Node** is a device or operating-system process running Myrmic. Node shapes: - **OS-based:** Linux-class systems with the plugin topology, broader compute, gateways, and data services. - **MCU-based:** supported microcontrollers with firmware execution, WAMR with modules compiled ahead of time, typed clients, and native Signal Layer tasks. Node roles: - **Orchestrator:** participates in coordination and authority. - **Executor:** runs Cells and contributes Capabilities without voting. MCU-based Nodes operate as Executors. ## Placement uses Capabilities Nodes advertise Capabilities such as architecture, protocols, storage roles, native modules, and Signal Layer taps or outlets. Cells declare capability tags. The current placement logic selects a reachable execution Node that provides the required Capabilities. Recovery models are not part of the preview Application manifest. They arrive with Partition Tolerance. ## Authority, data, and execution are separate A Cell may execute on one Node while its State and Mailbox live on another. Today: - authority uses one coordinator selected by lowest ID, - Cell data is held as one copy by default, - one Cell instance serves; redeploying a class that has active instances is refused, so you delete the instance first. The [Guarantees](../08_guarantees.md) page states the exact current contract. ## Current behaviour after Node loss When a Node is lost, Myrmic removes and reports affected deployments. It does not claim that the Cell resumes elsewhere. Without a State replica, there is nothing to resume from. Starting a fresh, empty Cell under the same identity would not be continuity. ## Messaging and external access Cells communicate through Commands, Events, and callbacks over Mailboxes. External clients can interact through: - the CLI, - the WebSocket gateway, - packaged web applications, - other integrations exposed by Nodes. The Chatty example demonstrates browser sessions, history, presence, and message fan-out through the same Cell model. ## Common deployment shapes ### Central swarm OS-based Nodes provide execution, data, gateways, and coordination. ### Site-local swarm Applications run close to users, assets, and local networks without requiring every interaction to cross a cloud path. ### Hybrid swarm Local Nodes handle context-sensitive work while central Nodes provide broader services. ### MCU plus Linux Bare-metal Executors provide local Cells and Signal Layer Capabilities. Linux Nodes provide data, orchestration, and gateways. ## Development workflow ```bash myrmic new my-cell myrmic build ./my-cell myrmic runtimes start --detached myrmic deploy ./my-cell myrmic send my-cell increment myrmic telemetry debug --id my-cell ``` > **Create · Build · Run · Deploy · Interact · Observe** ## What the roadmap changes - **Partition Tolerance:** authority over each Cell is held by a voter set of several Nodes and decided by majority, and fencing allows only one active serving copy. Deploy and stop operations become acknowledged. - **Durability:** Cell State and Mailboxes are replicated across Nodes. Transactions can extend across Nodes, timers become durable, Commands gain request identity, and a Cell can resume after Node loss. - **Secure Swarm:** Nodes and Cells become authenticated, Nodes can join and leave while Cells keep running, and upgrades get defined semantics. Durability is research before engineering. The roadmap names the target guarantee and the demonstration that will prove it, without pretending the full design is already scheduled. ## Evaluate the preview actively - reproduce the current Message and transaction behaviour, - test placement by capability tags on your target Nodes, - stop the Node holding Cell data and observe the documented result, - compare the diagrams with the guarantee page, - report any behaviour that contradicts the contract. ## See also - [Architecture](../07_architecture.md) - how Myrmic actually works, view by view - [Guarantees](../08_guarantees.md) - what the current release promises, and what it doesn't yet - [Roadmap](../09_roadmap.md) - what future stages are intended to add # Rethinking the Stack Software is becoming part of the world around us, inside products, machines, buildings, local infrastructure, and the operations people depend on. The application stack has not caught up. Teams still combine separate systems for execution, messaging, state, placement, failure handling, hardware integration, and device-specific tooling before they can build the application itself. > **Software is moving closer to the world it serves. Its infrastructure should move with it.** ## Software is moving closer Applications increasingly span: - central services and global users, - local sites and operational networks, - gateways and Linux-class systems, - bare-metal microcontrollers, - sensors, actuators, and physical processes. Location now affects latency, continuity, data movement, hardware access, and who remains in control when connectivity changes. ## The stack is fragmented A stateful application often requires teams to assemble: - a runtime, - messaging and stable addressing, - durable state and mailboxes, - placement and discovery, - lifecycle and failure handling, - gateways and external interfaces, - native drivers and signal processing, - different stacks for servers, gateways, and MCUs. The burden is not one component. It is making all of them behave as one system, then repeating that work for every product. ## Physical entities should participate Products, machines, rooms, and assets are often reduced to telemetry streams or database rows. Their identity and behaviour are reconstructed somewhere else. We believe physical entities should participate directly in software systems. They should have stable identities, receive requests, publish events, expose local functions, and support useful local behaviour. That does not require every state byte to live on the device. It requires the software model to respect where data, hardware, and operational context actually exist. ## Edge-first, not edge-only **Edge-first** means designing from the real context of the application: - where data is created, - where people and devices interact, - which Capabilities are local, - what must continue during network disruption, - where teams want control to remain. A Myrmic **swarm** is a network of devices and processes that runs Applications as one system. It can form and operate without a cloud connection. An Application that belongs entirely at the edge can run entirely at the edge. Central and cloud infrastructure remain useful for global access, aggregation, analytics, and cross-site coordination. They are optional deployment choices, not mandatory control paths for every interaction. ## Resilience should become a runtime property Stateful recovery becomes difficult when identity, authority, and data are fused with one process or machine. Myrmic separates three concerns: - **authority:** who decides, - **data:** what survives, - **execution:** what currently runs. The developer preview makes its current boundary explicit. The roadmap then makes authority survive failures with **Partition Tolerance** and data with **Durability**. ## Software should reduce routine operations Distributed software should organize, coordinate, and recover itself during routine operation without depending on a third-party operator to keep it running. This does not remove human oversight. Teams still define policy, security, lifecycle, and the boundaries within which the system may act. ## Infrastructure should remain controllable Myrmic is open source and self-hostable. The runtime, placement model, failure behaviour, and hardware integration remain inspectable and adaptable. The goal is not to reject cloud services. It is to preserve a credible alternative to making one provider part of every application's control path. ## Developer Preview Myrmic is available as a developer preview. Use it to evaluate the Cell model, messaging, placement, mixed Linux and MCU operation, the Signal Layer, and the current documented limits. ## See also - [Understanding Myrmic](./02_understanding-myrmic.md) - the model that responds to this shift - [Guarantees](../08_guarantees.md) - what the current release promises, and what it doesn't yet - [Roadmap](../09_roadmap.md) - what future stages are intended to add # Understanding Myrmic Myrmic is an open runtime for stateful edge applications that span servers, local systems, and physical devices. A **Cell** is a small, stateful program with a stable identity. Myrmic combines this Cell model with Mailbox messaging and placement based on capability tags. WebAssembly provides isolated execution, native Rust handles signal processing, and peer-to-peer sessions connect the runtime. > **One application model across a mixed swarm of OS-based systems and bare-metal MCUs.** ## The swarm is the product ![The Myrmic swarm view](../../images/swarm-view.svg) A **Node** is a device or operating-system process running Myrmic. A **swarm** is a network of Nodes that behaves as one application environment. Cells address each other by a **Stable Resource Identifier (SRI)** rather than a network location. A **Capability** is a function or resource a Node provides. Cells declare capability tags, and placement selects an eligible Node. ## Three concerns stay separate Most stateful systems fuse authority, data, and execution. Myrmic treats them as separate concerns: | Concern | Question | | --- | --- | | **Authority** | Who may decide placement, membership, and the serving role? | | **Data** | Where do state, mailboxes, and records live, and what survives? | | **Execution** | Which Node is currently running the Cell? | The roadmap introduces the concept of a **Sovereign Cell**: a Cell that survives its Node. This is achieved by replicating **Authority** and **Data**, never by replicating **Execution** — the system runs one active Cell instance, not several copies executing in lockstep. ## The six layers Myrmic uses one canonical architecture model: 1. **Execution Layer:** WebAssembly Cell execution 2. **Self-Organization Layer:** membership, authority, and placement 3. **Data Layer:** state, mailboxes, and records 4. **Peer-to-Peer (P2P) Layer:** the shared session and protocol fabric 5. **Transport Layer:** physical network links 6. **Signal Layer:** native acquisition, processing, and control [See the six-layer view](../07_architecture/05_the-six-layers.md) ## The application surface Developers interact with Myrmic through: - the Rust Cell SDK, - Application manifests, - the `myrmic` CLI, - Commands, Events, and callbacks, - the WebSocket gateway and packaged web assets, - named Signal Layer taps and outlets, - target-specific functions exposed by Nodes where explicitly available. ## Nodes, roles, and Capabilities - An **Orchestrator** participates in coordination and authority. - An **Executor** runs Cells and contributes Capabilities without voting. OS-based and MCU-based Nodes share the Cell model, but they do not expose identical Capabilities. A Cell declares capability tags, and placement selects a compatible Node. ## What ships in the preview - stable SRI addressing, - WebAssembly Cells on Linux and supported MCUs, - Commands, Events, callbacks, and mailbox-based delivery, - placement by capability tags, - Cell state and mailboxes held as one copy by default, - WebSocket and CLI access, - the native Signal Layer on both Node classes, - explicit remove-and-report behaviour after Node loss. The [Guarantees](../08_guarantees.md) page is authoritative for the current release. ## What Myrmic is not Myrmic is not: - only an IoT platform, - merely a WebAssembly runner, - a generic stateless microservices framework, - a system that requires a cloud control plane, - a PLC, hard-real-time controller, or functional-safety system, - an AI model or inference platform. ## See also - [Modelling Applications](./03_modelling-applications.md) - how to think in Cells when designing an application - [Architecture](../07_architecture.md) - how Myrmic actually works, view by view