{"id":16238996,"url":"https://github.com/awawa-dev/hyperspi","last_synced_at":"2025-04-04T10:02:52.763Z","repository":{"id":38398565,"uuid":"395355088","full_name":"awawa-dev/HyperSPI","owner":"awawa-dev","description":"HyperHDR bridge using SPI bus. Connects Raspberry Pi with a generic Raspberry Pi Pico (rp2040)/ESP32/ESP8266 to control a LED strip. Fasted possible cable solution for external Pico/ESP LED driver. Data integration check included.","archived":false,"fork":false,"pushed_at":"2025-01-12T21:53:58.000Z","size":77,"stargazers_count":72,"open_issues_count":0,"forks_count":149,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-28T09:04:51.639Z","etag":null,"topics":["ambilight","arduino","esp32","esp32-s2","esp8266","hyperhdr","led","led-controller","led-strips","pico","raspberry-pi","rp2040","rpi5","sk6812","spi","ws2812b"],"latest_commit_sha":null,"homepage":"https://hyperhdr.eu","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/awawa-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"awawa-dev"}},"created_at":"2021-08-12T14:58:08.000Z","updated_at":"2025-03-10T13:37:16.000Z","dependencies_parsed_at":"2023-12-06T02:55:04.169Z","dependency_job_id":"db95ad1a-5c1c-4fcf-b8a7-0ca51832f910","html_url":"https://github.com/awawa-dev/HyperSPI","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awawa-dev%2FHyperSPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awawa-dev%2FHyperSPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awawa-dev%2FHyperSPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awawa-dev%2FHyperSPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awawa-dev","download_url":"https://codeload.github.com/awawa-dev/HyperSPI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247156615,"owners_count":20893199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ambilight","arduino","esp32","esp32-s2","esp8266","hyperhdr","led","led-controller","led-strips","pico","raspberry-pi","rp2040","rpi5","sk6812","spi","ws2812b"],"created_at":"2024-10-10T13:41:58.080Z","updated_at":"2025-04-04T10:02:52.732Z","avatar_url":"https://github.com/awawa-dev.png","language":"C++","readme":"# HyperSPI\nSPI bridge for AWA protocol to control a LED strip from HyperHDR.  \nDiagnostic and performance data available at the serial port output [read more](#performancedebug-output).  \nRaspberry Pi acts as a master, ESP8266/ESP32/ESP32-S2/rp2040(Raspberry Pi Pico) is in slave mode. \n  \n| LED strip / Device             | rp2040 / Pico | ESP8266\u003cbr\u003e(limited performance) |    ESP32 / ESP32-S2 mini    \n|--------------------------------|:-------:|:-----------:|:-------:|\n| SK6812 cold white              |   yes   |   yes   |     yes     |\n| SK6812 neutral white           |   yes   |   yes   |     yes     |\n| WS281x                         |   yes   |   yes   |     yes     |\n  \n  \n# Why this project was created?\n\n- SPI is very faster. HyperSPI works best at speed over 20Mb\n- SPI doesn't have any data integration check. But AWA protocol does have one\n- you don't need to have 2Mb capable serial port on your ESP board\n- SPI transmission is much lighter than serial communication\n- 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 drop in overall USB transfer. So we can replace Adalight with a pure SPI data transfer as an alternative\n- I needed it and I was able to implemented it 😉\n\n# Hardware connection  \n\nIf 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. \n\nThe photos below use the same home-made adapter throughout, so you can see a repeating pattern and the cable colors should help you locate the correct pins. However, always consult the GPIO diagram for your boards to confirm that you have connected the cables correctly, because if you make a mistake and connect to the 5V GPIO line, it may damage both devices.  \n\nAs you can also notice, the pinout of the SPI0 interface is identical for the entire Raspberry Pi SBC family: 3, 4, 5, Zero 2W, etc.  \n\n\u003ctable\u003e  \n  \u003ctr\u003e\n    \u003ctd colspan=\"2\"\u003e\u003cp align=\"center\"\u003eSee how easy it is to connect Raspberry Pi Pico (rp2040) to Raspberry Pi 5 using SPI\u003c/p\u003e\u003c/td\u003e    \n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"2\"\u003e\u003cimg src=\"https://github.com/awawa-dev/HyperSPI/assets/69086569/7f24f87e-f7e0-43f3-a568-39d0f6beced1\"/\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/awawa-dev/HyperSPI/assets/69086569/170f5718-df88-4ef2-9ed8-7d92d913aeec\"/\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/awawa-dev/HyperSPI/assets/69086569/9235c689-062e-4c62-b632-8c506b0e2e97\"/\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"2\"\u003e\u003cp align=\"center\"\u003eor if you prefer ESP32/ESP32-S2/Esp8266\u003c/p\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/awawa-dev/HyperSPI/assets/69086569/1e500ca3-e93d-4082-af59-b701e6274a29\"/\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://github.com/awawa-dev/HyperSPI/assets/69086569/6e9ea441-312e-46d8-99b0-d33fc0b9f923\"/\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://user-images.githubusercontent.com/69086569/216763154-ca4aa8fa-5855-43c1-86c2-d401010de675.png\"/\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://user-images.githubusercontent.com/69086569/231207350-a670bfea-a96d-4d21-9e8f-f2ca027105da.png\"/\u003e\u003c/td\u003e\n  \u003c/tr\u003e \n\u003c/table\u003e\n\n# Example of supported boards\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eAdafruit RP2040 Scorpio and ItsyBitsy with built-in level shifter (recommended!)\u003c/b\u003e\u003cbr/\u003e  \n\u003cimg src=\"https://github.com/awawa-dev/HyperSPI/assets/69086569/c7ef2768-357e-47ca-aa1c-543769eeb360\" width=\"250\" /\u003e\u003cimg src=\"https://github.com/awawa-dev/HyperSPI/assets/69086569/3e55948d-fd3d-44cb-908c-9aad8ce2715d\" width=\"250\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eEsp8266 Wemos D1 mini (CH340) and Wemos D1 mini pro (CP2104)\u003c/b\u003e\u003cbr/\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/69086569/207572306-2b0bd3dd-fcb2-4f0c-8426-64341cbbadbf.png\" width=\"250\" /\u003e\u003cimg src=\"https://user-images.githubusercontent.com/69086569/207572335-9caf2567-2e23-4ee4-85a4-0f2f82676c16.png\" width=\"250\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eESP32 MH-ET Live and ESP32-S2 Lolin mini (CDC)\u003c/b\u003e\u003cbr/\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/69086569/207587620-1c4c53c8-426c-486e-a6d9-d429fd1b050d.png\" width=\"250\"/\u003e\u003cimg src=\"https://user-images.githubusercontent.com/69086569/207587635-b7816329-0e29-47ee-a75a-bc6c41cdc51f.png\" width=\"250\"/\u003e\n\u003c/p\u003e\n\n## Default pinout (can be changed for esp32, esp32-s2 and rp2040 Pico)\n  \n|    PINOUT   |  ESP8266  |   ESP32   | ESP32-S2 | Pico (rp2040) | Adafruit rp2040\u003cbr/\u003eScorpio / ItsyBitsy\n|-------------|-----------|-----------|-----------|-----------|-----------|\n| Clock (SCK) | GPIO 14   | GPIO 18   | GPIO 7    | GPIO 2    | GPIO 26 (A0) |\n| Data (MOSI) | GPIO 13   | GPIO 23   | GPIO 11   | GPIO 4    | GPIO 28 (A2) |\n| SPI Chip Select(e.g. CE0) | not used    | GPIO 5    | GPIO 12   | GPIO 5    | GPIO 29 (A3) |\n| GROUND      | mandatory | mandatory | mandatory | mandatory | mandatory |\n| LED output  | GPIO 2    | GPIO 2    | GPIO 2    | GPIO 14 | GPIO16 / GPIO14 |\n\n\u003e [!CAUTION]\n\u003e The ground connection between both GPIOs is as important as the other SPI data connections. The ground cable should be of a similar length as them and run directly next to them.\n\n# Flashing the firmware\n\nThere 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.\n\n## Flashing ESP32-S2 Lolin mini\n\nRequires using `esptool.py` to flash the firmware e.g.  \n - `esptool.py write_flash 0x10000 hyperspi_esp32_s2_mini_SK6812_RGBW_COLD.bin` or\n - `esptool.py write_flash 0x0 hyperspi_esp32_s2_mini_SK6812_RGBW_COLD.factory.bin`\n\nTroubleshooting: ESP32-S2 Lolin mini recovery procedure if the board is not detected or is malfunctioning.  \n1. Put the board into dfu mode using board buttons: press `Rst` + `0` buttons, then release `Rst`, next release `0`  \nDo not reset or disconnect the board until the end of the recovery procedure.\n2. Execute `esptool.py erase_flash`  \n3. Flash 'factory' version of the firmware e.g.  \n`esptool.py write_flash 0x0 hyperspi_esp32_s2_mini_SK6812_RGBW_COLD.factory.bin`  \n4. **`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.\n\n## Flashing generic Esp8266/ESP32\n\nRecommend to use [esphome-flasher](https://github.com/esphome/esphome-flasher/releases)  \nOr use `esptool.py` e.g.  \n - `esptool.py write_flash 0x10000 hyperspi_esp32_SK6812_RGBW_COLD.bin` or\n - `esptool.py write_flash 0x0 hyperspi_esp32_SK6812_RGBW_COLD.factory.bin`\n\nFor **RGBW LED strip** like RGBW SK6812 NEUTRAL white choose: *hyperspi_..._SK6812_RGBW_NEUTRAL.bin*  \nFor **RGBW LED strip** like RGBW SK6812 COLD white choose: *hyperspi_..._SK6812_RGBW_COLD.bin*  \nFor **RGB LED strip** like WS8212b or RGB SK6812 variant choose: *hyperspi_..._WS281x_RGB.bin*  \n\n## Flashing Pico boards\n\nIt's very easy and you don't need any special flasher.  \n\nUse firmware from the `hyperspi_pico_rp2040.zip` archive. Adafruit boards have their own custom firmware package inside the archive: `Adafruit_ItsyBitsy_RP2040.zip` and `Adafruit_Feather_RP2040_Scorpio.zip`\n\nPut your Pico board into DFU mode:  \n* If your Pico board has only one button (`boot`) then press \u0026 hold it and connect the board to the USB port. Then you can release the button.\n* If your Pico board has two buttons, connect it to the USB port. Then press \u0026 hold `boot` and `reset` buttons, then release `reset` and next release `boot` button.  \n\nIn the system file explorer you should find new drive (e.g. called `RPI-RP2` drive) exposed by the Pico board. Drag \u0026 drop (or copy) the selected firmware to this drive. \nThe Pico will reset automaticly after the upload and after few seconds it will be ready to use.\n  \n# Software configuration (HyperHDR v17 and above)\n\n**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)**\n\nSelect `esp8266` protocol for ESP proprietary SPI protocol, `esp32` for ESP32 boards, `rp2040 (Pico)` for Pico boards or `standard` for other devices.    \nMake sure you set \"Refresh time\" to zero, \"Baudrate\" should be set to high but realistic value like ```25 000 000```.  \nEnabling \"White channel calibration\" is optional, if you want to fine tune the white channel balance of your sk6812 RGBW LED strip.\n  \n\u003cimg src=\"https://user-images.githubusercontent.com/69086569/193319124-0054f367-3d30-4e50-8c52-3683c7bbc50e.png\" width=\"800\"/\u003e\n\n# Benchmark results\n\n## ESP32 \u0026 ESP32-S2 parallel multi-segment mode\n\n| sk6812 LED strip / Device                                                                      | ESP32 MH-ET LIVE mini\u003cbr/\u003eHyperSPI v9 |  ESP32-S2 Lolin mini\u003cbr/\u003eHyperSPI v9 |\n|-----------------------------------------------------------------------------------------|-----------------------|----------------------|\n| 300 RGBW LEDs\u003cbr\u003eRefresh rate/continues output=100Hz\u003cbr\u003eSECOND_SEGMENT_START_INDEX=150 |          100          |          100         |\n| 600 RGBW LEDs\u003cbr\u003eRefresh rate/continues output=83Hz\u003cbr\u003eSECOND_SEGMENT_START_INDEX=300  |           83          |           83         |\n| 900 RGBW LEDs\u003cbr\u003eRefresh rate/continues output=55Hz \u003cbr\u003eSECOND_SEGMENT_START_INDEX=450 |         54-55         |           55         |\n\n## SP8266 / ESP32\n\n| sk6812 LED strip / Device                             | ESP32 MH ET Live\u003cbr/\u003eHyperSPI v9 | ESP32-S2 Lolin mini\u003cbr/\u003eHyperSPI v9 | ESP8266 Wemos D1 Pro\u003cbr/\u003eHyperSPI v9 |\n|------------------------------------------------|-----------------|--------------------|---------------------|\n| 300 RGBW LEDs\u003cbr\u003econtinues output=83/70Hz  |        83       |          83        |          70         |\n| 600 RGBW LEDs\u003cbr\u003econtinues output=43/33Hz  |      42-43      |          42        |          33         |\n| 900 RGBW LEDs\u003cbr\u003econtinues output=28/22Hz  |       28        |          28        |          22         |\n\n# Compiling\n\n## ESP8266 / ESP32\n\nCurrently we use PlatformIO to compile the project. Install [Visual Studio Code](https://code.visualstudio.com/) and add [PlatformIO plugin](https://platformio.org/).\nThis 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).\n\n## Pico rp2040\n\nUse Pico SDK and Visual Code to open ```rp2040``` folder. Edit ```rp2040\\CMakeLists.txt``` configuration file if you need to apply changes.\n\n## Github Action\n\nBut 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:\n- esp8266/ESP32 boards: to the ```platformio.ini``` file\n- rp2040 Pico boards: to the ```rp2040\\CMakeLists.txt``` file\n\nfor 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.**\n\nTutorial: https://github.com/awawa-dev/HyperSPI/wiki\n\n# Multi-Segment Wiring (ESP32, ESP32-S2 and Pico rp2040 boards only)\n\n## ESP32\n\nUsing parallel multi-segment allows you to double your Neopixel (e.g. sk6812 RGBW) LED strip refresh rate by dividing it into two smaller equal parts. Both smaller segments are perfectly in sync so you don't need to worry about it. Proposed example of building a multisegment:\n- Divide a long or dense strip of LEDs into 2 smaller equal parts. So `SECOND_SEGMENT_START_INDEX` in the HyperSPI firmware is the total number of LEDs divided by 2.\n- Build your first segment traditional way e.g. clockwise, so it starts somewhere in middle of the bottom of frame/TV and ends in the middle of the top of frame/TV\n- Start the second segment in the opposite direction to the first one e.g. counterclockwise (`SECOND_SEGMENT_REVERSED` option in the HyperSPI firmware configuration must be enabled). So it starts somewhere in the middle of the bottom of the frame/TV and ends in the middle of the top of the TV/frame. Both segments could be connected if possible at the top but only 5v and ground ( NOT the data line).\n- The data line starts for both segments somewhere in the middle of the bottom of the TV/frame (where each of the LED strips starts)\n- Configuration in HyperHDR does not change! It's should be configured as one, single continues segment. All is done in HyperSPI firmware transparently and does not affect LED strip configuration in HyperHDR.\n\nYou also must configure data pin in the `platformio.ini`. Review the comments at the top of the file:\n* `SECOND_SEGMENT_DATA_PIN` - These is data pin for your second strip\n\nYou add these to your board's config. Be sure to put `-D` in front of each setting. \n\nExamples of final build_flags for 288 LEDs divided into 2 equal segments in the `platformio.ini`:\n```\n[env:SK6812_RGBW_COLD]\nbuild_flags = -DNEOPIXEL_RGBW -DCOLD_WHITE -DDATA_PIN=2 ${env.build_flags} -DSECOND_SEGMENT_START_INDEX=144 -DSECOND_SEGMENT_DATA_PIN=4 -DSECOND_SEGMENT_REVERSED\n...\n[env:WS281x_RGB]\nbuild_flags = -DNEOPIXEL_RGB -DDATA_PIN=2 ${env.build_flags} -DSECOND_SEGMENT_START_INDEX=144 -DSECOND_SEGMENT_DATA_PIN=4 -DSECOND_SEGMENT_REVERSED\n...\n```\nImplementation example:\n- The diagram of the board for WS2812b/SK6812 including ESP32 and the SN74AHCT125N 74AHCT125 [level shifter](https://github.com/awawa-dev/HyperHDR/wiki/Level-Shifter).\n\n## Pico rp2040\n\nEdit ```rp2040\\CMakeLists.txt``` file and recompile the project.\n\n![HyperSPI](https://user-images.githubusercontent.com/85223482/222923979-f344349a-1f8b-4195-94ca-51721923359e.png)\n\n# Performance/debug output\n\n**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.\n\nOn Linux you can `screen` command.  \nFirst install it: `sudo apt install screen`. Adjust USB port if necessary and connect to the serial port:  \n`screen /dev/ttyACM0 115200`  \nIf you want to exit screen press `Ctrl-a` then `k` and confirm exit.\n\nYou can also use `Putty` on Windows\n![obraz](https://user-images.githubusercontent.com/69086569/216762783-0ce47e57-98a7-474d-aa84-7e5afb42d294.png)  \n\nFor 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.\n\n  \n \n\n\n\n\n\n\n\n\n\n","funding_links":["https://github.com/sponsors/awawa-dev"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawawa-dev%2Fhyperspi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawawa-dev%2Fhyperspi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawawa-dev%2Fhyperspi/lists"}