|
| 1 | +# SPDX-FileCopyrightText: 2026 PN5180-tagomatic contributors |
| 2 | +# SPDX-License-Identifier: GPL-3.0-or-later |
| 3 | + |
| 4 | +"""Common types for different cards""" |
| 5 | + |
| 6 | +from typing import Protocol |
| 7 | + |
| 8 | + |
| 9 | +class UniqueId(Protocol): |
| 10 | + """Represents a cards unique identifier. |
| 11 | + Subtypes contain type specific extensions. |
| 12 | + """ |
| 13 | + |
| 14 | + def uid_as_bytes(self) -> bytes: |
| 15 | + """Returns the UID as bytes""" |
| 16 | + |
| 17 | + def uid_as_string(self) -> str: |
| 18 | + """Returns the UID as a string""" |
| 19 | + |
| 20 | + def __str__(self) -> str: |
| 21 | + """Returns a printable representation""" |
| 22 | + |
| 23 | + |
| 24 | +class Iso14443AUniqueId(UniqueId): |
| 25 | + """ISO/IEC 14443A card identifiers. |
| 26 | + It also includes the SAK response. |
| 27 | + """ |
| 28 | + |
| 29 | + def __init__(self, uid: bytes, sak: bytes): |
| 30 | + self._uid = uid |
| 31 | + self._sak = sak |
| 32 | + |
| 33 | + def uid_as_bytes(self) -> bytes: |
| 34 | + return self._uid |
| 35 | + |
| 36 | + def uid_as_string(self) -> str: |
| 37 | + return self._uid.hex(":") |
| 38 | + |
| 39 | + def sak_as_bytes(self) -> bytes: |
| 40 | + """The SAK response as bytes""" |
| 41 | + return self._sak |
| 42 | + |
| 43 | + def sak_as_string(self) -> str: |
| 44 | + """The SAK response as a string""" |
| 45 | + return self._sak.hex(":") |
| 46 | + |
| 47 | + def __str__(self) -> str: |
| 48 | + return f"UID: {self.uid_as_string()}, SAK={self.sak_as_string()}" |
| 49 | + |
| 50 | + |
| 51 | +# Add a class for ISO-15693 UIDs too |
| 52 | + |
| 53 | + |
| 54 | +class Iso15693UniqueId(UniqueId): |
| 55 | + """ISO/IEC 15693 card identifiers.""" |
| 56 | + |
| 57 | + def __init__(self, uid: bytes) -> None: |
| 58 | + self._uid = uid |
| 59 | + |
| 60 | + def uid_as_bytes(self) -> bytes: |
| 61 | + return self._uid |
| 62 | + |
| 63 | + def uid_as_string(self) -> str: |
| 64 | + return self._uid.hex(":") |
| 65 | + |
| 66 | + def __str__(self) -> str: |
| 67 | + return f"UID: {self.uid_as_string()}" |
| 68 | + |
| 69 | + |
| 70 | +class Card(Protocol): |
| 71 | + """Protocol for Cards""" |
| 72 | + |
| 73 | + @property |
| 74 | + def id(self) -> UniqueId: |
| 75 | + """Returns the card's unique id""" |
| 76 | + |
| 77 | + @property |
| 78 | + def memory_block_size(self) -> int: |
| 79 | + """How big the memory blocks are. |
| 80 | + This is the smallest unit that can be written |
| 81 | + and read from the card. |
| 82 | +
|
| 83 | + Raises: |
| 84 | + PN5180Error: If communication with the card fails. |
| 85 | + TimeoutError: If card does not respond. |
| 86 | + """ |
| 87 | + |
| 88 | + def read_memory(self, offset: int = 0, length: int = 128) -> bytes: |
| 89 | + """Read memory from the card. |
| 90 | +
|
| 91 | + Cards normally can only read blocks of fixed sizes so |
| 92 | + the returned memory region may be larger than the requested length. |
| 93 | + At the end of the cards memory, some cards wrap around, others |
| 94 | + stop responding. So the returned memory may be shorter as well. |
| 95 | +
|
| 96 | + Args: |
| 97 | + offset: Starting offset (default: 0). |
| 98 | + length: Number of bytes to read (default: 128). |
| 99 | +
|
| 100 | + Returns: |
| 101 | + All read memory as a single bytes object. |
| 102 | +
|
| 103 | + Raises: |
| 104 | + PN5180Error: If communication with the card fails. |
| 105 | + TimeoutError: If card does not respond. |
| 106 | + """ |
| 107 | + |
| 108 | + def write_memory(self, offset: int, data: bytes) -> None: |
| 109 | + """Write memory to a card. |
| 110 | +
|
| 111 | + Cards can only write blocks of a fixed size. |
| 112 | + The offset needs to start at an even such multiple |
| 113 | + and the data needs to be of the right length as well. |
| 114 | +
|
| 115 | + Args: |
| 116 | + offset: Starting page number (default: 0). |
| 117 | + data: 32-bit data to write to that page |
| 118 | +
|
| 119 | + Raises: |
| 120 | + PN5180Error: If communication with the card fails. |
| 121 | + TimeoutError: If card does not respond. |
| 122 | + MemoryWriteError: Other memory write failures. |
| 123 | + """ |
0 commit comments