diff --git a/.github/workflows/push-master.yml b/.github/workflows/push-master.yml index f3de148..80754ee 100644 --- a/.github/workflows/push-master.yml +++ b/.github/workflows/push-master.yml @@ -33,13 +33,18 @@ jobs: python -m pip install --upgrade pip pip install --upgrade platformio - name: Run PlatformIO - run: pio run + run: | + pio run + zip -j .pio/build/recovery_firmware.zip .pio/build/*.factory.bin + rm -f .pio/build/*.factory.bin + - uses: actions/upload-artifact@v3 name: Upload artifacts (commit) if: (startsWith(github.event.ref, 'refs/tags') != true) with: path: | .pio/build/*.bin + .pio/build/recovery_firmware.zip - uses: actions/upload-artifact@v3 name: Upload artifacts (release) @@ -48,6 +53,7 @@ jobs: name: firmware-release path: | .pio/build/*.bin + .pio/build/recovery_firmware.zip ################################ ###### Publish Releases ######## @@ -82,7 +88,8 @@ jobs: tag_name: ${{ env.TAG }} files: | *.bin + *.zip draft: true prerelease: ${{ env.preRelease }} env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index e2f25a4..c5fdb51 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # HyperSPI -SPI bridge for AWA protocol to control a LED strip from HyperHDR (version v17 and above). -Diagnostic data available at the serial port output (@115200 speed). -Rpi acts as a master, ESP8266/ESP32 is in slave mode. +SPI bridge for AWA protocol to control a LED strip from HyperHDR. +Diagnostic and performance data available at the serial port output [read more](#performancedebug-output). +Rpi acts as a master, ESP8266/ESP32/ESP32-S2 is in slave mode. -| LED strip / Device | ESP8266 | ESP32 | +| LED strip / Device | ESP8266
(limited performance) | ESP32 / ESP32-S2 mini | |--------------------------------|:-------:|:-----------:| | SK6812 cold white | yes | yes | | SK6812 neutral white | yes | yes | @@ -12,75 +12,61 @@ Rpi acts as a master, ESP8266/ESP32 is in slave mode. # Why this project was created? -- SPI is much faster. HyperSPI works best at speed over 20Mb. -- SPI doesn't have any data integration check. But AWA protocol does have one. -- you don't need to have 2Mb capable serial port on your ESP board. +- SPI is very faster. HyperSPI works best at speed over 20Mb +- SPI doesn't have any data integration check. But AWA protocol does have one +- you don't need to have 2Mb capable serial port on your ESP board - SPI transmission is much lighter than serial communication +- There is a hardware limitation for the Rpi current design...even if you connect your grabber using USB2.0 mode, working serial port driver (used by Adalight) results in quite a large overall USB transfer. So we can replace Adalight with a pure SPI data transfer as an alternative - I needed it and I was able to implemented it 😉 -- There is a hardware limitation for the Rpi current design...even if you connect your grabber to the USB3.0 in the USB2.0 mode the adalight running driver causes quite a big USB transfer drop. So we can replace Adalight with a pure SPI data transfer as an alternative. -See what's happening for USB2.0 bus... my problematic Ezcap 320 @ 50 fps fell back to USB2.0 mode and did not like the CH340G serial port driver at all (real USB3.0 should not be affected, but not tested it): -![slow](https://user-images.githubusercontent.com/69086569/129419155-f6366c27-ea2e-42a9-aa85-ffade3747700.jpg) - -That's how the grabbers works when other device is disconnected from the USB port. -![fast](https://user-images.githubusercontent.com/69086569/129419160-c546a0ea-4990-4215-a0a9-8fb1288e0ac9.jpg) - -# Software configuration (HyperHDR v17 and above) +# Hardware connection -**In HyperHDR `Image Processing→Smoothing→Update frequency` you should do not exceed the maximum capacity of the device. Read more here: [testing performance](https://github.com/awawa-dev/HyperSPI#performance-output)** +If you are using an ESP board compatible with the Wemos board (ESP8266 Wemos D1/pro, ESP32 MH-ET Live, ESP32-S2 lolin mini), the SPI connection uses the same pinout location on the ESP board! The pin positions of the LED output may vary. Cables (including ground) should not exceed 15-20cm or it may be necessary to lower the SPI speed. + + + + + + + + + + + + + +

See how easy it is to connect ESP to Raspberry Pi using SPI

-Select esp8266 protocol for ESP proprietary SPI protocol, esp32 for ESP32 boards or 'standard' for other devices. -Make sure you set "Refresh time" to zero, "Baudrate" should be set to high but realistic value like ```25 000 000```. -Enabling "White channel calibration" is optional, if you want to fine tune the white channel balance of your sk6812 RGBW LED strip. - -![obraz](https://user-images.githubusercontent.com/69086569/193319124-0054f367-3d30-4e50-8c52-3683c7bbc50e.png) +# Example of supported boards -# Hardware connection -If you are using an ESP board compatible with the Wemos board (ESP8266 Wemos D1/pro, ESP32 MH-ET Live, ESP32-S2 lolin mini), the SPI connection uses the same pinout location on the ESP board! The pin positions of the LED output may vary. Cables (including ground) should not exceed 15-20cm or it may be necessary to lower the SPI speed. See how easy it is to connect ESP to Rpi: +

+Esp8266 Wemos D1 mini (CH340) and Wemos D1 mini pro (CP2104)
+ +

-![obraz](https://user-images.githubusercontent.com/69086569/216763154-ca4aa8fa-5855-43c1-86c2-d401010de675.png) -![obraz](https://user-images.githubusercontent.com/69086569/231207350-a670bfea-a96d-4d21-9e8f-f2ca027105da.png) - -## Default pinout: ESP8266 (can not be changed) - -| ESP8266 | PINOUT | -|-------------|-----------| -| Clock (SCK) | GPIO 14 | -| Data (MOSI) | GPIO 13 | -| GROUND | mandatory | -| LED output | GPIO 2 | +

+ESP32 MH-ET Live and ESP32-S2 Lolin mini (CDC)
+ +

+## Default pinout (can be changed for esp32 and esp32-s2) -## Default pinout: ESP32 (can be changed) - -| ESP32 | PINOUT | -|---------------------------|-----------| -| Clock (SCK) | GPIO 18 | -| Data (MOSI) | GPIO 23 | -| SPI Chip Select(e.g. CE0) | GPIO 5 | -| GROUND | mandatory | -| LED output | GPIO 2 | - +| PINOUT | ESP8266 | ESP32 | ESP32-S2 lolin mini| +|-------------|-----------|-----------|-----------| +| Clock (SCK) | GPIO 14 | GPIO 18 | GPIO 7 | +| Data (MOSI) | GPIO 13 | GPIO 23 | GPIO 11 | +| SPI Chip Select(e.g. CE0) | not used | GPIO 5 | GPIO 12 | +| GROUND | mandatory | mandatory | mandatory | +| LED output | GPIO 2 | GPIO 2 | GPIO 2 | -## Default pinout: ESP32-S2 lolin mini (can be changed) +# Flashing the firmware -| ESP32-S2 lolin mini | PINOUT | -|---------------------------|-----------| -| Clock (SCK) | GPIO 7 | -| Data (MOSI) | GPIO 11 | -| SPI Chip Select(e.g. CE0) | GPIO 12 | -| GROUND | mandatory | -| LED output | GPIO 2 | +There are two versions of the firmware for ESP32 and ESP32-S2. The 'factory' (in the `recovery_firmware.zip` archive) and the 'base' one. Factory firmware should be flashed to offset 0x0, base firmware to offset 0x10000. -# Flashing - -There are two versions of the firmware for ESP32 and ESP32-S2. The 'factory' and the 'base' one. Factory firmware should be flashed to offset 0x0, base firmware to offset 0x10000. - -**ESP32-S2 Lolin mini:** +## Flashing ESP32-S2 Lolin mini Requires using `esptool.py` to flash the firmware e.g. - - `esptool.py write_flash 0x10000 hyperspi_esp32_s2_mini_SK6812_RGBW_COLD.bin` or - `esptool.py write_flash 0x0 hyperspi_esp32_s2_mini_SK6812_RGBW_COLD.factory.bin` @@ -90,21 +76,28 @@ Do not reset or disconnect the board until the end of the recovery procedure. 2. Execute `esptool.py erase_flash` 3. Flash 'factory' version of the firmware e.g. `esptool.py write_flash 0x0 hyperspi_esp32_s2_mini_SK6812_RGBW_COLD.factory.bin` -4. Reset the board manually with the `Rst` button. The board should be detected as a COM port in the system. +4. **`esptool.py` is not able to automatically reset esp32-s2 when in dfu mode. Reconnect or hard reset it manually.** The board should be detected as a COM port in the system. -**Generic Esp8266/ESP32:** +## Flashing generic Esp8266/ESP32 Recommend to use [esphome-flasher](https://github.com/esphome/esphome-flasher/releases) +Or use `esptool.py` e.g. + - `esptool.py write_flash 0x10000 hyperspi_esp32_SK6812_RGBW_COLD.bin` or + - `esptool.py write_flash 0x0 hyperspi_esp32_SK6812_RGBW_COLD.factory.bin` For **RGBW LED strip** like RGBW SK6812 NEUTRAL white choose: *hyperspi_..._SK6812_RGBW_NEUTRAL.bin* - For **RGBW LED strip** like RGBW SK6812 COLD white choose: *hyperspi_..._SK6812_RGBW_COLD.bin* - For **RGB LED strip** like WS8212b or RGB SK6812 variant choose: *hyperspi_..._WS281x_RGB.bin* - -If you want to disable your first LED because it's used as a sacrificial level shifter, please use [HyperHDR v19](https://github.com/awawa-dev/HyperHDR/pull/379) + +# Software configuration (HyperHDR v17 and above) + +**In HyperHDR `Image Processing→Smoothing→Update frequency` you should do not exceed the maximum capacity of the device. Read more here: [testing performance](https://github.com/awawa-dev/HyperSPI#performance-output)** -For the RGBW firmware the white channel is automatically calculated and R,G,B channels are corrected. +Select esp8266 protocol for ESP proprietary SPI protocol, esp32 for ESP32 boards or 'standard' for other devices. +Make sure you set "Refresh time" to zero, "Baudrate" should be set to high but realistic value like ```25 000 000```. +Enabling "White channel calibration" is optional, if you want to fine tune the white channel balance of your sk6812 RGBW LED strip. + + # Benchmark results @@ -118,19 +111,11 @@ For the RGBW firmware the white channel is automatically calculated and R,G,B ch ## ESP32 -| LED strip / Device | ESP32 MH ET Live
HyperSPI v9 | -|------------------------------------------------|-----------------| -| 300LEDs RGBW
Refresh rate/continues output=83Hz | 83 | -| 600LEDs RGBW
Refresh rate/continues output=43Hz | 42-43 | -| 900LEDs RGBW
Refresh rate/continues output=28Hz | 28 | - -## ESP32-S2 - -| LED strip / Device | ESP32-S2 Lolin mini
HyperSPI v9 | -|------------------------------------------------|--------------------| -| 300LEDs RGBW
Refresh rate/continues output=83Hz | 83 | -| 600LEDs RGBW
Refresh rate/continues output=43Hz | 42 | -| 900LEDs RGBW
Refresh rate/continues output=28Hz | 28 | +| LED strip / Device | ESP32 MH ET Live
HyperSPI v9 | ESP32-S2 Lolin mini
HyperSPI v9 | +|------------------------------------------------|-----------------|--------------------| +| 300LEDs RGBW
Refresh rate/continues output=83Hz | 83 | 83 | +| 600LEDs RGBW
Refresh rate/continues output=43Hz | 42-43 | 42 | +| 900LEDs RGBW
Refresh rate/continues output=28Hz | 28 | 28 | ## ESP8266 @@ -140,24 +125,12 @@ For the RGBW firmware the white channel is automatically calculated and R,G,B ch | 600LEDs RGBW
Refresh rate/continues output=33Hz | 33 | | 900LEDs RGBW
Refresh rate/continues output=22Hz | 22 | -# Example of supported boards - -**Esp8266 Wemos D1 mini (CH340) and Wemos D1 mini pro (CP2104)** -

- -

- -**ESP32 MH-ET Live and ESP32-S2 Lolin mini (CDC)** -

- -

- # Compiling Currently we use PlatformIO to compile the project. Install [Visual Studio Code](https://code.visualstudio.com/) and add [PlatformIO plugin](https://platformio.org/). This environment will take care of everything and compile the firmware for you. Low-level LED strip support is provided by my highly optimizated (pre-fill I2S DMA modes, turbo I2S parallel mode for up to 2 segments etc) version of Neopixelbus library: [link](https://github.com/awawa-dev/NeoPixelBus). -But there is also an alternative and an easier way. Just fork the project and enable its Github Action. Use the online editor to make changes to the ```platformio.ini``` file, for example change default pin-outs or enable multi-segments support, and save it. Github Action will compile new firmware automatically in the Artifacts archive. It has never been so easy! +But there is also an alternative and an easier way. Just fork the project and enable its Github Action. Use the online editor to make changes to the ```platformio.ini``` file, for example change default pin-outs or enable multi-segments support, and save it. Github Action will compile new firmware automatically in the Artifacts archive. It has never been so easy! **Just remember to follow the steps in the correct order otherwise the Github Action may not be triggered the first time after saving the changes.** Tutorial: https://github.com/awawa-dev/HyperSPI/wiki @@ -189,13 +162,24 @@ Implementation example: ![HyperSPI](https://user-images.githubusercontent.com/85223482/222923979-f344349a-1f8b-4195-94ca-51721923359e.png) -# Performance output +# Performance/debug output -The output is only available when HyperHDR is not using the device at the moment, so it should be disabled in the app for a while. Stores the last result when HyperHDR was running in the current session. You can read it from the serial port at a speed of 115200. +**The output is only available when HyperHDR is not using the device at the moment, so it should be disabled in the app for a while.** Stores the last result when HyperHDR was running in the current session. You can read it from the serial port at a speed of 115200. + +On Linux you can `screen` command. +First install it: `sudo apt install screen`. Adjust USB port if necessary and connect to the serial port: +`screen /dev/ttyACM0 115200` +If you want to exit screen press `Ctrl-a` then `k` and confirm exit. + +You can also use `Putty` on Windows +![obraz](https://user-images.githubusercontent.com/69086569/216762783-0ce47e57-98a7-474d-aa84-7e5afb42d294.png) For testing maximum performance in HyperHDR enable `Image Processing→Smoothing→Continuous output`, high `Update frequency` in the same tab and set any color in the `Remote control` tab as an active effect. After testing you need to disable `Continuous output`and set `Update frequency` according to your results. -![obraz](https://user-images.githubusercontent.com/69086569/216762783-0ce47e57-98a7-474d-aa84-7e5afb42d294.png) + + + +