Skip to content

Commit b0c30a7

Browse files
ryanamaralryanamaral
committed
🐢 TurtlePass v3.1 - Universal LED Framework & 130-Board Support
- Added complete LED driver suite: • AnalogLedDriver • Cyw43LedDriver • Rgb3PinLedDriver • FastLedDriver • NullLedDriver - Refactored LedManager for driver abstraction and shared interface (ILedDriver) - Implemented RP2040/RP2350 board auto-detection with automatic driver selection - Unified color and brightness handling across all drivers - Added native unit tests validating LED states, timing, and brightness without hardware
1 parent 8615289 commit b0c30a7

26 files changed

+2396
-498
lines changed

‎BUILD.md‎

Lines changed: 188 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# 🧑‍💻 Building TurtlPass Firmware from Source
22

3-
This guide explains how to compile and customize the **TurtlPass Firmware** using [**PlatformIO**](https://platformio.org/).
4-
Most users can rely on pre-built releases — building from source is ideal for developers or power users.
3+
This guide explains how to **compile, customize, and flash** the **TurtlPass Firmware** using [**PlatformIO**](https://platformio.org/).
4+
Most users can rely on the **prebuilt UF2 releases** — building from source is ideal for developers or power users.
5+
6+
> 🧠 **TurtlPass now supports over 130 RP2040 / RP2350-based boards**, with automatic driver and LED configuration.
57
68
---
79

@@ -26,9 +28,11 @@ Most users can rely on pre-built releases — building from source is ideal for
2628
## ⚙️ Overview
2729

2830
* **Core:** [Earle Philhower’s Arduino-Pico](https://github.com/earlephilhower/arduino-pico)
29-
* **Platform:** [Max Gerhardt’s RP2040 fork](https://github.com/maxgerhardt/platform-raspberrypi)
31+
* **Platform:** [Max Gerhardt’s Raspberry Pi RP2040 fork](https://github.com/maxgerhardt/platform-raspberrypi)
32+
* **Supported MCUs:** RP2040, RP2350
33+
* **Boards:** 130+ officially supported, including **Raspberry Pi Pico**, **Adafruit**, **Seeed**, **Waveshare**, and many others.
3034

31-
TurtlPass firmware supports **RP2040** and **RP2350** microcontrollers across a wide range of boards while maintaining full Arduino compatibility.
35+
TurtlPass auto-detects compatible drivers and LED configurations at build time, ensuring a unified experience across all supported boards.
3236

3337
---
3438

@@ -82,93 +86,210 @@ Replace `<env>` with one of the [supported environments](#️-supported-boards--
8286

8387
## 🖥️ Supported Boards / Environments
8488

85-
| Board | Environment | LED Type |
86-
| :------------------------------------ | :------------------------- | :----------- |
87-
| Raspberry Pi Pico (RP2040) | `pico` | Single-color |
88-
| Raspberry Pi Pico W (RP2040 + Wi-Fi) | `rpipicow` | Single-color |
89-
| Raspberry Pi Pico 2 (RP2350) | `rpipico2` | Single-color |
90-
| Raspberry Pi Pico 2W (RP2350 + Wi-Fi) | `rpipico2w` | Single-color |
91-
| Adafruit Feather RP2040 | `adafruit_feather` | RGB |
92-
| Adafruit QT Py RP2040 | `adafruit_qtpy` | RGB |
93-
| Adafruit Trinkey QT2040 | `adafruit_trinkeyrp2040qt` | RGB |
94-
| Seeed Xiao RP2040 | `seeed_xiao_rp2040` | RGB |
95-
| Seeed Xiao RP2350 | `seeed_xiao_rp2350` | RGB |
96-
| Waveshare RP2040-Zero | `waveshare_rp2040_zero` | RGB |
97-
| Waveshare RP2350-Zero | `waveshare_rp2350_zero` | RGB |
98-
| **Generic RP2040** | `generic` | Single/RGB |
99-
| **Generic RP2350** | `generic_rp2350` | Single/RGB |
89+
TurtlPass supports **over 130 boards** based on the **RP2040** and **RP2350** microcontrollers.
90+
Each board automatically selects the correct **LED driver** (Analog, Cyw43, RGB3Pin, FastLED).
91+
92+
93+
### 🍓 Official Raspberry Pi Pico Boards
94+
95+
| Board | Environment | LED Driver | MCU |
96+
| :------------------------ | :---------- | :--------- | :----- |
97+
| **Raspberry Pi Pico** | `pico` | Analog | RP2040 |
98+
| **Raspberry Pi Pico W** | `rpipicow` | Cyw43 | RP2040 |
99+
| **Raspberry Pi Pico 2** | `rpipico2` | Analog | RP2350 |
100+
| **Raspberry Pi Pico 2 W** | `rpipico2w` | Cyw43 | RP2350 |
101+
102+
> 🏷️ *These are the officially supported Raspberry Pi boards, with both RP2040 and RP2350 MCU variants.*
103+
104+
105+
### 🧠 Generic / Custom Boards
106+
107+
Use these environments for any other **RP2040** or **RP2350** design (custom PCBs, dev boards, etc.).
108+
LED pins and drivers can be configured manually through `build_flags`.
109+
110+
| Board | Environment | LED Type | MCU |
111+
| :----------------- | :--------------- | :------- | :----- |
112+
| **Generic RP2040** | `generic` | Mono/RGB | RP2040 |
113+
| **Generic RP2350** | `generic_rp2350` | Mono/RGB | RP2350 |
114+
115+
> ⚙️ *Ideal for custom or unlisted RP2040 / RP2350-based boards.*
116+
> *Configure `TP_PIN_LED` and `TP_RGB_LED` manually via `build_flags`.*
117+
118+
119+
### 🌐 Community & Partner Boards
120+
121+
<details>
122+
<summary>(Click to expand)</summary>
123+
124+
| Board | Environment |
125+
| :---- | :---------- |
126+
| 0xCB Helios | `0xcb_helios` |
127+
| Adafruit Feather RP2040 Adalogger | `adafruit_feather_adalogger` |
128+
| Adafruit Feather RP2040 CAN | `adafruit_feather_can` |
129+
| Adafruit Feather RP2040 DVI | `adafruit_feather_dvi` |
130+
| Adafruit Feather RP2040 Prop-Maker | `adafruit_feather_prop_maker` |
131+
| Adafruit Feather RP2040 RFM | `adafruit_feather_rfm` |
132+
| Adafruit Feather RP2350 Adalogger | `adafruit_feather_rp2350_adalogger` |
133+
| Adafruit Feather RP2350 HSTX | `adafruit_feather_rp2350_hstx` |
134+
| Adafruit Feather RP2040 SCORPIO | `adafruit_feather_scorpio` |
135+
| Adafruit Feather RP2040 ThinkINK | `adafruit_feather_thinkink` |
136+
| Adafruit Feather RP2040 USB Host | `adafruit_feather_usb_host` |
137+
| Adafruit Feather RP2040 | `adafruit_feather` |
138+
| Adafruit Floppsy | `adafruit_floppsy` |
139+
| Adafruit Fruit Jam RP2350 | `adafruit_fruitjam` |
140+
| Adafruit ItsyBitsy RP2040 | `adafruit_itsybitsy` |
141+
| Adafruit KB2040 | `adafruit_kb2040` |
142+
| Adafruit MacroPad RP2040 | `adafruit_macropad2040` |
143+
| Adafruit Metro RP2350 | `adafruit_metro_rp2350` |
144+
| Adafruit Metro RP2040 | `adafruit_metro` |
145+
| Adafruit QT Py RP2040 | `adafruit_qtpy` |
146+
| Adafruit STEMMA Friend RP2040 | `adafruit_stemmafriend` |
147+
| Adafruit Trinkey RP2040 QT | `adafruit_trinkeyrp2040qt` |
148+
| METE HOCA Akana R1 | `akana_r1` |
149+
| Amken BunnyBoard | `amken_bunny` |
150+
| Amken Revelop eS | `amken_revelop_es` |
151+
| Amken Revelop Plus | `amken_revelop_plus` |
152+
| Amken Revelop | `amken_revelop` |
153+
| Arduino Nano RP2040 Connect | `arduino_nano_connect` |
154+
| ArtronShop RP2 Nano | `artronshop_rp2_nano` |
155+
| BIGTREETECH SKR-Pico | `bigtreetech_SKR_Pico` |
156+
| BridgeTek IDM2040-43A | `bridgetek_idm2040_43a` |
157+
| BridgeTek IDM2040-7A | `bridgetek_idm2040_7a` |
158+
| iLabs Challenger 2040 LoRa | `challenger_2040_lora` |
159+
| iLabs Challenger 2040 LTE | `challenger_2040_lte` |
160+
| iLabs Challenger 2040 SD/RTC | `challenger_2040_sdrtc` |
161+
| iLabs Challenger 2040 SubGHz | `challenger_2040_subghz` |
162+
| iLabs Challenger 2040 UWB | `challenger_2040_uwb` |
163+
| iLabs Challenger 2350 WiFi/BLE | `challenger_2350_wifi6_ble5` |
164+
| iLabs Connectivity 2040 LTE/WiFi/BLE | `connectivity_2040_lte_wifi_ble` |
165+
| Cytron IRIV IO Controller | `cytron_iriv_io_controller` |
166+
| Cytron Maker Nano RP2040 | `cytron_maker_nano_rp2040` |
167+
| Cytron Maker Pi RP2040 | `cytron_maker_pi_rp2040` |
168+
| Cytron Maker Uno RP2040 | `cytron_maker_uno_rp2040` |
169+
| Cytron Motion 2350 Pro | `cytron_motion_2350_pro` |
170+
| DatanoiseTV PicoADK v2 | `datanoisetv_picoadk_v2` |
171+
| DatanoiseTV PicoADK | `datanoisetv_picoadk` |
172+
| Degz Robotics Suibo RP2040 | `degz_suibo` |
173+
| DFRobot Beetle RP2040 | `dfrobot_beetle_rp2040` |
174+
| L'atelier d'Arnoz DudesCab | `DudesCab` |
175+
| ElectronicCats HunterCat NFC RP2040 | `electroniccats_huntercat_nfc` |
176+
| EVN Alpha | `evn_alpha` |
177+
| ExtremeElectronics RC2040 | `extelec_rc2040` |
178+
| DeRuiLab FlyBoard2040Core | `flyboard2040_core` |
179+
| GeeekPi RP2040 Plus | `geeekpi_rp2040_plus` |
180+
| GroundStudio Marble Pico | `groundstudio_marble_pico` |
181+
| iLabs RPICO32 | `ilabs_rpico32` |
182+
| Architeuthis Flux Jumperless | `jumperless_v1` |
183+
| Architeuthis Flux Jumperless V5 | `jumperless_v5` |
184+
| Melopero Cookie RP2040 | `melopero_cookie_rp2040` |
185+
| Melopero Shake RP2040 | `melopero_shake_rp2040` |
186+
| Makerbase MKS THR36 | `mksthr36` |
187+
| Makerbase MKS THR42 | `mksthr42` |
188+
| MyMakers RP2040 | `MyRP_bot` |
189+
| Arduino Arduino Nano RP2040 Connect | `nanorp2040connect` |
190+
| Neko Systems BL2040 Mini | `nekosystems_bl2040_mini` |
191+
| Newsan Archi | `newsan_archi` |
192+
| nullbits Bit-C PRO | `nullbits_bit_c_pro` |
193+
| Olimex Pico2XL | `olimex_pico2xl` |
194+
| Olimex Pico2XXL | `olimex_pico2xxl` |
195+
| Olimex RP2040-Pico30 | `olimex_rp2040pico30` |
196+
| Raspberry Pi Raspberry Pi Pico | `pico` |
197+
| Pimoroni Explorer | `pimoroni_explorer` |
198+
| Pimoroni PGA2040 | `pimoroni_pga2040` |
199+
| Pimoroni PGA2350 | `pimoroni_pga2350` |
200+
| Pimoroni PicoPlus2 | `pimoroni_pico_plus_2` |
201+
| Pimoroni PicoPlus2W | `pimoroni_pico_plus_2w` |
202+
| Pimoroni Plasma2040 | `pimoroni_plasma2040` |
203+
| Pimoroni Plasma2350 | `pimoroni_plasma2350` |
204+
| Pimoroni Servo2040 | `pimoroni_servo2040` |
205+
| Pimoroni Tiny2040 | `pimoroni_tiny2040` |
206+
| Pimoroni Tiny2350 | `pimoroni_tiny2350` |
207+
| Pintronix PinMax | `pintronix_pinmax` |
208+
| RAKwireless RAK11300 | `rakwireless_rak11300` |
209+
| redscorp RP2040-Eins | `redscorp_rp2040_eins` |
210+
| redscorp RP2040-ProMini | `redscorp_rp2040_promini` |
211+
| Generic Sea-Picro | `sea_picro` |
212+
| Seeed INDICATOR RP2040 | `seeed_indicator_rp2040` |
213+
| Seeed XIAO RP2040 | `seeed_xiao_rp2040` |
214+
| Seeed XIAO RP2350 | `seeed_xiao_rp2350` |
215+
| Silicognition RP2040-Shim | `silicognition_rp2040_shim` |
216+
| Soldered Electronics NULA RP2350 | `soldered_nula_rp2350` |
217+
| Solder Party RP2040 Stamp | `solderparty_rp2040_stamp` |
218+
| Solder Party RP2350 Stamp XL | `solderparty_rp2350_stamp_xl` |
219+
| Solder Party RP2350 Stamp | `solderparty_rp2350_stamp` |
220+
| SparkFun IoT Node LoRaWAN | `sparkfun_iotnode_lorawanrp2350` |
221+
| SparkFun IoT RedBoard RP2350 | `sparkfun_iotredboard_rp2350` |
222+
| SparkFun MicroMod RP2040 | `sparkfun_micromodrp2040` |
223+
| SparkFun ProMicro RP2040 | `sparkfun_promicrorp2040` |
224+
| SparkFun ProMicro RP2350 | `sparkfun_promicrorp2350` |
225+
| SparkFun Thing Plus RP2040 | `sparkfun_thingplusrp2040` |
226+
| SparkFun Thing Plus RP2350 | `sparkfun_thingplusrp2350` |
227+
| SparkFun XRP Controller (Beta) | `sparkfun_xrp_controller_beta` |
228+
| SparkFun XRP Controller | `sparkfun_xrp_controller` |
229+
| uPesy RP2040 DevKit | `upesy_rp2040_devkit` |
230+
| VCC-GND YD RP2040 | `vccgnd_yd_rp2040` |
231+
| Viyalab Mizu RP2040 | `viyalab_mizu` |
232+
| Waveshare RP2040 LCD 0.96 | `waveshare_rp2040_lcd_0_96` |
233+
| Waveshare RP2040 LCD 1.28 | `waveshare_rp2040_lcd_1_28` |
234+
| Waveshare RP2040 Matrix | `waveshare_rp2040_matrix` |
235+
| Waveshare RP2040 One | `waveshare_rp2040_one` |
236+
| Waveshare RP2040 PiZero | `waveshare_rp2040_pizero` |
237+
| Waveshare RP2040 Plus | `waveshare_rp2040_plus` |
238+
| Waveshare RP2040 Zero | `waveshare_rp2040_zero` |
239+
| Waveshare RP2350 LCD 0.96 | `waveshare_rp2350_lcd_0_96` |
240+
| Waveshare RP2350 PiZero | `waveshare_rp2350_pizero` |
241+
| Waveshare RP2350 Plus | `waveshare_rp2350_plus` |
242+
| Waveshare RP2350 Zero | `waveshare_rp2350_zero` |
243+
| WIZnet W5100S-EVB-Pico | `wiznet_5100s_evb_pico` |
244+
| WIZnet W5100S-EVB-Pico2 | `wiznet_5100s_evb_pico2` |
245+
| WIZnet W5500-EVB-Pico | `wiznet_5500_evb_pico` |
246+
| WIZnet W5500-EVB-Pico2 | `wiznet_5500_evb_pico2` |
247+
| WIZnet W55RP20-EVB-Pico | `wiznet_55rp20_evb_pico` |
248+
| WIZnet W6300-EVB-Pico | `wiznet_6300_evb_pico` |
249+
| WIZnet W6300-EVB-Pico2 | `wiznet_6300_evb_pico2` |
250+
| WIZnet WizFi360-EVB-Pico | `wiznet_wizfi360_evb_pico` |
251+
</details>
100252

101253
---
102254

103255
## ⚙️ Optional Build Flags
104256

105257
Customize firmware parameters via `build_flags`:
106258

107-
| Flag | Description | Default |
108-
| :-------------------------- | :------------------------------ | :------------ |
109-
| `__TURTLPASS_VERSION__` | Firmware version string | `"3.0.0"` |
110-
| `__TURTLPASS_LED_PIN__` | Onboard LED pin number | `LED_BUILTIN` |
111-
| `__TURTLPASS_LED_IS_RGB__` | Enable RGB LED (`true`/`false`) | `false` |
112-
| `__TURTLPASS_EEPROM_SIZE__` | Emulated EEPROM size (bytes) | `4096` |
113-
| `__TURTLPASS_PIN_TTP223__` | GPIO pin for touch sensor | *undefined* |
259+
| Flag | Description | Default |
260+
| :--------------- | :------------------------------ | :------------ |
261+
| `TP_VERSION` | Firmware version string | `"3.1.0"` |
262+
| `TP_PIN_LED` | Onboard LED pin number | `LED_BUILTIN` |
263+
| `TP_RGB_LED` | Enable RGB LED (`1`/`0`) | `0` (false) |
264+
| `TP_EEPROM_SIZE` | Emulated EEPROM size (bytes) | `4096` |
265+
| `TP_PIN_TTP223` | GPIO pin for touch sensor | *undefined* |
266+
114267

115268
### 💡 Inline Override Example
116269

117270
```bash
118-
pio run -e pico -D__TURTLPASS_EEPROM_SIZE__=2048
271+
pio run -e pico -DTP_EEPROM_SIZE=2048
119272
```
120273

121274
---
122275

123276
## 🔄 Building for Other Boards
124277

125-
TurtlPass supports any board based on **RP2040** or **RP2350** — including fully custom configurations.
126-
127-
---
128-
129-
### 🧩 Supported Boards Reference
130-
131-
See the full list here:
132-
👉 [maxgerhardt/platform-raspberrypi — boards](https://github.com/maxgerhardt/platform-raspberrypi/tree/develop/boards)
133-
134-
To build for one, create a new environment in your `platformio.ini` file.
135-
136-
#### ⚙️ Example — Waveshare RP2040 Zero
137-
138-
```ini
139-
[env:waveshare_rp2040_zero]
140-
extends = env:base
141-
board = waveshare_rp2040_zero
142-
build_flags =
143-
${env:base.build_flags}
144-
-D__TURTLPASS_LED_IS_RGB__=true ; RGB LED
145-
```
146-
147-
Then build it:
148-
149-
```bash
150-
pio run -e waveshare_rp2040_zero
151-
```
152-
153-
---
154-
155-
### 🧠 Custom Boards
156-
157-
> 🧭 **Tip:**
158-
> Use `generic` for RP2040 or `generic_rp2350` for RP2350, and manually define LED pin and RGB settings.
278+
🧭 **Tip:**
279+
Use `generic` for RP2040 or `generic_rp2350` for RP2350, and manually define LED pin and RGB settings.
159280

160-
#### Example
281+
### Example
161282

162283
```bash
163284
pio run -e generic \
164-
-D__TURTLPASS_LED_PIN__=16 \
165-
-D__TURTLPASS_LED_IS_RGB__=true
285+
-DTP_PIN_LED=16 \
286+
-DTP_RGB_LED=1
166287
```
167288

168289
**Notes:**
169290

170-
* `__TURTLPASS_LED_PIN__` — sets the LED pin number
171-
* `__TURTLPASS_LED_IS_RGB__` — set `true` for RGB LED
291+
* `TP_PIN_LED` — sets the LED pin number
292+
* `TP_RGB_LED` — set `1` (true) for RGB LED
172293

173294
---
174295

@@ -177,7 +298,7 @@ pio run -e generic \
177298
Attach a **TTP-223 capacitive touch sensor** to replace the BOOTSEL button.
178299

179300
```ini
180-
-D__TURTLPASS_PIN_TTP223__=2
301+
-DTP_PIN_TTP223=2
181302
```
182303

183304
This configures the firmware to use the external touch input instead of **BOOTSEL**.

0 commit comments

Comments
 (0)