tuyaopen-embedded-hardware

Files (31)

• SKILL.md
• README.md · references/lvgl/
• development.md · references/lvgl/
• simulator.md · references/lvgl/
• AUTHORING.md · references/peripherals/
• README.md · references/peripherals/
• onchip-adc.md · references/peripherals/
• onchip-dma2d.md · references/peripherals/
• onchip-gpio.md · references/peripherals/
• onchip-i2c.md · references/peripherals/
• onchip-kws.md · references/peripherals/
• onchip-pwm.md · references/peripherals/
• onchip-qspi.md · references/peripherals/
• onchip-rtc.md · references/peripherals/
• onchip-spi.md · references/peripherals/
• onchip-timer.md · references/peripherals/
• onchip-uart.md · references/peripherals/
• onchip-vad.md · references/peripherals/
• onchip-watchdog.md · references/peripherals/
• peripheral-audio.md · references/peripherals/
• peripheral-button.md · references/peripherals/
• peripheral-camera.md · references/peripherals/
• peripheral-display.md · references/peripherals/
• peripheral-ir.md · references/peripherals/
• peripheral-joystick.md · references/peripherals/
• peripheral-led.md · references/peripherals/
• peripheral-leds-pixel.md · references/peripherals/
• peripheral-printer.md · references/peripherals/
• peripheral-sd.md · references/peripherals/
• peripheral-touch.md · references/peripherals/
• usr-board.md · references/peripherals/

SKILL.md (first lines)

# TuyaOpen Hardware Vibe Coding

## Shortcuts — `tuyaopen-cli hardware` / `tuyaopen-cli boards`

The `tuyaopen-cli hardware` group covers exactly the file reads/writes Steps
1–4 below describe — use it instead of reading/writing the JSON by hand where
it applies:

