The Pytrack shield is a location enable version of the Pycom Expansion board module and purpose built for GPS applications such as asset tracking and asset monitoring. This shield can be used with any of your Pycom multi-network modules allowing you to expand your modules to incorporate GPS tracking over Sigfox, LoRa, Wi-Fi, Bluetooth and dual LTE-M

In this guide we introduce the Pycom Pytrack shield attached to a Pycom SiPy device. The SiPy is a multi-network (Sigfox, WiFi and BLE) development board. For more details, check out the SiPy fact sheet. or check out my other articles for connecting your Pycom SiPy to Ubidots over Sigfox.

Requirements

Pycom Pytack
Pycom SiPy
Sigfox Antenna kit
Cable micro-USB
Ubidots account -or- Educational License

Step-by-Step

Setting up Hardware
Setting up a Callback to send data to Ubidots
Programming you Pytrack with Pymakr

1. Setting up Hardware

Before beginning, make sure your board is programmed and updated fully and correctly:

If this is your first time working with a Pycom board, we recommend that you reference this geting started documentation to become familiar with the capabilities and specs of your new board.

Registering the SiPy with Sigfox

In order to send a Sigfox message, you need to register your SiPy with the Sigfox Backend. Navigate to https://backend.sigfox.com/activate and then select the Sigfox. Then select Pycom to proceed.

Next, you will need to choose the correct Sigfox Operator for the country in which you will be activating your SiPy. Find your country and select the operator to continue.

Then enter your Device ID and PAC number found on the Pycom Device

Once your device is registered in the Sigfox backend you can verify its existence in the Device section. Screenshot below for reference:

NOTE: Don't forget to connect the antenna to the board. If you do not, SIgfox will not be able to receive messages from your device!

2. Setting up a Callback to send data to Ubidots

The management of the data between Sigfox and Ubidots uses a "Callback". The Sigfox device will read the sensors and then send the values to Sigfox. Here the data will be decoded using the custom payload config then the data is relayed to Ubidots for visualization, storage, and computation.

Now it is time to set up the callback. Go to the Device section and click on your registered device:

Next, verify your device information and select "CALLBACKS" from the menu on the left of the page, as shown below:

Sigfox callbacks allow you to report data to an external system like Ubidots. Use the parameters below to send your data to Ubidots API.

Type: DATA - UPLINK
Channel: URL
Custom payload config: lat::float:32:little-endian lng::float:32:little-endian
URL pattern: https://industrial.api.ubidots.com/api/v1.6/devices/{device}
Use HTTP method: POST
Send SNI: Disable
Headers: x-auth-token - {your_ubidots_token}
Content Type: application/json
Body:

