R3.3 hardware: Update README, add HW_REV switch, ordering info

.github/workflows/main.yml

@@ -3,14 +3,27 @@ name: build & test
 on: [push]
 
 jobs:
-  ubuntu-build-icebreaker:
+  ubuntu-build-icebreaker-r31:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: YosysHQ/setup-oss-cad-suite@v2
       - run: git submodule update --init gateware/external/no2misc
       - run: yosys --version
-      - run: make BOARD=icebreaker CORE=mirror -C gateware
+      - run: make HW_REV=HW_R31 BOARD=icebreaker CORE=mirror -C gateware
+      - uses: actions/upload-artifact@v3
+        with:
+          name: ubuntu-build-icebreaker.bin
+          path: gateware/build/icebreaker/top.bin
+
+  ubuntu-build-icebreaker-r33:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: YosysHQ/setup-oss-cad-suite@v2
+      - run: git submodule update --init gateware/external/no2misc
+      - run: yosys --version
+      - run: make HW_REV=HW_R33 BOARD=icebreaker CORE=mirror -C gateware
       - uses: actions/upload-artifact@v3
         with:
           name: ubuntu-build-icebreaker.bin
@@ -34,7 +47,7 @@ jobs:
           export PATH=$PATH:$RUNNER_TEMP/oss-cad-suite/bin
           export PATH=$PATH:$RUNNER_TEMP/oss-cad-suite/lib
           yosys --version
-          make BOARD=icebreaker CORE=mirror -C gateware
+          make HW_REV=HW_R33 BOARD=icebreaker CORE=mirror -C gateware
       - uses: actions/upload-artifact@v3
         with:
           name: windows-build-icebreaker.bin
@@ -48,7 +61,7 @@ jobs:
       - run: git submodule update --init gateware/external/no2misc
       - run: |
           yosys --version
-          make BOARD=icebreaker CORE=mirror -C gateware
+          make HW_REV=HW_R33 BOARD=icebreaker CORE=mirror -C gateware
       - uses: actions/upload-artifact@v3
         with:
           name: macos-build-icebreaker.bin
@@ -61,7 +74,7 @@ jobs:
       - uses: YosysHQ/setup-oss-cad-suite@v2
       - run: git submodule update --init gateware/external/no2misc
       - run: yosys --version
-      - run: make BOARD=colorlight_i5 CORE=mirror -C gateware
+      - run: make HW_REV=HW_R33 BOARD=colorlight_i5 CORE=mirror -C gateware
       - uses: actions/upload-artifact@v3
         with:
           name: ubuntu-build-colorlight-i5.bin
@@ -74,7 +87,7 @@ jobs:
       - uses: YosysHQ/setup-oss-cad-suite@v2
       - run: git submodule update --init gateware/external/no2misc
       - run: yosys --version
-      - run: make BOARD=colorlight_i9 CORE=mirror -C gateware
+      - run: make HW_REV=HW_R33 BOARD=colorlight_i9 CORE=mirror -C gateware
       - uses: actions/upload-artifact@v3
         with:
           name: ubuntu-build-colorlight-i9.bin
@@ -87,7 +100,7 @@ jobs:
       - uses: YosysHQ/setup-oss-cad-suite@v2
       - run: git submodule update --init gateware/external/no2misc
       - run: yosys --version
-      - run: make BOARD=ecpix5 CORE=mirror -C gateware
+      - run: make HW_REV=HW_R33 BOARD=ecpix5 CORE=mirror -C gateware
       - uses: actions/upload-artifact@v3
         with:
           name: ubuntu-build-ecpix-5.bin
@@ -100,7 +113,7 @@ jobs:
       - uses: YosysHQ/setup-oss-cad-suite@v2
       - run: git submodule update --init gateware/external/no2misc
       - run: yosys --version
-      - run: make BOARD=pico_ice CORE=mirror -C gateware
+      - run: make HW_REV=HW_R33 BOARD=pico_ice CORE=mirror -C gateware
       - uses: actions/upload-artifact@v3
         with:
           name: ubuntu-build-pico-ice.bin

README.md

@@ -1,25 +1,38 @@
+![ci workflow](https://github.com/schnommus/eurorack-pmod/actions/workflows/main.yml/badge.svg)
+
 # Eurorack PMOD
 
+- **R3.3 hardware in stock!** [order **here :)**](https://apfelaudio.com/order/)
 - ~~R3.1 hardware SOLD OUT~~
-- **R3.3 hardware coming soon!** [get notified **here :)**](https://apfelaudio.com/modules/pmod/)
 
-**Eurorack PMOD** makes it easy for you to combine the world of FPGAs and [hardware electronic music synthesis](https://en.wikipedia.org/wiki/Eurorack). It is an expansion board for FPGA development boards that allows them to interface with a Eurorack hardware synthesizer. This board exposes 8 (4 in + 4 out) DC-coupled audio channels, 192KHz / 32bit sampling supported, at a -8V to +8V swing, amongst many more features. R3.1 hardware looks like this:
+**Eurorack PMOD** is a [certified open hardware](https://certification.oshwa.org/de000135.html) Eurorack module that plugs directly into many FPGA boards, which makes it easy to combine the world of FPGAs and [hardware electronic music synthesis](https://en.wikipedia.org/wiki/Eurorack). The **latest (R3.3) hardware looks like this**:
 
-![assembled eurorack-pmod module R3.0 (panel)](docs/img/panel.jpg)
-![assembled eurorack-pmod module R3.0 (top)](docs/img/pmod_top.jpg)
+![assembled eurorack-pmod module R3.3 (front)](docs/img/r33_panel.jpg)
+![assembled eurorack-pmod module R3.3 (top)](docs/img/r33_top.jpg)
 
+For a (now quite outdated) high-level overview on the motivation for this project and some of the design decisions, **see [my FOSDEM '23 talk](https://youtu.be/Wbd-OfCWvKU)** on this project.
 
-![ci workflow](https://github.com/schnommus/eurorack-pmod/actions/workflows/main.yml/badge.svg)
+## How does it work?
+- Plug eurorack-pmod into an FPGA development board of your choice. Here is a list of [boards already supported by the examples](gateware/boards).
+- Get started with some [example DSP cores](gateware/cores). Examples include calibration, sampling, effects, synthesis sources and so on. The design files can be synthesized to a bitstream using Yosys' [oss-cad-suite](https://github.com/YosysHQ/oss-cad-suite-build).
 
+# R3.3 hardware details
 
-For a high-level overview on R2.2 hardware, **see [my FOSDEM '23 talk](https://youtu.be/Wbd-OfCWvKU)** on this project. Production hardware is named R3+ and has a few improvements (LEDs fully programmable, jack detection, calibration EEPROM).
+![labelled eurorack-pmod 3.3](docs/img/r33_labelled.png)
 
-[Want one?](#manufacturing). More photos can be found [below](#photos). 
+- 3HP module compatible with modular synthesizer systems.
+    - Module depth is 35mm with both ribbon cables attached.
+- [PMOD](https://en.wikipedia.org/wiki/Pmod_Interface) connector compatible with many FPGA development boards.
+- 8 (4 in + 4 out) DC-coupled audio channels, 192KHz / 32bit sampling supported.
+- PWM-controlled, user-programmable red/green LEDs on each output channel.
+- Jack insertion detection on input & output jacks.
+- Calibration EEPROM for unique ID and storing calibration data.
+- [new!] Touch and proximity sensing on all unused jacks as an extra input method.
+    - Note: this is disabled by default, if you want to play with this feature some example gateware [is on a separate branch](https://github.com/apfelaudio/eurorack-pmod/commits/seb/touch-fsm-r33/). I'll merge it properly ASAP.
 
-### This project is:
-- The design for a Eurorack-compatible PCB and front-panel, including a [PMOD](https://en.wikipedia.org/wiki/Pmod_Interface) connector (compatible with most FPGA dev boards). PCB designed in [KiCAD](https://www.kicad.org/). Design is [certified open hardware](https://certification.oshwa.org/de000135.html).
-- Various [example cores](gateware/cores) (and calibration / driver cores for the audio CODEC) initially targeting an [iCEBreaker FPGA](https://1bitsquared.com/products/icebreaker) (iCE40 part) but many more boards are supported (see below). Examples include calibration, sampling, effects, synthesis sources and so on. The design files can be synthesized to a bitstream using Yosys' [oss-cad-suite](https://github.com/YosysHQ/oss-cad-suite-build).
-- A [VCV Rack plugin](https://github.com/schnommus/verilog-vcvrack) so you can simulate your Verilog designs in a completely virtual modular system, no hardware required.
+**Compared to R3.1, the changes across R3.2 and R3.3 [are summarized here](https://github.com/apfelaudio/eurorack-pmod/issues/50)**
+
+[Want one?](#manufacturing). More photos can be found [below](#photos).
 
 ## Included examples
 This repository contains a bunch of example DSP cores which are continuously being updated:
@@ -45,22 +58,10 @@ The following development boards have been tested with `eurorack-pmod` and are s
 - Colorlight i9 (ECP5 based)
 - pico-ice from TinyVision (iCE40 based)
 
-## Hardware details
-
-![labelled eurorack-pmod 3.0](docs/img/labelled.jpg)
-
-- 3HP module compatible with modular synthesizer systems.
-    - Module depth is 47mm with both ribbon cables attached
-    - This fits nicely in e.g. a 4MS POD 48X (pictured below).
-- PMOD connector compatible with most FPGA development boards.
-- 8 (4 in + 4 out) DC-coupled audio channels, 192KHz / 32bit sampling supported.
-- PWM-controlled, user-programmable red/green LEDs on each output channel.
-- Jack insertion detection on input & output jacks.
-- Calibration EEPROM for unique ID and storing calibration data.
-- I/O is about +/- 8V capable, wider is possible with a resistor change.
-
 ## PMOD Pinout
 
+![assembled eurorack-pmod module R3.3 (bottom)](docs/img/r33_bottom.jpg)
+
 The PMOD pinout is on the silkscreen on the back side of the board. Details are below. Note that Pin 1 is the SQUARE pad.
 
 1) SDI (AK4619VN SDIN1)
@@ -76,13 +77,9 @@ The PMOD pinout is on the silkscreen on the back side of the board. Details are
 11) 3V3 IN
 12) 3V3 IN
 
-## Gateware details
-- Examples based on iCE40 and ECP5 based FPGAs supported by open-source tools.
-- User-defined DSP logic is decoupled from rest of system (see [`gateware/cores`](gateware/cores) directory)
-
 ## Getting Started
 
-For now, I have tested builds on Linux and Windows (under MSYS2). Both are tested in CI.
+I have tested builds on Linux, Mac and Windows (under MSYS2). All are tested in CI.
 
 0. Install the [OSS FPGA CAD flow](https://github.com/yosyshq/oss-cad-suite-build).
     - You may be able to get yosys / verilator from other package managers but I recommend using the [releases from YosysHQ](https://github.com/yosyshq/oss-cad-suite-build) so you're using the same binaries that CI is using.
@@ -105,22 +102,50 @@ The project is split into 2 directories, [`hardware`](hardware) for the PCB/pane
 
 # Manufacturing
 
-Update: R3.1 SOLD OUT, revision R3.3 will land in the next 1-2 months - [get notified **here :)**](https://apfelaudio.com/modules/pmod/)
+**R3.3 hardware is in stock** [order **here :)**](https://apfelaudio.com/)
+
+~~Update: R3.1 SOLD OUT, revision R3.3 will land in the next 1-2 months - [get notified **here :)**](https://apfelaudio.com/modules/pmod/)~~
 
 ~~Update: R3.1 (first production release) is fully functional with 1 rework, see github issues for up-to-date information.~~
 
 ~~Note: I gave some R3.0 (preproduction) units out at Hackaday Berlin '23. These are tested but NOT calibrated. They had 2 hacks applied. Some inductors are shorted with 0 ohm resistors as the wrong inductor was populated (means the board is a bit noiser than it should be - but still definitely useable). Also the reset line of the jack detect IO expander was routed incorrectly, so I manually shorted 2 pins of that chip. Functionally these boards are the same as R3.1, which fixes these issues.~~
 
+# R3.1 Hardware (no longer manufactured)
+
+The above README focuses on R3.3, which is currently being manufactured.
+
+Revision R3.1 was sold out in 2023. It's no longer manufactured, however this repository still supports it if you use the `HW_REV=HW_R31` flag when building. I left some of the old photos here in case they are useful.
+
+From the gateware perspective, there is almost no difference between R3.1 and R3.3 and so any cores should be compatible with both (unless they use new features of R3.3 e.g. touch sensitive jacks).
+
+## R3.1 boards
+
+![assembled eurorack-pmod module R3.0 (panel)](docs/img/panel.jpg)
+![assembled eurorack-pmod module R3.0 (top)](docs/img/pmod_top.jpg)
+
+## R3.1 hardware details
+
+![labelled eurorack-pmod 3.0](docs/img/labelled.jpg)
+
+## R3.1 technical
+
+- 3HP module compatible with modular synthesizer systems.
+    - Module depth is 47mm with both ribbon cables attached
+    - This fits nicely in e.g. a 4MS POD 48X (pictured below).
+- PMOD connector compatible with most FPGA development boards.
+- 8 (4 in + 4 out) DC-coupled audio channels, 192KHz / 32bit sampling supported.
+- PWM-controlled, user-programmable red/green LEDs on each output channel.
+- Jack insertion detection on input & output jacks.
+- Calibration EEPROM for unique ID and storing calibration data.
+- I/O is about +/- 8V capable, wider is possible with a resistor change.
+
 
 ## Known limitations
 - Moved to github issues
 
 # Photos
 
-## Assembled `eurorack-pmod` (front)
-![assembled eurorack-pmod module (front)](docs/img/leds_front.jpg)
-
-## `eurorack-pmod` connected to iCEBreaker
+## `eurorack-pmod` R3.1 connected to iCEBreaker
 ![assembled eurorack-pmod module (in system)](docs/img/pmod_insystem.jpg)
 
 # License

gateware/Makefile

@@ -1,16 +1,18 @@
 ALL_BOARDS = $(shell ls boards)
 ALL_CORES = $(shell basename --suffix=.sv -- cores/*.sv)
+ALL_HW_REV = "HW_R31 HW_R33"
 
 CORE ?= mirror
 
 all prog:
 ifeq ($(BOARD),)
+	@echo "Valid HW_REV values are: $(ALL_HW_REV)".
 	@echo "Valid BOARD values are: $(ALL_BOARDS)".
 	@echo "Valid CORE values are: $(ALL_CORES)".
 	@echo "For example:"
 	@echo "  $$ make clean"
 	@echo "  $$ # Build bitstream with specific core and program it"
-	@echo "  $$ make BOARD=icebreaker CORE=stereo_echo prog"
+	@echo "  $$ make HW_REV=HW_R33 BOARD=icebreaker CORE=stereo_echo prog"
 	@exit 1
 endif
 ifeq ($(wildcard ./boards/$(BOARD)/Makefile),)
@@ -22,6 +24,11 @@ ifeq ($(wildcard ./cores/$(CORE).sv),)
 	@echo "'$(CORE).sv' does not exist in 'cores/'"
 	@echo "Valid targets are: $(ALL_CORES)".
 	@exit 3
+endif
+ifeq ($(HW_REV),)
+	@echo "Please specify a eurorack-pmod hardware revision using HW_REV=<>".
+	@echo "Valid hardware revisions are: '$(ALL_HW_REV)'".
+	@exit 4
 endif
 	mkdir -p build/$(BOARD)
 	# For now we always force a re-build since we can pass different DSP cores

gateware/cal/cal.sv

@@ -18,7 +18,11 @@
 
 module cal #(
     parameter W = 16, // sample width
-    parameter CAL_MEM_FILE = "cal/cal_mem.hex"
+`ifdef HW_R33
+    parameter CAL_MEM_FILE = "cal/cal_mem_default_r33.hex"
+`else
+    parameter CAL_MEM_FILE = "cal/cal_mem_default_r31.hex"
+`endif
 )(
     input rst,
     input clk_256fs,

gateware/cal/cal_mem_default_r33.hex

@@ -0,0 +1,4 @@
+// Input calibration constants
+@00000000 ff63 484 ff4a 485 40 48a ff74 485
+// Output calibration constants
+@00000008 fd3f 3e5 fda5 3e8 fdc8 3ee fd15 3ec

gateware/drivers/pmod_i2c_master.sv

@@ -5,6 +5,8 @@
 //    - 24AA025UIDT I2C EEPROM with unique ID
 //    - PCA9635 I2C PWM LED controller
 //    - PCA9557 I2C GPIO expander (for jack detection)
+// For HW Rev 3.2+, we also have:
+//    - CY8CMBR3108 I2C touch/proximity sensor (experiment, off by default!)
 //
 // This kind of stateful stuff is often best suited for a softcore rather
 // than pure Verilog, however I wanted to make it possible to use all
@@ -55,13 +57,15 @@ module pmod_i2c_master #(
 localparam I2C_DELAY1        = 0,
            I2C_EEPROM1       = 1,
            I2C_EEPROM2       = 2,
-           I2C_INIT_CODEC1   = 3,
-           I2C_INIT_CODEC2   = 4,
-           I2C_LED1          = 5, // <<--\ LED/JACK re-runs indefinitely.
-           I2C_LED2          = 6, //     |
-           I2C_JACK1         = 7, //     |
-           I2C_JACK2         = 8, // >>--/
-           I2C_IDLE          = 9;
+           I2C_INIT_TOUCH1   = 3,
+           I2C_INIT_TOUCH2   = 4,
+           I2C_INIT_CODEC1   = 5,
+           I2C_INIT_CODEC2   = 6,
+           I2C_LED1          = 7,  // <<--\ LED/JACK re-runs indefinitely.
+           I2C_LED2          = 8,  //     |
+           I2C_JACK1         = 9,  //     |
+           I2C_JACK2         = 10, // >>--/
+           I2C_IDLE          = 11;
 
 `ifdef COCOTB_SIM
 localparam STARTUP_DELAY_BIT = 4;
@@ -157,7 +161,12 @@ always_ff @(posedge clk) begin
                         11: begin
                             eeprom_serial[32-3*8-1:32-4*8] <= data_out;
                             cmd <= I2CMASTER_STOP;
+`ifdef HW_R33
+                            i2c_state <= I2C_INIT_TOUCH1;
+`else
+                            // For R31, don't try initializing touch sense
                             i2c_state <= I2C_INIT_CODEC1;
+`endif
                             delay_cnt <= 0;
                         end
                         default: begin
@@ -166,6 +175,51 @@ always_ff @(posedge clk) begin
                     i2c_config_pos <= i2c_config_pos + 1;
                     stb <= 1'b1;
                 end
+                I2C_INIT_TOUCH1: begin
+                    cmd <= I2CMASTER_START;
+                    stb <= 1'b1;
+                    i2c_state <= I2C_INIT_TOUCH2;
+                    i2c_config_pos <= 0;
+                end
+                // Switch off the CY8CMBR3108 by default, as it can cause the
+                // LEDs to flicker (due to NACKs) and increase noise in the
+                // audio chain, unless it is configured correctly (currently
+                // touch sensing prototyping is on a separate branch, let's
+                // keep it out of master for now)
+                I2C_INIT_TOUCH2: begin
+                    case (i2c_config_pos)
+                        0: begin
+                            cmd <= I2CMASTER_START;
+                        end
+                        1: begin
+                            // 0x37 << 1 | 0 (W)
+                            data_in <= 8'h6E;
+                            cmd <= I2CMASTER_WRITE;
+                        end
+                        2: begin
+                            if (ack_out == 1'b0) begin
+                                // Write to command register
+                                data_in <= 8'h86;
+                                cmd <= I2CMASTER_WRITE;
+                            end else begin
+                                cmd <= I2CMASTER_STOP;
+                                i2c_state <= I2C_INIT_TOUCH1;
+                            end
+                        end
+                        3: begin
+                            // Disable + enter low-power mode.
+                            data_in <= 8'h07;
+                            cmd <= I2CMASTER_WRITE;
+                        end
+                        4: begin
+                            cmd <= I2CMASTER_STOP;
+                            i2c_state <= I2C_INIT_CODEC1;
+                        end
+                    endcase
+                    i2c_config_pos <= i2c_config_pos + 1;
+                    ack_in <= 1'b1;
+                    stb <= 1'b1;
+                end
                 I2C_INIT_CODEC1: begin
                     cmd <= I2CMASTER_START;
                     stb <= 1'b1;

gateware/eurorack_pmod.sv

@@ -9,7 +9,6 @@
 
 module eurorack_pmod #(
     parameter W = 16, // sample width, bits
-    parameter CAL_MEM_FILE = "cal/cal_mem.hex",
     parameter CODEC_CFG_FILE  = "drivers/ak4619-cfg.hex",
     parameter LED_CFG_FILE  = "drivers/pca9635-cfg.hex"
 )(
@@ -73,8 +72,7 @@ logic signed [W-1:0] sample_dac3;
 // Compensates for DC bias in CODEC, gain differences, resistor
 // tolerances and so on.
 cal #(
-    .W(W),
-    .CAL_MEM_FILE(CAL_MEM_FILE)
+    .W(W)
 ) cal_instance (
     .rst(rst),
     .clk_256fs (clk_256fs),