Connect Splunk Edge Hub OS to external sensors using the MQTT protocol

You can connect your Splunk Edge Hub to external sensors or IIoT gateways that support the Message Queuing Telemetry Transport (MQTT) protocol.

Splunk Edge Hub OS has an MQTT broker that facilitates MQTT communication protocol. It uses the MQTT protocol to connect to an IIoT gateway or a sensor. In the following example, the IIoT gateway connects Splunk Edge Hub OS to external sensors using a protocol native to the sensor producer.

The following diagram shows how Splunk Edge Hub OS connects to an external sensor:

This IO-Link VVB Starter Kit is an example to show you how to connect your Splunk Edge Hub OS to the IO-Link Vibration Sensor VVB001 using the IO-Link Master Dataline AL1350. You can also integrate your Splunk Edge Hub OS with other external sensors or IIoT gateways that use the MQTT protocol.

To learn more about the IFM Efector VVB Starter Kit and the IO-Link master, see https://www.ifm.com/ca/en/product/ZZ0809?tab=details in the IFM documentation.

Splunk has tested and verified integrating the IFM Vibration Sensor VVB001 with the Splunk Edge Hub OS. Splunk Edge Hub OS should is also compatible with other external sensors that support IIoT gateways and use the MQTT protocol.

Requirements and prerequisites

The following are requirements and prerequisites for connecting your Splunk Edge Hub to the IFM VVB001 Vibration Sensor.

Requirements

Integrating the Splunk Edge Hub with IFM Efector VVB Starter Kit sensor requires the following:

• A Splunk Edge Hub.
• Splunk Edge Hub OS version 0.10.0 or higher. Tap the settings icon to learn what software version your Splunk Edge Hub is on.
• The IFM Efector VVB Starter Kit that contains the IFM VVB001 Vibration Sensor https://www.ifm.com/ca/en/product/ZZ0809?tab=details

Prerequisites

Before integrating the external sensor, register your Splunk Edge Hub device, launch the Edge Hub Advanced Settings page, and enable the MQTT broker.

1. Register your Splunk Edge Hub. See Register or unregister your Splunk Edge Hub
2. Complete the steps at Access the Edge Hub Advanced Settings page.
3. In the Edge Hub Advanced Settings page, select MQTT then Enable External MQTT Broker.

Set up the the IO-Link Master

1. Assemble the kit according to the IFM documentation provided at https://www.ifm.com/ca/en/product/ZZ0809?tab=documents
2. Plug the RJ-45 ethernet port into a switch or router that is in the same network as the Splunk Edge Hub device.
3. Note the IP address of your IO-Link Master from the documentation.
4. Download the latest version of firmware for your IO-Link Master. You can find the latest version in the IO-Link Master documentation.
5. Unzip the firmware file and follow the instructions to update the firmware.
6. On a desktop computer able to access the IO-Link Master IP address, navigate to http://<ip-address>/web/subscribe in a browser.

Next, configure the Splunk Edge Hub OS subscription to the MQTT topic.

Configure the Splunk Edge Hub OS subscription to the MQTT topic

An MQTT topic filters messages for the connected client. Use the documentation at https://www.ifm.com/ca/en/product/AL1350?tab=documents to complete the following steps.

At http://<ip-address>/web/subscribe, complete the following steps to subscribe the MQTT broker in the Splunk Edge Hub OS to the MQTT topic.

1. Configure the event.
2. Configure the data.
3. Transfer information.

Configure the event

1. Select the Notification tab.
2. Select the + icon.
3. In the Events field, enter counter.
4. Select Search For.
5. Select the "counter" event. Refer to the IFM documentation to determine which counter event to select.
6. Select Next >.

Configure the data

1. In the Data field, enter pdin.
2. Select Search For.
3. Select the "pdin" event. Refer to the IFM documentation to determine which pdin event to select.

Transfer information

1. Enter the following values for the fields on this page:

   Field	Description	Value
   cid	Consumer ID related to the request.	Enter a unique consumer ID, such as 123.
   protocol	Protocol for this configuration	Select mqtt.
   frequency	How frequently the device sends data	Select lifetime to continuously send data.
   port	The Splunk Edge Hub OS port enabled for MQTT external integrations. It accepts unencrypted and unauthenticated requests.	Enter 1883
   topic	Take note of this topic for a later step during the Splunk Edge Hub OS setup process.	Add external/al1350/vibration

2. After entering the values, select Finish.
3. Select the Parameter tab.
4. Select the Timer[1] tab.
5. In the interval field, enter 100ms.
6. Select the pencil icon to save the configuration.

