The Notecard is a device-to-cloud data pump that simplifies adding IoT devices to a network via LoRa, with an easy-to-use API. It mounts onto the Notecarrier, a development board that enables quick prototyping and is essential for interfacing the Notecard to sensors. In this simple application, the Notecard + Notecarrier offer a quick way to prototyping and developing a full product, that, when combined with Ubidots, provides a full monitoring application.
Requirements
An active Blues Notehub account.
An active The Things Network account.
A Blues indoor LoRaWAN gateway or any other gateway.
Either a Notecarrier F or Notecarrier B.
1. Configure a Gateway in The Things Stack
You'll need a gateway connected to The Things Stack in order for this integration to work. It can be either a Blues LoRa gateway or any other brand/model. You can follow Blues' guide for this purpose.
2. Setting up the hardware and checking the USB connection
Make sure to attach the antenna to the Notecard LoRa and then hook it up to your Notecarrier. Finally, use a USB cable to connect the Notecarrier to your PC.
Next, go to Blues Notecard LoRa Quickstart. There, you'll be able to use Blues' in-browser terminal for communicating with the Blues board:
Click on the button located at the upper right corner of the screen, then click on the USB Notecard button, and then select your device:
Pro tip: If you are using Linux and experiencing connection issues, try installing libusb-1.0.0-dev. If you're on Windows and unable to connect, you may need to install the CP210x drivers from SILabs.
Once connected, run the following command to check if the serial connection with the device is working properly:
{"req" : "card.version" }
If you get a JSON containing the device's data, that means the configuration was done properly and you can proceed to the next section; otherwise, make sure that your USB cable is not a power-only cable, that the connections between the boards is correct, and that the dependencies listed in the "pro tip" above are installed.
3. Configure the Notecard
You'll need to define the object or structure of the data of your interest in order to let the Notecard know how to interpret the data. Suppose, for example, that you are interested in measuring temperature and humidity. In that case, you could have the data in an object as follows:
{
"temp":34.1,
"humid":50
}
Copy and paste the following command in the in-browser terminal to configure such data structure:
{
"req":"note.template",
"file":"data.qo",
"port":1,
"format":"compact",
"body":{
"temp":14.1,
"humid":14.1
}
}
After doing so, you'll get an output like the following in the Blues' terminal:
If you are planing on using a JSON schema different than this, just replace it under the body key of the command provided above.
4. Create a Notehub project and associate the Notecard to it
Log in to Notehub and create a new project. After doing this, the ProductUID for this project will be displayed; copy it:
Head back to the in-browser serial terminal and run the following command, just make sure you paste your ProductUID in it (instead of "<productUID>"):
{"req":"hub.set", "product": <productUID> }
The command above is to link the hardware to the created project on Notehub.
The next step is to perform a synchronization between the Notecard and Notehub. Run the following command:
{"req":"hub.sync"}
After doing that, you should be able to see your device added to the project:
Now that the device is associated to the project, let's simulate a data transmission. To do this, run the following command:
{"req":"note.add","file":"data.qo","body":{"temp":35.5,"humid":56.23}}
Now head to the Events section within Notehub. There, you'll be able to see the data sent from the Notecard to Notehub:
5. Route the data to Ubidots
The next step is to route the data from Notehub to Ubidots. Go to your Ubidots account, click on Devices → Functions and create a new UbiFunction with the following parameters:
Name: Enter a name for the UbiFunction.
Method: POST.
Runtime: For this example, Python 3.11 was chosen, however, you can select the one you prefer.
Token: Select the Ubidots token that you want to use for this particular application.
After creating the UbiFunction, copy its HTTPS endpoint URL. Don't worry about the UbiFunction's code for the moment.
Now, head back to your Notehub project and click on the Routes tab:
From there, create a new General HTTP/HTTPS Requests/Response route.
Configure the required fields of the General HTTP/HTTPS Requests/Response route as follows:
Route name: Choose any name.
URL: Paste the UbiFunction's HTTPS endpoint URL here.
HTTP Headers drop-down menu: Select the "additional headers" option.
Header: Type X-Auth-Token here.
Header value: The Ubidots token you previously used in the UbiFunction's configuration.
After that, click the Create Route button in order to save these settings.
Now, head back to the UbiFunction and, there, replace all the code with the following:
import requests
import time
BASE_URL = "https://industrial.api.ubidots.com"
REQUESTS_FUNCTIONS = {"get": requests.get, "post": requests.post}
def main(args):
# Print Args for debugging.
print(args)
# Get the device label -> Use the devId as device label
device_label: str = args.get('device', 'dev:').split(':')[-1] or None
# Get the payload
payload: dict = args.get('body', None)
# Get the selected Ubidots token for making the request
token: str = args.get('token', None)
if device_label == '' or device_label is None:
print('No device label')
return {"[ERROR]" : "No device label received"}
if payload is None:
print('No payload received.')
return {"[ERROR]" : "No payload received."}
if token is None:
print('No Ubidots Token received.')
return {"[ERROR]" : "No Ubidots Token received."}
# Send the data to a device
req = update_device(device_label, payload, token)
print("[INFO] Request result:")
print(req.text)
return {"status": "Ok", "result": req.json()}
def update_device(device, payload, token):
"""
updates a variable with a single dot
"""
url = "{}/api/v1.6/devices/{}".format(BASE_URL, device)
headers = {"X-Auth-Token": token, "Content-Type": "application/json"}
req = create_request(url, headers, payload, attempts=5, request_type="post")
return req
def create_request(url, headers, data, attempts, request_type):
"""
Function to create a request to the server
"""
request_func = REQUESTS_FUNCTIONS.get(request_type)
kwargs = {"url": url, "headers": headers}
if request_type == "post":
kwargs["json"] = data
try:
req = request_func(**kwargs)
print("[INFO] Request result: {}".format(req.text))
status_code = req.status_code
time.sleep(1)
while status_code >= 400 and attempts < 5:
req = request_func(**kwargs)
print("[INFO] Request result: {}".format(req.text))
status_code = req.status_code
attempts += 1
time.sleep(1)
return req
except Exception as e:
print("[ERROR] There was an error with the request, details:")
print(e)
return None
With this setup, every time the Notecard delivers data to Notehub, it'll be automatically re-routed to a device in Ubidots.
The device will appear in Ubidots with the device's devUID as its label:
