TigerTag SDK JS
中文

JavaScript / Node.js SDKTigerTag SDK

用 JavaScript 读取、验证和写入 TigerTag NFC 芯片。

开放的 TigerTag 协议的 SDK，面向 3D 打印耗材与树脂：它把芯片上的字节解析为材料、颜色、打印参数和余量，离线验证其 ECDSA-P256 签名，并逐字节生成新标签。

npm install tigertag
快速开始 在 npm 上查看 GitHub 源代码
quick-start.js
const { TigerTag } = require('tigertag');

const tag = TigerTag.fromPages(uid, payload);   // from your NFC SDK
console.log(tag.pretty());                      // human-readable summary
console.log(String(tag.verify()));              // VALID / NOT SIGNED / INVALID
console.log(tag.toDict());                      // JSON-ready object
README 中的快速开始示例：npm install 之后即可运行，无需任何配置。
1.2.1当前版本，发布于 2026-11-06
Node.js 18+使用内置的 crypto 和 fetch
0解析和验证所需的运行时依赖
Apache-2.0开源许可证，含专利授权

三步上手

安装软件包，用你的 NFC 库读取芯片，再写入新芯片。内置的参考数据表让首次运行无需联网。

  1. 1

    安装软件包

    从 npm 仓库安装。pnpm、yarn 和 bun 安装的是同一个软件包。

    npm install tigertag
    pnpm add tigertag
yarn add tigertag
bun add tigertag
  2. 2

    读取芯片

    传入 7 字节 UID 和 NFC 库读取的 144 字节。此处示例使用 nfc-pcsc 和 ACR122U。

    // Node.js — nfc-pcsc (ACR122U / PN532)
reader.on('card', async (card) => {
  const uid = Buffer.from(card.uid, 'hex');        // 7 bytes
  const payload = await reader.read(4, 144, 4);    // pages 4–39, 144 bytes
  const tag = TigerTag.fromPages(uid, payload);
  console.log(tag.pretty());
  console.log(String(tag.verify()));               // VALID / NOT SIGNED
});
  3. 3

    修改并写入

    每次修改都返回一个新的 TigerTag；toBytes() 给出要写回的字节。erase() 给出一个空白芯片。

    // Immutable surgical update — returns a new TigerTag, original unchanged
const patched = tag.patch({ nozzleTempMin: 200, dryTemp: 55 });

// Erase a chip — write the returned 80 bytes to the NFC chip
const blankBytes = TigerTag.erase();

README 中的完整 API

SDK 能做什么

一个软件包覆盖 TigerTag 芯片的各个方面：读取、校验、写入，并保持数据最新。

读取任何转储

fromPages()、fromDump() 和 fromFile() 接受 UID 加 80 或 144 字节，或完整的 180 字节转储。pretty()、describe()、toDict() 和 toRawDict() 返回文本、通俗的说明段落或可直接转为 JSON 的对象。

离线验证真伪

verify() 使用软件包内置的公钥，检查将芯片 UID 与产品数据绑定在一起的 ECDSA-P256 签名。结果为 valid、invalid、unsigned、no_key 或 no_uid。

创建和修改标签

create()、asInit()、patch() 和 erase() 生成芯片字节。TigerTag 对象不可变：patch() 返回新对象，并拒绝修改 idTigertag、idProduct、uid 或签名。

从产品目录生成

TigerTag.fromCatalog(productId) 根据官方产品目录生成完整的 TigerTag+；目录在首次使用时下载，并缓存在用户专属文件夹中。

与制造商同步

对于 TigerTag+ 芯片，rawApi()、diffApi() 和 patchFromApi() 获取品牌当前的产品数据，列出与芯片的差异并应用。

参考数据，离线优先

材料、品牌、外观、类型、直径和单位数据表随软件包提供。后台检查每天最多更新一次；offline: true 或 TIGERTAG_OFFLINE=1 表示完全不发起网络请求。

三种标签

SDK 可读写 TigerTag 协议 v2.2 的三种标签类型，适用于 NTAG213、NTAG215 和 NTAG216 芯片。

