Build Status Coverage Status Dependency Status Code Climate Inline docs

An object oriented interface for talking to the LEGO NXT brick.


Add this line to your application's Gemfile:

gem 'lego_nxt'

And then execute:

$ bundle

Or install it yourself as:

$ gem install lego_nxt

Mac OS X

You'll need a copy of libusb and its development library installed.

One easy way to do this is with homebrew:

brew install libusb

To get the bluetooth working, it's pretty easy:

  1. Pair your NXT to your computer.
  2. In "Bluetooth Preference" in "System Preferences":
    1. Click on "NXT" (This may be different if you renamed your NXT brick).
    2. Click on the gear below the list box.
    3. Select "Edit Serial Ports..."
    4. Press the "+" button. It should fill in as:
    5. Name: NXT-DevB
    6. Protocol: RS-232
    7. Service: Dev B
    8. Click "Apply"

You should now have two new devices in your /dev directory:

  • /dev/tty.NXT-DevB -- This is what we'll use to talk to the NXT brick.
  • /dev/cu.NXT-DevB


You need a copy of libusb's development libraries.'

TODO: Add instructions for setting up bluetooth.


WARNING: I only use Windows at work. I don't own a personal copy and therefore don't use it. However, my goal is to make this work on Windows with the help of people like you. So find me on [] IRC as docwhat or via if you have problems. Or file an issue!

The libusb gem has support for windows built in; it ships with a libusb.dll ready to use.

You may need a USB driver. I'm hopeful that if you installed the lego NXT-G environment (the CD that came with Mindstorms) that you should be ready to go. If not, read the libusb gem's docs. They suggest something called Zadig.

TODO: Add instructions for setting up bluetooth. Until then, see this helpful document


The easiest way to get started is to experiment with some of the examples. Use the run script in the examples directory to run examples (-l will list them).

examples/run -l
  * motor
  * piano
  * scale

examples/run piano


The documentation is written for yard. Install the yard gem and you can use the yri command to browse the documentation.

Alternatively, you can read the online documentation.


Most tests will work without owning a NXT brick

To run all the tests, including the ones that require a NXT brick, then you need to plugin your NXT brick, power it on, and run rake usb:spec or to run just the NXT tests use rspec --tag needs_nxt


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Reference Material

Useful if you're going to be hacking on the code:

  • libusb - The docs in particular.
  • LEGO's Support Files - In particular:
    • The Bluetooth Developer Kit -- Appendix 1: LEGO MINDSTORMS NXT Communication protocol
    • Software Development Kit -- The PDF contains a description of the Executable File Specification
  • Related troubleshooting