HiveMQ Swarm Scenarios

Scenarios are an important concept in HiveMQ Swarm. Each scenario is an abstract representation of a specific real-life MQTT use case.

You can define scenarios that represent very large numbers of MQTT clients and client actions. The ability of HiveMQ Swarm to execute big scenarios makes it possible for you to replicate the behavior of even large-scale IoT systems.

HiveMQ Swarm organizes the simulated MQTT clients that are used for each scenario in client groups and delineates the behavior of the clients in stages, lifecycles, and commands.

Create a HiveMQ Swarm Scenario

If you are currently using a trial version of the HiveMQ broker, you are limited to 25 client connections. Similarly, the trial version of HiveMQ Swarm only allows 25 clients and 1 agent. To run HiveMQ Swarm scenarios that require more connections, contact our sales team to request an extended evaluation licence or to learn more about HiveMQ Swarm options.

HiveMQ Swarm scenarios are defined in XML-based domain-specific language (DSL). The root tag of every scenario is <scenario>.

To simplify the development of scenarios, HiveMQ Swarm ships with an XML schema (xsd) that is located in the scenarios directory scenario/scenario.xsd of your HiveMQ Swarm installation.

Make sure to place the following information in your XML header:

<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="/path/to/scenario.xsd">
</scenario>

You can use the HiveMQ Swarm example scenario as a starting point for your custom scenarios. For more information, see HiveMQ Swarm Quick Start Guide.

Configure MQTT Broker Connections

In the <brokers> tag of your <scenario> configuration, you define each <broker> and <websocket-broker> that you want to use in your scenario.

One scenario can use multiple brokers.

To simulate client connections over WebSocket or Secure WebSocket, use the <websocket-broker> tag and define the path and port that WebSocket uses. For more information, see WebSockets.

Table 1. Broker connections settings
Setting	Description	Type	Required/Default
`id`	The unique identifier of the broker in this scenario	IDREF	required
`address`	The host address of the broker	string	required
`port`	The port on which the broker accepts MQTT connections	positive integer	1883
`transport`	The transport method the broker uses	string	TCP
`path`	The last part of the path to the WebSocket (only for WebSocket brokers)	string	/mqtt

Broker connections example code

<scenario>

    <brokers>
        <broker id="b1">
            <address>localhost</address>
            <port>1883</port>
            <transport>TLS</transport>
        </broker>

        <websocket-broker id="b2">
            <address>localhost</address>
            <port>80</port>
            <transport>TCP</transport>
            <path>/mqtt</path>
        </websocket-broker>

        <websocket-broker id="b3">
            <address>localhost</address>
            <port>443</port>
            <transport>TLS</transport>
            <path>/mqtt</path>
        </websocket-broker>
    </brokers>

</scenario>

Define Client Groups

In the <clientGroups> tag of your <scenario> configuration, you define the sets of MQTT clients that share common lifecycles in the scenario. Each set of clients forms a <client-group>.

Scenarios frequently have more than one <client-group>.

Each <client group> must contain at least one MQTT client.
All clients in the same <client group> have the same MQTT version, client ID pattern, and behavior in the scenario.

HiveMQ Swarm assigns each client in the <client-group> a unique client identifier that is derived from the clientIdPattern and the clientIdPatternOffset that you define for the group.

The count setting determines the number of clients in the <client-group>.

Table 2. Client group settings
Setting	Description	Type	Required/Default
`id`	The unique identifier of the client group in this scenario	IDREF	required
`clientIdPattern`	The pattern HiveMQ Swarm uses to generate client IDs	regular_expression	id + "-{64}"
`clientIdPatternOffset`	The offset of the client ID pattern	non-negative integer	0
`count`	The number of clients in the client group. The count + offset settings must not exceed the number of client IDs the client ID pattern can generate.	positive integer	1
`mqttVersion`	The MQTT version the clients use	3 or 5	5

Client groups example code

<scenario>

    <clientGroups>
        <clientGroup id="cg-1">
            <clientIdPattern>publisher-[0-9]{3}</clientIdPattern>
            <clientIdPatternOffset>500</clientIdPatternOffset>
            <count>500</count>
            <mqttVersion>3</mqttVersion>
        </clientGroup>
    </clientGroups>

</scenario>

Client ID Pattern Without Offset Example

This example shows how to set the client ID pattern of a client group without an offset.

The example creates a client group that contains 5 clients with the following identifiers:

<clientGroup id="publishers">
    <clientIdPattern>publishers-[0-9]</clientIdPattern>
    <count>5</count>
</clientGroup>

publishers-0
publishers-1
publishers-2
publishers-3
publishers-4

Client ID Pattern With Offset Example

This example shows how to set the client ID pattern of a client group with an offset.

The example creates a client group that contains 5 clients with the following identifiers:

<clientGroup id="subscribers">
    <clientIdPattern>subscribers-[0-9]</clientIdPattern>
    <clientIdPatternOffset>5</clientIdPatternOffset>
    <count>5</count>
</clientGroup>

subscribers-5
subscribers-6
subscribers-7
subscribers-8
subscribers-9

Define Topic Groups

In the <topicGroups> tag of your <scenario> configuration, you define each <topicGroup> that the client groups in your scenario can use to receive and publish messages.

Each topic group must contain at least one topic.

HiveMQ Swarm assigns each topic group a unique topic name that is derived from the topicNamePattern and the topicNamePatternOffset that you define for the group.

The count setting limits the size of the topic group.

Table 3. Topic group settings
Setting	Description	Type	Required/Default
`id`	The unique identifier of the topic group in this scenario	IDREF	required
`topicNamePattern`	The pattern HiveMQ Swarm uses to generate topic names	regular expression	required
`topicNamePatternOffset`	The offset of the topic name pattern	non-negative integer	0
`count`	The number of topics in the topic group. The count + offset must not exceed the number of topics the topic name pattern can generate.	positive integer	1

Topic groups example code

<scenario>

    <topicGroups>
        <topicGroup id="topics-1">
            <topicNamePattern>waitingTopic[0-9]{3}</topicNamePattern>
            <topicNamePatternOffset>500</topicNamePatternOffset>
            <count>500</count>
        </topicGroup>
    </topicGroups>

</scenario>

Set Topic Pattern Name Without Offset Example

This example shows how to set a topic pattern without an offset.

The example creates the following three topic names:

<topicGroup id="home">
    <topicNamePattern>home/room-[0-9]/light</topicNamePattern>
    <count>3</count>
</topicGroup>

home/room-0/light
home/room-1/light
home/room-2/light

Set Topic Pattern Name With Offset Example

This example shows how to set a topic pattern with an offset.

The example creates the following three topic names:

<topicGroup id="home">
    <topicNamePattern>home/room-[0-9]/coffeeMachine</topicNamePattern>
    <topicNamePatternOffset>5</topicNamePatternOffset>
    <count>3</count>
</topicGroup>

home/room-5/coffeeMachine
home/room-6/coffeeMachine
home/room-7/coffeeMachine

Define Subscriptions

In the <subscriptions> tag of your <scenario> configuration, define the subscription behavior that is available in the scenario.

Multiple subscribe commands can reference the same subscription.

You can model subscriptions in two ways:

Reference a topic group that contains one or more topics
Reference a specific topic filter directly

Table 4. Subscriptions settings
Setting	Description	Type	Required/Default
`id`	The unique identifier of the subscription in this scenario	IDREF	required
`topicGroup`	The ID of the topic group of the subscription	IDREF	required for topic group subscriptions
`wildcard`	Optional wild card HiveMQ Swarm can generate to match the entire target group	boolean	false
`topicFilter`	The MQTT topic filter of the subscription	string	required for topic filter subscriptions

This code example shows a subscription to a topic group.

<scenario>

    <subscriptions>
        <subscription id="subscription-1">
            <topicGroup>topics-1</topicGroup>
            <wildCard>false</wildCard>
        </subscription>
    </subscriptions>

</scenario>

This code example shows a subscription to a specific topic filter.

<scenario>

    <subscriptions>
        <subscription id="subscription-2">
            <topicFilter>topic/subtopic/#</topicFilter>
        </subscription>
    </subscriptions>

</scenario>

Define Lifecycles of Client Groups

In the <lifecycle> tags of your <scenario> configuration, define the behavior of each MQTT client in a specific client group.

