README.Debian for nqc -*- text -*- ===================== NQC now defaults to connect using USB. If you are using an USB infrared tower, you likely will have nothing special to do. If you use a serial device, you need to give the serial port name. Typically, this is /dev/ttyS0 or /dev/ttyS1 for a native port, or /dev/ttyACM0 for a USB serial adapter. RCX for Linux Quick Start ========================= Before you start writing your own programs for the RCX, you need to take care of a few things, explained below. Other than the RCX hardware itself, this package includes almost everything you need to get started. In addition, you'll need the CD that came with your Robotics Invention System (RIS) kit, if you haven't already downloaded the firmware to the RCX. Setup Hardware and Software --------------------------- You need to set up the hardware and software that goes with your RCX before you can use it with the computer. First, take the infrared tower and plug it into an unused USB or serial port. USB port: NQC now uses the USB tower kernel driver by default. In case your device does not appear as /dev/usb/legousbtower0, set the environment variable `RCX_PORT', using the command export RCX_PORT=usb:/dev/usb/legousbtower1 if you use the Bourne shell, or setenv RCX_PORT usb:/dev/usb/legousbtower1 if you use the C shell. You can avoid typing this command each time you log in by adding it to your .profile under the Bourne shell (or .bash_profile under Bash) or to .cshrc under the C shell. Serial port: If you used a serial port, note which one it is. If you're not sure, you can try port 0 first, then port 1 if that doesn't work. If you use a USB serial adapter, the corresponding device should appear in /dev when connected. Once you have determined the serial port, set the environment variable `RCX_PORT', using the command export RCX_PORT=/dev/the_device_name if you use the Bourne shell, or setenv RCX_PORT /dev/the_device_name if you use the C shell. You can avoid typing this command each time you log in by adding it to your .profile under the Bourne shell (or .bash_profile under Bash) or to .cshrc under the C shell. Note that users who are allowed to access the RCX will need permission to access serial ports. One way to do this is by adding these users to the `dialout' group, which by default under Debian GNU/Linux has access to serial devices. You can add user `foo' to group `dialout' with the command `adduser foo dialout'. Please note that such users will have full access to all system serial devices. If this is undesirable then you should implement a different group system for device permissions. Download Firmware ----------------- When you first receive it, the RCX is programmed only with a very simple operating environment that's only suitable for testing it and downloading a new set of firmware. So, the first thing you will want to do is download the standard LEGO firmware. If you've used any of the Windows-based LEGO interface software then you've probably already downloaded the standard firmware and you can skip this step. If you're not sure, then look at what the RCX display panel says immediately after you turn it on. If it says 0000, then the firmware has already been downloaded; if it says something else, then it probably hasn't been. For this step, you'll need the CD that came with your Mindstorms set. Assuming that the CD is mounted on /cdrom, you can download the firmware to the RCX using the following command: # nqc -firmware /cdrom/firm/firm0332.lgo /firm/firm0332.lgo is the name of the firmware file on my CDROM. It is possible that the name of the firmware file on your own CDROM is different; if so, substitute its name in the command above. While the firmware is downloading a number on the panel of the RCX will count up from 0 to about 1600. If you have trouble downloading the firmware, then consider the following: * Did you select the right port? Make sure that the port isn't in use by any other device. * Is the infrared tower working correctly? If it is, then the light on it should turn on when the firmware starts downloading. * Is the near/far switch at the base of the infrared tower set correctly? For near operation the IR tower should be 4-6 inches from the RCX IR receiver. * Is the RCX turned on, with its IR receiver aimed toward the IR tower, 4-6 inches away? Test Compile & Download ----------------------- The file test.nqc is included in this package as an example of a simple NQC program. To compile it and download the resultant program to the RCX, use the command: # nqc -d /usr/share/doc/nqc/test.nqc where nqc is the NQC compiler, -d means to download the result to the RCX, and /usr/share/doc/nqc/test.nqc is the NQC file to compile. If all goes well then you should see the message Downloading Program: complete or similar, from nqc, and NQC will return control to the shell. Test Program ------------ The program that you just downloaded to the RCX is very simple. It activates a motor attached to output A and waits for a button attached to input 1 to be pressed. When the button is pressed, the motor stops and the program terminates. Test the program to verify that it works. If it does, then your RCX is operating correctly. Explore! -------- This package includes a manpage for the nqc program that you can view with the command `man nqc'. You might also want to visit the NQC website, which has documentation and examples for NQC. (Previous versions of this package included these, but this version no longer does because the new versions do not include a license statement, making them impossible for Debian to distribute.) The NQC website is at: https://bricxcc.sourceforge.net/nqc/ This site has the NQC documentation in PDF format, the NQC FAQ, links to related sites, and other NQC resources. There is a NQC tutorial by Mark Overmars on the NQC documentation page. This tutorial doesn't assume any programming experience. It should be a good introduction for those to whom the NQC documentation is too terse. Another good LEGO Mindstorms resource is the Lego Mindstorms Internals page: https://web.archive.org/web/20240620153414/http://www.crynwr.com/lego-robotics/ Have fun!