MotionWorks Enterprise RFID Reader Management API Guide

P1129976-01EN Rev A

Zebra Technologies Corporation

• Google Docs
• Google Drive
• Download [pdf]
• Document:
  • References

File Info : application/pdf, 47 Pages, 219.24KB

MotionWorks Enterprise
RFID Reader Management

API Guide

P1129976-01EN Rev A

Copyright
2023/06/15 ZEBRA and the stylized Zebra head are trademarks of Zebra Technologies Corporation, registered in many jurisdictions worldwide. All other trademarks are the property of their respective owners. ©2023 Zebra Technologies Corporation and/or its affiliates. All rights reserved. Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of those agreements. For further information regarding legal and proprietary statements, please go to: SOFTWARE: zebra.com/linkoslegal. COPYRIGHTS: zebra.com/copyright. PATENTS: ip.zebra.com. WARRANTY: zebra.com/warranty. END USER LICENSE AGREEMENT: zebra.com/eula.
Terms of Use
Proprietary Statement
This manual contains proprietary information of Zebra Technologies Corporation and its subsidiaries ("Zebra Technologies"). It is intended solely for the information and use of parties operating and maintaining the equipment described herein. Such proprietary information may not be used, reproduced, or disclosed to any other parties for any other purpose without the express, written permission of Zebra Technologies.
Product Improvements
Continuous improvement of products is a policy of Zebra Technologies. All specifications and designs are subject to change without notice.
Liability Disclaimer
Zebra Technologies takes steps to ensure that its published Engineering specifications and manuals are correct; however, errors do occur. Zebra Technologies reserves the right to correct any such errors and disclaims liability resulting therefrom.
Limitation of Liability
In no event shall Zebra Technologies or anyone else involved in the creation, production, or delivery of the accompanying product (including hardware and software) be liable for any damages whatsoever (including, without limitation, consequential damages including loss of business profits, business interruption, or loss of business information) arising out of the use of, the results of use of, or inability to use such product, even if Zebra Technologies has been advised of the possibility of such damages. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you.

Contents
About this Guide.............................................................................................................................................. 6 Features......................................................................................................................................................6
Login................................................................................................................................................................... 7 Login............................................................................................................................................................ 7 Change Password....................................................................................................................................7
Version............................................................................................................................................................... 9 Query Version.......................................................................................................................................... 9
Format for Status Response.........................................................................................................................10 Format for Status Response...............................................................................................................10
Users................................................................................................................................................................. 12 Create User............................................................................................................................................. 12 Remove User...........................................................................................................................................13 Update User Information..................................................................................................................... 13 Query User...............................................................................................................................................13 Query All Users...................................................................................................................................... 14
Groups.............................................................................................................................................................. 15 Create Group.......................................................................................................................................... 15 Remove Group........................................................................................................................................16
3

Contents
Update Group Information.................................................................................................................. 16 Query Group by Group ID...................................................................................................................17 Query All Groups....................................................................................................................................17
Roles................................................................................................................................................................. 18 Query All Roles.......................................................................................................................................18
Devices............................................................................................................................................................ 20 Add Device............................................................................................................................................. 20 Initialize Device.......................................................................................................................................21 Get Initialize Device Status................................................................................................................. 21 Delete Initialize Task............................................................................................................................22 Remove Device..................................................................................................................................... 22 Update Device Information................................................................................................................ 22 Query Device by Device ID............................................................................................................... 23 Query Devices by Site........................................................................................................................ 32 Query Devices by Device Model..................................................................................................... 32 Query Devices by Device State....................................................................................................... 32 Query Devices by Device Model and Site.................................................................................... 33 Query All Devices................................................................................................................................. 33
Device Configuration.....................................................................................................................................34 Add Device Configuration.................................................................................................................. 34 Remove Device Configuration.......................................................................................................... 34 Update Device Configuration............................................................................................................ 34 Query Device Configurations by Configuration ID......................................................................35 Query Device Configurations by Site............................................................................................. 36 Query Device Configurations by Device Model...........................................................................37 Query Device Configurations by Device State.............................................................................37 Query Device Configurations by Device Model and Site.......................................................... 37 Query All Device Configurations...................................................................................................... 37
Device Tasks...................................................................................................................................................38
4

Contents
Add Device Task...................................................................................................................................38 Remove Device Task...........................................................................................................................38 Update Device Task.............................................................................................................................38 Query Device Tasks by Task ID.......................................................................................................39 Query Device Task History by Task ID.......................................................................................... 40 Query Device Tasks by Device......................................................................................................... 41 Query Device Tasks by Site............................................................................................................... 41 Query Device Tasks by Device Model............................................................................................ 41 Query Device Tasks by Status...........................................................................................................41 Query Device Tasks by Action......................................................................................................... 42 Query Device Tasks by Device Model and Site.......................................................................... 42 Query All Device Tasks...................................................................................................................... 42
Files.................................................................................................................................................................. 43 Add File....................................................................................................................................................43 Remove File............................................................................................................................................ 44 Update File Properties.........................................................................................................................44 Query File Properties by File ID....................................................................................................... 44 Query File Properties by Device Model.........................................................................................45 Query File Properties by Device Model and File Type..............................................................45 Get File by file ID..................................................................................................................................45 Query All File Properties.................................................................................................................... 46
5

About this Guide
About this Guide
This guide documents the REST API interface exposed by MWE RFID Reader Management, which can be used to interact with and manage devices via MWE RFID Reader Management.
Features
MotionWorks Enterprise RFID API enables you to: · Manage and control RFID reader via REST calls. · Manage users and groups on MWE RFID. · Manage and maintain reader configurations such as operating mode, data endpoint, etc. · Perform operation on a device (start, stop, config, mode).
6

Login

Login

Login

Log into system.
Example POST POST: https://<hostname>/trifecta/v1/login BODY:

{ "userName": "user1", "password": "password1"
}
Example Response

{ "access_token": "ey...10"
}
access_token should be used for all subsequent API calls in the Authorization header as a bearer token
Change Password
Change the user password. Example POST POST: https://<hostname>/trifecta/v1/changePassword

7

Login
BODY: {
"userName": "user1", "oldPassword": "password1", "newPassword": "password2", "confirmPassword": "password2" } Example Response No response body.
8

Version
Version
This section provides examples of version commands.
Query Version
Get system version information. Example GET GET: https://<hostname>/trifecta/v1/versions Example Response access_token should be used for all subsequent API calls in the Authorization header as a bearer token.
{ "deviceregistryversion": "0.1.0-fdff02b", "messagebridgeversion": "0.0.3-5608d75", "siteregversion": "0.0.1-5f457dc", "dmsvcversion": "0.0.1-1f4936a", "nginxversion": "1.21.6-31ff10e", "mqttversion": "4.2.3-1de3bbb", "kafkaversion": "7.0.1-7090bb5", "zookeeperversion": "7.0.1-7090bb5", "apigwversion": "2.1-4592521", "apigwinitversion": "2.1-4592521", "authsvcversion": "1.0.0-fe8f953", "usersvcversion": "1.0.0-e798813", "sitesvcversion": "2.0.0-862945f", "alertsvcversion": "2.0.0-17fdfc1", "tileserverversion": "v2.2.0-efea3cb", "fileserverversion": "0.1.0-f71d618", "taskmgrversion": "0.1.0-505c8b6", "devicepromproxyversion": "0.1.0-7ec0ef1", "certsigningsvcversion": "1.0.0-f525d5e", "alertingsidecarversion": "0.0.1-4e9c03f", "deviceinitializerversion": "0.0.4-a3d03a1", "uisvcversion": "0.0.1-528e17a"
}
9

Format for Status Response

Format for Status Response
This section describes formats for status responses.

Format for Status Response
Status response format.

Table 1 Status Response Object

Name

Value

apiName version error code message count pagination

string string string integer string integer object

Required/ Optional Required Required Required Required Required Required Optional

Description
Name of the API requested Version of the API More detailed description of error if any HTTP Code (for example, 200) HTTP message (for example, OK) Number of requests to the API See Pagination Object

Table 2 Pagination Object Name

Value

links first last prev next
page size

string string string string string object integer

totalElements integer

Required/ Optional

Description

Required Required Required Required

URL to the first page URL to the last page URL to the prev page URL to the next page

Required Required

Number of elements on the current page
Total number of elements

10

Format for Status Response

Table 2 Pagination Object (Continued)

Name

Value

totalPages number

integer integer

Required/ Optional
Required
Required

Description
Total number of pages Current page number

11

Users

Users
This section provides examples of user commands.

Create User
Add user. Example POST POST: https://<hostname>/trifecta/v1/user/ BODY:

{ "id": 12345, "username": "user1", "name": "my name", "description": "description of user", "email": "email@company.com", "groups": [{"id": 12345, "name": "admin"}], "password": "password1", "confirmPassword": "password1"
}

Response Format

Table 3 Add/Update User Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Object

Required

Description
See Status Response Object See User Object

12

Users

Table 4 User Object Name

Value

id username name description email groups

integer string string string string array

Required/ Optional Required Required Required Required Required Required

Description Unique identifier for user
See Group Object

Remove User
Delete a user by user id Example DELETE DELETE: https://<hostname>/trifecta/v1/user/{id} Response No response body
Update User Information
Update User Information Example PUT PUT: https://<hostname>/trifecta/v1/user/{id} BODY:

{ "id": 12345, "username": "user1", "name": "my name", "description": "description of user", "email": "email2@company.com", "groups": [{"id": 12345, "name": "admin"}]
}
Example Response See Add/Update User Response Object
Query User
Query user information by user id Example GET GET: https://<hostname>/trifecta/v1/user/{id}

13

Users

Example Response See Add/Update User Response Object

Query All Users

Query all users. NOTE: NOTE: This may return a significant amount of data.

Example Query GET: https://<hostname>/trifecta/v1/users
Response Format

Table 5 Multiple Users Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Array

Required

Description
See Status Response Object See User Object

14

Groups
Groups
This section provides examples of group commands.
Create Group
Add group. Example POST POST: https://<hostname>/trifecta/v1/group/ BODY: { "id": 12345, "name": "my group name", "description": "description of group", "roles": [{"id": 12345, "name": "role1", "description": "my first role}] }
15

Groups

Response Format

Table 6 Add/Update Group Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Object

Required

Description
See Status Response Object See Group Object

Table 7 Group Object

Name

Value

id name description roles

integer string string array

Required/ Optional Required Required Required Required

Description Unique identifier for group
See Roles Object

Remove Group
Delete group by group id. Example DELETE DELETE: https://<hostname>/trifecta/v1/group/{id} Response No response body
Update Group Information
Update group information. Example PUT PUT: https://<hostname>/trifecta/v1/group/{id} BODY:

{ "id": 12345, "name": "my group name", "description": "description of group", "roles": [{"id": 23456, "name": "role2", "description": "my second
role}] }
Response Format See Add/Update Group Response Object

16

Groups

Query Group by Group ID
Query a particular group's information.
Example GET GET: https://<hostname>/trifecta/v1/group/{id}
Response Format See Add/Update Group Response Object

Query All Groups

Query All Groups. NOTE: This may return a significant amount of data.

Example Query GET: https://<hostname>/trifecta/v1/groups
Response Format

Table 8 Multiple Users Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Array

Required

Description
See Status Response Object See Group Object

17

Roles

Roles
This section provides examples of role commands.

Query All Roles

Query all roles. NOTE: This may return a significant amount of data.

Example Query GET: https://<hostname>/trifecta/v1/role
Response Format

Table 9 Multiple Users Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Array

Required

Description
See Status Response Object See Roles Object

Table 10 Roles Object

Name

Value

Id

Number

name

String

description

String

permissions

Array

Required/Optional Required Required Required Required

Description Role Id Role Name Role Description See Permission Object

18

Roles

Table 11 Permission Object

Name

Value

Id

Number

name

String

description

String

Required/Optional Required Required Required

Description
Permission Id
Permission Name
Permission Description

19

Devices

Devices
This section provides examples of device commands.

Add Device
Add a new device to the system.
Body Format See Table 19 Device Object on page 24
Example POST POST: https://<hostname>/trifecta/v1/devices BODY:

{ "hostname": "FX9600ABCDEF"
}

Response Format

Table 12 Add/Update Device Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Object

Required

URL

String

Required

Description See Status Response Object URL to get device information

20

Devices

Initialize Device

Initialize a device. Body Format

Table 13 Initialize Device Body

Name

Value

username password

String String

Required/ Optional
Required
Required

Description
Username set on selected device Password set on selected device

