Started README. Includes notes on the intended protocols.HEADmaster

1 files changed, 111 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..7f92230
--- /dev/null
+++ b/README
@@ -0,0 +1,111 @@
+Overview
+--------
+
+This is a small project to implement a connection such that binary files can
+be downloaded to an Amstrad CPC from a Raspberry Pi via the joystick port.
+
+The circuitry is such that GPIO pins are connected via transistors and mapped
+to joystick directions:
+
+	GPIO 2	-	Fire
+	GPIO 3	-	Up
+	GPIO 4 	-	Down
+	GPIO 5	-	Left
+	GPIO 6	-	Right
+
+The idea is that a nibble is placed on the direction pins.  Once these are set
+the fire pin is activated and held for a period.  Then the fire is released.
+The next nibble is fired in the same way and this finishes the process for
+sending a byte.
+
+On the CPC side when reading the joystick via KM_GET_JOYSTICK(0xbb24) the
+firmware docs reveal this bit layout:
+
+Bit	Direction/Fire
+0	Up
+1	Down
+2	Left
+3	Right
+4	Fire2
+5	Fire1
+6	Spare
+7	Always zero
+
+However KM_GET_JOYSTICK only reads the joystick every 1/50th of seconds, so this
+is too slow for our purposes.  As such the joystick has to be read directly.
+When read directly the bits are reversed (i.e. a bit is set if that direction
+isn't pressed) so the results have to be xored with 255 to get the value we
+want.
+
+As the 4 directions are already arranged in the low nibble this layout is
+maintained for the protocol, so that this is the mapping between the GPIO
+pins and the info to send:
+
+Bit	GPIO Pin
+0	3
+1	4
+2	5
+3	6
+4	2
+
+
+Z80 code
+--------
+
+The z80 directory contains code to read the information sent over the joystick
+port.  xfer.z80 is for the basic file transfer.  copydisk.z80 is a more
+complicated process used to transfer and write disk images.
+
+Included is the text of a BASIC loader (loadxfer.bas) to poke in the results of
+assembling xfer.z80.  This should be used to get the initial code across to the
+CPC, which will involve some typing.  Needless to say, I'd save the code before
+running it.
+
+
+Pi code
+-------
+
+This comprises two command line tools.  cpcxfer is to transfer a file.
+cpcdiskxfer is to transfer a disk image.  Usage is as follows:
+
+cpcxfer file start_address milliseconds
+
+    file is the file to send.
+
+    start_address is the start address of the file.  Hex numbers can be
+    preceded with 0x.
+
+    milliseconds is the number of milliseconds to hold the fire button high
+    and then the number of milliseconds to hold it off.  Hence one nibble is
+    transferred every 2 * milliseconds.
+
+cpcdiskxfer disk_image milliseconds
+
+    disk_image is the DSK image to send.
+
+    milliseconds is the number of milliseconds to hold the fire button high
+    and then the number of milliseconds to hold it off.  Hence one nibble is
+    transferred every 2 * milliseconds.
+
+
+File transfer protocol
+----------------------
+
+This is a simple protocol using the following format:
+
+Byte 0	-	Destination address low byte.
+Byte 1	-	Destination address high byte.
+Byte 2	-	File length low byte.
+Byte 3	-	File length high byte.
+Byte n	-	File length bytes.
+
+
+Disk image transfer protocol
+----------------------------
+
+This protocol follows the following format.  Note that double sided disk
+images are not supported.
+
+First an overview packet is sent.
+
+TODO