Versions Compared

Old Version 16

changes.mady.by.user Nathan Davenport

Saved on

compared with

New Version Current

changes.mady.by.user Wes Johnson

Saved on

Key

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

...

The first tab contains the general settings for the Azure Injector module.

Image Modified

The general configurations options available on this tab are listed below:

...

The next tab is the list of Azure IoT Hub endpoints that the module should connect to to push tag data.

Image RemovedImage Added

One or more Azure IoT Hub endpoints can be configured on this tab. The configuration options for an Azure IoT Hub connection are listed below.

...

  • 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 pushing to this IoT Hub is enabled or notthis 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.
  • Set
    • The Set to associate this Azure IoT Hub connection with.

Authentication

  • 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 (next section), this is the connection string format that must be used.
  • 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 (previous section) must be a 'device' connection string.
      • Others may be available in the future
  • Set
    • The Set to associate this Azure IoT Hub connection with.
  • 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
    Certificates
    • The server certificates to use if required.

Store & Forward

  • 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

Advanced

  • Keep Alive
    • The MQTT keep alive timeout in seconds
  • Max Message Size
    • The maximum message size before outbound messages will be divided into chunks smaller than the max message sizein 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

    • 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 applicaton/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 this 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 this 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 tutorial for more details
    Session Expiration
    • The number of seconds before the session token expires and is renewed


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 Added

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 AddedImage 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 Modified

One or more Azure Event Hub endpoints can be configured on this tab.

...

  • 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 pushing to this Event Hub is enabled or not.
  • Password/Connection String
    • This is the Azure Event Azure Event Hub connection string used to connect.  This string can be one of the following:
      • An Event Hub connection string with the following format:
        • HostName=<Host Name>;SharedAccessKeyName=<Key Name>;SharedAccessKey=<SAS Key>
      • An Event Hub's Event Hub-compatible connection string with the following format:
        • Endpoint=<ENDPOINT>;SharedAccessKeyName=<Key Name>;SharedAccessKey=<KEYVALUE>
      • An Event Hub device connection string with the following format:
        • HostName=<Host Name>;DeviceId=<Device Name>;SharedAccessKey=<Device Key>
       
    • 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 IoT Hub connection with.
    Certificates
    • 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

...

  • Max Message Size
    • The maximum message size before outbound messages will be divided into chunks smaller than the max message size
  • 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 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 Modified

Sets

The Sets tab contains a list of Azure Sets.  Each set represents a grouping of Azure IoT Hub endpoints.  When a set is referenced by a Tag Agent the Agent will push Tag data to all Azure IoT Hub endpoints contained within that Set. The Sets are disjoint, meaning that a single Azure IoT Hub endpoint cannot be in more than one set.  Out of the box the Azure Injector module will have one "Default" set defined.

Image RemovedImage Added

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.

...

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

Image RemovedImage AddedTag 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 Modified

Tag Agents are configured to point to a single folder.  All Tags within that folder will be monitored by the Tag Agent. 

...