Each lifecycle contains one or more commands that all clients in the client group must complete during the associated stage of the scenario. A command is an abstract representation of an MQTT operation such as connect, disconnect, publish, and subscribe, or other behavior such as waiting.

The commands in the lifecycle of each client are executed sequentially.

To learn more about all the commands you can use in a lifecycle, see Commands.

Lifecycle Example

This example scenario shows a client group with one client, and a lifecycle that defines the following behavior for the client in the client group:

Connect to the MQTT broker
Subscribe to a topic
Publish a message and wait for a response for 10 iterations
Disconnect once all commands are complete

<scenario>
    ...
    <stages>
        <stage id="s1">
            <lifeCycle id="wait" clientGroup="waiter">
            <!--each client in the "waiter" client group connects to the "broker" broker-->
                <connect broker="broker"/>
                <subscribe to="topic"/>
                <!--each client in the "waiter" client group subscribes to the "topic" topic-->
                <for times="10">
                <!--each client in the "waiter" client group executes the commands contained in the 'for' tag 10 times-->
                    <publish message="test" topicGroup="topic"/>
                    <!--each clients in the "waiter" client group publishes a message to the "topic" topic 10 times-->
                    <receive from="topics-2" messagePattern="test"/>
                    <!--each client in the "waiter" client group waits to receive a message from the "topics-2" topic group with the message pattern "test" 10 times-->
                </for>
                <disconnect/>
                <!--each client in the "waiter" client group disconnects from the "broker" broker-->
            </lifeCycle>

        </stage>
    </stages>
</scenario>

Define Scenario Stages

In the <stages> tags of your <scenario> configuration, you define each <stage> of action through which your scenario progresses. Each stage contains the lifecycle of one or more client groups.

Per stage, only one lifecycle can be defined for a particular client group. However, one stage can contain the lifecycles of many different client groups.

If the stage contains lifecycles for more than one client group, HiveMQ Swarm executes the lifecycles in parallel.

As soon as a stage starts, HiveMQ Swarm begins all lifecycles of all the client groups that the stage contains.

When the last lifecycle in a stage finishes, the stage ends.

When the last stage ends, the scenario is complete.

Stages Example

In this example, a scenario contains two stages and two client groups with 10 clients each. The stages in a scenario always execute sequentially.

The first stage of the scenario is the connectStage. This stage contains two lifecycles. All lifecycles in the stage begin simultaneously:

The lifecycle for each client in the subscribers client group is to connect to the broker and subscribe to the topic named topic.
The lifecycle for each client in the publishers client group is to connect to the broker.

When both lifecycles of the first stage are done, the next stage begins.

The second stage of the scenario is the publishStage. This stage starts when the first stage is done. The second stage also contains two lifecycles:

The lifecycle for each client in the subscribers client group is to wait to receive 100 publishes from the topic group topic that match the pattern test and then disconnect.
The lifecycle for each client in the publishers client group is to publish 10 messages on the topic topic group with the message payload test and then disconnect.

When all the lifecycles of the second stage are done, the second stage finishes.

Since the second stage is the last stage of the scenario, when the second stage is finished, the scenario ends.

<scenario>

    <stages>
        <stage id="connectStage">
            <lifeCycle id="subscribers-1" clientGroup="subscribers">
                <connect to="broker"/>
                <subscribe to="topic"/>
            </lifeCycle>
            <lifeCycle id="publishers-1" clientGroup="publishers">
                <connect to="broker"/>
            </lifeCycle>
        </stage>
        <stage id="publishStage">
            <lifeCycle id="subscribers-2" clientGroup="subscribers">
                <receive from="topic" messagePattern="test" count="100"/>
                <disconnect/>
            </lifeCycle>
            <lifeCycle id="publishers-2" clientGroup="publishers">
                <publish message="test" topicGroup="topic" count="10"/>
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>

</scenario>

MQTT CLI

The HiveMQ platform ships with the open-source MQTT CLI command line tool. In addition to many other useful features, the MQTT CLI provides solid support for HiveMQ Swarm straight out of the box.

For a full list of all the HiveMQ Swarm-related command-line prompts the MQTT ClI offers, see MQTT CLI | HiveMQ Swarm.

Next Steps

Become familiar with all the commands you can use to shape client behavior in the lifecycles of your scenarios and browse through our collection of example scenarios.