shorepine · bwhitman · Oct 12, 2024 · Oct 7, 2024 · Oct 7, 2024 · Oct 8, 2024
diff --git a/README.md b/README.md
@@ -46,7 +46,7 @@ Tulip CC supports:
 - Can load PNGs from disk to set sprites or background, or generate bitmap data from code
 - Built in code and text editor
 - Built in BBS chat room and file transfer area called **TULIP ~ WORLD**
-- USB keyboard support
+- USB keyboard, MIDI and mouse support, including hubs 
 - Capactive multi-touch support (mouse on Tulip Desktop)
 - MIDI input and output
 - I2C / Grove / Mabee connector, compatible with [many I2C devices like joysticks, keyboard, GPIO, DACs, ADCs, hubs](docs/tulip_api.md#i2c--grove--mabee)
@@ -96,7 +96,7 @@ edit("game.py")
 
 ### Input and user interface
 
-Tulip supports USB keyboard input and touch input. (On Tulip Desktop, mouse clicks act as touch points.) It also comes with UI elements like buttons and sliders to use in your applications, and a way to run mulitple applications as once using callbacks. More in the [full API](docs/tulip_api.md).
+Tulip supports USB keyboard and mice input as well as touch input. (On Tulip Desktop, mouse clicks act as touch points.) It also comes with UI elements like buttons and sliders to use in your applications, and a way to run mulitple applications as once using callbacks. More in the [full API](docs/tulip_api.md).
 
 ```python
 (x0, y0, x1, y1, x2, y2) = tulip.touch()

diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -31,10 +31,11 @@ The Tulip board you got can work on its own. Most people will want to add a coup
 
 Tulip is a very command-line centered interface with some touch controls. You'll have a much easier time using Tulip if you connect a USB computer keyboard to it for typing. It turns the Tulip into a portable "deck" for whatever you can imagine. 
 
-You can use _almost_ any USB computer keyboard you already have. However, a keyboard including an internal USB hub will not work. You can tell if a keyboard includes a hub if it has one or more subsidiary USB sockets (e.g. for connecting a mouse), or if it includes an integrated pointing device (trackpad, trackball etc). These keyboards are not compatible with Tulip. 
+You _should_ be able to use any USB computer keyboard you already have. We're always surprised to find weird keyboards that don't follow all the "rules", so if yours doesn't "just work", get in touch and we'll help you debug!
 
 [If you want a more compact hardware keyboard, the tiny "cardKB" will work great with Tulip, plugged into the I2C port.](https://shop.m5stack.com/products/cardkb-mini-keyboard-programmable-unit-v1-1-mega8a)
 
+
 ### DACs or ADCs for modular synths
 
 If you use modular synths, Tulip is a powerful and fun control surface and way to "program" your modular rig or older analog synth in Python. You can use the existing MIDI ports to do a lot, but if you have CV gear, we recommend getting a I2C DAC to control it. [You can get a 2 channel DAC with modular ready 3.5mm jacks from Makerfabs](https://www.makerfabs.com/mabee-dac-gp8413.html). You can use up to 8 at once for a total of 16 CV outputs!
@@ -43,14 +44,20 @@ If you use modular synths, Tulip is a powerful and fun control surface and way t
 
 ### Type-A 3.5mm MIDI adapters to full size
 
-Most modern MIDI equipment now uses 3.5mm jacks for MIDI connectors. If you have the older 5-pin DIN connectors and want to use them on Tulip, you'll want to pick up a couple of [Type-A 3.5mm adapters](https://www.amazon.com/Kurrent-Electric-Type-3-5mm-Adapter/dp/B0C2RLB3SL/). 
+We support both USB MIDI and "standard" TRS MIDI. Most modern MIDI equipment now uses 3.5mm jacks for MIDI connectors. If you have the older 5-pin DIN connectors and want to use them on Tulip, you'll want to pick up a couple of [Type-A 3.5mm adapters](https://www.amazon.com/Kurrent-Electric-Type-3-5mm-Adapter/dp/B0C2RLB3SL/). 
+
+### A hub for USB MIDI
+
+If you want to use a USB MIDI device (like a keyboard or a USB-MIDI adapter), we support that on Tulip from the `USB-KB` connector. We also support simple hubs, since you'll want to connect both a USB MIDI plug and a typing keyboard. USB hub support works but is in constant development, so please let us know if your setup doesn't work! 
 
 ### A small li-po battery
 
 Tulip is a low power device and can run on battery for portable computing. There's a standard JST connector on back for flat li-po or 18650 battery packs. Tulip will charge the battery if you connect a USB power cable to the USB charge/PWR port (the top one.) I personally use [this 1200mAh battery](https://www.adafruit.com/product/258). If you want to keep it "inside" Tulip (between the back case and the PCB), you'll want to find a battery that is 5mm or so thin. You can use a piece of double sided tape it keep it inside the battery area of the PCB. 
 
 Larger batteries will work great and last longer, but you'll have to remove the back case to make them fit (or mount the battery some other way.) [This 5200mAh battery pack](https://www.amazon.com/XINLANTECH-Rechargeable-Bluetooth-Electronic-Batteries/dp/B0C2VFTDPY) will last many many hours on Tulip and fit right on the PCB with the back case removed. 
 
+**Please make sure you have the polarity right!** The red cable on the battery should be going to the side of the connector with a + sign on the Tulip board. 
+
 ### An extra Alles or five
 
 <img src="https://raw.githubusercontent.com/shorepine/tulipcc/main/docs/pics/nicoboard-alles.jpg" width=400>

diff --git a/docs/music.md b/docs/music.md
@@ -19,6 +19,7 @@ Tulip is a **music computer** where everything about the underlying synthesis an
  - Control CV outputs for modular synths and analog synths, with built in waveforms and sample & hold 
  - Sample CV inputs from an ADC to control other events on Tulip 
  - Send MIDI in and out, from code. You can write code to respond to MIDI messages to do whatever you want
+ - Use USB MIDI devices like keyboards or synthesizers or adapters connected to Tulip's USB-KB port (with a hub to still support typing keyboards)
  - Share a common sequencer clock across multiple apps, for example, a drum machine and an arpeggiator 
  - Add global EQ, chorus, echo or reverb to the audio output
  - A scale and chord library to define musical notes in code, e.g. `music.Chord("F:min")`
@@ -31,7 +32,7 @@ If you're using [Tulip Desktop](tulip_desktop.md) instead of a real Tulip, thing
 
 ## The built-in Tulip synthesizer
 
-When you start up your Tulip, it is configured to receive MIDI messages from the MIDI in port. You can plug in any MIDI device that sends MIDI out, like a MIDI keyboard or your computer running a sequencer. 
+When you start up your Tulip, it is configured to receive MIDI messages from the MIDI in port (or the USB MIDI port if connected.) You can plug in any MIDI device that sends MIDI out, like a MIDI keyboard or your computer running a sequencer. 
 
 Try to just play notes once you've turned on Tulip, By default, MIDI channel 1 plays a Juno-6 patch. Notes on channel 10 will play PCM patches, roughly aligned with General MIDI drums. 
 

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -78,7 +78,7 @@ You can see how to use them with Olav's `boot.py`: `world.download('boot.py', 'o
 
 ## USB computer keyboard not working
 
-If your USB computer keyboard is not working, the most likely explanation is that it appears as a "hub" instead of a bare keyboard to Tulip. At this time (we're working on it!) Tulip only supports "root" devices. You'll have to try another keyboard. If you think your keyboard should work, please find us on [issues](https://github.com/shorepine/tulipcc/issues) or the [Discord](https://discord.gg/TzBFkUb8pG) and we'll help out!
+If your USB computer keyboard is not working, please find us on [issues](https://github.com/shorepine/tulipcc/issues) or the [Discord](https://discord.gg/TzBFkUb8pG) and we'll help out! We have tested many keyboards but since we have to build this support ourselves there are likely edge cases we haven't run into yet. 
 
 ## The Mabee DAC is not correctly sending CV / Gate values to your modular synthesizer
 

diff --git a/docs/tulip_api.md b/docs/tulip_api.md
@@ -285,7 +285,9 @@ def run(screen):
 
 ## Input
 
-Tulip supports USB keyboard input and touch input. It also supports a software on-screen keyboard, and any I2C connected keyboard or joystick on Tulip CC. On Tulip Desktop, mouse clicks act as touch points, and your computers' keyboard works.
+Tulip supports USB keyboard input, USB mouse input, and touch input. It also supports a software on-screen keyboard, and any I2C connected keyboard or joystick on Tulip CC. On Tulip Desktop, mouse clicks act as touch points, and your computers' keyboard works. 
+
+If you have a USB mouse connected to Tulip (presumably through a hub) it will, by default, show a mouse pointer and treat clicks as touch downs. 
 
 ```python
 # Returns a mask of joystick-like presses from the keyboard, from arrow keys, Z, X, A, S, Q, W, enter and '
@@ -503,6 +505,10 @@ See the example `seq.py` on Tulip World for an example of using the music clock,
 
 Tulip supports MIDI in and out to connect to external music hardware. You can set up a python callback to respond immediately to any incoming MIDI message. You can also send messages out to MIDI out. 
 
+You can use MIDI over USB as well, using the `USB-KB` connector. Note this is meant as a **host** connector: you can connect USB MIDI keyboards or USB MIDI interfaces to Tulip. You cannot connect Tulip directly to a computer as a "USB MIDI gadget". If you want your Tulip to control your computer, use a MIDI interface on your computer and wire Tulip's MIDI out to it. 
+
+If you have a USB MIDI adapter connected, MIDI out from Tulip will go to USB, not the TRS MIDI connectors. MIDI in can come into either TRS or USB. 
+
 By default, Tulip boots into a live MIDI synthesizer mode. Any note-ons, note-offs, program changes or pitch bend messages will be processed automatically with polyphony and voice stealing, and Tulip will play the tones with no other user intervention needed.
 
 By default, MIDI notes on channel 1 will map to Juno-6 patch 0. And MIDI notes on channel 10 will play the PCM samples (like a drum machine).

diff --git a/docs/tulip_board.md b/docs/tulip_board.md
@@ -11,7 +11,7 @@ If you're comfortable with surface mount soldering, you can put together your ow
 
 [The BOM for the latest revision is here.](https://github.com/shorepine/tulipcc/blob/main/docs/pcbs/tulip4_board_v4r9/tulipcc-bom.xlsx) [KiCad files are here.](https://github.com/shorepine/tulipcc/tree/main/docs/pcbs/tulip4_board_v4r9) 
 
-Almost_ any USB keyboard should work. Please ensure it's just a keyboard -- if it has a trackpad, or extra USB ports on it, or anything else, it likely [won't work as we only support single root USB devices.](https://github.com/shorepine/tulipcc/issues/40).
+_Almost_ any USB keyboard should work. 
 
 If this looks too hard, you can [instead make a breakout board with just through hole solder](tulip_breakout.md), or [with no soldering and a breadboard.](tulip_breadboard.md)
 

diff --git a/docs/tulip_board_r9.md b/docs/tulip_board_r9.md
@@ -11,7 +11,7 @@ If you're comfortable with surface mount soldering, you can put together your ow
 
 [The BOM for the latest revision is here.](https://github.com/shorepine/tulipcc/blob/main/docs/pcbs/tulip4_board_v4r9/tulipcc-bom.xlsx) [KiCad files are here.](https://github.com/shorepine/tulipcc/tree/main/docs/pcbs/tulip4_board_v4r9) 
 
-Almost_ any USB keyboard should work. Please ensure it's just a keyboard -- if it has a trackpad, or extra USB ports on it, or anything else, it likely [won't work as we only support single root USB devices.](https://github.com/shorepine/tulipcc/issues/40).
+_Almost_ any USB keyboard should work. 
 
 If this looks too hard, you can [instead make a breakout board with just through hole solder](tulip_breakout.md), or [with no soldering and a breadboard.](tulip_breadboard.md)
 

diff --git a/docs/tulip_breadboard.md b/docs/tulip_breadboard.md
@@ -14,7 +14,7 @@ You'll need
 - [This $58 RGB dot-clock 10.1" display with capacitive touch.](https://www.hotmcu.com/101-inch-1024x600-tft-lcd-display-with-capacitive-touch-panel-p-215.html) Note other RGB dot clock displays of different sizes and resolutions can also work, but the pin numberings will be different and you'll have to update the resolution in our code. 
 - [A 40-pin FPC header for the display.](https://www.adafruit.com/product/4905)
 - One of two choices for sound: either [this mono I2S speaker amp board](https://www.adafruit.com/product/3006) (you'll also need a 3W speaker) or this stereo line-out / headphone jack [UDA1334 DAC.](https://www.aliexpress.com/item/3256803337983466.html?gatewayAdapt=4itemAdapt) 
-- _Almost_ any USB keyboard should work. Please ensure it's just a keyboard -- if it has a trackpad, or extra USB ports on it, or anything else, it likely [won't work as we only support single root USB devices.](https://github.com/shorepine/tulipcc/issues/40) If yours doesn't, please file an issue here and I can investigate with you. I can only test the ones I have here! I do recommend the [Keychron series of mechanical keyboards](https://www.keychron.com/products/keychron-k7-ultra-slim-wireless-mechanical-keyboard?variant=39396239048793), they're inspiringly clicky. 
+- _Almost_ any USB keyboard should work.
 - If you want to support an optional NES or SNES joytstick, [get the right connector.](https://www.zedlabz.com/collections/retro-nintendo-snes/products/zedlabz-7-pin-90-degree-female-controller-connector-port-for-nintendo-snes-console-2-pack-grey)
 - Connectors and random parts: 
    - [1 USB female A screw terminal](https://www.amazon.com/Poyiccot-Terminal-Connector-Converter-Breakout/dp/B08Y8NKGHL)

diff --git a/docs/tulip_breakout.md b/docs/tulip_breakout.md
@@ -22,7 +22,7 @@ You'll need:
 -  [This $58 RGB dot-clock 10.1" display with capacitive touch.](https://www.hotmcu.com/101-inch-1024x600-tft-lcd-display-with-capacitive-touch-panel-p-215.html) Note other RGB dot clock displays of different sizes and resolutions can also work, but the pin numberings will be different and you'll have to update the resolution in our code. 
 - [A 40-pin FPC header for the display.](https://www.adafruit.com/product/4905) 
 - This stereo line-out / headphone jack [UDA1334 DAC.](https://www.aliexpress.com/item/3256803337983466.html?gatewayAdapt=4itemAdapt) 
-- _Almost_ any USB keyboard should work. Please ensure it's just a keyboard -- if it has a trackpad, or extra USB ports on it, or anything else, it likely [won't work as we only support single root USB devices.](https://github.com/shorepine/tulipcc/issues/40) If yours doesn't, please file an issue here and I can investigate with you. I can only test the ones I have here! I do recommend the [Keychron series of mechanical keyboards](https://www.keychron.com/products/keychron-k7-ultra-slim-wireless-mechanical-keyboard?variant=39396239048793), they're inspiringly clicky. 
+- _Almost_ any USB keyboard should work. 
 - Connectors and random parts: 
    - [Female headers are recommended, so you don't solder the ESP and audio jack directly to the PCB.](https://www.adafruit.com/product/598) 
    - I'd also get this [2x20 shrouded header](https://www.adafruit.com/product/1993) for the display FPC breakout. 

diff --git a/docs/tulip_flashing.md b/docs/tulip_flashing.md
@@ -61,18 +61,22 @@ Linux:
 sudo apt install cmake ninja-build dfu-util virtualenv
 ```
 
-For both macOS & Linux, next, download the supported version of ESP-IDF. That is currently 5.2. [You can download it directly here.](https://dl.espressif.com/github_assets/espressif/esp-idf/releases/download/v5.2/esp-idf-v5.2.zip) Unpack it to a folder. I like to keep them in `~/esp/`, as you'll likely want to use different versions eventually. So we'll assume it's in `~/esp/esp-idf-v5.2`.
+For both macOS & Linux, next, download the supported version of ESP-IDF. That is currently a pre-release of 5.4. You need to get this with `git`, so install that if you don't already have it. Once Espressif updates the release, we can provide a direct download link that's a bit easier. 
+
+I like to keep them in `~/esp/`, as you'll likely want to use different versions eventually. So we'll assume it's in `~/esp/esp-idf`.
 
 Also, clone this Tulip repository. We'll assume it's in `~/tulipcc`.
 
 ```bash
 cd ~
 mkdir esp
 cd esp
-curl -O https://dl.espressif.com/github_assets/espressif/esp-idf/releases/download/v5.2/esp-idf-v5.2.zip
-unzip esp-idf-v5.2.zip
-esp-idf-v5.2/install.sh esp32s3
-source ~/esp/esp-idf-v5.2/export.sh
+git clone https://github.com/espressif/esp-idf.git
+cd esp-idf
+git checkout 70f222e5d29df8ffe5da25057601708c8097bcd1
+git submodule update --init --recursive
+./install.sh esp32s3
+source export.sh
 
 cd ~
 git clone https://github.com/shorepine/tulipcc.git 
@@ -111,7 +115,7 @@ To build and flash going forward, without modifying the filesystem:
 
 ```bash
 cd tulip/esp32s3
-source ~/esp/esp-idf-v5.2/export.sh # do this once per terminal window
+source ~/esp/esp-idf/export.sh # do this once per terminal window
 idf.py -DMICROPY_BOARD=[X] flash 
 idf.py monitor # shows stderr and stdin for controlling Tulip, use control-] to quit
 

diff --git a/micropython b/micropython
diff --git a/tulip/esp32s3/CMakeLists.txt b/tulip/esp32s3/CMakeLists.txt
@@ -67,7 +67,7 @@ set(SDKCONFIG_DEFAULTS ${CMAKE_BINARY_DIR}/sdkconfig.combined)
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 
 # Set the location of the main component for the project (one per target).
-set(EXTRA_COMPONENT_DIRS main components)
+#set(EXTRA_COMPONENT_DIRS main components)
 
 # Define the project.
 project(micropython)

diff --git a/tulip/esp32s3/boards/MATOUCH7/mpconfigboard.cmake b/tulip/esp32s3/boards/MATOUCH7/mpconfigboard.cmake
@@ -13,8 +13,9 @@ set(SDKCONFIG_DEFAULTS
 )
 
 
-list(APPEND MICROPY_SOURCE_PORT
+list(APPEND MICROPY_SOURCE_BOARD
      gt911_touchscreen.c
      esp32s3_display.c
-     usb_keyboard.c
+      esp_lcd_touch_gt911.c
+     usb_host.c
 )
diff --git a/tulip/esp32s3/boards/MATOUCH7/mpconfigboard.h b/tulip/esp32s3/boards/MATOUCH7/mpconfigboard.h
@@ -7,5 +7,15 @@
 // Enable UART REPL for modules that have an external USB-UART and don't use native USB.
 #define MICROPY_HW_ENABLE_UART_REPL         (1)
 
+
 #define MICROPY_HW_I2C0_SCL                 (I2C_SCL)
 #define MICROPY_HW_I2C0_SDA                 (I2C_SDA)
+
+#define MICROPY_HW_ENABLE_SDCARD            (0)
+#define MICROPY_PY_MACHINE_I2S              (0)
+#define MICROPY_PY_BLUETOOTH (0)
+#define MICROPY_BLUETOOTH_NIMBLE (0)
+#define MICROPY_HW_USB_CDC (1)
+#define MICROPY_HW_ENABLE_USBDEV (1)
+#define MICROPY_HW_ESP_USB_SERIAL_JTAG (0)
+#define MICROPY_ENABLE_SCHEDULER (1)
diff --git a/tulip/esp32s3/boards/MATOUCH7/pins.csv b/tulip/esp32s3/boards/MATOUCH7/pins.csv
@@ -0,0 +1,5 @@
+I2C_SCL,GPIO9
+I2C_SDA,GPIO8
+FG_INT,GPIO21
+UART0_TX,GPIO43
+UART0_RX,GPIO44
diff --git a/tulip/esp32s3/boards/N16R8/mpconfigboard.cmake b/tulip/esp32s3/boards/N16R8/mpconfigboard.cmake
@@ -12,8 +12,8 @@ set(SDKCONFIG_DEFAULTS
     boards/N16R8/sdkconfig.board
 )
 
-list(APPEND MICROPY_SOURCE_PORT
+list(APPEND MICROPY_SOURCE_BOARD
      esp32s3_display.c
-     usb_keyboard.c
+     usb_host.c
      ft5x06_touchscreen.c
 )
diff --git a/tulip/esp32s3/boards/N16R8/mpconfigboard.h b/tulip/esp32s3/boards/N16R8/mpconfigboard.h
@@ -10,3 +10,12 @@
 
 #define MICROPY_HW_I2C0_SCL                 (I2C_SCL)
 #define MICROPY_HW_I2C0_SDA                 (I2C_SDA)
+
+#define MICROPY_HW_ENABLE_SDCARD            (0)
+#define MICROPY_PY_MACHINE_I2S              (0)
+#define MICROPY_PY_BLUETOOTH (0)
+#define MICROPY_BLUETOOTH_NIMBLE (0)
+#define MICROPY_HW_USB_CDC (1)
+#define MICROPY_HW_ENABLE_USBDEV (1)
+#define MICROPY_HW_ESP_USB_SERIAL_JTAG (0)
+#define MICROPY_ENABLE_SCHEDULER (1)
diff --git a/tulip/esp32s3/boards/N16R8/pins.csv b/tulip/esp32s3/boards/N16R8/pins.csv
@@ -0,0 +1,5 @@
+I2C_SCL,GPIO9
+I2C_SDA,GPIO8
+FG_INT,GPIO21
+UART0_TX,GPIO43
+UART0_RX,GPIO44
diff --git a/tulip/esp32s3/boards/N32R8/mpconfigboard.cmake b/tulip/esp32s3/boards/N32R8/mpconfigboard.cmake
@@ -11,8 +11,8 @@ set(SDKCONFIG_DEFAULTS
     boards/N32R8/sdkconfig.board
 )
 
-list(APPEND MICROPY_SOURCE_PORT
+list(APPEND MICROPY_SOURCE_BOARD
      esp32s3_display.c
      ft5x06_touchscreen.c
-     usb_keyboard.c
+     usb_host.c
 )
diff --git a/tulip/esp32s3/boards/N32R8/mpconfigboard.h b/tulip/esp32s3/boards/N32R8/mpconfigboard.h
@@ -10,3 +10,12 @@
 
 #define MICROPY_HW_I2C0_SCL                 (I2C_SCL)
 #define MICROPY_HW_I2C0_SDA                 (I2C_SDA)
+
+#define MICROPY_HW_ENABLE_SDCARD            (0)
+#define MICROPY_PY_MACHINE_I2S              (0)
+#define MICROPY_PY_BLUETOOTH (0)
+#define MICROPY_BLUETOOTH_NIMBLE (0)
+#define MICROPY_HW_USB_CDC (1)
+#define MICROPY_HW_ENABLE_USBDEV (1)
+#define MICROPY_HW_ESP_USB_SERIAL_JTAG (0)
+#define MICROPY_ENABLE_SCHEDULER (1)
diff --git a/tulip/esp32s3/boards/N32R8/pins.csv b/tulip/esp32s3/boards/N32R8/pins.csv
@@ -0,0 +1,5 @@
+I2C_SCL,GPIO9
+I2C_SDA,GPIO8
+FG_INT,GPIO21
+UART0_TX,GPIO43
+UART0_RX,GPIO44
diff --git a/tulip/esp32s3/boards/TDECK/mpconfigboard.cmake b/tulip/esp32s3/boards/TDECK/mpconfigboard.cmake
@@ -13,8 +13,11 @@ set(SDKCONFIG_DEFAULTS
     boards/TDECK/sdkconfig.board
 )
 
-list(APPEND MICROPY_SOURCE_PORT
+list(APPEND MICROPY_SOURCE_BOARD
      tdeck_display.c
      tdeck_keyboard.c
+     esp_lcd_touch_gt911.c
      gt911_touchscreen.c
+     ../../micropython/ports/esp32/usb_serial_jtag.c
 )
+