— Platform / Architecture
The MOS4 stack.
MOS4 is a distributed micro service OS over Linux: 8 architectural layers, 52 production micro services, 89 proto interfaces, 10-second hot-swap. Proto-defined interfaces, registry-enforced startup ordering, and hot-swap are framework properties — not application responsibilities.
Component model
One declaration, full service surface.
Each micro service declares proto-defined provided_interfaces and required_interfaces. The code-generation step writes the full service surface: server trait, proxy, direct client, fake test double, metrics module, and compliance test suite — from a single declaration. The author writes lifecycle hooks and business logic — nothing else.
One code-generation step
build_api::generate_component_code(dir, out_dir) in build.rs drives: proto parsing → server trait → proxy → direct client → fake → metrics module → compliance
test suite. A minimal micro service is under 30 lines of user-written Rust.
Registry-enforced ordering
start_level 0–10 is the numeric registry priority — distinct from the L0–L7 architecture
mental model. The registry builds a dependency graph and enforces it at startup; no micro service
can call a required interface before its provider has registered.
Hot-swap at the framework level
When a new process registers with an existing component.id, the registry
requests a state-dump from the old instance, stops it, injects serialised state into the
new, and starts the replacement. From end-of-compile to first successful service call on a
real device: 10 seconds.
Browse the full micro service catalog — 52 services, 89 proto files.
Supervised runtime
Three supervision layers, zero boilerplate.
The framework monitors every micro service with task checkpoints, process health pings, and hardware watchdog integration. Corrective action — restart, reboot, or hardware reset — escalates automatically without any per-service configuration.
Watchdog
Micro services declare named task checkpoints with timeouts in the #[component]
macro. The framework monitors three supervision layers: task checkpoints, process health pings
between supervisor and worker processes, and the Linux /dev/watchdog
hardware escalation path. Missed checkpoint → Degraded → restart → reboot → hardware reset.
Sentry
Centralised issue tracking across all micro services. During the registry startup-grace window, cascade-class errors are gated — a Sentry cascade gate prevents startup noise from contaminating the issue log. Operators can tune the startup-grace period or disable the gate entirely.
Observability
The framework emits per-RPC histograms, error counters, service uptime, and lifecycle event traces for every registered service call — automatically, with no per-service instrumentation code required. W3C Trace Context propagation is included.
Dashboards, OTA, remote control, lifecycle — full observability surface at /platform/operations.
Registry + transport
Transport selected by endpoint URL.
The master registry owns service discovery and startup ordering. Transport mode — memory, Unix socket, shared memory, TCP, QUIC, WebSocket — is selected by URI scheme at bundle config time. Direct mode bypasses serialisation for same-process callers. Service code is transport-blind.
| Environment | Transport | Encoding |
|---|---|---|
| Same-chip service-to-service | iceoryx2 SHM + dmabuf | zero-copy |
| Camera / vision plane | SCM_RIGHTS fd passing | dmabuf handle |
| ROS2 (Robot Operating System 2) bridge | iceoryx2 DDS (Data Distribution Service) | protobuf / DDS |
| Cross-host / TCP | TCP / Unix sockets / QUIC | zstd / LZ4 / gzip |
| WebSocket clients | WebSocket | zstd / gzip |
Direct mode adds under 10 µs of overhead per co-located call: services in the same process exchange typed messages with zero serialisation, so a same-device call is closer to a function call than a network hop — no copy, no encode/decode round-trip. TCP, Unix sockets, shared memory, QUIC, WebSocket, named pipes, and ring buffers all implement the same transport interface. No conditional compilation in service code. On-wire compression (zstd, LZ4, Snappy, gzip) negotiates per connection. Circuit breaker and retry are built in to the registry.
Two transport modes. Mode 1: same-chip service-to-service data exchange uses shared memory with frame handles for zero-copy frame hand-off. Mode 2: ROS2 bridge — rclcpp and rclpy nodes publish DDS topics; the frame transport translates them to the MOS4 bus, delivering typed events to MOS4 micro services.
flowchart LR
subgraph S1["Same-chip service to service"]
A[Micro service A] -->|shared memory + frame handle| B[Micro service B]
end
subgraph S2["ROS2 bridge via the frame transport"]
R[rclcpp / rclpy node] -->|DDS topic| F[Frame transport]
F -->|MOS4 bus| C[MOS4 micro service]
end The 4 engines, one runtime
One platform serves all four no-code engines and N containers.
The supervisor, registry, event bus, and the in-process MQTT (Message Queuing Telemetry Transport) broker are shared infrastructure. MSP (signal processing), MEP (event policy), Multi Stacks (vehicle and industrial comms), and AI Funnel each consume the same primitives — and so does every customer container, in any of the five featured languages.
Shared platform
- · Supervisor — start, stop, restart, hot-swap
- · Registry — typed interfaces, semver, dependency graph
- · Event bus — named-event distribution
- · In-process MQTT broker — any language container reaches any service
Engines and containers, side by side
- · MSP — continuous signal-processing graphs
- · MEP — state-machine policies (Trigger · Condition · Action)
- · Multi Stacks — vehicle and industrial-IoT comms
- · AI Funnel — declarative edge AI
- · N containers — Python · Rust · C · C++ · Go (ROS2 sidecar)
Each no-code engine is documented in depth at /platform/no-code.
Glossary
Public name to engineering term.
| Term | What it is |
|---|---|
| Micro service | The runtime unit of MOS4. Rust crate, #[component] macro, proto interfaces. |
| MCM | MOS Container Manager — lightweight container engine with enforced resource isolation. |
| MD21 | Munic's telemetry uplink protocol (ASN.1 UPER), bandwidth-optimised. |
| MSP | MOS Signal Processing — YAML graph engine for vehicle-domain dataflow. |
| MEP | MOS Event Processor — state-machine policy engine. Each rule is a Trigger / Condition / Action primitive; the composed rule set is the state machine. Hot-reloadable. |
| iceoryx2 | Zero-copy IPC. Two modes: SHM + dmabuf same-chip, DDS in full for ROS2 bridge. |
Stack-diagram labels (L0–L7) are a mental model for layer grouping. Registry priority uses a
numeric start_level 0–10 — different scale, different purpose.
Cloud egress
Micro service to GraphQL mesh — end to end.
Micro service in container
Application code or a platform micro service publishes typed events.
MQTT bridge
Any standard MQTT client — no SDK adoption needed.
Communication gateway
MD21 telemetry uplink: ASN.1 UPER binary encoding, bandwidth-optimised for constrained links.
cloud-connect
Munic cloud relay — runs multiplexing, piggybacking, compression.
GraphQL mesh
Customer entry point. Public reference: gateway.munic.io
GraphQL mesh is the customer entry point — cloud-side, not device-side. The public reference endpoint is the developer documentation portal.
Developer unlock
RPC bridge — call any micro service from the cloud.
The RPC bridge exposes any registered MOS4 service over the applications.rpc channel. Accepts JSON with interface name, method name, and payload. No protocol or wiring code beyond the component interface and the cloud-side service.
Debug and unblock
Call any micro service — including containers — from the cloud to inspect state, trigger a one-off action, or unblock a rare situation on a remote device.
AI-driven hybrid flows
An AI agent or cloud automation layer can drive the device via API — query sensors,
trigger actuators, load a new policy — with ListServices() returning the
live service catalogue at runtime.
RoutingService is part of the modem stack, not a separate micro service. The SDK-developer view of the same RPC primitive lives at /platform/sdk.
Compare MOS4 against other embedded OS and platform approaches at compare overview.