emailler/doc/README.C64.html

<h1>NETBOOT FOR THE C64</h1>

There are 2 major 'flavours'  of  clients, the major difference being whether the cart supports UDP only (but allows access to BASIC), or UDP + TCP (but loses access to BASIC). The 
reason for this is the UDP only version of the client fits into an 8KB cartridge, whereas the TCP code pushes the cartridge size up to 16KB, and the upper half of a 16KB cartridge sits in the same
memory location as BASIC.
<p>
Within the major flavours, there are also variations in media - the majority of code is identical between the different media but there are different headers etc. The supported media are:
<p>
<ul>
	<li> A program that can be loaded from disk (filename will end with .prg)</li>
	<li>'ordinary' cartridge images (that can be burned into an eeprom on e.g. a 64NIC+ card) (filename will end with .bin)</li>
  <li>'Retro Replay' cartridge images - these are actually 'ordinary' cartridge images that have been converted into a form suitable for use in a Retro Replay using Doc Bacardi's 
  <a href=http://freenet-homepage.de/LittleDreamLand/CRT8040.html>CRT8040</a> tool (filename will end with _rr.bin)</li>
</ul>

<table>
<tr><th>filename</th><th>flavour</th><th>cartidge size</th></tr>
<tr><td>netboot.bin</td><td>UDP  only (+ BASIC)</td><td>8KB cart</td></tr>
<tr><td>kipperkart.bin</td><td>UDP/TCP (no BASIC)</td><td>16KB cart</td></tr>
<tr><td>kippergo.bin</td><td>basic telnet &amp; gopher client</td><td>16KB cart</td></tr>
<tr><td>kipperterm.bin</td><td>enhanced telnet</td><td>16KB cart</td></tr>

</table>


<h2>USING THE CARTRIDGES</h2>

When one of the cartridge images start, it will attempt to configure the IP stack via DHCP. If the DHCP config fails (either by timing out, or the user press RUN/STOP)
then the IP stack will fall back to using the IP configuration built into the cartridge. See the section "IP CONFIGURATION" for info on how to modify the
cartridge defaults prior to burning an image.
<p>

<h2>NETBOOT - UDP only cart</h2>

Once the IP stack is initialised, an attempt to boot from the network will take place. a TFTP server will be queried for a list of PRG files, and then a menu appears allowing the selection of a file to be downloaded and executed. Most 'single load' applications should work</li>

<h2>KIPPERKART - UDP/TCP cart</h2>
<ul>
	<li>F1 : TFTP BOOT. This will query a TFTP server for a list of PRG files, and allow the selection of a file to be downloaded and executed. This version of TFTP BOOT is restricted to running only 
  pure machine language programs, since BASIC is not available when this cart is active. (NB - programs that are pure M/L except for a BASIC stub consisting of a single SYS call will be executed). 
  </li>
  	<li>F2 : DISK BOOT. This will display a catalogue of files in drive #8 and allow the selection of a file to be executed. This version of DISK BOOT is restricted to running only 
  pure machine language programs, since BASIC is not available when this cart is active. (NB - programs that are pure M/L except for a BASIC stub consisting of a single SYS call will be executed). 
