Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

Connecting

no NXT brick found over USB

  • Is the brick switched on? It doesn’t show up on USB while it’s off.
  • On Linux, is the udev rule installed (NixOS, other distributions), and did you replug the brick afterwards? Without a rule, the program has to run as root.
  • On Windows, is the WinUSB driver installed?
  • If the brick ticks and its screen stays empty, it’s in firmware-update mode. Flash the firmware with LEGO’s tools first.

Permission denied (Linux)

The udev rule is missing or hasn’t taken effect. Replug the brick, or log out and in again if you just joined the plugdev group. As a quick workaround, run the program with sudo (details).

The device is busy

Another program (NXT-G, BricxCC, another nxt-rs program, a test running in parallel) has the brick open. Close it. Run hardware tests with --test-threads=1.

Bluetooth: connection refused or times out

  • Is the brick paired and trusted (bluetoothctl info <address>)?
  • Is Bluetooth switched on in the brick’s menu?
  • The brick accepts only one connection from a computer at a time.
  • Restarting Bluetooth on the brick (Bluetooth → On/Off) often helps.

While running

Error::Timeout

The brick didn’t answer in time. Over Bluetooth, or during heavy file transfers, raise the timeout with Brick::with_timeout. After a timeout the connection stays usable, and a late reply is ignored.

The brick switches itself off

It has a sleep timer. Spawn brick.keep_alive_task(interval), or call brick.keep_alive() regularly.

Error::PortTaken

Another device already claims the port. That can be one you still hold, or a clone of the brick. Drop it first, or call release() to reuse its port. brick.port_claims().claimed() shows what’s in use.

Status::ChannelBusy or Status::BusError from an I²C sensor

The sensor isn’t connected, isn’t powered, or the port isn’t configured for I²C. The high-level sensor types configure the port and power the sensor for you. With the low-level API, set the port to SensorType::LowSpeed9V (ultrasonic) or LowSpeed first, and give the sensor about 100 ms to start.

The colour sensor reads nonsense

It needs firmware 1.28 or newer (brick.firmware_version()).

Motors overshoot the requested angle

That’s the firmware: it switches the motor off once the angle is reached. Use .brake(), lower power, or a closed loop on the brick.

Synchronised motors behave oddly after a SyncedPair

Use drive.into_inner().await? to get the motors back. It ends the synchronisation properly.

Status::FileExists when writing a file

files().write never overwrites. Use files().upload, which replaces the file.

Status::NoMoreHandles

Too many files or searches are open. Drop readers and writers you no longer need. With the low-level API, close every handle.

Debugging

With the default tracing feature, every telegram is logged at TRACE level under the target nxt_rs::telegram:

// with tracing-subscriber:
// tracing_subscriber::fmt().with_env_filter("nxt_rs=trace").init();
TRACE nxt_rs::telegram: -> [00, 0b]
TRACE nxt_rs::telegram: <- [02, 0b, 00, 4c, 1d]

Compare these with the protocol reference.