Skip to main content

Edge Service API

Authentication: every request needs an IdToken — see Authentication. Send it as the Authorization header.

The Edge Service API manages the fixed RFID readers connected to Xemelgo: whether a reader is online, whether it is reading tags, and how it reads them.

PageWhat it covers
Device ControlConnection, reading status, start/stop reading, reader details, edge app registration
Data ModeHow the reader filters and reports tag reads
Device SettingsAntenna settings: power, session, RSSI filter, reader mode
GPIOGeneral-purpose outputs (lights, buzzers, relays)

Device IDs​

{deviceId} identifies a reader and is case-sensitive: use it exactly as shown, in capitals.

ReaderDevice ID
Zebra (IoT Connector)MAC address in capitals, without colons. C4:7D:CC:0A:1B:2C → C47DCC0A1B2C
Nordic IDThe reader's serial number, for example K123456789
ImpinjMAC address in capitals, without colons. 00:16:25:1A:2B:3C → 0016251A2B3C

Reader Types​

Each reader connects to Xemelgo through an edge app, which decides the edgeApp value and the shape of a few responses:

ReadersEdge appedgeApp
Nordic ID, ImpinjXemelgo edge appxemelgo
ZebraZebra IoT Connectorzebra

Where responses differ, each page shows an example for each.

A reader is registered with its edge app automatically the first time it connects to Xemelgo. Until then, the details and operations endpoints return the error Device {deviceId} is not yet registered or has never been online, Get Edge App returns 200 with an empty body, and Set Edge App can register the reader manually.

Live and Cached Reads​

details endpoints return the last known value from a cache by default. Add ?refresh=true to ask the reader directly instead.

Endpoints under operations always talk to the reader and update the cache with the result.

One Operation at a Time​

A reader handles one change at a time. While a start, stop, data mode, device settings, or GPO change is in progress on a reader, another change to the same reader returns Fail to aquire lock for resource. Wait for the first request to finish and try again.

Errors​

Errors return status code 400 with this body:

{
"reason": "Device C47DCC0A1B2C is not yet registered or has never been online",
"status": "failed"
}
ReasonCause
Device {deviceId} is not yet registered or has never been onlineNo reader with this ID has connected to Xemelgo. Check the ID and its capitalization
No response found after 5 wait attemptsThe reader did not answer, usually because it is offline
Fail to aquire lock for resourceAnother change to the same reader is in progress
Payload validation failed on field {field} due to: field is requiredA required field is missing from the request body
Payload validation failed on field {field} due to: contains unexpected value.A field has a value that is not allowed

A missing or invalid Authorization header returns status code 401:

{ "message": "Unauthorized" }