nqc

nqc(1)                      General Commands Manual                     nqc(1)



NAME
       nqc - A simple C-like language for Lego's RCX programmable brick

SYNOPSIS
       nqc [ options ] [ actions ] [ - | filename ] [ actions ]

DESCRIPTION
       NQC stands for Not Quite C, and is a simple language for programming
       the LEGO RCX.  The preprocessor and control structures of NQC are very
       similar to C.  NQC is not a general purpose language -- there are many
       restrictions that stem from limitations of the standard RCX firmware.

       This man page does not attempt to describe the NQC programming language
       or the RCX API, merely the options of the nqc command-line program.
       References to more complete documentation are given at the end of this
       man page.


       nqc is normally used to process a single source file given as filename.
       You can also read from stdin by using - instead.  If the filename ends
       in .rcx, it is assumed to be a RCX image file from a previous compile,
       and will be used as is (for downloading or listing).


OPTIONS
       -1     use NQC 1.x compatibility mode.  The RCX API changed
              significantly with version 2.0.  This flag makes the compiler
              grok old code.

       -Ttarget
              generate code and use communications methods for "smart bricks"
              other than the RCX.  Currently, can be either CM or Scout.

       -d     download program to the RCX.  When this option is given, code is
              sent directly over the serial port to the brick and no output
              file is generated by default.

       -n     prevent the standard nqc.h file from being automatically
              included.

       -Dsym[=value]
              define macro sym as value.

       -E[filename]
              write compiler errors to filename (or to stdout, if no name
              specified) instead of to stderr.

       -Ipath search path for include files.  Multiple directories should be
              seperated as normal for the platform (under Linux / Unix, that'd
              be "").  Can also be set with the NQC_INCLUDE environment
              variable.

       -L[filename]
              generate a human-readable bytecode listing to filename (or to
              stdout) instead of generating a binary file.

       -Ooutfile
              output code to outfile.  This option causes a file to be written
              even if -d or -L is also given.  If no filename is specified,
              the output file will have the same basename as the input file
              but an extension of .rcx instead of .nqc.

       -Sportname
              use serial port portname.  Under Linux, /dev/ttyS0 is the
              default.  (This will differ on other platforms.)  The port can
              also be specified via the RCX_PORT environment variable, but the
              command line option takes precedence.

       -Usym  undefine macro sym.

ACTIONS
       Actions look similar to options, but they have some subtle differences.
       In general, options set up things (such as a serial port) for later
       use, while actions cause something to happen.  Actions are executed in
       the order that they appear on the command line.  In addition, actions
       appearing before the source file happen before compilation, while
       actions after the source file happen after compilation.  For historical
       reasons, downloading the compiled file (-d) works as an option and not
       an action.

       -run   run the current program.  This causes the program selected on
              the RCX to execute.

       -pgm number
              select program number.  This changes the program slot on the
              RCX.

       -datalog
              get the datalog from the RCX and print it to stdout.

       -datalog-full
              same as -datalog but with more verbose output.

       -near  set the IR port to short-range mode.

       -far   set the IR port to long-range mode.

       -watch time
              set the RCX's clock to the specified time.  If you use now, then
              the host's current time is used.

       -firmware filename
              downloads the firmware to the RCX.  You'll need the official
              Lego RCX firmware from the CD-ROM -- the current (and so far
              only) file is called firm0309.lgo.  This will probably be
              necessary the first time you use your RCX, and whenever it's
              been without batteries for more than a few minutes.

       -firmfast filename
              same as -firmware, but at quad speed.  Requires the tower to be
              in near mode (see -near).   If you have trouble getting the fast
              download to work, please revert to the older (and slower)
              method.

       -sleep timeout
              set RCX auto-shutoff timeout, in minutes.

       -msg number
              send IR message to RCX. The brick will respond to this just as
              it would a communication from another RCX.

       -raw data
              send an arbitrary packet to the RCX and print the reply (if any)
              to stdout.  The data should be a hexadecimal string, with no
              spaces, zero-padded so that it is an even number of characters
              (although it may be an odd number of bytes). For example, to
              read the contents of variable 1, you could use -raw 120001. The
              bytecodes for raw messages can be found on web sites that
              document the RCX protocol.

       -remote value repeat
              send a repeating remote command to the RCX.

       -clear erase all programs and datalog from the RCX.

ENVIRONMENT VARIABLES
       RCX_PORT
              sets the default serial port.  See the -S option.

       NQC_OPTIONS
              specifies extra options to be inserted into the command line.
              For example, setting NQC_OPTIONS to -TScout would cause nqc to
              target the Scout by default.

       NQC_INCLUDE
              specifies additional paths to search for include files.  See
              also the -I option.

EXAMPLES
       To compile foo.nqc, download the bytecode to program slot three, and
       make the RCX start executing it immediately:

           nqc -d -pgm 3 foo.nqc -run

       To just compile bar.nqc, resulting in bar.rcx:

           nqc bar.nqc

       To download bar.rcx to the RCX:

           nqc -d bar.rcx

       To set the IR tower to short-range mode and download the firmware at
       high speed:

           nqc -near -firmfast firm0309.lgo

       To compile /usr/doc/nqc-2.1.0/test.nqc and print the resulting bytecode
       listing to the screen in human-readable format:

           nqc -L /usr/doc/nqc-2.1.0/test.nqc

       (This should result in the following output under nqc 2.1.0:

           *** Task 0 = main
           000 pwr        ABC, 7                13 07 02 07
           004 dir        ABC, Fwd              e1 87
           006 InType     0, Switch             32 00 01
           009 InMode     0, Boolean            42 00 20
           012 out        A, On                 21 81
           014 chkl       1 != Input(0), 14     95 82 09 01 00 00 fa ff
           022 plays      0                     51 00
           024 out        A, Off                21 41

       )

FILES
       Older versions of nqc required a seperate rcx.nqh or rcx2.nqh file.
       This is now integrated into the binary and no longer necessary, but for
       reference, rcx2.nqh is included with the package.  (If you installed
       the RPM, try /usr/doc/nqc-2.1.0/rcx2.nqh).

SEE ALSO
       http://www.enteract.com/~dbaum/nqc/
              The main Not Quite C web site.  You'll definitely want to look
              here.  Notably, you'll find the NQC Programmer's Guide, which
              covers the NQC language itself.

       http://www.crynwr.com/lego-robotics/
              A great site for alternative RCX / Mindstorms development.

       http://graphics.stanford.edu/~kekoa/rcx/
              Details on the internals of the RCX and the RCX protocol.

       http://www.lugnet.com/robotics/rcx/nqc/
              Discussion group for NQC.  Also available via NNTP at
              lugnet.com.

       http://nqc.mattdm.org/
              Linux binaries and RPM-format packages for NQC, including source
              RPMs.  Also has an RPM containing the NQC language documentation
              from Dave's site, in case you'd prefer to have it installed
              locally.

BUGS
       None known.  But be aware that Scout support is still preliminary and
       may change significantly.

COPYRIGHT
       nqc is Copyright (C) 1998-2000 David Baum and released under the terms
       of the Mozilla Public License.  See the documentation included with the
       program for more details.

AUTHOR
       The Not Quite C programming language and the nqc program were written
       and are maintained by Dave Baum.  Various contributions have been made
       by other people -- a full list of these can be found on Dave's web
       site.

       This man page was written by Matthew Miller (mattdm@mattdm.org), with
       extremely large amounts of borrowing from other NQC documentation.



                          Version 2.1 r1: 19 Feb 2000                   nqc(1)