Configuration Reference¶
Saved Files¶
Global Saved Files¶
The gateway stores the following files under /WEB/python/ for persistent configuration and startup behavior. If necessary, these files can be viewed directly using Device Cloud.
| File | Description |
|---|---|
| registry_settings.ini | Stores the current state of the registry settings for the gateway. (See registry_configuration) Each line of the registry file is a single entry formatted as follows where type is int, bool, or str. Format: registry_name [type registry_value] If a type and registry_value are not given then the registry entry exists but has no value. Sample Entry: Cluster.disable_APS_encryption bool False |
| devices.ini | Stores the 64-bit extended addresses of all known devices. Any device added via the add_device RPC request will be added to this file. If the gateway is in open joining mode, any new devices which become active will also be added to this file. Devices will only be removed from this file via the remove_device RPC request. This file is primarily used by explicit add mode as a way to remember which devices should be allowed to become active. In open joining mode it only serves to remember which devices have been seen on the network previously. Note It is possible to modify this file directly. However, when the gateway is operating as a coordinator, its XBee radio also maintains an internal table of link keys. Adding a device to devices.ini directly does not update the XBee radio’s internal table, meaning the new device may not be able to join. The add_device and remove_device RPC requests update the internal table and should be used normally. Sample Entry: 00:11:22:33:44:55:66:77 |
| paths.ini | Specifies additional system paths from which modules can be imported. Often these will be zip files. (See add_path and remove_path) Sample Entry: Custom_Extensions.zip |
| modules.ini | Specifies additional modules to be imported on startup. As with a python import, do not specify the file extension. (See add_module and remove_module) Sample Entry: Custom_Interface_Module |
| interfaces.ini | Specifies additional interface classes to be instantiated on startup. (See add_interface and remove_interface) Sample Entry: Custom_Interface_Class |
| endpoints.ini | Specifies additional endpoints to be instantiated on startup. Optional parameters default to the defaults of the class. (See add_endpoint and remove_endpoint) Format: endpoint_class_name endpoint_id [profile_id [device_id [device_version]]] Sample Entry: SE_EnergyServicePortal 0x5E |
| clusters.ini | Specifies additional clusters to be instantiated on startup. Optional parameters default to the defaults of the class. (See add_cluster and remove_cluster) Format: cluster_class_name endpoint_id [server_or_client [cluster_id [enable_APS_encryption]]] Sample Entry: ZCL_Cluster 0x5E Client 0x0201 False |
Registry Settings¶
The registry stores configuration parameters for miscellaneous global gateway behaviors. Registry settings can be modified by using the registry_configuration RPC command.
Reset Registry to Default Settings¶
To reset the registry to default settings, delete /WEB/python/registry_settings.ini and reboot the device. This allows a required custom configuration to be maintained.
Registry Configuration Parameters¶
| Registry Setting | Default | Description |
|---|---|---|
| Background_Thread.watchdog_alloc | 65536 | As of 1.4.0: The system must be able to service a request for a contiguous memory chunk of at least this size. Set to 0 to disable allocation check. As of 1.5.0:Removed (Replaced by watchdog free memory checks). |
| Background_Thread.watchdog_alloc_interval | 30 | As of 1.4.0: The watchdog memory allocation check will run every this many seconds. As of 1.5.0: Removed (Replaced by watchdog free memory checks). |
| Background_Thread.watchdog_memory | 225000 | As of 1.5.0: The system must have at least this much free memory. Set to 0 to disable memory check. As of 1.5.1: Only used on platforms running NDS. |
| Background_Thread.watchdog_memory_duration | 120 | As of 1.5.0: The watchdog memory check will reboot when consecutive memory checks trigger for at least this many seconds. Set to 0 to reboot on the first trigger. As of 1.5.1: Only used on platforms running NDS. |
| Background_Thread.watchdog_memory_interval | 30 | As of 1.5.0: The low memory watchdog will run every this many seconds. As of 1.5.1: Only used on platforms running NDS. |
| Background_Thread.watchdog_timeout | 300 | If more than this many seconds have passed since the last watchdog hit, the gateway will be rebooted. Set to 0 to disable watchdog. As of 1.5.1: Only used on platforms running NDS. |
| Buffer_Manager.max_flash_size | X2: 102400 (100kB) Other: 4194304 (4MB) | As of 1.6.0: The maximum amount of shared buffer space that can be allocated from flash (in bytes). |
| Buffer_Manager.max_ram_size | X2: 102400 (100kB) Other: 4194304 (4MB) | As of 1.6.0: The maximum amount of shared buffer space that can be allocated from RAM (in bytes). |
| Buffer_Manager.store_to_flash_delay | 300 | As of 1.6.0: If greater than 0, if a buffer pool has contents older than this many seconds, all of its contents will be saved to flash up to available space. |
| Cluster.disable_APS_encryption | False | If True, the APS encryption checks for clusters which normally require encryption will be ignored. For normal operation this should be set to False. Note that changing this value may result in the XBee leaving its current network. |
| Conversation.TX_status_timeout | 10 | Before 1.4.0: If a conversation does not receive a TX status message from the XBee within this many seconds, it will stop waiting for a TX status message but will not indicate TX success either. As of 1.4.0: Removed (Conversation.default_timeout now manages both TX_status and actual response). |
| Conversation.default_timeout | Before 1.4.0: 30 As of 1.4.0: 10 |
For unicast conversations with an expected response message, if that response has not arrived within this many seconds a timeout has occurred. For broadcast conversations, the conversation will automatically terminate after this many seconds. |
| device_blacklist | “” (empty string) | As of 1.6.0: For coordinator gateways, a comma-separated list of devices (specified by extended address) which should be removed if they show up on the network. A device is added to the blacklist if it is removed from the network via the remove_device RPC request with the remove_from_network parameter set to True (its default value). A device is removed from the blacklist if it is explicitly added to the network using the add_device RPC request. |
| Endpoint.max_socket_retries | 3 | Before 1.4.0: The maximum number of times that the ZigBee socket of an endpoint can fail to send a message before the message is dropped. As of 1.4.0: Removed. |
| ERTConnector.ert_update_timeout | 1800 | If a configured ERT meter has not updated within this time period (seconds) an error will be flagged. |
| main.tick_delay | Before 1.6.0: 0.05
|
The amount of time between ticks of the ZigBee node and RPC manager, in seconds. As of 1.6.0: Except on the X2, sockets use a longer select time that can be interrupted by a socketpair. This is why the polling can be slower on these platforms. |
| Message_Log.RPC_severity | 1 | If a message is generated by the gateway with severity of this level or greater, an RPC message will be generated. (0 = Debug, 1 = Warning, 2 = Error) |
| ReportCollection.default_jitter | 0 | As of 1.6.0: A jitter will be randomly chosen between 0 and this number for each reporting collection push and used to delay the push by that many seconds. |
| ReportWatchdog.enabled | False | New in 1.6.2: When enabled, ReportWatchdog.enabled monitors for report stalls. When report stalls are detected, resets ZCL attribute reporting When disabled, ReportWatchdog.enabled does not monitor reporting. |
| RPC_Manager.max_buffer_items | 250 | Before 1.5.0: The maximum number of messages that can be stored in the gateway’s output buffer before older messages are dropped. As of 1.5.0: Removed. (Replaced with RPC_Manager.max_buffer_length). |
| RPC_Manager.max_buffer_length | 100000 | As of 1.5.0: The maximum total number of bytes of all messages in the manager’s output buffer before older messages will be dropped. If 0, there is no limit on buffer length. As of 1.6.0: Removed. (Replaced with RPC_Manager.output_buffer_priority, which is based on Buffer_Manager.max_flash_size and Buffer_Manager.max_ram_size). |
| RPC_Manager.max_output_length | X2: 65536 (65kB) Other: 4194304 (4MB) | As of 1.6.0: The maximum number of bytes of any single pushed message. If a single message exceeds this size it will be subdivided. If push is not being used, this is the maximum size of a get_responses response instead. |
| RPC_Manager.output_buffer_priority | 0 | As of 1.6.0: The priority level of the buffer pool used for the RPC Manager’s general output buffer. |
| RPC_Manager.pushed_file_extension | “xml” | Before 1.4.0: If pushing is enabled, this string will be used as the file extension of the pushed file. As of 1.4.0: Removed. |
| RPC_Manager.pushed_file_prefix | “RPC_Response” | If RPC_Manager.use_push is TRUE, this string will be used as the first part of filename for the pushed file. |
| RPC_Manager.store_to_flash_delay | -1 | As of 1.5.0: If greater than 0, this is the number of seconds since the last attempted push that messages will start being saved to flash; this state is cleared whenever a push succeeds. If 0, messages will be saved immediately after generation. If less than 0, saving messages to flash will be disabled. No effect if push is not enabled. As of 1.6.0: Removed. (Replaced with Buffer_Manager.store_to_flash_delay). |
| RPC_Manager.synchronous_request_timeout | 40 | The maximum number of seconds that a synchronous request will wait for a response before timing out. |
| RPC_Manager.use_push | Before 1.4.0: False As of 1.4.0: True |
If True, asynchronous RPC responses will be automatically pushed to Device Cloud. See Automatic Response Pushing. Note: Device Cloud may configure use_push to be True when a gateway first connects to Device Cloud. |
| SE_Client.active_event_check_interval | 0 | Every this many seconds, if any SE client cluster does not have an active event, an event request will be sent to the corresponding SE server cluster. If 0, these checks will be disabled. |
| SE_MessageCluster_Server.cancel_on_confirmation | False | If True, when a message confirmation is received by the Messaging server, a corresponding cancel event will be sent to all other clients who previously received the event. |
| SE_Profile.profile_version_1_X | 1 | As of 1.5.0: The enumerated identifier of the Smart Energy profile version to be used. |
| SE_Server.event_retransmission_check_interval | 300 | Every this many seconds, all SE events will be checked to ensure that they have been sent to all active client devices. Any clients which have not yet received some events will be sent those events by the server. If set to 0, these checks will be disabled. |
| Time_Server.enable_superseding_bit | False | As of 1.5.0: If True, the superseding bit in time status will be set. Only applies to SE 1.1 and newer networks. Should normally be set to False. |
| Time_Synchronizer.initial_sync_interval | 60 | How often the gateway attempts to synchronize its time before a successful synchronization has occurred, in seconds. |
| Time_Synchronizer.sync_interval | 7200 | How often the gateway attempts to synchronize its time after a successful synchronization has occurred, in seconds. |
| Time_Synchronizer.use_NTP_server | not specified | Before 1.5.0: If True, or if not specified and the gateway does not have a ZCL time client, the gateway will periodically attempt to synchronize time with an NTP time server. See Time Synchronization. As of 1.5.0: Removed. (NTP synchronization is being transitioned to the operating system, see Time Synchronization). |
| Time_Synchronizer.use_os_timezone | False | New in 1.6.5: If True, the device uses the OS timezone when you do not set a timezone or when you clear the timezone setting using clear_timezone. See Time Synchronization. |
| Time_Synchronizer.use_ZCL_server | not specified | If True, or if not specified and the gateway has a ZCL time client, the gateway will periodically attempt to synchronize time with a ZCL time server. See Time Synchronization. |
| Version.version | (variable) | As of 1.4.0: The version of the framework as of the most recent execution. For example, 1.4.0 will be set to the string “1.4.0”. |
| ZCL_Cluster.disable_default_response | True | If True, the disable default response bit of ZCL messages generated by the gateway will be set to 1. If False the bit will be set to 0. |
| ZCL_Cluster.ignore_incomplete_records | True | As of 1.4.0: If TRUE, a received ZCL frame ending with an incomplete record will not be rejected. |
| ZCL_Endpoint.enable_direction_bit_correction | True | If True, when a ZCL message is received with the direction bit indicating a destination client or server cluster which the endpoint does not support, the message will instead be routed to the corresponding server or client cluster, respectively, if that cluster exists. |
| ZDO_Device_Manager.full_refresh_interval | 86400 (1 day) | How often all ZDO device information for all devices will be queried, even for fully discovered devices, in seconds. See Device Discovery |
| ZDO_Device_Manager.join_interval | 90 | For router gateways, the number of seconds between join attempts when the XBee radio is not on a network and is attempting to join. If 0, these join attempts will be disabled. |
| ZDO_Device_Manager.max_sequential_TX_failures | 2 | If this many transmission failures to a particular device occur in a row, that device will be marked as inactive. See Device Activity |
| ZDO_Device_Manager.node_list_refresh_interval | 0 | How often the underlying NDS node list, which is sometimes needed for detecting end devices, is refreshed, in seconds. Set to 0 to disable. |
| ZDO_Device_Manager.refresh_interval | 120 | How often the periodic match descriptor broadcast for device detection is sent, in seconds. See Device Activity |
| ZDO_Device_Manager.require_explicit_device_add | False | Before 1.5.0: If False, remote devices can be added to the local list of devices when they are detected. If not specified, defaults to whether the XBee radio is a coordinator or not. See Explicit Device Add and Open Join As of 1.5.0: Removed. Behavior is hardcoded to False. |
| ZigBee_Socket.max_socket_retries | 3 | As of 1.4.0: The maximum number of times that the ZigBee socket can fail to send a message before the message is dropped. |