Files
JC3636W518EN/CLAUDE.md
T
mangavalkandClaude Opus 5.5 c9ad39c8ed 12-OBD-Speed: read-only UDS DID scan of the car's modules
- Log page now runs a diagnostic scan instead of CAN listening (the Fiesta's OBD
  port carries no broadcast traffic): unfiltered check, module discovery
  0x700-0x7EF (22F188, then 3E00 with 1 s timeout), all 65536 DIDs per module,
  progress in NVS, speed/voltage polled every 2 s in between
- Result (drives 2026-11-12..18): only the PCM 0x7E0 answers; 389 DIDs supported
  (logs in docs/canlog/scan, scan2)
- Reset scan button, BLE connection interval request, progress lines
- CLAUDE.md: screen-has-priority rule, web UI future idea, findings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 16:06:31 +01:00

22 KiB
Raw Blame History

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 screen always has priority (user, 2026-11-12): the GIF animation and the speed updates etc. must stay smooth. Background work (BLE/OBD polling, scans, logging, SD, a future WiFi/web UI) must never make the display stutter or lag — measure FPS before/after when adding load, and give up features/RAM elsewhere first. (Accepted exception for now: the temporary diagnostic scan slows speed updates to ~2 s; user OK'd 2026-11-08.)
  • 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 — the 2024 BT-Classic→WiFi bridge and ELMulator — were removed 2026-10-23; they used espressif32@6.10.0, board esp32dev. In git history.)
  • 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) / getRotation() (panel rotates via MADCTL swap/mirror like the vendor table; touch converted in software in touchpad_read; verified by the user at all 4 angles, 2026-10-23), 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.
tools gif_to_360.py — converts GIFs to 360×360 for the device (Pillow; scale to cover + center crop, keeps frame timing)
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
12-OBD-Speed (+ log page: CAN logger / diagnostic DID scan, 2026-11, see "User's car") The new program — working in the car (2026-10-23): speed from the ELM327 over BLE as big number + arc gauge on a GIF background, battery-voltage arc in the bottom gap, idle/screen-off mode (both verified by the user); swipe left for the adapter menu (scan, select → remembered in NVS, auto-reconnect every 3 s), again for settings (rotation, idle/screen-off timeout), again for the background (GIF from SD /gifs copied into an 11.9 MB raw flash partition, own partitions.csv). See its README.md
13-Dash-Mount 3D-printed dashboard holder (OpenSCAD, 2026-10-23; base printed 2026-10-24, user: "perfect"): snap-in cup with lip over the bezel + USB-C opening on the side, detent tilt hinge (36 face teeth = 10° steps, M3×20 bolt + captive nut + printed knob), flat foot for VHB tape. ASA. User's choices: adhesive base, detent hinge, M3, cable exits sideways, only a USB-C opening needed. OpenSCAD is installed (C:\Program Files\OpenSCAD\openscad.exe, use from bash for -D part="..." quoting). See its README.md
10-GIF-Tests GIF playback experiments (was 10-OBD-Display-2024): display_gif_embedded, display_gif_sd, assets/gifs. The 2024 bridge/ELMulator/WiFi speed sketch, the broken LVGL 9 archive and the BLE scanner tool (11-BLE-Scanner: on-screen scan, GATT listing, ELM test, LittleFS log) were removed 2026-10-23 — all in git history
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.

Car battery / idle

