Getting Started with HiveMQ Cloud

HiveMQ Cloud is part of the HiveMQ Platform, an MQTT-based industrial AI platform.

HiveMQ Cloud deployments do not yet support Data Intelligence in the HiveMQ Platform. This means the Contextualize and Analyze capabilities are currently unavailable for Cloud-deployed brokers.

This quick start guide shows you how to complete the following tasks:

  • Create a free HiveMQ account.

  • Start a 15-day free trial of the HiveMQ Cloud Starter plan.

  • Configure client access to your HiveMQ Cloud broker.

  • Test your broker with MQTT clients.

More ways to get started:

Sign Up and Log In to HiveMQ

To get started with HiveMQ Cloud, navigate to app.hivemq.com.

HiveMQ Homepage

  1. The first time you use HiveMQ, you are asked to select a login method and sign up. You can use your GitHub, Google, or LinkedIn account, or your email address:

    • Email: HiveMQ sends a verification code to your email address. Enter the code and click Verify email. If you do not receive the code, click Resend code. Then set a secure password and click Create account.

    • GitHub, Google, or LinkedIn: The provider supplies your login data.

  2. To complete your sign-up, enter basic contact details for your user profile and click Continue:

    HiveMQ Profile

    Your account opens in the HiveMQ Platform at app.hivemq.com.
    For future visits, log in directly with the method you selected.

    HiveMQ automatically creates a HiveMQ organization when you create a HiveMQ account. The account creator becomes the organization owner and receives administrative rights. HiveMQ organizations enable users to collaborate on HiveMQ brokers across HiveMQ accounts. To learn more, see HiveMQ Organizations.

Select Your HiveMQ Cloud Plan

After you complete your sign-up, a page with information about the different plans HiveMQ Cloud offers opens:

Select HiveMQ Cloud Plan

  • HiveMQ Cloud Enterprise: Production-grade MQTT for large-scale, mission-critical IoT. For more information on HiveMQ Cloud Enterprise, contact our sales team.

  • HiveMQ Cloud Starter: Complete MQTT platform for testing and small-scale production.

This guide uses the 15-day free trial of the HiveMQ Cloud Starter plan.

  1. On the Select your Cloud Plan page, select Starter, then click Continue:

  2. A form opens to configure your HiveMQ Cloud starter plan trial:

    • Name your broker: You can keep the automatically generated broker name or enter a name of your choice. The broker name must be unique within your account. Use lowercase letters, numbers, hyphens (-) and dots (.) only. The broker name must start and end with a letter or number with no spaces, underscores, or uppercase letters.

    • If more than one AWS region is available, select the AWS region in which your HiveMQ Cloud broker is located from the list.

    • Enter your contact information and billing address.

    • Provide your payment details. You are not charged during your trial.

    • Review the configuration information in the Plan Details area. For the HiveMQ Cloud Starter free trial, pricing applies only after the 15-day trial ends.

    • After you review your configuration information, save your payment details. Review and agree to the HiveMQ Subscription Agreement, then click Start Free Trial.

View Your Newly Created HiveMQ Cloud Broker

Your trial HiveMQ Cloud Starter broker appears in the Connect & Manage Network view on the Connect page. Broker creation can take a few minutes.

  1. When broker creation is complete, select the broker name on the Connect & Manage Network view to open the Broker Details panel.

  2. On the Broker Details panel, click Configure to access broker details such as connection settings, usage, and configuration options.

    You can also click the settings icon for each broker on the Connect & Manage Network view to access the broker details.
    Broker Details

  3. Explore the broker detail tabs to become familiar with the management interface:

    Table 1. Broker detail tabs
    Tab Description Actions

    Overview

    Shows general broker information and connection details.

    • Custom Domain

    • Delete Broker

    Usage

    How much of the plan limit the broker currently uses.

    • See all usage & billing

    • Set period

    Access Management

    Area to configure how clients prove their identity to your broker and define permissions that control clients access. See, Configure Client Access.

    • Add Credentials

    • Add Permission

    • Add Role

    Integrations

    Connect your broker with external data platforms and services.

    • Configure Confluent

    • Configure Kafka

    • Configure Amazon Kinesis

    API Keys

    Manage API keys and access the HiveMQ REST API for this broker. View URLs to interact with your broker via the REST API.

    • Generate Key

    Troubleshooting

    Get help with common issues.

    • Test your connection

    • Trace Recordings

    • Logs

Configure Client Access to Your HiveMQ Cloud Broker

Before an MQTT client can connect to your HiveMQ Cloud broker, you must configure an authentication method for the client. The HiveMQ Cloud Starter plan offers three ways to ensure that only authorized devices connect to your MQTT broker:

  • Access Credentials

  • Client Certificate

  • JSON Web Token

Only clients that present a known access credential, client certificate, or JSON Web Token are allowed to connect and perform actions on the selected broker. You can choose the authentication method that fits your individual business needs.

You can use only one authentication method at a time. When you configure a method, HiveMQ disables the other methods for your MQTT clients.

This guide shows you how to add username and password access credentials. To learn more about other authentication methods, see HiveMQ Cloud Authentication and Authorization.

Configure Client Authentication

  1. Select the broker name on the Connect & Manage Network view and switch to the Access Management tab.

  2. In the Credentials section of the Authentication area, click Add Credentials.

    Create a HiveMQ Cloud Access Credential
    You can have HiveMQ generate credentials for you or add credentials manually. This guide uses the manual option. For more information, see Access Credentials.

  3. Enter a username, password, and password confirmation, and select a Role, then click Add.

    In HiveMQ Starter plan and above, permissions are tied to roles. When you assign one or more roles to an access credential, clients that connect to your broker with the access credential can perform all activities that the permissions associated with the roles allow.

