TigerTag: read tag index and tag count

Read the tag index / tag count byte (offset +39, TigerTag spec v2.2):
the high nibble is the index of the tag that was read, the low nibble
is the number of tags on the item (0x12 = tag 1 of 2). 0 means unknown,
which is what every tag written before v2.2 contains.

- Add tag_index and tag_count to GenericFilament (default 0 = unknown),
  exposed in to_dict() and shown in pretty_text() when the count is known
- Add twin-tag fixtures (tag 1 of 2, tag 2 of 2) built from the eSun
  TigerTag+ dump, and check that the existing dump reads as unknown

Author: TigerTag-Project

src/filament/generic.py

@@ -26,7 +26,9 @@ def __init__(self,
                  drying_temp_c: float,
                  drying_time_hours: float,
                  manufacturing_date: str, # ISO 8601 date string
-                 td: float = 0.0 # Transmission Distance in mm for HueForge/OrcaSlicer-FullSpectrum
+                 td: float = 0.0, # Transmission Distance in mm for HueForge/OrcaSlicer-FullSpectrum
+                 tag_index: int = 0, # Which tag of the item was read (1-based), 0 = unknown
+                 tag_count: int = 0, # Number of tags on the item (2 = twin tags), 0 = unknown
                  ):
         self.source_processor = source_processor
         self.unique_id = unique_id
@@ -43,6 +45,8 @@ def __init__(self,
         self.drying_time_hours = drying_time_hours
         self.manufacturing_date = manufacturing_date
         self.td = td
+        self.tag_index = tag_index
+        self.tag_count = tag_count
 
         if "CF" in self.modifiers:
             self.type += "-CF"
@@ -71,7 +75,7 @@ def pretty_text(self) -> str:
             f"- Drying: {self.drying_temp_c:.1f}C for {self.drying_time_hours:.1f} hours",
             f"- Manufactured on: {self.manufacturing_date}",
             f"- TD: {self.td:.1f} mm"
-        ])
+        ] + ([f"- Tag: {self.tag_index or '?'} of {self.tag_count}"] if self.tag_count else []))
 
     @property
     def rgba(self) -> int:
@@ -102,7 +106,9 @@ def to_dict(self) -> dict:
             "drying_temp_c": self.drying_temp_c,
             "drying_time_hours": self.drying_time_hours,
             "manufacturing_date": self.manufacturing_date,
-            "td": self.td
+            "td": self.td,
+            "tag_index": self.tag_index,
+            "tag_count": self.tag_count
         }
 
     @staticmethod

src/tag/tigertag/constants.py

@@ -20,6 +20,7 @@
 OFF_BED_TEMP_MIN = 30
 OFF_BED_TEMP_MAX = 31
 OFF_TIMESTAMP = 32
+OFF_TAG_INDEX_COUNT = 39  # high nibble = tag index, low nibble = tag count, 0 = unknown
 OFF_TD = 44
 OFF_METADATA = 48
 OFF_SIGNATURE = 80

src/tag/tigertag/processor.py

@@ -68,6 +68,17 @@ def __parse_tigertag(self, scan_result: ScanResult, user_data: bytes, tag_id: in
 
             timestamp_raw = struct.unpack_from('>I', user_data, Constants.OFF_TIMESTAMP)[0]
 
+            # Tag index / count (spec v2.2): 0x12 = tag 1 of 2. Tags written
+            # before v2.2 have 0x00 here, which means unknown.
+            tag_index = 0
+            tag_count = 0
+            if len(user_data) > Constants.OFF_TAG_INDEX_COUNT:
+                index_count = user_data[Constants.OFF_TAG_INDEX_COUNT]
+                tag_index = index_count >> 4
+                tag_count = index_count & 0x0F
+                if tag_index > tag_count:
+                    tag_index = 0
+
             material_label = self.registry.material_ids.get(material_id, f"Unknown({material_id})")
             material_type = self.registry.material_type_ids.get(material_id, material_label)
             filled_type = self.registry.filled_type_ids.get(material_id, "")
@@ -100,6 +111,7 @@ def __parse_tigertag(self, scan_result: ScanResult, user_data: bytes, tag_id: in
             self.logger.debug("  Bed Temp: %d-%d °C", bed_temp_min, bed_temp_max)
             self.logger.debug("  TD: raw=%d → %.1f mm", td_raw, td_mm)
             self.logger.debug("  Timestamp: %d (%s)", timestamp_raw, manufacturing_date)
+            self.logger.debug("  Tag: %d of %d", tag_index, tag_count)
 
             return GenericFilament(
                 source_processor=self.name,
@@ -120,6 +132,8 @@ def __parse_tigertag(self, scan_result: ScanResult, user_data: bytes, tag_id: in
                 drying_time_hours=float(dry_time),
                 manufacturing_date=manufacturing_date,
                 td=td_mm,
+                tag_index=tag_index,
+                tag_count=tag_count,
             )
 
         except Exception as e:

test/tags/Tigertag/eSun PLA Basic Refill Cold White TigerTag+ Twin 1 of 2.bin

@@ -0,0 +1,19 @@
+bed_temp_c: 0.0
+colors:
+- 0xFFDDE5ED
+diameter_mm: 1.75
+drying_temp_c: 50.0
+drying_time_hours: 8.0
+hotend_max_temp_c: 230.0
+hotend_min_temp_c: 210.0
+manufacturer: eSun
+manufacturing_date: '2025-11-12'
+modifiers:
+- Basic
+source_processor: TigerTagProcessor
+td: 0.0
+type: PLA
+unique_id: c97d79c4ec83c89e5063834556625468b602e492996bfd674fbbeb238469d031
+weight_grams: 1000.0
+tag_index: 1
+tag_count: 2

test/tags/Tigertag/eSun PLA Basic Refill Cold White TigerTag+ Twin 1 of 2.yml

@@ -0,0 +1,19 @@
+bed_temp_c: 0.0
+colors:
+- 0xFFDDE5ED
+diameter_mm: 1.75
+drying_temp_c: 50.0
+drying_time_hours: 8.0
+hotend_max_temp_c: 230.0
+hotend_min_temp_c: 210.0
+manufacturer: eSun
+manufacturing_date: '2025-11-12'
+modifiers:
+- Basic
+source_processor: TigerTagProcessor
+td: 0.0
+type: PLA
+unique_id: c97d79c4ec83c89e5063834556625468b602e492996bfd674fbbeb238469d031
+weight_grams: 1000.0
+tag_index: 2
+tag_count: 2

test/tags/Tigertag/eSun PLA Basic Refill Cold White TigerTag+ Twin 2 of 2.bin

@@ -15,3 +15,5 @@ td: 0.0
 type: PLA
 unique_id: c97d79c4ec83c89e5063834556625468b602e492996bfd674fbbeb238469d031
 weight_grams: 1000.0
+tag_index: 0
+tag_count: 0