amiibo-reader 0.1.0__py3-none-any.whl

amiibo_reader/__init__.py

@@ -0,0 +1,11 @@
+from .amiibo import Amiibo, AmiiboSeries
+from .read_tag import close_reader, read_tag
+from .unknown_tag import UnknownTag
+
+__all__ = [
+    "Amiibo",
+    "AmiiboSeries",
+    "UnknownTag",
+    "read_tag",
+    "close_reader",
+]

amiibo_reader/amiibo.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class AmiiboSeries(StrEnum):
+    ANIMAL_CROSSING = "Animal Crossing"
+    DARK_SOULS = "Dark Souls"
+    DETECTIVE_PIKACHU = "Detective Pikachu"
+    DIABLO = "Diablo"
+    FIRE_EMBLEM = "Fire Emblem"
+    KIRBY = "Kirby"
+    MEGA_MAN = "Mega Man"
+    METROID = "Metroid"
+    MONSTER_HUNTER = "Monster Hunter"
+    PIKMIN = "Pikmin"
+    POWER_UP_BANDS = "Power-Up Bands"
+    SPLATOON = "Splatoon"
+    SUPER_MARIO = "Super Mario"
+    SUPER_MARIO_30TH = "Super Mario 30th"
+    SUPER_SMASH_BROS = "Super Smash Bros."
+    THE_LEGEND_OF_ZELDA = "The Legend of Zelda"
+    THE_LEGEND_OF_ZELDA_30TH = "The Legend of Zelda 30th"
+    THE_LEGEND_OF_ZELDA_BOTW = "The Legend of Zelda: Breath of the Wild"
+    THE_LEGEND_OF_ZELDA_LA = "The Legend of Zelda: Link's Awakening"
+    THE_LEGEND_OF_ZELDA_SS = "The Legend of Zelda: Skyward Sword"
+    THE_LEGEND_OF_ZELDA_TOTK = "The Legend of Zelda: Tears of the Kingdom"
+    THE_LEGEND_OF_ZELDA_TP = "The Legend of Zelda: Twilight Princess"
+    XENOBLADE_CHRONICLES = "Xenoblade Chronicles"
+    YOSHI_WOOLY_WORLD = "Yoshi's Wooly World"
+
+
+@dataclass(frozen=True)
+class Amiibo:
+    id: str
+    series: AmiiboSeries
+    character: str

amiibo_reader/amiibos.py

