3.7 ZigBee Interface

The ZigBee functionality is only available in the 2N® SmartCom PRO version equipped with a ZigBee interface. The ZigBee parameters depend on the module mounted (radio frequency, e.g.). You can define up to 16 terminals within one network to communicate with 2N® SmartCom PRO, which works as a coordinator for this network. The ZigBee communication technology, based on the IEEE 802.15.4 – ZigBee standard, is one of the wireless PANs (Personal Area Networks). PANs also include a very popular IEEE 802.15.1 – Bluetooth technology, which is mostly applied in consumer electronics. However, there are a lot of industrial applications where Bluetooth is inapplicable. Therefore, ZigBee has been introduced as a new wireless communication standard suitable for industrial automation too. At present, over 60 companies including the world automation leaders are involved in ZigBee development and extension. ZigBee has been designed as a simple and flexible technology for extensive wireless networks that require no huge data transmissions. ZigBee features reliability, easy and undemanding implementation, low power requirements and, last but not least, cost efficiency. Based on multi-step ad-hoc routing, ZigBee provides long-distance communication without direct radio visibility of the devices involved. It is primarily applied in industry and sensor networks and works at 2.4 GHz in licenceless zones (general permission). The bit rate is 20, 40, 250 kbit/s. Thanks to these merits, ZigBee is widely applied in many areas. For our purpose, its use in the available functions will be described. See below for the list of parameters including descriptions.

Note

  • Check the front sticker or back panel label or use the SCZB AT command (AT^SCZB?) to know whether your 2N® SmartCom PRO is equipped with a ZigBee module. The terminals that are not equipped with ZigBee response ERROR.

At present, 2N® SmartCom PRO behaves as a Master, i.e. the main network coordinator to which devices get connected. A sufficient amount of clusters have been mounted to help you comfortably control your air conditioners, ZigBee keypads, sockets, moisture and other meters, street lighting and many other systems. 

Note

  • Contact us at sales@2n.cz for more details or integration capacities.

Now let us briefly describe the ZigBee properties. Each device is identified by its IEEE address. One or more endpoints (EPs) are defined for each device and function clusters are defined for each EP. One cluster may occur just once in each EP. Let us give a simple example. Suppose we have a device that measures temperature and is equipped with 3 relays that switch other devices. In this case, the device will have 3 EPs with one ONOFF cluster each and there will be a DEVTEMP cluster in one of them. The simplified record in the device list would be as follows:

^SCZB: ID: 6, STATE: ONLINE, IEEE_ADDR: 00:12:4B:00:04:26:35:C1, SIG: 43%, UPDATED: 307332129283893

EP2: ONOFF: 0, DEVTEMP: 25,00, 

EP3: ONOFF: 1,

EP4: ONOFF: 0,

2N® SmartCom PRO constitutes a wireless PAN to which devices log in. The meters are listed in a table, which can include a lot of independent meters. The count of the meters is determined by the firmware version. Generally, there can be up to 32 devices depending on the customer's requirements. The first step is to properly configure a wireless network and so the first set of commands relates to network setup and device adding. The next step is description of clusters and related functions. Refer to the ZigBee alliance web sites for detailed specifications. Now let us describe the PAN configuration AT commands.

 

Network Configuration

AT^SCZB="ADD",<16 HEX>[,<dev_id>]
  • The command adds a device to the list. <16 HEX> means a sixteen-character IEEE address. Ask your meter manufacturer for these data.
    • <dev_id> – this optional parameter specifies the meter list position. If it is not used, a new device is added to the first free list position. 

Tip

  • The IEEE ZigBee addresses have the following format: 00:12:4B:00:04:26:35:C1. The device adding AT command is as follows:
T^SCZB="ADD",00124B00042635C1,6
  • The command adds a device with the above mentioned address to position 6 of the list.
  • The count of the list positions depends on the FW version and is customer adjustable.
AT^SCZB?
  • The command reads out the meter list. The response can be as follows:
AT^SCZB?<br>
^SCZB: ID: 1, STATE: CONFIGURED, IEEE_ADDR: 00:12:4B:00:05:18:E7:42, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 2, STATE: CONFIGURED, IEEE_ADDR: 00:12:4B:00:04:26:35:C1, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 3, STATE: SLOT_FREE, IEEE_ADDR: 00:00:00:00:00:00:00:00, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 4, STATE: SLOT_FREE, IEEE_ADDR: 00:00:00:00:00:00:00:00, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 5, STATE: SLOT_FREE, IEEE_ADDR: 00:00:00:00:00:00:00:00, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 6, STATE: CONFIGURED, IEEE_ADDR: 00:12:4B:00:04:26:35:C1, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 7, STATE: SLOT_FREE, IEEE_ADDR: 00:00:00:00:00:00:00:00, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 8, STATE: SLOT_FREE, IEEE_ADDR: 00:00:00:00:00:00:00:00, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 9, STATE: SLOT_FREE, IEEE_ADDR: 00:00:00:00:00:00:00:00, SIG: 0%, CAP: UNKNOWN<br>
^SCZB: ID: 10, STATE: SLOT_FREE, IEEE_ADDR: 00:00:00:00:00:00:00:00, SIG: 0%, CAP: UNKNOWN<br>
OK

AT^SCZB="DEL",<dev_id>
  • The command removes a device from the list. The parameter setting depends on the count of records in the list. One record is only removed.
AT^SCZB="CLEAR"
  • The command removes all devices from the list.
AT^SCZB="PANID"[<4 HEX>]
  • The command sets the network identifier to the value specified in the parameter.
    • <4 HEX> – gives the new network name. The setting options are 4 hexadecimal characters (0–F).

Tip

  • In case the optional parameter is not entered, the command only reads out the currently set value. This holds true for all the commands!

Note

  • If there is another network within reach with the same name and channel, the module will choose a more available channel or automatically change the network name to the set value +1. Therefore, you are advised to check the setting by reading the current value.
AT^SCZB="PANID_READ"
  • The command reads out the current value of the PANID parameter.
AT^SCZB="CHANNEL"[<8 HEX>]

The command sets the used channel to the value set by the parameter.

  • <8 HEX> – gives the new network name. The setting options are 8 hexadecimal characters (0–F). The values of the last 8 positions are entered without 0x.
  • It is a channel bit mask. The default value is 0x00000800–channel 11.
ChannelMask ChannelMask
NONE0x00000000Channel 180x00040000
ALL_CHANNELS0x07FFF800Channel 190x00080000
Channel 110x00000800Channel 200x00100000
Channel 120x00001000Channel 210x00200000
Channel 130x00002000Channel 220x00400000
Channel 140x00004000Channel 230x00800000
Channel 150x00008000Channel 240x01000000
Channel 160x00010000Channel 250x02000000
Channel 170x00020000Channel 260x04000000
  • In case the optional parameter is not entered, the command only reads out the currently set value. It does not return a mask but a string with the selected channel number.

AT^SCZB="CHANNEL_READ"
  • The command only reads out the currently set value. It does not return a mask but a string with the selected channel number.

AT^SCZB="PRECFGKEY"[<32 HEX>]
  • The command sets the pre-configured key for encrypted communication.
    • <32 HEX> – encryption string including 16 ASCII characters in hexadecimal format: 32 characters 0–F.
AT^SCZB="PRECFGKEY_ENABLE"[<0-1>]
  • The command enables/disables sending of the encryption key.
    • If configured for both the communicating devices, the key need not be sent at communication start.
AT^SCZB="TCLK"[<32 HEX>]
  • The command sets the encryption key for communication key negotiation and transmission. Used for key replacement encryption.
    • <32 HEX> – encryption string including 16 ASCII characters in hexadecimal format: 32 characters 0–F.

Tip

  • Make sure that the key is configured identically on both the communication ends before communication starts. The key is set to the default factory value in all ZigBee devices, which is identical for all the devices. Keep the default setting to ensure compatibility. Change the key to increase security. The default key is as follows:
    • ASCII – ZigBeeAlliance09
    • HEX – 5A6967426565416C6C69616E63653039

AT^SCZB="IEEE_ADDR"
  • The command reads out and displays the ZigBee interface IEEE address.  
AT^SCZB="MODULE_TYPE"
  • The command reads out and displays information on the module.
AT^SCZB="RESTART"
  • The command restarts the interface and creates a new PAN. If the main parameters are not changed, no new PAN is created.

AT^SCZB="POLL",<dev_id>
  • The command reads out and updates the device list data for the defined dev_id (device list position).
    • One device is only updated. All available information including cluster values in endpoints is read out.
AT^SCZB="POLL_TIME",<time>
  • The command reads out and updates the device list data automatically in predefined intervals. The timer is kept for each device separately.
    • <time> – time is set in seconds. Setting options: 0–10000, where 0 means disabled.
AT^SCZB="PERMIT_JOIN",<dev_id>,<time>
  • The command permits a device to let new devices join the network.
    • <dev_id> – define the device(s) to be permitted to accept new devices. Setting 0 you enable permit_join for 2N® SmartCom PRO directly.
    • <time> - time is set in seconds. Setting options: 0–255.
      • 0 – disabled
      •  1–254 – enabled for defined time
      • 255 enabled permanently 

Tip

  • To add devices via Next Hop, make sure that permit join is enabled for 2N® SmartCom PRO and the point that is the closest to the device to be added.
AT^SCZB="PERMIT_JOIN_ALL",<time>
  • The command permits all the devices on the list to let new devices join the network.
    • <time> – time is set in seconds. Setting options: 0–255.
      • 0 – disabled
      •  1–254 – enabled for defined time
      • 255 – enabled permanently

Description of Function Commands

Remember to enter the dev_id of the device to which the command is to be sent. Also enter the end_point (EP) to identify the cluster in the given device. The default EP is always 2, but can have any value theoretically: 2, 3 and 4 are the most frequent values. These two parameters are the requisites of the commands below and so their meanings will not be described in every command.