Example Query POST: https://<hostname>/trifecta/v1/devices/<deviceId>/initialize
BODY:

{ "username": "sampleUsername" "password": "samplePassword"
}

Response Format

Table 14 Initialize Device Response Object

Name

Value

status

Object

Required/Optional Required

Description
See Table 1 Status Response Object on page 10

Get Initialize Device Status
Get the status of an initialize task on a device.
Body Format No Body.
Example Query GET: https://<hostname>/trifecta/v1/devices/<deviceId>/initialize

21

Devices

Response Format

Table 15 Initialize Device Response Object

Name

Value

Required/ Optional

Id

Number

Required

deviceId

Object

Required

status

String

Required

statusDescription String

Required

Description
Initialization task Id Device Id Initialization task status Initialization task status description

Delete Initialize Task

Cancells the initialization task on a device.
Body Format No Body.
Example Query DELETE: https://<hostname>/trifecta/v1/devices/<deviceId>/initialize
Response Format

Table 16 Initialize Device Response Object

Name

Value

status

Object

Required/Optional Required

Description
See Table 1 Status Response Object on page 10

Remove Device

Remove a device from the system.
Example Delete DELETE: https://<hostname>/trifecta/v1/devices/123456789
Response Format

Table 17 Remove Device/Configuration/Task/File Response Object

Name

Value

Required/ Optional

Description

status

Object

Required

See Status Response Object

results

Object

Required

null

Update Device Information
Change information regarding a device in the system. Example Patch PATCH: https://<hostname>/trifecta/v1/devices/123456789

22

Devices

BODY:

{ "position": { "x": 0, "y": 0, "z": 0 }
}
Body Format See Device Object
Response Format See Add/Update Device Response Object

Query Device by Device ID

Query the information regarding a single device using the device ID.
Example Query GET: https://<hostname>/trifecta/v1/devices/1234567890
Response Format

Table 18 Device Response Object

Name

Value

status status

Object Object

Required/ Optional
Required
Required

Description
See Status Response Object See Device Object

23

Devices

Table 19 Device Object

Name

Value

deviceId

string

deviceModel

string

serialNumber siteId name network position
x y z antennas

string string string object object number number number array

lastSeen

string

lastStatus state

object object

configId

string

version

object

region

object

orientation

object

raw number

pitch number

yaw number

hostName

string

gpioStatus

object

Required/ Optional Required
Optional
Optional Optional Optional Optional Optional

Description
Unique identifier for device (not available when creating or updating a device) Device Mode type (ATR7000, FX9600, FX7500, SNAP) Serial Number of the device Unique Identifier for the site of the device User-supplied name for the device See Table 20 Network Object on page 25 Position of the device in relation to its site x

Optional Optional
Optional Optional
Optional Optional Optional Optional
Required Optional

Array of antenna objects. See Table 21 Antennas Object on page 25
Timestamp of the last time the system was in contact with the device (not available when creating or updating a device)
See Table 22 Last Status Object on page 26 (not available when creating or updating a device)
State of the device (added, initialized, running, stopped, updating, rebooting, failure) (not available when creating or updating a device)
Unique Identifier for the device configuration
See Table 27 Version Object on page 31
See Table 28 Region Object on page 31
Orientation of the device in relation to its site
In degrees
In degrees
In degrees
Default Device Hostname (required when creating a device)
Array of GPIO Status objects. See Table 29 GPIO Status Object on page 32

24

Devices

Table 20 Network Object

Name

Value

macAddress dhcp dnsAddress subnetMask gatewayAddress ipAddress

string bool string string string string

Required/ Optional Required Required Required Required Required

Description
MAC address of the device
DNS address of the device Subnet mask of the device Gateway address of the device IP Address of the device

Table 21 Antennas Object Name
name
gain port
position
x y z state

orientation
type cableLoss

raw pitch yaw

Value string number integer object number number number string
number number number string number

Required/ Optional Required
Optional Optional
Optional

Description
User-supplied name for the antenna
Gain of the antenna (in db)
Reader port that the antenna is connected to
Position of the antenna in relation to its site

Optional Optional
Required Optional

Indicates if the antenna is connected to or disconnected from the port
Orientation of the antenna in relation to its site
In degrees
In degrees
In degrees
Type of antenna
Loss (in db) of the cable connecting the antenna to the port

