Send yourself a text message from a MQTT.fx software client using AWS IoT and SNS

IoT, or the Internet of Things, is starting to become a “thing”. Network-enabled gadgets are popping up all over the place in home automation and wearable accessories. Low cost kits like the Raspberry Pi make it easy for anyone to start tinkering with a DIY solution or test out a product idea.

The Internet part of IoT introduces new possibilities. Say that your basement is flooded — an appliance could beep if it senses moisture on the floor. But for times you’re not within earshot, it would be nice if it also sent you a text message.

AWS IoT makes it easy to connect your devices to the cloud. There are certain challenges specific to IoT, and AWS takes care of these for you:

  • Device security: Each device identifies itself and authenticates to the cloud using a certificate. You use policies to control what devices have access to.
  • Service integration: You can link up to other AWS services like SNS (Simple Notification Service), SQS (Simple Queue Service), and Lambda. IoT Rules can take you pretty far without writing code.
  • Two-way communication: Not only can devices send messages to the cloud, you can push state changes to a device — even if it’s offline at the moment.

In this tutorial, you’ll get your hands dirty with AWS IoT. You don’t need any hardware — which means you can get some practice with AWS IoT without having to buy sensors, breadboards, or buttons. Instead, you’ll use a desktop software client to mock out a hardware device.

Using the basement moisture alarm scenario, the goal of this tutorial is to get a software client to send you a text message:

  1. A software client sends an MQTT message to AWS IoT. (MQTT is a protocol commonly used in IoT)
  2. An IoT Rule sends an event to SNS
  3. SNS sends you a text message.

schematic-iotYou’ll learn how to work with the following:

  • SNS: Send text messages to yourself to make sure things are working end-to-end.
  • IoT Rules: Wire up AWS IoT to services like SNS.
  • IoT setup: Configure a Certificate, Policy, and Thing for each IoT device.
  • MQTT.fx: Import your certificate to a software client.

What you need before you begin

You need an AWS account for this tutorial. You can sign up for the free tier at aws.amazon.com.

You also need to download and install an MQTT software client, which is free. This tutorial assumes you are using a Mac, but the client is also available on PC.

  1. Download the MQTT.fx-1.1.0.dmg file.
  2. Open the disk image.
  3. Do not double-click on the Installer icon. Instead, right-click and select Open.
    right-click-open-mqtt
  4. You should see an alert confirming whether you wish to open software from an unidentified developer. Click Open.
    unidetified-developer-alert
  5. You should see an install4j Wizard. Accept the defaults and keep clicking Next until you’re finished installing MQTT.fx.mqtt-install-wizard

The developer of the MQTT.fx software was kind enough to provide this client for free. But since you’re installing it off the internet, you need to do things a little differently to let your Mac know that you are intentional about running this software.

Send a text message to your phone using SNS

In this section, you’re going to configure SNS to send a text message to your phone. Although you don’t need to know SNS in order to use AWS IoT, it’s worth learning for a couple of reasons:

  • Setup is quick, making SNS great for testing IoT Rules.
  • Sending text alerts is a practical use case for IoT.

SNS uses something called a topic. A topic is a channel, kind of like the cable TV channel HBO. The TV network broadcasts the latest episode of Silicon Valley, and only subscribers get to watch. Likewise, you can publish a message to a topic, and SNS pushes it out to subscribed users.

In this section, you’ll create a topic for your IoT test messages.

Set up a topic

  1. Log into AWS and go to the main dashboard.
  2. Under Mobile Services, click SNS.
  3. Click past the Get Started screen, if necessary.
  4. Within the SNS dashboard, click Create topic.
    create-topic
  5. In the Create new topic modal, type in TutorialTestSNS as the Topic name.
  6. For the Display name, type in MySensor.
    create-SNS-topicThe Display name shows up as a prefix in every message sent to the user.
  7. Click Create topic.
  8. You should see a Topic details summary screen:topicDetailSummary

Now that you have a topic, the next step is to subscribe using your cell phone number.

Create a subscription

  1. On the Topic details page, click Create subscription.createSubscription
  2. In the Create Subscription modal, change the Protocol to SMS.
  3. In the Endpoint field, type in your cell phone number.createSubscriptionModal
  4. Click Create subscription.

You may receive a text message asking whether you would like to receive messages from MYSENSOR. Just follow the instructions (e.g. reply with YES MYSENSOR to confirm your subscription).

Now that your cell phone is subscribed to an SNS topic, you can start sending text messages.

Send a test message

  1. On the Topic details page, click Publish to topic.topicDetailSummary
  2. On the Publish a message screen, type something into the Message field, like “your basement is flooded“.publishMessageFormNote: The Subject field is used for email, so you can leave it blank.
  3. Click Publish message.
  4. You should receive a text message.textMessageBasement

Using the SNS console, you are able to send text messages to your phone. The next step is to trigger this SNS topic from the AWS IoT console.

Wire an IoT Rule to SNS

Before you set up any IoT devices, you’re going to first create an IoT Rule. This way, you can test whether things are working along the way. You’ll do more IoT setup (i.e. configure a policycertificate, and thing) in a later section.