Cheap ELM327 clones draw ~20–50 mA permanently (OBD pin 16 = always 12 V); the display ~180 mA if its USB stays powered. 12-OBD-Speed idle mode stops OBD polling after N min without data so the car's ECUs can sleep; ATRV (adapter-internal) every 30 s detects an engine start (> 13.2 V).

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). Verified in the car (2026-10-23, with the since-removed BLE scanner tool; log in 12-OBD-Speed/docs/2026-10-23_ble_scanner_car_test.txt):

  • BLE name OBDII, MAC 1c:a1:35:69:8d:c5, advertises service 0xFFF0. Characteristics: FFF1 [W, WnR, Notify], FFF2 [W, WnR]. Working setup: subscribe to notifications on FFF1, write commands ("... ") to FFF1 (write without response) — FFF2 is the usual write characteristic on such clones and should work too.
  • Replies: ATZ → ELM327 v2.1 (echo on by default → send ATE0), ATRV → 12.9V, 0100 → 41 00 BE 3E A8 13.
  • Supported PIDs 01–20 (from BE 3E A8 13): 01 monitor status, 03 fuel system, 04 engine load, 05 coolant temp, 06/07 fuel trim B1, 0B intake manifold pressure (MAP), 0C RPM, 0D speed, 0E timing advance, 0F intake air temp, 11 throttle, 13 O2 sensors, 15 O2 sensor 2, 1C OBD standard, 1F run time, 20 → more PIDs in 21–40. No 10 (MAF) → speed-density engine.
  • Adapter is powered from the car's OBD port (pin 16, 12 V).

User's car

