Device Configuration Examples Using A Host Application

Owned by Luke Tutty (Unlicensed)
Last updated: Oct 20, 2017
8 min read

This section provides examples of Host application implementations for various device types, with a focus on the Startup Sequence to initialize and configure the Module.

Basic Gateway Startup Sequence

This section details the basic recommended startup sequence for a Host application serving as a gateway. A gateway is typically a network coordinator with facilities for forming a Home Area Network (HAN) and managing devices on that network.

The sequence is described as a series of serial transactions between the Host and the Module. The hexadecimal byte payloads of the frames sent or received by the Host are shown inside square brackets, e.g., [F1 55 20 00 00 75 00].

  1. Power Up
  2. Send Host Startup Ready [F1 55 20 00 00 75 00]; Wait for Startup Sync Request
  3. Receive Startup Sync Request [F1 55 21 80 02 00 00 F8 00]
    Running State: Starting Up
    Configuration State: Factory Default
  4. Send Module Info Request [F1 55 02 01 00 58 00]; Wait for Module Info Response
  5. Receive Module Info Response [F1 55 03 01 0F 00 05 00 02 00 0C 0B 0A 00 00 46 24 00 02 01 FD 00]      
    Version: 0.5.0
    Application: RapidHA
    EUI: 00244600000A0B0C
    Hardware: EM357
    Bootloader Type: Application Bootloader

    The Host should verify that it is running against the desired version of RapidHA.

  6. Verify the application Configuration State (i.e., as retrieved via Startup Sync Request in step 3)
    1. If Configuration State is Fully Configured (0x02) move to step 7
    2. If Configuration State is Factory Default, then:
      Set Device Type to Full Function Device by sending Device Type Write [F1 03 00 02 02 00 00 05 00]
      If assigned a Manufacturer ID by the ZigBee Alliance (e.g., 0x109A), set it by sending Manufacturer ID Write [F1 55 40 03 02 9A 10 44 01]
    3. If Configuration State is either Factory Default (0x00) or Needs Endpoint Configuration (0x01), then:

                        i.      Send Add Endpoint with the following parameters:
                                [F1 03 10 04 1A 01 04 01 07 00 01 02 00 00 0A 00 07 00 00 03 00 04 00 05 00 06 00 08 00 01 02 6C 00]
                                Endpoint ID = 1
                                Profile ID = 0x0104 (    HA Application Profile)
                                Device ID = 0x0007 (Combined Interface)
                                Device Version = 0x01
                                Number of Server Clusters = 2
                                Server Clusters = Basic (0x0000), Time(0x000A)
                                Number of Client Clusters = 7
                               Client Clusters = Basic (0x0000), Identify (0x0003), Groups (0x0004), Scenes (0x0005), On/Off (0x0006), Level Control (0x0008), Thermostat (0x0201)
          
                                RapidHA automatically adds the mandatory attributes for each of the listed clusters as they are natively supported by the application.

  7. Update default attribute values using Attribute Write
    1. Write to Application Version of Basic cluster [F1 03 25 05 08 01 00 00 01 01 00 20 03 C7 00]
      Endpoint ID  = 1
      Cluster ID = 0x0000
      Cluster Side = Server (0x01)
      Attribute ID = 0x0001 (Application Version)
      Attribute Type = 0x20 (Unsigned 8-bit Integer)
      Attribute Value = 0x03
    2. Write to UTC Time of Time cluster [F1 03 25 06 0B 01 0A 00 01 00 00 E2 29 DA 63 13 A0 02]
      Endpoint ID  = 1
      Cluster ID = 0x000A
      Cluster Side = Server (0x01)
      Attribute ID = 0x0000 (UTC Time)
      Attribute Type = 0xE2 (UTC Time)
      Attribute Value = 0x1363DA29
  8. Send Startup Sync Complete [F1 55 22 07 00 7E 00]
  9. Module starts application and sends Network Status [F1 01 09 81 0A 00 FF FF FF FF FF FF 00 00 00 00 00 00 00 00 00 8F 06]
    Network State = Network Down (0x00)
    ZigBee Device Type = Unknown (0xFF)
    Channel = Unknown (0xFF)
    Node ID = Unknown (0xFFFF)
    PAN ID = Unknown (0xFFFF)
    Extended PAN ID = Unknown (0x0000000000000000)
    Permit Join Time = 0x00

If the Module has a previous network in memory, it will start with that network automatically. In this example the Module has no previous network and as such is in the Network Down state.

