petwifi/README.md

# petwifi

An ESP8266 expansion for the Commodore PET / CBM.

## Description

Unlike the C64, the Commodore PET does not have a serial port.
For that reason, most serial port adapters for the C64 don't work, and an
alternate interface must be found. Furthermore, the user port on the PET
doesn't supply any power, so an external power supply would be necessary.

There is hope, however: The cassette port supplies 5V power and has
suitable logic lines that can be used to emulate a serial port.

The drawback is that serial communication must be fully emulated in
software.

Due to the different voltage levels of the ESP8266 and the PET,
some voltage conversion is necessary. Luckily, this can be achieved with
minimal circuitry: Converting from 5V to 3.3V can be done with a
resistor divider. For the opposite direction, no conversion is
necessary, because the voltage swing from 3.3V CMOS output drivers
is sufficient to drive NMOS input gates.

Special care must be taken for the MOTOR control line (which is used as
CTS control input on the ESP): It is driven by a darlington array on
a 9V supply rail.

The other pin mappings are as follows:

| PET pin        | ESP pin | Direction | Cassette 1 external | Cassette 2 internal  |
|----------------|---------|-----------|---------------------|----------------------|
| Cassette Write | RXD     | PET->ESP  | VIA PB3             | VIA PB3 (same as 1)  |
| Cassette Read  | TXD     | ESP->PET  | PIA1 CA1            | VIA CB1              |
| Cassette Motor | CTS     | PET->ESP  | PIA1 CB2            | VIA PB4              |
| Cassette Sense | RTS     | ESP->PET  | PIA1 PA4            | PIA1 PA5             |

A suitable serial signal (RS-232-like) must be generated/decoded in software.
Make sure that you don't access the cassette port 1 while the adapter is
connected.

For programming info, refer to this excellent document:
http://www.6502.org/users/andre/petindex/local/pet-io-2.txt

## RS232 Waveform

| Logic |  L  |  H  |
|-------|-----|-----|
| CMOS  | 0V  | 3V  |
| RS232 | +3V | -3V |
| Start | +3V |     |
| End   |     | -3V |

```
   _   ___   ___     ____
H   | |   | |   |   |
    | |   | |   |   |
L   |_|   |_|   |___|
     S 1 1 0 1 1 0 0 1 E

     _     _     ___
+3  | |   | |   |   |
    | |   | |   |   |
-3 _| |___| |___|   |____
     S 1 1 0 1 1 0 0 1 E
```

## PET RS232 Driver

On the software side, the RS-232 interface is realized as a loadable driver for
the PET. It can be compiled for loading into RAM, or for flashing onto a
ROM chip.

The driver defines four entry points:

| Function    | Entry point (load at $7000) | Description |
|-------------|-----------------------------|-------------|
| `rs_init`   | $7000                       | Initialize the driver and the hardware |
| `rs_uninit` | $7003                       | Disable the hardware interface |
| `rs_read`   | $7006                       | Read one byte from the input buffer |
| `rs_write`  | $7009                       | Write one byte to the output buffer |

Input parameters and return values for `rs_read` and `rs_write` are exchanged via the zero page:

| Variable       | Address | Description |
|----------------|---------|-------------|
| `rs_available` | $ed     | Available bytes to read or write (size of the input buffer or remaining space in output buffer) |
| `rs_data`      | $ee     | Data byte (return from read or parameter for write) |
| `rs_status`    | $ef     | Status of the operation (0=ok, 1=read buffer empty, 2=write buffer full, 3=not initialized, 4=already initialized) |

## Example BASIC Program

This program assumes that the driver is already loaded at start address $7000.

```basic
10 PRINT "Initializing driver"
20 SYS (28672)
30 PRINT "Waiting for input"
40 SYS (28678)
50 status = PEEK(239)
60 IF status <> 0 THEN GOTO 90
70 char = PEEK(238)
80 PRINT CHR$(char);
90 GOTO 40
100 PRINT
110 PRINT "Disabling driver"
120 SYS (28675)
130 END
```

## VICE Emulation

To help test the RS-232 driver, there is a patch for the Commodore computer
emulator VICE in the file vice-tape-rs232.patch.

It is intended for VICE 3.6.1 and prints out decoded RS-232 transmissions
from the driver to the console. Reading data into the emulator is not
supported yet.

To enable the emulated device, you need to open the "Tape port" settings
and select "RS-232 interface" for tape port 1.