firmware.txt - How to setup and use the plipbox firmware
--------------------------------------------------------

After building your device (see doc/hardware.txt) you need to flash the plipbox 
device firmware.

1. Flash Firmware

1.1 Find Arduino Serial Port

You need to connect your Arduino typically via the USB port to your Mac or PC 
and this will install a "virtual" serial port that allows to reach the Arduino
via a serial link. 

The device is called differently depending on your OS: 
  * Macs: /dev/cu.usbserial-<serial>
  * Linux: /dev/ttyUSB<num>
  * Windows: COM1 ... COMx
  
You can find out the port associated with your Arduino by looking at the registered devices before and after attaching the device.

1.2 Flash on Arduino Hardware with "avrdude"

For flashing the firmware you need a flash tool on your Mac/PC that talks via
this serial port. I use "avrdude" here. It is available on all platforms and
a command line tools. See the "avrdude" home page[1] for details.

Now open a shell/terminal/cmd.exe on your OS and call the firmware tool with:

> avrdude -p m328p -P <your_serial_port> -b 57600 -c arduino -U flash:w:plipbox-0.1-57600-arduino-atmega328.hex

This assumes that you have the plipbox firmware file called 
"plipbox-0.1-57600-arduino-atmega328.hex" in your current directory.
In the release archive you can find it in the "firmware" directory.

Furthermore, replace <your_serial_port> with the device name of your
Ardiuno serial device found in section 1.1.

If everything works well then you will see the following output:

"avrdude: AVR device initialized and ready to accept instructions

Reading | ################################################## | 100% 0.00s

avrdude: Device signature = 0x1e950f
avrdude: NOTE: FLASH memory has been specified, an erase cycle will be performed
         To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "plipbox-0.1-57600-arduino-atmega328.hex"
avrdude: input file plipbox-0.1-57600-arduino-atmega328.hex auto detected as Intel Hex
avrdude: writing flash (16596 bytes):

Writing | ################################################## | 100% 4.67s

avrdude: 16596 bytes of flash written
avrdude: verifying flash memory against plipbox-0.1-57600-arduino-atmega328.hex:
avrdude: load data flash data from input file plipbox-0.1-57600-arduino-atmega328.hex:
avrdude: input file plipbox-0.1-57600-arduino-atmega328.hex auto detected as Intel Hex
avrdude: input file plipbox-0.1-57600-arduino-atmega328.hex contains 16596 bytes
avrdude: reading on-chip flash data:

Reading | ################################################## | 100% 3.37s

avrdude: verifying ...
avrdude: 16596 bytes of flash verified

avrdude: safemode: Fuses OK

avrdude done.  Thank you."

Now your device is fully operational and we use the serial link to communicate 
with plipbox.

[1] http://www.nongnu.org/avrdude/

1.3 Flash on AVR-NET-IO Board

The AVR-NET-IO-Board from Pollin.de (see hardware.txt) has a different AVR
chip, the ATmega32 and thus needs another firmware version:

plipbox-0.1-57600-avrnetio-atmega32.hex

Again I use avrdude to flash the firmware. Although the board provides a 
bootloader via serial port I was not able to use this with avrdude. So
I switched over to direct ISP programming but that needs an AVR ISP
programming adapter. I use the USBasp [1] thats a cheap AVR ISP that
is supported by avrdude and has a USB connector. You can build one
yourself or buy a kit [2].

The command avrdude is as follows:

> avrdude -p m32 -c usbasp -U flash:w:plipbox-0.1-57600-avrnetio-atmega32.hex

[1] http://www.fischl.de/usbasp/
[2] http://www.fundf.net/usbasp/

2. plipbox Configuration

The plipbox firmware uses the serial link available on your Arduino to show you 
device information and allows you to configure the device in this terminal.

2.1 Setup your terminal program

On your Mac/PC you will need a terminal program to talk via the serial link.
If you haven't got a favorite one then have a look at CoolTerm[1] for Mac OSX
or TeraTerm[2] for Windows. Linux users might try minicom[3] or picocom[4].

[1] http://freeware.the-meiers.org/
[2] http://www.ayera.com/teraterm/
[3] http://alioth.debian.org/projects/minicom/
[4] http://code.google.com/p/picocom/

Run your terminal program and select the serial port of your Arduino (see 
section 1.1). For the serial port select the following parameters:

  * 8 N 1 = 8 data bits, no parity, 1 stop bit
  * no hardware (RTS/CTS) hand shaking
  * no software (XON/XOFF) hand shaking

If everything went well you will see the startup message of the plipbox 
firmware:

"Welcome to plipbox 0.1 20120722
by lallafa (http://www.lallafa.de/blog)

nn)et mask:  255.255.255.000
ng)ateway:   192.168.002.001
ns)erver     192.168.002.099
ne)th port:  192.168.002.133
np)lip port: 192.168.000.002
na)miga p2p: 192.168.000.001
nm)ac addr:  74:69:69:2D:30:31
nd)hcp on:   00
a1) arp ip:  000.000.000.000
a2) arp ip:  000.000.000.000
a3) arp ip:  000.000.000.000

eth rev: 07
plip: online
arp: cache do req #00
arp: requesting MAC for 192.168.002.001
eth: link up
arp: reply from 192.168.002.001: MAC=C0:25:06:AF:68:92 -> cache #00
eth: start net"

You see all important parameters of your device and their current values.
Below is the current status of the device starting with "eth rev" that
tells you that the firmware correctly detected your Ethernet chip.

2.2 Entering/Leaving Command Mode

If you press Return in your terminal program then the device will enter
"command mode". This mode allows you to enter commands that the device
will execute. Its mainly used to set parameters and load/save them.

Command mode is shown with a command prompt "> " in the beginning of a line.

If you enter 'q' and Return you give the "quit" command to leave the command
mode and the device returns to active mode. 

Note that during command mode the device does NOT operate and does NOT pass
any IP packets.

See the following section for a complete list of all commands available.

A command usually consists of a command name and optional arguments. All
a seperated by spaces on the command line.

A command is always finished by pressing Return.

2.3 plipbox Commands

'q' - Leave command mode
'v' - Show plipbox firmware version
'p' - Show parameters
'ps' - Save parameters to EEPROM
'pl' - Load parameters from EEPROM
'pr' - Reset parameters to factory defaults

'nd' - Toggle DHCP mode

  The device supports DHCP to get your local network parameters
  automatically. If you enable DHCP mode then netmask, eth port IP
  and gateway IP will be set automatically.

'nn <ip>' - Set the netmask of your local ethernet

  Manally set your network mask if DHCP is disabled.
  Typical values for <ip> are "255.255.255.0"

'ng <ip>' - Set the gateway IP address of your local network

  Manually set your gateway address if DHCP is disabled.
  The gateway IP is only needed if you want to reach hosts
  outside your local network (i.e. the internet)

'ne <ip>' - Set the IP address of the ethernet port on your plipbox

  Manually set your plipbox ethernet port address if DHCP is disabled.
  Make sure to pick an address available in your local network.

'ns <ip>' - Set the IP address of a server in your local network

  This option is totally optional. Its only used for the server
  ping key command (see seciton 2.4).
  The plipbox device works without setting this IP.

'np <ip>' - Set the IP address of the PLIP port on your plibox

  This address is a point-2-point address that the Amiga will
  talk to to reach the plipbox.
  Make sure to have a different IP network than you use on your ethernet!
  Also make sure to have an address in the same network as your Amiga!
  You can keep 192.168.0.2 if you don't use 192.168.0.x in your local net.
  You have to manually change this address if it collides.

'na <ip>' - Set the IP address of your Amiga

  This address is the point-2-point address of your Amiga.
  It has to be in the same network as your PLIP port.
  You can keep 192.168.0.1 if you don't use 192.168.0.x in your local net.
  You have to manually change this address if it collides.

2.4 plipbox Key Commands

If you are in active mode (not command mode) then you can press some command
keys to trigger actions on the device:

'a' - ping your Amiga

  Send a ping request to your Amiga to see if it replies and everything is
  set up correctly.
  
'g' - ping your Gateway

  If you defined a gateway or received one via DHCP then you can ping this
  machine with the 'g' command key.

's' - ping your Server

  If you set up a server IP for a machine on your local ethernet, you typically 
  use as your Amiga server then you can use this key command to ping it.

'c' - show the current ARP cache

  This command dumps the ARP cache managed by the plipbox.
  
'C' - clear the ARP cache of the plipbox

  This command allows you to clean the current ARP cache of the plipbox.
  All required IP addresses on your local network then will be re-resolved.

EOF