Configure Splunk Edge Hub OS

Configure topic and metric rules to set up your Splunk Edge Hub OS to integrate with the sensor.

A topic rule enables the MQTT broker in Splunk Edge Hub OS to process incoming messages and transform the fields so that Splunk software can ingest the data.

For each metric you want to send to your Splunk platform instance, you must define a metric rule. The IO-Link Master provides 6 metrics: fatigue, impact, friction, temperature, crest and device status. In this example, you configure 4 of these metrics. To learn more about these metrics, see the IO-Link Interface Description for the VVB001 sensor at https://www.ifm.com/download/files/ifm-000557-20201127-IODD11-en/$file/ifm-000557-20201127-IODD11-en.pdf in the IFM documentation.

Follow these steps to configur Splunk Edge Hub OS:

1. Configure topic rules
2. Create metric rules

Configuring topic rules

In the Advanced Configuration server, configure the topic rules:

1. Select the MQTT tab.
2. Select the Create button to create topic rules.
3. Enter the following values to configure the topic rules:

   Field	Description	Value
   Topic Name	Messages that use this rule will be published to this topic name in the Splunk Edge Hub OS External MQTT Broker. The topic name should match the MQTT notification settings applied to your IFM AL1350 IO-Link Master. You can use the single-level wildcard + to allow any topic that contains an arbitrary string in place of the wildcard to match the MQTT notification settings.	Enter external/al1350/vibration. If you're not using a wildcard, enter external/al1350/vibration. If you're using a wildcard, enter external/+/vibration.
   Sensor Type	Used to describe the sensor_type dimension added to the generated Splunk metric. This value is metadata that you can use to filter your searches in Splunk software.	Use a meaningful value to identify this particular sensor in a way that you can identify metrics coming from it in Splunk web.
   (Optional) Description	This field is available to document any notes you may find relevant but are not supported by other fields.	Optional field.

Create metric rules

Refer to the IFM documentation at https://www.ifm.com/ca/en/product/AL1350?tab=documents to complete these steps. In the Edge Hub Advanced Settings page, provide the following fields for each metric:

1. Configure Name, the thing you are measuring. For example, acceleration. Names must only include uppercase letters, lowercase letters, numbers, and underscore ( _ ), period ( . ) characters. Names use the period character to separate their namespaces into segments. The period character enables the creation of metric hierarchies, such as asspl.mlog.per_index_thruput.ev.
2. Configure Unit, the unit of the thing you are measuring. For example, if you are measuring acceleration, the unit is m/s^2.
3. Select Refresh to get the JSON message sample generated by the MQTT configuration.
4. Configure Value. In the JSON message, locate the value of the metrics you configured. Refer to the IFM documentation to learn how to identify the metric value in the JSON message. The following is an example of a JSON message generated by the configuration:

   {
     "data": {
       "payload": {
         "/iolinkmaster/port[1]/iolinkdevice/pdin": {
           "data": "0000FC000001FF000000FF000162FF000032FF03" 
         } 
       } 
     }
   }
   
   

   In this example, 0000FC000001FF000000FF000162FF000032FF03 is the value of six different metrics as stated by the IO-Link master documentation.




5. Enter the expression for the value that you're looking for to parse the JSON message. See the following section, "Expressions for the IO-Link sensor metrics" that provides the expressions for the IO-Link sensor metrics.
6. Select Save after configuring each metric rule. The configured rules apply to each message published to the topic.
   The messages from all topics that match the wildcard will be presented for validation. You can save the rule only if the JSONata produces accurate results in all sample messages from the matching topics.
   

Expressions for the IO-Link sensor metrics

The following tables provide the expressions for the IO-Link sensor metrics required in step 5:

Use the following fields for the fatigue metric:

Field	Entry
name	fatigue_vrms
unit	m/s
value	$parseInteger($string('0x'&$substring(data.payload.'/iolinkmaster/port[1]/iolinkdevice/pdin'.data, 0, 4)),'0') * 0.1
timestamp	Select Edit Timestamp Rule and check Set timestamp when message is processed to make sure the message carries the timestamp required for the metric. Or you can write a JSONata expression to extract the timestamp from the published JSON message. To learn more about how to write a JSONata expression, see the documentation at https://docs.jsonata.org/date-time-functions.

Use the following fields for the impact metric:

