diff --git a/docs/guides/README.md b/docs/guides/README.md index 708947b..b54dd08 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -3,12 +3,27 @@ Task-oriented how-to guides (shorter and more targeted than [tutorials](../tutorials/README.md)). -> **TODO:** this section is scaffolding. Planned topics: +## Available + +- **[Buying pitfalls](./buying-pitfalls.md)** — the handful of wrong purchases + that only reveal themselves after delivery: chips, readers, PN532 modules, + the TigerScale screen, screws, filament for printed parts. +- **[Troubleshooting: symptom → cause](./troubleshooting.md)** — chip reading, + writing and verification problems, most frequent first, collected from real + cases. +- **[Buy and encode TigerTag chips](./buy-and-encode-chips.md)** — start to + finish: which chips, which reader, encoding from phone or desktop, Twin Tag + pairs, and encoding in series. +- **[Promote a chipless spool to a real chip](./promote-chipless-spool.md)** — + writing a TigerData / TigerData+ record onto a physical NTAG chip (desktop + + reader). +- **[Publish a public list link on TigerHub](./publish-list-on-tigerhub.md)** — + share a read-only inventory or wishlist as a `/list/` link; no app, no + account for the viewer. + +> **TODO:** more guides planned: > -> - How to buy / encode TigerTag chips -> - How to promote a chipless (digital) spool to a real chip > - How to migrate an existing spreadsheet inventory into your TigerSystem account -> - How to publish a public list link on TigerHub --- diff --git a/docs/guides/buy-and-encode-chips.md b/docs/guides/buy-and-encode-chips.md new file mode 100644 index 0000000..f0e1abc --- /dev/null +++ b/docs/guides/buy-and-encode-chips.md @@ -0,0 +1,81 @@ +# Buy and encode TigerTag chips + +The fastest way to make a spool intelligent, start to finish: get the right +chips, then write their identity. No account, no cloud, a few cents per spool. + +For the wrong purchases that only reveal themselves after delivery, read +[buying pitfalls](./buying-pitfalls.md) first — this guide assumes you bought +the right chips. + +## 1. Which chips to buy + +Any **NTAG213 / 215 / 216** (NFC Forum Type 2), **25 mm round sticker** +recommended. NTAG213 is the minimum — the 144-byte payload is sized to fit it +([the TigerTag chip](../concepts/tigertag-chip.md)). Buy from anywhere; nothing +official is required. + +> **Note:** planning **two chips per spool**? That's how factory spools ship — +> one on each side, so a reader always faces one. Write them as a pair (see +> step 4). + +## 2. Which reader to use + +| You have | Use | Best for | +|---|---|---| +| An NFC phone | [Tiger NFC Connect](../products/tigertag-connect.md) | Getting started, occasional writes — the reader is already in your pocket | +| A computer + a USB reader | Tiger Studio + ACR122U or [TigerPOD](../products/tigerpod.md) | Encoding in series, an inventory, a workshop | + +Everything below works **100 % offline**. + +## 3. Encode a chip from your phone + +1. Open Tiger NFC Connect and tap **Scan**. +2. Present the chip to the phone's antenna (Android: upper back; iPhone: top + edge). + - A **blank** chip → the app offers to write a new TigerTag. + - A chip already holding **non-TigerTag** data → the app offers to + **convert** it. (If it errors instead, wipe it blank with a generic NFC + app, then re-scan — see [troubleshooting](./troubleshooting.md).) +3. **Describe the filament** — material, brand, colour, aspect, diameter, and + the print settings: nozzle and bed temperature ranges, drying. The choices + come from the shared catalogue, so every compatible app reads the spool the + same way. +4. Tap **Make** and hold the phone to the chip until it confirms. +5. Stick the chip on the spool, and re-scan to check. + +> **Tip:** fill in the temperatures even if you know them by heart. The day a +> reader-equipped machine reads the tag on its own, it needs them — and a +> field you leave empty is a field nobody else will fill for a generic +> filament. + +## 4. Encode two chips as a pair (Twin Tag) + +For the full experience, put a chip on each side of the spool and write them +**together**, so they stay one spool for its whole life: + +- **On the phone** — use the **Dual Link** option at creation time. +- **On the desktop** — write both with two readers, or repair an unlinked pair + in Tiger Studio with **Link to twin Spool**. + +Writing the two chips one after another with a single reader may link them +temporarily, but the association is not guaranteed to survive a re-scan — write +them as a pair. + +## 5. Encode in series (desktop) + +Beyond three or four spools, Tiger Studio + an ACR122U (or a +[TigerPOD](../products/tigerpod.md)) is the practical route: prepare one +filament sheet, duplicate it, and encode spools one after another. This is also +where you burn a **chipless** [TigerData / TigerData+](../concepts/universal-filament-identity.md) +record onto a physical chip — the mobile app doesn't do that yet. + +## What you can't do this way + +You cannot produce a **TigerTag+ Certified** (signed) chip: the signature is +issued by certified manufacturers, and TigerTag holds the private key +([TigerTag+](../products/tigertag-plus.md)). Encoding at home always produces a +standard TigerTag — fully readable everywhere, just not signed. + +--- + +**▲ [Documentation index](../../README.md)** · **Related:** [Buying pitfalls](./buying-pitfalls.md), [The TigerTag chip](../concepts/tigertag-chip.md), [Your first smart spool](../tutorials/first-smart-spool.md), [Troubleshooting](./troubleshooting.md) diff --git a/docs/guides/buying-pitfalls.md b/docs/guides/buying-pitfalls.md new file mode 100644 index 0000000..f3d2d81 --- /dev/null +++ b/docs/guides/buying-pitfalls.md @@ -0,0 +1,88 @@ +# Buying pitfalls + +Everything in the ecosystem runs on cheap, widely available parts — that's the +point. The flip side: marketplace listings all look alike, and the wrong +variant only reveals itself **after delivery**. Every pitfall below cost a +real builder time or money; most were reported on the +[Discord](https://discord.gg/3Qv5TSqnJH). + +Read this **before** placing an order, not after. + +## Blank NFC chips + +| Buy | Avoid | Why | +|---|---|---| +| **NTAG213 / 215 / 216**, 25 mm round sticker recommended | Listings that only say "NFC 13.56 MHz" | That label also covers incompatible chips. Insist on the exact NTAG reference. | +| | **MIFARE Classic 1K** tags | Same frequency, different standard — it's what several printer vendors use for their own locked tags ([compatibility](../compatibility/README.md)). A blank one cannot hold a TigerTag. | +| | UID-changeable **"magic" chips** | The [TigerTag+](../products/tigertag-plus.md) trust model is anchored on the factory-locked UID. A spoofable UID defeats it — and a seller pushing "magic" chips for spool tagging is a red flag in itself. | +| | Pre-locked promotional tags | Some promotional NFC stickers ship **write-locked** and can never be encoded. | + +> **Note:** NTAG213 is the minimum — the 144-byte payload is sized to fit it. +> Official branded chips ship as NTAG215 so the chip can be reused as a plain +> NDEF object at end of life ([the TigerTag chip](../concepts/tigertag-chip.md)). + +Sticking a chip **on a metal surface**? A standard sticker goes dead on metal — +you need an *on-metal* (ferrite-backed) tag, which costs more. For a plastic or +cardboard spool, the standard sticker is fine. + +## USB desktop readers (ACR122U class) + +The ACR122U is the reference desktop reader — two of them power a +[TigerPOD](../products/tigerpod.md). The reader itself is a safe buy; how you +plug it is the trap: + +> **Warning:** on an **unpowered USB hub**, an ACR122U reads fine but **fails +> writes intermittently** — the most confusing failure mode there is, reported +> repeatedly by builders. Plug it directly into the computer, or use a powered +> hub. + +## PN532 modules (TigerScale builds) + +> **Warning:** *"Sealed USB-C-only PN532 dongles will not work with this +> board"* — the +> [Tiger-Scale-V3 README](https://github.com/TigerTag-Project/Tiger-Scale-V3)'s +> own words. You need bare **PN532 V3 modules with accessible header pins**. +> The sealed dongles look like the convenient option; they are the single most +> common wrong purchase of the build. + +Two more things to check on the listing photos: + +- The common red PN532 boards carry **two DIP switches** selecting the bus + (I²C / SPI / HSU). Wrongly set, the module is simply invisible — set them to + match the transport you flash. +- You need **two** modules for a TigerScale. + +## The TigerScale touchscreen: 3.5 vs 3.5B + +Both Waveshare variants are supported — they differ only in controllers: + +| | ESP32-S3-Touch-LCD-**3.5** | ESP32-S3-Touch-LCD-**3.5B** | +|---|---|---| +| Display controller | ST7796 (SPI) | AXS15231B (QSPI) | +| Touch controller | FT6336 (separate chip, I²C) | AXS15231B (integrated, I²C) | +| MCU / PSRAM / resolution | identical | identical | + +The **3.5B** was the original development target and is the nicer +architecture — but it is chronically **out of stock**. The plain **3.5** +performs just as well in practice (team-confirmed after user testing, on the +Discord). **Buy whichever you can find**; you select the variant at flash +time. + +## Screws: order them with the electronics + +The TigerScale build needs 2× M5×30 + 2× M4×30 (load cell), 4× M2×6 +(display) and M3 self-tapping screws (housing). In non-metric countries these +are genuinely hard to find in local hardware stores — a builder on the +Discord ended up assembling a separate parts order after discovering this +mid-build. One online order **together with the electronics** avoids the +wait. + +## Filament for the printed parts + +Do **not** print any part that sits between a reader and a chip in +carbon-fiber-filled filament (PLA-CF, PETG-CF): the conductive fibers disturb +the NFC field. Plain PLA or PETG works fine. + +--- + +**▲ [Documentation index](../../README.md)** · **Related:** [The TigerTag chip](../concepts/tigertag-chip.md), [TigerScale](../products/tigerscale.md), [TigerPOD](../products/tigerpod.md), [FAQ](../faq/README.md) diff --git a/docs/guides/promote-chipless-spool.md b/docs/guides/promote-chipless-spool.md new file mode 100644 index 0000000..512579d --- /dev/null +++ b/docs/guides/promote-chipless-spool.md @@ -0,0 +1,49 @@ +# Promote a chipless spool to a real chip + +You can manage a whole inventory with **no chips at all** — as +[TigerData or TigerData+](../concepts/universal-filament-identity.md) records, +the identity living purely in your account. When you're ready, "promoting" a +record means writing it onto a physical NTAG chip so the spool carries its own +identity, offline. + +## What you need + +- The chipless spool in your inventory (a **TigerData** or **TigerData+** + record). +- A blank **NTAG213 / 215 / 216** chip. +- **[Tiger Studio](../products/tiger-studio.md) + a USB reader** — an ACR122U + or a [TigerPOD](../products/tigerpod.md). + +> **Warning:** this one step is **desktop-only**. Tiger NFC Connect can write a +> tag you describe on the spot, but it cannot burn an existing chipless +> **record** onto a chip yet — that path runs through Tiger Studio and a reader. + +## Steps + +1. In Tiger Studio, open the chipless spool from your inventory. +2. Place the blank chip on the reader. +3. Write the record to the chip. The record keeps its catalogue identity — a + promoted TigerData+ stays identified. +4. Re-scan to confirm, and stick the chip on the spool. + +The moment the data lands on the chip, the record becomes a **TigerTag**: a +physical UID is now associated with the identity. A promoted **TigerData+** +becomes a **TigerTag+** (still identified, still not signed — see +[TigerTag+](../products/tigertag-plus.md)). + +## Two chips? Promote them as a pair + +If the spool will carry two chips, write both in the same operation so they +stay one spool — with two readers, or by repairing the pair afterwards with +**Link to twin Spool**. See +[Buy and encode chips](./buy-and-encode-chips.md#4-encode-two-chips-as-a-pair-twin-tag). + +## The reverse is always possible + +Chips are never write-locked. A promoted spool can be re-encoded, wiped, or +returned to a plain chipless record at any time — the identity is yours to move +between digital and physical. + +--- + +**▲ [Documentation index](../../README.md)** · **Related:** [Universal filament identity](../concepts/universal-filament-identity.md), [Buy and encode chips](./buy-and-encode-chips.md), [TigerPOD](../products/tigerpod.md), [Tiger Studio](../products/tiger-studio.md) diff --git a/docs/guides/publish-list-on-tigerhub.md b/docs/guides/publish-list-on-tigerhub.md new file mode 100644 index 0000000..ce02e73 --- /dev/null +++ b/docs/guides/publish-list-on-tigerhub.md @@ -0,0 +1,67 @@ +# Publish a public list link on TigerHub + +Share a read-only view of an inventory or a wishlist as a plain web link. +Whoever opens it needs **no app and no account** — just a browser. + +## What it is + +A public list link looks like: + +``` +https://tigersystem.io/list/ +``` + +It's a read-only snapshot served by [TigerHub](../products/tigerhub.md), the +ecosystem's web home. The `` is what makes the link work — anyone who +has it can view the list, so treat it like a shared password (see revoking, +below). + +## Publish a list + +The link is generated from the apps, not from the website — TigerHub only +displays what [Tiger Studio](../products/tiger-studio.md) or +[Tiger NFC Connect](../products/tigertag-connect.md) publish: + +1. In Tiger Studio or Tiger NFC Connect, open the inventory or wishlist you + want to share. +2. Generate a **share link** for it. +3. Copy the `https://tigersystem.io/list/` link and send it to anyone. + +The viewer opens it in any browser and sees the list read-only — they cannot +edit it, and nothing about your account is exposed beyond what the list shows. + +## Revoke a link + +A share link stays valid until you revoke it. Revoke it from the same place you +generated it (Tiger Studio / Connect) once you no longer want the list public — +after that, the old `/list/` URL stops resolving. + +> **Tip:** revoking then re-publishing produces a **new** token. If you shared +> the old link widely and want to cut access, revoking is the way — the old URL +> goes dead immediately. + +## Public link vs sharing with a friend + +Two different mechanisms, same source data: + +| | Public list link | Friend | +|---|---|---| +| Who can see it | anyone with the URL | a specific person you added | +| They need an account | no | yes (a TigerSystem account) | +| How | generate a `/list/` link | exchange **friend codes / invitations** | +| Good for | a Reddit post, a forum, a quick show-and-tell | an ongoing, mutual view between two makers | + +Friend codes and invitations are managed from the apps and from your account on +the web (`/account`). + +## What's behind it + +The published data comes from your TigerSystem account (a single shared Firebase +database that every app reads and writes); TigerHub is only the web surface that +renders the public view. Your account data is never public — only the specific +list you chose to publish. See +[Inventory & cloud sync](../concepts/inventory-and-cloud-sync.md). + +--- + +**▲ [Documentation index](../../README.md)** · **Related:** [TigerHub](../products/tigerhub.md), [Inventory & cloud sync](../concepts/inventory-and-cloud-sync.md), [Tiger Studio](../products/tiger-studio.md) diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md new file mode 100644 index 0000000..a0fec6f --- /dev/null +++ b/docs/guides/troubleshooting.md @@ -0,0 +1,88 @@ +# Troubleshooting: symptom → cause + +Chip reading, writing and verification problems, ordered from most to least +frequent. Start at your symptom, work down the checks in order — most of them +were collected from real cases on the +[Discord](https://discord.gg/3Qv5TSqnJH). + +For printer-link problems (a machine not appearing in Tiger Studio, a slot not +updating), see the per-vendor pages in [compatibility](../compatibility/README.md); +for purchases that fail by design, see [buying pitfalls](./buying-pitfalls.md). + +## The chip is not detected at all + +| Check | Detail | +|---|---| +| Is NFC on? | Android: Settings → Connections → NFC. iPhone: always on, nothing to enable. | +| Right antenna spot? | Android phones usually have the antenna in the **upper back**; iPhones read from the **top edge**. Sweep the phone slowly over the chip rather than holding one spot. | +| Case in the way? | A thick case, a magnetic mount plate or a metal ring blocks the field. Take the case off for the read. | +| Chip on metal? | A standard sticker goes dead on a metal surface — that needs an on-metal tag ([buying pitfalls](./buying-pitfalls.md)). | +| Chip damaged? | A fold, tear or puncture cuts the antenna trace. That chip is permanently dead — encode a fresh one. | +| Two chips in the field? | Two chips presented to one reader at the same time collide and neither reads. Separate them. (The two chips of a single spool sit on **opposite sides** precisely so a reader only ever sees one — [why two chips](../concepts/tigertag-chip.md).) | + +## The chip reads as blank / "Init" + +Not a fault: the chip is new. It carries the TigerTag Init marker and no data +yet. Encode it — [your first smart spool](../tutorials/first-smart-spool.md). + +## The chip reads, but the data is wrong + +The chip was encoded with the wrong values, or it came off another spool. +Chips are **never write-locked**: just re-encode it with the right data +([the TigerTag chip](../concepts/tigertag-chip.md)). + +## The phone reads fine, but the printer does nothing + +The chip is fine — what's missing is printer-side support. No printer reads +TigerTag chips by itself out of the box today (the one exception is the +Snapmaker U1 running the community firmware — see +[Snapmaker](../compatibility/snapmaker.md)); the filament data reaches the +six integrated brands **through Tiger Studio**. Check where your machine +stands in the [compatibility matrix](../compatibility/README.md). + +## TigerTag+ Certified verification fails + +| Cause | What to do | +|---|---| +| Stale reference data | Verification resolves against the shared reference database. Update the app / let it sync, then re-scan. | +| Data was rewritten after signing | **Expected behaviour.** Rewriting the signed area invalidates the signature; the chip stays fully readable — it is simply no longer certified ([TigerTag+](../products/tigertag-plus.md)). | +| Data was copied onto another chip | **By design.** The chip's factory-locked UID is part of what's signed — a clone can never verify. | + +Only the first row is fixable; the other two are the trust model doing its +job. + +## The write fails on a chip that already holds other data + +A blank chip writes first try; a chip that already carries **non-TigerTag +data** sometimes doesn't — reported on the Discord since August 2025. + +The app is designed to detect a non-TigerTag chip and offer to **convert** it. +If you get an error instead: + +1. wipe the chip back to blank with a generic NFC app (the community + workaround is "NFC Tools", iOS/Android), +2. re-scan — it now behaves like a factory-blank chip and the write goes + through. + +## A write fails midway + +- **Hold still.** Moving the phone or the chip during a write can interrupt it + and leave the chip in an inconsistent state — reported by builders, and + recoverable: a full re-encode brings the chip back. +- **ACR122U writing intermittently?** Check how it's powered — + [buying pitfalls](./buying-pitfalls.md#usb-desktop-readers-acr122u-class). + +## Still stuck? + +Ask in **#help-and-support** on the [Discord](https://discord.gg/3Qv5TSqnJH), +with the five things that make an answer possible: + +1. chip model (NTAG213/215/216, or unknown), +2. reader — phone model, ACR122U, TigerPOD, TigerScale, +3. app and version, +4. what you did, in order, +5. what the app showed, word for word (or a screenshot). + +--- + +**▲ [Documentation index](../../README.md)** · **Related:** [Buying pitfalls](./buying-pitfalls.md), [The TigerTag chip](../concepts/tigertag-chip.md), [Compatibility](../compatibility/README.md), [FAQ](../faq/README.md)