This project allows you to set up remote alerts from your IoT device when your environment exceeds certain thresholds.
We use the Arduino MKR NB 1500 and IMU Shield on Telstra’s Cat-M1 network to alert when acceleration on the z axis is high (inferring a falling device!). This can be used in various examples that rely on instant alerts from falling objects (or people).
The following Arduino sketch posts sensor data from the board as a json string to our Watson IoT broker. A nodered flow takes in requests from that broker, pulling the sensor data as global variables. If the incoming data exceeds a pre-determined threshold, (i.e acceleration is >2 Gs) it will trigger an SMS alert. This SMS is sent via the TelstraDev Messaging API.
See the over all flow architecture: https://github.com/MichelleHowie/Arduino-MKR-IMU-Fall-Detect/blob/main/health%20hack%20demo%20flow.jpg
This workshop was created by DeveloperSteve Coochin and Michelle Howie for Telstra Health Hack For Digital Healthcare in November 2020 as part 3 of a series in IBM and TelstraDev IoT workshops. Video of this workshop available here: https://www.youtube.com/watch?v=UebmjYumGoQ&feature=youtu.be&ab_channel=TelstraHealth
Using the NB IOT network with a Telstra SIM, the MKR NB 1500 can be contacted from almost anywhere in Australia. You can send the data requests remotely.
For part 1 of this workshop, learn how to set up your Messaging API with node red and program the Arduino board. See the video recap of this tutorial recorded at IBM’s Call For Code May 2020 Hackathon: https://video.ibm.com/recorded/126684032
In part 2 of this workshop, we connected the MKR Environmental Sensor Shield and created a node red flow that allowed users to send in an SMS to poll for live sensor data on demand. See the video recap of this tutorial recorded at IBM’s Call For Code June 2020 Hackathon: https://video.ibm.com/channel/23832688/video/cfc2020-telstradev-iotworkshop Repo available here: https://github.com/MichelleHowie/IoTSensorData_OnDemand
To set-up your board, and connect to the NB IoT cellular network, Follow the Arduino MKR NB 1500 Get Started Guide on TelstraDev IoT Marketplace Make sure you have downloaded the Arduino libraries for the MKRNB, MKRIMU and MKRENV.
Login to IBM Cloud
go to catalogue and find the IoT platform: https://cloud.ibm.com/catalog/services/internet-of-things-platform
create a lite (free) plan
go to devices and 'add device'
enter a meaningful device type (e.g "arduinomkr")
enter a meaningful name (e.g "mydevice1")
all the other fields are optional
select 'Finish'
STOP! make sure you copy all the text on this page: ORG, DEVICE TYPE, DEVICE, AUTH METHOD, AUTH TOKEN IMPORTANT! you will not have access to the token again. save this somewhere you can access it. If you lose your device token, you will need to add a new device and start again.
you then need to create a new app from the left screen toolbar. Generate API Key
save your api key and token. they will be needed in your node red instance
change the role of this app to be backend trusted app
Go to https://nodered.org/
Get started with NodeRed here: https://developer.ibm.com/components/node-red/gettingstarted/
If you have an Openshift account, you can run an instance in IBM cloud, You can select a local instance of nodered.
Import the nodered flow in json we have pre-prepared: https://github.com/MichelleHowie/IoTSensorData_OnDemand/blob/master/IoTSensorData_OnDemand%20rode%20red%20flows%20(without%20client%20creds).json
We split the nodered flow into 4 parts (plus one introduction) to simplify. Click the link below to see a screenshot schematic of each:
-
NodeRed Flow 1 - Prov & B-Num.JPG is required to provision your TelstraDev Messaging API subscription with the NotifyURL
-
NodeRed Flow 2 - Request ENV Details.JPG This is from part 2 of this workshop where we took the data from our Environmental Shield and send it in a reply to any texts that come in matching specific data. It creates the body of the message to be replied to based on the SMS incoming request (msg.smsout.body), as well as taking the sender mobile and adding it to our destination number (msg.smsout.to). Both these variables are used in the Send SMS Flow You can skip this, or head to part 2 of this demo to understand more.
-
NodeRed Flow 3 - Device Alerts.JPG this is the key logic of our fall detection demo. When our Arduino device with the sketch running outputs an event to our IoT broker (after the acceleration exceeds our thresholds to infer a fall) then this flow is triggered. It simply triggers an SMS to be send to our pre-defined contacts with a standard message body "A device has had a fall". You can customise this message.
-
NodeRed Flow 4 - Send SMS.JPG This flow makes sure we have a valid OAuth token to use the TelstraDev Messaging API, then takes the SMS output (msg.smsout.body) and the destination number (msg.smsout.to) from either the Device Alerts flow or the Request ENV Details, whichever is triggered, and sends the SMS.
Once you have imported the NodeRed flow, create your notifyURL to be used as a webhook to receive inbound SMS to our virtual mobile number. For this project, the notifyURL is based off of your nodered URL. Take the start of the URL in your nodered browser, remove everything after the '.net' and add the identifier for your node that will receive the message and take action (in this case it is the 'SMS in' http endpoint node in the 'Request Env details' tab): e.g ['notify_url'] = "https://your-stack.mybluemix.net/sms"; Take note of this notifyURL as you will need this when provisioning your Messaging API mobile number below
There are a few places where you will need to update our imported nodered flow with your own credentials: - In the Watson IoT nodes, replace 'INSERT_HERE' under Server Name, API Key and API Token with your valid IBM Cloud credentials (see previous step) - In the "Get a Token" node, replace 'INSERT_HERE' under Client Secret and CLient ID with your valid TelstraDev Messaging API client credentials (see next step) - In the "Prep SMS" and "B-Num reg" nodes, replace 'INSERT_HERE' with your mobile number that you want to receive the SMS alerts to. - In the "Prov Number" node, replace 'INSERT_HERE' with your NotifyURL.
Register your free developer account at https://dev.telstra.com.
Login and navigate to the My apps page.
Create your application by clicking the 'Add new app' button
Select API Free Trial Product when configuring your application. This Product includes the Telstra Messaging API as well as other free trial APIs. Your application will be approved automatically. There is a maximum of 100 free messages per developer. Additional messages and features can be purchased by creating a company and adding billing details.
Note your Client key and Client secret as these will be needed to provision a number for your application and for authentication (see NodeRed "Get a Token" node).
Now head over to Getting Started where you can find a postman collection as well as some links to sample apps and SDKs to get you started.
Download the MessagingAPI-SDK in the language of your choice from https://github.com/telstra and follow the steps to:
-
Get an OAuth Token
-
Provision your Virtual Mobile Number Subscriptions (define the NotifyURL endpoint in this call). Note the new subscription mobile number / MSISDN (e.g 61412345678) in the API call response. This is your virtual number
-
Send an SMS from your new virtual number
The notifyURL in the Provisoning call will be the URL where replies to the provisioned number will be posted Telstra will deliver messages sent to that dedicated number to the notifyURL defined by you. The notifyURL should be a complete URL address which includes the protocol identifier (e.g. https://). It should also have a forward slash at the end if it is just a domain (e.g. http://www.example.com/).
If that NotifyURL is the correct nodered http in endpoint, you should see the message payload of any inbound messages to your number appear in nodered 'SMS in' node it’s then matched to the possible requests for sensor data (temp, UV, humidity, light) the most recent sensor data is pulled every 30 seconds from watson IoT and stored in the nodered global variables. The matched word + the matching global variables + time of latest data from sensors + information from the inbound text ('from' address) make up the response to send an SMS reply using another http request (i.e another call to the TelstraDev Messaging API Gateway)
BEFORE Deploying the NodeRed flow, make sure you have provisioned a mobile number with the TelstraDev Messaging API with a NotifyURL. If you are using the free trial, you will also need to register your b-numbers that will receive the SMS alerts.
We’ve added a tab in the node red flow to provision the subscription and register bnumbers, or you can do this in postman using our collections.
Download the .ino Arduino sketch from this repo and open in your Arduino IDE.
Add your secrets from the Waston IoT platform (token, org, device name, device type).
Carefully connect your IMU sensor shield by aligning the pins to the MKR NB 1500 board.
Upload the code contained in this sketch on to your board
Deploy the NodeRed Flow
When your device moves suddenly, the acceleration in Gs will increase. Give it a go by moving it up or down lightly. Then you should get a text with the pre-defined text.
This is just a proof of concept for sending automated alerts based on change in acceleration of our remote device. We did not consider the direction of acceleration or fine-tune the thresholds to differentiate between a fall and the device being picked up for example. If you would like a more functional result with better accuracy to deploy in real fall detection scenarios, please spend the time to fine-tune the paramaters. But we hope this gives you a good start!
NodeRed Flows => Folder containgin things for NodeRed Flows ├── Arduino MKR IMU Fall Detect flows (no creds).json => (optional) pre-loaded nodered flow you can import ├── NodeRed Flow 1 - Prov & B-Num.JPG ... etc => (optional) screenshots of pre-loaded nodered flow you can import ├── Arduino-MKR-IMU-Fall-Detect.ino => (optional) pre-loaded nodered flow you can import ├── mkr imu fall detect demo flow.jpg => schematic of the final working demo └── ReadMe.adoc => this file
To contribute to this project please contact michelle2minhye https://id.arduino.cc/michelle2minhye
This document is written in the AsciiDoc format, a markup language to describe documents. If you need help you can search the AsciiDoc homepage or consult the AsciiDoc cheatsheet