@@ -0,0 +1,119 @@
+from .amiibo import Amiibo, AmiiboSeries
+
+AMIIBOS: dict[str, Amiibo] = {
+    # Animal Crossing
+    # Not implemented yet
+    #
+    # Dark Souls
+    # Not implemented yet
+    #
+    # Detective Pikachu
+    # Not implemented yet
+    #
+    # Diablo
+    # Not implemented yet
+    #
+    # Fire Emblem
+    # Not implemented yet
+    #
+    # Kirby
+    # Not implemented yet
+    #
+    # Mega Man
+    # Not implemented yet
+    #
+    # Metroid
+    # Not implemented yet
+    #
+    # Monster Hunter
+    # Not implemented yet
+    #
+    # Pikmin
+    # Not implemented yet
+    #
+    # Power-Up Bands
+    # Not implemented yet
+    #
+    # Splatoon
+    # Not implemented yet
+    #
+    # Super Mario
+    # Not implemented yet
+    #
+    # Super Mario 30th
+    # Not implemented yet
+    #
+    # Super Smash Bros.
+    # Not completed yet
+    "0000000000000002": Amiibo("0000000000000002", AmiiboSeries.SUPER_SMASH_BROS, "Mario"),
+    "0002000000010002": Amiibo("0002000000010002", AmiiboSeries.SUPER_SMASH_BROS, "Peach"),
+    "0003000000020002": Amiibo("0003000000020002", AmiiboSeries.SUPER_SMASH_BROS, "Yoshi"),
+    "0008000000030002": Amiibo("0008000000030002", AmiiboSeries.SUPER_SMASH_BROS, "Donkey Kong"),
+    "0100000000040002": Amiibo("0100000000040002", AmiiboSeries.SUPER_SMASH_BROS, "Link"),
+    "0580000000050002": Amiibo("0580000000050002", AmiiboSeries.SUPER_SMASH_BROS, "Fox"),
+    "05C0000000060002": Amiibo("05C0000000060002", AmiiboSeries.SUPER_SMASH_BROS, "Samus"),
+    "0700000000070002": Amiibo("0700000000070002", AmiiboSeries.SUPER_SMASH_BROS, "Wii Fit Trainer"),
+    "0180000000080002": Amiibo("0180000000080002", AmiiboSeries.SUPER_SMASH_BROS, "Villager"),
+    "1919000000090002": Amiibo("1919000000090002", AmiiboSeries.SUPER_SMASH_BROS, "Pikachu"),
+    "1F000000000A0002": Amiibo("1F000000000A0002", AmiiboSeries.SUPER_SMASH_BROS, "Kirby"),
+    "21000000000B0002": Amiibo("21000000000B0002", AmiiboSeries.SUPER_SMASH_BROS, "Marth"),
+    "01010000000E0002": Amiibo("01010000000E0002", AmiiboSeries.SUPER_SMASH_BROS, "Zelda"),
+    "00090000000D0002": Amiibo("00090000000D0002", AmiiboSeries.SUPER_SMASH_BROS, "Diddy Kong"),
+    "00010000000C0002": Amiibo("00010000000C0002", AmiiboSeries.SUPER_SMASH_BROS, "Luigi"),
+    "06C00000000F0002": Amiibo("06C00000000F0002", AmiiboSeries.SUPER_SMASH_BROS, "Little Mac"),
+    "0740000000100002": Amiibo("0740000000100002", AmiiboSeries.SUPER_SMASH_BROS, "Pit"),
+    "0600000000120002": Amiibo("0600000000120002", AmiiboSeries.SUPER_SMASH_BROS, "Captain Falcon"),
+    "0004010000130002": Amiibo("0004010000130002", AmiiboSeries.SUPER_SMASH_BROS, "Rosalina"),
+    "0005000000140002": Amiibo("0005000000140002", AmiiboSeries.SUPER_SMASH_BROS, "Bowser"),
+    "1AC0000000110002": Amiibo("1AC0000000110002", AmiiboSeries.SUPER_SMASH_BROS, "Lucario"),
+    "0100010000160002": Amiibo("0100010000160002", AmiiboSeries.SUPER_SMASH_BROS, "Toon Link"),
+    "0101010000170002": Amiibo("0101010000170002", AmiiboSeries.SUPER_SMASH_BROS, "Sheik"),
+    "2101000000180002": Amiibo("2101000000180002", AmiiboSeries.SUPER_SMASH_BROS, "Ike"),
+    "22400000002B0002": Amiibo("22400000002B0002", AmiiboSeries.SUPER_SMASH_BROS, "Shulk"),
+    "3200000000300002": Amiibo("3200000000300002", AmiiboSeries.SUPER_SMASH_BROS, "Sonic"),
+    "3480000000310002": Amiibo("3480000000310002", AmiiboSeries.SUPER_SMASH_BROS, "Mega Man"),
+    "1F02000000280002": Amiibo("1F02000000280002", AmiiboSeries.SUPER_SMASH_BROS, "King Dedede"),
+    "1F01000000270002": Amiibo("1F01000000270002", AmiiboSeries.SUPER_SMASH_BROS, "Meta Knight"),
+    "21030000002A0002": Amiibo("21030000002A0002", AmiiboSeries.SUPER_SMASH_BROS, "Robin"),
+    "2102000000290002": Amiibo("2102000000290002", AmiiboSeries.SUPER_SMASH_BROS, "Lucina"),
+    "00070000001A0002": Amiibo("00070000001A0002", AmiiboSeries.SUPER_SMASH_BROS, "Wario"),
+    "1906000000240002": Amiibo("1906000000240002", AmiiboSeries.SUPER_SMASH_BROS, "Charizard"),
+    "22800000002C0002": Amiibo("22800000002C0002", AmiiboSeries.SUPER_SMASH_BROS, "Ness"),
+    "3340000000320002": Amiibo("3340000000320002", AmiiboSeries.SUPER_SMASH_BROS, "Pac Man"),
+    "1B92000000250002": Amiibo("1B92000000250002", AmiiboSeries.SUPER_SMASH_BROS, "Greninja"),
+    "07420000001F0002": Amiibo("07420000001F0002", AmiiboSeries.SUPER_SMASH_BROS, "Palutena"),
+    "0741000000200002": Amiibo("0741000000200002", AmiiboSeries.SUPER_SMASH_BROS, "Dark Pit"),
+    "05C00100001D0002": Amiibo("05C00100001D0002", AmiiboSeries.SUPER_SMASH_BROS, "Zero Suit Samus"),
+    "01020100001B0002": Amiibo("01020100001B0002", AmiiboSeries.SUPER_SMASH_BROS, "Ganondorf"),
+    "0000010000190002": Amiibo("0000010000190002", AmiiboSeries.SUPER_SMASH_BROS, "Dr. Mario"),
+    "0006000000150002": Amiibo("0006000000150002", AmiiboSeries.SUPER_SMASH_BROS, "Bowser Jr."),
+    "06400100001E0002": Amiibo("06400100001E0002", AmiiboSeries.SUPER_SMASH_BROS, "Olimar"),
+    #
+    # The Legend of Zelda
+    # Not implemented yet
+    #
+    # The Legend of Zelda 30th
+    # Not implemented yet
+    #
+    # The Legend of Zelda: Breath of the Wild
+    # Not implemented yet
+    #
+    # The Legend of Zelda: Link's Awakening
+    # Not implemented yet
+    #
+    # The Legend of Zelda: Skyward Sword
+    # Not implemented yet
+    #
+    # The Legend of Zelda: Tears of the Kingdom
+    # Not implemented yet
+    #
+    # The Legend of Zelda: Twilight Princess
+    # Not implemented yet
+    #
+    # Xenoblade Chronicles
+    # Not implemented yet
+    #
+    # Yoshi's Wooly World
+    # Not implemented yet
+    #
+}

