MIDI-BLE-RTCTL(1)

NAME
midi-ble-rtctl - control and diagnostics CLI for midi-ble-rt

SYNOPSIS
midi-ble-rtctl COMMAND [ARGS...]
midi-ble-rtctl -v|--version
midi-ble-rtctl -vv|--version-verbose
midi-ble-rtctl help [COMMAND]

DESCRIPTION
midi-ble-rtctl is the command-line control and diagnostics tool for midi-ble-rt. It can inspect BlueZ devices, prepare BLE-MIDI devices, write local configuration, talk to a running midi-ble-rtd(1) instance through its local control socket, and print runtime diagnostics.

GLOBAL OPTIONS

-h, --help
    Print global help.

-v, --version
    Print CLI version and exit.

-vv, --version-verbose
    Print version plus compiled feature summary and exit.

BLUEZ AND DEVICE COMMANDS

list
    List known BlueZ devices.

scan
    Run BlueZ discovery, then list devices.

info
    Show one device's BlueZ properties.

probe
    Connect if needed and inspect BLE-MIDI GATT objects.

pair
    Pair a device through BlueZ Device1.Pair.

trust
    Set BlueZ Device1.Trusted=true.

untrust
    Set BlueZ Device1.Trusted=false.

connect
    Prepare a BLE-MIDI device using BlueZ. This may pair, trust, connect, probe, and optionally write local configuration depending on command options.

configure
    Write a local midi-ble-rtd(1) configuration file.

disconnect
    Disconnect a BlueZ device.

forget
    Remove a device from the BlueZ cache or pairing records.

DAEMON CONTROL COMMANDS
These commands require a running midi-ble-rtd(1) instance. They use the daemon control socket below $XDG_RUNTIME_DIR/midi-ble-rt/control.sock.

daemon-ping
    Ping the running daemon. Expected reply: OK PONG.

daemon-status
    Print one daemon runtime status line.

daemon-list
    List configured daemon sessions.

daemon-connect DEVICE
    Ask the daemon to connect a configured device. DEVICE must match a configured id or Bluetooth address.

daemon-disconnect DEVICE
    Ask the daemon to disconnect a configured device.

daemon-recheck DEVICE
    Ask the daemon to recheck a configured device.

DAEMON STATUS FIELDS
daemon-status prints an OK STATUS line with key-value fields.

devices
    Number of configured device sessions known to the daemon.

streaming
    Number of configured device sessions currently in STREAMING state.

alsa_tx_thread
    Shared ALSA Sequencer TX thread state: running or stopped.

rx_workers, tx_workers
    Number of per-device runtime worker threads currently allocated.

rtkit
    Whether RTKit scheduling was requested by daemon configuration: on or off.

rtkit_priority
    Configured RTKit realtime priority after daemon-side clamping.

rtkit_rx, rtkit_tx
    Whether RTKit is enabled for RX and TX runtime worker classes: on or off.

lifecycle_busy
    Whether the daemon lifecycle/control-plane queue is currently executing a command: yes or no.

lifecycle_queue
    Number of pending lifecycle/control-plane commands.

Example:

OK STATUS devices=1 streaming=1 alsa_tx_thread=running rx_workers=1 tx_workers=1 rtkit=on rtkit_priority=1 rtkit_rx=on rtkit_tx=off lifecycle_busy=no lifecycle_queue=0

DIAGNOSTICS COMMANDS

stats [--path PATH]
    Print one formatted stats snapshot. The default path is $XDG_RUNTIME_DIR/midi-ble-rt/stats.tsv.

top [--path PATH] [--interval MS]
    Repeatedly print stats snapshots.

latency [--path PATH]
    Print one latency diagnostics snapshot. The default path is $XDG_RUNTIME_DIR/midi-ble-rt/latency.tsv.

latency-top [--path PATH] [--interval MS]
    Repeatedly print latency diagnostics snapshots.

EXAMPLES
Scan for BLE-MIDI devices:

midi-ble-rtctl scan --timeout 10 --midi-only

Prepare a Roland GO:KEYS profile and write configuration:

midi-ble-rtctl connect CB:81:F4:62:FF:07 --profile roland_gokeys --write-config

Check daemon state:

midi-ble-rtctl daemon-status

Show detailed help for daemon status fields:

midi-ble-rtctl help daemon-status
midi-ble-rtctl daemon-status --help

SEE ALSO
midi-ble-rtd(1), aconnect(1), aplaymidi(1), aseqdump(1)

BUGS
Report bugs at the project repository: https://github.com/mwprado/midi-ble-rt.