Skip to content

Restyle the hardware table as Qty / Component / Link - #3

Open
Ptitlouis6012 wants to merge 2 commits into
TigerTag-Project:mainfrom
Ptitlouis6012:docs/bom-table-style
Open

Restyle the hardware table as Qty / Component / Link#3
Ptitlouis6012 wants to merge 2 commits into
TigerTag-Project:mainfrom
Ptitlouis6012:docs/bom-table-style

Conversation

@Ptitlouis6012

Copy link
Copy Markdown
Contributor

Match the Tiger-Scale-V3 README's parts-table format: a Qty column, the component description folded into one cell, and a plain link column instead of prose links.

What this changes

Documentation only — no firmware, no hardware, no links added or removed. Same five parts, same three hardware/BOM.md links (board, PN532, USB-C cable), just laid out as Qty | Component | Link instead of Part | Notes.

What you tested it on

Docs only.

Checklist

  • One concern. A rename and a behaviour change in one diff cannot be reviewed.
  • English — comments, identifiers, log messages.
  • No credentials, keys or tokens added anywhere.
  • Any hardware constant carries a comment saying what breaks without it. (N/A — no hardware constant touched)
  • Docs updated if behaviour changed. (N/A — no behaviour changed; this is the docs update)
  • CHANGELOG.md updated for anything user-visible. Not touched: this is a visual change to the documentation, not user-visible device behaviour.

Match the Tiger-Scale-V3 README's parts-table format: a Qty column,
the component description folded into one cell, and a plain link
column instead of prose links. Same five parts, same links already in
hardware/BOM.md — only the presentation changes.

@BenGlut BenGlut left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this — the Qty | Component | Link shape is the right one, it does match Tiger-Scale-V3, and bash scripts/verify.sh --quick passes on the branch. I checked that rather than assuming it.

Two things need to come back before this can go in, and one to decide.

The DIP switch instruction

- | **PN532 NFC module**, V3 with DIP switches | Set to **HSU (UART)** — not I²C, not SPI. Both switches `0` / OFF. |
+ | 1 | PN532 **V3** NFC module — DIP switches, **HSU** mode required | [buy](...) |

"HSU mode required" states the requirement; "both switches 0 / OFF" is what someone holding the module actually does about it. That sentence is the only place in the README that says which position is HSU, and a reader with the board in one hand and the README in the other now has to go and find docs/WIRING.md to finish a ten-second job.

The charge-only cable

- | **A USB-C to USB-A cable that carries data** | Powers and flashes the board. A charge-only cable makes a working board look dead — no serial port ever appears. |
+ | 1 | USB-C to USB-A cable that carries data | [buy](...) |

This one is not a style note, it is a failure mode: a working board looks dead, and no serial port ever appears. It is the first thing that goes wrong for someone flashing their first ESP32, and the symptom points at the board rather than at the cable. Losing that sentence will cost somebody an evening and will arrive here as an issue.

The links, which is a genuine question rather than a fix

The table now carries the three Amazon links, and the line immediately under it still says "Parts, links and prices: hardware/BOM.md". That is the same list in two files. The day a link changes, one of them gets updated and the other quietly becomes wrong — and the wrong one is the one people read first.

Two ways out, both fine by me:

  • keep [buy] in the README and drop the "Parts, links and prices" line, so the README is the shopping list and BOM.md is the detail; or
  • keep the link column pointing at BOM.md sections rather than at Amazon, so there stays exactly one place a URL is written.

Your call — say which and I will not argue it.

Not a change request

The third column has no header (| Qty | Component | |). Deliberate, or worth a word in it?


To be concrete about what would land this: keep the new three-column layout, and put the two sentences above back into the Component cell. The cell is wide enough for them.

Review feedback: collapsing the parts table lost two load-bearing
sentences — which position the PN532's DIP switches for HSU, and what
a charge-only USB cable actually looks like (a board that boots but
never offers a serial port). Both are back, folded into the Component
cell instead of a separate Notes column.

Also drops the "Parts, links and prices: hardware/BOM.md" line now
that the table carries its own buy links directly, so the two files
don't each hold a copy that can drift. The separate "Full parts list"
line further down is untouched — it points at the fuller BOM.md
writeup, not at a duplicated link.
@Ptitlouis6012

Copy link
Copy Markdown
Contributor Author

Pushed 1a39689 — both sentences are back, folded into the Component cell:

  • PN532 row now reads "DIP switches, set to HSU (UART): both switches 0 / OFF"
  • USB cable row now reads "a charge-only cable makes a working board look dead, no serial port ever appears"

On the links question: went with your first option — kept [buy] in the table and dropped the "Parts, links and prices: hardware/BOM.md" line right under it, since that was the one repeating the same links. The separate "Full parts list: hardware/BOM.md" line further down (next to the Wiring links) is untouched — no URL lives there, just a pointer to the fuller writeup, so it isn't the duplication you flagged.

The blank third header is deliberate, not an oversight — copied straight from Tiger-Scale-V3's own README (| Qty | Component | |), so it stays that way here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants