DESKTOP-PUHFO60\dsx2016
937c0090d5
Prefer media/preview.html over raster covers so catalog cards mirror each LVGL screen. Co-authored-by: Cursor <cursoragent@cursor.com>
124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
Markdown
# 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)
|
||
|
||
```powershell
|
||
cd c:\Users\dsx2016\Desktop\codes\cyd\cydweb
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
Open **Chrome** or **Edge**: [http://localhost:3000](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)
|
||
|
||
```powershell
|
||
npm run build
|
||
npm start
|
||
```
|
||
|
||
## Firmware discovery
|
||
|
||
Scans sibling projects by default:
|
||
|
||
```text
|
||
../<project>/firmware/<variant>/{bootloader,partitions,boot_app0,firmware}.bin
|
||
```
|
||
|
||
Optional rich metadata next to the bins: `meta.json` (see below).
|
||
|
||
```env
|
||
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:
|
||
|
||
```json
|
||
{
|
||
"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`.
|
||
|
||
```powershell
|
||
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
|
||
```
|
||
|
||
```env
|
||
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
|
||
|
||
```text
|
||
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/` 文件即可，无需改前端代码。
|