Disruptive Technologies Disruptive Developers

30min of your time:

Sending SMS notifications

If coffee thumbs-up button pressed, then send SMS: "Another vote for the new coffee beans! 👍"

If water pipe temperature < 2 degrees C, then send SMS: "The pipe is in danger of freezing! ❄️"

If fire escape door is opened, then send SMS: "Someone just opened the emergency exit door! 🤦‍♀️"

This guide contains everything you need to do the above without writing a single line of code by using Node-RED and Twilio deployed on IBM Cloud.

After you have completed this guide you will be able to:

  • Send SMS notifications based on temperature, touch or proximity
  • Configure notifications per-sensor
  • Add notifications to any Studio project by adding a Data Connector

Deploying and configuring the application in 3 simple steps

To get the application up and running we will:

  1. Deploy the pre-made Node-RED application to IBM Cloud
  2. Configure the application with your Twilio credentials
  3. Set up the Data Connector that will send sensor data to your application

Before you begin

You will need:

  • An IBM Cloud account to host the application.
  • A Twilio account to send SMS.

Both IBM Cloud and Twilio offer free trial accounts.

Twilio trial account setup

To be able to send an SMS using a Twilio Trial Account, there are a few things you will need to configure:

  1. Make sure the phone number you want to send an SMS to is a Verified Caller ID. The number you used when you signed up for the Twilio trial is automatically added already.
  2. Add a number from which you send your SMS with, as per Twilio’s trial guide.

    Please make sure the number you add has SMS capabilities.

  3. Make sure the country you are sending the SMS to is checked in your Messaging Geographic Permissions.

Step 1 - Deploy application to IBM Cloud

  1. Deploy to IBM Cloud by pressing this button:

    Deploy to IBM Cloud

    If you don’t have a IBM Cloud account yet, then you will be asked to create one. If you do this in this step, then you will have to go back and click the deploy button again after you have created and verified your account.

    The underlying GitHub repository can be found at https://github.com/disruptive-technologies/nodered-twilio-ibm-cloud.

    Note:If you already have an existing Node-RED installation and editor, you can find the flow used in defaults/flow.json and import this straight into the editor via the top-right menu.

  2. Configure the deployment by:

    1. Select your closest Region
    2. Create an IBM Cloud API Key
    3. Wait for Region, Organization and Space to load
    4. Press Deploy

  3. Wait until the application has been built and deployed:

    1. Navigate to the Delivery Pipeline.

    1. Wait for the deployment to complete, then click on the application, or View console.

    1. Open the newly deployed application by pressing Visit App URL

Step 2 - Configure the Node-RED application

After the Node-RED application has been deployed, it is configured from within the application itself.

Note: There is a known issue with the Grammarly Chrome plugin causing issues with Node-RED. Either disable the plugin while working with the Node-RED editor, use an incognito tab or another browser.

  1. If you don’t already have the Node-RED application open, navigate to the application by going to the IBM Cloud dashboard and clicking on the new applications App URL.

  2. Go through the guide and:

    1. Set a Username and Password

    2. Skip “Optionally enable Application Metrics for Node.js monitoring” and “Browse available IBM Cloud nodes” for now.

    3. Press Finish and wait for the editor to load

    4. Click Go to your Node-RED flow editor

  3. In the new editor, locate the Twilio node and:

    1. Double-click on the node

    2. Add a new API profile

    3. Fill in the details from your Twilio account.

      The Account SID and Token can both be found in the Twilio Dashboard.

      The From number can be found in on Twilio’s Manage Numbers.

    4. Deploy the updated flow

Optional - Enable debugging

Enable debugging or troubleshooting at any point in the flow by pressing the little button next to the attached, green, debug nodes and redeploy the flow.

The debug log is available on the right hand side.

Step 3 - Create a Data Connector in Studio

You need to add a Data Connector to your projects in Studio to send events from our servers to the SMS application.

