8. Binding

This chapter describes how to use the binding functionality in Unify.

The unify binding feature can be used by an IoT service / rules engine to impose direct rules between nodes on the PAN or even for nodes between PAN and wireless protocols. The benefit of the direct rules are a binding between two nodes in the same network will impose less network latency compared to a star topology where all events needs to be passed though an IoT service. Another benefit is that in the event of the a protocol controller going offline the binding rules setup in the network will still work.

The Unify Binding framework also features a system to identify which nodes can be bound. Care must be taken when IoT services setup bindings, because the Protocol Controllers will not sanitise whether a binding is safe from a security perspective.

An IoT service MUST verify what a binding is acceptable from a security perspective before setting up the binding.

8.1. Establishing a binding

The main use case of a binding is to have a PAN node cluster client issue commands directly to another PAN node cluster server.

An example is shown below.

8.2. Binding object

A binding consists of the following elements/fields

• SourceUnid:

  The UNID of the client node that will issue commands to the server.

  This information will be found in the topic used to issue the command or read the attributes

• SourceEp:

  The Endpoint ID of the client node that will issue commands to the server

  This information will be found in the topic used to issue the command or read the attributes

• ClusterName:

  The name of the ClusterID of the client node that will issue commands to the server

• DestinationUnid:

  The UNID of the server node that will receive commands from the client

• DestinationEp:

  The Endpoint ID of the server node that will receive commands from the client

There is no real control over what triggers which commands from the client to the server. For example, an OccupancySensor server that is also an OnOff cluster client may decide to send On commands to bound device when OccupancySensing is True and Off when False, or vice-versa.

8.2.1. MQTT Topics and Parameters

Table 8.1 Binding MQTT Topics

MQTT Topic	Description
ucl/by-unid/+/+/Binding/Commands/<CommandName>	Command topic space. IoT services can publish under this topic. See the XML file for command definitions.
ucl/by-unid/+/+/Binding/Attributes/<AttributeName>/Reported	Used to publish the standard and additionnal attributes of the cluster. See the XML file for attributes definitions.
ucl/by-unid/+/+/Binding/Attributes/<AttributeName>/Desired	Used to publish the standard and additionnal attributes of the cluster. See the XML file for attributes definitions.
ucl/by-unid/+/+/Binding/SupportedCommands	Used to publish the supported commands.
ucl/by-unid/+/+/Binding/SupportedGeneratedCommands	Used to publish the supported generated commands.
ucl/by-unid/+/+/Binding/GeneratedCommands/<CommandName>	Used to publish the generated commands.

8.2.2. Additional attributes

This cluster makes use of several additional attributes. These attributes are not present in the XML file.

8.2.2.1. Binding Table

A binding table will be kept by each PAN node, keeping track of the established bindings.

The value of the binding table is an array of binding objects. Each binding object consists in a Cluster ID, Destination UNID and Destination Endpoint.

For example:

ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindingTable/Reported -
  { "value": [
      {"ClusterName" : "OnOff", "DestinationUnid": "node_2", "DestinationEp": 1},
      {"ClusterName" : "OnOff", "DestinationUnid": "node_2", "DestinationEp": 2},
      {"ClusterName" : "Level", "DestinationUnid": "node_2", "DestinationEp": 2}]
  }

The JSON schema for the BindingTable MUST be as follows:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Binding Table",
  "description": "Binding Table",
  "definitions": {
    "Binding Table Entry": {
      "type": "object",
      "properties": {
        "ClusterName": {
          "type": "string",
          "minLength": 1
        },
        "DestinationUnid": {
          "type": "string",
          "minLength": 1
        },
        "DestinationEp": {
          "type": "integer",
          "minimum": 0,
          "maximum": 254
        }
      },
      "required": [
        "ClusterName",
        "DestinationUnid",
        "DestinationEp"
      ]
    }
  },
  "type": "object",
  "properties": {
    "value": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Binding Table Entry"
      }
    }
  },
  "required":["value"]
}

8.2.2.2. Discovering what can be bound