idProduct 0xFFFFFFFF

TigerTag (Maker)

所有字段都在芯片上，可完全离线读取。

idProduct 0x00000000

TigerTag Init

空白模板，可直接编程。TigerTag.asInit() 用于创建。

ECDSA-P256

TigerTag+

所有字段都在芯片上，另有一个产品 ID，可通过云端 API 获取制造商的更新。已签名的芯片可用 verify() 验证。

命令行与 Electron

软件包会安装 tigertag 命令，也可在 Electron 应用的主进程中运行。

tigertag 命令

以文本、JSON 或原始字段解析转储，并按需更新参考数据表。

# Parse a dump file
tigertag dump.bin

# JSON output
tigertag dump.bin --json

# Update the reference tables now (into the data dir)
tigertag update

在 Electron 应用中

在主进程中解析芯片，无需附带子进程。

// main.js — replace parseTigerTag() subprocess dependency
const { TigerTag, TigerTagDB } = require('tigertag');

function parseTigerTag(payload, uid) {
  const tag = TigerTag.fromPages(Buffer.from(uid), Buffer.from(payload));
  const db  = new TigerTagDB();
  return {
    dict: tag.toDict(db),
    raw:  tag.toRawDict(),
    sig:  tag.verify(db).toDict(),
  };
}

无需读卡器即可试用：Playground

由 SDK 自身提供的本地网页，可生成和解码 TigerTag 芯片并显示每个字节。无需 NFC 硬件。

  • SDK 输入与输出并排显示：create() 调用，以及 pretty()、describe()、verify() 和 toDict()。
  • 连接一个或多个 PC/SC 读卡器（如 ACR122U）时，芯片放上即被读取，Burn 会写入当前内容。
  • Playground 从不写入签名：只有经过认证的制造商才能签发签名。
npm run playground
# then open http://localhost:7432/tools/playground.html

# Enable live reader support (one-time install)
npm install ws nfc-pcsc

TigerTag 生态系统的一部分

SDK 实现了开放的 TigerTag 规范，与其他官方工具相互配合。

TigerTag RFID Connect

官方移动应用：使用手机内置 NFC 读写芯片。

App StoreGoogle Play

常见问题

如何安装 TigerTag JavaScript SDK？

运行 npm install tigertag，或 pnpm add tigertag、yarn add tigertag、bun add tigertag。需要 Node.js 18 或更高版本，解析和验证不需要其他软件包。

需要联网吗？

不需要。参考数据表和签名公钥都随软件包提供，因此读取和验证可离线完成。网络仅用于每日数据表检查、产品目录和 TigerTag+ 云端方法；offline: true 或 TIGERTAG_OFFLINE=1 可将其关闭。

支持哪些 NFC 芯片和读卡器？

TigerTag 使用 NTAG213、NTAG215 和 NTAG216 芯片（ISO 14443-3）。SDK 接收 NFC 库读取的 UID 和字节，因此不绑定任何读卡器；README 中示例使用 nfc-pcsc 和 ACR122U。

如何验证芯片是否为正品？

verify() 使用软件包内置的公钥，检查芯片基于其 UID 和产品标识的 ECDSA-P256 签名。返回 valid、invalid、unsigned（Maker 标签）、no_key 或 no_uid，无需调用服务器。

能写入芯片吗？

它负责生成字节：create()、patch()、asInit()、erase() 和 fromCatalog() 返回一个 TigerTag，其 toBytes() 就是 NFC 库要写入的内容。Playground 的 Burn 按钮会把它写入已连接读卡器上的芯片。

有 Python 版本吗？

有：TigerTag-SDK-Python 是同一 API 的 Python 移植版，两个 SDK 提供同一个 Playground 页面。

SDK 采用什么许可证？

Apache-2.0，包含明确的专利授权。实现 TigerTag 协议本身无需任何许可。

一条命令即可开始

npm install tigertag，然后调用 TigerTag.fromPages(uid, payload)。

在 npm 上查看