hexaTuneProto

Unified Rust protocol library for the hexaTune AT-over-SysEx-over-USB-MIDI communication stack. One codebase, two targets: embedded firmware (no_std) and Flutter mobile app (FFI).

hexaTune LLC — MIT License

Quick Start

# Prerequisites: Rust toolchain, just (task runner)
cargo install just    # if not already installed

just setup            # configure git hooks (commit-msg + pre-push)
just build            # build workspace (dev)
just test             # run all tests
just ci               # full CI pipeline (lint + build + test + no_std check)

Workspace Structure

hexaTuneProto/
├── crates/
│   ├── hexa-tune-proto/              # Core protocol — no_std, zero dependencies
│   │   └── src/
│   │       ├── at.rs                 # AT command parse / encode
│   │       ├── sysex.rs              # SysEx frame / unframe
│   │       ├── usb_midi.rs           # USB MIDI 4-byte packetize / depacketize
│   │       ├── stream.rs             # Streaming state machine decoder
│   │       ├── codec.rs              # Full pipeline helpers
│   │       └── error.rs              # ProtoError enum (#[repr(u8)])
│   │
│   ├── hexa-tune-proto-embedded/     # Embedded adapter — typed commands, dispatch
│   │   └── src/
│   │       ├── command.rs            # HexaCommand enum + TryFrom
│   │       ├── dispatch.rs           # Command resolution helper
│   │       └── error.rs              # HexaError (domain errors)
│   │
│   └── hexa-tune-proto-ffi/          # FFI adapter — cdylib for Flutter
│       ├── src/c_api.rs              # extern "C" functions (htp_*)
│       ├── include/                  # Generated C header
│       └── cbindgen.toml             # Header generation config
│
├── scripts/                          # Shell scripts for all tasks
├── docs/                             # Detailed documentation
├── justfile                          # Task runner (delegates to scripts/)

Crates

Crate	Target	Description
hexa-tune-proto	no_std	Core protocol: AT, SysEx, USB MIDI, streaming decoder
hexa-tune-proto-embedded	no_std	Typed command enums, dispatch helpers, heapless wrappers
hexa-tune-proto-ffi	std	C-ABI functions for Flutter / desktop FFI integration

Protocol Stack

┌─────────────────────────┐
│   AT Command Layer      │  AT+FREQ=5#440#1000#1
├─────────────────────────┤
│   SysEx Framing         │  F0 … payload … F7
├─────────────────────────┤
│   USB MIDI Packets      │  [CIN, b1, b2, b3] × N
└─────────────────────────┘

Data flows through these layers in both directions — the same functions are used on both the Flutter (via FFI) and embedded (via crate dependency) sides.

Commands (just)

All just commands delegate to shell scripts in scripts/:

Command	Description
just setup	Setup dev environment (git hooks)
just build [dev|release|ffi]	Build workspace or specific target
just test [all|proto|embedded|ffi]	Run tests for workspace or crate
just lint [all|clippy|fmt|fix]	Run clippy / check format / auto-fix
just check-nostd	Verify no_std compilation
just gen-header	Generate C header via cbindgen
just ci	Full pipeline: lint → build → test → no_std
just clean	Remove build artifacts
just build-android [debug|release]	Cross-compile FFI for Android
just build-ios [debug|release]	Cross-compile FFI for iOS
just changelog [version]	Generate changelog from commits

CI/CD

Workflow	Trigger	Description
CI	Push to any branch, PRs	Lint, build, test, no_std check
Release	Push to release/v*	Build artifacts, GitHub Release, cargo publish

Release flow: develop → release/vX.Y.Z branch → push triggers CD → tag created → GitHub Release with Android/iOS/Linux binaries + changelog → crates.io publish.

Required secret: CARGO_REGISTRY_TOKEN for crates.io publishing.

Documentation

Technical

Document	Description
Architecture	Crate hierarchy, design decisions, data flow
Protocol	AT command format, SysEx framing, USB MIDI packets
FFI Guide	C API reference, Dart integration examples
Embedded Guide	Firmware integration, StreamDecoder usage, memory budget

Process

Document	Description
Branch Strategy	Branching model, merge rules, protection
Commit Strategy	Conventional commit format and types
PR Strategy	Pull request conventions and workflow
Labelling Strategy	Issue and PR label taxonomy
Contributing	How to contribute to the project
Code of Conduct	Community behavior standards
Security	Vulnerability reporting policy
Support	How to get help
Community	Community guidelines
Contact	Communication channels

Features

The core crate uses feature flags for optional functionality:

Feature	Default	Description
(none)	✅	no_std, zero dependencies — bare-metal ready
std	—	Adds Display and std::error::Error impls
defmt	—	Adds defmt::Format for embedded debug logging

Project Files

File	Description
AGENTS.md	AI agent rules and project conventions
LICENSE	MIT License

License

MIT — hexaTune LLC