Skip to main content

Wonder-Shipped Reader Provisioning

How readers provisioned by Wonder arrive ready to plug in and work.

What "Wonder-Shipped" Means​

Wonder-Shipped = Reader is configured at Wonder's bench before shipping to customer. Hardware arrives with:

  • CAP installed (Titan Agent)
  • Identity provisioned (/cust/rw_dir/ contains ca.crt, client.crt, client.key, titan.json)
  • MQTT configured to reach mqtt.titanrfid.com:8883 with TLS
  • Reader row created in customer's Titan Cloud account
  • Titan Cloud knows which customer owns this reader (device binding)

Customer experience: Unbox, plug into PoE, reader appears online in hub within 60 seconds.

Bench Provisioning Process​

What Wonder's Technician Does​

  1. Receive reader (Impinj R700, new or returned hardware)
  2. Power reader on bench (PoE or AC adapter)
  3. Access reader web UI at https://<bench-lan-ip>/ (reader on bench network)
  4. Run provisioning tool: 
    readerprov provision \
      -reader 192.0.2.10 \
      -tenant acme-corp \
      -name "Goods In 3"

What readerprov provision Does​

In this order (atomic transaction - all or nothing):

  1. Read serial from reader via GET /api/v1/system (e.g. 370-12-34-5678-9012)
  2. Check tenant exists in Titan Cloud database (fail if not found)
  3. Issue client certificate:
    • CN (Common Name) = serial number
    • Validity: 10 years
    • Signed by Titan Cloud CA
  4. Create reader row in customer's account:
    • Reader ID (Titan internal UUID for the readers row; not the cert CN)
    • Name: "Goods In 3"
    • Serial: 370-12-34-5678-9012
    • Tenant: acme-corp
  5. Create device binding in devices table:
    • Identity: serial number
    • Tenant: acme-corp
    • Reader: (FK to reader row above)
    • Provisioned: at_bench
  6. Install CAP (if not already present):
    • Upload titan-agent-0.1.6.0.upgx
    • Set Persistent Data = rw_dir
  7. Write identity files to /cust/rw_dir/ via reader REST API:
    • POST /api/v1/files/cust/rw_dir/ca.crt (Titan CA)
    • POST /api/v1/files/cust/rw_dir/client.crt (reader's cert)
    • POST /api/v1/files/cust/rw_dir/client.key (private key, mode 0600)
    • POST /api/v1/files/cust/rw_dir/titan.json (REST credentials)
  8. Configure MQTT via PUT /api/v1/mqtt:
    • Broker: mqtt.titanrfid.com:8883
    • TLS: enabled
    • Client ID: 370-12-34-5678-9012
    • Topics: titan/v1/370-12-34-5678-9012/{events,status}
  9. Start reader with titan-default preset:
    • POST /api/v1/profiles/inventory/presets/titan-default/start
  10. Verify connection:
    • Poll GET /api/v1/status until mqttBrokerConnectionStatus: connected
    • Poll GET /api/v1/status until mqttTlsAuthentication: server
    • Timeout: 60 seconds
  11. Audit log provisioning event:
    • Serial, tenant, timestamp, technician, outcome

Rollback on Failure​

If any step fails, tool undoes all changes (newest first):

  • Restore previous MQTT config
  • Restore previous preset
  • Delete identity files
  • Delete device binding
  • Delete reader row
  • Discard DB transaction

Reader left unchanged if provisioning fails. No half-configured state.

What Gets Verified​

Before boxing:

  • Reader shows "connected" in own web UI status
  • Hub UI shows reader online (tag reads flowing)
  • Start/Stop buttons work (CAP subscribed to commands)
  • Identity files persisted in rw_dir (survive CAP restart)

Security Model​

Physical Access Required​

Provisioning requires:

  • Reader on bench (technician's LAN)
  • Reader admin credentials (default: root + password from label)
  • Access to Titan Cloud database (tenant lookup, reader creation)

Cannot be done remotely. No internet exposure during provisioning. Credentials written over local REST API (HTTPS on bench LAN).

No Shared Secrets​

Each reader gets:

  • Unique client certificate (CN is the reader serial number, the device identity for MQTT)
  • Unique private key (2048-bit RSA or ECDSA P-256)
  • Unique REST password (32-byte random)

No shared MQTT username/password. Certificate is the identity.

Audit Trail​

Every provisioning logged:

  • Serial number
  • Tenant (customer)
  • Timestamp
  • Technician (who ran readerprov)
  • Outcome (success, or reason for failure)

Queryable in hub UI → Audit Log, or via API: GET /api/v1/audit?resource=device

Customer Receives Reader​

Shipping​

Reader is powered off, boxed, shipped to customer address. No changes made to reader after provisioning.

Packing Note​

Included in box:

  • Reader hardware (R700)
  • Serial number label (physical label on reader)
  • Quick start: "Plug into PoE. Reader will appear at hub.titanrfid.com within 60 seconds."

No credentials in packing note. Identity is already on reader.

First Boot​

Customer plugs reader into PoE:

  1. Reader powers on
  2. Stock firmware starts, reads MQTT config (already set to Titan Cloud)
  3. CAP starts, reads identity from /cust/rw_dir/
  4. Reader connects to mqtt.titanrfid.com:8883 with client cert
  5. Broker authenticates (cert CN matches reader serial; ACL allows topics for that identity)
  6. CAP subscribes to titan/v1/370-12-34-5678-9012/commands
  7. Stock firmware publishes first status update to titan/v1/370-12-34-5678-9012/status
  8. Titan ingest resolves serial → device → tenant → reader
  9. Hub UI shows reader Online

Time to online: ~60 seconds from plug-in.

Advantages of Wonder-Shipped​

vs BYO (bring-your-own):

AspectWonder-ShippedBYO (Designed, Not Built)
Customer SetupPlug in (1 step)Install CAP, claim, bootstrap (3 steps)
Network ExposureNone (bench LAN only)Bootstrap endpoint on internet
Attack SurfaceMinimalLarger (token handling, pull API)
Support BurdenLow (works on arrival)Higher (customer-side install errors)
Hardware ControlRequired (Wonder must touch hardware)Not required (customer owns hardware)
Time to Online60 seconds (plug in)5-10 minutes (install + claim + pull)

Security: Wonder-Shipped is stronger. No internet exposure during provisioning; physical access required; credentials never transit internet.

Trade-off: Requires Wonder to control hardware flow (buy readers, provision at bench, ship to customer). Cannot be used for customer-owned hardware already on-site.

Re-Provisioning (Returned Readers)​

Scenario: Reader returned from Customer A, now going to Customer B.

Process:

  1. Release reader from Customer A's account (operator console; customer requests via support or Wonder):
    • Operator releases the device so it unassigns the tenant only (clears device binding; tenant_id = NULL)
    • Reader row in Customer A's account marked released
  2. Revoke the old client certificate (recommended before re-provisioning):
    • Contact support or Wonder to revoke the old certificate on the broker
    • Without revocation on the broker, the old cert can still connect to MQTT until support revokes it
  3. Factory reset reader (config-image mode default - keeps CAP):
    • Wipes MQTT config, presets, settings
    • Keeps CAP installed
    • Keeps /cust/rw_dir/ - old identity still present (will be overwritten)
  4. Re-provision for Customer B:
    • Run readerprov provision -reader <ip> -tenant customer-b -name "Receiving"
    • Issues new cert (same reader serial as CN, new keys)
    • Overwrites identity files in /cust/rw_dir/
    • Creates device binding to Customer B
    • If you completed step 2, the old cert cannot reconnect even if Customer A still has the old credentials

No cross-contamination: New cert issued for Customer B. If support or Wonder has revoked the old certificate on the broker, Customer A's credentials cannot reconnect. Customer B cannot see Customer A's data (separate tenant).

Factory Reset and Identity​

Config-Image Modes​

R700 config-image setting controls what survives factory reset:

ModeCAPIdentity (/cust/rw_dir/)When to Use
defaultKeptKeptReset config, keep identity (most common)
removecapWipedWipedFull wipe, return to stock (rare)

Physical Default Restore button: Uses whatever config-image mode is set (default = default = keeps CAP + identity).

When Identity Survives​

  • Config reset via web UI (Settings → Reset to defaults) - if mode = default
  • Physical Default Restore button - if mode = default
  • CAP upgrade (identity in rw_dir, marked Persistent)
  • Reader reboot

When Identity Is Wiped​

  • Config-image mode set to removecap + factory reset
  • Manual delete via REST API: DELETE /api/v1/files/cust/rw_dir/*

If wiped: Reader must be re-provisioned (new claim, new identity).

What Customer Cannot Change​

Reader identity is immutable once provisioned (unless re-provisioned by Wonder):

  • Cannot change serial number (hardware property)
  • Cannot change client cert (requires CA signing key, which customer doesn't have)
  • Cannot move reader to different tenant (requires device binding change, which is Titan DB write)

Customer CAN:

  • Rename reader in hub UI (cosmetic only, does not change identity)
  • Map antennas to zones
  • Configure RF settings (power, session, etc.)
  • Start/Stop reader
  • Factory reset (if mode = default, identity survives)

Troubleshooting Wonder-Shipped Readers​

Reader Offline After Arrival​

Check:

  1. Powered? (PoE or AC - needs 802.3at or 802.3bt)
  2. Network? (Reader reachable on LAN; firewall allows outbound 8883/tcp)
  3. CAP running? (Reader web UI → Apps → Titan Agent → Status)
  4. Identity present? (SSH or REST API: ls /cust/rw_dir/ - should have 4 files)
  5. MQTT config? (Reader web UI → Status → mqttBrokerConnectionStatus)

Common causes:

  • No PoE power (reader not supported by switch PoE budget)
  • Firewall blocks outbound 8883/tcp (reader cannot reach mqtt.titanrfid.com)
  • CAP crashed (check CAP log)
  • Identity wiped (customer did removecap factory reset)

Start/Stop Doesn't Work​

Check:

  1. CAP running? (Web UI → Apps → Status = Running)
  2. CAP subscribed? (CAP log → Subscribed to titan/v1/.../commands)
  3. Commands reaching reader? (Hub audit log → command published)
  4. Acks sent? (CAP log → Published ack: {...})

Fix: Usually CAP restart. If persist, re-provision identity.

Reader Shows Wrong Customer​

Cannot happen if provisioned correctly. Device binding is set at bench, immutable.

If it happens: Provisioning error. Contact Wonder support with serial number.

Next Steps​