lighthouse-manager

Control SteamVR Lighthouse base stations (V1 & V2) via Bluetooth LE from the command line.

Overview

lighthouse-manager is a Rust CLI tool that lets you discover, power on/off, and identify SteamVR Lighthouse base stations wirelessly via Bluetooth Low Energy. It scans for nearby devices using BLE advertising data, stores them in a local JSON database, and communicates with both Lighthouse V1 (HTC BS-*) and V2 (LHB-*) stations.

Features

🔍 Discover — Scan the air for nearby Lighthouse base stations via BLE
⚡ Power On/Off — Turn all managed lighthouses on or off in parallel
💡 Identify (blink) — Make a V2 Lighthouse flash its LED by index
💾 Persistent storage — Database backed by a local JSON file (via XDG dirs)
✅ Cross-platform — Linux, macOS, and Windows (requires BLE adapter)
🔄 Autostart (SteamVR) — Auto-power lighthouses on SteamVR launch, off on exit

Installation

From crates.io (recommended)

cargo install lighthouse-manager

Then run lighthouse-manager --help to verify the installation.

Prebuilt binaries

Download the latest release binary for your platform from GitHub Releases.

From source

git clone https://github.com/atomicflag/lighthouse-manager.git
cd lighthouse-manager
cargo build --release
./target/release/lighthouse-manager --help

Usage

All commands require a working Bluetooth adapter. Run with -v / -vv for debug/trace logs, or set the RUST_LOG environment variable directly.

Discover nearby Lighthouses

Scans for BLE-advertising Lighthouse base stations and saves them to the local database (newly discovered units are marked unmanaged by default):

# Default 10-second scan
lighthouse-manager discover

# Custom scan duration
lighthouse-manager discover -d 20

List known Lighthouses

# Show all lighthouses in the database
lighthouse-manager list

# Show only managed lighthouses
lighthouse-manager list --managed

# Output as pretty JSON
lighthouse-manager list --json

Set managed status

Mark one or all lighthouses as managed or unmanaged. Only managed lighthouses are affected by power-on / power-off.

# Mark a specific lighthouse as managed
lighthouse-manager set-managed 0 true

# Mark a specific lighthouse as unmanaged (ignored by power commands)
lighthouse-manager set-managed 1 false

# Mark all lighthouses in the database as managed
lighthouse-manager set-managed all true

Power On / Off

# Power on all managed lighthouses simultaneously
lighthouse-manager power-on

# Sleep (power off) all managed lighthouses
lighthouse-manager power-off

Identify a Lighthouse (V2 only)

Causes a V2 base station to flash its LED so you can locate it physically:

# Flash the lighthouse at index 0 in the database
lighthouse-manager identify 0

# Alias: same as above
lighthouse-manager blink 0

Autostart (SteamVR)

Automatically turn your lighthouses on when SteamVR starts and power them off when it shuts down. Configure once so you never have to think about base stations again.

# Enable — lighthouses turn on when SteamVR launches, off when it exits
lighthouse-manager autostart on

# Disable — reverts to manual control only
lighthouse-manager autostart off

Logging

Control verbosity globally with -v / -vv, or use RUST_LOG:

# Equivalent to -v
RUST_LOG=lighthouse_manager=debug lighthouse-manager list

# Trace-level logging for debugging BLE issues
RUST_LOG=lighthouse_manager=trace lighthouse-manager discover

Architecture

src/
├── lib.rs               # Library crate (re-exports modules)
├── cli/                 # CLI binary entry point (clap Parser + subcommand dispatch)
│   └── main.rs
├── ovr/                 # Companion SteamVR binary (auto-launch target)
│   └── main.rs
├── bluetooth.rs         # Bluetooth adapter management via btleplug
├── lighthouse.rs        # Lighthouse device model & version detection
├── protocol.rs          # BLE GATT communication protocol layer
├── storage.rs           # Local JSON database (XDG-compliant paths)
└── commands/
    ├── autostart.rs     # Auto-on/off lighthouses when SteamVR starts/stops
    ├── discover.rs       # BLE scan → save discovered units
    ├── list.rs           # Database listing with filtering
    ├── set_managed.rs    # Set managed/unmanaged status by index or "all"
    ├── power.rs          # Parallel power on/off via GATT writes
    └── identify.rs       # V2 LED flash via GATT characteristic

Building from Source

Prerequisites

Rust 1.85+ (rustup recommended)
A Bluetooth 4.0+ adapter (Linux: bluez; macOS / Windows: native BLE stack)

Compile

# Development build (fast iteration)
cargo build

# Release build (optimized, smaller binary)
cargo build --release

Testing

Run the full test suite:

cargo test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

lighthouse-manager 0.1.0