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 9.6.0 port (display_gif_embedded, 2026-10-23): 23.4 fps (= the GIF's own 23.7 fps; decode ~12 ms, refresh ~24 ms) vs 20.6 fps tuned LVGL 8.3. LVGL 9.6 replaced gifdec with bitbank2 AnimatedGIF (2× faster decode, correct transparency — no local patch needed). Port notes: lib_deps = lvgl/lvgl@9.6.0 (takes priority over the vendor lvgl 8 in lib_extra_dirs); lv_conf.h generated from the 9.6 template (CLIB malloc, refresh 15 ms, GIF on, examples off); in 9.6 public headers live in include/lvgl/ and LV_COLOR_DEPTH is deprecated → LV_COLOR_FORMAT_DEFAULT (RGB565); no LV_COLOR_16_SWAP → lv_draw_rgb565_swap() in the flush cb; no LV_TICK_CUSTOM → lv_tick_set_cb(millis); no monitor_cb → display events LV_EVENT_REFR_START/RENDER_START/REFR_READY; images are lv_image_dsc_t with LV_IMAGE_HEADER_MAGIC. lv_gif_set_color_format() can switch the GIF buffer from ARGB8888 to RGB565 (untested).
• LVGL version: the other 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.