What if you had to store something precious to be picked up by someone you do not know? What if you were far away from the box and had to change the password for security reasons?
This is where Sigfox comes in! Indeed, Sigfox allows you to use 4 downlink messages per day. The idea is to be able to update the password controlling the opening of the box. Therefore in this tutorial, every 6 hours (4 times per day), the box's password will be set with a newly generated one from a web application. The owner can then decide to share the password to whom he wants. He will also be notified every time the box is opened!
This repository includes:
- the firmware to upload on the MKRFox1200
- the web API generating a new password and receiving the box's notifications
Some photos showing how the mechanical part works:
π Opened state:
π Locked state:
Making the box:
Below is a diagram showing how the global system works:
- an MKRFox1200 board
- a buzzer
- an RGB led
- 2x AA batteries or equivalent (in this tutorial I use a 3.7 Li-Ion battery)
- some jumper wires and a breadboard
- a box with a lock system
Start by cloning the repo: git clone https://github.com/AntoinedeChassey/MKRFox1200_lock_box
- Flash the MKRFox1200 with the firmware located in this folder: MKRFox1200_lock_box/MKRFox1200/src (I used PlatformIO a new great IDE for IoT. After being installed on Atom, the folder "MKRFox1200" can be imported with
File>Open Folder...>Select
and the project will be configured automatically with the Arduino core and libraries - defined in the fileplatformio.ini
)
- Make sure to respect the correct pin mapping (check
Defines & variables
in the code)
Some informations regarding the data frames being sent from the MKRFox1200 to the Sigfox Backend (12 bytes maximum):
getPasswordBySigfox()
sends the following:
Byte: 1 -> 6 & 7 -> 10
Type: char & float - Little Endian
Content: "UPDATE" & Estimated battery voltage
sendAlertBySigfox()
sends the following:
Byte: 1 -> 4 & 5 -> 8
Type: char & float - Little Endian
Content: "OPEN" & Estimated battery voltage
You can help yourself with this website to decode hexadecimal (the battery voltage is a Float - Little Endian (DCBA)
).
FYI: the estimated battery voltage is only indicating a very rough approximation. It is not a reliable piece of information at all but it will help you get an idea. A better approximation would be made with a 5V battery using the following formula: float voltage = sensorValue * (5 / 1023)
In this tutorial we will use Flask to build our little API. Flask is a microframework for Python which simplifies the creation of web applications. ngrok will be used to expose it through an online tunnel, this means it will be deployed on YOUR computer for simplicity purposes. Of course, you can decide to deploy it on a private server or PaaS (Platform as a Service) if you wish (this is not presented in this tutorial in order to keep it as short as possible).
Please keep in mind Python with Flask can be substituted with any other kind of web application created with a totally different programming language! π
- Edit the "app.py" script (in folder MKRFox1200_access_control/API/)
- Set the
deviceId
variable with your own MKRFox1200 device ID (you can find it when you actived your board or on the Sigfox Backend)
- Install the Flask module with pip (Linux commands):
$ sudo apt-get update && sudo apt-get -y upgrade
$ sudo apt-get install python-pip3
$ pip3 install flask
- Launch the Python script (on windows, if a PATH environment variable has not been created, the Python executable must be accessible from
C:\Users\USERNAME\AppData\Local\Programs\Python\Python36-32\python.exe
):
$ cd MKRFox1200_access_control/API/
$ python app.py
If everything went fine, you must be able to access http://localhost:5000/ and see a result in your browser. There is an endpoint configured to generate a new password when calling http://localhost:5000/getPassword. This will also be used for the Sigfox Backend Callback configuration.
Now we'll take a look at ngrok as a method of exposing your Python server publicly so that the Sigfox Backend can GET/POST data to it. This is particularly useful for testing purposes as we do not have to spend time on server configurations.
- Install ngrok from here
- Launch ngrok on port 5000:
$ ngrok http 5000
- This will expose your server publicly (on port 5000). To double check that this has worked, copy the address that has appeared in your terminal window under "forwarding" and navigate to it using your browser; it should look something like below. Make note of this as we'll need it below!
- Log in here
- Go to https://backend.sigfox.com/devicetype/list, click left on your device row and select "Edit"
- Under "Downlink data", select the
CALLBACK
"Downlink mode"
- Now go to the "CALLBACKS" section on the left, select "new" on the top right, select "Custom Callback"
- Type:
DATA
|BIDIR
- Channel
URL
- Url pattern:
http://<YOUR_ngrok_SERVER_ADDRESS>/getPassword
- Use HTTP Method:
POST
- Content Type:
application/json
- Body: (this will be sent to the API)
{
"device" : "{device}",
"time" : "{time}",
"duplicate" : "{duplicate}",
"snr" : "{snr}",
"rssi" : "{rssi}",
"avgSnr" : "{avgSnr}",
"station" : "{station}",
"lat" : "{lat}",
"lng" : "{lng}",
"seqNumber" : "{seqNumber}",
"data" : "{data}"
}
- Select "OK" to validate
- Tick the "Downlink" button to activate the newly created callback, make sure it looks like below
- Power up the system
- The default password is
2017
- The buffer storing the input (keys pressed) is 4 characters long
- This buffer is emptied every 3 seconds and the timer emptying it is paused every time there is a new key being pressed
- Press
*
to reset the input or lock the box
- For debug purposes, you can press
#
to reset the password to its default (2017)
- A new generated password will be set every 6h by default, see:
const long interval = 1000 * 60 * 60 * 6
(this means a downlink will be asked every 6h = 4 per day to the Sigfox Backend, this respects the ETSI Standards)
- The new password will be stored in the MKRFox1200 flash memory (this means that if you reboot the board, the default password (2017) is set again)
- The new password is accessible on the ngrok Python API (home page - http://localhost:5000/)
- Each time the correct password is entered, the message "OPEN" is sent to the Sigfox Backend so the owner can be notified it has been opened by someone (this takes 6 seconds)
- add multi-tasking to allow asynchronous jobs
- put the board in deepsleep when not in use to preserve battery consumption
Have fun and always keep your keys safe! π π
Antoine de Chassey
Comments