ⓘ API Reference with Python Scripting
MQTT Distributor provides a set of scripting functions that allow you to create, read, update, delete, and manage Distributor configuration settings programmatically.
These functions can be executed from any Ignition Scripting Scope using the system.cirruslink.distributor.*operation* format.
The available functions are:
createConfig()– Create a new configuration record.deleteConfig()– Delete an existing configuration record.getConfigNames()– Retrieve the names of configuration resources.isConfigEnabled()– Check whether a configuration resource is enabled.readConfig()– Retrieve an existing configuration record.setConfigEnabled()– Enable or disable a configuration resource.updateConfig()– Modify an existing configuration record.
These functions can be used to manage MQTT Distributor configuration resources and user accounts without manually configuring them through the Gateway web interface. Return values vary by function and are described in the corresponding sections below.
Note: Configuration changes made through scripting do not undergo the same validation as changes made through the UI. For example, deleting a Sets configuration that is referenced by a Servers configuration can cause the UI to display an Internal Error.
createConfig()
Creates a new MQTT Distributor configuration record.
Syntax
system.cirruslink.distributor.createConfig(
type,
name,
config,
enabled,
description
)
Parameters
| Parameter | Type | Description |
|---|---|---|
type | String | Type of configuration resource to create. |
name | String | Unique name for the configuration resource. |
config | Dictionary | Properties that define the configuration resource. |
enabled | Boolean | Optional. Specifies whether the configuration resource is enabled. |
description | String | Optional. Description of the configuration resource. |
The config dictionary contains the properties for the resource. Supported properties are described in the Distributor Configuration Properties section.
Returns
A dictionary representing the config.json of the specified resource.
readConfig()
Retrieves an existing MQTT Distributor configuration record.
Syntax
system.cirruslink.distributor.readConfig(type, name)
Parameters
| Parameter | Type | Description |
|---|---|---|
type | String | Type of configuration resource to read. |
name | String | Unique name of the configuration resource. |
Returns
A dictionary representing the config.json of the specified resource.
updateConfig()
Updates an existing MQTT Distributor configuration record.
Syntax
system.cirruslink.distributor.updateConfig(
type,
name,
collisionPolicy,
config
)
Parameters
| Parameter | Type | Description |
|---|---|---|
type | String | Type of configuration resource to update. |
name | String | Unique name of the configuration resource to update. |
collisionPolicy | String | Specifies how existing configuration properties are handled. Valid options are MergeOverwrite and Overwrite. |
config | Dictionary | Properties to apply to the configuration resource. |
Collision Policies
| Policy | Description |
|---|---|
MergeOverwrite | Replaces the existing properties for the named resource with only the properties included in the call. |
Overwrite | Replaces all existing properties for the named resource with the properties included in the call. |
Returns
A dictionary representing the config.json of the updated resource.
deleteConfig()
Deletes an existing MQTT Distributor configuration record.
Syntax
system.cirruslink.distributor.deleteConfig(type, name)
Parameters
| Parameter | Type | Description |
|---|---|---|
type | String | Type of configuration resource to delete. |
name | String | Unique name of the configuration resource to delete. |
Returns
| Type | Description |
|---|---|
| Boolean | Returns True if the configuration resource was successfully deleted; otherwise, returns False. |
getConfigNames()
Retrieves the names of MQTT Distributor configuration resources.
Syntax
system.cirruslink.distributor.getConfigNames(type, enabled)
Parameters
| Parameter | Type | Description |
|---|---|---|
type | String | Type of configuration resource for which to retrieve names. |
enabled | Boolean | Optional. Filters the results based on whether the configuration resources are enabled. |
Returns
A list of strings containing the names of the matching configuration resources.
isConfigEnabled()
Checks whether an MQTT Distributor configuration resource is enabled.
Syntax
system.cirruslink.distributor.isConfigEnabled(type, name)
Parameters
| Parameter | Type | Description |
|---|---|---|
type | String | Type of configuration resource to check. |
name | String | Unique name of the configuration resource to check. |
Returns
A Boolean indicating whether the specified configuration resource is enabled.
setConfigEnabled()
Enables or disables an MQTT Distributor configuration resource.
Syntax
system.cirruslink.distributor.setConfigEnabled(type, name, enabled)
Parameters
| Parameter | Type | Description |
|---|---|---|
type | String | Type of configuration resource to modify. |
name | String | Unique name of the configuration resource to modify. |
enabled | Boolean | Specifies whether to enable (True) or disable (False) the configuration resource. |
Returns
A Boolean indicating whether the operation was successful.
Distributor Configuration Properties
The type parameter specifies the type of configuration resource to operate on. The config dictionary contains the properties associated with that resource.
The supported configuration types and their properties are described below.
General Configuration Properties
| Property | Type | Description |
|---|---|---|
enabled | Boolean | Whether the configuration resource is enabled. |
name | String | Unique name of the configuration resource. |
enableDistributor | Boolean | Whether to enable MQTT Distributor. |
enableTcp | Boolean | Whether to enable plain TCP connections. |
port | Integer | Standard, non-secure MQTT port. |
enableWebsocket | Boolean | Whether to enable WebSocket connections. |
websocketPort | Integer | Standard, non-secure WebSocket port. |
enableTls | Boolean | Whether to enable TLS connections. |
securePort | Integer | Secure MQTT port. |
allowAnonymousConnections | Boolean | Whether to allow anonymous connections. |
customProperties | String | Custom or internal properties. |
enforceUniqueLwtTopic | Boolean | Whether to enforce unique Will Message topics across MQTT clients. |
uniqueLwtTopicFilter | String | Comma-separated list of topic filters used to enforce unique Will Message topics. |
User Configuration Properties
| Property | Type | Description |
|---|---|---|
enabled | Boolean | Whether the configuration resource is enabled. |
name | String | Unique name of the configuration resource. |
password | String | User password. |
ACLs | String | Comma-separated list of access control lists (ACLs). |
Configuration Dictionary Structure
The config parameter is a dictionary containing the properties for the configuration resource being created or updated. The properties supplied should correspond to the configuration type specified by type.
For additional details about the supported configuration properties, refer to the General Configuration Properties and User Configuration Properties tables above.