shorepine · bwhitman · Jan 23, 2024 · Jan 19, 2024 · Jan 20, 2024 · Jan 20, 2024
diff --git a/.gitignore b/.gitignore
@@ -9,9 +9,14 @@ tulip/macos/tulip
 tulip/macos/tulip.arm64
 tulip/macos/tulip.x86_64
 tulip/macos/dist
-tulip/linux/build-standard/
+tulip/linux/build-standard
 tulip/linux/dev
 tulip/ios/build-standard
+tulip/esp32s3/managed_components
+tulip/tdeck/build
+tulip/tdeck/managed_components
+tulip/tulipcc_r10/build
+tulip/tulipcc_r10/managed_components
 .submodules_ok
 
 # Prerequisites

diff --git a/docs/tulip_api.md b/docs/tulip_api.md
@@ -10,7 +10,9 @@ Here you can see the API [Tulip](../README.md) currently ships with.
 
 ## General
 
-[Tulip](../README.md) boots right into a Python prompt and all interaction with the system happens there. You can make your own Python programs with Tulip's built in editor and execute them, or just experiment on the Tulip REPL prompt in real time.
+[Tulip](../README.md) boots right into a Python prompt and all interaction with the system happens there. You have your own space to store code and files in `/user` and we keep system examples and programs in `/sys`. 
+
+You can make your own Python programs with Tulip's built in editor and execute them, or just experiment on the Tulip REPL prompt in real time.
 
 ```python
 # Interact with the filesystem.
@@ -23,8 +25,9 @@ cd('directory')
 clear
 
 # Run a saved Python file. Control-C stops it
-cd('ex') # The ex folder has a few examples and graphics in it
+cd('/sys/ex') # The /sys/ex folder has a few examples and graphics in it
 execfile("parallax.py")
+
 run('game') # Runs a package, see below
 
 # Extract a .tar file.
@@ -36,7 +39,7 @@ tulip.tar_create(directory)
 # If you want something to run when Tulip boots, add it to boot.py
 edit("boot.py")
 
-# On Tulip CC with 16MB of flash or more, you can upgrade the firmware over-the-air over wifi
+# You can upgrade the firmware over-the-air over wifi
 tulip.upgrade()
 
 # Takes a screenshot and saves to disk. The screen will blank for a moment
@@ -49,8 +52,6 @@ imgur_url = tulip.screenshot()
 usage = tulip.cpu() # or use tulip.cpu(1) to show more detail in a connected UART
 
 ms = tulip.ticks_ms() # returns the milliseconds since boot, aka Arduino millis() 
-
-tulip.off() # Shuts down Tulip. On hardware, the button up top will turn it back on.
 ```
 
 If you have a program that relies on mulitple files (graphics, or multiple Python files) you'll want to create a Tulip Package. A package is just a folder with your files in it, like:
@@ -342,22 +343,6 @@ tulip.gpu_reset()
 clock = tulip.display_clock() 
 tulip.display_clock(mhz)
 
-# You can also change the timing and resolution on the fly. 
-# This is helpful for getting higher FPS with lower resolution (less pixels)
-# If h_visible or v_visible is smaller than the resolution of the display, we will draw the whole h_res and v_res
-# to the display but center your visible res in a window. This is helpful for the Tulip CC display which cannot 
-# easily change native resolution. Your FPS will stay the same but you will have more GPU time to draw in the window.
-
-# H_RES, V_RES, H_VISIBLE_RES, V_VISIBLE_RES should be multiples of the Tulip default font size -- 8 x 12.
-(h_res, v_res, h_offscreen_px, v_offscreen_px, h_visible_res, v_visible_res,
-  hsync_back_porch, hsync_front_porch, hsync_pulse_width, 
-  vsync_back_porch, vsync_front_porch, vsync_pulse_width) = tulip.timing() # returns current
-tulip.timing(1024, 600, 256, 150, 139, 140, 20, 20, 12, 20) # sets, will erase all display RAM
-
-# You can set the visible window on its own with
-tulip.window(1024, 240)
-(w,h) = tulip.window()
-
 # Convenience function for getting the screen width and height,
 # which are just the first two values returned by tulip.timing()
 (WIDTH, HEIGHT) = tulip.screen_size()
