quartz

Crystal-native dev framework for Flipper Zero.

Docs are the README + ROADMAP.md + docs/. A standalone docs site lands with shipr in a later phase.

Why quartz?

• Offline-first. No browser, no cloud, no account. Your device, your laptop, a serial cable.
• Crystal-native. Single static binary, no Python runtime, no node_modules.
• Federated signal taps. .sig bundles are designed to be shared between trusted peers, not uploaded to someone else's lab.
• Honest scope. Phase 0 is scaffolding. Most subcommands print todo today. See ROADMAP.md.

Install

git clone https://github.com/kdairatchi/quartz && cd quartz
shards install
shards build quartz --release

Requires Crystal >= 1.19.1.

Quick start

quartz devices                             # list attached Flipper devices
quartz rpc ping [port]                     # protobuf ping round-trip (works)
quartz build ./my-app --variant momentum   # compile a FAP via ufbt wrap (works)
quartz signal info ./foo.sub               # parse a .sub/.nfc/.ir/.ibtn/.rfid file
quartz signal id   ./foo.sub               # print canonical content id (q1:sha256…)
quartz connect /dev/ttyACM0                # attach to a device (planned — stub)
quartz repl                                # interactive session       (planned — stub)
quartz init ./my-app                       # scaffold a new FAP        (planned — stub)
quartz sim  run ./my-app                   # host-side furi-HAL simulator (Crystal-DSL today)
quartz tap  …                              # federated signal taps     (planned — Phase 4)

All CLI subcommands: init connect repl devices build rpc sim signal tap. Current status per subcommand is tracked in ROADMAP.md and docs/COMPATIBILITY.md.

Host-side simulator (quartz sim)

Phase 3 ships a furi-HAL simulator under Quartz::Simulator — a Crystal-native shim for GUI, input, storage, notification, and radio stubs. Use it to unit-test FAP-shaped app logic on your laptop, no device attached.

require "quartz"

app = Quartz::Simulator::App.new("counter") do |ctx, event|
  ctx.gui.draw_str(8, 20, "HELLO")
  ctx.exit! if event.try(&.key) == Quartz::Simulator::InputKey::Back
end

ctx = app.run([
  Quartz::Simulator::InputEvent.new(
    Quartz::Simulator::InputType::Press,
    Quartz::Simulator::InputKey::Back,
  ),
])
ctx.gui.screenshot # => 1024-byte Flipper-layout bitmap

See examples/sim-counter/main.cr for a working app with specs.

The quartz sim run <path> CLI is a stub — loading compiled C FAPs lands in phase 3.1. Radio stubs (subghz, nfc, ir) record calls but never transmit.

Configuration

quartz reads ~/.config/quartz/config.yml at startup (respects $XDG_CONFIG_HOME). Every field is optional — unset fields fall back to built-in defaults.

# ~/.config/quartz/config.yml
# default_port: /dev/ttyACM0
default_variant: stock        # stock | rm | xfw
default_channel: release      # release | rc | dev
ai_backend: ollama            # ollama | claude
ollama_url: http://localhost:11434
ollama_model: qwen2.5-coder:7b
sdk_cache: ~/.quartz/sdk
tap_registry: []

Precedence (low to high): defaults → config file → environment vars (QUARTZ_*) → CLI flags.

Logging is controlled by QUARTZ_LOG=debug|info|warn|error (default info), or with -v / -vv / -vvv CLI flags which override the env var. Output is colored on a TTY and plain when piped.

List attached devices:

quartz devices

Status

What works today:

• Serial transport with termios raw-mode + VMIN/VTIME (Quartz::Serial)
• Sim transport (in-memory, for tests)
• BLE transport stub (interface only, raises NotImplementedError)
• RPC: varint framing + protobuf envelope + rpc ping round-trip
• SDK cache layout + Variant registry (stock / unleashed / momentum / roguemaster)
• quartz build wraps ufbt and returns the emitted .fap
• application.fam parser (tokenizer, no exec)
• Signal parsers (DATA ONLY) for .sub .nfc .ir .ibtn .rfid + content id
• quartz devices enumerates /dev/ttyACM* on Linux/macOS
• Structured logging (QUARTZ_LOG, -v/-vv/-vvv), YAML config, env overrides
• AI router with Ollama backend live, Claude stub
• 61 specs green, ameba lint clean

Subcommand stubs (print todo / not yet implemented): init, connect, repl, sim, tap.

What's coming (see ROADMAP.md):

• Phase 1 — termios-correct serial + Flipper RPC protobuf (quartz rpc ping ~9h per docs/PROTOBUF_PLAN.md)
• Phase 2 — quartz build replaces ufbt
• Phase 3 — quartz sim against furi-HAL shim
• Phase 4 — signal capture/replay + federated .sig taps
• Phase 5 — TUI + editor extensions

Security

Report suspected vulnerabilities privately — see SECURITY.md.

License

MIT. See LICENSE.