NAME

       firmdl3 - A firmware downloader for the RCX.  Version 3.0.

SYNOPSIS

       firmdl3 [options] srecfile

DESCRIPTION

       This manual page documents the firmdl3 kernel download command.

       firmdl3  is  a  program  which is used to download the brickOS kernel (firmware).  firmdl3
       Supports single and quad rate downloading (quad-rate is default).

       Quad-rate downloading is a feature that significantly reduces firmware download times.  It
       is  implemented  on  top  of  a  fast  serial  protocol  that  has  a 2x baud rate with no
       complements or parity bits.  The fast protocol is enabled by a short  firmware  stub  that
       reconfigures  some control registers and tweaks some ROM program state.  Once the firmware
       stub is downloaded and executed, the ROM responds to the fast serial protocol,  which  the
       downloader  then  uses to transfer the actual firmware file.  Because the initial firmware
       stub is small, all but the most trivial programs see  a  download  time  improvement  when
       using quad-speed downloading.

       The  caveat  to  using  quad-speed  downloading is its sensitivity to lighting conditions.
       Getting quad-speed downloading to work right might  require  some  trial  and  error.   In
       addition  to  avoiding  harsh lighting conditions, it is important to place the RCX around
       4-12 inches from the IR tower.

OPTIONS

       This program follows the usual GNU command line syntax, with long  options  starting  with
       two dashes (`-').  The options supported by firmdl3 are:

       -h, --help
              Show built-in help (summery of options)

       -f, --fast
              Use 'fast' (4x) download algorithm (default)

       -s, --slow
              Use 'slow' (1x) download algorithm (Use if experiencing download problems)

       --tty={ttydevice}
              Specify serial serial tty where IR tower is connected.

              NOTE: The environment variable RCXTTY may be used in place of -tty

       --debug
              Enable debugging. (Mostly displays raw bytes).

ENVIRONMENT VARIABLES

       firmdl3 will respond to the environment variable RCXTTY.  This should be set to the serial
       device to which the IR tower is connected.  Use of RCXTTY is equivalent the using the -tty
       command-line option.

EXAMPLES

       firmdl3 is a simple command to use.  The following examples show most of the uses.

       Ex1: download the brickOS kernal to ttyS0.

          $ firmdl3 -tty=/dev/ttyS0 /usr/lib/brickos/brickOS.srec
          Transferring "Fast Download Image" to RCX...
          100%
          Transferring "/usr/lib/brickos/brickOS.srec" to RCX...
          100%
          $

       Ex2: download the brickOS kernal to ttyS1 (set env var 1st).

          $ export RCXTTY=/dev/ttyS1
          $ firmdl3 /usr/lib/brickos/brickOS.srec
          Transferring "Fast Download Image" to RCX...
          100%
          Transferring "/usr/lib/brickos/brickOS.srec" to RCX...
          100%
          $

       Ex3: download the brickOS kernal using slow protocol (assumes RCXTTY is already set).

          $ firmdl3 --slow /usr/lib/brickos/brickOS.srec
          Transferring "/usr/lib/brickos/brickOS.srec" to RCX...
          100%
          $

       NOTE: the missing indication of the "Fast Download Image" being sent.

       We'll  leave the experiment of running firmdl3 with --debug set as an exercise for you our
       reader... (You really interested in seeing all the bytes fly by? ;-)

ERROR MESSAGES

       (excerpt from brickOS HOWTO)

       delete firmware failed
              Because of a  limitation  in  the  Lego  firmware,  firmdl3  cannot  delete  LegOS.
              Instead,  before  downloading  the  new firmware, you must first stop the old LegOS
              program, and then hold down the Prgm button while hitting the On/Off  switch.  This
              will  delete  the old LegOS firmware, allowing a new download.  Alternately, if you
              see no green light on the IR box and get this error message, it  may  indicate  you
              have a dead battery in the IR tower.

       /dev/ttyS0: Permission denied, com1: Permission denied, or a similar message.
              The  first  part  of the error message is the output port that firmdl3 is trying to
              use. This can mean two things. Either you have specified the wrong  device  or  you
              have specified the correct device but do not have permission to access it. If it is
              an access problem, speak to your sysadmin.  If not, you can use the --tty  argument
              to specify another device. For example, to specify the standard device under linux,
              try ´firmdl3 --tty /dev/ttyS0´. Under cygwin, you probably  probably  want  to  use
              ´firmdl3  --tty  com1´.  If  you  discover  that  this is the case, you may wish to
              recompile firmdl3 to make your setting the default.

       /dev/ttyS0: Input/output error or a similar message.
              You forgot to plug the tower in, most likely.

       unlock firmware failed
              This indicates that there was a slight corruption in the  download.  Clear  brickOS
              and download it again.

       no response from RCX
              This  error  should  be called "you forgot to turn on your RCX, moron." If I hadn't
              done it about 10 million times, I'd submit the patch to change the error myself.

       If firmdl3 gives you repeated problems, you may want to try  using  the  --slow  argument,
       which  will  make  your  download much slower but can correct for certain errors caused by
       ambient light.

SEE ALSO

       dll(1)

AUTHOR

       Laurent Demailly, Allen Martin, Markus Noga, Gavin Smyth, and Luis Villa  all  contributed
       something to some version of firmdl3.

       firmdl3 was written by: Kekoa Proudfoot
       <kekoa@graphics.stanford.edu> - 10/13/99

       This  manual  page  was  written  by Stephen M Moraco <stephen@debian.org>, for the Debian
       GNU/Linux system (but may be used by others).