Home > Support > Knowledge Base
Knowledge Base
 
Reset Search
Search
 

 

Knowledge

HOW TO: Remove non-encrypted ZigBee Smart Energy clusters for a device and re-add them as APS Enrcypted clusters (Example: 2D2C Inc Model 1313 Load Controller)

« Go Back

Information

 
Article Number000002139
Problem Resolution

Introduction


Digi International creates tested Plug-In drivers to ensure compatibility with a number of popular Smart Energy devices available on the market today. (Click on Gateway model for the ConnectPort X2 for Smart Energy or ConnectPort X2e for Smart Energy Plug-in driver page).  As the number of Smart Energy devices available on the market increases however, so does the likelihood that you'll use a device which Digi hasn't created a driver for.  This article describes how to manually add Manufacturer Specific Clusters (MSC) Client clusters to the Smart Energy network of a Digi gateway, using the 2D2C Inc Safeplug Model 1313 Load Controller as an example.  The guidance from this article can be used to remove a non-secure cluster and/or add a secure cluster, for ANY Smart Energy device which contains APS Encrypted Server clusters.

NOTE:  To perform the changes described in this article, a Device Cloud account is necessary, and your Digi Smart Energy Gateway must be added to that account.  If needing a Device Cloud account, click here to Get Started with the Device Cloud.  Once your Device Cloud account has been created, use the Add Device button under Device Management --- Devices to add the Gateway to your account inventory.  Once your Gateway is added, the Smart Energy Framework commands used in this article can be sent using any of the methods in this article:  HOW TO: Run Smart Energy Framework RPC commands from Digi Device Cloud Web Services.

 

Installing the 2D2C Inc. Safeplug Model 1313 Load Controller


A customer has purchased a 2D2C Model 1313 Load Controller. They want to add the Load Controller to the Smart Energy network of a ConnectPort X2e for Smart Energy gateway, but after consulting the Plug-in driver page for the Gateway, have determined that Digi hasn't created a Plug-In driver for the 2D2C Inc. Model 1313 Load Controller.

Without a Plug-in driver, they will need to manually add any Load Controller clusters which aren't already found on the Gateway so they can  access the attributes/data found under them.  Adding the Manufacturing Specific Clusters of this device will also allow them to setup Reporting, as well as control the Load Controller using its documented command set.

The customer starts by contacting 2D2C Inc in order to obtain the developer documentation for their Model 1313 device.  After consulting the documentation, they discover the Load Controller device has two endpoints:

Endpoint 10 (0xA) - contains the Basic, Identify, Time, DRLC, and Key Establishment clusters

Endpoint 11 (0xB) - contains the APS encrypted On/Off, Level Control, Metering, EFCI, and Scheduler clusters.


When developer documentation isn't available from a Smart Energy device manufacturer, you might be able to figure out which Client cluster(s) need to be added to the Gateway by first adding the Smart Energy device to your Gateway's network, then finding out which Server Clusters you aren't able to read.  You could then use the examples below to add the corresponding Client cluster(s) necessary to read information from the device.

 

Discover existing Gateway clusters:


To start, send a get_clusters request to the Gateway, to find out which Server/Client clusters are already present on the Gateway's network:

Request:  <get_clusters synchronous="true" />

Response:
<get_clusters_response timestamp="1397829743">
  <clusters type="list">
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0x0</cluster_id>
      <cluster_class type="string">ZCL_BasicCluster_server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0x800</cluster_id>
      <cluster_class type="string">SE_KeyEstablishmentCluster_server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0x3</cluster_id>
      <cluster_class type="string">ZCL_IdentifyCluster_server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0x701</cluster_id>
      <cluster_class type="string">SE_DemandResponseLoadControlCluster_server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">TRUE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0xA</cluster_id>
      <cluster_class type="string">ZCL_TimeCluster_server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">TRUE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0x703</cluster_id>
      <cluster_class type="string">SE_MessageCluster_server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">TRUE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0x19</cluster_id>
      <cluster_class type="string">OTA_Cluster_Server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">TRUE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x0</server_or_client>
      <cluster_id type="int">0x700</cluster_id>
      <cluster_class type="string">SE_PriceCluster_server</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">TRUE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x0</cluster_id>
      <cluster_class type="string">ZCL_BasicCluster_client</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x800</cluster_id>
      <cluster_class type="string">SE_KeyEstablishmentCluster_client</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x702</cluster_id>
      <cluster_class type="string">SE_SimpleMeteringCluster_client</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">TRUE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x3</cluster_id>
      <cluster_class type="string">ZCL_IdentifyCluster_client</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x6</cluster_id>
      <cluster_class type="string">ZCL_Cluster</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x201</cluster_id>
      <cluster_class type="string">ZCL_Cluster</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x202</cluster_id>
      <cluster_class type="string">ZCL_Cluster</cluster_class>
      <endpoint_id type="int">0x5E</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
    <item type="dict">
      <server_or_client type="int">0x1</server_or_client>
      <cluster_id type="int">0x23</cluster_id>
      <cluster_class type="string">APSME_RemoveDeviceCluster</cluster_class>
      <endpoint_id type="int">0xE6</endpoint_id>
      <enable_APS_encryption type="bool">FALSE</enable_APS_encryption>
    </item>
  </clusters>
