JC3636W518EN/CLAUDE.md

# JC3636W518EN — Project Notes

Vendor kit and documentation for the **JC3636W518** (Shenzhen Jingcai / JCZN, Guition), a round 1.8" ESP32-S3 touch-display puck.
Goal: write a **new custom program** for this device.

## Working agreement (from the user)
- Before starting any task, **ask questions first** and make sure requirements are clearly understood.
- While working, **describe what is being done** at each step.
- Keep this file updated with new findings.
- The folder is a **git repo** (local only, no remote). Commit `9ee85bf` = original kit snapshot before any cleanup.

## Hardware summary
| Item | Detail |
|---|---|
| MCU | ESP32-S3R8 (dual-core LX7 @ 240 MHz, 512 KB SRAM, **8 MB OPI PSRAM** in-package) |
| Flash | **16 MB confirmed** (esptool flash_id: mfr 0x85, dev 0x2018, quad mode). Chip rev v0.2, MAC f0:9e:9e:1e:60:40 |
| Radio | WiFi + **BLE 5 only — NO Bluetooth Classic** (ESP32-S3 has no BR/EDR, so no SPP / `BluetoothSerial`) |
| Connection | Board shows up on **COM21** on this PC. esptool: `%LOCALAPPDATA%\Arduino15\packages\esp32\tools\esptool_py\4.6\esptool.exe` |
| Display | 1.8" round IPS, **360×360**, driver **ST77916** over **QSPI**, RGB565 used (panel is 262K/18-bit) |
| Touch | **CST816S** capacitive, I2C (addr 0x15), single touch + gestures |
| Audio out | **PCM5100A** I2S DAC → 3.5 mm line-out jack (no speaker amp on board) |
| Microphone | **MSM261S4030H0R** I2S MEMS mic ("pickup port") |
| Storage | microSD (TF) slot, 4-bit SD_MMC |
| Button | BOOT button on GPIO0 (only user button) |
| Power | 5 V USB-C (~180 mA), plus **Qi wireless receiver** (standalone, no MCU signals) |
| USB | Native USB (GPIO19/20) — USB-CDC serial, no separate USB-UART chip |
| Expansion | CN2 4-pin connector: **5V, GPIO39, GPIO38, GND** (the only free GPIOs) |
| Size | 58 × 58 × 11 mm metal case, active area 45.68 × 45.68 mm |

## Pin map (from `pincfg.h`, cross-checked against schematic)
```
LCD QSPI : CS=10  SCK=9  D0=11 D1=12 D2=13 D3=14  RST=47  BL=15 (PWM, LEDC, via AO3400 MOSFET)
           LCD_TE is on the FPC; schematic net near GPIO47/RST is hard to read — treat TE as unused
Touch I2C: SDA=7  SCL=8  INT=41  RST=40
SD_MMC   : CLK=3  CMD=4  D0=2  D1=1  D2=6  D3=5
DAC I2S  : BCK=18 WS/LRCK=16 DOUT=17  MCK=21 (code uses -1, PCM5100A PLLs from BCK)  MUTE/XSMT=48 (LOW = mute)
Mic I2S  : SCK=42 WS=45 SD=46
Button   : GPIO0 (BOOT)
Free     : GPIO38, GPIO39 (on CN2 header)
USB      : D-=19 D+=20
```

