Skip to main content

CAP Operations

Day-to-day management of Titan CAP on R700 readers.

Checking CAP Status​

Via Reader Web UI​

  1. Open https://<reader-ip>/
  2. Navigate to Apps → Custom Applications
  3. Find Titan Agent - status should be Running
  4. Click View Log to see recent activity

Via Titan Hub UI​

Reader status in hub reflects CAP health indirectly:

  • Online: CAP connected, command subscriptions active
  • Degraded: Tag reads arriving, but no command acks (CAP may be offline)
  • Offline: No tag reads or status updates (reader or CAP down)

Start/Stop button responsiveness: If buttons work, CAP is healthy. If buttons do nothing (no ack), check CAP log.

Reading CAP Logs​

In Reader Web UI​

Apps → Titan Agent → View Log

Healthy log shows:

[2026-09-20 12:00:01] INFO: Titan Agent 0.1.6.0 starting
[2026-09-20 12:00:02] INFO: Read identity from /cust/rw_dir/
[2026-09-20 12:00:03] INFO: Connecting to mqtt.titanrfid.com:8883
[2026-09-20 12:00:04] INFO: TLS handshake complete
[2026-09-20 12:00:05] INFO: MQTT connected, client_id=370-12-34-5678-9012-agent
[2026-09-20 12:00:06] INFO: Subscribed to titan/v1/370-12-34-5678-9012/commands
[2026-09-20 12:00:07] INFO: Ready

Command execution:

[12:05:30] INFO: Received command: {"kind":"start","id":"abc123","preset":"titan-default"}
[12:05:31] INFO: POST /api/v1/profiles/inventory/presets/titan-default/start
[12:05:32] INFO: Reader started (200 OK)
[12:05:33] INFO: Published ack: {"id":"abc123","ok":true,"status":"started"}

Error patterns:

ERROR: Cannot read /cust/rw_dir/titan.json         → Identity not provisioned
ERROR: TLS handshake failed                        → Wrong CA, cert/key mismatch, or cert revoked on the broker
ERROR: MQTT connected but no events in hub         → Cert CN mismatch (ACL silently drops publishes)
ERROR: POST /api/v1/presets failed: 401            → Reader REST password wrong

Via SSH (If Enabled)​

SSH to reader (if enabled in reader settings):

ssh root@<reader-ip>
cat /var/log/cap/titan-agent.log

Note: SSH is disabled by default on R700. Enable in reader web UI under Settings → SSH.

Restarting CAP​

When to restart:

  • After provisioning identity (if CAP was already running)
  • After updating identity files (cert rotation)
  • If CAP log shows errors and you want to retry connection

How:

  1. Reader web UI → Apps → Titan Agent
  2. Click Restart
  3. Wait 10 seconds, check log for "Ready" message

Alternative: Restart reader (reboots stock firmware + CAP). Takes ~2 minutes.

Upgrading CAP​

In-Place Upgrade​

  1. Download new .upgx file (e.g. titan-agent-0.1.7.0.upgx)
  2. Reader web UI → Apps → Titan Agent → Upload New Version
  3. Select new .upgx file
  4. Persistent Data: Ensure rw_dir is selected
  5. Click Upload

What happens:

  • Old CAP stopped
  • New CAP installed
  • Identity files (/cust/rw_dir/) preserved
  • New CAP started automatically

Downtime: ~30 seconds. Tag reads and commands are queued during upgrade.

Verify Upgrade​

Check CAP log after upgrade:

[12:10:05] INFO: Titan Agent 0.1.7.0 starting   ← New version
[12:10:08] INFO: Ready

Hub UI should show reader back online within 1 minute.

Monitoring CAP Health​

Key Metrics​

From Hub UI (per reader):

  • Last Seen: When last tag read or status update arrived
  • Commands Acked: Timestamp of last command acknowledgment
  • Status: Online / Degraded / Offline

From Reader Log:

  • MQTT connection state (connected / reconnecting)
  • Command receive → ack latency (should be under 2 seconds)
  • REST API errors (reader's own API, not CAP's fault)

Alerting​

Hub Alerts (if configured):

  • Reader offline > 5 minutes
  • Commands timeout (no ack within 30 seconds)

CAP-Specific: Watch for:

  • Crash-loop (restarts every few seconds) → Check log for errors
  • Commands received but not executed → REST API credentials wrong
  • No MQTT connection → Identity or network issue

Common Operations​

Rotate Reader Certificate​

When: Certificate nearing expiry, or security incident

Steps:

  1. Generate new client cert (same CN as reader serial / device identity)
  2. Write new client.crt and client.key to /cust/rw_dir/ (via REST API or re-provision)
  3. Restart CAP
  4. Contact support or Wonder to revoke the previous certificate on the broker if it must not reconnect

Downtime: ~10 seconds (CAP restart)

Change MQTT Broker Address​

Scenario: Migrating from one broker to another