Step 2-10 needs to be done for every project that should support SMS notifications on sensors.

  1. Go to Studio.

  2. Navigate to the project you want to enable notifications for.

  3. Open the Data Connector view for the project via the menu on the left.

  4. Click Create new.

  5. Set the Name to “SMS Notifications”.

  6. Take the App URL saved previously, add /events at the end, and enter this into Endpoint URL.

    Example: https://nodered-twilio-ibm-cloud.eu-gb.mybluemix.net/events

  7. Set the Data Connector to only send the Touch, Temperature, ObjectPresent and ConnectionStatus events.

  8. Configure the INCLUDE SENSOR & CLOUD CONNECTOR LABEL DATA to be:

    Notify, Message, AltMessage, Phone, Email, EmailSubject, TouchTrigger, ObjectPresentTrigger, MaxTempTrigger, MinTempTrigger, ConnectionTrigger

  9. Leave everything as is and click SAVE NEW DATA CONNECTOR.


Setting up notifications on a sensor

A label is a key-value pair that is associated with a sensor.

All notifications are configured by adding specific labels to sensors in Studio.

Adding sensor labels

There are two ways to add labels to sensors in Studio:

  1. Add labels on one sensor at a time in the sensor details view.

  2. Add labels to multiple sensors at the same time by selecting multiple sensors in Studio and pressing the “LABELS” button on the right side above the list.

Labels as configuration

The SMS notification application is configured straight from inside Studio using specific labels.

These labels are then added as meta-data to each sensor event sent from our servers to the SMS application over the previously configured Data Connector.

The following table contains all possible configurations:

Label Key Value  
Notify true or false Enable notifications on this sensor
TouchTrigger true or false Trigger on touch
ObjectPresentTrigger NOT_PRESENT, PRESENT or BOTH Trigger on proximity event(s)
MaxTempTrigger E.g. 20 Trigger when temperature above Value, in degrees C
MinTempTrigger E.g. 2 Trigger when temperature below Value, in degrees C
ConnectionTrigger true or false Enable notifications on Cloud Connector offline/online
Phone +47XXXXXX The phone number(s) to send SMS to
Message The pipe is in danger of freezing! The SMS text that should be sent
AltMessage The fire door was closed again.  

AltMessage usage

The AltMessage can be set to configure the text that is sent when:

  1. ObjectPresentTrigger is BOTH and we get a NOT_PRESENT event.
  2. MinTempTrigger is triggered, to support different messages for MinTempTrigger and MaxTempTrigger.
  3. ConnectionTrigger is triggered, AltMessage controls what message to send when the device goes online.

Examples

Example 1: Send SMS on button press

Label Key Value
Notify true
TouchTrigger true
Phone +47XXXXXX
Message Another vote for the new coffee beans!

Example 2: Send SMS when temperature below 2 degrees C

Label Key Value
Notify true
MinTempTrigger 2
Phone +47XXXXXX
Message The pipe is in danger of freezing!

Example 3: Send SMS when a door is opened and closed

Label Key Value
Notify true
ObjectPresentTrigger BOTH
Phone +47XXXXXX
Message Someone just opened the emergency exit door!
AltMessage The emergency exit door was closed again.

Example 4: Send SMS when a Cloud Connector goes offline and online

Label Key Value
Notify true
ConnectionTrigger true
Phone +47XXXXXX
Message Warning: Cloud Connector in Warehouse 1B is offline.
AltMessage Cloud Connector in Warehouse 1B is now online again.

Special cases and troubleshooting

  • Both keys and values are case-sensitive.
  • Using TouchTrigger together with ObjectPresentTrigger or Min/MaxTempTrigger at the same time will generate multiple notifications.
  • You can add multiple recipients by adding a comma-separated list of phone numbers to the Phone label.
  • Temperature triggered SMS are only sent once. After a temperature trigger SMS has been sent, the temperature has to go down/above the trigger value at least once before a new SMS is sent.
  • State is cached using best effort in memory. During redeployment, it’s possible to receive extra Min/MaxTempTriggers or ConnectionTrigger events, if it is already active.