1. Log in to the Kuika platform and open the project you’ll be working on from the Apps screen.
2. Open the Datasources module from the top menu. Here, you can view your existing data sources and actions under the Recently modified and Data sources tabs, search using the Search by name field, or add a new data source.
3. Click the Create an API card at the top of the screen. This card allows you to create Swagger, REST, OData, SAP, and MQTT broker connections.
4. In the list that opens, select the MQTT (Message Queuing Protocol) option under the Communication heading. You can use the ↑/↓ keys to navigate the list and the Enter key to make a selection.

5. Enter a name for your data source in the Name field (e.g., userguidemqtt). The CREATE button remains disabled until a name is entered.
6. Click the CREATE button to complete the process. To cancel the operation, click the CANCEL button; to return to the connection type selection, use the < MQTT link.

Note: You can also start the process of adding a new data source by clicking the + icon next to the Sources heading in the left panel.

After these steps, the MQTT connection settings screen opens. If you do not have an MQTT broker yet, you can follow the HiveMQ Cloud steps below before entering your connection information.

HiveMQ Cloud is an IoT platform that supports the MQTT protocol. You can create an MQTT broker and connect your devices using the HiveMQ Console.

Creating a HiveMQ Cloud Account

1. Go to the HiveMQ Cloud Console.
2. If you don’t have an account, click the Sign Up button to register.
3. If you have an account, click the Login button to sign in.

Creating a New Cluster

1. Go to the Clusters section and click the Create Cluster option.
2. Specify a name for the cluster (e.g., “MyFirstCluster”).
3. Select the cluster’s location (e.g., ‘Europe’ or “North America”).
4. Select one of the free or paid plans.
5. Click the CREATE button to create the cluster.

Connecting via the Web Client

1. Click the Web Client tab in the left menu.
2. On the screen that opens, enter the connection details:
   
   • Host: The connection URL provided when you created the cluster (usually in the format *.hivemq.cloud).
   • Port: 1883 (unsecured) or 8883 (SSL).
   • Client ID: Specify a random ID.
   • Username & Password: The credentials you created in the HiveMQ Console.
3. Click the Connect button.

After completing these steps, you can send (publish) messages or listen for (subscribe to) messages on a specific topic.

Topic

In MQTT, a topic enables the filtering of messages. A hierarchical structure separated by slashes (/) is used.

Examples:

• home/living_room/temperature → Living room temperature data.
• vehicles/car/speed → Vehicle speed data.

Quality of Service (QoS)

In MQTT, the QoS level determines the reliability of message delivery.

• QoS 0 (At Most Once): Messages are sent without waiting for acknowledgment. This can be used if data loss is tolerable.
• QoS 1 (At Least Once): Messages are delivered at least once but may be repeated.
• QoS 2 (Exactly Once): This is the most reliable level; the message is delivered only once.

Retain

The Retain feature ensures that messages are stored on the broker and forwarded to newly connected clients.

Example: If a temperature value is sent with Retain, all clients newly connecting to this topic can see that value.

To clear a Retain message, an empty message with `retain true` must be sent.

After creating the MQTT data source, enter the connection details on the screen that appears. At the top of the screen, you’ll find the back button (←), the data source name (pencil icon to edit the name), and the CREATE button to save the settings.

01 Broker

Contains the broker information Kuika will connect to.

• Protocol (required): The connection protocol. WebSocket is selected by default.
• Host: The MQTT broker address (e.g., mqtt.example.com).
• Port (required): The broker’s connection port (e.g., 1883 for unsecured, 8883 for secure/TLS-supported).
• Base path: Required for WebSocket connections (e.g., /mqtt).

02 Credentials

These are the authentication credentials sent to the broker during connection.

• Username: MQTT server username.
• Password: MQTT server password. You can show or hide the password using the eye icon.

03 Transport Security

These are the security settings applied to the connection address defined in the Broker section.

• Use TLS: Enhances security by encrypting the connection.
• Validate certificate: Verifies the connection’s TLS certificate. When disabled, self-signed certificates are also accepted.

Testing and Saving the Connection

1. Click the Test connection button in the Connection section on the right to test the connection.
2. If the connection is successful, click the CREATE button in the upper-right corner.

The CREATE button saves the connection and automatically adds the Publish and Subscribe actions associated with this data source. You can use these actions in your application in later steps.

With the Subscribe action, you can automatically subscribe to a specific topic.

1. Go to the UI Design module.
2. Click the ADD ACTION button in the Properties panel on the right.
3. Add the Subscribe action.
4. Example topic: “kuika/test”

The user can view messages sent to the specified topic. You can also add additional actions:

• Use the Notify action to display incoming messages as notifications.
• Add the Set Value Of action to display messages in a text input field.

1. Add a Button from the Elements section in the left panel.
2. Connect the Publish action to this button.
3. Specify the relevant topic to send a message.
4. Example topic: “user/guide”

All users subscribed to this topic will receive the message.

This tutorial will help you quickly set up an MQTT connection, exchange messages, and integrate your applications with MQTT on the Kuika platform.