Dev

.gitignore

@@ -1,6 +1,8 @@
 # ESP-IDF auto generated by build
 sdkconfig
 sdkconfig.old
+dependencies.lock
+**/dependencies.lock
 
 # compiled output
 /build/
@@ -1044,8 +1046,8 @@ size_info_*.txt
 # pytest-embedded log folder
 pytest_embedded_log/
 
-# idf-component-manager output
-dependencies.lock
+# idf-component-manager lock: TRACKED for reproducible builds (pins the exact
+# managed-component versions so every clone resolves the same deps).
 
 !assets/
 !assets/**

AGENTS.md

@@ -61,7 +61,7 @@ firmware_p4/          # ESP32-P4 master firmware (embeds C5 binary)
     Drivers/          # Hardware drivers (SPI, buttons, display, radio, USB)
     Service/          # Support services (OTA, WiFi, console, storage, SPI bridge)
     Core/             # System core and main managers
-    Applications/     # User-facing apps (UI, bad_usb, SubGhz)
+    Applications/     # User-facing apps (UI, bad_usb, SubGhz, gameboy, nfc)
     Drivers/spi_bridge_phy/  # SPI bridge physical layer (P4 side)
   main/main.c         # Entry point
 common/metadata/      # Shared metadata

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="pics/Highboy_repo.png" alt="HighBoy Banner" width="1000"/>
+  <img src="pics/banner.png" alt="HighBoy Banner" width="1000"/>
 </p>
 
 
@@ -45,7 +45,7 @@ See the general project architecture:
 
 ## How to use this project
 
-We recommend that this project serves as a basis for custom projects with ESP32-S3.
+We recommend that this project serves as a basis for custom projects with the ESP32-P4 and ESP32-C5.
 To start a new project with ESP-IDF, follow the official guide:
 [ESP-IDF Documentation - Create a new project](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project)
 

README.pt.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="pics/Highboy_repo.png" alt="HighBoy Banner" width="1000"/>
+  <img src="pics/banner.png" alt="HighBoy Banner" width="1000"/>
 </p>
 
 
@@ -47,7 +47,7 @@ Veja a arquitetura geral do projeto:
 
 ## Como utilizar este projeto
 
-Recomendamos que este projeto sirva como base para projetos personalizados com ESP32-S3.  
+Recomendamos que este projeto sirva como base para projetos personalizados com o ESP32-P4 e o ESP32-C5.  
 Para começar um novo projeto com ESP-IDF, siga o guia oficial:  
 [Documentação ESP-IDF - Criar novo projeto](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project)
 

docs/README.md

@@ -14,21 +14,33 @@ README.md, separated by `---`.
 
 | Component | Docs |
 |-----------|------|
+| `audio_i2s` | [README.md](audio_i2s/README.md) - I2S audio output driver |
 | `bad_usb` | [README.md](bad_usb/README.md)  |
 | `bluetooth` | [README.md](bluetooth/README.md)  |
 | `boot_report` | [README.md](boot_report/README.md)  |
+| `bq25896` | [README.md](bq25896/README.md) - TI BQ25896 battery charger / PMIC driver |
+| `bridge_manager` | [README.md](bridge_manager/README.md) - P4<->C5 bridge lifecycle and coordination service |
 | `buttons_gpio` | [README.md](buttons_gpio/README.md)  |
 | `c5_flasher` | [README.md](c5_flasher/README.md)  |
 | `cc1101` | [README.md](cc1101/README.md)  |
 | `console` | [README.md](console/README.md)  |
 | `dns_server` | [README.md](dns_server/README.md)  |
+| `drv2605l` | [README.md](drv2605l/README.md) - TI DRV2605L haptic motor driver |
 | `esp_now` | [README.md](esp_now/README.md)  |
 | `espnow_chat` | [README.md](espnow_chat/README.md)  |
+| `gameboy` | [README.md](gameboy/README.md) - Game Boy emulator application |
 | `host_link` | [app-guide.md](host_link/app-guide.md) [protocol.md](host_link/protocol.md) [README.md](host_link/README.md)  |
 | `http_server` | [README.md](http_server/README.md)  |
+| `i2c_init` | [README.md](i2c_init/README.md) - shared I2C bus initialization driver |
 | `input_manager` | [README.md](input_manager/README.md)  |
-| `lvgl_port` | [README.md](lvgl_port/README.md)  |
+| `ir` | [README.md](ir/README.md) - infrared transmit/receive service |
+| `led` | [README.md](led/README.md) - status/RGB LED driver |
+| `LoRa` | [README.md](LoRa/README.md) - LoRa messaging application |
+| `lvgl` | [README.md](lvgl/README.md)  |
+| `nfc` | [README.md](nfc/README.md) - NFC read/write application |
 | `ota` | [README.md](ota/README.md)  |
+| `pins` | [README.md](pins/README.md) - board pin assignment definitions |
+| `power_manager` | [README.md](power_manager/README.md) - battery and power-state management service |
 | `recovery` | [README.md](recovery/README.md)  |
 | `sd_card` | [README.md](sd_card/README.md)  |
 | `spi` | [README.md](spi/README.md)  |
@@ -38,8 +50,11 @@ README.md, separated by `---`.
 | `storage_assets` | [README.md](storage_assets/README.md)  |
 | `storage_vfs` | [README.md](storage_vfs/README.md)  |
 | `SubGhz` | [README.md](SubGhz/README.md)  |
+| `sx1262` | [README.md](sx1262/README.md) - Semtech SX1262 LoRa radio transceiver driver |
 | `sys_monitor` | [README.md](sys_monitor/README.md)  |
 | `sys_prio` | [README.md](sys_prio/README.md)  |
+| `sys_time` | [README.md](sys_time/README.md) - system clock / RTC time service |
 | `tusb_desc` | [README.md](tusb_desc/README.md)  |
 | `ui` | [README.md](ui/README.md) [input-migration.md](ui/input-migration.md)  |
 | `wifi` | [README.md](wifi/README.md)  |
+| `ys_rfid2` | [README.md](ys_rfid2/README.md) - YS-RFID2 125 kHz RFID reader driver |

docs/SubGhz/README.md

@@ -60,6 +60,8 @@ Captures RF signals via the CC1101 GDO0 pin routed to the ESP32 RMT RX periphera
 4. **SCAN mode:** Protocol registry tries all decoders -> Analyzer for unknowns
 5. **RAW mode:** Direct save to storage
 
+**LED feedback:** The RX pipeline drives the status LED as it processes signals: `led_signal_info()` fires when a known protocol is decoded, and `led_signal_warning()` fires when RF is captured but no registered protocol matches.
+
 #### API
 
 ```c
@@ -120,7 +122,7 @@ void subghz_spectrum_start(uint32_t center_freq, uint32_t span_hz);
 void subghz_spectrum_stop(void);
 bool subghz_spectrum_get_line(subghz_spectrum_line_t *out_line);
 ```
-- Task stack: 4096 bytes, priority 1, Core 1.
+- Task stack: 4096 bytes, Core 1. Priority comes from `sys_prio.h`: the `SYS_PRIO_BACKGROUND_LO` band (lowest non-idle background work), so the sweep never contends with the renderer or latency-sensitive services.
 - Thread-safe reads via `subghz_spectrum_get_line`.
 
 ### Signal Analyzer (`subghz_analyzer`)

docs/audio_i2s/README.md

@@ -0,0 +1,151 @@
+# Audio I2S Driver (P4)
+
+This component drives the on-board audio path of the HighBoy V2 (ESP32-P4 firmware only): a class-D speaker amplifier for playback (TX) and a PDM microphone for capture (RX), both on a single I2S port. It owns one persistent TX channel used for UI chimes, tones, melodies, raw PCM and continuous streaming, and opens independent PDM-RX channels for mic recording and live streaming.
+
+## Overview
+
+- **Location:** `firmware_p4/components/Drivers/audio_i2s/`
+- **Header:** `include/audio_i2s.h`
+- **Firmware:** `firmware_p4` only (no C5 counterpart)
+- **Dependencies:** `driver/i2s_std`, `driver/i2s_pdm`, `driver/gpio`, `freertos`, `pin_def`, `sys_prio`
+- **I2S port:** `I2S_NUM_0` (master role). The single TX channel and the PDM-RX channels share this one port.
+
+> **Part naming note:** the public header docstrings refer to a **MAX98357A** amplifier, while the driver source (`audio_i2s.c`) and the pin map (`pin_def.h`) name an **NS4168** amp and an **MSM261** PDM mic. The code and pin comments are the authoritative wiring reference; the amplifier is enabled by taking its shutdown pin high, and its hardware gain is fixed, so volume is applied digitally.
+
+## Signal Path
+
+### TX (speaker / amplifier)
+
+- **Mode:** I2S standard (Philips) slot format, **16-bit**, **mono**, master.
+- **Default sample rate:** `44100` Hz (`SAMPLE_RATE_HZ`). PCM and stream calls may pass any rate; the driver reconfigures the TX clock only when the requested rate actually changes.
+- **One persistent channel:** `I2S_NUM_0` has exactly one TX channel. It is created once at init and never deleted; playback only enables/disables it and reconfigures its clock. Creating/deleting a channel per sound churned internal DMA RAM and stuttered the UI, so that is avoided.
+- **DMA depth:** `AUDIO_DMA_DESC_NUM` = 8 descriptors x `AUDIO_DMA_FRAME_NUM` = 256 frames (~46 ms, ~8 KB internal RAM), deeper than the IDF default for underrun slack.
+- **Underrun behaviour:** `auto_clear = true`, so a starved channel emits zeros instead of looping the stale buffer.
+- **Anti-click:** each note gets a raised-cosine attack (`ENV_ATTACK_MS` = 4 ms) / release (`ENV_RELEASE_MS` = 8 ms) envelope, and playback brackets sounds with short silence; melodies use a continuous phase accumulator for gapless rendering.
+- **Amp enable:** `GPIO_AUDIO_EN_PIN` is driven high (out of shutdown) at init; idempotent.
+
+### RX (PDM microphone)
+
+- **Mode:** PDM RX, **16-bit**, **mono**, master.
+- **Filtering:** high-pass filter enabled with a 50 Hz cut-off (`hp_cut_off_freq_hz`), digital gain `amplify_num = 3`. A ~120 ms settle delay is applied after enable to let the HP filter converge.
+- **Channels:** the mic uses its own RX channel on `I2S_NUM_0`, independent of the TX side. `audio_i2s_mic_record()` opens/closes a channel per call; the streaming API keeps a persistent RX channel (`s_rx_stream`).
+
+## Concurrency
+
+- Playback runs on a pinned task `"audio_i2s"`: stack `AUDIO_TASK_STACK_SIZE` = 4096, priority `SYS_PRIO_SERVICE_LO`, core `SYS_CORE_RADIO`. It is deliberately **not** on the UI core, because the LVGL renderer at `SYS_PRIO_RENDER` would starve the I2S DMA during a full-frame redraw.
+- A single mutex (`s_tx_mux`) guards the shared TX channel. Callers from the LVGL thread use finite timeouts and drop the sound rather than stall the UI:
+  - `TX_LOCK_WAIT_MS` = 250 ms for blocking playback / stream claims.
+  - `FX_TX_WAIT_MS` = 0 for queued UI effects (never wait behind a melody).
+- Queued UI effects (`audio_play_chime`, `audio_click`) post `fx_t` entries to a depth-4 queue (`QUEUE_DEPTH`); overflow is dropped so button mashing never piles up.
+- While a TX stream is active (`s_streaming`), one-shot playback calls become no-ops so they do not fight the stream.
+
+## Pins (from `pin_def.h`)
+
+| Signal | Define | GPIO |
+| :--- | :--- | :--- |
+| Amp enable / shutdown | `GPIO_AUDIO_EN_PIN` | 49 |
+| I2S bit clock (BCLK) | `GPIO_AUDIO_BCLK_PIN` | 28 |
+| I2S word select (LRCLK / WS) | `GPIO_AUDIO_LRCLK_PIN` | 29 |
+| I2S data out (DOUT) | `GPIO_AUDIO_DIN_PIN` | 27 |
+| Mic PDM clock | `GPIO_MIC_PDM_CLK_PIN` | 54 |
+| Mic PDM data | `GPIO_MIC_PDM_DATA_PIN` | 53 |
+
+MCLK and the TX-side DIN are `I2S_GPIO_UNUSED`.
+
+## API Reference
+
+### Initialization
+
+#### `audio_i2s_init`
+```c
+esp_err_t audio_i2s_init(void);
+```
+Brings up `I2S_NUM_0` on the amp pins, allocates the DMA chunk buffer, mutex and effect queue, and starts the playback task. Idempotent; safe to call multiple times.
+
+#### `audio_i2s_set_volume`
+```c
+void audio_i2s_set_volume(uint8_t pct);
+```
+Sets global output volume (0..100), clamped. Applied as a perceptual (square-law) digital scale on top of each sound's own amplitude, because the amplifier's hardware gain is fixed.
+
+### Tones and Melodies
+
+#### `audio_i2s_play_tone`
+```c
+esp_err_t audio_i2s_play_tone(float freq_hz, int dur_ms, float amp);
+```
+Plays a single blocking sine tone at 44.1 kHz mono. `amp` is in [0..1]. Returns `ESP_ERR_TIMEOUT` if the channel is busy (sound dropped), `ESP_OK` otherwise (also when not ready or a stream is active).
+
+#### `audio_i2s_play_song` / `audio_i2s_play_song_cb`
+```c
+esp_err_t audio_i2s_play_song(const audio_note_t *notes, int count, float amp);
+esp_err_t audio_i2s_play_song_cb(const audio_note_t *notes, int count, float amp,
+                                 audio_song_progress_cb_t cb, void *ctx);
+```
+Plays a melody blocking and gapless: opens the channel once, renders all notes back-to-back with per-note anti-click envelopes and a continuous phase accumulator, then ends. The `_cb` variant invokes `cb` before each note (in the worker thread) with the note index, total count and frequency; returning `false` cancels playback cooperatively after the current note. Pass `cb = NULL` for plain playback.
+
+`audio_note_t` is `{ uint16_t freq_hz; uint16_t dur_ms; }`; `freq_hz == 0` is a rest (silence).
+
+`audio_song_progress_cb_t`:
+```c
+typedef bool (*audio_song_progress_cb_t)(int note_index, int note_count,
+                                         uint16_t freq_hz, void *ctx);
+```
+Must be trivial (touch only volatile scalars); never call `lv_*` from it.
+
+### Raw PCM Playback
+
+#### `audio_i2s_play_pcm`
+```c
+esp_err_t audio_i2s_play_pcm(const int16_t *pcm, size_t n_samples, uint32_t sample_rate);
+```
+Plays a raw 16-bit mono PCM buffer (blocking) at `sample_rate`. Reconfigures the TX clock to the given rate and appends a short tail-silence.
+
+### Continuous TX Streaming
+
+#### `audio_i2s_stream_start` / `audio_i2s_stream_write` / `audio_i2s_stream_stop`
+```c
+esp_err_t audio_i2s_stream_start(uint32_t sample_rate);
+int       audio_i2s_stream_write(const int16_t *pcm, int n_samples);
+void      audio_i2s_stream_stop(void);
+```
+Begins a continuous 16-bit mono TX stream (e.g. WAV playback), reusing the shared TX channel and suppressing UI chimes/clicks for its duration. `stream_write` applies global volume, blocks and paces to real time via the I2S DMA, and returns samples written (or -1 if the stream is not active). `stream_stop` drains the DMA, restores the default clock and re-enables UI sounds; safe when not started.
+
+### PDM Microphone Capture
+
+#### `audio_i2s_mic_record`
+```c
+esp_err_t audio_i2s_mic_record(int16_t *out, size_t max_samples, uint32_t sample_rate,
+                               size_t *out_captured, audio_mic_level_cb_t cb, void *ctx);
+```
+Captures up to `max_samples` of 16-bit mono PCM from the PDM mic (blocking): opens a PDM-RX channel, lets the HP filter settle (~120 ms), fills `out`, then closes. `*out_captured` receives the real sample count. If `cb` is non-NULL it is invoked after each chunk with that chunk's peak and RMS level for a live VU meter.
+
+`audio_mic_level_cb_t`:
+```c
+typedef void (*audio_mic_level_cb_t)(int peak, int rms, void *ctx);
+```
+`peak` is max |sample| (0..32767) of the last chunk. Runs in the recording task's context; keep it trivial.
+
+#### `audio_i2s_mic_stream_start` / `audio_i2s_mic_stream_read` / `audio_i2s_mic_stream_stop`
+```c
+esp_err_t audio_i2s_mic_stream_start(uint32_t sample_rate);
+int       audio_i2s_mic_stream_read(int16_t *buf, int max_samples);
+void      audio_i2s_mic_stream_stop(void);
+```
+Opens a persistent PDM-RX stream at `sample_rate` (idempotent). `mic_stream_read` reads up to `max_samples` 16-bit mono samples, returning the count read (0 on error/timeout/not-started). `mic_stream_stop` stops and frees the RX channel; safe when not started.
+
+### UI Sound Effects
+
+#### `audio_play_chime`
+```c
+void audio_play_chime(void);
+```
+Queues a 3-note boot chime (C5 -> E5 -> G5, ~130-180 ms each). Non-blocking; dropped if the queue is full.
+
+#### `audio_click`
+```c
+void audio_click(void);
+```
+Queues a short click (~30 ms, ~2 kHz). Non-blocking; dropped if the queue already holds pending entries so rapid button presses never pile up.
+</content>
+</invoke>