Troubleshooting Guide

Quick reference for common issues with Titan RFID readers.

Reader Offline

Symptom

Hub UI shows reader "Offline". No tag reads, no status updates.

Checks

1. Powered? PoE or AC connected? (Reader needs 802.3at or 802.3bt PoE)
2. Network? Can you reach reader web UI at https://<reader-ip>/?
3. MQTT config? Reader web UI → Status → mqttBrokerConnectionStatus
4. Firewall? Outbound 8883/tcp allowed to mqtt.titanrfid.com (Cloud) or broker IP (On-Prem)?
5. CAP running? Apps → Titan Agent → Status = Running?

Fixes

• Check PoE budget (reader draws ~25W; some switches can't supply enough)
• Verify network connectivity (ping reader from workstation)
• Check MQTT config (broker address correct?)
• Restart CAP (Apps → Restart)
• Check identity files: SSH → ls /cust/rw_dir/ (should have 4 files)

Start/Stop Buttons Don't Work

Symptom

Click Start, nothing happens. Hub shows timeout or no response.

Checks

1. CAP installed? Reader web UI → Apps → Custom Applications → Titan Agent present?
2. CAP running? Status = Running (not Stopped or Crashed)?
3. CAP log? Apps → View Log → Subscribed to titan/v1/{serial}/commands?
4. Commands reaching reader? Hub → Audit Log → Command published?

Fixes

• Install CAP if missing (see CAP Install)
• Restart CAP if crashed
• Check identity files (CAP cannot connect without credentials)
• Manually start via reader web UI (workaround: Profiles → Inventory → Start)

No Tags Appearing

Symptom

Reader shows "Reading" in hub, but Tag Data stays empty.

Checks

1. Reader really started? Reader web UI → Status → Inventory profile active?
2. Tags present? Wave tag in front of antenna (test with known tag)
3. Antennas enabled? Reader web UI → Antennas → Enabled checkboxes
4. Antennas mapped? Hub → Zones → Antennas mapped to zones?
5. Tag reads in reader? Reader web UI → Status → Tag read count incrementing?
6. MQTT telemetry? Hub → Readers → Last Seen timestamp updating?

Fixes

• Enable antennas (reader web UI)
• Map antennas to zones (hub UI → Zones)
• Check tag frequency (R700 is 902-928 MHz; tags must match)
• Check MQTT broker connection (reader → broker)

CAP Crash-Loops

Symptom

Reader web UI → Apps → Titan Agent restarts every few seconds.

Checks

1. CAP log? Apps → View Log → What error before crash?
2. Firmware version? CAP 0.1.6.0 requires firmware 10.0.0+
3. Identity files? All 4 present in /cust/rw_dir/?
4. File permissions? client.key mode 0600?

Fixes

• Upgrade firmware to 10.0.0+ (reader web UI → Software Updates)
• Provision identity if missing (see CAP Identity)
• Fix file permissions: chmod 0600 /cust/rw_dir/client.key
• Upgrade CAP to 0.1.6.0+ (static-linked libstdc++ fixes old firmware issues)

TLS Handshake Failures

Symptom

CAP log: TLS handshake failed or certificate verify failed

Checks

1. ca.crt correct? Must be Titan Cloud CA (not the reader's self-signed cert). A wrong CA fails verification.
2. Cert + key match? client.crt and client.key issued together?
3. Client certificate revoked on the broker? TLS handshake fails when the broker rejects a revoked cert.

Fixes

• Re-provision with correct CA (see Provisioning)
• Verify cert CN matches serial: openssl x509 -in client.crt -noout -subject
• If support or Wonder has revoked the old certificate on the broker, re-provision with a new cert and ask support to revoke the previous cert if it must not reconnect

Commands Reach Reader But Fail to Execute

Symptom

CAP log shows command received, but REST API returns error (401, 500).

Checks

1. Reader REST password? titan.json password correct?
2. Reader API reachable? CAP → https://127.0.0.1/api/v1/ (loopback)
3. Preset exists? Command references titan-default; does preset exist on reader?

Fixes

• Re-provision identity (titan.json gets new password)
• Verify loopback REST API works: curl -k -u root:<pw> https://127.0.0.1/api/v1/status
• Create missing preset on reader (web UI → Profiles → Create)

Reader Online But "Degraded"

Symptom

Hub shows reader "Degraded". Tag reads flowing, but commands timeout.

Meaning

• Stock firmware publishing tag reads (MQTT publish works)
• CAP not responding to commands (cannot subscribe, or not installed)

Fixes

• Check CAP installed and running
• Check CAP subscribed to correct topic (titan/v1/{serial}/commands)
• Restart CAP

Identity Lost After Reset

Symptom

Factory reset reader, now offline. CAP present but won't connect. /cust/rw_dir/ empty.

Cause

Config-image mode was removecap (full wipe) instead of default (keep identity).

Fixes

1. Ask support or Wonder to release the reader in the operator console (unassigns tenant only; ask support or Wonder to revoke the old certificate separately if it must not reconnect)
2. Re-provision:
   • Wonder-shipped: Re-run readerprov provision -replace
   • BYO: Re-claim via hub, re-pull identity

Data loss: None (tag history in Titan, not on reader). Reader config must be restored.

Broker Refuses Connection ("Bad Credentials")

Symptom

CAP log: MQTT connect refused: Bad username or password

Causes

• Broker ACL or authentication policy rejected the MQTT session (unusual with mutual TLS). Release does not change broker login. A revoked certificate fails at TLS, not here.

Fixes

• Capture the exact broker reason from the CAP log and contact support

Connected but No Tag Events (Cert CN Mismatch)

Symptom

CAP log shows MQTT connected, but the hub shows no tag reads and Last seen does not update.

Cause

The broker uses use_identity_as_username true, so the MQTT username is the certificate CN. ACLs allow publishes only on titan/v1/%u/... where %u is that CN. If the CN does not match the reader serial, TLS and MQTT connect succeed, but publishes to the expected topics are silently dropped by the ACL.

Fixes

• Verify cert CN: openssl x509 -in /cust/rw_dir/client.crt -noout -subject (should be CN=<serial>)
• Re-provision if the CN does not match the reader serial

Performance Issues

Symptom

Slow tag reads, delayed updates in hub.

Checks

1. Reader performance? Reader web UI → Status → Tag read rate?
2. Network latency? Ping broker from reader
3. Server load? (On-Prem) Check docker stats (CPU, memory)
4. Database size? (On-Prem) docker exec postgres pg_database_size titan

Fixes

• Check RF settings (power, session, filter)
• Reduce tag population (session filters, FastID)
• Scale server (more CPU, RAM) if On-Prem
• Prune old history (database cleanup script)

Help Not Here?

For On-Prem:

• Contact Titan support for on-prem troubleshooting.
• Email: support@titanrfid.com

For Cloud:

• Hub UI → Help → Contact Support
• Include: reader serial, symptom, CAP log, MQTT status

For CAP Issues:

• Reader web UI → Apps → Titan Agent → View Log (copy full log)
• Reader firmware version
• CAP version (from log first line)

Quick Reference

Symptom	Most Likely Cause	Quick Fix
Reader offline	Power, network, or MQTT config	Check PoE, network, MQTT broker address
Start/Stop doesn't work	CAP not installed or crashed	Install CAP, restart CAP
No tags appearing	Antennas disabled or not mapped	Enable antennas, map to zones
CAP crash-loops	Missing identity or firmware too old	Provision identity, upgrade firmware
TLS handshake fails	Wrong CA or cert/key mismatch	Re-provision with correct identity
Commands fail to execute	Reader REST password wrong	Re-provision identity (updates titan.json)
Degraded status	CAP offline, tag reads still working	Check CAP running, subscribed to commands

Next Steps

• CAP Operations - Managing CAP logs, upgrades
• Factory Reset - Safe reset procedures
• Start/Stop - Remote reader control