Installation

Set up a development environment (optional)

If you use devenv, a minimal setup gives you Rust plus the system libraries the bluetooth feature needs. In a new project directory, run devenv init, then replace the generated devenv.nix with:

{
  pkgs,
  lib,
  config,
  inputs,
  ...
}: {
  languages.rust.enable = true;
  packages = with pkgs; [pkg-config dbus];
}

Enter the environment with devenv shell (or automatically, with direnv). pkg-config and dbus are only needed for the bluetooth feature, but are harmless otherwise. Without devenv, install Rust with rustup.

Add the crate

nxt-rs is not on crates.io yet. Add it from its git repository:

cargo new my-robot
cd my-robot
cargo add nxt-rs --git https://forge.wvffle.net/wvffle/nxt-rs.git

The default features include USB support. For Bluetooth or serial ports, enable the matching feature:

cargo add nxt-rs --git https://forge.wvffle.net/wvffle/nxt-rs.git --features bluetooth   # Linux, via BlueZ
cargo add nxt-rs --git https://forge.wvffle.net/wvffle/nxt-rs.git --features serial      # any OS, via a Bluetooth serial port

Your Cargo.toml then contains:

[dependencies]
nxt-rs = { git = "https://forge.wvffle.net/wvffle/nxt-rs.git", features = ["serial"] }

See Cargo features for the full list.

Platform setup

USB access needs a little setup on Linux and Windows. macOS works out of the box.

Linux

On Linux, only root may access USB devices by default. Give your user access with a udev rule (recommended), or run your programs as root (see Without udev rules).

NixOS

Add the rule to your system configuration:

# configuration.nix
services.udev.extraRules = ''
  # LEGO MINDSTORMS NXT
  SUBSYSTEM=="usb", ATTRS{idVendor}=="0694", ATTRS{idProduct}=="0002", MODE="0660", TAG+="uaccess"
'';

Apply it with sudo nixos-rebuild switch, then unplug and replug the brick. The uaccess tag gives the user logged in at the machine access.

For Bluetooth, enable BlueZ with hardware.bluetooth.enable = true;. The bluetooth feature also needs dbus and pkg-config at build time. The devenv setup above provides them, or use nix-shell -p pkg-config dbus.

Other Linux distributions

Install the udev rule that ships with the crate (contrib/70-lego-nxt.rules in the repository):

SUBSYSTEM=="usb", ATTRS{idVendor}=="0694", ATTRS{idProduct}=="0002", MODE="0660", GROUP="plugdev", TAG+="uaccess"

sudo cp contrib/70-lego-nxt.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules

Then unplug and replug the brick. The uaccess tag gives the logged-in user access. On headless machines, where nobody is logged in at the console, the plugdev group grants access instead. Add yourself with sudo usermod -aG plugdev $USER and log in again. Some distributions, such as Fedora and Arch, don’t have that group: create it first with sudo groupadd plugdev.

For Bluetooth, BlueZ must be installed and running (sudo systemctl enable --now bluetooth). The bluetooth feature also needs the D-Bus development files and pkg-config:

Without udev rules: run as root

If you’d rather not install a udev rule, for example on a machine you don’t administer permanently, build as your normal user and run only the finished program as root:

cargo build --release
sudo ./target/release/my-robot

Don’t run cargo itself with sudo. Root usually has no Rust toolchain, and the build would leave root-owned files in target/.

To keep using cargo run (and cargo test), tell cargo to start the compiled program through sudo. Create .cargo/config.toml in your project:

[target.'cfg(target_os = "linux")']
runner = "sudo"

Cargo now builds as you and runs sudo target/debug/my-robot, asking for your password when needed. To pass environment variables such as RUST_LOG through, use runner = ["sudo", "--preserve-env=RUST_LOG"].

Only USB needs this. Bluetooth access goes through BlueZ and works as a normal user. A udev rule is still the better long-term solution: programs running as root can do anything to your system.

Windows

The brick needs the generic WinUSB driver. LEGO’s own driver isn’t supported. Install it with Zadig: plug in the brick, choose Options → List All Devices, select LEGO MINDSTORMS NXT, choose WinUSB and click Replace Driver.

macOS

Nothing to do.

Check that it works

Plug in the brick, switch it on, and run:

use nxt_rs::prelude::*;

fn main() -> nxt_rs::Result<()> {
    let brick = Brick::usb_first().block()?;
    println!("Connected to {}", brick.name().block()?);
    Ok(())
}

If you see no NXT brick found, check Troubleshooting.

Next: Connecting your brick.