At this point, both the Host and Module have been fully initialized. The next steps illustrate how the Host may prompt the Module to form a network and commission a device onto that network.

  1. Send Form Network
    [F1 01 01 08 0F 00 F8 FF 03 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 16 02]
    Channel Mask = Any channel between 11-25 (0x03FFF800)
    Auto Options = Auto-select PAN ID and Auto-select Extended PAN ID (0x03)
    Short PAN ID = 0x0000 (N/A as auto-select is enabled)
    Extended PAN ID = 0x0000000000000000 (N/A as auto-select is enabled)
  2. Wait for Network Status
  3. Receive Network Status [F1 01 09 82 0A 01 0F 00 00 CD AB 34 12 34 12 34 12 34 12 36 03]
    Network State = Network Up (0x01)
    ZigBee Device Type = Coordinator (0x00)
    Channel = 15 (0x0F)
    Node ID = 0x0000
    PAN ID = 0xABCD
    Extended PAN ID = 0x1234123412341234
    Permit Join Time = 0x00
  4. Open permit join window for 60s by sending Permit Join [F1 01 03 09 01 3C 4A 00]
  5. Wait for device to join
  6. When device joins, receive Trust Center Update [F1 01 10 83 0E 0B 1A 45 23 01 00 00 46 24 00 00 00 00 9A 01]
    Node ID = 0x1A0B
    EUI64 = 0x0024460000012345
    Device Update Event = MAC Association (0x00)
    Parent Node ID = 0x0000

The device is now on the network and the Host may send ZDO and ZCL messages to it.

Basic HA Outlet Startup Sequence

Below is the basic recommended startup sequence for a Host application serving as an HA Outlet with support for the On/Off cluster on two separate endpoints and a third manufacturer-specific endpoint.

The sequence is described as a series of serial transactions between the Host and the Module. The hexadecimal byte payloads of the frames sent or received by the Host are shown inside square brackets, e.g., [F1 55 20 00 00 75 00].

  1. Powers Up
  2. Send Host Startup Ready [F1 55 20 00 00 75 00]; Waits for Startup Sync Request
  3. Receive Startup Sync Request [F1 55 21 80 02 00 00 F8 00]
    Running State: Starting Up
    Configuration State: Factory Default
  4. Send Module Info Request [F1 55 02 01 00 58 00]; Wait for Module Info Response
  5. Receive Module Info Response [F1 55 03 01 0F 00 05 00 02 00 0C 0B 0A 00 00 46 24 00 02 01 FD 00]  
    Version: 0.5.0
    Application: RapidHA
    EUI: 00244600000A0B0C
    Hardware: EM357
    Bootloader Type: Application Bootloader

    The Host should verify that it is running against the desired version of RapidHA.

  6. Verify the application Configuration State (i.e. as retrieved via Startup Sync Request in step 3)
    1. If Configuration State is Fully Configured (0x02) move to step 7
    2. If Configuration State is Factory Default, then:
      Set Device Type to Full Function Device by sending Device Type Write [F1 03 00 02 02 00 00 05 00]
      If assigned a Manufacturer ID by the ZigBee Alliance (e.g., 0x109A), set it by sending Manufacturer ID Write [F1 55 40 03 02 9A 10 44 01]
    3. If Configuration State is either Factory Default (0x00) or Needs Endpoint Configuration (0x01), then:

                        i.      Configure the first On/Off endpoint by sending Add Endpoint with following parameters:
                                [F1 03 10 04 12 01 04 01 02 00 01 05 00 00 03 00 04 00 05 00 06 00 00 49 00]
                                Endpoint ID = 1
                                    Profile ID = 0x0104 (HA Application Profile)
                                    Device ID = 0x0002 (On/Off Output)
                                Device Version = 0x01
                                Number of Server Clusters = 5
                                Server Clusters = Basic (0x0000), Identify (0x0003), Groups (0x0004), Scenes (0x0005), On/Off (0x0006)
                                Number of Client Clusters = 0

                       ii.      Configure the second On/Off endpoint by sending Add Endpoint with the following parameters:
                               [F1 03 10 05 10 02 04 01 02 00 01 04 03 00 04 00 05 00 06 00 00 48 00]
                               Endpoint ID = 2
                               Profile ID = 0x0104 (HA Application Profile)
                               Device ID = 0x0002 (On/Off Output)
                               Device Version = 0x01
                               Number of Server Clusters = 4
                               Server Clusters = Identify (0x0003), Groups (0x0004), Scenes (0x0005), On/Off (0x0006)
                               Number of Client Clusters = 0

                                   RapidHA automatically adds the mandatory attributes for each of the clusters listed in sub-steps (i) and (ii) as they are natively supported by the application.

                     iii.      Configure the manufacturer-specific endpoint by sending Add Endpoint with the following parameters:
                               [F1 03 10 06 0D 03 01 F0 01 F0 01 01 01 FC 01 01 01 FC C1 0F]
                               Endpoint ID = 3
                               Profile ID = 0xF001 (MSE Profile)
                               Device ID = 0xF001
                               Device Version = 0x01
                               Number of Server Clusters = 1
                               Server Clusters = 0xFC02
                               Number of Client Clusters = 1
                               Client Clusters = 0xFC02

                               RapidHA will not automatically add attributes, mandatory or otherwise, for the custom clusters configured in this step, as they are not natively supported.

                     iv.      Add attributes to the Manufacturer-Specific cluster by sending Add Attributes to Cluster with the following parameters:
                              [F1 03 20 07 0D 03 01 FC 01 02 00 00 30 01 01 00 20 03 67 0A]
                              Endpoint ID = 3
                              Cluster ID = 0xFC02
                              Cluster Server/Client = 0x01 (Server)
                              Number of Attributes to Add = 2
                              Attribute Definition 1: ID = 0x0000, Type = 0x30 (8-bit Enum), Property = 0x01 (Read Only)
                              Attribute Definition 2: ID = 0x0001, Type = 0x21 (Unsigned 8-bit Int), Property = 0x03 (Read/Write)

  7. Update default attribute values
    1. Write to Application Version of Basic cluster [F1 03 25 08 08 01 00 00 01 01 00 20 03 CA 00]
      Endpoint  = 1
      Cluster ID = 0x0000
      Cluster Side = Server (0x01)
      Attribute ID = 0x0001 (Application Version)
      Attribute Type = 0x20 (Unsigned 8-bit Int)
      Attribute Value = 0x03
    2. Write to On/Off State on Endpoint 1 [F1 03 25 09 08 01 06 00 01 00 00 10 00 1B 01]
      Endpoint  = 1
      Cluster ID = 0x0006
      Cluster Side = Server (0x01)
      Attribute ID = 0x0000 (On/Off State)
      Attribute Type = 0x10 (Boolean)
      Attribute Value = 0x00
    3. Write to On/Off State on Endpoint 2 [F1 03 25 0A 08 02 06 00 01 00 00 10 01 1E 01]
      Endpoint  = 2
      Cluster ID = 0x0006
      Cluster Side = Server (0x01)
      Attribute ID = 0x0000 (On/Off State)
      Attribute Type = 0x10 (Boolean)
      Attribute Value = 0x01
    4. Write to Manufacturer-Specific Attribute on Endpoint 3
      [F1 03 25 0B 09 03 01 FC 01 01 00 21 34 12 A5 01]
      Endpoint  = 3
      Cluster ID = 0xFC02
      Cluster Side = Server (0x01)
      Attribute ID = 0x0001
      Attribute Type = 0x21 (16-bit Enum)
      Attribute Value = 0x1234
  8. Send Startup Sync Complete [F1 55 22 0C 00 83 00]
  9. Module starts application and sends Network Status [F1 01 09 81 0A 00 FF FF FF FF FF FF 00 00 00 00 00 00 00 00 00 8F 06]
    Network State = Network Down (0x00)
    ZigBee Device Type = Unknown (0xFF)
    Channel = Unknown (0xFF)
    Node ID = Unknown (0xFFFF)
    PAN ID = Unknown (0xFFFF)
    Extended PAN ID = Unknown (0x0000000000000000)
    Permit Join Time = 0x00