Every sent command is followed by a response with one of the following 4 states:

  1. <DATA> <OK> – displays description of the set/measured values and the command is terminated with an OK sequence: everything is OK.
  2. <ERROR> – means that an invalid parameter was sent or an error occurred while processing.
  3. <TIMEOUT> – means that the command was sent to the device but the device failed to respond within the timeout.
  4. <ZCLERROR:[code]> – means that an error was detected in the ZigBee protocol. A numerical error code is displayed. See the ZigBee data sheet for details.

Note

  • The device responds to the command if the cluster with the given parameter is implemented. Not all of the devices support all the clusters. The devices only use the clusters they need for their function.
AT^SCZB="ANLGVAL",<dev_id>,<EP>
  • The command reads out the value of the analogue input in a device on the selected end_point.
AT^SCZB="BASIC",<dev_id>,<EP>
  • The command reads out all the values included in the BASIC cluster.
    • The following information can be included, for example: (BASIC_ZCL_VER, BASIC_APP_VER, BASIC_STACK_VER, BASIC_HW_VER, BASIC_MAN_NAME, BASIC_MODEL_ID, BASIC_PWR_SRC, BASIC_LOC_DESC, ONOFF, POWCFG_MAINS_VOLTAGE, POWCFG_BATTERY_VOLTAGE)
AT^SCZB="DEVTEMP",<dev_id>,<EP>
  • The command reads out the current device temperature.
AT^SCZB="FAN",<dev_id>,<EP>
  • The command returns the current state of the fan.
AT^SCZB="FAN_MODE",<dev_id>,<EP>,<value>
  • The command sets the fan mode to the defined value.
AT^SCZB="HMDT",<dev_id>,<EP>
  • The command returns the moisture value in % with the accuracy of 2 decimal places.
AT^SCZB="LC",<dev_id>,<EP>
  • The command returns the Level Control value (position of the aerodynamic air flow compensator, "flap").
AT^SCZB="LC_MOVE_TO_LEVEL",<dev_id>,<EP>,<level>[,<transition_time>]
  • The command sets the Level Control value (flap position). The optional transition_time parameter in tenths of a second defines when the position is to be set. If time is not set, the change will be made immediately.
AT^SCZB="METER",<dev_id>,<EP>
  • The command writes out the immediate consumption values. The output includes two numbers: the first specifies the immediate power output and the other the total output withdrawn (the parameter is adjusted to the needs of electric meters and so it displays the [W, Wh] units. In general, however, any meter can be used and the values then specify energy [J] or flow rate [m3/h]).
AT^SCZB="MSTVAL",<dev_id>,<EP>
  • The command reads out the Multi State Value. Used mostly for error codes.
AT^SCZB="ONOFF",<dev_id>,<EP>
  • The command returns the 1/0 value depending on the immediate setting.
AT^SCZB="ONOFF_SET",<dev_id>,<EP>,<state>
  • The command sets the switch to the value specified in the state parameter. Setting options: 1 – enabled, 0 – disabled.
AT^SCZB="TEMP",<dev_id>,<EP>
  • The command returns a temperature value in °C with the accuracy of two decimal places.
AT^SCZB="THERM",<dev_id>,<EP>
  • The command reads out and displays the currently set thermostat mode.
AT^SCZB="THERM_MODE",<dev_id>,<EP>,<value>
  • The command sets the thermostat mode to the defined value: 2 hexadecimal characters. Refer to the table below.
ValueDescription
00Off
01Auto
03Cool
04Heat
05Emergency heating
06Precooling
07Fan only
02, 08, feReserved
AT^SCZB="THERM_TEMP_HEAT",<dev_id>,<EP>,<value>
  • The command sets the heating temperature in °C with the accuracy of two decimal places.
AT^SCZB="THERM_TEMP_COOL",<dev_id>,<EP>,<value>

  • The command sets the cooling temperature in °C with the accuracy of two decimal places.
AT^SCZB="TIME",<dev_id>,<EP>

  • The command returns the currently set time value and time status.
AT^SCZB="TIME_SET",<dev_id>,<EP>,<utc_time>

The command sets the device time to the value specified by the utc_time parameter in a 32-bit format.

AT^SCZB="GROUP_ADD",<dev_id>,<EP>,<group_id>[,<group_name>]

The command adds the device with the selected dev_id to the group defined in group_id. The optional group_name parameter helps you assign a name of the maximum length of 15 characters to a new group.

AT^SCZB="GROUP_MEMBERSHIP",<dev_id>,<EP>,<group_id>

The command returns the YES string if the device defined in dev_id is assigned to the group defined in group_id. If not, the NO string is returned.

AT^SCZB="GROUP_REMOVE",<dev_id>,<EP>,<group_id>

The command removes the device specified in dev_id from the group defined in group_id.

AT^SCZB="GROUP_REMOVE_ALL",<dev_id>,<EP>

The command removes the device specified in dev_id from all the groups.

AT^SCZB="SCENE_RECALL_ALL",<group_id>,<scene_id>

The command starts the scenario defined in scene_id in all the devices in the group defined in group_id.

  • Make sure that this scenario has been implemented in the devices. The command can only start it.