What is the End Device Bind functionality in the EmberZNet stack, and how do I use it?

What it is:
A ZigBee method of service discovery (via the ZDO) that provides for pairing of devices in a PAN that have reciprocating capabilities (client side of a cluster versus server side of same cluster). It involves user-initiated requests on two devices, with the coordinator node acting as a moderator for matching the requests and sending responses. Note that this ZDO request type differs from the ZDO Bind Request (or Unbind Request) in that the End Device Bind Request is a precursor to possible binding activities (which, if initiated, occur via the actual Bind/Unbind Requests), whereas the Bind/Unbind Requests themselves serve to specifically modify the binding table of recipient devices.

How it works:

• Some device in the PAN (Device 1) sends an End Device Bind Request (Request 1) with a particular cluster list.
• Another device in the PAN (Device 2) also sends an End Device Bind Request (Request 2) with a particular cluster list.
• Each End Device Bind Request consists of identity information about the requesting device, a cluster list of input (server-side) clusters, a cluster list of output (client-side) clusters, and the Application Profile ID and source endpoint to which these clusters apply.
• Requests are always sent to the PAN’s ZigBee Coordinator (ZC) node, and that ZC node is the one who generates responses accordingly. The ZC must implement End Device Bind support (which is an optional EmberZNet PRO feature) to facilitate this process. (The process is carried out automatically by the ZC when support is present.)
• If a request is sent to a device other than the ZC, or the ZC does not have the necessary End Device Bind support (as a library in SoC firmware or an NCP feature in EZSP NCP firmware) , then the receiver will respond with a status of EMBER_ZDP_NOT_SUPPORTED to indicate that the request type can’t be handled.
• Within a given time window (set by EMBER_END_DEVICE_BIND_TIMEOUT or EZSP_CONFIG_END_DEVICE_BIND_TIMEOUT, defaulting to 60 seconds), if the ZC receives two requests for which the Application Profile ID is the same and for which any [not necessarily all] cluster IDs in the Input Cluster List of Request 1 match any cluster IDs in the Output Cluster List of Request 2, or for which any cluster IDs in the Input Cluster List of Request 2 match any cluster IDs in the Output Cluster List of Request 1, then the matching process is considered successful. If neither of these conditions can be satisfied between the two requests (or no second response is seen within the timeout), the process is considered a failure.
• Device 1 is allowed to be the same node as Device 2 (although having a node bind to itself is not a common occurrence), and either of these devices can also be the ZC itself.
• The process is not designed to match among more than two requests at the same time (ie. matching process will begin as soon as second request is received).
• If the process was successful (ie. at least one input cluster from one request was matched to among the output clusters from the other request), then the ZC will first send ZDO Unbind Requests (which ask the destination node to remove any binding table entry matching the one in the request) to each client device (the one implementing the output cluster), one for each cluster match detected, so that any existing binding to the same server device (the one implementing the input cluster) on the matched clusters can be removed. (The Unbind Requests will be answered with Unbind Responses indicating EMBER_ZDP_SUCCESS for erased entries or EMBER_ZDP_NO_ENTRY for unmatched entries.) This allows the End Device Bind mechanism to work as a “toggle” for binding entries, where the first successful End Device Bind process causes the entry to be set, the second successful End Device Bind process for the same client on the same cluster causes the entry to be removed, the third process sets it again, and so on…
• After sending all necessary Unbind Requests as part of a successful match process, if none of these Unbind Requests resulted in an EMBER_ZDP_NO_ENTRY status (meaning there were no bindings to erase), the ZC next begins to send ZDO Bind Requests (which ask the destination node to bind to a third party with the provided source/destination endpoints, cluster ID and profile ID), one for each cluster match detected, to the client device instructing it to bind to the server device on the matched cluster using the source/destination endpoints provided in the requests. Note that this may result in Bind Requests (or Unbind Requests in the previous step) being sent to both Device 1 and Device 2 if Request 1 and Request 2 have matches in both directions among their cluster lists.
• Upon concluding the successful case (as explained above), both Device 1 and Device 2 are sent End Device Bind Response messages with a status of EMBER_ZDP_SUCCESS (even if some or all of the resulting Bind/Unbind Requests to the client devices failed to due to unreachable nodes or failure to modify the binding table entries).
• If the process fails because Request 2 was not received within the ZC’s configured End Device Bind timeout window, then Device 1 will be sent an End Device Bind Response message with a status of EMBER_ZDP_TIMEOUT.
• If the process fails because no matches were detected between Request 1 and Request 2, then both devices (1 and 2) will each receive End Device Bind Response messages with a status of EMBER_ZDP_NO_MATCH.
• APS Options (such as APS_RETRY or ENABLE_ROUTE_DISCOVERY) for the Bind/Unbind requests sent to client devices are copied from the APS Options used in the original End Device Bind Request sent by that client device.

Libraries/Code Support:

