TigerTag Python SDK
Русский

SDK с открытым кодом · протокол TigerTag v2.2

TigerTag Python SDK

Читайте, проверяйте и записывайте NFC-чипы TigerTag на Python.

Пакет tigertag превращает 144 байта чипа TigerTag в материал, цвета, температуры и количество, проверяет его подпись ECDSA-P256 и создаёт новые метки. Справочные данные входят в пакет, поэтому всё работает без сети сразу после pip install.

Начать tigertag на PyPI Исходный код на GitHub 
pip install tigertag
from tigertag import TigerTag

tag = TigerTag.from_pages(uid, payload)        # from your NFC SDK
print(tag.pretty())                            # human-readable summary
print(tag.verify())                            # VALID / NOT SIGNED / INVALID
print(tag.to_dict())                           # JSON-ready dict
Быстрый старт в том виде, в каком он дан в README: uid и payload приходят от вашего NFC-считывателя.
1.4.0Последний выпуск ·
3.8+Python 3.8 и новее
0Зависимостей ядра во время работы: только стандартная библиотека
144Байт читается с чипа: страницы 0x04–0x27, данные и подпись

Начните за три шага

Пакет tigertag опубликован на PyPI. Установите его, передайте ему то, что возвращает NFC-считыватель, и проверьте подпись.

  1. 1

    Установка

    Одна команда. Ядро использует только стандартную библиотеку, справочные данные уже включены: никакой настройки и никакой сети при первом запуске.

    pip install tigertag
  2. 2

    Чтение чипа

    Передайте 7-байтовый UID и 144-байтовый payload из вашего NFC SDK. pretty(), to_dict() и validate() дают сводку, словарь, готовый для JSON, и предупреждения.

    from tigertag import TigerTag
tag = TigerTag.from_pages(uid, payload)
  3. 3

    Проверка подписи

    Дополнение verify добавляет пакет cryptography, и tag.verify() проверяет подпись ECDSA-P256 без сети с помощью открытого ключа, встроенного в SDK.

    pip install tigertag[verify]

Необязательные дополнения

sync добавляет requests (обновления уже работают на стандартной библиотеке), verify добавляет cryptography для подписей, full ставит оба, а nfc добавляет pyscard для PC/SC-считывателей в playground.

tigertag на PyPIБыстрый старт в README

pip install tigertag                    # core only — stdlib, works fully offline (data bundled)
pip install tigertag[sync]              # + requests (optional — updates use the standard library)
pip install tigertag[verify]            # + cryptography (ECDSA signature check)
pip install tigertag[full]              # everything
pip install "tigertag[nfc]"             # + pyscard (playground: ACR122U / PC/SC readers)

Подписи и структура чипа

Подписанный TigerTag несёт подпись ECDSA-P256, которая связывает UID чипа с данными продукта. SDK проверяет её без обращения к серверу.

tag.verify()

Возвращает SignatureResult: ok равно True только для действительной подписи, а status иначе объясняет причину (нет подписи, не установлен cryptography, нет открытого ключа, нет UID).

result = tag.verify()    # fully autonomous — finds the public key from the bundled DB

result.ok       # True only for VALID
result.status   # "valid" | "invalid" | "unsigned" | "no_crypto" | "no_key" | "no_uid"
str(result)     # "VALID" | "INVALID" | "NOT SIGNED" | "NO CRYPTO — …" | "NO PUBLIC KEY — …" | "NO UID — …"
result.to_dict()# {"status": "valid", "ok": True, "detail": "…"}
Подробнее в README

Что читает SDK

from_pages() принимает 144 байта (страницы 0x04–0x27, данные и подпись) или 80 байт (только данные). from_dump() также принимает полный 180-байтовый дамп и берёт из него UID.

Структура памяти NTAG-чипа TigerTag, страницы 0x04–0x27, поле за полем Спецификация TigerTag

Что умеет SDK

Всё, что описано в README, в одном пакете, работающем без сети.

Прежде всего без сети

Справочные таблицы и каталог TigerTag+ (около 1 МБ) входят в пакет. offline=True или TIGERTAG_OFFLINE=1 отключает любые сетевые запросы.

