cydweb/README.md

CYD Flasher

Browser flasher for Cheap Yellow Display and related boards.

Stack: Next.js 15 · Web Serial · esp-web-tools · next-intl · Tailwind / shadcn-style UI

Locales	English (default) /en · 中文 /zh only when Chinese is detected (browser/OS Accept-Language, navigator.languages, Intl locale, or prior cookie)
Boards	CYD 2.8" available · 2.4" / 3.5" / S3 Touch shown as Soon
Catalog	Searchable card grid · detail pane · media-ready
SEO	generateMetadata, Open Graph, /sitemap.xml, /robots.txt
Flash	0x1000 bootloader · 0x8000 partitions · 0xe000 boot_app0 · 0x10000 firmware

Quick start (local)

cd c:\Users\dsx2016\Desktop\codes\cyd\cydweb
npm install
npm run dev

Open Chrome or Edge: http://localhost:3000 (redirects to /en).

1. Pick a board (only CYD 2.8" is active for now)
2. Browse / search the firmware catalog
3. Connect & flash and choose the serial port (CH340 / CP210x)

npm run build
npm start

Firmware discovery

Scans sibling projects by default:

../<project>/firmware/<variant>/{bootloader,partitions,boot_app0,firmware}.bin

Optional rich metadata next to the bins: meta.json (see below).

CYD_FIRMWARE_ROOT=C:\Users\dsx2016\Desktop\codes\cyd

After rebuilding a project, run its firmware\export_from_build.ps1, then click Refresh.

Extending a firmware (HTML UI preview / docs)

Preferred card preview: media/preview.html — HTML recreation of the on-device LVGL UI (320×240). Auto-detected if present.

Optional meta.json beside the .bin files:

{
  "boardId": "esp32-2432s028",
  "name": "CYD Pomodoro",
  "summary": "Short card blurb",
  "description": "Longer detail text",
  "tags": ["pomodoro", "touch"],
  "media": {
    "preview": "media/preview.html",
    "video": "media/demo.mp4",
    "docs": "docs/README.md"
  }
}

• Media paths are served via /api/firmware/.../media/... (only if the file exists).
• docs may also be an https:// URL.
• boardId values: esp32-2432s028 (active), esp32-2432s024, esp32-3248s035, esp32-s3-touch (UI reserved).

Without meta.json, the catalog still works from VERSION.txt + auto media/preview.html.

Public deploy (Docker + Caddy)

Production: https://cyd.smallzhiyuns.com
Server layout: /home/dsx2016/docker/cydweb + Caddy reverse proxy 127.0.0.1:3020.

npm run sync:firmware
# On server:
cd /home/dsx2016/docker/cydweb
docker compose up -d --build
# Reload Caddy after Caddyfile changes:
cd /home/dsx2016/docker/caddy && docker compose exec caddy caddy reload --config /etc/caddy/Caddyfile

NEXT_PUBLIC_SITE_URL=https://cyd.smallzhiyuns.com
CYD_FIRMWARE_ROOT=/app/firmware

Web Serial requires HTTPS (or localhost).

Scripts

Command	Description
npm run dev	Dev server (Turbopack)
npm run build	Production build
npm start	Serve production build
npm run sync:firmware	Copy sibling firmware/* into ./firmware
npm run lint	ESLint

Project layout

app/[locale]/          # SSR pages (en / zh)
app/api/firmware/      # list · manifest · .bin · media
components/            # board selector, catalog cards, detail
lib/boards.ts          # board catalog
lib/firmware.ts        # discovery + meta.json
messages/              # en.json · zh.json

中文说明

本机：npm run dev → http://localhost:3000 ，右上角切语言。先选板型（目前仅 2.8" 可用），再在卡片目录里选固件刷写。

为固件增加封面 / 动画 / 视频 / 文档：在对应 firmware/<variant>/ 下放 meta.json 与 media/ 文件即可，无需改前端代码。