Configure and Commission Large Batches of Tags

The tags for Quuppa systems are usually taken into use by configuring and commissioning then using the Quuppa Site Planner (QSP) software and a Focusing Locator. However, for large-scale deployments with large volumes of tags, it's also possible to configure and commission the tags directly using the Quuppa APIs, without the QSP and a Focusing Locator. This document will describe this process of taking the tags into use without needing to use the QSP or the Focusing Locator.

Tip: For more information about this method and access to an example code, please visit our Github page at https://github.com/quuppalabs.

Prerequisites

In order to complete the steps below successfully, you will need to:

Use tags that are compatible with this method - use Quuppa QT1-1 Tags with tag firmware version 10.037 or above. Quuppa Partner Tags using Quuppa Tag Firmware Library 1.2 (shown as tag firmware 10.042) can also be used to implement this feature. However, please note that changes to the tag pre-configurations, such as the default channels that the tag transmits on (Quuppa proprietary channels at 2478Mhz and 2481MHz and Bluetooth® channel 37) may affect compatibility with this method.
Be familiar with the Quuppa software suite, including the Quuppa Site Planner (QSP) and the Quuppa Positioning Engine (QPE).

Configure a Batch of Tags

Active the tag by pressing the button while it is within the coverage area of the Locators.

Note: If you are using Quuppa Partner tags instead of the Quuppa QT1-1 tag, please check the manufacturers instructions for more details on how to activate them (e.g. NFC or shaking).

Use the Get Tag Data API to detect any unknown tags with a tagGroupName of null, as shown in the example below.

{
  "code": "0",
  "status": "Ok",
  "command": "http://192.168.50.1:8080/qpe/getTagData?format=defaultLocation&humanReadable=true&maxAge=10000",
  "message": "Tag data",
  "responseTS": 1647266872723,
  "version": "1.0",
  "formatId": "defaultLocation",
  "formatName": "defaultLocation",
  "tags": [
    {
      "tagId": "a4da22e4e75d",
      "tagName": null,
      "color": "#FF0000",
      "tagGroupName": null,
      "locationType": "proximity",
      "locationMovementStatus": "stationary",
      "locationRadius": 16.00,
      "location": [19.86,1.63,1.20],
      "locationTS": 1647266868846,
      "locationCoordSysId": "619fdd07-d7d7-40a1-98cb-48b95b802057",
      "locationCoordSysName": "Quuppa HQ:111983487",
      "locationZoneIds": null,
      "locationZoneNames": null
    }
}

Use the Configure Tag API to configure all unknown tags with the appropriate tag configuration. In the example below, the tag is configured with the ASSET_TAG configuration and to use channel 230 (i.e. the Quuppa proprietary channel on 2481 MHz).
```
{
  "commanded":["a4da22e4e75d"],
  "code":0,
  "responseTS":1610980253741,
 "message":"Commanding 1 tag(s), skipped 0 Tag(s)",
  "version":"1.0",
  "command":"http://192.168.50.1:8080/qpe/configureTag?tag=a4da22e4e75d&id=ASSET_TAG&channel=230",
  "status":"Ok"
}
```
Note: For information about creating custom tag configurations, please refer to our QSP User Manual's Create a New Tag Configuration section.

Use the Get Tag Data API to verify that the tag configuration was completed successfully. Check that the configStatus is done and the configStatusTS (i.e. timestamp for the status) is recent enough as shown in the example below. Note that it may take several seconds and multiple polls to get the confirmation that the configuration was successful.

{
  "code": "0",
  "status": "Ok",
  "command": "http://192.168.50.1:8080/qpe/getTagData?format=defaultInfo&tag=a4da22e4e75d&humanReadable=true&maxAge=10000",
  "message": "Tag data",
  "responseTS": 1647332271182,
  "version": "1.0",
  "formatId": "defaultInfo",
  "formatName": "defaultInfo",
  "tags": [
    {
      "tagId": "a4da22e4e75d",
      "tagName": null,
      "lastPacketTS": 1647332269229,
      "color": "#FF0000",
      "tagGroupName": null,
      "batteryVoltage": 3.11,
      "batteryVoltageTS": 1647332264153,
      "batteryAlarm": "ok",
      "batteryAlarmTS": 1647332269229,
      "txPower": 0,
      "txPowerTS": 1647332266181,
      "txRate": 1.0,
      "txRateTS": 1647332266181,
      "button1State": "notPushed",
      "button1StateTS": 1647332269229,
      "button1LastPressTS": null,
      "tagState": "triggered",
      "tagStateTS": 1647332266181,
      "stateTransition": "normal",
      "stateTransitionTS": 1647332266181,
      "fwVersion": 0.000,
      "triggerCount": 171,
      "triggerCountTS": 1647332268211,
      "ioStates": ["low","low","low","low"],
      "ioStatesTS": 1647332266181,
      "rssi": 32,
      "rssiLocatorCount": 6,
     "configStatus": "done",
      "configStatusTS": 1647332271054,
      "locationCoordSysId": "619fdd07-d7d7-40a1-98cb-48b95b802057",
      "locationCoordSysName": "Quuppa HQ:111983487"
    }
}

Note: You can use the QSP to create a new custom data format that includes both the configStatus and configStatusTS parameters and any others that you are interested in. For more details, please refer to the API Data Formats & Output Targets section of our QSP User Manual.

Assign the configured tags to an appropriate tag group within your project. In the example below, the tags are assigned to a tag group called Assets.

{
  "code": 0,
  "command": "http://192.168.50.1:8080/qpe/setTagGroup?targetGroup=Assets&tag=a4da22e4e75d&humanReadable",
  "message": "1 Tags moved to Assets",
  "responseTS": 1505725561162,
  "status": "Ok",
  "version": "1.0"
}

Save the new tag group information to the project file. For more details, see the Manage the Tags section below.
Note: A new tag group can not be created through the API. A tag group must exist within the project (synchronised with the QPE) before a tag can be assigned to it. Any tags assigned to a tag group while the system is running won't automatically be saved to the project file. So to retain any newly applied settings it's important to also save them to the project file.

Manage the Tags

To retain any tag group changes that you applied while the system was running (using the method shown in the above section), the changes will also need to be saved to the project file itself. To do so, you can either use the Import Tags API to import the tag data to the QPE during run-time/start-up or use the Import Tags feature in the QSP to import and save the tags into the project file. This section will cover the option using the APIs.

Export tags from the currently running QPE instance using the Export Tags API. The example below shows all of the tag IDs being exported in JSON format into an autostart file with the .quuppatagjson extension (for more options, please see our API documentation).
```
{
  "code": 0,
  "command": "http://192.168.50.1:8080/qpe/exportTags?humanReadable&filename=autostart",
  "message": "974 Tags written to /opt/quuppa/PE/tags/autostart.quuppatagjson, new file created",
  "responseTS": 1647342807747,
  "status": "Ok",
  "version": "1.0"
}
```
Use the Import Tags API to import the tag data into the running QPE. If you have created an autostart file in the QPE's project folder, the QPE will automatically import the tag data from the file during start-up. The example below shows this process.
```
{
  "code": 0,
  "command": "http://192.168.50.1:8080/qpe/importTags?filename=autostart&humanReadable",
  "message": "Tags imported from file  /opt/quuppa/PE/tags/autostart.quuppatagjson",
  "responseTS": 1647343149625,
  "status": "Ok",
  "version": "1.0"
}
```
Note: Alternatively, you can use the QSP to import the tag file and save the information directly into the project file. For more information about this method, please refer to our QSP User Manual's Import an Existing Tag Configuration section.