Ford Fiesta Mk8, 2018 (pre-facelift), EcoBoost, automatic, EU, radar ACC; dashboard shows speed signs (traffic sign recognition). User wants (2026-11-02) ACC set speed + speed-limit sign on the puck. Choices: no direct CAN wiring (option C rejected), FORScan possible but not preferred, over-limit warning = a setting (tolerance), items hidden when no data. Test drive 1 (2026-11-02, CAN logger, 12-OBD-Speed/docs/canlog): NO broadcast frames on the OBD port - every ATMA window (wildcard-filtered survey 0XX..7XX) answered NO DATA, only diagnostic replies come through: the gateway passes only diagnostics. Adapter accepted ATCSM1, ATCRA with wildcards, protocol A6. User does not want to use FORScan (2026-11-08). Next: read-only UDS 0x22 DID scan built into the log page (2026-11-08, flashed, not yet run in the car): unfiltered listen check, module discovery 0x700-0x7EF, then all DIDs of 0x706/0x764/0x720/0x7E0 + others, progress in NVS, runs during normal drives (user OK'd slower speed updates). Online search (2026-11-08): no published DIDs for Fiesta TSR / cruise set speed; FORScan forum TSR threads are about enabling TSR (IPMA write-protected); github.com/consp/ford-can-stuff has a Mk7.5 Fiesta broadcast-ID sheet (0x3CD Traffic Recognition Data on I-CAN) - broadcast only, not usable through the gateway. Candidate IDs from opendbc ford_lincoln_base_pt.dbc (newer Fords, only ~40 % of the file read verbatim — re-check bits): 0x165 Veh_V_DsplyCcSet 23|8 (+ CcStat_D_Actl 10|3), 0x202 Veh_V_RqCcSet 32|9 ×0.5 km/h, 0x3D9 IPMA_Data2 IsaVLim_D_Rq 7|8 (254 = no data), IsaVLimUnit_D_Rq 15|2 (1 kph, 2 mph), cycle 1 s / on change. Test drive 2 (2026-11-12, DID scan, 12-OBD-Speed/docs/canlog/scan): unfiltered ATMA = nothing (gateway confirmed). Discovery (22F188, 100 ms timeout) found only the PCM 0x7E0 (F188 = JB2B-14C204-ADA); 0x706/0x764/0x720 silent. PCM DIDs found in D000-D2BF: D002 1FFE, D003 80000000, D005/D006/D014 0, D015 87F840F8, D01A "UNKNOWN", D100 01, D127 140E, D134 00, D137 00. Scan rate only ~200 ms per DID (BLE + clone), PCM answers NRC 31 for unsupported. The PCM is promising anyway: per opendbc it receives IsaVLim_D_Rq (speed limit) and it runs the cruise control. Firmware after drive 2: probe again with 3E00 + 1 s timeout (once, NVS probed), 3 DIDs per request (single CAN frame, hits re-asked one by one; tested per module with 22F1FFF188F1FE), BLE interval 7.5-15 ms requested, E progress line every 512 DIDs with ms/DID. Flashed, not yet driven.

Future ideas (not started)

  • Web UI hosted by the puck (user's idea, 2026-11-12): WiFi access point / web server on the puck showing all the advanced data it can gather (OBD PIDs, the module/DID scan results, battery voltage history, ...) and maybe maintenance advice based on the data. Don't build yet — wait until the user asks. Notes for later: WiFi + BLE run together on the ESP32-S3 (shared radio, coexistence), but WiFi needs roughly 40-60 KB more internal RAM; 12-OBD-Speed has only ~23 KB free (see Internal RAM gotcha), so the draw buffers would probably have to shrink or move to PSRAM — only if the display stays smooth (screen has priority, see working agreement). Data/history could live on the SD card.

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 (10-GIF-Tests/*, 12-OBD-Speed). SD drive A: = LV_USE_FS_STDIO on /sdcard/.
  • 1 px offset with the panel's row mirror (MY): at 270° one edge line (near the USB port) showed random pixels at boot, then the far edge of the image once GRAM was cleared. So the image lands one line off when MY is set. Fix verified by the user (2026-10-24): setRotation() sets a 1 px gap on the axis MY mirrors (rot 3: setGapX(1), rot 2: setGapY(1) (assumed, not yet seen), rot 1 uses only MX: no gap). scr_lvgl_init() also clears GRAM to black at rotation 0 before the backlight comes on.
  • 80 MHz QSPI and RGB565_SWAPPED rendering: visually confirmed OK by the user (colors correct, no 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 setup() returns 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.
  • LittleFS works on the spiffs partition of huge_app.csv (~900 KB); the first mount after flashing formats it (prints Corrupted dir pair / mount failed (-84) and some task_wdt ... task not found once — harmless).
  • BLE (NimBLE) in the user's home: ~12 devices visible within 10 s.
  • Big fonts: generate with npx lv_font_conv (Node 22 installed) from lvgl/scripts/generators/built_in_font/Montserrat-Medium.ttf; -DLV_LVGL_H_INCLUDE_SIMPLE (in shared ini) makes the generated #include work.
  • GIF size after converting: upscaling with LANCZOS can make a GIF ~3x bigger (7.2 MB source 498x298 -> 24.9 MB), because blended pixels plus per-frame palettes with dithering break the delta compression. Nearest-neighbour scaling gave 7.2 MB and looked as good. tools/gif_to_360.py retries with sharp scaling automatically when the result exceeds 11.5 MB. --crop-x 0..1 moves the crop of wide GIFs (0 = left, 0.5 = center); 3d2c218d...gif is converted with --crop-x 0.36 (character is mostly left; best visible share inside the circle at 0.3-0.4).
  • Binary assets (GIFs): board_build.embed_files = data/x.gif → extern const uint8_t x_start[] asm("_binary_data_x_gif_start") (no huge C arrays).
  • Python edit scripts: never pass C strings containing \n through a bash heredoc into Python (happened 4 times now, also with <<'EOF') — it turned into a real line break twice; write the script with the Write tool instead.
  • Serial output from the background task (core 0) is often lost, not only right after reset; don't rely on it as proof. Serial output right after a reset can be lost/garbled (USB-CDC re-enumeration, prints from two cores interleave) — don't conclude a task isn't running from a missing early line.
  • Internal RAM in 12-OBD-Speed (2026-11-02): draw buffers 115 KB + UI 23 KB + NimBLE 58 KB left only ~10 KB, SD mounts failed with ESP_ERR_NO_MEM (0x101, sdmmc_read_blocks failed (257), DMA largest block 788 B) - looks like a card fault but isn't. Fix: heap_caps_malloc_extmem_enable(64) at the start of setup() -> ~23 KB free, 13.8 KB DMA block.
  • The black screen after pressing Start (2026-11-02) was the normal idle screen-off (2 min after boot without speed data), not a crash.
  • Preferences prints nvs_open failed: NOT_FOUND the first time a namespace is read before it was written — harmless.