25

Devices

Table 22 Last Status Object Name
radioControl status cpu ram uptime radioActivity radioConnection
readerGateway
system
userApps

Value object string number number string string string
object
object

Required/ Optional Required Required Required Required Required Required Required
Required
Required
Optional

Description
Status of Radio Control (running or stopped)
Radio Control % CPU utilization
Radio Control % RAM utilization
Radio Control uptime
Radio activity status (running or stopped)
Radio connection status (connected or disconnected)
See Table 23 Reader Gateway Status Object on page 27
See Table 24 System Status Object on page 28
See Table 26 User Application Object on page 30

26

Devices

Table 23 Reader Gateway Status Object

Name

Value

cpu

number

ram

number

uptime numDataMessagesRxed

string number

numDataMessagesTxed

number

numDataMessagesRetained number

numDataMessagesDropped number numManagementEventsTxed number

Required/ Optional Optional Optional Optional Optional Optional
Optional
Optional Optional

Description
Reader Gateway % CPU utilization
Reader Gateway % RAM utilization
Reader Gateway uptime
Number of data messages received by Reader Gateway
Number of data messages transmitted by Reader Gateway
Number of data messages currently retained by Reader Gateway
Number of data messages dropped by Reader Gateway
Number of management events transmitted by Reader Gateway

27

Devices

Table 24 System Status Object Name

cpu system user
ram used

free

total

flash platform

used

free

total

readerConfig used

free

total

readerData

used

free

total

rootFileSystem used

free

total

Value object integer integer object integer integer integer object object integer integer integer object integer integer integer object integer integer integer object integer
integer
integer
28

Required/ Optional Optional Required Required Optional Required
Required
Required
Optional Required Required
Required
Required
Required Required
Required
Required
Required Required
Required
Required
Required Required
Required
Required

Description
% of system CPU % of user CPU
Number of bytes used in RAM Number of bytes free in RAM Total number of bytes in RAM
Number of bytes used in partition flash partition Number of bytes free in partition flash partition Total number of bytes in partition flash partition
Number of bytes used in reader config flash partition Number of bytes free in reader config flash partition Total number of bytes in reader config flash partition
Number of bytes used in reader data flash partition Number of bytes free in reader data flash partition Total number of bytes in reader data flash partition
Number of bytes used in root file system flash partition Number of bytes free in root file system flash partition Total number of bytes in root file system flash partition

Devices

Table 25 System Status Object (continued)

Name

Value

uptime ntp

reach

string object number

temperature

offset pa

number object number

ambient systemTime powerSource powerNegotiation

number string string string

Required/ Optional Optional Optional Required
Required Optional Required
Required
Optional
Optional
Optional

Description
System uptime
NTP Reach value (octal value 0 ­ 377)
Clock offset in milliseconds
Radio Power Amplifier temperature (in degrees Celsius)
Radio Ambient temperature (in degrees Celsius)
Current system time on the device
Power source of system (DC, POE, POE+)
Power Negotiation of the system (DISABLE, IN_PROGRESS, SUCCESS, FAILURE, NOT_APPLICABLE)

29

Devices

Table 26 User Application Object Name
appname status

Value
string string

cpu ram uptime numDataMessagesRxed

number number string number

numDataMessagesTxed

number

incomingDataBuffer PercentageRemaining
outgoingDataBuffer PercentageRemaining

number number

Required/ Optional Required Required
Optional Optional Optional Optional
Optional
Optional
Optional

Description
Application name
Status of application (running or stopped)
Application % CPU utilization
Application % RAM utilization
Application uptime
Number of data messages received by application
Number of data messages transmitted by application
% input data buffer remaining for application
% output data buffer remaining for application

30

Devices

Table 27 Version Object Name
readerApplication radioAPI radioFirmware radioControlApplication readerOS readerHardware readerBootLoader readerFileSystem cloudAgentApplication
Table 28 Region Object Name
region
regulatoryStandard lbtEnabled channelData maxTransmitPower

Value string string string string string string string string string

Required/ Optional Required
Required Required Required
Optional
Required
Required
Required
Optional

Description
Version of the reader application
Version of the radio API
Version of the radio firmware
Version of the Radio Control Application
Version of the reader Operating System
Version of the reader hardware
Version of the reader bootloader
Version of the reader filesystem
Version of the Cloud Agent Application

