From 574a7e22ea349d6b5b9a83853d3a1962d00ebe3a Mon Sep 17 00:00:00 2001
From: sys64738 <sys64738@noreply.example.org>
Date: Tue, 22 Jun 2021 20:30:32 +0000
Subject: [PATCH] Add 'USB protocol'

---
 USB-protocol.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 USB-protocol.md

diff --git a/USB-protocol.md b/USB-protocol.md
new file mode 100644
index 0000000..e6fb194
--- /dev/null
+++ b/USB-protocol.md
@@ -0,0 +1,76 @@
+The USB interface is an FTDI FT240X ([datasheet](https://ftdichip.com/wp-content/uploads/2020/08/DS_FT240X.pdf)). While not explicitely supported by libftdi, you can still use it (libftdi will think it is an FT230X).
+
+### `lsusb` output
+
+```
+Bus 001 Device 061: ID 0403:7fd0 Future Technology Devices International, Ltd ScanaQuad SQ50
+Device Descriptor:
+  bLength                18
+  bDescriptorType         1
+  bcdUSB               2.00
+  bDeviceClass            0 
+  bDeviceSubClass         0 
+  bDeviceProtocol         0 
+  bMaxPacketSize0         8
+  idVendor           0x0403 Future Technology Devices International, Ltd
+  idProduct          0x7fd0 
+  bcdDevice           10.00
+  iManufacturer           1 IKALOGIC
+  iProduct                2 ScanaQuad SQ50
+  iSerial                 3 1003050005482
+  bNumConfigurations      1
+  Configuration Descriptor:
+    bLength                 9
+    bDescriptorType         2
+    wTotalLength       0x0020
+    bNumInterfaces          1
+    bConfigurationValue     1
+    iConfiguration          0 
+    bmAttributes         0x80
+      (Bus Powered)
+    MaxPower              400mA
+    Interface Descriptor:
+      bLength                 9
+      bDescriptorType         4
+      bInterfaceNumber        0
+      bAlternateSetting       0
+      bNumEndpoints           2
+      bInterfaceClass       255 Vendor Specific Class
+      bInterfaceSubClass    255 Vendor Specific Subclass
+      bInterfaceProtocol    255 Vendor Specific Protocol
+      iInterface              2 ScanaQuad SQ50
+      Endpoint Descriptor:
+        bLength                 7
+        bDescriptorType         5
+        bEndpointAddress     0x81  EP 1 IN
+        bmAttributes            2
+          Transfer Type            Bulk
+          Synch Type               None
+          Usage Type               Data
+        wMaxPacketSize     0x0040  1x 64 bytes
+        bInterval               0
+      Endpoint Descriptor:
+        bLength                 7
+        bDescriptorType         5
+        bEndpointAddress     0x02  EP 2 OUT
+        bmAttributes            2
+          Transfer Type            Bulk
+          Synch Type               None
+          Usage Type               Data
+        wMaxPacketSize     0x0040  1x 64 bytes
+        bInterval               0
+can't get device qualifier: Resource temporarily unavailable
+can't get debug descriptor: Resource temporarily unavailable
+Device Status:     0x0000
+  (Bus Powered)
+```
+
+### Protocol
+
+The device operates in two (or three, depending on how you count) operting modes: bootloader mode (and authenticated bootloader mode), and application mode.
+
+In bootloader mode, you first have to send a magic number for the device (stored in the FT240X' EEPROM) to enable some functionality: when authenticated, in bootloader mode, you can access the Spartan-3AN's internal SPI flash, as well as maybe a few extra bits.
+
+You can switch to application mode (and back to bootloader mode) at any time, however, allegedly (this is the behavior of the [ScanaPLUS](https://sigrok.org/wiki/IKALOGIC_ScanaPLUS) device, which has a similar setup) capturing samples (in application mode) will not work when not authenticated in bootloader mode. (TODO: does switching to bootloader mode from application mode bring you into authenticated mode when already authenticated before switching to application mode?)
+
+TODO: document the commands of every mode
\ No newline at end of file