mangavalk/JC3636W518EN
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3e412f8231bcd24c24781ad5eee8463bb685e7ec
JC3636W518EN/CLAUDE.md
T
patriandClaude Opus 5.5 3e412f8231 Fix LVGL GIF decoder: start with transparent canvas 
LVGL 8.3.11 gifdec filled the initial canvas opaque with the GIF background
color, so transparent-background GIFs (loligod.gif) showed dark gray until
'restore to background' frames cleared each area to the screen color.

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

104 lines
9.3 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.
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).
- 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.
Reference in new issue View Git Blame Copy Permalink