Repository navigation
Your first chip: a step-by-step tutorial with screenshots - #29
Merged
Merged
Conversation
docs/user-guide/first-chip.md walks one design (the UART receiver starter) from the start page to "Ready for expert review": the description, running the examples, why a value is what it is, planted mistakes and "Find examples for everything", and the build and layout; then what to do when an example fails, and where to go next. No AI is used, so it costs nothing. Screenshots taken from the local app at 2x and compressed (about 1.2 MB in all). Linked from the README and the user guide. Fixed on the way: Health said "Add examples to finish checking" for any design with a state machine, even fully checked, because the state-machine diagram counted as unfinished. Information-only cards (the diagram, "Find examples for everything") no longer count towards ready. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
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.
This adds a guided tutorial for newcomers. The existing docs explain each part on its own, but nothing walked someone through a whole project.
What
docs/user-guide/first-chip.md takes the UART receiver starter from the start page to Ready for expert review in about ten minutes. It uses no AI, so it costs nothing. There are 8 screenshots, taken from the running app.
The steps:
It ends with what to do when an example fails, and where to go next.
The tutorial is linked from the README (in the docs table and after the quick start) and from the top of the user guide.
The screenshots were taken at 2× from the local app with a script, then resized to 1600 px wide and compressed. Together they are about 1.2 MB.
Fixed on the way
Taking the screenshots exposed a bug: Health never said "Ready for expert review" for a design with a state machine. The UART receiver was fully checked — 6 of 6 examples passing on the gates, 20 of 20 cases tried, 34 of 34 mistakes caught, clean build — yet the heading said "Add examples to finish checking".
The cause: the "How it works" diagram counted as an unfinished check. Information-only cards (the state-machine diagram and "Find examples for everything") no longer count towards ready. The counter and FIFO in the release rehearsal have no state machine, which is why the rehearsal missed this. The last screenshot shows the fixed heading.
Checks
🤖 Generated with Claude Code