Crate pamoja_ffi 

The curated C ABI surface for the pamoja SDK.

This crate exposes a small, hand-written extern "C" API over [pamoja_core] and the capability crates so that languages without a native Rust bridge - C, C++, and C#/.NET through P/Invoke - can drive the SDK. It is deliberately the project’s single auditable unsafe boundary: every raw pointer is dereferenced here and nowhere else.

The committed header include/pamoja.h is generated from this source by cbindgen (see build.rs) and is drift-checked in CI, so the C contract can never fall behind the Rust surface.

Conventions

• Fallible calls return a PamojaStatus code. On any non-Ok result a human-readable message is stored for the calling thread and can be read with pamoja_last_error_message.
• Handles are opaque, heap-allocated, and owned by the caller, who must release each with its matching *_free function.
• All strings crossing the boundary are UTF-8. Inputs are borrowed for the duration of the call; returned pointers document their own lifetime.
• An enum the caller passes in, as an argument or as a field of a struct, must hold one of the values the enum declares. The library reads it as one of those values, and any other value is undefined behavior; the .NET binding refuses one before the call.

Choosing what the library carries

Every capability is a cargo feature, all on by default, so a host that builds this crate itself gets the same “compile only what you use” property a Rust consumer has, and it is worth using. The seven capabilities that need an async runtime (mqtt, coap, loopback, sync, ladder, bus, and sim) carry Tokio and the network stacks with them, and are about half the compiled library on their own: dropping just those, keeping every other capability, took a release build from 2.07 MB to 1.01 MB. A host that only decodes protocol bytes can go much further, to 0.41 MB:

cargo build --release -p pamoja-ffi --no-default-features \
  --features "modbus,can,serial,gpio,sensors,codec,security"

Those figures are one x86_64-pc-windows-msvc build and will differ per platform; cargo xtask builds reports the sizes on the machine at hand. The Node, Python, and .NET packages ship the full default build regardless, because their package managers cannot express the choice per consumer.

Modules

actuators

The C ABI for the actuator drivers.

actuators_driver

The C ABI for the actuator drivers that run over an I2C bus.

audit

The C ABI for tamper-evident audit logs.

bus

The C ABI for the in-process event bus.

can

The C ABI for CAN bus framing.

can_bus

The C ABI for a node on a CAN bus.

coap

The C ABI for CoAP.

codec

The C ABI for wire formats and metered-link packing.

gateway

The C ABI for the LoRaWAN gateway protocols.

gateway_chirpstack

The C ABI for the uplink events a ChirpStack network server publishes.

gateway_network

The C ABI for the network side of one site.

gateway_station

The C ABI for the LoRa Basics Station protocol.

gpio

The C ABI for on-board bus addressing and pin logic.

hal

The C ABI for the bus layer: one I2C bus that a program and every driver on it share.

host

A transport the host implements: callbacks that cross the C boundary.

kit

The C ABI for the goal-named helper math.

ladder

The C ABI for the cost-aware transport ladder.

loopback

The C ABI for the in-process loopback broker.

lora

The C ABI for LoRa link math.

lora_radio

The C ABI for a LoRa radio on a Linux board, or on a simulated chip anywhere.

lora_region

The C ABI for LoRaWAN regional channel plans.

lorawan

The C ABI for LoRaWAN 1.0.x MAC framing.

lorawan_device

The C ABI for a LoRaWAN Class A end device, without a radio.

lorawan_link

The C ABI for what keeps a LoRaWAN link running: the specification revision a device follows, the timings and counts its regional parameters recommend, the back-off that hands back what adaptive data rate tuned away once the network falls silent, and the channel list a join accept can carry.

lorawan_mac

The C ABI for the commands a LoRaWAN network and device configure each other with.

lorawan_packages

The C ABI for the LoRaWAN application layer packages: clock synchronization TS003-2.0.0, fragmented data block transport TS004-2.0.0, remote multicast setup TS005-2.0.0, and firmware management TS006-2.0.0.

lorawan_relay

The C ABI for a LoRaWAN relay, TS011-1.0.1: the wake-on-radio frames an end device and a relay exchange, the uplinks a relay forwards, and the timing that keeps a wake-on-radio preamble short.

lorawan_relay_node

A LoRaWAN relay across the C ABI, TS011-1.0.1.

mavlink

The C ABI for the MAVLink wire protocol.

mavlink_enums

The C ABI for the MAVLink dialect’s named values.

mavlink_protocol

The C ABI for the MAVLink service protocols: mission transfer, commands, and offboard setpoints.

mavlink_schema

The C ABI for MAVLink message shapes: reading and writing a message by field name.

mesh

The C ABI for mesh packet framing.

modbus

The C ABI for Modbus RTU framing.

modbus_client

The C ABI for a Modbus client on a serial port, and the devices it polls.

motion

The C ABI for the motion helpers: chassis kinematics, an arm, odometry, waypoint guidance, the safety gate, and the conversions to servo, ESC, and encoder units.

mqtt

The C ABI for the MQTT transport.

port

The C ABI for one serial port that a program and every driver on it share.

power

The C ABI for power-aware scheduling.

profile

The C ABI for device profiles.

radios

The C ABI for LoRa radio chips.

ros2

The C ABI for the ROS 2 naming and encoding rules.

routing

The C ABI for cost-aware mesh routing.

rules

The C ABI for rules between nodes.

security

The C ABI for device identity and signed telemetry.

sensors

The C ABI for the sensor drivers.

sensors_driver

The C ABI for the sensor drivers that run over an I2C bus.

serial

The C ABI for serial-line packet framing.

session

The C ABI for encrypted, authenticated sessions.

sim

The C ABI for simulated devices.

sync

The C ABI for store-and-forward buffers.

telemetry

The C ABI for device-side telemetry.

transport

The C ABI for composing transports.

update

The C ABI for signed firmware updates.

zenoh

The C ABI for Zenoh key expressions.

Structs

PamojaBuffer

An opaque handle to a byte buffer owned by the caller.

PamojaString

An owned, null-terminated UTF-8 string produced by the library.

Enums

PamojaStatus

The result of a fallible pamoja call.

Functions

pamoja_buffer_data^⚠

Returns a pointer to a buffer’s bytes.

pamoja_buffer_free^⚠

Releases a buffer handle.

pamoja_buffer_len^⚠

Returns the length in bytes of a buffer.

pamoja_last_error_message

Returns the calling thread’s most recent error message, or null if none.

pamoja_string_data^⚠

Returns a pointer to a string’s bytes.

pamoja_string_free^⚠

Releases a string handle.

pamoja_string_len^⚠

Returns the length in bytes of a string, excluding its null terminator.

pamoja_version

Returns the version string of the native pamoja library.