firmdl3(1)							  brickOS Utility							firmdl3(1)

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

brickOS 							 January  6, 2001							firmdl3(1)