Ubuntu Manpage: nqc - A simple C-like language for Lego's RCX programmable brick

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/rcx 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).

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)