> For the complete documentation index, see [llms.txt](https://docs.kpnthings.com/kpn-things/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kpnthings.com/kpn-things/building-blocks/destinations/mqtt-broker.md).
# MQTT broker
{% hint style="warning" %}
It is only possible to connect KPN Things to your MQTT broker using an **encrypted connection**!
{% endhint %}
## Connect an MQTT broker
The following parameters are available to connect an MQTT broker:
| Parameter | | Description | Example value |
| ------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `name` | \* | The name of the destination | *My Server* |
| `description` | | Description of the destination | *Endpoint of my server* |
| `destinationFormat` | \* | Specify the data format used for outgoing payloads. By default, SenML is selected, meaning data is forwarded in the KPN Things's native format. To transform the payload and routing metadata into a custom structure before delivery, select one of your pre-configured [Destination Formats](/kpn-things/the-portal-explained/things-creator/destination-formats.md) from the list. | *SenML* |
| `host` | \* | The host name of the MQTT broker | *broker.hivemq.com* |
| `port` | \* | The port on which the MQTT broker allows encrypted connections | *8883* |
| `username` | \*† | The username for KPN Things to connect to the broker | your-username |
| `password` | \*† | The password for KPN Things to connect to the broker | your-password |
| `applicationId` | \* | MQTT Client ID for KPN Things to connect to the broker | *kpnthings* |
| `topic` | \* | The topic structure describing how KPN Things should publish data. There are several [variables](#variables) available | *things/%p/%d/%n* |
| `qosLevel` | \* |
The MQTT Quality of Service desired for the connection to your broker.
Options:
AT\_MOST\_ONCE
AT\_LEAST\_ONCE
EXACTLY\_ONCE
| *AT\_LEAST\_ONCE* |
| `messageTimeout` | \* | Timeout for sending a message and handling QoS in milliseconds | *10000* |
| `retainMessage` | \* | Whether messages send to the broker should be [retained messages](https://www.hivemq.com/blog/mqtt-essentials-part-8-retained-messages/). | *false* |
*\*) required value*\
*†) secret value, can only be written*
## Variables
## What does the connection do?
* Open an encrypted client connection to your MQTT broker.
* Publish all forwarded IoT data in [SenML](/kpn-things/building-blocks/data-processing/thingsml-and-senml/senml.md) JSON format on topics following the specified topic template.
## Trusted TLS/SSL certificates
We do not support self-signed certificates. Your TLS/SSL certificate should be signed by a root certificate authority (CA) that is trusted by the default Java trust store. You can use the [SSL Server Test from Qualys](https://www.ssllabs.com/ssltest/index.html) to check if your certificate is trusted by the Java trust store:
he result of the SSL Server Test indicating the certificate is trusted by Java
Your server should preferably use TLSv1.2 or higher, but at least TLSv1.1. Older protocols are not supported because they are not considered safe.
## Learn about MQTT
Are you new to MQTT, but still interested in using it? HiveMQ has published some very nice articles about MQTT essentials:
{% embed url="" %}
## Test with a demo broker
For testing purposes, you can use the public MQTT broker available at . When connecting to this broker, make sure to use **port 8883**. Although the broker supports anonymous access, you may enter any username and password in Things to establish the connection.
Keep in mind that this is an open, publicly accessible MQTT broker. **It is not suitable for production use.**
{% embed url="" %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.kpnthings.com/kpn-things/building-blocks/destinations/mqtt-broker.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
