General Operation

Startup Sequence

The following operations are performed when the gateway when powered on:

• Core modules are imported and core objects are initialized. The gateway will then load the modules and objects specified in the configuration files (See Saved Files). Once this completes, all RPC requests will be registered and available for use. Note that some RPC requests require certain conditions to function properly, such as time to be synchronized or the gateway to be joined to a network.
• The gateway waits for its XBee radio to report that it is joined to a network. Until the radio reports that it is joined to a network, ZigBee communications will be disabled.
• The gateway attempts to synchronize its time with an appropriate time server. Some features of the gateway that rely on knowing the current time, such as those related to Smart Energy events, cannot function until the gateway’s time has been synchronized.

See Asynchronous Message Reference for details on notification messages generated during gateway startup.

Time Synchronization

Before 1.5.0:

Time on the gateway can be synchronized in three ways:

• NTP server.
• ZCL time server on the gateway’s ZigBee network.
• RPC call (see set_time).

By default, the gateway will choose to use NTP synchronization if it does not have a ZCL time client, and will use ZCL synchronization if it does have a ZCL time client. Additionally, note that ZCL time synchronization cannot occur until the gateway has joined to a ZigBee network and detected a ZCL time server. Time is periodically resynchronized in order to prevent significant drift of the gateway’s clock.

The decision of what type of time synchronization to use, as well as the synchronization period, can be overridden with registry settings (see “Time_Synchronizer” in Registry Settings).

Note

Do NOT use the operating system to configure NTP on the gateway. This may cause serious problems, especially when the gateway is configured to use ZCL time.

As of 1.5.0:

By default, the operating system of the gateway is responsible for synchronizing to NTP and providing the gateway with UTC time. The Python code can still perform NTP synchronization, but the functionality has been deprecated and may be removed in future releases.

The gateway will now store an offset from NTP time to create a network time. The network time is used for all timing of events on the ZigBee network. The NTP UTC time is used for timestamps when communicating over the Internet.

By default, the gateway will set the network offset to zero if it does not have a ZCL time client, and will use ZCL synchronization to set the offset if it does have a ZCL time client. Additionally, note that ZCL time synchronization cannot occur until the gateway has joined to a ZigBee network and detected a ZCL time server. Time is periodically resynchronized in order to prevent significant drift of the gateway’s clock.

The decision of what type of time synchronization to use for the network time, as well as the synchronization period, can be overridden with registry settings (see the “Time_Synchronizer” settings in Registry Settings).

Note

The operating system SHOULD be configured with NTP on the gateway. NTP can still be handled by the Python code by configuring the NTP time servers using the Registry Settings “NTP_Client.server1” and “NTP_Client.server2”.

Remote Device Management

The gateway will keep track of basic information about devices on the network and whether devices appear to be actively communicating.

Device Activity

A remote device is detected as active when it responds to a specific ZDO match descriptor request sent by the gateway. This request is generated when any of the following occurs:

• A non-ZDO message is received by the gateway from a known device that is not currently marked as active.
• A non-ZDO message is received by the gateway from an unknown device, and the gateway is in open joining mode (the default behavior). See also: Explicit Device Add and Open Join
• The periodic refresh period has passed. See also: “ZDO_Device_Manager.refresh_interval” in Registry Settings

A device which is currently active will remain active so long as:

• Transmission errors to the device do not occur. Transmission errors refer specifically to non-success TX status values reported by the XBee radio.
• The device responds to match descriptor requests sent by the periodic refresh.

If communication to a device fails, as described above, a sufficient number of times in a row (see “ZDO_Device_Manager.max_sequential_TX_failures” in Registry Settings), the device will be marked as inactive. Of particular note, this means that devices which have dropped off the network will eventually be marked as inactive due to the periodic refresh.

Device Discovery

The gateway will maintain information about all known devices on the network. This is performed through ZDO discovery.

When a device is first detected as active, the following ZDO queries are sent:

• Node Descriptor
• Power Descriptor
• Active Endpoints

When the active endpoints response is received, the following is generated for each reported endpoint:

• Simple Descriptor

In this way, the gateway determines which clusters are available on each remote device. This information is used by the gateway primarily to pair local ZCL server and client clusters with their remote counterparts. This matching is in turn used as an alternative to requiring ZDO bind requests.

If the gateway receives communication from a remote device for an endpoint that did not previously detect, the gateway will send a ZDO active endpoints request to that device followed by simple descriptor requests as appropriate. Similarly, if the gateway receives communication from a remote device for a cluster that it did not previously detect, the gateway will send a ZDO simple descriptor request.

