Versions Compared

Old Version 16

changes.mady.by.user Wes Johnson

Saved on

compared with

New Version Current

changes.mady.by.user Gill Houghton

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The Azure Injector module provides the ability to push Tag data to an Azure IoT Hub, Azure IoT Edges, Azure Event Hubs and Azure IoT Central endpoints.

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 seven tabs - General, Azure IoT Hubs, Azure IoT Edges, Azure Event Hubs, Azure IoT Central, Sets, and Tag Agents.  Each of these tabs is described in detail in the following sections. - are detailed below.

Anchor
general
general
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:

...

configuration section available is Main. Image Added

  • 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.


Anchor
azureiothubs
azureiothubs
Azure IoT Hubs

The Azure IoT Hubs tab has two parts - Settings and CertificatesImage Added

Anchor
azureiothubssettings
azureiothubssettings
Azure IoT Hubs - Settings

This tab provides a list of the Azure IoT Hub endpoints 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. The configuration options for an  

Clicking on the 'Create new Azure IoT Hub connection are listed below.

Main

..' 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 - MainImage Added

  • Setting Name
      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: 
        • MQTT
          • Note: If using MQTT as the protocol, the connection string must be a 'device' connection string when not using certificate based authentication.
      • Currently MQTT only is supported. 
    • Set
      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.
      • This determines the authentication fields available for use.
    • Password
      • Available if . 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 This is the Azure IoT Hub device connection string used to connect .  This string can be one of in the following format:An IoT Hub connection string with the following format:
      • HostName=<Host Name>;SharedAccessKeyName=<Key HostName=<Host Name>;DeviceId=<Device Name>;SharedAccessKey=<SAS <Device 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
    • MQTT Hostname
      • Available if using certificate based authentication 
      • This is the DNS endpoint name of your IoT Hub
    • Device ID
      • Available if using certificate based authentication 
      • The Device ID to connect to as provisioned in the IoT Hub
    • CA Certificate File
      • Available if using certificate based authentication
      • The CA certificate that signed the SSL certificate being used in the IoT Hub server. 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 FileCA 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 Private Key File
      • Available 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 deviceprivate key file that was used in generating the certificate for the Device ID specified above. See this Connecting to Azure IoT Hub with Certificate Based Authentication for details on creating the client private key 
      • The drop down is populated from a list of files that have been uploaded to the IoT Hub/Certificates tab.
    • Password/Private key password
      • Available if using certification based authentication
      • The password used for the private key if one was specified for the keyClient Private Key File

    Anchor
    azureiothubsettingsstore&forward
    azureiothubsettingsstore&forward
    Azure IoT Hub Settings - Store & Forward

    Note

    From release 4.0.19, major improvements have been made to the disk-backed History Store. As a result, Message Capacity has been deprecated and History Max Age added

    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

    Store & Forward

    • 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

    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

    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.

    Image Removed

    Azure Event Hubs

    The next tab is the 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.

    Notes

    • Ports 5671 and 5672 need to be opened for outbound traffic so the EventHubClient can establish an AMQP connection to the EventHub.

    The configuration options for an Azure Event Hub connection are listed below.

    Main

    • Setting Name
      • This is a friendly name of the Azure Event Hub used to easily identify it.  This must also be unique.
    • Password/Connection String
      • This is the Azure Event Hub connection string used to connect. 
      • NOTES: Be sure to provide the connection string for the EventHub itself and not the EventHub Namespace. They both have connection strings, but the one for the EventHub will be of the form -

        Endpoint=<YOUR_ENDPOINT>;SharedAccessKeyName=<YOUR_KEYNAME>;SharedAccessKey=<YOUR_KEY>=;EntityPath=<YOUR_EVENTHUB_ENTITYPATH>

        The Namespace connection string will not contain the entity path.

    • Set
      • The Set to associate this Azure Event Hub connection with.
    • Certificate File Upload
      • The server certificates to use if required.

    Store & Forward

    • Store & Forward Enabled
      • Whether to enable Store & Forward capbilities 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

    Advanced

    • 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)

    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

    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. 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.

    Main

    • Name
      • This is the friendly name of the set used to easily identify it.
    • Description
      • This is a friendly description of the set.
      • options: In_Memory and Disk_Backed (available in release 4.0.17 and higher)
      • Data stored with an In_Memory Store & Forward will not be persisted across a module configuration change, module disable/enable, module restart or power loss. 
      • Data stored with a Disk_Backed Store & Forward will persist across a module configuration change, module disable/enable, module restart or power loss
    • Message Capacity - deprecated in 4.0.19
      • The maximum number of messages to store before dropping the oldest historical messages
    • History Max Age
      • The maximum number of minutes to store history before dropping the data
    • 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. Generally, this should match the max message size allowed by IoTHub.
    • Session Expiration
      • How long in seconds to specify for session token timeouts when not using certificate based authentication
    • Content Type

      • The content type to include in the topic to Azure IoT Hub

        • NONE (default) - No content type header will be included with the message
        • APPLICATION_JSON - The application/json header will be included with the message and make the body of the message available for routing if content encoding is also not 'NONE'
      • See Using IoT Hub Message Based Routing tutorial for more details
    • 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 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 Pushing Data to Azure Time Series Insights tutorial for more details


    Anchor
    azureiothubscertificates
    azureiothubscertificates
    Azure IoT Hubs - Certificates

    This tab provides a list of the certificate or private keys if loaded and available for certificate based authentication.

    This will include the CA Certificate that signed the SSL cert being used on the IoTHub server along with any device(s) certificate and private key files.

    Note

    All certificate or private keys must be in PEM format.

    For modules pre 4.0.9, only RSA PKCS1 format private keys are supported.

    For modules 4.0.9 to 4.0.16, RSA PKCS8 format private keys are also supported.

    For modules 4.0.17 or higher, password encrypted PKCS8 private keys are also supported.

    Image Added

    Clicking on the 'Create new Certificate Clicking on the 'Create new Azure Set. ..' link will bring up the following form to add a new Set.

    Image RemovedTag Agents

    Tag 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 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. 

    Agent Settings

    • 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.
    • 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 only be set if 'Convert UDTs' is false
        • Whether or not to publish UDT definitions in the NBIRTH 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.

    Sparkplug Settings

    • 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.

    The Sparkplug settings are optional and allow for an additional customization of how the Tag Agent scans and discovers tag within the specified Tag Path.  Here is a brief description of how the Agent scans/discovers folders based on the different combinations of potential Sparkplug Settings.

    • If all three IDs are left blank the Agent will assume the following folder structures follow the Tag Path:
      • <groupFolder>/<edgeNodeFolder>/<deviceFolder>/<tags>
      • <groupFolder>/<edgeNodeFolder>/<tags>
    • If only the Group ID is specified the Agent will assume the following folder structure follows the Tag Path:
      • <edgeNodeFolder>/<deviceFolder>/<tags>
      • <edgeNodeFolder>/<tags>
    • If the Group ID and the Edge Node ID are specified the Agent will assume the following folder structure follows the Tag Path:
      • <deviceFolder>/<tags>
      • <tags>
    • If the Group ID, Edge Node ID, and the Device ID are specified the Agent will assume the following folder structure follows the Tag Path:
      • <tags>

    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. 

    Advanced

    Certificate. The Certificates tab contains a single Main section.

    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
    azureiotedges
    azureiotedges
    Azure IoT Edges

    The Azure IoT Edges tab has two parts - Settings and Certificates

    Anchor
    azureiotedgesettings
    azureiotedgesettings
    Azure IoT Edge - Settings

    This tab provides a list of Azure IoT Edge endpoints that the module should connect to to push tag data. One or more Azure IoT Edge endpoints can be configured on this tab.Image Added

    Clicking on the 'Create new Azure IoT Edge..." link will bring up the following form to add a new Azure IoT Edge. The configuration sections available are Main, Connectivity, Authentication, Store & Forward and Advanced. 

    Anchor
    azureiotedgesettinsgmain
    azureiotedgesettinsgmain
    Azure IoT Edges Settings - MainImage Added

    • Setting Name
      • This is the friendly name of the Azure IoT Edge used to easily identify it. This must be unique.
    • Enabled
      • Whether or not this connection is enabled.
    • Set
      • The Set to associate this Azure IoT Edge connection with
    • Automatic
      • Whether the Azure Edge environment variables will be used as the connection parameters rather than those defined in the connectivity and Authentication sections of the configuration.

    Anchor
    azureiotedgesettingsconnectivity
    azureiotedgesettingsconnectivity
    Azure IoT Edges Settings - ConnectivityImage Added

    • MQTT Server URL
      • The MQTT Server URL for the Azure IoT Edge. Default: ssl://edgehub:8883

    Anchor
    azuireiotedgesettingsauthentication
    azuireiotedgesettingsauthentication
    Azure IoT Edges Settings - AuthenticationImage Added

    • Enable Certificate Based Authentication
      • Whether or not to use certificate based authentication.
      • If not using certificate based authentication, the 'Password' field must be used.
      • If certificate based authentication is used, the other Authentications fields must be used.
    • Password (required if not using certificate based authentication)
      • This is the Azure IoT Edge connection string used to connect. 
      • This is either the Connection string associated with the Child Device or with the Azure Edge Module
    • CA Certificate File
      • The CA certificate file currently in use on the IoT Edge instance. 
      • It is used for both Certificate and Connection String based authentication and is the CA Device Certificate that was uploaded to the Azure Edge instance.
      • The drop down is populated from a list of files that have been uploaded to the IoT Edge/Certificates tab.
    • Client Certificate File (required if using certificate based authentication)
      • The client certificate file currently in use
      • The drop down is populated from a list of files that have been uploaded to the IoT Edge/Certificates tab.
    • Client Private Key File (required if using certificate based authentication)
      • The client private key file currently in use
      • The drop down is populated from a list of files that have been uploaded to the IoT Edge/Certificates tab.
    • Password/Private key password
      • The password used for the private key if one was specified for the key
    • 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 Azure IoT Edge configuration
    • Module ID Config Option
      • The method to use to configure the Module ID. This should be 'NONE' if using a 'child device' connection to Edge. It should be 'ENVIRONMENT_VARIABLE' if you want to pick up the Module ID from the 'IOTEDGE_MODULEID' environment variable. Otherwise, specify IGNITION_CONFIG and specify the Module ID in this configuration page.
    • Module ID
      • The Module ID as provisioned in the Azure IoT Edge configuration. This is only used if the 'Module ID Config Option' is IGNITION_CONFIG.

    Anchor
    azureiotedgesettingsstoreandforward
    azureiotedgesettingsstoreandforward
    Azure IoT Edges Settings - Store & Forward


    Note

    From release 4.0.19, major improvements have been made to the disk-backed History Store. As a result, Message Capacity has been deprecated and History Max Age added


    Image Added

    • Store & Forward Enabled
      • Whether to enable Store & Forward capabilities for this endpoint
    • Store & Forward Type
      • The type of the Store & Forward mechanism options: In_Memory and Disk_Backed (available in release 4.0.17 and higher)
      • Data stored with an In_Memory Store & Forward will not be persisted across a module configuration change, module disable/enable, module restart or power loss. 
      • Data stored with a Disk_Backed Store & Forward will persist across a module configuration change, module disable/enable, module restart or power loss
    • Message Capacity - deprecated in 4.0.19
      • The maximum number of messages to store before dropping the oldest historical messages
    • History Max Age
      • The maximum number of minutes to store history before dropping the data
    • Flush Period
      • The period of time to wait (in milliseconds) between sending when flushing messages

    Anchor
    azureiotedgessettingsadvanced
    azureiotedgessettingsadvanced
    Azure IoT Edges Settings - AdvancedImage Added

    • Keep Alive
      • The MQTT keep alive in seconds
    • Max Message Size
      • The maximum message size in bytes that any message can be when publishing to IoT Edge. Generally, this should match the max message size allowed by IoT Edge.
    • Session expiration
      • How long in seconds to specify for token timeouts when not using certificate based authentication
    • Content Type
      • The content type to include in the topic to Azure IoT Edge
        • NONE (default) - No content type header will be included with the message
        • APPLICATION_JSON - The application/json header will be included with the message and make the body of the message available for routing if content encoding is also not 'NONE'
    • Content encoding
      • The content encoding to include in the topic to Azure IoT Edge
        • 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 
    • Azure Date/Time Format
      • The date/time for mat to use when pushing messages to IoT Edge
        • 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. 
    • Custom Topic Extension
      • The Custom Topic Extension to append to the topic string for things like Application Properties


    Anchor
    azureiotedgecertificates
    azureiotedgecertificates
    Azure IoT Edges - Certificates

    This tab provides a list of the certificate or private keys loaded and available for certificate based authentication. This should generally include the root CA for your IoT Edge, the client certification file and the client private key file.

    Note
    All certificate or private keys must be in PEM format. If using modules pre 4.0.9, any private key must also be in RSA PKCS1 format. If using modules 4.0.9 or greater, any private key must also be in either RSA PKCS1 or PKCS8 format.

    Image Added

    Clicking on the 'Create new Certificate...' will bring up the following form to add a new certificate. The Certificates tab contains only a single Main section.

    Anchor
    azureiotedgescertificatesmain
    azureiotedgescertificatesmain
    Azure IoT Edges Certificates - Main

    Image Added

    • Certificate File Upload
      • Browse to the certificate 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 Hubs

    This tab provides a list of Azure Event Hub endpoints that the module should connect to to push tag data. One or more Azure Event Hub endpoints can be configured on this tab. Image Added

    Clicking on the 'Create new Azure Event Hub ..' link will bring up the following form to add a new Azure Event Hub. The configuration sections available are Main, Store & Forward and Advanced

    Anchor
    eventhubssettingsmain
    eventhubssettingsmain
    Azure Event Hub - MainImage 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
      • This is the Azure Event Hub connection string used to connect. 
      • NOTES: Be sure to provide the connection string for the EventHub itself and not the EventHub Namespace. They both have connection strings, but the one for the EventHub will be of the form -

        Endpoint=<YOUR_ENDPOINT>;SharedAccessKeyName=<YOUR_KEYNAME>;SharedAccessKey=<YOUR_KEY>=;EntityPath=<YOUR_EVENTHUB_ENTITYPATH>

        The Namespace connection string will not contain the entity path.

    • Set
      • The Set to associate this Azure Event Hub connection with.


    Anchor
    eventhubssettingsstoreandforward
    eventhubssettingsstoreandforward
    Azure Event Hub Settings - Store & Forward


    Note

    From release 4.0.19, major improvements have been made to the disk-backed History Store. As a result, Message Capacity has been deprecated and History Max Age added


    Image Added

    • Store & Forward Enabled
      • Whether to enable Store & Forward capabilities for this endpoint
    • Store & Forward Type
      • The type of the Store & Forward mechanism options: In_Memory and Disk_Backed (available in release 4.0.17 and higher)
      • Data stored with an In_Memory Store & Forward will not be persisted across a module configuration change, module disable/enable, module restart or power loss. 
      • Data stored with a Disk_Backed Store & Forward will persist across a module configuration change, module disable/enable, module restart or power loss
    • Message Capacity - deprecated in 4.0.19
      • The maximum number of messages to store before dropping the oldest historical messages
    • History Max Age
      • The maximum number of minutes to store history before dropping the data
    • Flush Period
      • The period of time to wait (in milliseconds) between sending when flushing messages

    Anchor
    eventhubssettingsadvanced
    eventhubssettingsadvanced
    Azure Event Hub Settings - AdvancedImage Added

    • Max Message Size
      • The maximum message size for the Azure Event Hub. Default is 262144 bytes (256KB). Generally, this should match the max message size allowed by the Event Hub.
        • 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 options are UTF_8, UTF_16 and UTF_32
    • 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 Pushing Data to Azure Time Series Insights tutorial for more detail


    Anchor
    azureiotcentral
    azureiotcentral
    Azure IoT Central

    This tab provides a list of Azure IoT Central endpoints that the module should connect to to push tag data. One or more Azure IoT Central endpoints can be configured on this tab.Image Added

    Clicking on the 'Create new Azure IoT Central Setting.." link will bring up the following form to add a new Azure IoT Central. The configuration sections available are Main, Store & Forward and Advanced.

    Anchor
    iotcentralmain
    iotcentralmain
    Azure IoT Central - Main

    Image Added

    • Setting Name
      • This a friendly name of the Azure IoT Central used to easily identify it. This must also be unique.
    • Enabled
      • Whether or not this connection is enabled.
    • Scope ID
      • The Azure IoT Central Scope ID.
      • Found in the IoT Central -> Administration → Device Settings.
    • Password
      • The Azure Enrollment Group Symmetric Key.
      • Found in the IoT Central -> Security -> Permissions -> Device Connection Groups -> [SAS-IoT-Devices] -> SAS -> Primary/Second key.
    • Global Endpoint
      • The global endpoint of the IoT Central connection. Default is global.azure-devices-provisioning.net
    • Provisioned Device ID
      • The provisioned Device ID associated with this IoT Central connection.  
    • Model ID
      • The Model ID associated with this IoT Central connection.
    • Set
      • The Set associated with this IoT Central connection.


    Anchor
    iotcentralstore&forward
    iotcentralstore&forward
    Azure IoT Central - Store & Forward


    Note

    From release 4.0.19, major improvements have been made to the disk-backed History Store. As a result, Message Capacity has been deprecated and History Max Age added


    Image Added

    • Store & Forward Enabled
      • Whether to enable Store & Forward capabilities for this endpoint
    • Store & Forward Type
      • The type of the Store & Forward mechanism options: In_Memory and Disk_Backed (available in release 4.0.17 and higher)
      • Data stored with an In_Memory Store & Forward will not be persisted across a module configuration change, module disable/enable, module restart or power loss. 
      • Data stored with a Disk_Backed Store & Forward will persist across a module configuration change, module disable/enable, module restart or power loss
    • Message Capacity - deprecated in 4.0.19
      • The maximum number of messages to store before dropping the oldest historical messages
    • History Max Age
      • The maximum number of minutes to store history before dropping the data
    • Flush Period
      • The period of time to wait (in milliseconds) between sending when flushing messages

    Anchor
    iotcentraladvanced
    iotcentraladvanced
    Azure IoT Central - AdvancedImage Added

    • Max Message Size
      • The maximum message size in bytes that any message can be when pushing to IoT Central.
    • 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 Pushing Data to Azure Time Series Insights tutorial for more details


    Anchor
    sets
    sets
    Sets

    This 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. Additional Sets can be configured for situations where multiple Tag Agents will need to push to different Azure IoT Hub endpoints.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

    Anchor
    setsmain
    setsmain
    Sets - MainImage 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.


    Anchor
    tagagents
    tagagents
    Tag Agents

    Tag Agents define which tags will be picked up from the Ignition tag tree, converted to a JSON representation and pushed to one or more Azure endpoints.

    Tag Agents will monitor tags from a specific Tag Provider and, optionally, a specific Tag Path. If the tag folder hierarchy has been constructed as Group ID, Edge Node ID, and Device ID, then these will automatically be used when building up the JSON message payload which includes these in the topic.

    Tip
    Review the Cloud Injector Tag Agents and Tag Trees describing how Tag Agent configurations interact with Ignition tag trees

    If your tag folder hierarchy does not conform to this structure, you can explicitly define these required elements under the SparkPlug Settings section to be included when building the message topic.

    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

    • Name
      • A unique name for the tag agent.
    • Enabled
      • Sets whether the Tag Agent is enabled or disabled.  If disabled, the Tag Agent will not run and no data will be pushed to any configured endpoints.
    • Tag Provider Name
      • The name of the Tag provider containing the tags.
    • Tag Path
      • An optional path to the root folder where the tag tree starts.
    • 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 will only be used if 'Convert UDTs' is false  
      • Whether or not to push the UDT Definitions in the the NBIRTH messages
    • Optimize UDTs
      • This will only be 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.
    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.

    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.

    ...

      • .

    ...