firm-client 1.2.2

Python bindings for FIRM Client using Rust

FIRM-Client

A modular Rust library for parsing FIRM data packets, with bindings for Python and WebAssembly.

Project Structure

The project is organized as a Cargo workspace with the following crates:

• firm_core: The core no_std crate containing the packet parser, CRC logic, and data structures. This is the foundation for all other crates and can be used in embedded environments.
• firm_rust: A high-level Rust API that uses serialport to read from a serial device and provides a threaded client for receiving packets.
• firm_python: Python bindings for the Rust client.
• firm_typescript: WebAssembly bindings and TypeScript code for using the parser in web applications.

Philosophy

The goal of FIRM-Client is to provide a single, efficient, and correct implementation of the FIRM parser that can be used across different ecosystems (Rust, Python, Web/JS, Embedded). By centralizing the parsing logic in firm_core, we ensure consistency and reduce code duplication.

Building

Prerequisites

• Rust (latest stable)
• Python 3.10+ (for Python bindings)
• maturin (for building Python wheels)
• wasm-pack (for building WASM)
• Node.js/npm (for TypeScript)

Build Instructions

We assume that you are using a Unix-like environment (Linux or macOS).

Windows users may need to adapt some commands (we will mention where this is the case), or use WSL (Windows Subsystem for Linux) for best compatibility.

Make sure you have Cargo and uv installed.

You would also need npm if you want to test the web/TypeScript bindings. Install it and Node.js here: https://nodejs.org/en/download/

1. Build all Rust crates:

   cargo build
   

2. Build Python bindings:

   cargo build -p firm_python
   uv sync
   # or to build a wheel
   uv run maturin build --release
   

3. Build WASM/TypeScript:

   cd firm_typescript
   npm install
   npm run clean
   npm run build
   
   # For testing the code with examples/index.html
   npx serve .
   

Usage

Rust

Add firm_rust to your Cargo.toml.

use firm_rust::FirmClient;
use std::{thread, time::Duration};

fn main() {
    let mut client = FIRMClient::new("/dev/ttyUSB0", 2_000_000, 0.1);
    client.start();

    loop {
        while let Ok(packet) = client.get_packets(Some(Duration::from_millis(100))) {
            println!("{:#?}", packet);
        }
    }
}

Python

You can install the library via pip (once published) or build from source.

pip install firm-client

This library supports Python 3.10 and above, including Python 3.14 free threaded.

from firm_client import FIRMClient
import time

# Using context manager (automatically starts and stops)
with FIRMClient("/dev/ttyUSB0", baud_rate=2_000_000, timeout=0.1) as client:
    client.get_data_packets(block=True)  # Clear initial packets
    client.zero_out_pressure_altitude()
    while True:
        packets = client.get_data_packets()
        for packet in packets:
            print(packet.timestamp_seconds, packet.raw_acceleration_x_gs)

Web (TypeScript)

todo: Add usage example.

Publishing

This is mostly for maintainers, but here are the steps to publish each crate to their respective package registries:

Rust API (crates.io)

todo (idk actually know yet)

Python Bindings (PyPI)

We need to to first build wheels for each platform, right now the workflow is to do this locally and then upload to PyPI. At the minimum, we build for Linux x86_64 and aarch64 for python versions 3.10+, including free threaded wheels.

1. Always bump the version in firm_python/Cargo.toml before publishing.

2. Build the wheels

# If you're on Linux
./compile.sh

# If you're on Windows
.\compile.ps1

This will create wheels in the target/wheels directory, for Python versions 3.10 to 3.14, for both x86_64 and aarch64.

3. Make sure you also have a source distribution:

uv run maturin sdist

4. We will use uv to publish these wheels to PyPI. Make sure you are part of the HPRC organization on PyPI, so you have access to the project and can publish new versions.

uv publish target/wheels/*

This will ask for PyPI credentials, make sure you get the token from the website.

TypeScript Package (npm)

1. Always bump the version in firm_typescript/Cargo.toml and package.json before publishing. Make sure they match.

2. Login to npm

npm login

3. Publish it

npm publish

(Ensure the version in package.json is bumped before publishing.)

License

Licensed under the MIT License. See LICENSE file for details.