# Connect to the TilliT Broker

## Overview

MQTT works by using a subscribe/publish model. In this model, a broker acts as the one destination that all clients connect to. This article will describe how you will be able to connect to the TilliT Broker securely.

{% hint style="info" %}
MQTT communicates on port 8883. Firewalls will generally block this port by default. Contact your IT services and confirm the port is open before attempting a connection.\
\
See this for more information about firewall security - <https://help.tillit.cloud/tillit/infrastructure/firewall-security>
{% endhint %}

## MQTT Authentication

All TilliT MQTT connections are secured by a **X.509 certificate** authentication method. Create your Edge with MQTT type and download your certificates from there. See <https://help.tillit.cloud/tillit/knowledge-base/setting-up-tillit/edge/edge> for more information. Place these files in a secure location that is accessible by your MQTT client software.

You can also receive these certificates by first contacting TilliT Support. You will be issued a private key file, certificate file and root authority file that acts to authenticate and secure your connection.&#x20;

## MQTT Broker Connection

Once you have the above authentication, use the broker endpoint `iot.tillit.cloud` , `iot-us.tillit.cloud` for US tenants, to connect to the MQTT Broker on **port 8883**.&#x20;

Depending on your client. you may need to define the endpoint as `ssl://iot.tillit.cloud:8883` (see Ignition). Once connected, you will be able to do the following two things to confirm.

1\. **Subscribe** to the topic `/tenant` (replace tenant with yours)

2\. **Publish** a message to the topic you subscribed to above. You should receive the message

## Example (MQTT X)

You can get get up and running quickly with the MQTTx GUI client - <https://mqttx.app/>

Follow the following settings as an example. NOTE: ensure you have MQTT v3.1.1 selected and have the port you want (8883 or 443) is allowed through the firewall

### Port 8883

* Default port for **secure MQTT** connections (`mqtts://`).
* Uses **TLS encryption**.
* **No ALPN** required.
* Best for **IoT devices and servers**.
* May be **blocked by corporate firewalls**.
* Easiest to configure in MQTTX (just enable TLS and provide certificates if needed).

<figure><img src="https://2508759266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh0XWAsvhQAYlvQe4wbHt%2Fuploads%2FN46rDAR9dMaBBXVtcuI7%2Fimage.png?alt=media&#x26;token=47669b77-4287-4ea3-803a-7c67f5fd71df" alt=""><figcaption></figcaption></figure>

### Port 433

* Common port for **HTTPS** and **WebSocket Secure (WSS)** traffic.
* **Firewall-friendly** (usually always open).
* Can use **MQTT over WebSockets (wss\://)** or **MQTT over TLS (mqtts\://)**.
* Often requires setting an **ALPN field** (e.g., `"x-amzn-mqtt-ca"` for AWS IoT) to tell the server it’s MQTT, not HTTPS.
* Slightly **more complex setup** due to ALPN or WebSocket path requirements.
* Useful in **restricted networks** or when connecting from browsers.

<figure><img src="https://2508759266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fh0XWAsvhQAYlvQe4wbHt%2Fuploads%2FKmMYuKSARDVuSu9gNFzh%2Fimage.png?alt=media&#x26;token=a54f8bce-0d75-4b1c-b759-34ed5d7b04d4" alt=""><figcaption></figcaption></figure>

### Example (Javascript)

Copy the following contents into a file called `mqtt.js` and install the dependencies with `npm install mqtt`. Run with `node mqtt.js`.

```
Copy the following contents into a file called mqtt.js and install the dependencies with npm install mqtt. Run with node mqtt.js.
```

```javascript
const mqtt = require('mqtt')
const fs = require('fs')

//Replace the following with the correct paths and names
const privateKeyPath =  './tillitEdgeConfig/privKey.key'
const thingCertPath = './tillitEdgeConfig/thingCert.crt'
const tenant = 'bottling'


let client = mqtt.connect({
  host: 'iot.tillit.cloud',
  port: 8883,
  key: fs.readFileSync(privateKeyPath),
  cert: fs.readFileSync(thingCertPath),
  protocol: 'mqtt'
})


client.on('connect', function () {
    console.log("Connected...")
    client.subscribe(`/${tenant}`, function (err) {
        if (!err) {
            console.log("Subscribed...")
            client.publish(`/${tenant}`, JSON.stringify({message: 'Hello!!!'}))
        }else{
            console.log(err)
        }
    })
})


client.on('error', function(err) {
    console.log(err)
})


client.on('message', function (topic, message) {
    console.log("Message Received!")
    console.log(JSON.parse(message))
})
```

You should see the following output.

```javascript
Connected...
Subscribed...
Message Received!
{ message: 'Hello!!!' }
```

If you want to subscribe to anything in a level, then you can use the character `+` like so:

```
/tenant/+/assetName/endpoint - receive updates on an asset across any site
/tenant/siteName/+/endpoint - receive updates on a site across any asset
/tenant/+/+/endpoint - receive updates on any site and any asset for an endpoint
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.tillit.cloud/api/mqtt-api/connect-to-the-tillit-broker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.