Your first Mota driver

This walks through writing, installing and changing a driver on a running Mota system in about ten minutes. It uses the sensor template because it needs no hardware; the other classes work the same way. The full reference is the Driver SDK reference.

1. Set up (once)

Mota ships the driver tools and the SDK source in mota-services (mota-driver, /usr/share/mota/driver-sdk). You need a Rust toolchain (1.85 or newer) and a C linker:

sudo apt install build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # or your preferred way to get Rust

The first build downloads the SDK's dependencies from crates.io, so be online for it.

2. Create a driver

mota-driver new room-temp --class sensor

room-temp/
├── Cargo.toml          # depends on /usr/share/mota/driver-sdk
├── mota-driver.toml    # the manifest: name, class, what it matches, [config]
└── src/main.rs         # the driver

The sensor template registers one temperature sensor and publishes the number it finds in a file ([config] path, /run/room-temp/value) whenever it changes. Look at src/main.rs: probe sets things up, run loops, and the TODO marks where your device goes.

Other starting points:

3. Build, package, install

mota-driver package room-temp          # builds and writes mota-driver-room-temp_0.1.0_amd64.deb
sudo mota-driver install ./mota-driver-room-temp_0.1.0_amd64.deb

Installing tells mota-driverd to look again. A virtual driver (this one) starts at once; a hardware driver starts when its device is present.

$ mota-driver list
room-temp 0.1.0 (sensor)
    (virtual): running (restarts 0, unit mota-driver-room-temp-virtual.service)

4. See it work

sudo mkdir -p /run/room-temp
echo 21.5 | sudo tee /run/room-temp/value
busctl --system call org.motaos.Sensors /org/motaos/Sensors org.motaos.Sensors Read s room-temp/main
# dt 21.5 1791904638337
mota-driver logs room-temp

5. Change it

Edit src/main.rs or the manifest, then package and install again; the new version replaces the running one. While developing you can also run the driver directly, outside driverd and its sandbox:

cargo build --release --manifest-path room-temp/Cargo.toml
sudo MOTA_DRIVER_LOG=debug ./room-temp/target/release/room-temp --manifest room-temp/mota-driver.toml

(A hardware driver also takes --device /dev/hidraw3, /dev/bus/usb/001/004 or /sys/bus/pci/devices/0000:03:00.0. A sensor driver run by hand can't publish: org.motaos.Sensors only accepts drivers that driverd started.)

6. Things worth knowing early

• Return the right error. Error::Unsupported from probe means "not my device" and is never retried; Error::NoDevice means it was unplugged. Anything else counts as a crash: driverd restarts the driver, and after 4 crashes in 5 minutes stops it and tells the user (mota-driver enable to try again).
• The sandbox is tight. A driver sees only its own device and its sink: no network (except network drivers), a read-only system, no new privileges. Write state to the sink, not to files.
• Clean up in Drop. Stopping cancels run; sinks remove themselves when dropped.
• PCI and kernel drivers. driverd only takes a PCI device that no kernel driver owns. Without an IOMMU, PCI drivers get registers and interrupts but no DMA.
• Remove a driver with sudo apt remove mota-driver-room-temp, or keep it installed but stopped with mota-driver disable room-temp.

Next

• The example drivers in the Mota source tree, sdk/drivers/: a key remapper, hwmon sensors, a UDP tunnel NIC, a RAM disk, and a PCI driver that moves data by DMA.
• the Driver SDK reference for every API, the manifest, the sandbox and the D-Bus interfaces.