| Intent | Command |
|---|---|
| Read the confirmed hardware (Step 1 input) | `tuyaopen-cli hardware list-used --project-root <project>` |
| Render the board catalog index (Step 1's `board-context.md`) | `tuyaopen-cli hardware board-context --project-root <project>` (add `--write` to persist it) |
| Render the compact confirmed-hardware context block (what the host inlines into vibe prompts) | `tuyaopen-cli hardware confirmed-context --project-root <project>` |
| Record the confirmed selection (Step 3) — **device peripherals and plain-string on-chip ids only** | `tuyaopen-cli hardware set-used --project-root <project> --ids <id1,id2,...> --source vibe` |
| Reverse-derive used peripherals from already-authored source (code written outside vibe coding) | `tuyaopen-cli hardware scan-used --project-root <project>` |
| (Re)write `.vscode/c_cpp_properties.json` for the project's platform/SDK | `tuyaopen-cli hardware intellisense --project-root <project>` |
| Browse the **published board catalog** (used by `project create --board`, not this project's board) | `tuyaopen-cli boards list` / `tuyaopen-cli boards detail --id <id>` |

> **No CLI?** No `tos.py` equivalent for `hardware`/`boards` — hand-read /
> hand-write `.tuyaopen/used-peripherals.json` and `.tuyaopen/board-context.md`
> directly, exactly as Steps 1–4 below describe. See skill `tuyaopen-start`
> § 7.

All `hardware` subcommands are read-only except `set-used` and `intellisense`
(both **P2** — need `--yes`, or `--dry-run` to
preview; see skill `tuyaopen-start` § 4).

**⚠ `hardware set-used --ids` cannot record on-chip pin occupancy.** Verified
against `src/cli/commands/hardware.ts` + `src/core/hardware/usedPeripherals.ts`:
`--ids` writes a flat list of bare-string ids only. Step 3 below requires an
**object** form for on-chip entries — `{ "id": "onchip:uart2", "pins": [...] }`
— so the Hardware IO diagram can mark the occupied GPIOs; the CLI command has
no flag for that shape. When any confirmed peripheral is on-chip with pins to
record, skip `hardware set-used` and full-overwrite
`.tuyaopen/used-peripherals.json` directly with a file-write tool, exactly as
Step 3 describes. `hardware set-used` is safe to use only when every id in the
set is a bare device/on-chip id with no pins to record.

`hardware board-context`/`confirmed-context` read `.tuyaopen/ide/board.json`
for **this project's already-selected board** — they are unrelated to
`tuyaopen-cli boards list/detail`, which reads the **published manifest
catalog** (the same one `tuyaopen-cli project create --board <id>` picks from).
Don't confuse the two: a custom board you add via the `tuyaopen-start` routing table
will never show up in `tuyaopen-cli boards list` — that command doesn't read the
SDK's `boards/` source tree at all.

Full flags: `tuyaopen-cli hardware --help` / `tuyaopen-cli schema get --group
hardware --command <cmd>` — don't hardcode the flag list here (skill
`tuyaopen-start` § 5).

## Architecture

TDD (driver registration) → TDL (device management) → App (business logic).

`board_register_hardware()` registers **only the device peripherals the board
already adapted** — the ones listed in `board-context.md`. For those, do not
write TDD code. Any peripheral the user **attaches themselves** (not in
`board-context.md`) you must register yourself in **`usr_board`**, **even when
the SDK already ships its TDD driver** — you just call that existing driver with
your pins. Writing a brand-new TDD driver (IC with no SDK driver) is only a
sub-case of `usr_board`, never the trigger for it. On-chip peripherals are the
other exception (call `tal_*`/`tkl_*` directly). See Rules.

## Read these files first (your hardware context)

This skill is the authority. Read these yourself before doing anything:

1. **`.tuyaopen/used-peripherals.json`** — the **already-confirmed** hardware
   (device `ID:`s and/or `onchip:<type><n>`s). This is your **INPUT**: generate
   code for exactly these. Empty/missing → nothing confirmed yet.
2. **`.tuyaopen/board-context.md`** — a slim **index** of the board's **device**
   peripherals (display/camera/led/button/audio/touch/printer/…): each device's
   `ID:`, enable `Kconfig:`, grouping, and per-group registration semantics. Raw
   per-device data (pins / driver IC / resolution / timing) is **not** here —
   read it from `.tuyaopen/ide/board.json` (the same JSON, full detail).
3. **`.tuyaopen/ide/platform.json` → `peripherals`** — **on-chip** support + specs
   (uart/gpio/pwm/i2c/spi/qspi/adc/timer/watchdog/rtc/dma2d/vad/kws). For each type:
   - **`enabled`** — does this SoC support it. If **`false`**, do NOT generate code
     for it; tell the user it's unsupported on this platform.
   - **`count`** + **`spec`** — instance count and valid config (ports, pins, ranges,
     enums). Read these instead of hardcoding; values differ per platform.
   Consult before writing any on-chip code.
4. **`.tuyaopen/ide/board.json` → `expansionPins`** — the **only pins the developer
   may freely wire** (the board's broken-out pins), each with the `functions` it can mux
   to (`GPIO`, `UART2_TX`, `I2C1_SCL`, …). This — **not** the full SoC pinout — is the
   basis for "available pins". **Empty/absent → the board is sealed: there are NO free
   pins**; you can only use already-wired onboard peripherals.

## Rules (must follow)

- **Confirm before code (hard gate).** Generate code ONLY for hardware listed in
  `used-peripherals.json`. If the request needs something not yet confirmed, or the
  catalog has multiple matches / any `## group —`, **ASK the user which one and
  wait** — never auto-pick. When asking the user to choose, **prefer an interactive
  multiple-choice prompt if your tooling supports one** (otherwise list the options as text).
- **Record before code.** As soon as the selection is settled, **full-overwrite**
  `used-peripherals.json` (Step 3) BEFORE writing any code; update it if the set changes.
- **Pick user-peripheral pins from `expansionPins` only.** When you choose a pin for a
  user/on-chip peripheral or a usr_board device, pick a `gpio` from
  `board.json.expansionPins` whose `functions` include the role you need (e.g. a UART2
  TX pin must list `UART2_TX`; a plain output needs `GPIO`). Never pick a pin that is not
  in `expansionPins` — it isn't physically accessible. If `expansionPins` is empty/absent,
  tell the user the board exposes no free pins and you cannot wire an external peripheral.
- **"串口 / serial / UART" is ambiguous → ASK first.** It may mean the debug/log
  console (`PR_*` — often a USB-serial the PC already sees; **no** peripheral, nothing
  recorded) OR a dedicated user UART (`tal_uart` on its own instance + pins —
  `onchip:uart<N>`). Do NOT assume `PR_*`; ask which before writing code.
- **Where a device peripheral registers — decide by ADAPTATION, not by "does
  the SDK have a driver".** A catalogued device peripheral **in
  `board-context.md`** is board-adapted → `board_register_hardware()` registers
  it; write no TDD code and no `CONFIG_ENABLE_*`. A device peripheral the user
  **attaches externally** (NOT in `board-context.md`) → you register it yourself
  in **`usr_board`**, reusing the SDK's existing TDD driver (e.g. an extra GPIO
  button → call `tdd_gpio_button_register` from `usr_register_hardware()`). The
  SDK shipping the driver does **not** mean `board_register_hardware()` wires
  *your* hardware — it only wires what the board adapted. **Rule of thumb: any
  peripheral you wire on yourself goes through `usr_board`.**
- **Device vs on-chip.** A part with a TDD/TDL driver (button, led, display,
  audio, touch, …) is a **device** — even on a plain GPIO pin — so it follows
  the device path above (board-adapted → `board_register_hardware()`; external →

From tuya/tuyaopen-ide-manifests, Apache-2.0.

More from tuya/tuyaopen-ide-manifests