10. AoX Application

This chapter contains cluster definitions used to support the AoX application. These cluster definitions are unique to the Unify Controller Language. This is an addition to the clusters already defined in the ZCL.

10.1. Terminology

We define here several entities as part of an AoX system:

• Assets Tags

  Assets tags are radio devices sending unencrypted radio beacons that allow to triangulate assets.

• AoX Protocol Controller / Locator

  The AoXPC is a component that processes incoming radio beacons, converts them into IQ Reports or Angle reports, which will allow another component to compute the position of the device. A locator is a part of the AoX Protocol Controller, it is basically an NCP with a configuration that will help to determine the relative position of an asset tag.

• AoX Positioning Service

  This is essentially a helper component (like the SmartStart list manager) that reads the data reported from the locators and will compute and publish the absolute position of each tag.

The system can be seen as follows:

10.2. AoX Clusters

This section defines how to represent Angle-of-X (e.g, Angle of Arrival) IQ report, Angle, and Position data in the Unify Framework.

The AoX system relies on several new clusters:

• AoXLocator, used to manage locator devices within the AoXPC.

• AoXPositionEstimation, used to report Assets estimated position.

10.2.1. Locators and the AoXLocator cluster

The AoX Protocol Controller allows to read the configuration of its Locator using the AoXLocator Cluster. For example, an AoX Protocol Controller could advertise it like this:

ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/Attributes/PositionAndOrientationValid/Desired - {"value": true}
ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/Attributes/PositionAndOrientationValid/Reported - {"value": true}
ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/Attributes/PositionAndOrientation/Desired - {
  "value": {
    "CoordinateX": 3.75,
    "CoordinateY": 0,
    "CoordinateZ": 1.25,
    "OrientationX": 50,
    "OrientationY": 0,
    "OrientationZ": 0
  }
}
ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/Attributes/PositionAndOrientation/Reported - {
  "value": {
    "CoordinateX": 3.75,
    "CoordinateY": 0,
    "CoordinateZ": 1.25,
    "OrientationX": 50,
    "OrientationY": 0,
    "OrientationZ": 0
  }
}

The PositionAndOrientation represents the location of the NCP radio for the AoX locator. CoordinateX, CoordinateY, CoordinateZ are cartesian coordinates, in meters. OrientationX, OrientationY and OrientationZ are the axis rotation (Euler angles) in degrees. More details are provided in Silicon Labs RTL Locator item

The additional PositionAndOrientationValid boolean attribute indicates if the locator PositionAndOrientation attributes has been set and the reported values reported are correct.

A subscription to ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/Attributes/# will allow to read the entire configuration and possibly write back the configuration that is writable.

The AoXLocator Cluster can be configured using the AoXLocator cluster WriteAttributes command.

ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/SupportedCommands - {"value": ["AngleCorrection", "WriteAttributes"]}
ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/SupportedGeneratedCommands - {"value": ["IQReport"]}

An AoX Protocol Controller MUST generate an IQReport or an AngleReport Command for every radio beacon that has been received by a locator.

ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/GeneratedCommands/IQReport - {
  "TagUnid" : "ble-pd-842E1431C9F0",
  "Channel": 13,
  "Rssi": -50,
  "Sequence": 42767,
  "Samples": [23, 105, 106, -10, 2, -108]
}

Or

ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/GeneratedCommands/AngleReport -
{
  "Deviation": {
    "Azimuth": 0,
    "Distance": 0,
    "Elevation": 0
  },
  "Direction": {
    "Azimuth": -6.4180755615234375,
    "Distance": 1.5519763231277466,
    "Elevation": 51.71907043457031
  },
  "Sequence": 42767,
  "TagUnid": "ble-pd-842E1431C9F0"
}

In the AngleReport commands, Direction represents the measured angle data while Deviation indicates the standard deviation of the that measurement. Both Direction and Deviation are spherical coordinates. In sphrical coordinates objects, the Azimuth and Elevation are in degrees and the Distance is in meter.

More details about how to interpret the values in the IQReports or AngleReports are given in Silicon Labs RTL Library and Silicon Labs User Guide 103.18

Each locator will generate ‘IQReport’ or ‘AngleReport’. Locators supporting both modes will advertise which mode is configured using the ReportingMode attribute configuration. If the ReportingMode attribute is not writable, it will not be advertised and instead IoT Services will be able to know what commands are generated reading the value published at the SupportedGeneratedCommands topic:

ucl/by-unid/<aoxpc_unid>/ep0/AoXLocator/SupportedGeneratedCommands - {"value": ["AngleReport"]}

For example, the following diagram shows an example of configuring which commands are generated by a locator.

10.2.1.1. AngleCorrection Command

For calibration and accuracy purposes, AoX locators generating AngleReport commands SHOULD support receiving the AngleCorrection command. The AngleCorrection command will indicate what values are expected for a given asset tag to an AoX locator.

Details on applying angle correction are given in Silicon Labs RTL Library: Get expected direction

10.2.2. AoXPositionEstimation cluster

A Positioning Service helper MQTT client can be used to listen to MQTT publications coming from the AoXLocator cluster to determine the position of each tag in the system.

The Positioning Service does not have a UNID itself. It connects to the MQTT broker, and performs the following actions:

1. Read/Write the configuration:

1. Reads the configuration for each AoXPC / Locator, using a subscription to ucl/by-unid/+/+/AoXLocator/Attributes/+/Reported

2. Optionally adjusts the configuration issuing WriteAttributes Command ucl/by-unid/+/+/AoXLocator/Commands/WriteAttributes

2. Listen to incoming IQReport or AngleReports by subscribing to: ucl/by-unid/+/+/AoXLocator/GeneratedCommands/+

Whenever position data for a tag is available, the Positioning Service MUST publish the calculated Position attribute in the AoXPositionEstimation Cluster.

ucl/by-unid/<TAG_UNID>/ep0/AoXPositionEstimation/Attributes/Position/Reported -
  {
  "value": {
    "ApplicationId": "positioning_4154",
    "DeviationX": 3.1297969818115234,
    "DeviationY": 0.6999226212501526,
    "DeviationZ": 3.8446271419525146,
    "Sequence": 47021,
    "X": 0.8519021272659302,
    "Y": 0.000349800189724192,
    "Z": 0.8335742950439453
  }
}

In the Position attribute, Coordinate components (X, Y, etc.) unit is Meter.

The first time that a tag’s position is determined, or a new tag is detected, the Positioning Service application MUST publish a node state topic for that tag.

ucl/by-unid/<TAG_UNID>/State - {
  "NetworkStatus": "Online functional",
  "Security": "None",
  "MaximumCommandDelay": "unknown"
}

When a Positioning Service application shuts down, it MUST unretain all the AoXPositionEstimation and State data that it published for tags.

10.2.3. Positioning Service

The Positioning Service is a helper component that can determine spatial coordinates, or position, for each tag UNID and publises the last reported position.

10.2.4. Asset Tag UNIDs

Asset Tag UNIDs MUST indicate the BLE address type in addition to the BLE address. The generic format is ble-<ADDRESS_TYPE>-<BLE_ADDRESS>. Refer to Unify Architecture Overview for details about UNID composition. Static random addresses can be abbreviated sr and public device addresses pd.

An example of a public device address UNID is ble-pd-842E1431C9F0.