Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
121 lines (85 loc) · 5.22 KB

CONTRIBUTING.md

File metadata and controls

121 lines (85 loc) · 5.22 KB
Raw

Contributing to shurectl

Development Setup

Prerequisites

  • Rust (edition 2024)
  • Linux: libasound2-dev and libudev-dev
  • A supported Shure device for hardware testing, or use --demo for UI-only work

Building

git clone https://github.com/Humblemonk/shurectl.git
cd shurectl
cargo build

Quality Gate

All of the following must pass clean before any commit:

cargo clippy --features probe -- -D warnings && cargo fmt --check && cargo test

The --features probe flag is required: shurectl-probe is feature-gated and would otherwise be skipped by clippy entirely.

There are no warnings — only requirements.

Using AI Assistants

If you use an AI coding assistant (Claude, Copilot, Cursor, etc.), load CLAUDE.md into its context before starting any work.

CLAUDE.md at the repository root is the authoritative source for this project's architecture, protocol rules, domain constraints, and coding standards. It covers the USB HID packet structure, the data flow between modules, forbidden patterns, and the required workflow for adding new commands. An AI working without it will produce code that conflicts with established patterns and is likely to introduce protocol bugs.

Most AI tools support a project instructions file natively:

  • Claude Projects — add CLAUDE.md as project knowledge, or paste it into the system prompt
  • Cursor / Windsurf — rename or symlink to .cursorrules / .windsurfrules, or reference it in your rules file
  • GitHub Copilot — add it to .github/copilot-instructions.md
  • Any chat-based tool — paste the contents at the start of your session

The key rules AI assistants must follow are called out explicitly in CLAUDE.md: the Research → Plan → Implement sequence, the one-change-at-a-time discipline when touching protocol code, and the requirement to run the quality gate before considering any work done.

Project Structure

src/
├── main.rs       — Entry point, event loop, CLI args
├── app.rs        — Application state, focus/tab navigation, DeviceAction events
├── device.rs     — hidapi wrapper; open/send/receive for Shure devices
├── meter.rs      — cpal audio capture; real-time dBFS metering, RollingWindow, PeakWindow
├── presets.rs    — Host-side preset storage: TOML serialisation, load/save/delete, PresetSlot
├── protocol.rs   — USB HID packet encoding, CRC-16/ANSI, command constructors, apply_response()
└── ui.rs         — ratatui TUI rendering (all 5 tabs + help overlay)

All USB HID command byte values, feature addresses, and packet structure details are documented inline in src/protocol.rs.

HID Feature Address Probe

src/bin/probe.rs is a developer tool used for protocol reverse-engineering. It systematically sweeps HID feature addresses across all pages and logs every valid device response, which is how undocumented features are discovered on new or updated hardware.

The probe is read-only — it only sends GET packets, never SET or CONFIRM. It is safe to run against a live device; no settings will be changed.

The probe binary is named shurectl-probe and is gated behind the probe cargo feature, so it is not built by default. This keeps it out of cargo install and Homebrew installs — end users have no reason to have an HID address sweeper in their PATH.

cargo run --bin shurectl-probe --features probe                          # scan MVX2U Gen 2 (default)
cargo run --bin shurectl-probe --features probe -- --pid 0x1013          # MVX2U Gen 1
cargo run --bin shurectl-probe --features probe -- --pid 0x1026          # MV6
cargo run --bin shurectl-probe --features probe -- --also-mix-class      # also sweep mix-class prefix
cargo run --bin shurectl-probe --features probe -- --also-lock-class     # also sweep lock-class
cargo run --bin shurectl-probe --features probe -- --page 0x03           # sweep a specific page only
cargo run --bin shurectl-probe --features probe -- --output results.txt  # write results to file
cargo run --bin shurectl-probe --features probe -- --delay-ms 50         # increase if device misses responses

See the module-level doc comment in src/bin/probe.rs for full details on packet classes and known limitations.

Adding Support for a New Device

  1. Capture USB traffic with usbmon/Wireshark against the official ShurePlus MOTIV Desktop app
  2. Run the probe tool against the device to enumerate responding feature addresses
  3. Cross-reference captures with probe output to confirm address→feature mappings
  4. Add FEAT_* constants, command constructors, and apply_response() branches in protocol.rs
  5. Add typed get_*/set_* methods in device.rs and wire up DeviceAction variants in app.rs
  6. Update KNOWN_FEATURES in src/bin/probe.rs with any newly confirmed addresses

When protocol behaviour is uncertain, capture first — don't guess.

Commit Style

This project follows Conventional Commits. Commit messages should explain the why, not just the what.

feat: add gain lock support for MVX2U Gen 2
fix: correct feature address for MV6 monitor mix SET packet
docs: document HDR_CONSTANT quirk for MV6 lock commands