# Quickstart

The following guide will show you how to publish data to GCMB using a Python program, to visualize it with a live README and subscribe to the published data using the command line.

# Create an account on gcmb.io

The first step is to create an account on gcmb.io. Go to Sign Up and create an account.

You can use your GitHub or Google account or use email and password.

You will be asked for a username:

This username will be part of your topic namespace. If your username is juhu3000, your topics will look like this: juhu3000/someproject/sometopic.

# Create Project

Let's now create a project. Click on New Project in the navigation panel.

Enter a project name, e.g. clock and optionally give a description. Let's make the project public so that everyone can see the data.

Click Create to create the project.

We now need credentials to connect via MQTT. Click on Client Apps.

And then Create Client App.

Give the client a name, e.g. myclient. Add a topic pattern, juhu3000/clock/# (replace juhu3000 with your username) and click Add new topic pattern.

Check the boxes for Publish and Subscribe and click Create.

You have created a client app that can publish and subscribe to all topics in the juhu3000/clock namespace.

# Implement Publisher in Python

Go back to the Overview of the project.

Scroll down for the code snippets. Select Python (Paho). Select the myclient client app. The code snippet below Publish data will be populated with the credentials of the client app.

Copy the snippet to the clipboard.

Create a new directory and initiate a new Python project, e.g. using uv:

mkdir clock
cd clock
uv init

Paste the code from the clipboard to a new file called main.py. It should look something like this:

import paho.mqtt.client as mqtt

broker = 'gcmb.io'
port = 8883
topic = 'juhu3000/clock/sometopic'
client_id = 'juhu3000/clock/myclient/pub'
username = 'juhu3000/clock/myclient'
password = 'xxxxxxxxxxxxxxxxxxx'


def connect_mqtt():
    def on_connect(client, userdata, flags, rc, properties):
        if rc == 0:
            print("Connected to MQTT Broker!")
            publish(client)
        else:
            print(f"Failed to connect, return code {rc}")

    client = mqtt.Client(client_id=client_id,
                         callback_api_version=mqtt.CallbackAPIVersion.VERSION2)
    client.tls_set(ca_certs='/etc/ssl/certs/ca-certificates.crt')
    client.username_pw_set(username, password)
    client.on_connect = on_connect
    client.connect_async(broker, port)
    return client


def publish(client):
    msg = 'hello world'
    status = client.publish(topic, msg)
    if status.rc == 0:
        print(f"Sent '{msg}' to topic {topic}")
    else:
        print(f"Failed to send message to topic {topic} with status {status.rc}")


def main():
    client = connect_mqtt()
    client.loop_forever(retry_first_connection=True)


if __name__ == '__main__':
    main()

This code is ready to go. Execute it, e.g. (if using uv):

uv run main.py

You should see:

Connected to MQTT Broker!
Sent 'hello world' to topic juhu3000/clock/sometopic

Go back to the browser.

When you execute the program again, you will see the message (hello world) appear in the Last message section.

Congratulations, you have published your first messages to GCMB.

Let's now update our program to publish the current time every 5 seconds. Update main.py to look like this:

import paho.mqtt.client as mqtt
import threading
from datetime import datetime, timezone

broker = 'gcmb.io'
port = 8883
topic = 'juhu3000/clock/utc'
client_id = 'juhu3000/clock/myclient/pub'
username = 'juhu3000/clock/myclient'
password = 'xxxxxxxxxxxxxxxxxxx'


def connect_mqtt():
    def on_connect(client, userdata, flags, rc, properties):
        if rc == 0:
            print("Connected to MQTT Broker!")
            start_periodic_publish(client)
        else:
            print(f"Failed to connect, return code {rc}")

    client = mqtt.Client(client_id=client_id,
                         callback_api_version=mqtt.CallbackAPIVersion.VERSION2)
    client.tls_set(ca_certs='/etc/ssl/certs/ca-certificates.crt')
    client.username_pw_set(username, password)
    client.on_connect = on_connect
    client.connect_async(broker, port)
    return client


def publish_time(client):
    utc_now = datetime.now(timezone.utc).isoformat()
    status = client.publish(topic, utc_now)
    if status.rc == 0:
        print(f"Sent UTC time '{utc_now}' to topic {topic}")
    else:
        print(f"Failed to send message to topic {topic} with status {status.rc}")


def start_periodic_publish(client):
    def publish_and_reschedule():
        publish_time(client)
        threading.Timer(5, publish_and_reschedule).start()
    publish_and_reschedule()


def main():
    client = connect_mqtt()
    client.loop_forever(retry_first_connection=True)


if __name__ == '__main__':
    main()

Let's visualize the time data in a live README.

Here is the content of the README file if you want to copy it:

## Clock

The current time is <Value topic="juhu3000/clock/utc" />.

When you reload the page, the ? will be displayed as the value initially. After a few seconds, the current time will appear as a new message is received. We want to see the current time immediately, so we add the retain=True attribute when publishing the message. Modify the publish_time function in main.py:

def publish_time(client):
    utc_now = datetime.now(timezone.utc).isoformat()
    status = client.publish(topic, utc_now, retain=True)
    # ...

Now you will see the current time immediately when you reload the page.

As the last exercise, let's subscribe to the time data using the command line. Scroll down on the topic page.

Copy the command line snippet and execute it in your terminal:

mosquitto_sub \
  -h gcmb.io \
  -p 8883 \
  -i juhu3000/clock/myclient/sub \
  -u juhu3000/clock/myclient \
  -P xxxxxxxxxxxxxxxxxxxx \
  -t juhu3000/clock/utc

Now you should see a new line with the current time every 5 seconds.

This completes the quickstart.

# Example projects

Check out these example projects for more inspiration:

Airplane data: https://github.com/stefan-hudelmaier/gcmb-airplanes (Python)
Wikipedia change stream: https://github.com/stefan-hudelmaier/wikipedia-stream (NodeJS)
Parking data: https://github.com/stefan-hudelmaier/gcmb-parken-dd (Python)

# Quickstart

# Create an account on gcmb.io

# Create Project

# Implement Publisher in Python

# Subscribe to Data using the Command Line

# Example projects