Your first MQTT connection

This guide walks you through connecting to CloudSignal and sending your first message.

Prerequisites

Before starting, you need:

1. A CloudSignal account. Sign up if you haven't already.
2. An MQTT user. See Create MQTT user.
3. Your organization ID. Found in Settings → Organization.

Connection details

Option 1: Using MQTTX (recommended)

MQTTX is a free, cross-platform MQTT client with a graphical interface.

Option 2: Using the Mosquitto CLI

If you prefer the command line:

brew install mosquitto

sudo apt-get install mosquitto-clients

mosquitto_sub -h mqtt.cloudsignal.app -p 8883 \
  -u "myuser@abc123-org-id" \
  -P "your-password" \
  -t "chat/lobby/#" \
  --capath /etc/ssl/certs

mosquitto_pub -h mqtt.cloudsignal.app -p 8883 \
  -u "myuser@abc123-org-id" \
  -P "your-password" \
  -t "chat/lobby/messages" \
  -m "Hello from CLI!" \
  --capath /etc/ssl/certs

Option 3: Using code

JavaScript / Node.js

const mqtt = require('mqtt');

const client = mqtt.connect('mqtts://mqtt.cloudsignal.app:8883', {
  username: 'myuser@abc123-org-id',
  password: 'your-password',
});

client.on('connect', () => {
  console.log('Connected!');

  // Subscribe
  client.subscribe('chat/lobby/#');

  // Publish
  client.publish('chat/lobby/messages', 'Hello from Node.js!');
});

client.on('message', (topic, message) => {
  console.log(`${topic}: ${message.toString()}`);
});

Python

import paho.mqtt.client as mqtt
import ssl

def on_connect(client, userdata, flags, rc):
    print("Connected!")
    client.subscribe("chat/lobby/#")
    client.publish("chat/lobby/messages", "Hello from Python!")

def on_message(client, userdata, msg):
    print(f"{msg.topic}: {msg.payload.decode()}")

client = mqtt.Client()
client.username_pw_set("myuser@abc123-org-id", "your-password")
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.on_connect = on_connect
client.on_message = on_message

client.connect("mqtt.cloudsignal.app", 8883)
client.loop_forever()

Verify in dashboard

After connecting, you can verify in the CloudSignal dashboard:

1. Go to Sessions → Active Sessions.
2. You should see your connected client.
3. Check the client ID, username, and IP address.

Troubleshooting

"Connection refused"

• Verify you're connecting to mqtts://mqtt.cloudsignal.app:8883 (native clients) or wss://connect.cloudsignal.app:18885/ (browser clients).
• Check that TLS is enabled if using port 8883.

"Not authorized" or "Bad username or password"

• Verify the username includes @organization_id.
• Double-check the password.
• Ensure the MQTT user exists and is active.

"Connection timeout"

• Check your internet connection.
• Verify the hostname is correct.
• Try a different port.

Can't see messages

• Make sure you subscribed before publishing.
• Check that the topic patterns match.
• Verify ACL rules allow access to the topic.

Next steps

Now that you're connected:

• Set up ACL rules - Control topic access
• Explore quickstarts - Integrate with your framework
• Learn about QoS - Understand delivery guarantees