MQTT Broker Integration

Overview

Get the data of your LoRaWAN® devices from the MQTT broker of TEKTELIC KONA Core Network Server. You add an MQTT_BROKER integration to an application. KONA Core creates a broker account and topics for it, and your MQTT client subscribes to the decoded uplinks.

This guide covers MQTT_BROKER. To have KONA Core publish to your own broker instead, see MQTT Integration.

MQTT_BROKER or MQTT_V2

Both types deliver the same data over MQTT. They differ in who runs the broker and who connects to whom.

	MQTT_BROKER (this guide)	MQTT_V2
Broker	The KONA Core broker.	Your broker.
Who connects	Your MQTT client connects to the KONA Core broker.	KONA Core connects to your broker as a client.
Credentials and topics	KONA Core creates them when you save the integration. You can't change them.	You enter them in the form.
TLS	Your client connects to the MQTTS Port (TLS).	Enable TLS, with optional certificates.
Retry scheme	Not in the form. confirm how KONA Core retries an MQTT_BROKER delivery.	In the form.

We recommend MQTT_BROKER when you have no preference: you host nothing and open no inbound port. Use MQTT_V2 when you already run an MQTT broker that your applications subscribe to. Use HTTP_V2 when your system is a web service that already accepts HTTPS requests. For all integration types, see Integrations Overview.

Before you start

• Role: Customer administrator or Sub-Customer administrator. The user roles open integrations read-only. See Users, Roles & Permissions.
• Application: an application with your devices. See Manage Applications.
• Data converter: a v2 data converter for your devices. An MQTT_BROKER integration lists only v2 data converters. For TEKTELIC devices, see TEKTELIC Device Converters Library. To write one, see Write a Decoder.
• MQTT client: in your system, with TLS support and outbound internet access to the KONA Core broker. confirm which MQTT protocol versions the KONA Core broker accepts.
• Subscription plan: room for 1 more integration. See Subscription Plans & Limits.

Steps

Add the integration

1. In the side menu, select Applications.

2. In your application's row, select the Manage integrations icon. You can also select the application and then Manage integrations in its details panel. The application's integrations page opens, titled with the application name and Integrations.

3. Select Add Integration (the + icon). The Add Integration dialog opens.

4. Enter a Name. The name is required.

5. In Type, select MQTT_BROKER. The dialog shows: Credentials and topics are auto-provisioned. They will appear here after the integration is saved.

6. Select the Data converter for your devices. Only v2 data converters are listed.

7. Leave Send empty payload cleared, unless your system needs uplinks without data. It's cleared by default.

8. Leave Allow all ports selected to receive uplinks on every FPort. To receive only some ports, clear it and enter each port from 0 to 255 in Allow messages with ports.

   

9. Select Add. The integration appears in the list with the type MQTT_BROKER.

Get the connection details

1. Select the new integration in the list. The Integration details panel opens. It shows: Credentials and topics were auto-provisioned and can not be changed.

2. Copy the connection details from the panel:

   Field	What it is
   MQTT Broker Address (IP or domain name)	The host of the KONA Core broker.
   MQTT Port	The port without TLS.
   MQTTS Port (TLS)	The port with TLS.
   Username/Token	The username of the integration's broker account. It's tek-ext- followed by the integration ID.
   Password	The password of that account.
   Uplink Topic (subscribe)	The topic your client subscribes to for uplinks.
   Downlink Topic (publish)	The topic your client publishes downlinks to.

   

Use the values your integration shows. On the EU hosted service, the MQTT Port is 1885 and the MQTTS Port (TLS) is 8885. confirm the broker ports on the NA hosted service and on on-premises installations.

warning

The details panel shows the Password in plain text. Don't share screenshots of the panel. Store the password in your system's secret store, not in code or shared files.

Topics

The topics contain the integration ID, so each integration has its own topics:

Topic	Pattern	Your client
Uplink Topic (subscribe)	integrations/v1/<integration-id>/${deviceEui}/uplink	Subscribes
Downlink Topic (publish)	integrations/v1/<integration-id>/downlink	Publishes

KONA Core publishes each uplink on a topic with the DevEUI of its device in place of ${deviceEui}. To get the uplinks of all devices in the application, subscribe with the MQTT wildcard + in place of ${deviceEui}. To get one device only, subscribe with its DevEUI. confirm the DevEUI format in the topic, such as uppercase or lowercase hex.

Connect your client

1. In your MQTT client, set the host to the MQTT Broker Address (IP or domain name).
2. Set the port to the MQTTS Port (TLS), and enable TLS. We recommend TLS: without it, the password and the device data cross the internet unencrypted. Use the MQTT Port only for a test on a trusted network. confirm which CA signs the certificate of the KONA Core broker, and whether clients need a CA file.
3. Set the username to the Username/Token and the password to the Password.
4. Set a client ID that is unique among your clients. Most brokers disconnect a client when another client connects with the same ID. confirm whether the KONA Core broker restricts the client ID.
5. Subscribe to the Uplink Topic (subscribe), with + in place of ${deviceEui}.

For example, with the Eclipse Mosquitto client mosquitto_sub, run this on a computer with internet access. Replace each <…> with the value from the details panel:

mosquitto_sub -h <broker-address> -p <mqtts-port> \
  --capath /etc/ssl/certs \
  -u <username> -P <password> \
  -i <client-id> \
  -t 'integrations/v1/<integration-id>/+/uplink' -v

The client prints each message with its topic. It prints nothing until a device sends an uplink.

Check the result

1. Wait for the next uplink of a device in the application. Your client receives a message on the Uplink Topic (subscribe), with the device's DevEUI in the topic.
2. Check the message body. It's a JSON object with the device metadata and the values your data converter returns. See Message Formats.
3. In KONA Core, select the integration in the list, then select Show UL delivery statistics. It counts the uplinks the integration delivered.

For the statistics in detail, see Integration Monitoring.

Send a downlink

To send a downlink, publish a message to the Downlink Topic (publish). The data converter's encoder turns your data into bytes. Use the V2 envelope with deviceEui, confirmed, msgId and an encoder-defined data object. See Message Formats and Write an Encoder.

Select Show DL statistics to see the downlinks the integration received. The downlink then waits in the device's downlink queue until the device's next receive window. See Uplink & Downlink Data Flow.

Troubleshooting

Symptom	Likely cause	What to do
Your client can't connect.	A wrong port or TLS setting, or a firewall that blocks outbound connections to the broker port.	Use the MQTTS Port (TLS) with TLS enabled, or the MQTT Port without TLS. Check that your network allows outbound connections to that port.
The broker refuses the sign-in.	The username or password doesn't match the integration, or you copied it from another integration.	Copy the Username/Token and Password again from the details panel of this integration. They can't be changed, so a new integration has other credentials.
Your client connects but receives nothing.	The topic is wrong, no device has sent an uplink yet, or the integration's filters drop the uplinks.	Copy the Uplink Topic (subscribe) and replace only ${deviceEui} with +. Check the device's Real-time packets tab for uplinks. Check Allow messages with ports and Send empty payload. Look for the event INTEGRATION_UL_DECODING_FAILURE.

Still stuck? A Sub-Customer contacts their Customer, a Customer contacts their Provider, and a Provider contacts TEKTELIC Support. Send the integration name, the DevEUI of a device, the time in UTC and the exact error message of your client. Add a screenshot of the integration details, with the password hidden.

Related

• MQTT Integration
• Message Formats
• Integrations Overview
• Integration Monitoring
• HTTP Integration
• Payload Converters Overview
• Write an Encoder
• Uplink & Downlink Data Flow
• Glossary
• API Reference: Save integration, Get integration by ID.