# 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\" + 3.5\" (3248S035) selectable · 2.4\" / S3 Touch Soon · 3.5\" firmware only appears after `pio run -e cyd_35r` + export |
| Catalog | Searchable card grid · detail pane · HTML UI previews (sync sibling `firmware/*`) |
| 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.

Cards also offer a **Hardware** tab (sensor / module still). Mapping lives in `lib/sensor-media.ts`; images under `public/sensors/` (see `ATTRIBUTION.md`).

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**

完整账号、路径、Caddy、Cloudflare、排错与 AI 检查清单见 **[DEPLOY.md](./DEPLOY.md)**（含 SSH 密码与一键脚本说明）。

```powershell
npm run sync:firmware
npm run deploy
```

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 deploy` | Sync firmware + upload/build on production (`scripts/deploy_remote.py`) |
| `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
```

## Catalog snapshot (local)

After `npm run sync:firmware`, the flasher discovers every sibling package under `../**/firmware/<variant>/` that has the four bins. Current set includes sensor dashboards (climate / GY30 / SGP30 / LD2420), Pomodoro / photo album, plus module demos (buzzer, button, touch button, PIR, whistle, HW-069, HW-269, KY-009, LCD1602A, BLE, WiFi Prov).

## 中文说明

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

为固件增加封面：在对应 `firmware/<variant>/media/preview.html`（及可选 `meta.json`）即可，卡片用 HTML iframe 预览，无需改前端。

公网部署与服务器账号见 **[DEPLOY.md](./DEPLOY.md)**。本次仅更新本地，未部署公网。