To get you started, HiveMQ provides a default Allow All role. For more information, see Role Based Access Control.

When you create or edit a credential, the Credentials area automatically adjusts to display your changes. All currently available MQTT access credentials for the selected broker are listed in the Credentials area of the Access Management tab. For more information, see HiveMQ Cloud Authentication and Authorization.

Configure Client Authorization

The HiveMQ Cloud Starter plan uses permissions and roles to control the actions that MQTT clients can perform on your HiveMQ Cloud broker.

To authorize an MQTT client to perform specific actions on your HiveMQ Cloud broker, you assign the MQTT client a role that contains the desired set of permissions. You can define and attach one or more permissions to a role. For more information, see Permission Management.

By default, your HiveMQ Cloud Starter broker contains a predefined Allow All role that includes the default permissions and additional MQTT-specific permissions.

HiveMQ Cloud Permissions

This guide uses the default Allow All role.

To learn how to restrict the access of MQTT clients to your broker, see Create Permissions and Custom Roles.

Test Your New HiveMQ Cloud Broker

After you create your MQTT credentials, you are ready to connect some MQTT clients and explore basic MQTT functionality.

This guide walks you through two ways to try out the connection to your HiveMQ Cloud instance:

Pub/Sub Test with the HiveMQ WebSocket Client

Your HiveMQ Cloud Starter broker supports MQTT over WebSocket on port 8884.

The graphical view of the public WebSocket client provides a convenient way to explore and experiment with MQTT functionality.

Access the HiveMQ WebSocket Client

To get started with the HiveMQ WebSocket Client, switch to the Troubleshooting tab on your HiveMQ Cloud broker details. Then click Test your connection.

Broker Details Troubleshooting Tab

Connect to Your HiveMQ Cloud Broker

  1. In the Connection Settings area, enter the credentials you want to use for the web client connection.
    You can use one of the credentials listed on your Access Management tab or create a new set of automatically generated connection credentials.

    Connect Web Client on HiveMQ Cloud

    1. To connect with credentials that you previously created, enter one of your active credentials and click Connect to establish the connection.

    2. Alternatively, HiveMQ can generate credentials for the connection. To use generated credentials, select Connect with autogenerated credentials.

      • If you selected the Connect with autogenerated credentials option, a dialog opens with your autogenerated username and password.
        Record your new credential information in a secure location, and click Connect to establish the connection.

  2. Upon connection, the screen adjusts to show a Web Client is connected banner.

Pub/Sub Test with the HiveMQ Web Client

After you connect the Web Client to your broker, you can test that messages route correctly through your broker.

  1. In the Topic Subscriptions area of the Test your connection page, enter the wildcard topic # to subscribe to all MQTT topics routed through the broker. Then click Subscribe. The default Quality of Service (QoS) level QoS 0 is suitable for this test.

    Web Client Subscription

  2. In the Send Message area, enter the destination topic, the desired message payload, and quality of service level (QoS). For example, enter Test message payload in the Message field, and web-client-test in the Topic field. The default QoS level is 0.

    Web Client Publish

  3. To publish the message to your HiveMQ Cloud broker, click Send Message.
    In the Messages area of the Test your connection page, the topic, QoS level, and message payload display immediately.

    Web Client Messages

    You can also generate a test message from the Messages area of the Test your connection page. In the Messages area, click Send a test message. HiveMQ automatically generates a message with the topic Hello, QoS: 0, and the payload MQTT.

For more information on MQTT over WebSockets, see the HiveMQ MQTT Essentials special edition on WebSockets.

Pub/Sub Test with the MQTT CLI

This guide uses the MQTT CLI for ease of use and to simplify the explanation of this example procedure. However, you are free to use whichever tool and method you prefer.

Preparation

Download and install the current version of the MQTT CLI.
Documentation and download packages with complete installation instructions are available at no cost on GitHub.
An introductory tutorial for the MQTT CLI is available on YouTube.

Connect an MQTT Client

  1. To start the MQTT CLI in shell mode, open a terminal window and enter the following command:

    mqtt shell

    The MQTT CLI starts and shows a list of options and commands.

  2. To connect to your HiveMQ Cloud broker, enter the following command:

    con --host <broker-url> --port 8883 --secure --user <username> --password <password>

    Replace the placeholders with your own values:

    • <broker-url>: The URL of your broker, from the Overview tab of your broker details.

    • <username> and <password>: The access credentials that you created on the Access Management tab.

      The --secure option opens a TLS connection with the default TLS configuration. HiveMQ Cloud accepts only TLS connections.

      The MQTT CLI shows information about the connection. This client is your first connected MQTT client.

  3. To create a second client, open a second terminal window, and keep the first window open.

  4. In the second window, enter mqtt shell, and then enter the same con command as before.

    This client is your second connected MQTT client.

Publish/Subscribe Test

  1. In the terminal window of the second client, enter the following command:

    sub --topic testTopic --stay

    The second client subscribes to all messages on the topic testTopic. The --stay option keeps the console open, so the client shows each incoming message.

  2. In the terminal window of the first client, enter the following command:

    pub --topic testTopic --message "Hello"

    The first client publishes the message Hello to the topic testTopic. The message appears immediately in the terminal window of the second client.

  3. To publish another message, enter the following command in the first window:

    pub --topic testTopic --message "Goodbye"

    The message Goodbye appears in the terminal window of the second client.

    The MQTT CLI also accepts short options. In the con command, -s is short for --secure. In the sub command, -s is short for --stay. == Next Steps

After you connect your first MQTT clients with your HiveMQ Cloud broker and exchange your first MQTT messages, you are ready to scale up and dive deeper.
To learn more about HiveMQ Cloud features and applications, visit our informative blog: