The Azure Injector module provides the ability to push Tag data to an Azure IoT Hub.
The The settings configuration for this module are located under the Configure tab of the Ignition Gateway web UI in the left hand navigation pane under 'Azure Injector Settings'. Once in the configuration section there are four tabs:
Image Added
Image Added
The configuration options for each of the six tabs - General, Azure IoT Hubs, Sets, Azure IoT Edges, Azure Event Hubs, Sets and Tag Agents . Each of these tabs is described in detail in the following sections.
General
The first tab contains the general settings for the Azure Injector module.
Image RemovedThe general configurations options available on this tab are listed below:
...
- are detailed below.
GeneralThe configuration section available is Main.
Image Added options Main
- Enabled
- Sets whether the module is enabled or disabled. If disabled, the Tag Agents will not run and now data will be pushed to any configured endpoints.
Azure IoT HubsThe Azure IoT Hubs tab has two parts - Settings and Certificates
Anchor |
---|
| azureiothubssettings |
---|
| azureiothubssettings |
---|
|
Azure IoT Hubs - SettingsThis tab provides a list of the next tab is the list of Azure IoT Hub endpoints that the module should connect to to push tag data.
Image Removed
One or more Azure IoT Hub endpoints can be configured on this tab.
Image Added
Clicking on the 'Create new Azure IoT Hub .. The configuration options for an Azure IoT Hub connection are listed below.
...
' link will bring up the following form to add a new Azure IoT Hub. The configuration sections available are Main, Authentication, Store & Forward and Advanced
Anchor |
---|
| azureiothubsettingmain |
---|
| azureiothubsettingmain |
---|
|
Azure IoT Hub Settings - Main
Image Added- Setting Name
- This is a friendly name of the Azure IoT Hub used to easily identify it. This must also be unique.
- Enabled
- Whether or not this connection is enabled.
- Protocol
- The protocol to use when connecting to the Azure IoT Hub. It can be one of the following:Currently MQTT only is available.
- MQTTNote: If When using MQTT as the protocol, the connection string must be a 'device' connection string when not using certificate based authentication.
- Set
- The Set to associate this Azure IoT Hub connection with.
Anchor |
---|
| azureiothubsettingsauthentication |
---|
| azureiothubsettingsauthentication |
---|
|
Azure IoT Hub Settings - Authentication
Image Added- Enable Certificate Based Authentication
- Whether or not to use certificate based authentication.
- If not using certificate based authentication, the 'Password/Connection String' field must be used.
- If certificate based authentication is used, the other Authentications fields must be used.
- Password/Connection String (required if not using certificate based authentication)
- This is the Azure IoT Hub connection string used to connect. This string can be one of the following:
- An IoT Hub connection string with the following format:
- HostName=<Host Name>;SharedAccessKeyName=<Key Name>;SharedAccessKey=<SAS Key>
- An IoT Hub's Event Hub-compatible connection string with the following format:
- Endpoint=<ENDPOINT>;SharedAccessKeyName=<Key Name>;SharedAccessKey=<KEYVALUE>
- An IoT Hub device connection string with the following format:
- HostName=<Host Name>;DeviceId=<Device Name>;SharedAccessKey=<Device Key>
- Note: If using MQTT as the protocol, this is the connection string format that must be used.
- MQTT Hostname (required if using certificate based authentication)
- This is the DNS endpoint name of your IoT Hub
- Device ID (required if using certificate based authentication)
- The Device ID as provisioned in the IoT Hub to connect as
- CA Certificate File
- The CA certificate file of your IoT Hub. See this document for more information.
- The drop down is populated from a list of files that have been uploaded to the IoT Hub/Certificates tab.
- Client Certificate File (required if using certificate based authentication)
- The client certificate file as provisioned for this device.
- The drop down is populated from a list of files that have been uploaded to the IoT Hub/Certificates tab.
- Client Private Key File (required if using certificate based authentication)
- The client private key file that was used in generating the certificate for this device
- The drop down is populated from a list of files that have been uploaded to the IoT Hub/Certificates tab.
- Password/Private key password
- The password used for the private key if one was specified for the key
Anchor |
---|
| azureiothubsettingsstore&forward |
---|
| azureiothubsettingsstore&forward |
---|
|
Azure IoT Hub Settings - Store & Forward
Image Added
- Store & Forward Enabled
- Whether to enable Store & Forward capabilities for this endpoint
- Store & Forward Type
- The type of the Store & Forward mechanism
- Message Capacity
- The Maximum number of messages to store before dropping the oldest historical messages
- Flush Period
- The period of time to wait (in milliseconds) between sending when flushing messages
Anchor |
---|
| azureiothubsettingsadvanced |
---|
| azureiothubsettingsadvanced |
---|
|
Azure IoT Hub Settings - Advanced
Image Added
- Keep Alive
- The MQTT keep alive timeout in seconds
- Max Message Size
- The maximum message size in bytes that any message can be when pushing to IoT Hub.
- Session Expiration
- How long in seconds to specify for session token timeouts when not using certificate based authentication
- Content Type
- Content Encoding
- The content encoding to include in the topic to Azure IoT Hub
- NONE (default) - No content encoding header will be included with the message
- UTF_8 - The 'utf-8' header will be included with the message and make the body of the message available for routing if the content type is also set to APPLICATION_JSON
- UTF_16 - The 'utf-16' header will be included with the message and make the body of the message available for routing if the content type is also set to APPLICATION_JSON
- UTF_32 - The 'utf-32' header will be included with the message and make the body of the message available for routing if the content type is also set to APPLICATION_JSON
- See this Using IoT Hub Message Based Routing tutorial for more details
- Azure Date/Time Format
- The date/time format to use when pushing messages to IoT Hub
- LONG_MS_SINCE_EPOCH (default) - The timestamp values will all be as numbers in milliseconds since epoch (Jan 1, 1970) in UTC
- STRING_AZURE_COMPAT - The timestamp will be pushed as described here. This is useful when wanting to use 'edge' timestamps in Azure Time Series insights.
- See this Pushing Data to Azure Time Series Insights tutorial for more details
Clicking on the "Create new Azure IoT Hub Setting..." link will bring up the following form for adding a new Azure IoT Hub endpoint.
Image Removed
Anchor |
---|
| azureiothubscertificates |
---|
| azureiothubscertificates |
---|
|
Azure IoT Hubs - CertificatesThis tab provides a list of the certificate or private keys if loaded and available for The following shows the page where certificate files are uploaded and can then be selected in the Main IoT Hub Settings page when using certificate based authentication. This should generally include the root CA for your IoT Hub, the client certificate file, and the client private key file.
Note |
---|
All certificate or private keys must be in PEM format. In addition, any private key file must also be in RSA PKCS1 format. |
Image Added
Clicking on the 'Create new Certificate ..' link will bring up the following form to add a new Certificate. The Certificates tab contains a single Main section.
Image Removed
Anchor |
---|
| azureiothubcertificatesmain |
---|
| azureiothubcertificatesmain |
---|
|
Azure IoT Hub Certificates - Main
Image Added
- Certificate File Upload
- Browse to the certificate file or private key to upload.
- Friendly Name
- The friendly name of the certificate file or private key.
- File Description
- The description of the certificate file or private key.
Anchor |
---|
| azureeventhubs |
---|
| azureeventhubs |
---|
|
Azure Event HubsThe next tab is the This tab provides a list of Azure Event Hub endpoints that the module should connect to to push tag data.
Image Removed
One or more Azure Event Hub endpoints can be configured on this tab. The configuration options for an Azure Event Hub connection are listed below.
...
Image Added
Clicking on the 'Create new Azure event Hub ..' link will bring up the following form to add a new Event Hub. The configuration sections available are Main, Store & Forward and Advanced
Anchor |
---|
| eventhubssettingsmain |
---|
| eventhubssettingsmain |
---|
|
Azure Event Hub - Main
Image Added- Setting Name
- This is a friendly name of the Azure Event Hub used to easily identify it. This must also be unique.
- Enabled
- Whether or not this connection is enabled.
- Password/Connection String
- Set
- The Set to associate this Azure Event Hub connection with.
Anchor |
---|
| eventhubssettingsstoreandforward |
---|
| eventhubssettingsstoreandforward |
---|
|
Azure Event Hub Settings - Store & Forward
Image Added- Store & Forward Enabled
- Whether to enable Store & Forward capbilities capabilities for this endpoint
- Store & Forward Type
- The type of the Store & Forward mechanism
- Message Capacity
- The Maximum number of messages to store before dropping the oldest historical messages
- Flush Period
- The period of time to wait (in milliseconds) between sending when flushing messages
Anchor |
---|
| eventhubssettingsadvanced |
---|
| eventhubssettingsadvanced |
---|
|
Azure Event Hub Settings - Advanced
Image Added- Max Message Size
- The maximum message size for the Azure Event Hub. Default is 262144 bytes (256KB).
- EventHub Basic: 262144 bytes (256KB)
- EventHub Standard or better: 1048576 bytes (1MB)
- Content Encoding
- The content encoding of the data to push to Event Hub. Current option is In_Memory
- Azure Date/Time Format
- The date/time format to use when pushing messages to IoT Hub
- LONG_MS_SINCE_EPOCH (default) - The timestamp values will all be as numbers in milliseconds since epoch (Jan 1, 1970) in UTC
- STRING_AZURE_COMPAT - The timestamp will be pushed as described here. This is useful when wanting to use 'edge' timestamps in Azure Time Series insights.
- See this Pushing Data to Azure Time Series Insights tutorial for more details
Clicking on the "Create new Azure Event Hub Setting..." link will bring up the following form for adding a new Azure Event Hub endpoint.
Image Removed
Sets
SetsThis The Sets tab contains a list of Azure Sets. Each set represents a grouping of Azure IoT/Event Hub endpoints. When a set is referenced by a Tag Agent, the Agent will push Tag data to all Azure IoT/Event Hub endpoints contained within that Set.
Note |
---|
The Sets are disjoint, meaning that a single Azure IoT/Event Hub |
...
endpoint cannot be in more than one set. |
Out of the box the Azure Injector module will have one "Default" set defined.
Image Removed
Additional Sets can be configured for situations where multiple Tag Agents will need to push to different Azure IoT Hub endpoints. The configuration options for Sets are listed below.
...
Image Added
Clicking on the 'Create new Azure Set ..' link will bring up the following form to add a new Set. The configuration section available is Main
Sets - Main
Image Added- Name
- This is the friendly name of the set used to easily identify it.
- Description
- This is a friendly description of the set.
- Push Policy
- This defines which endpoints to push to. If PUSH_TO_ALL is selected, every endpoint that is part of this set will receive all messages. If PUSH_TO_ANY is selected, only one of the endpoints that is part of this set will receive any given message. PUSH_TO_ANY is useful when adding endpoint configurations to increase the throughput of the Injector.
Clicking on the 'Create new Azure Set...' link will bring up the following form to add a new Set.
...
Tag AgentsTag Agents are the workers within Azure Injector that monitor tag events, convert them to a JSON representation, and push them to one or more Azure IoT Hub endpoints. Out Out of the box the Azure Injector module will have one "default" Tag Agent defined.
Image Removed
Tag Agents are configured to point to a single folder. All Tags within that folder will be monitored by the Tag Agent.
Image Added
Clicking on the 'Create new Tag Agent Settings..' link will bring up the following form to add a new Tag Agent. The configuration sections available are Agent Settings, Sparkplug Settings and Advanced
Anchor |
---|
| tagagentsagentsettings |
---|
| tagagentsagentsettings |
---|
|
Tag Agents - Agent Settings
Image Added- Tag Provider Name
- The name of the Tag provider containing the tags.
- Tag Path
- An optional folder path under the Tag provider where the root folder of the Tags can be found.
- Push Trigger
- Defines what triggers a push to the cloud endpoint
- EVENT_DRIVEN (default) - when a tag change event (value or quality) occurs, and no pending push exists, tag events will be aggregated for the 'Tag Pacing Period' before being pushed.
- PERIODIC - will push the latest data for all tags associated with the Agent every 'Tag Pacing Period'. With this option, only one event per tag will be sent and tag change events will not be captured.
- Tag Pacing Period
- The buffer period, in milliseconds, that Tag events will be aggregated into a single payload before pushing.
- Convert UDTs
- Whether to convert UDT members to normal Tags before publishing. If enabled the Tags representing the UDT member will retain their member path prefixed by the UDT Instance name.
- Publish UDT Definitions
- This can will only be set used if 'Convert UDTs' is false
- Whether or not to push the UDT Definitions in the the NBIRTH messages
- Optimize UDTs
- This can will only be set used if 'Convert UDTs' is false
- Whether or not to 'convert UDTs' only for DATA messages.
- Set
- The Set of Azure IoT Hub endpoints that the Tag Agent will push to.
- Auto-discover Tags
- Whether newly added tags should be dynamically scanned and their values pushed. This field is disabled by default. It should remain disabled while manually editing tags and/or their configurations. It should only typically be enabled in systems where tags are created in real time.
Tip |
---|
Review the Managing UDTs through Injector Tag Agents for more details on the Convert UDTs, Publish UDT Definitions and Optimize UDTs parameters |
Anchor |
---|
| tagagentssparkplugsettings |
---|
| tagagentssparkplugsettings |
---|
|
Tag Agents - Sparkplug Settings
Image Added- Group ID
- An ID representing a logical grouping of MQTT Edge Of Network (EoN) Nodes and Devices into the infrastructure.
- Edge Node ID
- An ID that uniquely identifies the MQTT Edge Of Network (EoN) Node within the infrastructure.
- Device ID
- An optional ID that uniquely identifies a Device within the infrastructure.
...
As you can see, the Sparkplug settings can be used to either hard-code these IDs, or leave them blank so that the Agent will scan and discover them based on the tag tree layout. For more information see this MQTT Transmission Transmitters and Tag Trees document keeping in mind that MQTT Transmission Transmitters can be thought of like 'Agents' in Injectors with regard to Sparkplug IDs and tag trees.
Anchor |
---|
| tagagentsadvanced |
---|
| tagagentsadvanced |
---|
|
Tag Agents - Advanced
Image Added
- Filtered Properties
- A semicolon delimited list of Tag properties to filter/block from being published. These should typically not be modified unless there is an explicit requirement that a specific property is needed to be added or removed from the default.
...
...