• In SoC (system on chip) designs, End Device Bind support is available as a library called the “end-device-bind-library”. (The “end-device-bind-stub-library” is its counterpart and does not implement any of the support for matching requests.) PANs wishing to utilize this feature should link this library into any builds for devices that may act as the ZC for a PAN. (Devices in the PAN besides the ZC can use the stub library, since all matching logic is handled at the ZC.)
• In NCP (Network CoProcessor) designs using EZSP, End Device Bind support is available as a feature in certain NCP firmware images. For most NCP images, unless the filename includes the phrase “no-end-device-bind”, it is generally safe to assume that the firmware contains support for End Device Bind when running as a ZC in a PAN. The exception to this is the collection of ECC-enabled images available from Certicom as part of the Ember Smart Energy Suite. For information about which stack features are available in which ECC-enabled firmware images for EZSP NCP devices, please consult the special EmberZNet release notes (for the version of firmware you’re using) found in the ECC distribution from Certicom.
• For client devices participating in End Device Bind activities, the use of Binding Table support is strongly advised (since the ZC will be asking client devices to create/modify binding table entries as part of the End Device Bind process). To ensure Binding Table support (also an optional stack feature), the client device must include the “binding-table-library” (rather than the “binding-table-stub-library”) in SoC application builds. For EZSP NCP images (even those with ECC support), binding table support is always included as a feature, so any NCP firmware can be used.
• If either of the required features (End Device Bind support on the ZC or Binding Table support for client devices) can’t be supported due to other design constraints on the device that requires it, the application still has the ability to implement handling of these Bind/Unbind and End Device Bind ZDO requests manually in its application logic [on the host in EZSP NCP designs] if using EmberZNet 3.3.2 or later. This is accomplished through the use of EZSP_CONFIG_APPLICATION_HANDLES_UNSUPPORTED_ZDO_REQUESTS (for EZSP designs) or EMBER_APPLICATION_HANDLES_UNSUPPORTED_ZDO_REQUESTS (for SoC designs), which instructs the EmberZNet stack (or NCP firmware) to defer to the [host] application in cases where EMBER_ZDP_NOT_SUPPORTED would otherwise be sent.
• For source code related to the use of End Device Bind requests, see utility libraries in app/util/zigbee-framework and the ZDO sample application in app/zdo.

Why is it called “End Device Bind”? Can’t I use this with non-end device nodes?
Yes, an End Device Bind Request can be sent by any device, not just an end device (ie. Device 1 and Device 2 can be any device type). While the term “End Device Bind” is a bit confusing/misleading, it seems to have originated from the idea that end devices would typically be less sophisticated devices with simpler application state machines and less memory resources, so the typical process of Service Discovery via ZDO Match Descriptor requests (where a client broadcasts to a set of devices, looking for those who have server-side support for the cluster in question, and then parses through the responses and creates bindings to one or more of the matching nodes’ endpoints at the application’s discretion) would potentially be too complex and resource-intensive for the end device. The concept was advocated for use in Home Automation (HA) networks, where some devices may be relatively simpler and where devices typically have some kind of buttons or other user interface to engage the End Device Bind mechanism. Unlike the Match Descriptor concept, the End Device Bind strategy allows both the discovery and the binding actions to be initiated with one request (End Device Bind Request) from each side of the communication, whereas the Match Descriptor method provides only the discovery piece, not the binding piece.

Drawbacks
While End Device Bind certainly allows for a simpler pairing of devices versus having to require the client to search out the matching server manually (via Match Descriptor requests), it also has a few disadvantages worth noting:

• Requires some external stimulus (like a button or switch) on both the client and server device in order to ensure that the End Device Bind requests are initiated on both sides within the acceptable time window. Also, if multiple endpoints exist on a device, an End Device Bind process would have to occur for each endpoint where the client needs to be paired to a server for a set of its clusters. The external stimulus used to initiate the process would need some way of differentiating which cluster lists will be provided for the request, especially if multiple endpoints exist.

• Requires special support of optional End Device Bind feature on the ZC device, which impacts available flash memory resources at the ZC. Also, not all PANs may have a ZC that supports this feature, since it’s optional, so devices wishing to use this may find that they cannot do so in certain PANs.

• Assumes that each cluster will have its own binding. While this is often the case, not all applications may find this convention appropriate, especially in cases where there are a large number of client clusters, since each binding occupies RAM and non-volatile storage (“token”) resources and since Binding Table Library feature support does require additional flash and RAM resources for SoC builds.

• Requires that the ZC always be accessible. While this is generally the case in most networks (since the ZC is also the Trust Center and often the Network Manager device as well), this may not always be true, either by design of the network or based on temporary connectivity/bandwidth issues being experienced by the ZC that prevent it from receiving messages from the requesters and responding properly.

• Generates a lot of unicast traffic. While unicasts are generally much less impactful on the network’s performance (and are more reliable) as compared with broadcasts, the number of unicasts and the time to convey them may be significant if there are a large number of matching clusters that necessitate a corresponding large number of Unbind and Bind Requests (as well as their Response messages and the APS ACKs for both the requests and the responses).

• Client devices in this process must support remote binding modification. Although the ZDO allows for remote modification of the binding table via Bind/Unbind requests, the application is ultimately the one in charge of mediating these requests to decide what is allowed and what isn’t. For this process to work correctly, remote binding modification must be allowed via the emberRemoteSet/DeleteBindingHandler() on SoC designs or the EZSP_BINDING_MODIFICATION_POLICY in EZSP NCP designs. Even if devices have Binding Table support, it’s still possible for the application to deny the binding table modifications based on its current configuration.

• End devices must poll more often during the End Device Bind process. Since the process generally leads to a number of Bind/Unbind requests coming down to the client device from the ZC, the client must ensure that it can receive these request frames (and respond) in a timely fashion. Although unicasts for end devices are typically buffered by their parent parent device, the parent only has a limited amount of buffer space to hold message data, so it’s possible for the large number of unicasts resulting from the Bind/Unbind traffic to overflow the buffer space on the parent if the queue isn’t being emptied by the end device’s polls. Ember’s recommended poll interval when participating as a client (supplying output clusters) in the End Device Bind transaction is one poll per 200ms until the transaction is complete (End Device Bind Response frame has arrived).