Field	Entry
name	impact_apeak
unit	m/s^2
value	$parseInteger($string('0x'&$substring(data.payload.'/iolinkmaster/port[1]/iolinkdevice/pdin'.data, 8, 4)),'0') * 0.1
timestamp	Select Edit Timestamp Rule and check Set timestamp when message is processed to make sure the message carries the timestamp required for the metric. Or you can write a JSONata expression to extract the timestamp from the published JSON message. To learn more about how to write a JSONata expression, see the documentation at https://docs.jsonata.org/date-time-functions.

Use the following fields for the friction metric:

Field	Entry
name	crest
unit	peakRatio
value	$parseInteger($string('0x'&$substring(data.payload.'/iolinkmaster/port[1]/iolinkdevice/pdin'.data, 32, 4)),'0') * 0.1
timestamp	Select Edit Timestamp Rule and check Set timestamp when message is processed to make sure the message carries the timestamp required for the metric. Or you can write a JSONata expression to extract the timestamp from the published JSON message. To learn more about how to write a JSONata expression, see the documentation at https://docs.jsonata.org/date-time-functions.

If you have a different message from this format, you can write your own JSONata expression to parse the JSON message. To learn more about how to write a JSONata expression, see the JSONata documentation at https://jsonata.org/ to learn more.

Send external MQTT sensor data as events

In Splunk Edge Hub OS version 2.0 and higher, you can send external MQTT data as events without converting it to metrics first.

In Splunk Edge Hub OS version 2.1 and higher, all events sent to the external MQTT broker are encapsulated in a payload entry. For example:

{   
    "puck_name": "SplunkEdgeHub", 
    "puck_model": "SPLKEH201GL", 
    "uuid": "uuid", 
    "serial": "serial_number", 
    "version": "2.1.0", 
    "topic": "your_topic", 
    "payload": {
        "value": 0.5,
        "message": "random_message"
    }
}

The MQTT message must be in JSON format before sending the data as events.

Consider the following limitations:

1. The Splunk Edge Hub does not display a data panel for the events.
2. You cannot apply transformations to the event data.

Steps

1. In Splunk Web, create an events index. See Create events indexes in the Splunk Enterprise Managing Indexers and Clusters of Indexers manual.
2. Select the events index for the HEC token that the Splunk App for Edge Hub is using. See Modify an Event Collector token on Splunk Enterprise in the Splunk Enterprise Getting Data In manual.
3. Navigate to the MQTT tab in the Edge Hub Advanced Settings page.
4. Select Create.
5. Select the Events tab and complete the following fields:
   1. Topic name: The topic that your MQTT publisher is publishing to
   2. Index: The name of the events index that you created in step 1
   3. (Optional) Description for the topic rule
6. Select Save.

To view the event data, search for the index in the Search and Reporting app with the following search:

index="<your_index>".

The data populates depending on the sample rate of your MQTT publisher.

Confirm your Splunk platform is receiving external sensor data

There are several ways you can check if your Splunk platform is receiving external sensor data. See View Splunk Edge Hub data to learn how to view your data.

Search for the data

You can search for the data with a Search Processing Language (SPL) search. For example, use the following search to look for fatigue metrics:

| mstats avg(_value) as avg_v where index=*-data* AND metric_name=* AND extracted_host="splunkedgehub-test" span=1s by metric_name | fields metric_name extracted_host _time avg_v | sort 0 - _time | search metric_name="fatigue_vrms" | rename avg_v as value | table value | head 1

Create a dashboard

You can create your own dashboard or perform your own searches when using different metrics outside of this example.

Configure username and password authentication

Optionally, you can set up username and password authentication for the external MQTT broker.

1. In the Splunk Edge Hub advanced settings, navigate to the MQTT tab.
2. Enter a username and password for the external MQTT broker. To allow anonymous access, leave both fields blank.
3. Select Save.

Configure TLS

Optionally, you can configure your MQTT external broker to use Transport Layer Security (TLS). In the MQTT tab of the Splunk Edge Hub advanced settings page, upload your private and public keys.

Download your MQTT configuration and upload it to another Splunk Edge Hub device

After completing a MQTT configuration for external sensors, you can download a configuration file to use it with other Splunk Edge Hub devices. Update the configuration file to replace values that are applicable to other Splunk Edge Hub devices, such as time stamp, dimension, or metric rules.

Downloading and uploading a configuration file means you don't have to repeat the configuration steps again for multiple Splunk Edge Hub devices.

See Download a configuration file and upload it to another Splunk Edge Hub device to download and upload a configuration file to other Splunk Edge Hub devices.

Troubleshooting

If you're not seeing data after proper configuration or if you want to connect a different sensor or gateway that uses MQTT protocol sensor, contact edgesupport@splunk.com.