Skip to content

RFID Setup and Operation

Jump to bottom
Jorden Luke edited this page Sep 4, 2026 · 6 revisions

RFID Setup And Operation

Ultra-Tracker supports automated RFID timing with the Zebra FXR90 reader. RFID controls are intended for the event's configured Start Line and Finish Line stations. The reader must be reachable from the station computer over the network.

Before Setup

Confirm the following:

  • The Zebra FXR90 is powered on and connected to the station network.
  • The station computer can resolve or reach the reader hostname or IP address.
  • You have a Zebra reader username and password.
  • You have the reader certificate serial number or certificate common name used for certificate pinning.

Connection profiles contain credentials and should be handled as sensitive files.

Connection Settings

Open Settings and expand RFID Configuration.

Field Value
Reader Type Zebra FXR90
Hostname or IP The reader hostname or IP address. The same host is used for the REST API and WebSocket connection.
Certificate Serial The pinned certificate serial number or common name presented by the reader.
Username The Zebra reader account username.
Password The Zebra reader account password.

The Load Connection Profile button can populate these values from a JSON profile. Review the values before authenticating and keep the profile secure.

Example JSON file

{
  "type": "zebra-fxr90",
  "restApiUrl": "fxr90c94e1c",
  "sslCert": "5ecb6929",
  "userName": "admin",
  "password": "password!"
}

Authenticate

  1. Enter the connection settings or load a connection profile.
  2. Select Authenticate.
  3. Ultra-Tracker authenticates with the reader's local REST API.
  4. The app opens a WebSocket for RFID tag events.
  5. After the connection is established, the app reads the reader's current radio activity so the Scan control reflects the actual reader state.

When authentication succeeds, Setup is disabled while the reader remains connected. To change connection settings, use Disconnect RFID first.

Authentication does not start or stop the reader radio. Use the scan control to choose whether the reader should be actively reading tags.

Scan Controls

  • Start Scan starts the reader radio and waits for the reader to report an active radio state.
  • Stop Scan stops the reader radio and waits for the reader to report an inactive radio state.
  • Disconnect RFID stops local RFID processing, closes the WebSocket, and attempts to stop the reader remotely before disconnecting.

When a valid RFID event is received, Ultra-Tracker stores the incoming payload in the local RFID inbox before processing it. This protects tag data when the database or processing path needs to retry.

Connection Health And Recovery

While connected, Ultra-Tracker checks the reader's REST status every 30 seconds. The health check reads /cloud/status and uses the reader's radioActivity value (active or inactive) as the source of truth for the scan state.

After three consecutive failed health checks, the app marks the reader as disconnected, clears the local scanning state, closes the WebSocket, and begins recovery. A brief WebSocket connection does not count as a successful recovery; REST authentication and a successful radio-status check must also complete.

Recovery retries REST authentication and the WebSocket connection with increasing delays, up to ten attempts. Once the reader is reachable again, the app re-reads its radio activity and resumes the health checks. If the reader does not recover, Setup becomes available so the operator can correct the connection settings or retry manually.

If the computer sleeps or resumes, the app invalidates the old RFID connection and uses the same recovery process. It does not assume that the local state from before sleep is still valid.

Troubleshooting

Setup is disabled

The app still considers the reader connected. Select Disconnect RFID and wait for the status to clear. If the reader is unreachable, the local connection is still cleared after the disconnect attempt fails, allowing Setup to be used again.

Start Scan does not produce tags

Check the following:

  1. The reader is powered on and reachable.
  2. The Scan control shows Stop Scan, meaning the reader reports an active radio state.
  3. The antenna and tag placement are appropriate for the station.
  4. The application logs for REST, WebSocket, or certificate errors.

The reader went offline

Wait for the health checks and recovery attempts to complete. If recovery does not succeed, reconnect the reader to the network, select Disconnect RFID if available, and authenticate again. Do not repeatedly click Start Scan while the reader is offline; the app will reconcile the reader state after recovery.

Certificate errors

Verify that Certificate Serial matches either the reader certificate's serial number or its common name. The app pins this value even though the FXR90 uses a self-signed certificate.

Clone this wiki locally