pamoja

An SDK for IoT, robotics, and drones

pamojaRev 0.2.0MIT licensepamoja.molex.cloud

Standards and conformance#

Anything defined by a published standard is implemented from the authoritative specification itself, and its tests are anchored to that specification's own reference vectors. Bit layouts, field orders, reserved bits, and algorithm constants are where the subtle bugs hide, and a plausible guess is worse than none.

Every row below links two things: the document, and the test in this repository that holds the code to it. cargo xtask links fetches each document on every run, so a specification that moves fails the build rather than sitting here looking authoritative. A handful of publishers refuse scripted clients; those rows say so, and a person opens them instead.

What a row's second heading claims:

Anchored toWhat the test asserts
Published vectorThe specification's own test vector or worked example
Specification ruleIts constants, bit layout or equation, asserted directly
Live implementationA third-party implementation the test talks to
Round trip onlyThe code against itself, with no external vector to pin against

62 standards registered, 35 of them pinned to the document's own published vectors. Counted from docs/standards.toml when this page was rendered.

Cryptography#

The primitives under device identity, the secured session, and signed updates.

RFC 9124#

IETF

The information model a firmware manifest must answer

Each named threat is answered by a test named after it. The SUIT CBOR serialization is a deliberate deviation: draft-ietf-suit-manifest is still a draft.

Identity and signing#

What names a device and what proves a message came from it.

Encodings#

The wire formats readings and manifests are written in.

Field I/O#

The buses and framings that reach a part on the end of a wire.

MODBUS Application Protocol Specification V1.1b3#

Modbus Organization

The function codes and their limits, the four data tables, and the exception responses a device answers with

The worked request and reply of each of the eight functions in section 6, the exception example in section 7, and the register-count example given for exception 0x02.

Modbus over Serial Line V1.02#

Modbus Organization

The RTU frame, the silence between frames, unit addresses and broadcasts, and a client's timeouts

The 3.5-character gap and its fixed 1.75 ms above 19200 baud from section 2.5.1.1; a broadcast carried out and not answered, and a frame that fails its CRC left unanswered, from sections 2.2 and 2.6.

SocketCAN, the Linux kernel's CAN documentation#

The Linux kernel

The raw CAN socket: its frame layouts, its receive filters, and which frames a socket hears

Run in CI against the kernel's own virtual CAN interface: classic, extended, remote, and CAN FD frames, a filter by J1939 parameter group, and no echo of a node's own frames.

Sensors and actuators#

Parts decoded byte for byte, each from the manufacturer's own datasheet.

Twelve manufacturer datasheets#

Bosch, Analog Devices, Texas Instruments, Sensirion, NXP

BME280, BMP280, DS18B20, HDC1080, INA219, INA226, ADS1115, OPT3001, SCD4x, SHT3x, TMP117 and PCA9685

Each driver asserts its datasheet's own worked compensation example. Every document is linked from the hardware page, part by part.

A4988 Rev. 8 and DRV8825 SLVSA73F#

Allegro MicroSystems, Texas Instruments

Step and direction timing: the direction settled before the step line rises, and the pulse's minimum width

Figure 1 of the A4988 datasheet and the DRV8825's timing requirements: 200 ns and 650 ns of setup before the rising edge, 1 and 1.9 microseconds high. The driver holds each for its pulse width, 10 microseconds unless told otherwise.

w1_therm sysfs interface#

The Linux kernel

The w1_slave file a Linux board serves for each DS18B20 on its 1-Wire bus

The text is the one w1_slave_show prints in the kernel's drivers/w1/slaves/w1_therm.c, and its millidegrees are the datasheet's temperature rows.

Radio, mesh and gateways#

Reaching a network that is not there, and the rules a regulator sets for doing it.

TS011-1.0.1#

LoRa Alliance

The LoRaWAN relay: wake-on-radio frames, forwarding and relay commands

Appendix 1's worked synchronization example, with WOR frames checked against Semtech LoRa Basics Modem and the root key against The Things Stack.

TS003-2.0.0#

LoRa Alliance

Application layer clock synchronization, so a device without a clock knows the time