IoT Rules connect AWS IoT to other AWS services, including:

  • S3
  • SQS
  • Kinesis
  • Lambda
  • SNS

There are two parts to an IoT Rule:

  • Rule query statement: Filters through incoming IoT messages so that the rule only runs under specific conditions.
  • Action: Forwards the IoT message to another AWS service.

In this section, you’re going to listen for any IoT messages sent to a topic named moisture-level. Then you’ll forward these messages to the SNS topic you created earlier.

Create a Rule

  1. From the main Dashboard, click AWS IoT.
  2. On the splash screen, click Get started.first-time-IoT-splash
  3. On the Resources page, click Create a resource.aws-iot-resourcesNote: AWS IoT might take you to Create a thing by default. Just skip to the next step.
  4. Choose Create a rule.create-a-rule
  5. In the Create a rule form, type TutorialTestRule in the Name field.create-a-rule-form

This is going to be a pretty long form, so keep on reading!

Create a rule query statement

IoT rules use a rule query statement to filter on relevant IoT messages. The query uses an SQL-like syntax. Don’t worry, you don’t have to write it manually (in fact, the form doesn’t even let you). The form generates syntax for you based on how you fill out the AttributeTopic filter, and Condition form fields.

  1. For the Attribute field, type *.
  2. For the Topic filter field, type moisture-level.
  3. Leave the Condition field blank.select-form-iot

The generated rule query statement should look like this:

This rule listens for any IoT messages sent to the moisture-level topic. The asterisk (*) means every attribute (i.e. the entire message) is forwarded to the action.

Note: AWS IoT uses topics just like SNS. This is because they both use the pub-sub pattern.

Create an action

  1. For the Choose an action dropdown, select Send message as a push notification (SNS).create-a-rule-form-BThe form reveals additional fields, depending on which service you choose.
  2. For the SNS target, select the SNS topic named TutorialTestSNS that you created earlier.
  3. For the Message format, type in RAW.create-a-rule-form-CThe form also accepts JSON as an option.
  4. Next to Role name, click Create a new role.
    This creates a role that gives AWS IoT permission to publish messages to your SNS topic.
  5. For Role name, type in tutorial-test-iot-role, and click Create.
  6. Click Add actioncreate-role-iot
  7. You should see a purple SNS icon next to the words SNS Action. Click the Create button. sns-action-create-rule
    Note: if the Create button is still gray, go back and make sure the form is filled out completely.

To recap, you just created an IoT Rule. In the process of filling out this form, you created three things:

  • Rule query statement: Listens on an IoT topic named moisture-level.
  • Action: Relays the message to an SNS topic named TutorialTestSNS.
  • Role: Grants AWS IoT permission to call SNS.

Test the rule

In order to test the rule, you need to publish IoT messages to the moisture-level topic. Fortunately, you can do this using the MQTT Client built right into the AWS console.

  1. In the navigation bar, click MQTT Client.nav-bar-mqtt-client
  2. Under MQTT Client Actions, click Generate client ID.
  3. Once the client ID is generated, click Connect.built-in-mqtt-client
  4. Click Publish to topic.
  5. In the Publish topic field, type in moisture-level.
  6. Under Payload, type in the following message: “your berber is ruined”.aws-mqtt-client-message-send
  7. Click Publish.
  8. You should receive a text message.text-message-carpet

The built-in MQTT Client is very convenient for sending test messages. All you had to do was click the Generate client ID button, and AWS automatically creates a virtual client for you.

But for physical IoT devices (or in our case, a software client), you’ll have to manually configure certificates, policies, and things. This is the subject of the next section.

Configure AWS IoT

A good portion of AWS IoT configuration relates to security. These devices could unlock a door, or stream a baby monitor feed, so it’s important to get security right.

In this section, you’re going to configure three components, and then link them together.

  • Thing: An instance that represents a physical IoT device.
  • Policy: A permission set that authorizes a device to perform actions and access resources.
  • Certificate: A set of credentials used to authenticate and identify a device.

Create a Thing

The tutorial is halfway over, and you finally get to create your first Thing!

  1. Click Create a resource.aws-iot-resources
  2. Click Create a thing.
  3. In the Name field, type TutorialTestThing1.
  4. Leave the thing type and attributes as their default.
  5. Click Create.create-a-thing1
  6. You should see a new thing at the bottom of the screen.tutorial-test-thing-1

thing represents just a single instance of an IoT device. If you have an entire inventory of devices, AWS IoT provides tools to help you manage them: thing type, thing registry, and search attributes.

Create a Policy

A policy manages the permissions of your IoT device.

  1. Click Create a policy.
  2. In the Name field, type TutorialTestPolicy.tutorial-test-policy
  3. In the Add a statement section, type iot:* in the Action field.
  4. Type in the Resource field.
  5. Check the box next to Allow.
  6. Click Add statement.
  7. The Create button should turn blue. Click Create.create-iot-policy-statamenet
  8. You should see a new Policy at the bottom of the screen.created-new-iot-policy

You just created a policy with a fairly open permission set, which is fine for getting things to work in a tutorial. But you might want to tighten down access in a real application.