amiibo_reader/read_tag.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .amiibo import Amiibo
+from .amiibos import AMIIBOS
+from .unknown_tag import UnknownTag
+
+if TYPE_CHECKING:
+    from mfrc522 import MFRC522  # type: ignore[import-untyped]
+
+reader: MFRC522 | None = None
+
+
+def _get_reader() -> MFRC522:
+    global reader
+
+    if reader is None:
+        from mfrc522 import MFRC522  # type: ignore[import-untyped]
+
+        reader = MFRC522(bus=0, device=0, spd=1000000, pin_mode=10, pin_rst=22)
+
+    return reader
+
+
+def close_reader() -> None:
+    global reader
+
+    if reader is not None:
+        reader.Close()
+        reader = None
+
+
+def _read_ntag_page(page: int) -> list[int] | None:
+    reader = _get_reader()
+
+    command = [0x30, page]
+
+    crc = reader.CalulateCRC(command)
+    command += crc[:2]
+
+    reader.WriteReg(reader.BitFramingReg, 0x00)
+
+    status, data, _ = reader.MFRC522_ToCard(reader.PCD_TRANSCEIVE, command)
+
+    if status != reader.MI_OK:
+        return None
+
+    return data
+
+
+def _anticoll_level(level: int) -> list[int] | None:
+    """
+    Performs ISO14443A anticollision.
+    This function is used to retrieve the UID of a tag at a specific level (1 or 2).
+
+    level 1 = 0x93
+    level 2 = 0x95
+    """
+
+    reader = _get_reader()
+
+    command = [level, 0x20]
+
+    reader.WriteReg(reader.BitFramingReg, 0x00)
+
+    status, data, _ = reader.MFRC522_ToCard(reader.PCD_TRANSCEIVE, command)
+
+    if status != reader.MI_OK:
+        return None
+
+    if len(data) != 5:
+        return None
+
+    # BCC (Block Check Character) is the XOR of the first 4 bytes of the UID.
+    bcc = data[0] ^ data[1] ^ data[2] ^ data[3]
+
+    if bcc != data[4]:
+        print("Invalid BCC")
+        return None
+
+    return data
+
+
+def _select_level(level: int, uid_part: list[int]) -> bool:
+    """
+    Selects an ISO14443A UID level.
+
+    uid_part = 5 bytes:
+    - level 1: 88 + 3 bytes UID + BCC
+    - level 2: 4 bytes UID + BCC
+    """
+
+    reader = _get_reader()
+
+    command = [
+        level,
+        0x70,  # SELECT
+        *uid_part,
+    ]
+
+    crc = reader.CalulateCRC(command)
+    command += crc[:2]
+
+    reader.WriteReg(reader.BitFramingReg, 0x00)
+
+    status, _, _ = reader.MFRC522_ToCard(reader.PCD_TRANSCEIVE, command)
+
+    return status == reader.MI_OK
+
+
+def _select_amiibo() -> bool:
+    """
+    Select an amiibo by performing anticollision and SELECT operations
+    for both UID levels.
+
+    Amiibo UIDs use two ISO14443A cascade levels, so both levels must
+    be processed before reading the NTAG215 data.
+    """
+
+    level1 = _anticoll_level(0x93)
+
+    if not level1:
+        print("Anticollision failed at level 1")
+        return False
+
+    if not _select_level(0x93, level1):
+        print("Select failed at level 1")
+        return False
+
+    level2 = _anticoll_level(0x95)
+
+    if not level2:
+        print("Anticollision failed at level 2")
+        return False
+
+    if not _select_level(0x95, level2):
+        print("Select failed at level 2")
+        return False
+
+    return True
+
+
+def _get_amiibo_id(data: list[int]) -> str:
+    """Extract the amiibo ID (first 8 bytes) from the tag data."""
+
+    return bytes(data[:8]).hex().upper()
+
+
+def read_tag() -> Amiibo | UnknownTag | None:
+    """
+    Read a tag and return the corresponding Amiibo object if recognized,
+    otherwise return an UnknownTag object. Returns None if no tag is detected.
+    """
+
+    reader = _get_reader()
+
+    status, _ = reader.Request(reader.PICC_REQIDL)
+
+    if status != reader.MI_OK:
+        return None
+
+    _, uid = reader.Anticoll()
+    uid = bytes(uid).hex().upper()
+
+    if not _select_amiibo():
+        return UnknownTag(uid)
+
+    data = _read_ntag_page(21)
+
+    if not data:
+        return UnknownTag(uid)
+
+    amiibo_id = _get_amiibo_id(data)
+
+    return AMIIBOS.get(amiibo_id, UnknownTag(amiibo_id))