## PlatformIO setup (preferred build system, since 2026-10-23)
- All projects are **PlatformIO projects** (`platformio.ini`, `src/main.cpp`, `include/`). They no longer open in the Arduino IDE.
- PlatformIO IDE extension is installed in VS Code. CLI: `%USERPROFILE%\.platformio\penv\Scripts\pio.exe` (Core 6.2.0, not on PATH).
- **JC3636W518 (ESP32-S3)**: platform `https://github.com/pioarduino/platform-espressif32/releases/download/51.03.05/platform-espressif32.zip` (pioarduino = Arduino core 3.0.5; the official PIO espressif32 only has core 2.x, which ESP32_Display_Panel 0.1.4 can't use).
  Board `esp32-s3-devkitc-1` + `board_build.arduino.memory_type = qio_opi`, `flash_mode = qio`, `board_upload.flash_size = 16MB`, `partitions = huge_app.csv`, `-DBOARD_HAS_PSRAM -DARDUINO_USB_CDC_ON_BOOT=1`, upload/monitor COM21 @115200.
  Libraries: `lib_extra_dirs` → vendor `2-Program Example/Demo_Arduino/library`.
  **LVGL config:** `-DLV_CONF_INCLUDE_SIMPLE -Iinclude` — the `-Iinclude` is required, otherwise the LVGL library compiles without the project's `lv_conf.h` (symptom: `undefined reference to lv_gif_create`).
- **Classic ESP32** projects (bridge, ELMulator): `espressif32@6.10.0` (core 2.0.17), board `esp32dev`, `huge_app.csv`.
- Template for a new JC3636W518 project: copy `10-OBD-Display-2024/display_speed_wifi/platformio.ini` (+ `include/pincfg.h`, `include/scr_st77916.h`, `include/lv_conf.h`).
- When converting `.ino` → `main.cpp`: add `#include <Arduino.h>` and prototypes for functions used before their definition; don't `#include` `.c` files that are also in `src/`.

## Software stack used by the vendor demo
- **Arduino IDE** + **arduino-esp32 core ≥ 3.0.1** (core **3.0.5 already installed** on this PC under `%LOCALAPPDATA%\Arduino15`).
- Libraries (bundled in `2-Program Example/Demo_Arduino/library/`):
  - `ESP32_Display_Panel` **0.1.4** (Espressif) — ST77916 QSPI LCD + CST816S touch + backlight
  - `ESP32_IO_Expander` **0.0.2** (dependency)
  - `lvgl` **8.3.11** bundled (instructions say "8.4.0 and below"; LVGL 9 is NOT supported by the demo)
- `lv_conf.h` must be copied next to the `lvgl` library folder (`Documents\Arduino\libraries\lv_conf.h`); for the LVGL demos, move `lvgl/demos` into `lvgl/src/`.
- Key `lv_conf.h` settings: `LV_COLOR_DEPTH 16`, `LV_COLOR_16_SWAP 1`, `LV_MEM_CUSTOM 1` (uses malloc → can use PSRAM), `LV_TICK_CUSTOM 1`, `LV_USE_GIF 1`, `LV_USE_PNG 1`, `LV_USE_SJPG 1`, Montserrat 48 enabled.
- None of these libraries are currently in `Documents\Arduino\libraries` (only unrelated Adafruit libs). No arduino-cli / PlatformIO / ESP-IDF installed. Python 3.12 and git are available.

### Arduino board settings (from `Arduino set up.png`)
Board **ESP32S3 Dev Module**, USB CDC On Boot **Enabled**, CPU 240 MHz, Flash **QIO 120 MHz**, Flash Size **16 MB**,
Partition **Huge APP (3MB No OTA/1MB SPIFFS)**, PSRAM **OPI PSRAM**, Upload Mode UART0/Hardware CDC, Upload speed 921600.
If upload fails: hold BOOT (GPIO0) while plugging in / resetting.

## Display driver pattern (`scr_st77916.h`)
`scr_lvgl_init()` does everything: LEDC backlight → CST816S on I2C @400 kHz → QSPI bus @50 MHz → `ESP_PanelLcd_ST77916(bus, 16bpp, RST)` → `invertColor(true)` → LVGL draw buffer of **72 rows** (360×72×2 = ~52 KB, internal RAM) → flush callback with DMA-done callback → touch indev.
Helpers: `setRotation(0..3)`, `set_brightness(0..100)`, `screen_switch(bool)`.
Note: `scr_lvgl_init()` already calls `lv_init()`; the demo `.ino` calls it again (redundant).

## Folder contents
| Folder | What it is |
|---|---|
| `1-Instructions` | Spec PDF (duplicate), AIDA64 remote-sensor layout `aida_remote_1.85.rslcd`, MJPEG conversion tool (Windows .NET, converts video to 360×360 MJPEG 25 fps) |
| `2-Program Example/Demo_Arduino` | **Vendor only:** `library/` (3 libs), `lv_conf.h` (vendor original), `sd/` (SD listing example; its lv_conf.h has FATFS edits), `docs/` (setup screenshots + compile instructions). The vendor's original LVGL demo sketch no longer exists unmodified. |
| `10-OBD-Display-2024` | **Earlier OBD speed-display project**, split into separate sketches — see its `README.md`: `display_speed_wifi`, `display_gif_sd`, `display_gif_embedded`, `elm327_wifi_bridge` (classic ESP32), `elmulator`, `assets/gifs`, `_archive/lvgl9_broken` |
| `3-Specification` | Spec sheet (factory firmware features, interface photo) |
| `4-Chip manual` | ESP32-S3R8 datasheet, PCM5100A datasheet |
| `5-Dimension` | Mechanical drawings (JPG + DWG) |
| `6-Schematic diagram` | 5 pages: power/USB/SD/mic, ESP32-S3, DAC, LCD FPC, Qi receiver |
| `7-User's manual` | "Getting started" — Arduino IDE setup, library install steps (16 pages) |
| `8-Tool` | Network debugging assistant, SSCOM serial tool (Chinese Windows tools, .rar) |
| `9-Burn` | Espressif Flash Download Tool 3.9.3, factory demo `1.85_demo.bin` (1.7 MB, flash at 0x0), screenshots. `logs/` are old (2022) logs from other boards — ignore |

## Factory firmware (for reference)
AIDA64 secondary screen (18 styles), mic spectrum, MP3 player (`/music` on SD), photo frame (`/pic`, 360×360 JPEG), MJPEG player (`/mjpeg`), weather, theme clocks, WiFi provisioning AP "My App"/12345678 + web config at device IP.
Re-flash it with Flash Download Tool: ESP32-S3, `1.85_demo.bin` @ 0x0.

## OBD adapter (user's)
AliExpress "ELM327 Mini V2.1 Bluetooth OBD **Dual Mode** 5.1" — dual mode = Bluetooth Classic SPP **and BLE**, so the ESP32-S3 should be able to connect directly over BLE (no bridge ESP32).
Cheap dual-mode clones typically expose BLE service `FFF0` (notify `FFF1`, write `FFF2`) — **not yet verified** on this adapter; scan it first. Adapter is powered from the car's OBD port (pin 16, 12 V).

## Gotchas / observations
- **LVGL GIF bug (patched locally):** LVGL 8.3.11 `gifdec.c` (`gd_open_gif`) filled the canvas *opaque* with the GIF's background color. GIFs with a transparent background (e.g. `loligod.gif`, bg = RGB 28,29,49) showed that dark gray except where "restore to background" frames had cleared to transparent (→ screen black). **Patched** in the vendor copy `2-Program Example/Demo_Arduino/library/lvgl/src/extra/libs/gif/gifdec.c`: initial canvas alpha 0x00 (marked `LOCAL PATCH`). Re-apply if LVGL is ever replaced/upgraded.
- Most GIFs in `assets/gifs` are optimized (transparent unchanged pixels, disposal 1/2); `loligod.gif` has a fully transparent background (~84 % of each frame).
- **GIF performance** (360×360 loligod, embedded, measured with a `monitor_cb` FPS counter in `display_gif_embedded`):
  baseline 15.4 fps (decode 27 ms + refresh 31 ms) → no LVGL log / no per-loop prints: no change → `vTaskDelay(1)`: 16.5 → **double draw buffer** (2×72 rows internal RAM): 19.5 (refresh 21 ms) → **`-O2`** instead of `-Os`: **20.6 fps** (refresh 19 ms, decode ~24 ms). GIF's own rate is 23.7 fps. From SD card it was only ~1.4 fps.
  Remaining limit is LVGL's single-threaded GIF decode; going further would need decoding on the other core or a lighter format (e.g. pre-converted frames/MJPEG).
- **SD card (user's 487 MB SDSC)** intermittently fails to init (`sdmmc_init_ocr ... 0x107`) after resets; once stuck only a power cycle helps (card VDD is hard-wired to 3V3). Recommend a newer SDHC card.
- Reading boot logs: USB-CDC — reset via DTR=0/RTS pulse, then reopen the port (it re-enumerates).
- LVGL version: all JC3636W518 projects use the vendor-bundled **LVGL 8.3.11**. LVGL 9 would require porting `scr_st77916.h` (display/touch driver glue).
- Display is round: corners of the 360×360 framebuffer are not visible — design UI within a 360 px circle.
- Compiling a 13.9 MB GIF into the firmware will not fit "Huge APP" (3 MB); large media should live on SD (or in a custom partition).
- The top-level demo `setup()` returns early if no SD card is present, before showing anything.
- Draw buffer is in internal RAM; PSRAM is available for larger buffers / images.