Value string
string bool Array of numbers number

Required/ Optional Required
Optional Required Optional

Description
Region the Device is being used (for example, United States)
Regulatory Standard (for example, FCC)
Listen Before Talk (LBT) enabled or disabled
List of Channel Frequencies

Optional

Maximum Conducted Transmit power (dbm)

31

Devices

Table 29 GPIO Status Object

Name

Value

port state

integer bool

direction

string

Required/ Optional Optional Optional
Optional

Description
GPIO Port Indicates the state of the GPIO port (False means low and True means high) Input or Output

Query Devices by Site

Query for the information of all devices in a site.
Example Query GET: https://<hostname>/trifecta/v1/devices?$siteId=1234567890
Response Format

Table 30 Multiple Devices Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Array

Required

Description
See Status Response Object See Device Object

Query Devices by Device Model
Query for the information of all devices matching a device model. Example Query GET: https://<hostname>/trifecta/v1/devices?$deviceModel=FX9600 Response Format See Multiple Devices Response Object
Query Devices by Device State
Query for all devices that are in a particular state. Example Query GET: https://<hostname>/trifecta/v1/devices?$deviceState=running Response Format See Multiple Devices Response Object

32

Devices
Query Devices by Device Model and Site
Query by device model for a specific site. Example Query GET: https://<hostname>/trifecta/v1/devices? $deviceMode=FX9600&siteId=1234567890 Response Format See Multiple Devices Response Object
Query All Devices
Query All Devices NOTE: This may return a significant amount of data.
Example Query GET: https://<hostname>/trifecta/v1/devices
Response Format See Multiple Devices Response Object
33

Device Configuration

Device Configuration
This section provides examples of device configuration commands.

Add Device Configuration
Add new device configuration to the system.

Example POST POST: https://<hostname>/trifecta/v1/configurations
BODY Format: See Configuration Object
Example Response

Table 31 Add/Update Device Configuration Response Object

Name

Value

Required/ Optional

Description

status

Object

Required

See Status Response Object

results

Object

Required

URL

String

Required

URL to get configuration information

Remove Device Configuration
Remove a device configuration from the system. Example Delete DELETE: https://<hostname>/trifecta/v1/configurations/1234567 Response Format See Remove Device/Configuration/Task/File Response Object
Update Device Configuration
Change device configuration. Example Patch PATCH: https:///trifecta/v1/devices/configurations/1234567

34

Device Configuration

BODY Format See Configuration Object
Response Format See Add/Update Device Configuration Response Object

Query Device Configurations by Configuration ID

Query for information about a particular configuration.
Example Query https://<hostname>/trifecta/v1/devices/configurations/1234567890
Response Format

Table 32 Configuration Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Object

Required

Description
See Status Response Object See Configuration Object

35

Device Configuration

Table 33 Configuration Object

Name

Value

configId

string

xml

string

mode
gpioLed events
batching
retention
userApps name certificates
dataEndpoints

object
object object
object
object
array string array
object

Required/Optional Required in Responses Optional
Optional Optional Optional Optional Optional Optional Optional Optional Optional