Protocol Controller MUST advertise the list of available Clusters for binding for each PAN node. The BindableClusterList attribute indicates an array of Cluster IDs that can be used for Binding Commands.

If the list of Cluster IDs that can be bound is unknown to the Protocol Controller, it MUST NOT publish any Binding capabilities for that UNID/Endpoint.

ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindableClusterList/Desired - { "value": ["OnOff", "Level"]}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindableClusterList/Reported - { "value": ["OnOff", "Level"]}

The JSON schema for this topic MUST be as follows:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Binding Cluster ID list",
  "description": "Binding Cluster ID list",
  "type": "object",
  "properties": {
    "value": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    }
  },

  "required":["value"]
}

IoT Service SHOULD NOT attempt to bind a node to a destination, if the destination does not have any Attributes or SupportedCommands for the Cluster used in the binding.

Protocol Controller MUST reject bindings if the destination cannot receive commands from the cluster defined in the binding.

8.3. Binding levels

When a binding is estalished in the Unify system, it is possible that the 2 nodes cannot communicate directly with each other.

Therefore, an IoT Service requesting to Bind 2 nodes can lead to 3 (hidden) substates

• Direct PAN binding

  When such a binding is established, 2 nodes will communicate directly with each other and no Protocol Controller will be involved.

• Intra Protocol Controller binding

  The 2 nodes cannot communicate directly with each other, but are serviced by the same Protocol Controller and therefore the Protocol Controller can “relay” messages.

• Inter Protocol Controller binding

  The 2 nodes have 2 different Protocol Controllers and therefore the Protocol Controllers will need to send commands to each other to make the binding work.

Both Intra and Inter Protocol Controller Bindings may be treated the same way by a Protocol Controller, which can publish a Command to the destination UNID/Ep using the MQTT command space.

If the Protocol Controller itself is servicing the destination, it will receive its own command publication and proceed with sending the command to the destination.

Protocol Controllers are not mandated to support creating Intra or Inter Protocol Controller bindings. In this case, it will appear from the IoT Service as if the Bind command was ignored or rejected.

8.3.1. Binding table capacity

A PAN node may have a limited capacity in its binding table. When that happens, a protocol controller can use the BindingTableFull attribute to indicate that we have reached the limit, and no more bindings can be made.

ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindingTableFull/Reported - {"value": true}

Note that Protocol Controllers MAY start establishing Intra Protocol Controller bindings when the capacity of the PAN node is reached. In this case, the Protocol Controller MUST NOT advertise that the binding table is full.

A Protocol Controller establishing Intra Protocol Controller Bindings MUST advertise that the Binding table is full only if both the PAN node and the Protocol Controller have exhausted their binding capacity.

8.3.2. MQTT publications example

An example of a PAN node with the Bindings server PAN node able to send commands for the OnOff and Level clusters will be shown as follows:

ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindingTableFull/Reported - {"value": false}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindingTableFull/Desired - {"value": false}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindableClusterList/Reported - {"value": ["OnOff", "Level"]}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindableClusterList/Desired - {"value": ["OnOff", "Level"]}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindingTable/Reported - {"value": []}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/Attributes/BindingTable/Desired - {"value": []}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/SupportedCommands - {"value": ["Bind","Unbind"]}
ucl/by-unid/<UNID>/ep<EndpointId>/Binding/SupportedGeneratedCommands - {"value": []}

8.3.3. Detailed examples

8.3.3.1. Happy case

8.3.3.2. Failed binding attempts

8.3.3.3. Explicit binding towards a Protocol Controller

IoT Service MAY use the binding cluster to force binding towards a Protocol Controller. The Binding cluster provides a special command for this, so IoT services do not need to figure out which UNID/ep to use for the Binding to point at the Protocol Controller.

Protocol Controllers supporting to establish bindings towards themselves SHOULD forward commands received by PAN nodes to IoT Services using the ucl/by-unid/<unid>/ep<id>/<ClusterName>/GeneratedCommands topic space.

The diagram below shows an example of an explicit binding to the Protocol Controller.