Проверка подписи

ECDSA-P256, полностью без сети, с открытым ключом из встроенного id_version.json. Установите tigertag[verify], чтобы добавить пакет cryptography.

Создание, изменение, стирание

TigerTag.create() создаёт метку с нуля, patch() возвращает новую метку с изменёнными полями, erase() возвращает 80 нулевых байт для стирания чипа. Попытка изменить UID или подпись вызывает ValueError.

Каталог TigerTag+

TigerTag.from_catalog() превращает идентификатор продукта TigerTag+ в полную метку, готовую к записи, по официальному каталогу. catalog_entry() даёт название, бренд, SKU и фото.

Обновление справочных данных

Первый TigerTagDB в процессе ищет новые данные не чаще раза в день и никогда не выбрасывает исключений: при любой ошибке используются локальные данные. tigertag update проверяет сразу.

Любой NFC SDK

from_pages(uid, payload) принимает то, что возвращают Android, iOS, Flutter и nfcpy. В README есть полный пример для считывателя ACR122U с nfcpy.

Командная строка и один файл

Команда tigertag разбирает дамп чипа, выводит его текстом, в JSON или сырыми полями и обновляет справочные данные.

tigertag dump.bin              # parse + human-readable output
tigertag dump.bin --json       # output as JSON
tigertag dump.bin --raw        # raw protocol fields, no DB lookup
tigertag update [--force]      # check for new reference data now (--catalog, --data-dir)
tigertag dump.bin --offline    # no network access at all
tigertag --version             # show SDK version

python -m tigertag dump.bin    # same, via module runner
Подробнее в README

Один файл, без пакета

parse_tigertag.py — полная автономная копия SDK для проектов, которым нельзя добавлять зависимости: положите файл в проект и импортируйте из него TigerTag.

parse_tigertag.py

Playground

Локальная веб-страница, которая создаёт, разбирает и проверяет метки с помощью этого SDK, без оборудования. Со считывателем ACS ACR122U или другим PC/SC она также читает и записывает настоящие чипы.

python3 tools/server.py 7432
Подробнее в README

Вопросы

Что такое TigerTag Python SDK?

Пакет Python, tigertag на PyPI, который читает, проверяет, создаёт и изменяет NFC-чипы TigerTag для филамента и смолы для 3D-печати. Он распространяется с открытым кодом по лицензии Apache 2.0 и реализует протокол TigerTag v2.2.

Как его установить?

Выполните pip install tigertag на Python 3.8 или новее. Добавьте tigertag[verify] для проверки подписей, tigertag[full] для всех необязательных зависимостей или tigertag[nfc] для PC/SC-считывателей в playground.

Нужно ли подключение к интернету?

Нет. Справочные данные входят в пакет, поэтому чтение и проверка работают без сети. Начиная с версии 1.3.0 SDK ищет новые справочные данные не чаще раза в день; offline=True, TIGERTAG_OFFLINE=1 или auto_update=False это отключает.

Какие чипы он читает?

NTAG213, NTAG215, NTAG216 и чипы, совместимые с ISO 14443-3, с тремя типами меток: TigerTag (Maker), TigerTag Init и TigerTag+. SDK читает все три одинаково.

Как он проверяет подлинность чипа?

tag.verify() проверяет подпись ECDSA-P256 чипа, которая связывает его UID с данными продукта, с помощью встроенного в пакет открытого ключа и без обращения к серверу. Нужен UID, поэтому читайте чип через from_pages(uid, payload).

Можно ли пользоваться им без установки пакета?

Да. parse_tigertag.py в корне репозитория — полная автономная копия: скопируйте файл в свой проект и импортируйте из него TigerTag.

Есть ли инструмент командной строки?

Да. tigertag dump.bin выводит читаемую сводку, --json выводит JSON, --raw — сырые поля протокола; tigertag update обновляет справочные данные, а python -m tigertag работает так же.

Прочитайте свой первый TigerTag на Python

pip install tigertag, затем TigerTag.from_pages(uid, payload).

tigertag на PyPI