{
  "snr" : "{snr}",
  "avgSnr" : "{avgSnr}",
  "rssi" : "{rssi}",
  "position":{"value":1,"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. As developers, please code this section as you see fit.

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

Above where "int1" is the name of the value, "uint:8" specifies the datatype and the number of bits, respectively. To know 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.

To verify if the message is received at Sigfox go to the Device section, then select the device's ID:

Next, at the left menu select "message" to visualize the messages received:

Please note the "customData#..." from the body field will contain the actual sensor information, in the example shown as "lat"and "lng". If you desire to send more values, you have to assign it at the custom payload config, then assign it at the body following the same structure.

Following this guide, we configured two variables "lat" and "lng"as float; you can use any format desired but ensure that the device is sending values to Sigfox using the same format assigned by you in the custom payload config.

After configuring the callback, your Sigfox backend setup should look like this:

Once you can verify the callback, press "OK".

3. Programming you Pytrack with Pymakr

Setup the Pytrack with Pymakr Plugin - (Atom)

Pycom developed a series of tools known as the Pymakr Plugins allowing you to connect any programs with your Pycom device. If this is your first time wit Pymakr, please reference the Pycom official documentation and follow all the steps provided. Once finished with the "Initial Configuration", you will be able to communicate with your Pycom SiPy using the Pymakr Plugin.

1. Open the Atom editor, and activate the Pymakr plugin.

2. Connect the board with the Pymakr (Atom editor). Once the board is connected you will see the message "connected" in the status. Pycom devices can also be accessed using your console, as is shown below.

IMPORTANT NOTE: This plugin allow us connect the board via Serial USB REPL (UART) and via Telnet REPL. Based on our experience during the integration we recommend using Telnet.

FAQs and Troubleshooting: If the board is connected via Serial USB and you are not able to access to the board over the console, please connect it to the Pymakr by Telnet; see this guide for additional details for establishing a proper connection.

3. Create a new directory called "ubidots" to manage the codes and libraries. Once the directory is created, in the Atom editor select Open a Project, and search for the directory "ubidots," and open it.

4. In the file "ubidots" we are going to manage the libraries and main/boot codes. Please reference and follow the structure below to build your project properly:

> ubidots
  - boot.py
  - main.py
  > lib
    - L76GNSS.py
    - LIS2HH12.py
    - pytrack.py

First, we are going to add the folder for the libraries. Right click the folder "ubidots" and select "New folder", and assign "lib" as name.

Now, we're going to add the main and boot files:

Right click the folder "ubidots" and select "New File", assign "boot.py" as the name
Repeat the above steps to create the main called "main.py":

Once both files are created, the structure of your project will look as follows:

5. Lastly, we must add the Pytrack libraries files into the "lib" folder. Using the Pycom Repository download the Pytrack Libraries and store them in the "lib" folder. The final structure of your project will look as follows if executed correctly:

Now it is time to Code your Pytrack

1. Copy and paste the code below into the "boot.py" file:

from machine import UART
import machine
import os

uart = UART(0, baudrate=115200)
os.dupterm(uart)

machine.main('main.py')

Uploaded and save your code to the "boot.py" file.

2. Next, copy/paste and upload and save the code below into the "main.py" file:

from network import Sigfox
import socket
import struct
import time
from L76GNSS import L76GNSS
from pytrack import Pytrack

init_timer = time.time()

# Constructor
py = Pytrack()
l76 = L76GNSS(py, timeout=60)

# init Sigfox Zone for RCZ1
sigfox = Sigfox(mode=Sigfox.SIGFOX, rcz=Sigfox.RCZ4)

# create a Sigfox socket
s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)

# make the socket blocking
s.setblocking(True)

# configure it as DOWNLINK specified by 'True'
s.setsockopt(socket.SOL_SIGFOX, socket.SO_RX, False)

while(True):
    # time-counter configurations
    final_timer = time.time()
    diff = final_timer - init_timer
    # save the coordinates in a new variable
    coord = l76.coordinates()
    # verify the coordinates received
    if coord == (None,  None):
        print("Getting Location...")
        continue
    # time established to send the next Sigfox message
    # diff <= 900 takes 15 min approximately to send the next message
    if diff <= 900 and coord != (None, None):
        print("Waiting for send the next Sigfox message")
        continue
    # send the Coordinates to Sigfox
    s.send(struct.pack("<f",  float(coord[0]))+struct.pack("<f",  float(coord[1])))
    print("Coordinates sent -> lat: " + str(coord[0]) + ", lng: " + str(coord[1]))
    # reset the timer
    init_timer = final_timer

Save your code once you've uploaded to the "main.py" file.

3. Next, synchronize the project. Press the "Sync" icon from the console, or select Packages > Pymakr > Synchronize project.

NOTE: As you can see the last part of the "main.py" code the values are sent following the same format assigned at the custom payload config.

Code: s.send(struct.pack("<f", float(coord[0]))+struct.pack("<f", float(coord[1])))
Custom payload config (Sigfox): lat::float:32:little-endian lng::float:32:little-endian

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, reference this article from Ubidots Help Center.

4. Once the project is properly synchronized, you have to wait a couple of minutes in order to the GPS module catch the latitude and longitude. The code provided gives the GNSS module 60 seconds of timeout to catch the coordinates; if the device is not able to transmit the coordinates during the time specified you will received the message "Getting location..." once per minute until the device's location is received. Below is a typical example of this "Getting Location" experience.

5. Once the module is receiving coordinates properly it will take approximately 15 minutes to send the first Sigfox message. Once you've received the first coordinates into the console the message will also be available in Sigfox's backend and then to Ubidots for your application's required implementation.

Data to the Sigfox backend:

Data displayed in Ubidots:

This sample code uploads data every 15 minutes to keep data costs down. If you desire incremental times of more/less than 15 minutes using the limit of the diff conditional to adjust the sending rate.

if diff <= (limit) and coord != (None, None):

4. Summary

Through this guide we made a simple GPS tracer using Sigfox. Beyond device tracking, the Pytrack has many other features beyond the GPS to maximize your applications efficiency.

If you desire to learn how to manage Uplink & Downlink messages, by using Sigfox Callbacks and UbiFunction Egnine, refer to the guides below:

Now it is time to create a dashboard to control and manage the variables of your Pycom device. To learn more about Ubidots widgets and events, check out these helpful video tutorials.