mangavalk/JC3636W518EN
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
55e27b657292f71dedc2492c6e6e4053c2bea890
JC3636W518EN/CLAUDE.md
T
patriandClaude Opus 5.5 55e27b6572 Port display_gif_sd and display_speed_wifi to LVGL 9.6 + shared library 
- both use shared/jc3636w518.ini, board library and perf monitor
- GIF decoded in the display color format, loop delay 1 ms,
  per-loop memory prints removed
- lv_conf: LVGL drive A: = SD card via LV_USE_FS_STDIO (/sdcard/)
- shared/README.md, CLAUDE.md and project README updated

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 01:37:29 +02:00

116 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
**All of this lives in `shared/jc3636w518.ini`**; a project's `platformio.ini` only does `extra_configs` + `[shared] dir` + `extends = jc3636w518` (see `shared/README.md`).
Libraries: `lib_deps = lvgl/lvgl@9.6.0`, `lib_extra_dirs` → `shared/lib` (board library) + vendor `2-Program Example/Demo_Arduino/library` (ESP32_Display_Panel, ESP32_IO_Expander; its lvgl 8 is not used).
**LVGL config:** `-DLV_CONF_INCLUDE_SIMPLE -I${shared.dir}/include` — the `-I` is required, otherwise the LVGL library compiles without `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`.
- **New JC3636W518 project:** follow `shared/README.md` (3-line platformio.ini + `#include "jc3636w518.h"`).
- Editing files with scripts: keep each file's line endings (most are LF, some `main.cpp` are CRLF) — Python `open(..., newline="")`.
- 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 (shared board library `shared/lib/JC3636W518`, was the vendor `scr_st77916.h`)
`scr_lvgl_init()` does everything: LEDC backlight → CST816S on I2C @400 kHz → QSPI bus @**80 MHz** (vendor: 50) → `ESP_PanelLcd_ST77916(bus, 16bpp, RST)` → `invertColor(true)` → `lv_init()` + tick → LVGL display with **two 72-row draw buffers** (2 × ~52 KB internal RAM) → flush callback with DMA-done callback → touch indev. Returns the `lv_display_t*`.
Helpers: `setRotation(0..3)`, `set_brightness(0..100)`, `screen_switch(bool)`; `perf_monitor.h` prints FPS/refresh/other/CPU once per second.
Display color format is `RGB565_SWAPPED` (ST77916 byte order, set in `lv_conf.h`).
## 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. |
| `shared` | **Shared code for all JC3636W518 projects:** `jc3636w518.ini` (PlatformIO base config), `include/lv_conf.h` (LVGL 9.6), `lib/JC3636W518` (board library). See its `README.md` |
| `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 8 GIF bug (patched locally, only relevant if LVGL 8 is used again):** 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()` switches the GIF buffer format (used, see below).
- **LVGL 9 tuning** (display_gif_embedded, CPU at full 23.8 fps): start 86 % → GIF in display color format 66 % → render `RGB565_SWAPPED` (no swap pass) 60 % → QSPI 80 MHz 55 % → IRAM for hot LVGL code 53 %. No effect: `LV_GIF_CACHE_DECODE_DATA` (not used anywhere in 9.6), 120-row buffers. AnimatedGIF "turbo" mode can't be used: it only outputs in COOKED draw mode, LVGL uses RAW.
- **All JC3636W518 LVGL projects now use LVGL 9.6.0 + the shared library** (display_gif_embedded, display_gif_sd, display_speed_wifi). SD drive `A:` = `LV_USE_FS_STDIO` on `/sdcard/`.
- 80 MHz QSPI and RGB565_SWAPPED rendering: **visual check by the user still pending** (colors / glitches).
- 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).
- `display_gif_sd` / `display_speed_wifi` `setup()` return early if the SD card fails to mount (black screen); `display_gif_embedded` starts its GIF first.
- Draw buffer is in internal RAM; PSRAM is available for larger buffers / images.
Reference in new issue View Git Blame Copy Permalink