The ZDO discovery information about devices on the network will be retained when devices are marked inactive. Specifically, if a remote device is marked inactive and then later marked active again, ZDO queries will not be re-sent. However, discovery information is not power safe and will be queried again if the gateway is restarted.

SE Server Clusters and Device Activity

If an SE server cluster on the gateway is notified of a matching client cluster on a remote device, that client cluster will be added to the list of known SE client clusters for that particular SE server cluster. The server cluster uses its list of known client clusters when performing certain SE server operations, such as sending out new SE events to all clients.

SE server clusters will try to guarantee that client devices receive events. If an event is not sent successfully to an active client device, or if a client device becomes active after an event has been sent and does not request the server’s events, the server will send its events to the client after some amount of time. See “SE_Server.event_retransmission_check_interval” in Registry Settings for details on configuration.

When a remote device is marked as inactive, any SE client clusters on the device will be removed from lists kept by the gateway’s corresponding SE server clusters.

SE Client Clusters and Device Activity

If an SE client cluster on the gateway is notified of a matching server cluster on a remote device, that server cluster will be added to the list of known SE server clusters for that particular SE client cluster. Additionally, when this notification occurs the SE events of the server cluster will be queried by the client automatically. The client cluster will also attempt to do a ZDO bind to the remote server cluster, in case the server cluster requires that clients bind to it. Afterwards, the client cluster uses its list of known server clusters when performing certain SE client operations, such as requesting or confirming events.

When a remote device is marked as inactive, any SE server clusters on the device will be removed from lists kept by the gateway’s corresponding SE client clusters.

Explicit Device Add and Open Join

The gateway can be in either open join or explicit device add mode. When in open join mode, any device can be marked active (see Device Activity). Devices that become active will be added to the gateway’s list of known devices. When in explicit device add mode, only devices which have previously been added as known devices can become active. In either mode, devices can be added to the list of known devices by using the RPC add_device command.

The gateway defaults to open join mode. (see “ZDO_Device_Manager.require_explicit_device_add” in Registry Settings)

ZCL Reporting

The gateway supports the sending and receiving of ZCL attribute reports. Any ZCL attribute on the gateway which is not write-only may be reported.

Attribute reporting configurations, and particularly their timers, are handled independently per attribute. This means that:

• Timeouts and min/max intervals of a given configuration will not affect other configurations.
• RPC messages (received_attribute_report_collection*) will be generated as reports are received for each attribute, and will not be combined.

Pseudo Reporting

The gateway supports a simulated report receiving mode called “pseudo reporting.” When a reporting configuration is set up to use pseudo reporting, periodic ZCL read attributes requests are sent to the remote device, rather than configuring the remote device to send reports on its own. These reads are processed in order to generate reports based on the specified min/max interval and delta change. As such, from an RPC interface perspective, pseudo reporting is typically indistinguishable from normal reporting. This allows a user to set up attribute reporting behavior on attributes which do not normally support ZCL reporting, in exchange for slightly more ZigBee traffic overhead. Also note that, unless explicitly disallowed, pseudo reporting will be used as a fallback if a normal ZCL reporting configuration request sent to a remote device is unsuccessful. For details on using pseudo reporting, see the start_receiving_reports RPC request.

Automatic Reconfiguration on Timeout

For normal ZCL reporting, should the gateway not receive a report from the remote device within the timeout specified by its configuration, it will re-send the configuration to the remote device. The intention is to cover for the remote device losing its configuration due to power loss or other fatal error.

Device Inactivity

Should the remote device involved in the reporting behavior be marked inactive:

• Configurations for receiving reports from that device will not time out. For normal reporting, this means that the configuration will not be re-sent on timeout.
• Pseudo reporting configurations for receiving reports will not send periodic reads to the device.
• Configurations for sending reports to that device will not send reports.

If the device is later marked active, reporting behavior will resume.

Registry

The registry is created when the gateway first boots and contains power-safe global settings to control various elements of gateway behavior. Individual entries can be accessed and modified through the registry_configuration RPC request. A help RPC request can be used to retrieve all available registry entries. Manually editing the registry file and rebooting is also possible but generally should not be necessary. See Registry Settings for a listing of all registry settings.

Power Safety

Certain information is automatically saved to flash in order to maintain gateway functionality in case of a power failure. During normal operations these files do not need to be modified directly. Generally, the following items are power safe:

• Endpoint and cluster configuration.
• Certain ZCL attribute values.
• Reporting configurations.
• Smart Energy events on SE server clusters.
• Registry settings.
• Alias definitions.

See Saved Files for further information.