Create a Certificate

  1. Click Create a certificate.create-a-certificate
  2. Under Create a certificate, check the box next to Activate.
    Checking this box saves you from having to remember to activate the certificate later on.
  3. Click the 1-Click certificate create button.
  4. Click Download public key and note the file’s save location.
  5. Click Download private key.
  6. Click Download certificate.one-click-create-certificate
  7. You should see a Certificate at the bottom of the page, with an ACTIVE status.active-iot-certificate
  8. In Finder, you should see three files in your Downloads folder.downloaded-certificates-iot

Note: Before you navigate to a different page, it’s important to download the private key while the link is still available.

Attach your Thing, Policy, and Certificate

So far, you created a thing, policy, and certificate. Next you need to link them together. You do this by attaching the policy and thing to the certificate.

  1. Check the box underneath the Certificate you just created (the one with a handshake icon).
  2. Under the Actions dropdown, select Attach a policy.
  3. In the pop-up modal, type TutorialTestPolicy in the Policy name field, and click Attach.
  4. Again, under the Actions dropdown, select Attach a thing.
  5. In the pop-up modal, type TutorialTestThing1 in the Thing name field, and click Attach.attach-policy-thing
  6. Select the Certificate. In the Detail pane on the right, you should see the policy and thing you just attached.attached-policy-and-thing

 

Configure the MQTT Client

MQTT is a lightweight pub-sub protocol that’s popular with IoT. MQTT.fx is a free cross-platform software client that uses this protocol.

In order to use MQTT.fx, you have to configure it with your certificate, private key, and API enpoint — just as you would any IoT device. This means you can use MQTT.fx to mock out a hardware device, and get some practice with AWS IoT even if you don’t own a Raspberry Pi or Amazon IoT button.

Set up the Connection Profile

Note: Make sure MQTT.fx is installed on your computer. Refer to the beginning of this tutorial for installation instructions.

  1. Launch MQTT.fx from your Applications folder.
  2. Near the top, click the Gear ⚙  icon to open the Edit Connection Profiles window.gear-icon-mqtt
  3. On the bottom left corner, click the Plus ➕ button to create a new Profile.create-new-profile-mqtt
  4. Back in the AWS IoT console, select your thing named TutorialTestThing1. In the right detail pane, look for the REST API endpoint.
  5. Copy the hostname (e.g. abcdefghjklmno.iot.us-east-1.amazonaws.com).rest-api-endpoint-iot
  6. Back in the MQTT.fx client, look for the Broker Address field. Replace the default 127.0.0.1 with your REST API endpoint hostname.
  7. Change the Broker Port from 1883 to 8883, which is MQTT over SSL.
  8. You can leave the Profile Name and Client ID as the default.broker-address-port

You’re not done yet — you still have to configure your certificate and key in the bottom half of the form.

Set up the Certificates

A certificate authenticates your IoT device to AWS. The private key also identifies your device, because it’s assumed that you alone have that key.

  1. In the bottom half of the form, switch tabs from General to SSL/TLS.
  2. Check the box next to Enable SSL/TLS.
  3. Select the radio button for Self signed certificates.
  4. Check the box next to PEM Formatted.set-SSL-mqtt
  5. For the CA File, download this file. Open the zip file, and use root-CA.crt as your CA File.
    Note: If you prefer, you can create the file yourself using these instructions.
  6. For the Client Certificate File, use the xxxxxxx-certificate.pem.crt file you downloaded earlier.
  7. For the Client Key File, use the xxxxxxx-private.pem.key file.
    Note: you wont be using the xxxxxxx-public.pem.key.
  8. Click Apply, and OK.mqtt-cert-files-set

You’ll find out in the next section whether the configuration worked.

Test the Profile

Now to finally test the entire MQTT setup from end to end. You’ll send an MQTT message to AWS IoT, and hopefully you’ll get a text message from SNS.

  1. Make sure your New Profile is selected, and click Connect.connect-new-profile-mqtt
  2. If you see a lock icon and green circle in the top right corner, this means the connection worked.lock-icon-green-circle
  3. Make sure the Publish tab is selected.
  4. For the topic name, type in moisture-level.
  5. In the message body, type in “hi from MQTT.fx!”
  6. Click Publish.test-message-mqtt-hi
  7. Wait a few moments, and you should receive a text message.text-message-from-mqtt

 

Conclusion

You sent a text message to yourself using the MQTT.fx software client. Under the hood, you used AWS IoT and SNS to accomplish this.

In this tutorial, you started with SNS and IoT rules, and worked backward from there. There’s a lot that could go wrong, so it’s important to be able to test along the way.

When writing this tutorial, I found these two resources to be particularly helpful:

The AWS documentation is quite good. But as reference material, it has to be comprehensive. My goal for this tutorial was to provide a quickstart guide to get your feet wet, under the assumption that

Got any tips for using AWS IoT? Have any suggestions for future tutorial topics? Feel free to add your thoughts to the comments.

Like this post? Please share it using the share buttons to the left. Then join our mailing list below and follow us on Twitter – @thorntech – for future updates.