Device Identity

Every Haltian IoT device carries multiple identifiers, each used in different contexts. Understanding which identifier to use — and how to map between them — is essential for API integration, field installation, and data analysis.

The Identity Problem

A single sensor might be referenced as:

• TSPR04EZU31901021 on the QR code sticker
• 15056570 in Wirepas mesh traffic
• a3b7c9d0-1234-5678-90ab-cdef01234567 in API responses and MQTT topics

These are all the same device. The platform maps between them, but you need to know which identifier to use in each context.

Identity Types

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F6FAFA', 'primaryTextColor': '#143633', 'primaryBorderColor': '#143633', 'lineColor': '#143633', 'secondaryColor': '#C7FDE6', 'tertiaryColor': '#73F9C1', 'clusterBkg': '#ffffff', 'clusterBorder': '#143633', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart TB
    subgraph Manufacturing["fa:fa-industry Manufacturing"]
        IMC["IMC<br/><i>Item Model Code</i><br/>e.g., TSPR04"]
        Serial["Vendor Serial<br/>e.g., EZU31901021"]
        WirepasID["Wirepas Node ID<br/>e.g., 15056570"]
        MAC["MAC Addresses<br/>BLE, WiFi, LAN"]
    end

    subgraph Physical["fa:fa-qrcode Physical Label"]
        TUID["TUID<br/>= IMC + Vendor Serial<br/>e.g., TSPR04EZU31901021"]
        QR["QR Code<br/>Contains TUID + Wirepas ID"]
    end

    subgraph Platform["fa:fa-cloud Platform Registration"]
        UUID["UUID<br/>Haltian IoT Device ID<br/>e.g., a3b7c9d0-..."]
        CustLabel["Customer Label ID<br/><i>Optional, user-assigned</i>"]
        ExtID["External ID<br/><i>Optional, for 3rd-party systems</i>"]
    end

    IMC --> TUID
    Serial --> TUID
    TUID --> QR
    WirepasID --> QR
    TUID --> UUID
    UUID --> CustLabel
    UUID --> ExtID

    style Manufacturing fill:#ffffff,stroke:#143633,stroke-width:2px,color:#143633
    style Physical fill:#ffffff,stroke:#143633,stroke-width:2px,color:#143633
    style Platform fill:#ffffff,stroke:#143633,stroke-width:2px,color:#143633
    style TUID fill:#73F9C1,stroke:#143633,stroke-width:2px,color:#143633
    style UUID fill:#73F9C1,stroke:#143633,stroke-width:2px,color:#143633
    style IMC fill:#F6FAFA,stroke:#143633,stroke-width:2px,color:#143633
    style Serial fill:#F6FAFA,stroke:#143633,stroke-width:2px,color:#143633
    style WirepasID fill:#F6FAFA,stroke:#143633,stroke-width:2px,color:#143633
    style MAC fill:#F6FAFA,stroke:#143633,stroke-width:2px,color:#143633
    style QR fill:#C7FDE6,stroke:#143633,stroke-width:2px,color:#143633
    style CustLabel fill:#F6FAFA,stroke:#143633,stroke-width:2px,color:#143633
    style ExtID fill:#F6FAFA,stroke:#143633,stroke-width:2px,color:#143633

Hardware Identifiers (set at manufacturing)

Platform Identifiers (assigned at registration)

When to Use Which Identifier

Mapping Between Identifiers

The UUID is the hub — you can always go from any identifier to UUID, and from UUID to any other identifier.

From physical label to API

Scan the QR code → extract TUID → query the Service API:

query {
  devices(where: { identifiers: { tuid: { _eq: "TSPR04EZU31901021" } } }) {
    id          # UUID
    name
    identifiers {
      tuid
      wirepasNodeId
      vendorSerial
    }
  }
}

From Wirepas Node ID to UUID

When processing binary passthrough data, map the Wirepas address:

query {
  devices(where: { identifiers: { wirepasNodeId: { _eq: 15056570 } } }) {
    id          # UUID
    name
    identifiers { tuid }
  }
}

From UUID to everything

query {
  devices(where: { id: { _eq: "a3b7c9d0-1234-5678-90ab-cdef01234567" } }) {
    identifiers {
      tuid
      vendorSerial
      wirepasNodeId
      wirepasNetworkId
      bleMac
      customerLabelId
    }
  }
}

For a complete walk-through with QR code parsing, see the Device Lookup by QR Code tutorial.

QR Code Formats

Devices ship with a QR code sticker containing identity data. Three formats exist:

The QR code format varies by manufacturing batch. Your application should handle all three formats. See the QR code tutorial for parsing logic.

Legacy vs. Current Identifiers

The TUID remains important for physical-world workflows (installation, maintenance, troubleshooting) but the UUID is the authoritative identifier for all programmatic interactions.

Next Steps

• Device Lookup by QR Code — Step-by-step tutorial for TUID-to-UUID mapping
• Data Model — Device entity fields and relationships
• Wirepas Mesh — How Wirepas Node IDs are used in mesh routing
• Binary Passthrough — Working with Wirepas Node IDs in raw data