Skip to content

Commit

Permalink
Update the documentation & pictures (#29)
Browse files Browse the repository at this point in the history
  • Loading branch information
@awawa-dev
awawa-dev committed Jul 15, 2023
1 parent 0cb91aa commit 651938b
Show file tree
Hide file tree
Showing 2 changed files with 87 additions and 96 deletions.
11 changes: 9 additions & 2 deletions .github/workflows/push-master.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -48,6 +53,7 @@ jobs:
name: firmware-release
path: |
.pio/build/*.bin
.pio/build/recovery_firmware.zip
################################
###### Publish Releases ########
Expand Down Expand Up @@ -82,7 +88,8 @@ jobs:
tag_name: ${{ env.TAG }}
files: |
*.bin
*.zip
draft: true
prerelease: ${{ env.preRelease }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
172 changes: 78 additions & 94 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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<br>(limited performance) | ESP32 / ESP32-S2 mini |
|--------------------------------|:-------:|:-----------:|
| SK6812 cold white | yes | yes |
| SK6812 neutral white | yes | yes |
Expand All @@ -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.

<table>
<tr>
<td colspan="2"><p align="center">See how easy it is to connect ESP to Raspberry Pi using SPI</p></td>
</tr>
<tr>
<td><img src="https://github.com/awawa-dev/HyperSPI/assets/69086569/1e500ca3-e93d-4082-af59-b701e6274a29"/></td>
<td><img src="https://github.com/awawa-dev/HyperSPI/assets/69086569/6e9ea441-312e-46d8-99b0-d33fc0b9f923"/></td>
</tr>
<tr>
<td><img src="https://user-images.githubusercontent.com/69086569/216763154-ca4aa8fa-5855-43c1-86c2-d401010de675.png"/></td>
<td><img src="https://user-images.githubusercontent.com/69086569/231207350-a670bfea-a96d-4d21-9e8f-f2ca027105da.png"/></td>
</tr>
</table>

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:
<p align="center">
<b>Esp8266 Wemos D1 mini (CH340) and Wemos D1 mini pro (CP2104)</b><br/>
<img src="https://user-images.githubusercontent.com/69086569/207572306-2b0bd3dd-fcb2-4f0c-8426-64341cbbadbf.png" width="250" /><img src="https://user-images.githubusercontent.com/69086569/207572335-9caf2567-2e23-4ee4-85a4-0f2f82676c16.png" width="250" />
</p>

![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 |
<p align="center">
<b>ESP32 MH-ET Live and ESP32-S2 Lolin mini (CDC)</b><br/>
<img src="https://user-images.githubusercontent.com/69086569/207587620-1c4c53c8-426c-486e-a6d9-d429fd1b050d.png" width="250"/><img src="https://user-images.githubusercontent.com/69086569/207587635-b7816329-0e29-47ee-a75a-bc6c41cdc51f.png" width="250"/>
</p>

## 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`

Expand All @@ -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.

<img src="https://user-images.githubusercontent.com/69086569/193319124-0054f367-3d30-4e50-8c52-3683c7bbc50e.png" width="800"/>

# Benchmark results

Expand All @@ -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<br/>HyperSPI v9 |
|------------------------------------------------|-----------------|
| 300LEDs RGBW<br>Refresh rate/continues output=83Hz | 83 |
| 600LEDs RGBW<br>Refresh rate/continues output=43Hz | 42-43 |
| 900LEDs RGBW<br>Refresh rate/continues output=28Hz | 28 |

## ESP32-S2

| LED strip / Device | ESP32-S2 Lolin mini<br/>HyperSPI v9 |
|------------------------------------------------|--------------------|
| 300LEDs RGBW<br>Refresh rate/continues output=83Hz | 83 |
| 600LEDs RGBW<br>Refresh rate/continues output=43Hz | 42 |
| 900LEDs RGBW<br>Refresh rate/continues output=28Hz | 28 |
| LED strip / Device | ESP32 MH ET Live<br/>HyperSPI v9 | ESP32-S2 Lolin mini<br/>HyperSPI v9 |
|------------------------------------------------|-----------------|--------------------|
| 300LEDs RGBW<br>Refresh rate/continues output=83Hz | 83 | 83 |
| 600LEDs RGBW<br>Refresh rate/continues output=43Hz | 42-43 | 42 |
| 900LEDs RGBW<br>Refresh rate/continues output=28Hz | 28 | 28 |

## ESP8266

Expand All @@ -140,24 +125,12 @@ For the RGBW firmware the white channel is automatically calculated and R,G,B ch
| 600LEDs RGBW<br>Refresh rate/continues output=33Hz | 33 |
| 900LEDs RGBW<br>Refresh rate/continues output=22Hz | 22 |

# Example of supported boards

**Esp8266 Wemos D1 mini (CH340) and Wemos D1 mini pro (CP2104)**
<p align="center">
<img src="https://user-images.githubusercontent.com/69086569/207572306-2b0bd3dd-fcb2-4f0c-8426-64341cbbadbf.png" /><img src="https://user-images.githubusercontent.com/69086569/207572335-9caf2567-2e23-4ee4-85a4-0f2f82676c16.png" />
</p>

**ESP32 MH-ET Live and ESP32-S2 Lolin mini (CDC)**
<p align="center">
<img src="https://user-images.githubusercontent.com/69086569/207587620-1c4c53c8-426c-486e-a6d9-d429fd1b050d.png" /><img src="https://user-images.githubusercontent.com/69086569/207587635-b7816329-0e29-47ee-a75a-bc6c41cdc51f.png" />
</p>

# 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

Expand Down Expand Up @@ -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)







Expand Down

0 comments on commit 651938b

Please sign in to comment.