</li>

	<li>F3 : UPLOAD D64. You will prompted to specify a filename, then the disk in the default drive will be read and sent to the tftp server</li>
  <li>F4 : DOWNLOAD D64. A TFTP server is queried for a list of D64 files, which can be selected from a menu. Once a D64 file is selected, it will be downloaded and written to the default drive (usually #8).</li>
	<li>F5 : SID NETPLAY. A TFTP server is queried for a list of SID files, which can be selected from a menu. Once a SID file is selected, it will be played. Not all SIDs work yet.</li>
  <li>F6 : PING. You will be prompted for a hostname which will be pinged 3 times, and a response time (in milliseconds) is printed for each ping.</li>	
	<li>F7 : CONFIG. This brings up a menu where the IP configuration can be modified. Changes made here will be persistent until the next reboot.</li>
</ul>

<a name="autoexec"><h2>AUTOEXEC</h2></a>
Once the 16KB cartridge image has initialised the IP stack, it will look for a file called "autoexec.prg" on the default drive. If this file is found it will be loaded (using the load address specified by the first 2
bytes of the file) and executed. NB - since BASIC is not available only 100% Machine Language programs can be executed, although if there is a BASIC stub consisting of a single line that does a SYS 
call, the target of the SYS call will be used as the address to start execution from.

<h2>KIPPERGO cart</h2>
<ul>
	<li>F1 : TELNET. You will be prompted to enter a hostname, a port number, and a connection mode. Connection mode is either 
  <ul>
  <li>VT100 -  keypresses are converted to ASCII before  being sent out, and incoming data is converted to PETSCII before being displayed. Many common VT100 escape codes are interpreted, and keystrokes are sent a character at a time.</li>
  <li>PETSCII - no translation is done on data coming in or out. This mode is suitable for connecting to PETSCII BBSs</li>
  </ul>
  Once a connection is made, it can be terminated by hitting RUN/STOP
  <li>F3 : GOPHER. You will be prompted to enter the hostname (only - no port number can be specified) of a gopher server, and the gopher client will be launched connecting to the specified server.
	<li>F5 : GOPHER.FLOODGAP.COM. This will launch the Gopher client, and connect to the gopher portal at gopher://gopher.floodgap.com/</li>
  <li>F7 : CONFIG. This brings up a menu where the IP configuration can be modified. Changes made here will be persistent until the next reboot.</li>
</ul>

<h3>Gopher Client</h3>
Once a gopher resource is loaded, the following keys are active:
<ul>
<li>SPACE, F7 or down arrow : scroll down to next page
<li>F1 or up arror : scroll up to previous page
<li>F2 : show recently visited resource
<li>F3 or left arrow : go back to last visited resource
<li>F5 : prompt to enter a new server (nb server name only - not resource or port)
<li>RUN/STOP : quit
</ul>
If the page currently being displayed has links to further resources in it, each link will be displayed 
starting with a highlighted letter (e.g. the first link on a page will have an inverse "A" next to it,
the 2nd link on a page will have an inverse "B" next to it etc). Press the letter assigned to the link
to load up that resource.

<h2>KIPPERTERM cart</h2>
<ul>
	<li>F1 : TELNET. You will be prompted to enter a hostname, a port number, and a connection mode. Connection mode is either 
  <ul>
  <li>VT100 -  keypresses are converted to ASCII before  being sent out, and incoming data is converted to PETSCII before being displayed. Many common VT100 escape codes are interpreted, and keystrokes are sent a character at a time.</li>
  <li>PETSCII - no translation is done on data coming in or out. This mode is suitable for connecting to PETSCII BBSs</li>
  </ul>
</ul>  
Once a connection is made, it can be terminated by hitting RUN/STOP
<h3>File Transfer</h3>  
While connected, you can hit F1 to bring up a file transfer menu. This menu presents the following options:
<ul>
	<li>F1 : D/L File (XMODEM). Select this option after you have started the file download process on the remote server. You will be prompted for a filename for the file to be saved as after the download has completed.
  <li>F3 : U/L File (XMODEM). Select this option after you have started the file upload process on the remote server. You will be given a menu of files on the local disk to transfer.
  <li>F5 : Send ASCII char. You will be prompted to enter a number between 0 and 255, and the corresponding byte will be sent. This is useful for sending characters which can't be entered on a C64 keyboard.
  <li>F7 : Return. Selecting this option will restore the screen return you to your connection
</ul>





<h2>IP CONFIGURATION</h2>
There is a script in the "bin" folder called "set_ip_config.rb" that can be used to modify the MAC address and IP config details in the cart image before
it is burned. For example, to set the MAC address and DNS servers, use this command:
<pre>set_ip_config.rb nb65_std_cart.bin mac ab:cd:ef:12:34:56 dns 10.5.1.1</pre>
run "set_ip_config.rb" with no parameters to see all the options for what can be configured.

<h2>STARTING THE SERVER</h2>
<ol>
	<li> unzip the archive somewhere on your local hard drive</li>
	<li>start the bin/tftp_server.rb script (e.g. by double-clicking on it)</li>
</ol>

<h2>ADDING MORE FILES</h2>

Only single-load files can be used. The files need to be in "PRG" format, i.e.the first 2 bytes of the file must be
the load address (little-endian, i.e. low/high). The files also need to have a file extension of ".PRG" (in upper case, if your operating system of choice
is case sensitive).
<p>
Files need to be placed in the 'boot/' folder.
<p>
Due to a limitation in the menu selection code, only the first 128 PRG files in the boot/ folder can be selected.

<h2>ERROR CODES</h2>
Most network functions will return an 8 bit error code if things go wrong.
<table><tr><th>ERROR CODE</th><th>DESCRIPTION</th></tr>
<tr><td>$80</td><td>PORT IN USE</td></tr>
<tr><td>$81</td><td>TIMEOUT ON RECEIVE</td></tr>
<tr><td>$82</td><td>TRANSMIT FAILED</td></tr>
<tr><td>$83</td><td>TRANSMISSION REJECTED BY PEER</td></tr>
<tr><td>$84</td><td>INPUT TOO LARGE</td></tr>
<tr><td>$85</td><td>DEVICE FAILURE</td></tr>
<tr><td>$86</td><td>ABORTED BY USER</td></tr>
<tr><td>$87</td><td>LISTENER NOT AVAILABLE</td></tr>
<tr><td>$88</td><td>NO SUCH LISTENER</td></tr>
<tr><td>$89</td><td>CONNECTION RESET BY PEER</td></tr>
<tr><td>$8A</td><td>CONNECTION CLOSED</td></tr>
<tr><td>$8B</td><td>TOO MANY ERRORS</td></tr>
<tr><td>$90</td><td>FILE ACCESS FAILURE</td></tr>
<tr><td>$A0</td><td>MALFORMED URL</td></tr>
<tr><td>$A1</td><td>DNS LOOKUP FAILED</td></tr>
<tr><td>$FE</td><td>OPTION NOT SUPPORTED</td></tr>
<tr><td>$FF</td><td>FUNCTION NOT SUPPORTED</td></tr>
</table>
<h2>REQUIREMENTS</h2>
<ol>
	<li>RR-NET or compatible adaptor (to use under VICE, you will need pcap or winpcap installed)</li>
	<li>(RECOMMENDED) a DHCP server on your network</li>
	<li>a working ruby installation</li>
</ol>
<h2>LICENSE</h2>
NETBOOT65 is licensed under the same terms as IP65, the <a href=http://www.mozilla.org/MPL/>Mozilla Public License Version 1.1.</a>

<h2>SOURCE CODE</h2>
	Browse online at <a href=http://netboot65.svn.sourceforge.net/viewvc/netboot65/>http://netboot65.svn.sourceforge.net/viewvc/netboot65/</a> or else download the whole tree  through SVN with the following instruction set: 
  <pre>svn co https://netboot65.svn.sourceforge.net/svnroot/netboot65 netboot65 </pre>

<h2>CREDITS</h2>
Package is maintained by Jonno Downes - jonno@jamtronix.com
<h3>Contributors</h3>
<ul>
<li>Jonno Downes - current maintainer of ip65, original developer of layers 4-7 (dhcp,dns,tcp,telnet, http, gopher)</li>
<li>Glenn Holmer - icmp enhancements, bugfixes</li>
<li>Per Olofsson - initial creator of ip65, original developer of layers 1-3 (eth,arp,ip,icmp,udp)</li>
<li>Lars Stollenwerk - vt100 emulation </li>
</ul>