@@ -386,9 +371,8 @@ tulip.frame_callback() # disables the callback
 # Sets the screen brightness, from 1-9 (9 max brightness.) 5 is default.
 tulip.brightness(5)
 
-# Show a log of the GPU usage (frames per second, time spent in GPU) to the stderr log
-tulip.gpu_log_start()
-tulip.gpu_log_stop()
+# Show the GPU usage (frames per second, time spent in GPU) at the next GPU epoch (100 frames) in stderr 
+tulip.gpu_log()
 ```
 
 ## Graphics background plane
@@ -574,23 +558,22 @@ You can also use the sprite RAM to also draw lists of lines. You can store lists
 
 You can also load 3D models as wireframes in from standard `obj` files, and set their rotation and scale, which will render a list of line positions for you to sprite line list RAM. 
 
-You can choose a color per line. It's encoded into the top bits of the x0 and x1 coordinates in sprite RAM. So each line only takes 8 bytes in sprite RAM.
 
 ```python
 # Load an obj file into a list of raw faces and vertices - unscaled and unrotated.
 model = tulip.wire_load("teapot.obj")
 # A model encodes vertices and faces of a 3d model. You can also generate this model in code yourself.  
 
 # Draw model wireframe to a line buffer
-lines = tulip.wire_to_lines(model, x, y, scale, theta, color)
+lines = tulip.wire_to_lines(model, x, y, scale, theta, max_faces)
 # scale = integer multiplier on 0..1 coordinates. in general, sets width/height of model as pixels
 # theta = # of 100.0/PI rotations
-# color = chooses the color of the entire model
+# max_faces = optional, cuts the model off at a number of faces (3 lines). if not given uses all faces in model
 
 # You can also generate line lists yourself in code.
 lines = tulip.lines([
-    [x0_0,y0_0,x1_0,y1_0,color_0],
-    [x0_1,y0_1,x1_1,y1_1,color_1]
+    [x0_0,y0_0,x1_0,y1_0],
+    [x0_1,y0_1,x1_1,y1_1]
     ]) # will return packed buffer of lines, sorted, including the last sentinel line
 
 # However you got your lines buffer, you can now load it into sprite RAM at whatever position you want. 

