ApsaraMQ for MQTT:Migrate clients from open-source MQTT brokers to ApsaraMQ for MQTT

Prerequisites

Before you begin, make sure that you have:

• An Alibaba Cloud account with sufficient balance

• A Java development environment with Maven configured

• An existing MQTT client application that uses the Eclipse Paho Java SDK

This guide uses the Eclipse Paho Java SDK as an example. The same parameter changes apply to other languages and SDKs. For complete sample projects, see Demo projects.

Create an instance

1. Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.

2. In the top navigation bar, select a region. In the upper-left corner, click Create Instance.

3. In the panel that appears, keep the default value Subscription for the Billing Method parameter. Click OK.

4. Select the instance specifications based on your requirements, select Terms of Service, and click Buy Now. For a comparison of instance editions, see Instance editions.

5. Complete the payment as prompted.

Create a topic

1. Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.

2. Select the region of your instance. Click the instance name to open the Instance Details page.

3. In the left-side navigation pane, click Topics. In the upper-left corner, click Create Topic.

4. Set the Name and Description parameters, then click OK.

Create a group

1. Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.

2. Select the region of your instance. Click the instance name to open the Instance Details page.

3. In the left-side navigation pane, click Groups. In the upper-left corner, click Create Group.

4. Set the Group ID parameter and click OK.

Add Maven dependencies

Add the following dependencies to the pom.xml file of your project:

<dependencies>
    <!-- MQTT client -->
    <dependency>
        <groupId>org.eclipse.paho</groupId>
        <artifactId>org.eclipse.paho.client.mqttv3</artifactId>
        <version>1.2.2</version>
    </dependency>

    <!-- Required for signature-based authentication -->
    <dependency>
        <groupId>commons-codec</groupId>
        <artifactId>commons-codec</artifactId>
        <version>1.10</version>
    </dependency>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.2</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.48</version>
    </dependency>
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-onsmqtt</artifactId>
        <version>1.0.3</version>
    </dependency>
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <version>4.5.0</version>
    </dependency>
</dependencies>

If your project already includes the Eclipse Paho dependency, keep version 1.2.2 or later. The remaining five dependencies are required for signature-based authentication. If you use custom authentication, see Custom authentication for the required dependencies.

Update connection parameters

The following table lists the parameters to change. All other parameters (QoS, retained flag, clean session, keep-alive interval) remain the same.

Code comparison

The following examples show the connection code before and after migration. Only the highlighted parameters change.

Before migration (open-source broker):

String broker = "tcp://my-emqx-broker.example.com:1883";
String clientId = "my-device-001";

MqttClient client = new MqttClient(broker, clientId, new MemoryPersistence());

MqttConnectOptions connOpts = new MqttConnectOptions();
connOpts.setUserName("my_user");
connOpts.setPassword("my_password".toCharArray());
client.connect(connOpts);

// Publish and subscribe -- same as before
client.publish("my/topic", new MqttMessage("Hello".getBytes()));

After migration (ApsaraMQ for MQTT with signature authentication):

// Endpoint: find on Instances > Endpoints for Client SDK tab
String broker = "tcp://mqtt-cn-******.mqtt.aliyuncs.com:1883";

// Client ID: <GroupID>@@@<DeviceID>
// GroupID: created in the ApsaraMQ for MQTT console
// DeviceID: a unique identifier you assign to each device
String groupId = "GID_test";
String deviceId = "my-device-001";
String clientId = groupId + "@@@" + deviceId;

MqttClient client = new MqttClient(broker, clientId, new MemoryPersistence());

MqttConnectOptions connOpts = new MqttConnectOptions();
// Signature mode: AccessKey ID as username, HMAC signature as password
String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
String secretKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
connOpts.setUserName(accessKey);
connOpts.setPassword(Tools.macSignature(clientId, secretKey).toCharArray());
client.connect(connOpts);

// Publish and subscribe -- no changes to message logic
client.publish("my/topic", new MqttMessage("Hello".getBytes()));

For the complete Tools class implementation and other authentication methods, see Demo projects.

Troubleshoot connection failures

If the connection fails, check the following: