Skip to content

BUILDING.md

Latest commit

 

History

History
124 lines (96 loc) · 5.72 KB

BUILDING.md

File metadata and controls

124 lines (96 loc) · 5.72 KB
Raw

Building from source

Requirements

  • ESP-IDF v5.5.3 or later
  • The jsonnet Python package in ESP-IDF's Python environment (python -m pip install jsonnet after activating the IDF environment) — used by the LWDT device-tree generator

Build and flash

Boards are selected with an LWDT board ID; the ESP-IDF target and per-board sdkconfig defaults come from the board definition under boards/<vendor>/<model>/ (no set-target needed):

idf.py build -DLWDT_BOARD_ID=cyd/cyd28_ili9341_touch
idf.py -p /dev/ttyACM0 flash

Available board IDs:

Board LWDT board ID
CYD 2.8" ILI9341 cyd/cyd28_ili9341_touch
CYD-S3 2.8" ILI9341 cyd/cyd28s3_ili9341_touch
CYD 3.5" ST7796 cyd/cyd35_st7796_touch
Waveshare ESP32-S3 Touch LCD 2.0" waveshare/wvshr200_touch
Waveshare ESP32-P4 720×720 (default) waveshare/wvshr_p4_720_touch

The legacy short names still work via the BOARD environment variable (BOARD=cyd28 idf.py build). When switching boards, use a separate build directory per board (idf.py -B build_cyd28 ...) or run idf.py fullclean first. The generated sdkconfig lives in the build directory, named after the board.

Board wiring (pins, panel geometry, touch calibration) lives in each board's board.lwdt device-tree file and is turned into C macros at build time by components/lwdt. To tweak a pin, edit board.lwdt — no C changes needed.

To create a merged single-file binary (suitable for the web flasher):

idf.py merge-bin -o esp32-gh-dashboard-flash.bin

Output is in build/esp32-gh-dashboard-flash.bin, ready to flash to offset 0x0.

Configuration

Adjust via idf.py menuconfig → Dashboard Configuration:

Option Default Description
DASHBOARD_TIMEZONE CST6CDT,M3.2.0,M11.1.0 POSIX TZ string (US Central w/ DST)
DASHBOARD_REFRESH_HOUR 6 Hour of day to re-fetch stats (local time)
DASHBOARD_CYCLE_SEC 30 Seconds between screen transitions
GH_USERNAME (empty) Compile-time fallback username (optional)
GH_TOKEN (empty) Compile-time fallback classic token (optional)

GH_USERNAME and GH_TOKEN are only used if NVS is empty (i.e. provisioning has never run). Normally credentials are entered via the first-boot portal.

Common timezone strings:

CST6CDT,M3.2.0,M11.1.0   US Central
EST5EDT,M3.2.0,M11.1.0   US Eastern
MST7MDT,M3.2.0,M11.1.0   US Mountain
PST8PDT,M3.2.0,M11.1.0   US Pacific
UTC0                      UTC

Hardware

Part Details
Board Waveshare ESP32-P4-WIFI6-Touch-LCD-4B
Display 720×720 MIPI-DSI (ST7703 controller)
WiFi ESP32-C6 co-processor via SDIO
Flash 16 MB
PSRAM 32 MB HEX mode, 200 MHz

For ESP32-P4 + C6 chip-level notes (esp_hosted, SDIO, PSRAM, errata) see esp32-notes.

How it works

Traffic data is collected by the github-traffic-log companion GitHub Action, which runs daily and appends stats to CSV files. The dashboard fetches these on boot and at a configurable daily refresh hour.

  • latest.csv — last two days of per-repo traffic (views, clones, uniques)
  • totals.csv — cumulative all-time sums per repo
  • traffic.csv — full 14-day daily history per repo (used for the graph)
  • repo_config.csv — optional per-repo display flags (show, exclude_totals)

Repo names and descriptions come from the GitHub GraphQL API. GitHub's traffic API only retains 14 days — the CSV log provides permanent accumulation beyond that window.

Credentials (WiFi SSID/password, GitHub username and token) are entered via a captive-portal web form on first boot and stored in NVS flash. Subsequent boots skip provisioning and connect directly.

Project structure

main/
  main.c                                App entry point, scheduling, button handling
  board_*.c                             Per-board display/touch implementations
                                        (all compiled; LWDT compatible guards
                                        select the active one)
  board_interface.h                     Board abstraction (pixel, flush, dimensions)
  dashboard.c / .h                      Screen renderer
  github_api.c / .h                     GraphQL client for repo metadata
  traffic_csv.c / .h                    CSV fetcher and parser for traffic data
  font8x16.c / .h                       Bitmap font renderer
  Kconfig.projbuild                     menuconfig options
boards/
  <vendor>/<model>/board.lwdt           Device-tree hardware description (pins, panel)
  <vendor>/<model>/board.cmake          ESP-IDF target for the board
  <vendor>/<model>/sdkconfig.defaults   Per-board sdkconfig defaults
components/
  lwdt/                                 LWDT device-tree generator + drvfx runtime
  wifi_prov/                            First-boot captive portal provisioning (NVS)
  nordesems__esp-captive-portal/        DNS hijack + OS probe endpoint handling
  esp_lcd_st7703/                       ST7703 MIPI-DSI panel driver
partitions*.csv                         Flash layouts (selected per board)
releases/
  esp32-gh-dashboard-*-flash.bin       Pre-built merged binaries (flash to offset 0x0)