The mc-Demo205 is a powerful IoT device, which combines SIGFOX™, GNSS, and the new mcAir protocol into one device. Have a closer look at mc-Demo205 promo video below, or the mcDemo fact sheet for extra device specs.
Following this guide you will be able to get start with your mc-Demo205 and Ubidots in just a couple of minutes, so let's get started!
Requierements
mc-Demo205, mcThings device
mc-Dongle, mcThings device
Latest Firmware for the mcDemo Device
Before beginning your IoT applications using the mcDemo205’s always best to make sure you have the latest firmware updated. Follow this Getting Started guide to ensure your device is up-to-speed.
1. Registering the mcDemo205 in the Sigfox backend
In order to activate your mcDemo we need to establish the device with the Sigfox network. For this, you need the Sigfox ID (device ID) and the Sigfox PAC printed clearly on your mcDemo205 unit.
IMPORTANT NOTE: This mcDemo205 does not include a SIGFOX™ Network Subscription. For more information visit SIGFOX™ online to purchase your subscription.
Follow the steps below to activate the module:
Go to the Sigfox's activation portal for the mcThings devices.
Select the country of your device's location and add the Sigfox ID (device ID) and the Sigfox PAC where is indicated.
To confirm your device is registered - select the "Device Type" section from the Sigfox backend to find your device.
Pro Tip: Instead of activating through the kit page, you can go to "Devices" section, then press "new" to create a new device. From here, assign the parameters required such as Device ID, PAC, and the account information.
FAQs and Troubleshooting: If you receive any issue during the activation process, contact Sigfox Support, and a specialist will assist you through the configuration process.
2. Setting up the Sigfox callback to the Ubidots Cloud
The management of the data between Sigfox and Ubidots requires a "Callback". The mcDemo device will read the sensors and send the values to Sigfox where the messages will be decoded using the custom payload config and then relayed to Ubidots for visualization, computation, and storage.
Now it's time to set up the callback.
Go to the Device section and click on the registered device:
Next, verify your device information and select "CALLBACKS" from the menu on the left of the page, as you can see below:
Sigfox callbacks allow you to report data to an external system like Ubidots. To setup a callback to Ubidots API, use these parameters:
Type:
DATA-UPLINKChannel:
URLCustom payload config:
lat::float:32:little-endian lng::float:32:little-endian
URL pattern:
https://things.ubidots.com/api/v1.6/devices/{device}Use HTTP method:
POSTSend SNI:
DisableHeaders:
x-auth-token-{your_ubidots_token}Content Type:
application/jsonBody:
{
"snr" : "{snr}",
"avgSnr" : "{avgSnr}",
"rssi" : "{rssi}",
"position":{"value":0,"context":{"lat":"{customData#lat}","lng":"{customData#lng}"}}
}IMPORTANT NOTE: The field "custom payload config" allows you to specify how you would like Sigfox to decode your device's payload. You might, for example, wish to decode an incoming byte as an unsigned integer. An example of this is the first line of the sample below where "int1" is the name of the value and "uint:8" specifies the datatype and the number of bits, respectively.
int1::uint:8 // Unsigned integer of 8 bits with name int1
str::char:6 // Character String of 6 letters with name str
b1::bool:7 // Boolean based on value of bit in position 7 with name b1
To learn more about how to build the custom payload config, please reference to the Sigfox documentation by pressing the question icon in the upper right of the displayed page.
IMPORTANT DEPLOYMENT NOTE: Ubidots and Sigfox communicate via either URL or Batch URL (used for large deployments). This tutorial explains the standard URL channel. If you have a large scale sensor network, please contact support@ubidots.com to receive additional information for Batch URL integrations.
The Sigfox payload will decode the message and then relay the data to Ubidots via the callback. Note that you must set the same format for your device's code as what is in Sigfox and if not, the data will not be received by Sigfox. To verify if the message is received by Sigfox go to the Device section, then select the device's ID:
To verify the data is being received, click "message" from the left-hand pane to visualize the messages received:
Please note the "customData#..." from the body field will contain the actual location information. In this example we will see "lat" and "lng". If you desire to send more values, you must to assign these data points as part of the custom payload config, then assign it at the body following the same structure.
Within this guide, we configured two variables "lat" and "lng" as float values; You can use any format that you desire but please note that the device has to send the values using the same format assigned by you at the custom payload config. And this payload must also match the code uploaded to the device.
3. Completed Sigfox Backend Setup
After configuring the callback, your Sigfox backend setup should look like this:
Once you verify the callback, press "OK". Now your callback is ready and enabled to post data o the Ubidots Cloud.
4. Setting up the mcStudio project
Now that your Sigfox callback configured it's time to setup the mcStudio to program your device. Please ensure you have completed the mcThings getting started prior to attempting to code your mcDemo205.
1. Open the mcStudio IDE
2. Create a new project – Select File > New Project
Next, assign "ubidotsGPS" as the Project Name, then assign the location where you want to save the project. Make sure you assign the mcDemo205 as the Device Type, and then press "Ok". The image below serves as a guide:
Once the project is properly created, you will see the name of the project at the top of the mcStudio IDE.
3. Establish the connection between the mcDemo205 and the mcStudio. For this, please reference to the following mcThings guide and follow all the steps mentioned. Once the mcDemo205 is properly connected you will see the UID of the device appear at the top of your Title Bar.
4. We built the below sample code to send a message to Sigfox containing the coordinates of the device every time the "SW1" button is pressed.
In order to test this sample code erase the class assigned when you created the project and copy/save the code below:
IMPORTANT NOTE: Make sure to assign the proper Sigfox radio zone for your country.
Class ubidotsGPS
' Message Types
Const MSGTYPE_LOCATION As Byte = 1
' Configuration Constants
Const GPS_TIMEOUT_uS As Integer = 120000000 '120 second timeout
Const GPS_MIN_SAT_COUNT As Integer = 3 'minimum satellites to get a fix
Shared Event Boot()
' Set Sigfox radio zone to US
'Lplan.SigfoxRadioZone(SigfoxRadioZone.US)
' Set Sigfox radio zone to Australia
Lplan.SigfoxRadioZone(SigfoxRadioZone.Australia)
End Event
' Initiate GNSS acquisition on Button 1 press
Shared Event SW1FallingEdge()
' Turn on LED2 to indicate GNSS acquisition started
Led2 = True
Device.StartGPS(GPS_TIMEOUT_uS, GPS_MIN_SAT_COUNT)
End Event
' Called when GNSS location aquired or timeout occurred
Shared Event LocationDelivery()
' Get latitude
Dim Lat As Float = Device.GetLatitude()
' Get longitude
Dim Lng As Float = Device.GetLongitude()
' Get GNSS fix time
Dim timeIntUs As Integer = Device.GetGpsFixTime()
' Create Sigfox list of byte
Dim sigfoxMsg As ListOfByte = New ListOfByte()
'Dim timeIntSec As Float = timeIntUs / 1000000
'Dim timeShortSec As Short = timeIntSec.ToShort
' Verify if the lat and lng were properly obtained
If Lat.IsNaN() Then
Lat = 0.0
End If
If Lng.IsNaN() Then
Lng = 0.0
End If
' Add data to Sigfox message
sigfoxMsg.AddFloat(Lat)
sigfoxMsg.AddFloat(Lng)
'sigfoxMsg.AddByte(GetTemperature())
If Lat <> 0.0 Then
' Send Sigfox Message
Lplan.Sigfox(sigfoxMsg)
' Turn off LED2 to indicate Sigfox transmission complete
Led2 = False
End If
End Event
End Class
Upload the code into the mcDemo205
The mcStudio allows you run the code in a debug mode for testing propose, if needed. Run a test of your code by pressing the "Run" icon located at the top-right of the IDE toolbar.
As you can see below, the project is running. If you desire to make an additional modification in the code after "running" the code remember to stop the debug mode before editing the code.
1. With you code verified as debugged, you now need to Build the Application by pressing the hammer icon. Building your application allows you to first compile the application then generates the listing mode.
Next, press the icon located at the right of the hammer icon to Load and Save the program to the device:
2. Power off the mcDemo205 and wait a couple of seconds, then reboot your mcDemo. With the code is properly uploaded into the mcDemo205, press the button "SW1" to start receiving GPS location. This may take up to 120 seconds to receive the first GPS location depending on your converge. Once the GPS location is received, you can see the message received in the messages section in the Sigfox backend and then to Ubidots where you data is visualized, computed, and stored.
IMPORTANT NOTE: To be able to receive a GPS location, make sure you have no building interference (estimated 20 meter away) and you have to have the antenna pointing to the sky; the antenna is the yellow/white block above the Sigfox and mcThings logo:
DEPLOYMENT NOTE: We setup the LED2 of the mcDemo205 in order to verify the behavior of the device. Once the SW1 button is pressed, the LED2 will be turned on until the GPS location is properly received. Once the GPS location is received the data will be sent to Sigfox and the LED2 will turned off.
3. Once you have received the first coordinates and the LED2 has turned OFF, the Sigfox message will be send to the Sigfox backend, and then relayed to Ubidots for display. To visualize the device created in the Ubidots go to the Device section of your Ubidots account where you device and GPS location are automatically created and updated.
Please note that the "Device API Label" will be the same as the Sigfox {device} field.
If you desire to change you device and variable names to a more friendly one, please reference this article below.
Result
Using this guide we made a simple GPS tracker over Sigfox to track assets in and across different countries at an affordable price. The mcDemo205 has other features besides GPS; to maximize your device's capabilities and your IoT application, take a look at the mcDemo205 Product factsheet.
For additional questions and answers about your mcDemo205 or an intended project, check out the mcThings forum.
Now it is time to create a dashboard to control and manage the variables of your mcDemo205 device. To learn more about Ubidots widgets and events, check out these video tutorials.
Happy hacking! :)