Skip to main content

Device Control

Authentication: every request needs an IdToken — see Authentication. Errors follow the shared error format.

MethodPathPurpose
GET/devices/{deviceId}/edge-appEdge app and connection status
POST/devices/{deviceId}/edge-appSet a reader's edge app manually
GET/devices/{deviceId}/details/statusWhether the reader is reading tags
POST/devices/{deviceId}/operations/startStart reading tags
POST/devices/{deviceId}/operations/stopStop reading tags
GET/devices/{deviceId}/details/biographyModel, vendor, network and software versions
GET/versionVersion of the Edge Service API
GET/devices-files/da-appDownload the Xemelgo app package for Zebra readers

Get Edge App​

Returns which edge app a reader runs and whether it is connected to Xemelgo.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/devices/{deviceId}/edge-app
  • Method: GET

Path Parameters​

ParameterTypeDescriptionRequired
deviceIdStringReader device IDYes

StatusCode — 200 on success

Response Body​

{
"connectionStatus": "connected",
"edgeApp": "zebra",
"deviceId": "C47DCC0A1B2C"
}
PropertyTypeDescription
deviceIdStringReader device ID
edgeAppStringxemelgo or zebra
connectionStatusStringconnected, disconnected, or unknown (set manually, see Set Edge App)

If no reader with this ID has ever connected, the response is 200 with an empty body.

Set Edge App​

Sets a reader's edge app manually. Readers are registered automatically when they connect, so use this only when a reader cannot register itself.

warning

This overwrites the reader's existing record and sets connectionStatus to unknown until the reader next connects. Setting the wrong edgeApp stops the device endpoints from working for that reader.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/devices/{deviceId}/edge-app
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
edgeAppStringxemelgo or zebraYes

Request Body​

{
"edgeApp": "xemelgo"
}

StatusCode — 200 on success

Response Body​

{
"deviceId": "K123456789",
"edgeApp": "xemelgo"
}

Get Device Status​

Returns whether the reader is reading tags.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/devices/{deviceId}/details/status
  • Method: GET

Query Parameters​

ParameterTypeDescriptionRequired
refreshStringtrue to ask the reader now. Omit to return the cached statusNo

StatusCode — 200 on success

Response Body​

The fields depend on the reader's edge app.

Nordic ID and Impinj readers (Xemelgo edge app)

{
"operationalStatus": "running",
"connectionStatus": "connected"
}
PropertyTypeDescription
operationalStatusStringrunning (reading tags) or stopped
connectionStatusStringWhether the edge app is connected to the reader's radio: connected or disconnected

Zebra readers (Zebra IoT Connector)

{
"status": "running"
}
PropertyTypeDescription
statusStringrunning (reading tags), stopped, or unknown if the reader did not report its radio state

Start Reading​

Starts the reader reading tags.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/devices/{deviceId}/operations/start
  • Method: POST
  • Body: none

StatusCode — 200 on success

Response Body​

Nordic ID and Impinj readers (Xemelgo edge app)

{
"operationalStatus": "running"
}

Zebra readers (Zebra IoT Connector)

{
"status": "running"
}

For Zebra readers this response confirms the reader accepted the command; it is not read back from the reader. To confirm the reader's actual state, call Get Device Status with refresh=true.

Stop Reading​

Stops the reader reading tags. The reader stays connected and can be started again.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/devices/{deviceId}/operations/stop
  • Method: POST
  • Body: none

StatusCode — 200 on success

Response Body​

Nordic ID and Impinj readers (Xemelgo edge app)

{
"operationalStatus": "stopped"
}

Zebra readers (Zebra IoT Connector)

{
"status": "stopped"
}

As with Start Reading, confirm a Zebra reader's actual state with Get Device Status and refresh=true.

Get Device Biography​

Returns the reader's model, vendor, network addresses, software versions, and supported features.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/devices/{deviceId}/details/biography
  • Method: GET

Query Parameters​

ParameterTypeDescriptionRequired
refreshStringtrue to ask the reader now. Omit to return the cached valueNo

StatusCode — 200 on success

Response Body​

{
"biography": {
"deviceId": "C47DCC0A1B2C",
"deviceType": "rfid-mounted-reader",
"model": "FX7500",
"vendor": "zebra"
},
"commandVersion": "0.6.2.96",
"networks": {
"ip": "192.168.1.50",
"subnet": "255.255.255.0",
"gateway": "192.168.1.1"
},
"versions": {
"cloudAgentApplication": "0.6.2.96",
"radioControlApplication": "0.2.58.12",
"radioFirmware": "1.4.91.0",
"readerApplication": "4.0.48.0"
},
"supports": {
"features": ["version", "gpo", "readerConfig"]
}
}
PropertyTypeDescription
commandVersionStringCommand protocol version the reader uses
biography.deviceIdStringReader device ID
biography.modelStringReader model
biography.vendorStringReader vendor
biography.deviceTypeStringrfid-mounted-reader or rfid-handheld-reader
networksObjectNetwork names and their addresses
versionsObjectSoftware component names and their versions
supports.featuresString[]Features the reader supports, for example dataMode, gpo, readerConfig, version

Example from a Zebra FX7500. The keys inside networks and versions depend on the reader model.

Get API Version​

Returns the version of the Edge Service API.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/version
  • Method: GET

StatusCode — 200 on success

Response Body​

"1.0.0"

Download Zebra App Package​

Downloads the Xemelgo app package (.deb) that is installed on Zebra readers.

Endpoint Details​

  • URL: https://rest.api.xemelgo.com/edge/devices-files/da-app
  • Method: GET

Query Parameters​

ParameterTypeDescriptionRequired
categoryStringZebra reader family: fx (FX7500, FX9600) or atr (ATR7000). Default fxNo
versionStringPackage version. Default 1.0.1No

StatusCode — 200 on success

Response​

The package file as a binary download, named xemelgo-app_{version}.{category}.deb:

Content-Disposition: attachment; filename="xemelgo-app_1.0.1.fx.deb"