
-------------------------------------------------------------------------------
  Mecrisp-Ice for the Orange Crab
-------------------------------------------------------------------------------

This is Mecrisp-Ice for the Orange Crab rev 0.2.1 with ECP5 85F FPGA,
running at 48 MHz clock.

-------------------------------------------------------------------------------
  Installation and usage
-------------------------------------------------------------------------------

Flash with DFU. You can enter DFU mode
by holding the button on the Orange Crab while plugging it in.

dfu-util --alt 0 -D j1a.dfu

It will enumerate as an USB-CDC device (probably /dev/ttyACM0) for terminal.

Note the terminal both expects and sends LF only for line endings.

The user button is wired to reset the processor,
but does not reload memory contents,
and keeps the terminal connection alive.

-------------------------------------------------------------------------------
  IO Ports
-------------------------------------------------------------------------------

            bit READ            WRITE

    + ...0                      Write as usual
    + ...1                      _C_lear bits
    + ...2                      _S_et bits
    + ...3                      _T_oggle bits

      0008  3   Unused

      0010  4   \
      0020  5    \  Selector bits
      0040  6    /  for further decoding
      0080  7   /

      0100  8   PORT A... (with cst)
      0200  9   PORT B... (with cst)
      0400  10  ADC...    (with cst)
      0800  11  LEDs...   (with cst)

      1000  12  UART RX         UART TX
      2000  13  UART Flags
      4000  14  Ticks           Set Ticks
      8000  15  Cycles

-------------------------------
  GPIO:
-------------------------------

  $0110  (ro)     Port A IN
  $0120  (rw cst) Port A OUT
  $0140  (rw cst) Port A DIR

  $0210  (ro)     Port B IN
  $0220  (rw cst) Port B OUT
  $0240  (rw cst) Port B DIR

  The GPIO register bits are "one-hot" decoded and can be ORed together
  to access multiple GPIO registers at once.

Bit:     PORTA:         PORTB:

 0       gpio_a0        gpio_13
 1       gpio_a1        gpio_12
 2       gpio_a2        gpio_11
 3       gpio_a3        gpio_10
 4       gpio_a4        gpio_9
 5       gpio_a5        gpio_6
 6       gpio_sck       gpio_5
 7       gpio_mosi      gpio_scl
 8       gpio_miso      gpio_sda
 9       gpio_0
10       gpio_1

-------------------------------
  ADC:
-------------------------------

The Orange Crab features an one-bit sigma delta analog-digital conversion
circuit that is based on a hack using a differential LVDS input and a RC lowpass
filtered one-bit return path. Expect quite noisy readings.

You can get either decimated/averaged values with a sample rate of
48 MHz / 2^16 = 732.42 Hz
or for special purposes, also the raw sigma-delta bitstream values, 16 bits each,
arriving at 48 MHz / 16 = 3 MHz, so you have 16 clock cycles to handle these if you
want to record these for further experiments.

FIFOs with flags are available in order to sync with the conversions.

  $0400  (ro)     Current decimated/averaged ADC value
  $0410  (ro)     ADC FIFO valid
  $0420  (ro)     ADC FIFO fetch

  $0430  (rw cst) ADC MUX

  $0440  (ro)     Current raw bitstream data
  $0450  (ro)     Raw bitstream FIFO valid
  $0460  (ro)     Raw bitstream FIFO fetch

Input channels on the multiplexer:

  0: GND
  1: A0
  2: A1
  3: A2
  4: A3
  5: A4
  6: A5
  7: AREF (with 100 nF capacitor)
  8: 3.3V
  9: GND
 10: GND
 11: GND
 12: 1.35V
 13: 2.5V
 14: 1.1V
 15: Vbatt/2

 16: Multiplexer disable, disconnect ADC from inputs

-------------------------------
  Blinkenlights:
-------------------------------

  $0800  (rw cst) {Blue, Green, Red} Simply switch LEDs on and off
  $0810  (rw cst)  Red   fading
  $0820  (rw cst)  Green fading
  $0830  (rw cst)  Blue  fading

  If the fading register is zero,    the bit in $0200 controls the LED.
  If the fading register is nonzero, the sigma-delta modulated pulse train
                                     is ORed together with the bit in $0200.

Note that the required forward voltage varies for the different colours,
so the brightness levels when using the fading registers might surprise you.
