# 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` |
| 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 (media / docs)

Create `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": {
    "cover": "media/cover.webp",
    "animation": "media/preview.gif",
    "video": "media/demo.mp4",
    "docs": "docs/README.md"
  }
}
```

- Relative 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`.

## Public deploy

Web Serial requires **HTTPS** (or localhost).

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

```env
NEXT_PUBLIC_SITE_URL=https://your-domain.example
```

Then `npm run build && npm start` (or any Next.js host). `firmware/` mirror is gitignored.

## 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/` 文件即可，无需改前端代码。