</get_clusters_response>
 

Compare Device and Gateway clusters


The get_clusters output from the Gateway is compared with the Cluster listing found in the Load Controller's documentation. The Load Controller is found to have two endpoints (0xA and 0xB), so the Server clusters of these two endpoints will need to be compared with the Client cluster's on endpoint 0x5E of the Gateway.

Several of the Client clusters from the get_clusters output above have been highlighted.  We know these are Client clusters because the server_or_client attribute has a value of 0x1.  Here is how the two endpoints listed in the Load Controller documentation break down:

Endpoint 10 (0xA) - The Client clusters found on Gateway endpoint 0x5E match up perfectly with the Server clusters already found under endpoint 0xA of the Load Controller.  Any of the attributes found under the Clusters of this endpoint will be accessible. 

Endpoint 11 (0xB) - Here is where we'll see problems if we don't make a few changes first.  The APS encrypted 0x702 cluster checks out OK, since the APS encrypted client cluster found on the Gateway matches the APS encrypted server cluster found on the Load Controller.  On/Off cluster 0x0006 is problematic, since the DRLC server cluster is encrypted, and the Gateway's client cluster is not.  In order to resolve this:
 

Remove non-encrypted Client cluster from the Gateway's 0x5E endpoint:


Non-encrypted cluster 0x0006 can be removed from the Gateway's network with the following command:
  
<remove_cluster synchronous="true">
  <endpoint_id>0x5E</endpoint_id>
  <cluster_id>0x6</cluster_id>
  <server_or_client>1</server_or_client>
</remove_cluster>
 

Add APS Encypted Client clusters on the Gateway's 0x5E endpoint:


Re-add Client cluster 0x0006 (removed in previous step), but as an APS Encrypted cluster:

<add_cluster synchronous="true">
  <endpoint_id>0x5E</endpoint_id>
  <cluster_class type="string">ZCL_Cluster</cluster_class>
  <cluster_id>0x6</cluster_id>
  <server_or_client>1</server_or_client>
  <enable_APS_encryption>TRUE</enable_APS_encryption>
</add_cluster>

Lastly, there appear to be three additional Manufacturer Specific Clusters (MSC) found on the Load Controller in the form of clusters 0x0008 (Level Control), 0xFE04 (EFCI), and 0xFE05 (Scheduler) which aren't found on the Gateway at all.  Since these Load Controller Server clusters require APS encryption as well, we add them to the network manually in the same way we added cluster 0x0006:

<add_cluster synchronous="true">
  <endpoint_id>0x5E</endpoint_id>
  <cluster_class type="string">ZCL_Cluster</cluster_class>
  <cluster_id>0x8</cluster_id>
  <server_or_client>1</server_or_client>
  <enable_APS_encryption>TRUE</enable_APS_encryption>
</add_cluster>

<add_cluster synchronous="true">
  <endpoint_id>0x5E</endpoint_id>
  <cluster_class type="string">ZCL_Cluster</cluster_class>
  <cluster_id>0xFE04</cluster_id>
  <server_or_client>1</server_or_client>
  <enable_APS_encryption>TRUE</enable_APS_encryption>
</add_cluster>

<add_cluster synchronous="true">
  <endpoint_id>0x5E</endpoint_id>
  <cluster_class type="string">ZCL_Cluster</cluster_class>
  <cluster_id>0xFE05</cluster_id>
  <server_or_client>1</server_or_client>
  <enable_APS_encryption>TRUE</enable_APS_encryption>
</add_cluster>
 

Adding the Load Controller to the Gateway's network:


Now that we've mapped all the server/client clusters of the Gateway to the client/server clusters of the Load Controller, the only step we have left is to actually add the Load Controller to the Gateway's network using the EUI-64 and Installation Code found of the Load Controller (the bolded numbers below are an example, replace them with your Load Controller's actual values):

<add_device synchronous="true">
  <device_address type="MAC">11:22:33:44:55:66:77:88</device_address>
  <join_time>600</join_time>
  <installation_code type="string">1234-5678-90AB-CDEF</installation_code>
</add_device>
 

What if the Gateway isn't the Coordinator?


The ConnectPort X2e for Smart Energy gateway can be configured as a Smart Energy Coordinator or Router, depending on the needs of the network.  This article will show you HOW TO: Change a ConnectPort X2e Smart Energy Coordinator Gateway to a Router Gateway and Vice Versa. In the context of this article, all steps would still need to still be performed, except for the add_device portion, since this function would be performed by the 3rd party ZigBee Smart Energy network Coordinator.

 

Next Steps:


Now that the 2D2C Model 1313 Load Controller has been added to your Gateway's network successfully, you might want to control the Load Controller using it's documented commands (see manufacturer's document for specific  information) or setup a Reporting configuration for the Load Controller's Simple Metering Cluster:

HOW TO: Configure Pseudo (differential) Reporting on the ConnectPort X2e for Smart Energy
HOW TO: Configure Scheduled (cron) Reporting on the ConnectPort X2e for Smart Energy

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255