Repository navigation
docs: add a prebuilt-firmware quick start and a proper README header - #49
Merged
Merged
Conversation
- Add an "English | 中文" switcher at the top of README.md and README_zh.md so the two link to each other. - Restructure Quick Start into two paths. New "Option A — Flash a Prebuilt Firmware" covers the no-toolchain route end to end: downloading the per-board image from the Releases page (with the board -> asset-name table and SHA256SUMS verification), installing and running tyutool, and configuring credentials over the serial CLI. The existing source build becomes "Option B". - Both READMEs get the same content; the Chinese one is a translation, not a copy. Facts verified against the source and the live release rather than assumed: the asset names match release v2.1.0 exactly, the serial CLI baud is 115200 (TuyaOpen/src/tal_cli/src/tal_cli.c:833), the cfg_* command list comes from src/app_cli_cmd.c, and the tyutool invocations use the real `tyutool write -d <chip> -f <file>` syntax with chip ids `t5ai` / `esp32s3`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- tyutool's GUI button is labelled **Flash**, not "Start" (docs/tyutool/getting-started.md:98). - `tyutool authorize` takes `-d <chip>`; only `reset` documents a default device, so pass it explicitly. - `/docs/tyutool/` -> `/docs/tyutool`: the site sets `trailingSlash: false` and emits `docs/tyutool.html` with no directory index. - Note that `<version>` in the asset name is the project version baked into the firmware (`1.0.0`), not the release tag, so readers don't hunt for `2.1.0`. - Add the missing `cfg_set_ws_token` to the command list. - `help` lists the `cfg_*` commands, not literally every command. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rebuild the top of README.md and README_zh.md as a centered hero block instead of a bare `# TClaw` line: - Hoist the banner image to the very top. It already existed but sat below the hardware table, so the first screen was plain text. - Centered title, a one-line positioning statement, and the existing tagline moved up from the body. - Two badge rows: release / license / build / top language (all live from GitHub), then platforms / docs / forum. - A nav row (Quick Start · Documentation · Supported Boards · Skills · Issues) and the English/中文 switcher. - The "Under Active Development" warning moves directly under the hero so it is still the first thing read after the header. Everything was verified rather than assumed: the four dynamic badge URLs were fetched and return real values (v2.1.0, Apache-2.0, passing, C 99.4%); every in-page anchor was harvested from GitHub's own rendered HTML of the published READMEs, including the CJK ones (`#-快速开始`, `#支持的硬件`, `#-技能skills开发`); and both headers were run through GitHub's markdown API to confirm markdown inside `<div align="center">` is processed and all 8 images and 7 badge links resolve. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The prebuilt-firmware section had grown into a full walkthrough — a six-row asset table, GUI field descriptions, per-OS install caveats and the complete cfg_* command list. That belongs on the docs site, which now carries all of it. The README keeps four numbered steps with just the commands that matter and links to https://tuyaopen.ai/docs/tclaw/quick-start-prebuilt-firmware for the detail. Roughly 90 lines down to 45 per language. The one thing added rather than removed: where PID, UUID and AuthKey actually come from. The old text said to set them but never said how to obtain them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Follows the docs-site change to teach GUI flashing only. The README's step 3 and 4 showed `tyutool write` and `tyutool monitor`, which would have left it demonstrating a CLI path the linked full guide no longer covers. Step 3 now describes the Firmware Flash page; step 4 points at the Serial Debug page as the terminal. The cfg_* commands are unchanged — those are the device's own console commands, not tyutool's. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- The Docs badge and the Documentation nav link pointed at /docs/tclaw, which is a 404 — that category has no index.md, so it has no root route. The TClaw overview lives at /tclaw (what sidebars.js and the site navbar both use). Fixed in all four places across the two files; verified /tclaw and /zh/tclaw return 200 while /docs/tclaw and /zh/docs/tclaw return 404. - The flash step still said to pick the chip before the serial port and implied the chip is chosen manually. tyutool auto-fills chip and baud once a port is selected (docs/tyutool/getting-started.md). The docs-site page was corrected for this earlier; the README had been missed, so the two disagreed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reverts 3a6c627. The warning block is back in both READMEs, in its original position directly under the hero. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
shiliu-yang
approved these changes
Aug 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two things: a proper README header, and a no-toolchain path for getting a board running.
Companion docs-site PR: Tuya-Community/TuyaOpen.io#261
Header
The first screen was a bare
# TClawand a line of text — while the banner imagealready existed, buried below the hardware table. It is now a centered hero: banner,
title, positioning line, two badge rows (release / license / build / language, then
platforms / docs / forum), a nav row, and an English · 中文 switcher. The two
READMEs now link to each other.
Quick Start, split in two
Option A — Flash a Prebuilt Firmware is new: download the per-board image from
Releases, get your Tuya credentials, flash with the tyutool desktop app, configure
over the device's serial console. Four steps and the commands that matter; the full
walkthrough lives on the docs site.
Option B — Build from Source is the previous content, unchanged apart from
heading levels.
Verification
Facts were taken from source and the live release rather than assumed:
v2.1.0exactly;<version>in the filename is thefirmware's project version (
1.0.0), not the release tag.TuyaOpen/src/tal_cli/src/tal_cli.c:833.cfg_*commands and the channel-mode list come fromsrc/app_cli_cmd.c.auto-fills chip and baud.
checked against the actual headings, including the CJK ones.
A review pass caught two things worth naming: the Docs badge and Documentation link
originally pointed at
/docs/tclaw, which is a 404 (that category has no index, theoverview is at
/tclaw); and the flash step had chip-before-port, contradicting bothtyutool's docs and the companion docs page. Both fixed.
🤖 Generated with Claude Code