IMU Kit CLI Reference

Run these commands with the Python interpreter in the virtual environment where you installed reforge-core. The examples below use this common prefix:

bash
python -m reforge_core.imu.tools.<tool>

Use --help after any command or subcommand to show the same information in the terminal.

BLE status: `get_imu_stats.py`

Connects over BLE and prints battery, memory, and active device settings.

Argument	What it does
`--name <name>`	Exact advertised BLE name. Default: `muse_v3`.
`--include-calibration`	Also reads calibration matrices. This is slower and may be unsupported on some firmware; use only for advanced troubleshooting.

bash
python -m reforge_core.imu.tools.get_imu_stats --name muse_v3

USB diagnostics: `usb_diagnostics.py`

Subcommand	Arguments	What it does
`ports`	None	Lists candidate Muse USB serial ports.
`health`	`--port <port>`, `--timeout-s <seconds>`	Checks normal USB command endpoints. If `--port` is omitted, uses the only detected candidate. The default timeout is 2.5 seconds.
`info`	`--port <port>`, `--timeout-s <seconds>`	Prints a read-only USB device/configuration report. Uses the same port and timeout behavior as `health`.
`probe`	`--port <port>`, `--timeout-s <seconds>`	Runs a verbose low-level USB probe for support troubleshooting.

bash
python -m reforge_core.imu.tools.usb_diagnostics ports
python -m reforge_core.imu.tools.usb_diagnostics health --port <port>

Plot and capture: `plot_acquisition.py`

Choose one subcommand:

Subcommand	What it does	Supported rates
`stream`	Opens a live plot. Close the plot window to stop.	25, 50, 100, 200 Hz
`record`	Captures retained streaming history, then plots it.	25, 50, 100, 200 Hz
`logging`	Captures an on-device log, downloads it, then plots it.	25, 50, 100, 200, 400, 800, 1600 Hz

Shared plot arguments

These arguments apply to stream, record, and logging.

Argument	What it does
`--name <name>`	Exact BLE device name. Ignored with `--usb`. Default: `muse_v3`.
`--usb`	Use USB rather than BLE.
`--port <port>`	USB serial port. It is auto-detected when omitted.
`--mode <mode>`	Device data mode. Leave at the default `DATA_MODE_9DOF_TIMESTAMP`; this is the supported customer mode.
`--gyro-full-scale-dps <245	500
`--accel-full-scale-g <4	8
`--mag-full-scale-gauss <4	8
`--hdr-accel-full-scale-g <100	200
`--frequency <Hz>`	Sampling rate for the selected subcommand. You can also use the corresponding `DATA_FREQ_*` name.

Do not use full-scale override arguments over USB. Change full scales over BLE with configure_device.py full-scale instead.

Live streaming arguments

stream also accepts these options:

Argument	What it does
`--direct <true	false>`
`--read-timeout-s <seconds>`	Maximum time to wait for a stream read. Default: 1 second.
`--window-seconds <seconds>`	Width of the rolling live-plot window. Default: 10 seconds.
`--plot-fps <frames-per-second>`	Maximum plot refresh rate. Default: 20.
`--initial-samples-to-skip <count>`	Ignores initial decoded samples to avoid startup transients. Default: 1.

bash
python -m reforge_core.imu.tools.plot_acquisition stream \
  --usb --port <port> --frequency 200

Fixed-duration capture arguments

record and logging also accept these options:

Argument	What it does
`--record-seconds <seconds>`	Capture duration when automatic stop is used. Default: 5 seconds.
`--stop-on-enter <true	false>`
`--output <path>`	Writes the finished plot before displaying it. The file extension selects the format, such as `.svg` or `.png`.

bash
python -m reforge_core.imu.tools.plot_acquisition logging \
  --usb --port <port> --frequency 800 --record-seconds 12 \
  --stop-on-enter false --output imu-logging.svg

The plots show acceleration in m/s^2, angular velocity in rad/s, and timestamp spacing.

Persistent configuration: `configure_device.py`

Rename the kit: `device-name`

Argument	What it does
`--port <port>`	Required USB serial port.
`--new-name <name>`	Required new BLE name. It must be non-empty and shorter than 16 characters.
`--timeout-s <seconds>`	USB command timeout. Default: 2.5 seconds.
`--restart-application`	Restarts the device application after verified readback so the new name is advertised.

bash
python -m reforge_core.imu.tools.configure_device device-name \
  --port <port> --new-name muse_v3_lab_a --restart-application

Auto-standby: `auto-standby`

Argument	What it does
`--name <name>`	Exact BLE device name. Default: `muse_v3`.
`--enable`	Enables auto-standby. Cannot be combined with `--disable`.
`--disable`	Disables auto-standby. Cannot be combined with `--enable`.

With neither --enable nor --disable, the tool reads the current setting.

bash
python -m reforge_core.imu.tools.configure_device auto-standby \
  --name muse_v3_lab_a --enable

Measurement ranges: `full-scale`

Argument	What it does
`--name <name>`	Exact BLE device name. Default: `muse_v3`.
`--transport <ble	usb>`
`--port <port>`	USB serial port; required only with `--transport usb`.
`--usb-baudrate <baud>`	USB baudrate hint. Default: 115200.
`--show-only`	Prints the active configuration without changing it.
`--gyro-dps <245	500
`--accel-g <4	8
`--mag-gauss <4	8
`--hdr-g <100	200

bash
python -m reforge_core.imu.tools.configure_device full-scale \
  --name muse_v3_lab_a --show-only

Only use BLE to change full-scale settings. USB full-scale writes are not supported by current firmware.

Support-only tools

check_data_integrity.py, run_imu_diagnostics.py, and probe_sensor_full_scale_limits.py are advanced validation and support tools. Use them with Reforge support rather than as part of normal setup or recording.

IMU Kit CLI Reference

BLE status: get_imu_stats.py

USB diagnostics: usb_diagnostics.py

Plot and capture: plot_acquisition.py