xenial (1) nqc.1.gz

Provided by: nqc_3.1.r6-2_amd64 bug

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  separated  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/share/doc/nqc/examples/test.nqc and print the resulting bytecode listing to the screen in
       human-readable format:

           nqc -L /usr/share/doc/nqc/examples/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 separate 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/share/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.

       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)