Using Flux with Sim:sendDownlinkPing API to Monitor Devices

Introduction

Soracom Flux is a low-code IoT application builder designed for advanced automation.

In this guide, we use Flux to periodically monitor the status of devices that use Soracom Air SIMs or Virtual SIMs.

We will be creating a Flux app using the Soracom API, Sim:sendDownlinkPing, to determine whether devices are functioning properly. If there is not ping response, an alert is sent to Slack.

Requirements

For this project, you will need the following:

• A Soracom account
• A registered IoT SIM
• A Slack account

If you don't already have a Soracom account or a registered SIM, follow the steps in the Quick Start guide.

Project Overview - Device Monitoring with Downlink Ping

This project leverages Soracom Flux to continuously monitor IoT devices using periodic ping requests. An Interval Timer channel triggers the scheduled execution of the Sim:sendDownlinkPing API, which sends ping requests to devices identified by their SIM IDs.

If a device fails to respond to these ping requests, indicating a potential issue or loss of connectivity, the system automatically triggers a Slack notification. This alert informs operators of the offline status, allowing them to take prompt remedial action. Overall, the solution provides an automated, low-code mechanism to ensure that your devices remain connected and operational.

Project Steps

Create a Flux App

A Flux App can integrate various forms of inputs and apply sophisticated business logic to achieve desired outcomes.

1. Login to the User Console. From the Menu, expand Soracom Flux and select Flux Apps.

2. Click Create a new Flux app.

3. Name the Flux app and provide an optional description, then click Create.

   The Flux app will be created and the Studio tab in Soracom Flux Studio will automatically be displayed.

---

Create a Channel

A channel is a Flux component that connects an event source to actions in your Flux app.

1. Open the Studio tab in Soracom Flux Studio:

   • If you have just created a Flux app, you will already be in the Studio tab.
   • If you are returning, follow Step 1 under Create a Flux App to access your Flux Apps, then select your app to open the Studio tab.

2. Click Create a channel.

3. Choose Interval Timer as the event source and click Next.

4. Configure the following:

   • Name: Name your channel.
   • Description: Optionally provide a summary of the channel.
   • Event source config:
     • Enabled: Set the channel to enabled.
     • Schedule Expression: Set the frequency and select a time unit.
       • Example: Every 1 Hours an event is ingested
     • Description: Optionally provide a description for the Interval Timer setting.

   

5. Click Create a new channel.

6. After confirming that your configuration is correct, click the to return to the Studio tab and see the new channel.

   

---

Create a Soracom API Action to Call the Sim:sendDownlinkPing API

An action is a component that can be added to a channel that can conditionally process information from an event source to execute a desired effect.

In this step, we will create a Soracom API action to call the Sim:sendDownlinkPing API.

1. Click on the channel created in the previous section to open the configuration dialog, then select the Actions tab and click Add Action.

   

2. In the Create a new action dialog, choose Soracom API as your action type, then click OK.

3. Configure the following:

   • Name: Enter an action name.
   • Description: Optionally provide a summary.
   • Enabled: Set the action to enabled.

   • Condition:

     • Action Condition: Define when the action should trigger.

       In this case, leave this field blank so that the action executes each time the Interval Timer calls it.

4. Configure the following in the Config section of the dialog:

   • API: Select an API from the searchable dropdown.

     For the purposes of this guide, select sendDownlinkPing.

   • URL: The URL /v1/sims/{sim_id}/downlink/ping is displayed, replace the placeholder {sim_id} with your SIM ID (e.g., 8942310000012345678).

   • HTTP Body: Enter the following in JSON.

     {
       "numberOfPingRequests": 3,
       "timeoutSeconds": 2
     }

     The example above configures 3 ping attempts, each with a timeout of 2 seconds. Please set the API values as necessary for your purposes.

   

5. Read the warning about API calls. If you're in agreement and ready to move on, click I understand the above and use this action to continue.

6. Choose Create a new SAM User or Select a SAM User for this action.

   For Create a new SAM User, use the automatically generated name or enter the user's name in the SAM User Name field. The permissions and Trust Policy for executing the selected API are automatically set and readily usable.

   For Select a SAM User, see the Soracom API Action documentation for more information.

7. Configure the following in the Output section of the dialog:

   Republish the action output to another channel: Set to Enabled to republish to another channel and set the following:

   • Destination Channel: Select Create a New Channel.
   • Channel Name: Enter a name (e.g., Output).

   

8. Click Create.

   The Soracom API Action will be created and you will be returned to the Actions tab on the channel details screen.

   You can view the settings of the SAM user by clicking the Soracom API action in the Studio tab, then clicking the link under SAM User.

   

9. After confirming that your configuration is correct, click the to return to the Studio tab and see the new channel.

Create a Slack Notification Action to Send Notifications to Slack

1. Click on the output channel created in the previous section.

   

2. Select the Actions tab and click the Add Action button.

3. Select Slack Notification as your action type, then click OK.

4. Configure the Slack Notification action:

   • Name: Name the Slack Notification action.
   • Description: Optionally provide a summary.
   • Enabled: Set the action to enabled.

   • Condition:

     • Action Condition: Define when the action should trigger.

       Set the action to execute when the Sim:sendDownlinkPing API fails its attempts to ping a device.

       Enter payload.success == false.

       

5. Configure the following in the Config section of the dialog:

   • URL: Enter the incoming webhook URL associated with the Slack channel you want to notify.

     For information on setting up a URL, refer to the official Slack Documentation.

   • Payload: Specify the message you want to receive on your Slack account.

     The data received by this channel is being referenced in the Payload field. In this case we are using ${payload.stat} to reference the Soracom API action's output.

     For example:

     There is no ping response from
     
     SIM ID: 8942310000012345678
     
     ${payload.stat}

6. Configure the following in the Output section of the dialog:

   • Republish this action output to another channel: Set republishing to Disabled.
7. Click Create.

---

Testing the Flux App

Confirm Sim:sendDownlinkPing API Execution on Target SIM

Verify that the device with the target SIM ID is able to respond when the Interval Timer event in your Flux App is triggered.

Confirm the status of your device. If the device is powered off or unable to respond to the ping at the time of execution, the Sim:sendDownlinkPing API call will return a status of false.

You can test if the setup is working by powering off the device, then running the app in order to see if you receive a Slack notification. If you receive a Slack notification, it verifies that your Action Condition, payload.success == false has been met.

---

Check the Execution History of the Flux App

1. Login to the User Console. From the Menu, expand Soracom Flux and select Flux Apps.

2. Click on the Flux app you created.

3. Select the History tab.

   For each channel, the Message, Context, Input, and Output of the action executed from that channel are displayed. For more information, see Execution History.