If the Module has a previous network in memory, it will work to automatically rejoin that network. In this case the Module has no previous network and as such is in the Network Down state.

At this point, both the Host and Module have been fully initialized. The next steps explains how the Host prompts the Module to join a network.

  1. Open the Permit Join window on the ZigBee coordinator (not a Host or Module action, but a necessary step by the coordinator to allow the device to join)
  2. Send Join Network
    [F1 01 00 0C 0F 00 F8 FF 03 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 19 02]
    Channel Mask = Any channel between 11-25 (0x03FFF800)
    Auto Options = Auto-select PAN ID and Auto-select Extended PAN ID (0x03)
    Short PAN ID = 0x0000 (N/A as auto-select is enabled)
    Extended PAN ID = 0x0000000000000000 (N/A as auto-select is enabled)
  3. Wait for Network Status
  4. Receive Network Status [F1 01 09 82 0A 01 0F 00 01 CD AB 34 12 34 12 34 12 34 12 37 03]
    Network State = Network Up (0x01)
    ZigBee Device Type = Router (0x01)
    Channel = 15 (0x0F)
    Node ID = 0x0000
    PAN ID = 0xABCD
    Extended PAN ID =  0x1234123412341234
    Permit Join Time = 0x00

The Module is now joined to the network and may transmit ZCL and ZDO messages. When an external device modifies the application On/Off State value on either Endpoint 1 or Endpoint 2, the Host receives the command On/Off State Update informing it of the update. Any other attribute value change (i.e. against the MSE Endpoint 3 and its custom cluster) is reported to the Host via the Received Attribute Write command.

Legal Notices

Copyright © 2017 MMB Networks, Inc. All rights reserved.
Confidential materials prepared and delivered by MMB Networks for receipt and review only by any partner subject to a valid and enforceable MMB Networks confidentiality agreement. Any receipt, review, or misuse of any of the content exchanged hereunder by any party not a party to this confidential exchange shall be subject to any and all rights available under the law. All rights, title and interest to the materials shall remain with MMB Networks.
Any suggestions provided to MMB Networks with respect to MMB Networks' products or services shall be collectively deemed “Feedback.” You, on behalf of yourself, or if you are providing Feedback on behalf of your employer or another entity, represent and warrant that you have full legal authority to bind such entity to these terms, agree to grant and hereby grant to MMB Networks a nonexclusive, perpetual, irrevocable, royalty free, worldwide license to use and otherwise exploit such Feedback within any MMB Networks products and services.