amiibo_reader/unknown_tag.py

@@ -0,0 +1,6 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class UnknownTag:
+    id: str

amiibo_reader-0.1.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: amiibo-reader
+Version: 0.1.0
+Summary: Python library for reading amiibo tags using an MFRC522 NFC reader on Raspberry Pi
+Author: Pascal Béger
+License: MIT
+Project-URL: Homepage, https://github.com/p-beger/amiibo-reader
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mfrc522-python==0.0.9
+Dynamic: license-file
+
+# amiibo-reader
+
+Python library for reading amiibo tags with an MFRC522 RFID reader.
+
+The library detects NFC tags, reads amiibo data from NTAG215 tags, and identifies amiibo figures using a local amiibo database.
+
+`amiibo-reader` is an independant Python library for reading and parsing NFC data from amiibo tags. It is not affiliated with or endorsed by Nintendo.
+
+## Features
+
+- Read amiibo tags using an MFRC522 RFID reader
+- Read NTAG215 data
+- Extract amiibo IDs
+- Identify amiibo figures from the local database
+- Distinguish between recognized amiibo and unknown tags
+- Expose a small and simple Python API
+
+## How it works
+
+When a tag is placed on the MFRC522 reader:
+
+1. The reader detects the tag.
+2. The tag UID is retrieved.
+3. The library performs ISO14443A anticollision and selection.
+4. The NTAG215 data is read.
+5. The amiibo ID is extracted from the tag data.
+6. The amiibo ID is looked up in the local amiibo database.
+7. The corresponding `Amiibo` is returned if it is known.
+8. Otherwise, an `UnknownTag` is returned.
+
+If no tag is detected, `read_tag()` returns `None`.
+
+## Requirements
+
+- Python 3.13+
+- Raspberry Pi or another compatible Linux system
+- MFRC522 RFID reader
+- amiibo figures or compatible NTAG215 tags
+- SPI interface enabled
+
+The library uses the `mfrc522` Python package to communicate with the MFRC522 reader.
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone https://github.com/p-beger/amiibo-reader.git
+cd amiibo-reader
+```
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+If creating the virtual environment fails, make sure `python3-full` is installed:
+
+```bash
+sudo apt-get install python3-full
+```
+
+Install the library:
+
+```bash
+python -m pip install .
+```
+
+For development, install the development dependencies:
+
+```bash
+python -m pip install --group dev
+```
+
+## MFRC522 configuration
+
+The library currently uses the following MFRC522 configuration:
+- SPI bus: 0
+- SPI device: 0
+- SPI speed: 1 MHz
+- Reset pin: 22
+SPI must be enabled on the Raspberry Pi.
+
+The reader is automatically initialized when the library is imported.
+
+## Usage
+
+The main API is exposed directly from the `amiibo_reader` package:
+
+```python
+from amiibo_reader import close_reader, read_tag
+```
+
+Read a tag:
+
+```python
+tag = read_tag()
+
+if tag is None:
+    print("No tag detected")
+else:
+    print(tag)
+```
+
+## Recognized amiibo
+
+When the tag is recognized, `read_tag()` returns an `Amiibo` object:
+
+```python
+from amiibo_reader import Amiibo, read_tag
+
+tag = read_tag()
+
+if isinstance(tag, Amiibo):
+    print(f"ID: {tag.id}")
+    print(f"Series: {tag.series}")
+    print(f"Character: {tag.character}")
+```
+
+For example:
+```
+ID: 0000000000000002
+Series: Super Smash Bros.
+Character: Mario
+```
+
+## Unknown Tags
+
+If a tag is detected but cannot be identified as a known amiibo, `read_tag()` returns an `UnknownTag` object:
+
+```python
+from amiibo_reader import UnknownTag, read_tag
+
+tag = read_tag()
+
+if isinstance(tag, UnknownTag):
+    print(f"Unknown tag ID: {tag.id}")
+```
+
+The `id` contains the most relevant identifier available:
+- the tag UID if the amiibo data could not be read
+- the amiibo ID if the tag was successfully read but is not present in the local database
+
+## No tag detected
+
+If not tag is present:
+
+```python
+tag = read_tag()
+
+if tag is None:
+    print("No tag detected")
+```
+
+## Closing the reader
+
+When the reader is no longer needed, close it with:
+
+```python
+from amiibo_reader import close_reader
+
+close_reader()
+```
+
+## amiibo database
+
+The amiibo database is stored in `amiibos.py`.
+
+Each entry associates an amiibo ID with an `Amiibo` object.
+
+```python
+AMIIBOS: dict[str, Amiibo] = {
+    "0000000000000002": Amiibo(
+        "0000000000000002",
+        AmiiboSeries.SUPER_SMASH_BROS,
+        "Mario",
+    ),
+}
+```
+
+Additional amiibo can be added to the database by adding their amiibo ID, series and character.
+
+## Project structure
+
+```
+amiibo-reader/
+├── src/
+│   └── amiibo_reader/
+│       ├── __init__.py
+│       ├── amiibo.py
+│       ├── amiibos.py
+│       ├── read_tag.py
+│       └── unknown_tag.py
+├── .gitignore
+├── pyproject.toml
+└── README.md
+```
+
+## Development
+
+The project uses:
+- Ruff for formatting and linting
+- mypy for static type checking
+
+Format the code with Ruff:
+
+```bash
+ruff format .
+```
+
+Lint the code:
+
+```bash
+ruff check .
+```
+
+Run mypy:
+
+```bash
+mypy src
+```

amiibo_reader-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+amiibo_reader/__init__.py,sha256=rY_RHD52cVfVl4cTiGVTlyoK7e0s6N6dr_cX17c8XxQ,225
+amiibo_reader/amiibo.py,sha256=SFzUdw_Pa7e-LiwMRNAANyaYqMCoouOQVJ6WMdy7XIM,1220
+amiibo_reader/amiibos.py,sha256=ovBWci2xXw212oSScj_rRk2GbsZ2vVlv8AmEymgFVJo,5498
+amiibo_reader/read_tag.py,sha256=zBYFM9lRIXS4wVfOudilEXL3637V_2uqnqOV1OJ13sE,3823
+amiibo_reader/unknown_tag.py,sha256=1KSeXqlKCiZj4XejJCqEfxQ6GhSwpmAq9Hb4X2d7Eys,90
+amiibo_reader-0.1.0.dist-info/licenses/LICENSE,sha256=RQm_nUhBRXwOJHHnJObpKH3CYiK7Li-rZ1lfQazu3t8,1056
+amiibo_reader-0.1.0.dist-info/METADATA,sha256=tP6sKuyPm9fk78jU2PlsubXrdp5BZpkeNW0o5XRHSQA,4868
+amiibo_reader-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+amiibo_reader-0.1.0.dist-info/top_level.txt,sha256=MbW0CUU5HU-ypArty50r5lAC8APl4zTtnm8xmkDjE5E,14
+amiibo_reader-0.1.0.dist-info/RECORD,,

amiibo_reader-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

amiibo_reader-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Pascal Béger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

amiibo_reader-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+amiibo_reader