HubIQ to External Apps¶

Use MQTT to export sensor process values from SITRANS hub IQ to external applications through a customer-managed MQTT broker. Create an export target, define its payload format, and assign sensors to it. Creating a target alone does not start exporting every device's data.

For gateway-to-hub IQ ingestion, see Gateway to HubIQ. The two connections use separate brokers, settings, and credentials.

Prerequisites¶

• An active Pro Connect subscription that enables MQTT data export and covers the devices you want to export.
• Permission to configure data export targets and device export settings in your company's hub IQ environment.
• A customer-managed MQTT broker reachable from hub IQ over TLS. Unencrypted MQTT connections are not supported.
• Broker credentials and certificates supplied by your broker administrator. hub IQ does not issue these for customer brokers.
• Onboarded sensors that are sending process values to hub IQ.
• A subscriber with permission to read the destination topic, for end-to-end verification.

Step 1: Create an MQTT Target¶

1. Open Settings > Data export settings > Applications (MQTT). Some interface versions label the entry Applications (MQTT-Paid).
2. Select Add to open Add Application (MQTT).
3. Enter an Application name, for example Demo MQTT Target.
4. Choose the authentication method and supply the corresponding broker credentials.

The CA certificate allows hub IQ to verify the customer broker. For certificate authentication, the client certificate and private key identify hub IQ to that broker. Both methods require a secure connection; username/password authentication does not enable unencrypted MQTT.

Do not upload the gateway connection package from the gateway onboarding workflow. Use certificates and credentials issued for your customer broker, and keep private keys and passwords out of shared examples.

Step 2: Configure and Test the Broker Connection¶

Complete the MQTT broker section of the dialog:

1. Select Test Connection.
2. If the test fails, correct the broker settings, network access, credentials, or certificates and test again.
3. After the test succeeds, select Next to open the payload mapper. A successful test is required to proceed.

Do not reuse a client ID already used by another active connection to your broker. The connection test checks broker connectivity, not sensor assignments or measurement delivery.

Step 3: Define the Export Payload¶

Payload mapping determines the JSON structure sent to the broker. It is configured per target and sensor type, so the same sensor type can use different formats for different targets. Device-to-target assignment, configured later, determines which sensors export data.

The mapping screen contains a Variables panel and a Builder panel. Sensor types listed in the mapper depend on the devices onboarded in your company.

If the receiving application accepts the standard hub IQ canonical payload, leave the custom mapping empty. Otherwise:

1. Expand the relevant sensor type in Variables.
2. Add the required attributes to the Builder using their drag handles.
3. Expand a measurement, such as Humidity, and add its value and unit attributes.
4. Rename output fields to match the receiving application's contract.
5. Use field, Object, or array blocks to arrange the output as needed. For example, place gatewayId and tenantId inside a meta object.
6. Repeat for each sensor type that will export through this target.

Example Custom Payload¶

The following illustrates a custom mapping. The values are examples, not live readings or the default canonical schema.

{
  "serialNumber": "SN-EXAMPLE-001",
  "deviceType": "EXAMPLE-SENSOR",
  "firmwareVersion": "1.0.0",
  "timestamp": "2026-11-04T08:00:00.000Z",
  "humidityValue": 45,
  "humidityUnit": "percent",
  "temperatureValue": 22,
  "temperatureUnit": "celsius",
  "meta": {
    "gatewayId": "GATEWAY-EXAMPLE-001",
    "tenantId": "TENANT-EXAMPLE-001"
  }
}

Review and Save¶

1. Enable Schema preview.
2. Check the Output shape for field names, nesting, and selected attributes.
3. Disable the preview to make corrections in the builder.
4. Select Save to save the target and payload configuration.
5. Return to Settings > Applications (MQTT) and confirm that your application appears in the list.

The preview uses example values. It does not confirm that a sensor has published data.

Use the application name you saved when locating your target; the screenshot contains demonstration names.

Step 4: Assign Sensors to the Target¶

Assign or Remove a Target for One Sensor¶

1. Open the Device list and select a sensor to open its details.
2. Open Data export > Applications (MQTT).
3. Select the checkbox beside each target to assign, or clear a checkbox to remove an existing assignment.
4. Select Save changes.
5. Reopen the sensor's export settings and confirm that the selected targets were saved.

Checked targets are assigned to that sensor; unchecked targets are not. The screenshot shows the controls before selection, with unrelated identifying target names masked. Removing an assignment stops export from that sensor to that target. It does not delete the target or change other sensors' assignments.

Assign Targets to Multiple Sensors¶

1. Open the Device list and filter it to find the required sensors.
2. Select the sensors' checkboxes.
3. Select Setup process data export in the toolbar to open Setup data export.
4. Open Applications (MQTT) and select the target or targets to add.
5. Select Export to apply the assignments.
6. Open an individual sensor's Data export settings to verify the result.

Bulk assignment adds targets to existing assignments. It does not replace them. The bulk dialog does not display each sensor's current assignments, so an unchecked target does not mean that it is unassigned from every selected sensor. To remove an assignment, use the individual sensor's export settings.

If hub IQ reports that the subscription's device allowance is exceeded, review your Pro Connect package and the devices already covered before retrying. Follow the selection limits shown by your current interface when assigning devices in bulk.

Step 5: Verify End-to-End Delivery¶

1. Connect a subscriber to your customer broker with credentials permitted to read the destination topic.
2. Subscribe to the exact topic configured in the target.
3. Wait for a new process value from an assigned sensor.
4. Confirm that a message arrives and that its JSON matches the configured mapping or the canonical payload if no custom mapping was defined.
5. Check the sensor identifier and timestamp to confirm that the message belongs to the expected device and measurement.

A successful broker connection test alone does not verify end-to-end delivery.

Manage MQTT Targets¶

In Settings > Applications (MQTT), use the actions beside the target:

After changing connection settings, test the connection again. Select Next to review the payload mappings, check Schema preview, and select Save. Verify delivery from an assigned sensor after saving changes.

Troubleshooting¶