Steps:

  1. Update broker address in hub config (titand side)
  2. Re-provision identity (includes new broker address in titan.json or CAP config)
  3. Restart CAP

Note: CAP currently hardcodes broker address at build time. Future versions will read from titan.json or rw_dir config file.

Revoke Reader (Lost or Stolen)​

Operator console (not customer hub UI): revoke the device via titand's operator API after recording a reason.

Titand revoke effect:

  • Marks the device revoked so Titan stops accepting its data.
  • Does not stop the reader connecting to the MQTT broker.

To block MQTT reconnects: Contact support or Wonder to revoke the client certificate on the broker. After the cert is on the broker revocation list, the reader is refused at its next connection attempt. An existing connection continues until it drops on its own (no fixed time bound).

Cannot be undone in titand. Re-provisioning issues a new certificate but does not revoke the old one; contact support or Wonder to revoke the old certificate if it must not reconnect.

Troubleshooting​

CAP Running But Start/Stop Doesn't Work​

Symptom: Hub buttons do nothing, or commands timeout

Check:

  1. CAP log: Is CAP subscribed to titan/v1/{serial}/commands?
  2. Hub audit log: Is command being published?
  3. CAP log: Is command received? Received command: {...}
  4. CAP log: Is command executed? POST /api/v1/... and response
  5. CAP log: Is ack published? Published ack: {...}

Common causes:

  • Cert CN mismatch → MQTT may connect, but the ACL delivers no commands to the reader (the commands topic is read for the cert CN; a wrong %u has no read rule). Publishes to events/status can be dropped on CN mismatch.
  • Reader REST password wrong → Command received, execution fails
  • Network issue → Commands published but not reaching reader

CAP Crash-Loops​

Symptom: Reader web UI shows CAP restarting every few seconds

Check:

  1. CAP log: What's the error before crash?
  2. Firmware version: CAP 0.1.6.0 requires firmware 10.0.0+ (libstdc++ compatibility)
  3. Identity files: Are all 4 files present and readable?

Common causes:

  • Missing identity files → Cannot read /cust/rw_dir/...
  • libstdc++ version mismatch → GLIBCXX_3.4.32 not found (upgrade CAP to 0.1.6.0+)
  • Permissions on client.key → Must be 0600

Reader Online But No Commands Acked​

Symptom: Tag reads flowing, but Start/Stop buttons timeout

Check:

  1. CAP running? (Web UI → Apps → Status)
  2. CAP log: MQTT connected?
  3. CAP log: Subscribed to correct topic?
  4. Hub audit log: Commands being published?

Common causes:

  • CAP not installed (stock firmware only)
  • CAP installed but stopped
  • CAP subscribed to wrong topic (cert CN ≠ actual serial)

TLS Handshake Failures​

Symptom: CAP log shows TLS handshake failed or certificate verify failed

Check:

  1. ca.crt: Is it Titan Cloud CA? (Not reader's self-signed cert)
  2. client.crt + client.key: Do they match? (issued together)
  3. Client certificate revoked on the broker?

Fix:

  • Re-provision with correct CA and matching cert+key
  • If support or Wonder has revoked the certificate on the broker, re-provision with a new cert and ask support to revoke the previous cert if needed

Commands Work Initially, Then Stop​

Symptom: Start/Stop worked, then stopped working hours/days later

Check:

  1. CAP still running? (May have crashed)
  2. MQTT connection still up? (CAP log: Reconnecting... means broker unreachable)
  3. Client certificate revoked on the broker? (For example after re-provisioning elsewhere)

Fix:

  • Restart CAP if crashed
  • Check network connectivity to broker
  • If the old cert was revoked on the broker, re-provision identity with a new cert

Performance Notes​

CAP Resource Usage:

  • Memory: ~10 MB
  • CPU: under 1% (idle), ~5% (processing command)
  • No impact on reader's RFID performance

Command Latency:

  • Hub click → CAP receives command: under 1 second (MQTT)
  • CAP → Reader REST API: under 1 second
  • Total: ~2 seconds from hub click to radio started

Concurrency: CAP processes one command at a time. Multiple Start commands queued → processed in order.

Backup and Disaster Recovery​

What to back up:

  • Reader configuration (export from reader web UI)
  • Identity files (/cust/rw_dir/*) - but these can be re-provisioned

Restoring:

  1. Factory reset reader (if replacing hardware)
  2. Restore reader config (or reconfigure from scratch)
  3. Install CAP (upload .upgx)
  4. Re-provision identity (Wonder-shipped path, or BYO claim when available)

Lost identity files: Re-provision or re-claim (issues new cert; contact support or Wonder to revoke the old certificate if it must not reconnect). No data loss (tag history is in Titan, not on reader).

Next Steps​

  • Factory Reset - Safely resetting reader while preserving identity
  • Troubleshooting - Full troubleshooting guide
  • CAP claim-and-pull - Future self-service provisioning (internal security design)