Every command checked against the size the specification gives it, cross-read with Semtech LoRa Basics Modem's own size constants.

TS004-2.0.0#

LoRa Alliance

Fragmented data block transport, which carries an image larger than a frame

ChirpStack's own command bytes, and the parity matrix against an independent rendering. The coded fragments are seeded by the index among the coded fragments, which is what Semtech's Basics Modem and ChirpStack both do; the appendix reads as though the session index were the seed.

TS006-1.0.0#

LoRa Alliance

Firmware management: what a device runs, what it holds, and the one reboot it keeps

Every command checked against the size the specification gives it, including the version that rides only with an installable image.

CRC-16/IBM-3740#

CRC RevEng

The integrity check a mesh frame carries

Check value 0x29B1. Also listed as CRC-16/CCITT-FALSE; the bare name CRC-16/CCITT means a different algorithm, KERMIT, which checks 0x2189.

Drones#

The protocol a ground station and a flight controller speak.

Robotics#

Naming, typing and carrying messages the way ROS 2 and Zenoh do.

The Key Expressions Language, Zenoh RFC#

Zenoh project

Validity, canonical form, verbatim chunks, and how two expressions intersect or include

Every intersection and inclusion vector from zenoh-keyexpr's own tests, the RFC's canonical-form statements, and a test that asks Zenoh's implementation the same questions.

Messaging#

The protocols a node speaks to a broker or a server.

MQTT Version 3.1.1#

OASIS

The client: packet framing and size, topic and filter rules, clean sessions, the three delivery guarantees and their acknowledgments, retained messages, the last will, and signing in

The valid and invalid filters of sections 4.7.1.2 and 4.7.1.3, and the remaining-length boundaries of Table 2.4. Acknowledged delivery at each level (4.3), a retained message and its clearing (3.3.1.3), the will a dropped client leaves and the DISCONNECT that discards it (3.1.2.5, 3.14.4), and the password rule of 3.1.2.9 are tested against an in-process broker in crates/pamoja-mqtt/tests/delivery.rs and were checked against Mosquitto 2.1.2.

RFC 7252#

IETF

CoAP: the message types, retransmission, deduplication, Reset, and the response codes

Sections 4.2 to 4.5 and 5.3.1, and table 6. Beside it, a Reset and a 4.04 fail a confirmable send, and a ping is answered with a Reset.

RFC 7641#

IETF

Observing a CoAP resource: registration, notifications by token, freshness, and cancelling with a Reset

The freshness conditions of section 3.4, including the 24-bit wrap and the 128-second rule.

Across languages#

A second set of vectors, in conformance/vectors.json, does the same job across languages rather than against a specification. It is generated from the Rust implementation by cargo run -p pamoja-examples --example conformance_vectors and asserted by all four binding suites, so a facade that drifts fails instead of quietly returning something else. CI regenerates the file and fails on any difference.

Each vector pins the exact bytes where a capability has a wire format, and the register values, tables and timings where it does not. The suites are checked by perturbation: each runner mutates a vector it has loaded and asserts that its own comparison rejects it, so a suite that silently stopped comparing fails instead of passing.

Against the real thing#

Where a specification has a live implementation to talk to, CI talks to it.

The MAVLink layer commands ArduPilot and PX4 in SITL. It reads a heartbeat, requests a message, and waits for the autopilot to report its pre-arm checks passing. Then it downloads the vehicle's plan, uploads one of its own and reads it back item for item, and arms and disarms. The arm has to be accepted and then seen in the vehicle's own heartbeat. Nothing is flown.

The ROS 2 bridge exchanges topics, services and actions with ROS 2 Jazzy in the official image, under the RMW that image selects. The same job then selects rmw_zenoh and publishes a Twist from a ROS 2 node that a plain pamoja Zenoh peer receives, on the key pamoja-ros2 builds for that topic and type, and decodes with its own CDR. The LoRa gateway registers a device with a ChirpStack network server and forwards a join and an uplink through it.

Every no_std crate is cross-compiled for a Cortex-M4F microcontroller, since a host no_std build still links the host std.

Edit this page on GitHub