diff --git a/docs/tulip_board_r9.md b/docs/tulip_board_r9.md
@@ -0,0 +1,46 @@
+# The Tulip Creative Computer Board
+
+##  🌈🌈 Revision 9 🌈🌈
+This page is for **revision 9**.  
+
+![Tulip Board](https://raw.githubusercontent.com/bwhitman/tulipcc/main/docs/pics/nicoboard-pcb.png)
+
+TulipCC fan NicoVR designed an integrated [Tulip CC](../README.md) board. It's the nicest way to DIY your own Tulip: a display FPC connector, USB-C connector for charging, power and flashing, USB keyboard connector, 3 3.5mm jacks for audio + headphone out, MIDI in, and MIDI out, a power switch, and I2C "grove / stemma" header.
+
+If you're comfortable with surface mount soldering, you can put together your own board relatively easily. You can order the PCBs from any board manufacturer like OSH Park, PCBway, or JLCPCB. You can also upload the BOM file to a service to have the entire board manufactured for you.
+
+[The BOM for the latest revision is here.](https://github.com/bwhitman/tulipcc/blob/main/docs/pcbs/tulip4_board_v4r9/tulipcc-bom.xlsx) [KiCad files are here.](https://github.com/bwhitman/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/bwhitman/tulipcc/issues/40).
+
+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)
+
+![Tulip Board](https://raw.githubusercontent.com/bwhitman/tulipcc/main/docs/pics/nicoboard-assembled.jpg)
+
+
+## Assembly tips
+
+I've found assembling a Tulip with a hot plate and stencil the easiest way to go. You can get stencils from your PCB manufacturer when you're ordering the boards. 
+
+Attach the FPC cable to the RGB port on the display. You can use the cable that comes with the display.
+
+
+## Power
+
+The board can be powered from USB-C or via battery. 
+
+![With Alles](https://raw.githubusercontent.com/bwhitman/tulipcc/main/docs/pics/nicoboard-alles.jpg)
+
+## MIDI
+
+The 3.5mm MIDI jacks are for Type A TRS MIDI connectors. If you want to wire them to full size MIDI connectors, you should get [Type A converters.](https://www.amazon.com/ZAWDIO-Breakout-LittleBits-Female-Electribe/dp/B08WHSP7ZL/) You can also get Type-A to Type-B converter cables if your equipment is mostly Type B. 
+
+## Flash and startup
+
+After you're done assembling, [read about how to compile and flash Tulip.](tulip_flashing.md)
+
+
+
+
+
+
diff --git a/docs/tulip_breadboard.md b/docs/tulip_breadboard.md
@@ -10,7 +10,7 @@ If you'd rather make something more permanent, you can [instead make a breakout
 You'll need
 
 - A breadboard
-- [ESP32-S3 WROOM-1 N32R8 dev board](https://www.adafruit.com/product/5364). The N32R8 has 32MB of flash. You can also use the N8R8 with 8MB of flash but the speed of the display will be slightly slower and you won't be able to perform over-the-air upgrades as you won't have enough space. The 32MB is the same price, so get that if you can! 
+- [ESP32-S3 WROOM-1 N32R8 dev board](https://www.adafruit.com/product/5364). The N32R8 has 32MB of flash. You can also use the N16R8 with 16MB of flash.
 - [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) 

diff --git a/docs/tulip_breakout.md b/docs/tulip_breakout.md
@@ -18,7 +18,7 @@ The [Eagle files for this breakout PCB are here.](https://github.com/bwhitman/tu
 
 You'll need:
 
-- [ESP32-S3 WROOM-1 N32R8 dev board](https://www.adafruit.com/product/5364). The N32R8 has 32MB of flash. You can also use the N8R8 with 8MB of flash but the speed of the display will be slightly slower and you won't be able to perform over-the-air upgrades as you won't have enough space. The 32MB is the same price, so get that if you can!
+- [ESP32-S3 WROOM-1 N32R8 dev board](https://www.adafruit.com/product/5364). The N32R8 has 32MB of flash. You can also use the N16R8 with 16MB of flash.
 -  [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) 

diff --git a/docs/tulip_desktop.md b/docs/tulip_desktop.md
@@ -58,13 +58,6 @@ cd tulip/linux
 ./dev/tulip
 ```
 
-## Smaller REPL font
-
-To use the 6x8 REPL font (instead of 8x12), change the `./build.sh` to call
-
-```
-COPT='-DTULIP_REPL_FONT_8X6' make DEBUG=1
-```
 
 ## Windows build of Tulip Desktop
 

diff --git a/docs/tulip_flashing.md b/docs/tulip_flashing.md
@@ -1,6 +1,41 @@
-# Compiling and flashing Tulip CC
+# Upgrading, flashing or compiling Tulip CC
 
-## Compile TulipCC for ESP32-S3
+We will aim to release new versions of the Tulip firmware regularly. If you're developing on Tulip itself, you should learn how to compile and flash your own code. Otherwise, you can use our built in upgrading or full-device flash files to flash Tulip.
+
+To flash from a computer, you *may* need a driver for a serial-USB chip on the Tulip you're working with. If your board uses a CH340X chip, and it is not detected by `idf.py`, [you may need to follow the instructions here to install a driver.](https://github.com/WCHSoftGroup/ch34xser_macos)
+
+
+## Upgrade your working Tulip to the latest version
+
+If your Tulip is running and you just want to upgrade to the latest firmware, you can do that "over the air." Make sure your Tulip is connected to wifi and run `tulip.upgrade()`:
+
+```python
+>>> tulip.wifi("ssid", "password")
+>>> tulip.upgrade()
+```
+
+It will ask you if you want to upgrade your firmware and/or your `/sys` folder (the place we store baked in programs and examples.) Usually, a new firmware means new features, so it's recommended to upgrade both so that they're using the same APIs. This whole process takes about five minutes, and your Tulip will reboot. Easy!
+
+## Flash Tulip from a compiled release
+
+We aim to release versions of Tulip regularly. You can find the latest in our [releases section](https://github.com/bwhitman/tulipcc/releases). Find the `.bin` file for your type of Tulip:
+
+ * Any DIY Tulip board based on the N16R8 (16MB flash): `N16R8`
+ * Any DIY Tulip board based on the N32R8 (32MB flash): `N32R8`
+ * The [T-Deck](../tulip/tdeck/README.md): `TDECK`
+ * For the [MaTouch 7"](https://github.com/bwhitman/tulipcc/issues/160): `MATOUCH7`
+ * Tulip CC (our integrated board with display): `TULIP4_R10`
+
+ Download the `.bin` and use [`esptool.py`](https://docs.espressif.com/projects/esptool/en/latest/esp32/) or any other ESP32-flasher tool to write the entire `.bin` to flash:
+
+```bash
+% esptool.py write_flash 0x0 tulip-full-XXX.bin
+```
+
+This completely erases the chip on Tulip and may take some time for 32MB boards, up to 10 minutes or so. You don't have to do this very often, you can use `tulip.upgrade()` going forward after the first flash.
+
+
+## Compile and flash TulipCC for ESP32-S3
 
 [Tulip CC](../README.md) should build on all platforms, although I've only tested macOS and Linux so far. Please let me know if you have any trouble!
 
@@ -15,7 +50,6 @@ macOS:
 brew install cmake ninja dfu-util
 ```
 
-You *may* need a driver for a serial-USB chip on the Tulip you're working with. If your board (including Tulip r10) uses a CH340X chip, and it is not detected by `idf.py`, [you may need to follow the instructions here to install a driver.](https://github.com/WCHSoftGroup/ch34xser_macos)
 
 Linux:
 ```bash
@@ -43,48 +77,40 @@ pip3 install littlefs-python # needed to flash the filesystem
 cd ~/tulipcc/tulip/esp32s3
 ```
 
-### Build and flash Tulip 
+### Flash Tulip 
 
-Now connect your Tulip to your computer over USB. If using a breakout board, connect it to the UART connector, not the USB connector. If using our Tulip board, use the USB-C connector and make sure Tulip is on. 
+Now connect your Tulip to your computer over USB. If using a breakout board, connect it to the UART connector, not the USB connector. 
 
 Choose the right `MICROPY_BOARD` value for your board. 
 
- * Tulip4 (our integrated board): `TULIP4_N32R8`
- * Any Tulip board based on the N8R8 (8MB flash): `TULIP4_N8R8`
- * Any Tulip board based on the N16R8 (16MB flash): `TULIP4_N16R8`
- * For the [T-Deck](../tulip/tdeck/README.md), omit `MICROPY_BOARD` and make sure you're in the `tdeck` folder. 
- * For the [MaTouch 7", or Tulip CC v4r10](https://github.com/bwhitman/tulipcc/issues/160), omit `MICROPY_BOARD` and make sure you're in the `tulipcc_r10` folder.
-
-The default is `TULIP4_N32R8`, so if you omit it that's what it'll use.
+ * Any DIY Tulip board based on the N16R8 (16MB flash): `N16R8`
+ * Any DIY Tulip board based on the N32R8 (32MB flash): `N32R8`
+ * The [T-Deck](../tulip/tdeck/README.md): `TDECK`
+ * For the [MaTouch 7"](https://github.com/bwhitman/tulipcc/issues/160): `MATOUCH7`
+ * Tulip CC (our integrated board with display): `TULIP4_R10`
 
-You have to flash the firmware (`idf.py flash`) and then, for **only the first install**, run `tulip_fs_create.py`. The latter will set up the storage on Tulip. Only do that once per chip, or if you make changes to the underlying filesystem.
+The default is `N32R8`, so if you omit it that's what it'll use.
 
-For example, for the N8R8 chip only:
-
-```bash
-idf.py -D MICROPY_BOARD=TULIP4_N8R8 flash 
-# With a brand new chip or devboard, the first time, you'll want to flash Tulip's filesystem 
-# to the flash memory. Run this only once, or each time you modify `fs` if you're developing Tulip itself.
-python tulip_fs_create.py TULIP4_N8R8
-```
+You have to build the firmware (`idf.py build`) and then, for **only the first install**, run `tulip_fs_create.py` and then `esptool.py` to flash the entire filesystem to Tulip. This sets up the storage on Tulip. Only do that once per chip, or if you make changes to the underlying filesystem. Any further flashing can just use `idf.py -DMICROPY_BOARD=X flash`, which will save time and not overwrite your files!
 
-For the Tulip4 PCB or a board based on a N32R8:
+For example, for a Tulip4 DIY board based on a N32R8:
 
 ```bash
-idf.py flash 
+idf.py -DMICROPY_BOARD=N32R8 build
 # With a brand new chip or devboard, the first time, you'll want to flash Tulip's filesystem 
 # to the flash memory. Run this only once, or each time you modify `fs` if you're developing Tulip itself.
 python tulip_fs_create.py
+esptool.py write_flash 0x0 build/tulip.bin
 ```
 
 You may need to restart Tulip after the flash, bt Tulip should now just turn on whenever you connect USB or power it on. 
 
-To build going forward:
+To build and flash going forward, without modifying the filesystem:
 
 ```bash
 cd tulip/esp32s3
 source ~/esp/esp-idf-v5.2-beta2/export.sh # do this once per terminal window
-idf.py flash
+idf.py -DMICROPY_BOARD=[X] flash 
 idf.py monitor # shows stderr and stdin for controlling Tulip, use control-] to quit
 
 # If you (or we!) make changes to the underlying libraries on AMY or micropython, you want to fully clean the build 
@@ -95,17 +121,6 @@ idf.py flash
 
 [To debug using GDB or profile code, see our new guide on live debugging of the ESP32S3.](tulip_debug.md)
 
-### Set REPL size smaller
-
-If you want a smaller REPL, add this line
-
-```
-idf_build_set_property(COMPILE_OPTIONS "-DTULIP_REPL_FONT_8X6" APPEND)
-```
-
-To the bottom of `esp32s3/CMakeLists.txt`.
-
-
 ## Windows build and flash
 
 TODO 

diff --git a/tulip/README.md b/tulip/README.md
@@ -1,16 +1,14 @@
 # Tulip folder structure
 
 ```
-esp32s3 - all TulipCC hardware specific files
+esp32s3 - all TulipCC hardware specific files for the supported boards 
 fs - the filesystem that gets flashed/copied on first run -- examples, images, etc
 ios - all Tulip Desktop for iOS specific files
 linux - all Tulip Desktop for Linux specific files
 macos - all Tulip Desktop for macOS specific files
 shared - code shared between all Tulip ports (hardware & Desktop)
 shared/py - Python modules that get loaded into Tulip
 shared_desktop - code shared between Tulip Desktop ports (macOS, iOS, Linux)
-tdeck - Tulip port to the T-Deck 
-tulipcc_r10 - Tulip for the new integrated Tulip CC 
 ```
 
 
diff --git a/tulip/esp32s3/CMakeLists.txt b/tulip/esp32s3/CMakeLists.txt
@@ -12,7 +12,7 @@ execute_process(COMMAND bash -c "../shared/grab_submodules.sh"
 
 # Set the board if it's not already set.
 if(NOT MICROPY_BOARD)
-    set(MICROPY_BOARD TULIP4_N32R8)
+    set(MICROPY_BOARD N32R8)
 endif()
 
 # Set the board directory and check that it exists.
@@ -55,9 +55,8 @@ 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)
+set(EXTRA_COMPONENT_DIRS main components)
 
 # Define the project.
 project(micropython)
 idf_build_set_property(COMPILE_OPTIONS "-fdiagnostics-color=always" APPEND)
-#idf_build_set_property(COMPILE_OPTIONS "-DTULIP_REPL_FONT_8X6" APPEND)
diff --git a/tulip/esp32s3/boards/MATOUCH7/board.json b/tulip/esp32s3/boards/MATOUCH7/board.json
@@ -0,0 +1,18 @@
+{
+    "deploy": [
+        "../deploy_s3.md"
+    ],
+    "docs": "",
+    "features": [
+        "BLE",
+        "WiFi"
+    ],
+    "images": [
+        "generic_s3.jpg"
+    ],
+    "mcu": "esp32s3",
+    "product": "Tulip CC (MaTouch7)",
+    "thumbnail": "",
+    "url": "https://www.espressif.com/en/products/modules",
+    "vendor": "Espressif"
+}