Description
Unique identifier for the configuration.
Exported XML configuration from the reader. Details on exporting the reader's XML configuration can be found in the FX Series RFID Fixed Reader Integration Guide . This format is internal to the reader and subject to change. It is recommended XML is used only for replicating settings from one reader to one or more other readers.
NOTE: XML field should not be included in cases where the deployment uses unique settings on each reader such as static IP, unique name/location, unique passwords etc.
Operation mode configuration (see https:// zebradevs.github.io/rfid-ziotc-docs/schemas/ operating_modes/index.html)
Configuration of Asynchronous Management Events (see https://zebradevs.github.io/rfid-ziotcdocs/schemas/cloud_config/index.html#)
Data message batching configuration (see https:// zebradevs.github.io/rfid-ziotc-docs/best_practices/ tag_data/index.html#tag-data-batching)
Data message retention configuration (see https:// zebradevs.github.io/rfid-ziotc-docs/best_practices/ tag_data/index.html#tag-data-retention)
An array of strings listing the user apps used for this device configuration
User-supplied name for the configuration.
Configuration of certificates to be used for data endpoints (see https://zebradevs.github.io/rfidziotc-docs/schemas/endpoint_config/index.html#)
Configuration of data endpoints (see https:// zebradevs.github.io/rfid-ziotc-docs/schemas/ endpoint_config/index.html#)

Query Device Configurations by Site
Query for configurations applicable at a site. Example Query https://<hostname>/trifecta/v1/devices/configurations?$siteId=1234567

36

Device Configuration

Response

Table 34 Multiple Configurations Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Array

Required

Description
See Status Response Object See Configuration Object

Query Device Configurations by Device Model
Query for configurations applicable to a device model. Example Query https://<hostname>/trifecta/v1/devices/configurations/? $deviceModel=FX9600 Response Format See Multiple Configurations Response Object
Query Device Configurations by Device State
Query for configurations for devices that are in a particular state. Example Query https://<hostname>/trifecta/v1/devices/configurations? $deviceState=running Response Format See Multiple Configurations Response Object
Query Device Configurations by Device Model and Site
Query for configurations by device model for a specific site. Example Query https://<hostname>/trifecta/v1/devices/configurations? $deviceMode=FX9600&siteId=1234567890 Response Format See Multiple Configurations Response Object
Query All Device Configurations
NOTE: This may return a significant amount of data.
Example Query https://<hostname>/trifecta/v1/devices/configurations
Response Format See Multiple Configurations Response Object

37

Device Tasks

Device Tasks
This section provides examples of device task commands.

Add Device Task

Add new device task to the system.
Example POST POST: https://<hostname>/trifecta/v1/devices/tasks BODY Format: See Table 37 Task Object on page 40
Response Format

Table 35 Add/Update Device Task Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Object

Required

URL String

Required

Description See Status Response Object URL to get task information

Remove Device Task
Remove a device task from the system. Example Delete DELETE: https://<hostname>/trifecta/v1/devices/tasks/123456789 Response Format See Remove Device/Configuration/Task/File Response Object
Update Device Task
Change device task. Example Patch PATCH: https:///trifecta/v1/devices/task/123456789 BODY Format See Task Object

38

Device Tasks

Response Format See Add/Update Device Task Response Object

Query Device Tasks by Task ID

Query for information about a task by task ID.
Example Query GET: https://<hostname>/trifecta/v1/devices/tasks/1234567890
Response Format

Table 36 Task Response Object

Name

Value

status results

Object Object

Required/ Optional
Required
Required

Description
See Status Response Object See Device Object

39

Device Tasks

Table 37 Task Object Name
id
description devices
startDateTime

fileId

action status enabled siteId deviceModel

params

color flash

seconds

Value string string array string
string
string string bool string string
object string bool
integer

Required/ Optional Required in Response Optional Optional Optional
Optional
Required Required Required Optional Optional
Optional Optional Optional
Optional

Description
Unique identifier for the task
Description of task
Array of device ids to perform the task
ISO 8601 format of local server time to begin the task. If not provided, the task begins immediately
File Identifier of the file to use when using update or install action
Action to take (update, reboot, install, start, stop, set-led)
Status of task (In progress, Complete, Pending)
Indicates if the task is currently enabled
Site Identifier of the site to apply to task all devices
Device Model upon which to perform the task (ATR7000, FX9600, FX7500)
Used when action is set-led to set the LED color
Used when action is set-led to set enable/disable flashing LED
Used when action is set-led to indicate the duration of the set-led action

Query Device Task History by Task ID
Query for the history of a particular task. Example Query https://<hostname>/trifecta/v1/devices/tasks/1234567890/history

40

Device Tasks

Response Format

Table 38 Multiple Tasks Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Array

Required

Description
See Status Response Object See Device Object

Query Device Tasks by Device
Query for tasks applicable to a particular device. Example Query https://<hostname>/trifecta/v1/devices/tasks?$deviceId=1234567890 Response Format See Multiple Tasks Response Object
Query Device Tasks by Site
Query for tasks applicable at a site. Example Query https://<hostname>/trifecta/v1/devices/tasks?$siteId=1234567890 Response Format See Multiple Tasks Response Object
Query Device Tasks by Device Model
Query for tasks applicable to a device model. Example Query https://<hostname>/trifecta/v1/devices/tasks/?$deviceModel=FX9600 Response Format See Multiple Tasks Response Object
Query Device Tasks by Status
Query for tasks that are in a particular state. Example Query https://<hostname>/trifecta/v1/devices/tasks?$taskStatus=completed Response Format See Multiple Tasks Response Object

41

Device Tasks
Query Device Tasks by Action
Query for tasks with a particular action. Example Query https://<hostname>/trifecta/v1/devices/taks?$taskAction=update Response Format See Multiple Tasks Response Object
Query Device Tasks by Device Model and Site
Query for configurations by device model for a specific site. Example Query https://<hostname>/trifecta/v1/devices/taks? $deviceModel=FX9600&siteId=1234567890 Response Format See Multiple Tasks Response Object
Query All Device Tasks
Query all device tasks. NOTE: This may return a significant amount of data.
Example Query https://<hostname>/trifecta/v1/devices/tasks
Response Format See Multiple Tasks Response Object
42

Files

Files
This section provides examples of file commands.

Add File
Add a new file to the system. EXAMPLE POST POST: https://<hostname>/trifecta/v1/files BODY: form-data

Table 39 File Post Object

Key

file

File

fileName

Text

fileVersion

Text

deviceModel

Text

Type

description

Text

fileType

Text

Value File to upload Name of file Version of file Device Model file is appropriate for (ATR7000, FX9600, FX7500) Description of the file Type of file (firmware, app, certificate, generic)

Response Format

Table 40 Add/Update File Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Object

Required

URL

String

Required

Description See Status Response Object URL to get File information

43

Files

Remove File
Remove a file from the system. Example Delete DELETE: https://<hostname>/trifecta/v1/files/123456789 Response Format See Remove Device/Configuration/Task/File Response Object
Update File Properties
Change file properties. Example Patch PATCH: https://<hostname>/trifecta/v1/files//123456789/properties

BODY: {
"fileName": "myNewFileName", "fileVersion": "0.1.2", "deviceModel": "FX9600", "fileType": "firmware", "description": "my new file", }
Response Format See Add/Update File Response Object

Query File Properties by File ID

Query file properties using a File ID.
Example Get GET: https://<hostname>/trifecta/v1/files//123456789/properties See Table 43 Get Multiple Files Properties Response Object on page 45
Response Format

Table 41 Get File Properties Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Object

Required

Description
See Status Response Object See Table 42 File Properties Object on page 45

44

Files

Table 42 File Properties Object

Name

Value

fileId deviceModel

Object Object

fileName fileVersion fileType

string string string

uploadedAt

string

description fileSize

string integer

Required/ Optional Required Required
Optional Optional Required
Required
Optional Required

Description
Unique identifier for the file Device Model file is appropriate for (ATR7000, FX9600, FX7500) Name of file Version of file Type of file (firmware, app, certificate, generic) ISO 8601 format of time when file was uploaded User provided description of file Size of file in bytes

Query File Properties by Device Model

Query for files by device model and file type.
Example Query GET: https://<hostname>/trifecta/v1/files?$deviceMode=FX9600
Response Format

Table 43 Get Multiple Files Properties Response Object

Name

Value

Required/ Optional

status

Object

Required

results

Array

Required

Description
See Status Response Object See File Properties Object

Query File Properties by Device Model and File Type
Query for files by device model and file type. Example Query GET: https://<hostname>/trifecta/v1/files? $deviceMode=FX9600&fileType=firmware Response Format See Get Multiple Files Properties Response Object
Get File by file ID
Get binary file. Example Query GET: https://<hostname>/trifecta/v1/files/123456789

45

Files
Response Format File in binary format.
Query All File Properties
Query all file properties. NOTE: This may return a significant amount of data.
Example Query https://<hostname>/trifecta/v1/files
Response Format See Get Multiple Files Properties Response Object
46

www.zebra.com



References

• Patents
• Copyright and Trademarks | Zebra
• Software Product Categories and End User License Agreements | Zebra
• Legal | Zebra
• Product Warranty Information | Zebra
• Local Deployment REST API Guide — Zebra IoT Connector documentation
• Best practices for Tag Data Interface — Zebra IoT Connector documentation
• Best practices for Tag Data Interface — Zebra IoT Connector documentation
• Endpoint Configuration and Mapping Schemas — Zebra IoT Connector documentation