Asset Tracking

One of the most common and valuable use cases for IoT is asset tracking. Whether for a vehicle, trailer, or shipping container, asset tracking is a powerful way for developers and companies to understand where an asset has been, where it is, and where it’s headed, all while monitoring the conditions of the asset itself.

The Notecard contains in its package nearly everything you need to build a cellular-powered asset tracker. This guide provides instructions for configuring your Notecard as a standalone asset tracker as well as an MCU host-controlled tracker.

What You Need to Get Started

This guide provides instructions for using the Notecard as both a standalone tracker, and with an MCU host. For both approaches, you’ll need the following:

• A Notecard.
• A Notecarrier with Cellular and GPS/GNSS antennas, and battery support. The Notecarrier-AL and Notecarrier-AF have both antennas on-board, and provide a connector for a LiPo battery. The Notecarrier-AA also has both antennas and a battery case for three AA batteries.
• A USB 2.0 mini cable.

If you’re building a standalone Notecard tracker, you’ll need the following:

• The Notecard CLI for configuring the Notecard.

If you’re building a host-driven tracker, you’ll need the following:

• A microcontroller or single-board computer for communicating with the Notecard. The code samples in this guide target the ESP32 Feather running Arduino code, but can easily be adapted for your board of choice.
• [Optional] An external sensor for gathering additional information about your asset. This guide uses a Bosch BME680 temperature and humidity sensor.
• A text-editor for writing firmware, such as the Arduino IDE or VS Code.

Tracker Configuration Requests

To configure your Notecard as a tracker, you’ll need to do the following:

• Perform a factory restore on the Notecard. This step is optional, but recommended as card.restore will perform a factory reset on the Notecard and clear out Notes and Notefiles from previous applications. Setting "delete":true will also clear out all configuration settings.

COPY
{"req":"card.restore","delete":true}

• Set a Product UID, mode, and sync times with hub.set. periodic is recommended for cases where your tracker will need to operate on battery power for long-periods of time. The outbound and inbound fields specify the interval, in minutes, that the Notecard should process outbound and inbound requests. These values also affect battery life, so use a value that makes sense for your application’s power and data sync needs. The Notecard will only sync on the outbound interval if un-synced tracking information is available, but will always sync on the inbound interval in order to process new Notes and environment variables from Notehub.

COPY
{
  "req":      "hub.set",
  "product":  "com.veritas.delivery-fleet.tracker",
  "mode":     "periodic",
  "outbound": 60,
  "inbound":  720
}

• Set the Notecard to use periodic or continuous location mode. periodic is recommended for battery-powered applications, and continuous for cases where low-latency location tracking is needed and power consumption is not a concern. When using periodic, the seconds field defines the interval at which to activate GPS and capture a location sample. Note: When in periodic mode, the GPS module will only activate to take a reading if the Notecard detects movement through its onboard accelerometer between interval periods.

COPY
{
  "req":     "card.location.mode",
  "mode":    "periodic",
  "seconds": 3600
}

• Configure the Notecard to store tracking results in a tracking file that will be synced to Notehub, and set a heartbeat to check-in even if the device has not moved. card.location.track will store location-tagged tracking data like velocity, bearing, and distance in a Notefile that will be sent to Notehub on each sync. The default file is _track.qo, but you can specify your own with the file field. If you expect that your asset may be stationary for long periods of time , you can use heartbeat and hours to instruct the Notecard to create a tracking entry at a defined interval, regardless of motion. The Notecard does not switch on the GPS for heartbeats, since no movement has occurred. However the heartbeat provides confirmation that the Notecard tracker is still functioning correctly.

COPY
{
  "req":       "card.location.track",
  "start":     true,
  "heartbeat": true,
  "hours":     12
}

Once these requests have been sent to the Notecard, your tracker is ready to be deployed. The following two sections provide the specific steps for sending these requests for a standalone or host-controlled tracker.

note

The above commands will only work if the Notecard accelerometer is enabled. The {"req":"card.restore","delete":true} request enables the accelerometer, or it can be enabled with the following request if previously disabled.

COPY
{"req":"card.motion.mode","start":true}

Configure a Standalone Tracker

There are times where you simply want to track the location of your Notecard-connected asset and don’t need to gather data from an external sensor, or control how and when your Notecard should track and sync after deployment. In these cases, you can configure your Notecard as a standalone tracker by issuing a few requests from a connected computer, connect a battery and deploy it to the asset to be tracked.

The fastest way to configure the Notecard in this way is with the Notecard CLI, which allows you to connect to a Notecard over USB Serial and issue requests. The requests above can be sent individually using the req or play flag, or you can place all of the requests into a file with a json extension and use the setup flag to send them all at once. This is a handy approach when configuring multiple trackers for deployment.

COPY
notecard -setup configure-standalone-tracker.json

The Notecard will send each request in turn and output the result.

COPY
{"req":"card.restore","delete":true}
{}

{"req":"hub.set","mode":"periodic","product":"com.veritas.delivery-fleet.tracker"}
{}

{"req":"card.location.mode","seconds":3600,"mode":"periodic"}
{"seconds":3600,"mode":"periodic"}

{"req":"card.location.track","start":true,"hours":1,"heartbeat":true}
{"start":true,"minutes":60,"heartbeat":true}

Once these requests complete, your Notecard will self-provision with Notehub and start tracking location and movement.

Configure a Host-Controlled Tracker

If your application needs to capture and sync additional location-tagged data during tracking, or you wish to control tracking modes and intervals at runtime, you can build a host-controlled tracker. In this scenario, the Notecard receives the same requests as above, with the difference being that these requests are sent from a host MCU and can be adjusted by that host depending on the needs of your application.

When host-controlled, you’ll configure the tracker in firmware after boot, and before entering the application loop. For instance, assume that you’re working with an Arduino-style host that will configure the Notecard as a tracker, and capture environmental readings from a BME680. You’ll start by making a serial connection to the Notecard, and sending each tracker configuration request:

COPY
#include <Notecard.h>
#include <Wire.h>
#include <seeed_bme680.h>

#define serialDebug Serial
#define serialNotecard Serial1
#define productUID "com.veritas.delivery-fleet.tracker"

#define IIC_ADDR  uint8_t(0x76)
Seeed_BME680 bmeSensor(IIC_ADDR);

Notecard notecard;

long previousMillis = 0;
long interval = 60000 * 10;

void setup()
{
  serialDebug.begin(115200);

  notecard.setDebugOutputStream(serialDebug);
  notecard.begin();

  J *req = notecard.newRequest("hub.set");
  JAddStringToObject(req, "product", productUID);
  JAddStringToObject(req, "mode", "periodic");
  JAddNumberToObject(req, "outbound", 60);
  JAddNumberToObject(req, "inbound", 120);
  notecard.sendRequest(req);

  req = notecard.newRequest("card.location.mode");
  JAddStringToObject(req, "mode", "periodic");
  JAddNumberToObject(req, "seconds", 3600);
  notecard.sendRequest(req);

  req = notecard.newRequest("card.location.track");
  JAddBoolToObject(req, "sync", true);
  JAddBoolToObject(req, "heartbeat", true);
  JAddNumberToObject(req, "hours", 4);
  notecard.sendRequest(req);

  if (!bmeSensor.init()) {
    serialDebug.println("Could not find a valid BME680 sensor...");
  } else {
    serialDebug.println("BME680 Connected...");
  }
}

note

This sample does not perform a card.restore because doing so would wipe the Notecard on each reset. The full firmware source in GitHub does show an example for performing a restore only when the Device's ProductUID doesn't match the intended ProductUID.

Then, your application loop will capture readings, and add them as location-tagged Notes to the Notecard.

COPY
void loop()
{
  unsigned long currentMillis = millis();

  if ((currentMillis - previousMillis > interval) && notecardProductSet) {
    previousMillis = currentMillis;

    if (bmeSensor.read_sensor_data()) {
      serialDebug.println("Failed to obtain a reading...");
    } else {
      J *req = notecard.newRequest("note.add");
      if (req != NULL) {
        JAddStringToObject(req, "file", "sensors.qo");

        J *body = JCreateObject();
        if (body != NULL) {
          JAddNumberToObject(body, "temp", bmeSensor.sensor_result_value.temperature);
          JAddNumberToObject(body, "humidity", bmeSensor.sensor_result_value.humidity);
          JAddNumberToObject(body, "pressure", bmeSensor.sensor_result_value.pressure / 1000.0);
          JAddNumberToObject(body, "gas", bmeSensor.sensor_result_value.gas / 1000.0);
          JAddItemToObject(req, "body", body);
        }

        notecard.sendRequest(req);
      }
    }
  }
}

Once the application firmware has been deployed to your device and tested, you can add a battery to your project and deploy it to your asset.

The host-controlled tracker has the added benefit of allowing you to adjust Notecard tracking settings in response to sensor readings or certain external conditions. For instance, you can change the mode or increase reading interval when the asset is in motion, and decrease it when the asset is idle for a period of time.

note

The complete source for both configuration approaches can be found in the Blues note-tutorials repository.

Viewing Tracker Data

Once your tracker is deployed and the Notecard is provisioned, it will synchronize tracking data in accordance with the configuration settings you specified. Upon synchronization, you will be able to view your data in Notehub.io. For both types, tracking entries will show up as Notes from the _track.qo Notefile (or the Notefile name you specified).

If you open an individual Note, you can view the Device location and Time Zone under the location tab.

In the JSON tab, you can see tracking data like bearing, distance and velocity in the Note body, as well as the location fields, all of which begin with where.

If you’re using a host-controlled tracker and sending sensor readings in a Notefile, each Note is also tagged with the same where fields as tracking Notes.

Routing Tracker Data to Third-Party Services

Once your tracker is deployed and is synching to Notehub, you can use Routes to send tracker data to any third-party service for additional processing and visualization. Notehub Routes can be configured to connect to any external service. Routes also give you the ability to send everything from all your Notecards, targeted fleets, or even Notefiles, and to transform event data before you route it to an external service.

For example, if you wanted to create a Route to send only the data you need from a _track.qo Note to an external service, you could use a JSONata transformation like this:

COPY
{
  "location": {
    "where": where,
    "latitiude": where_lat,
    "longitude": where_lon,
    "location": where_location,
    "country": where_country,
    "time_zone": where_timezone
  },
  "motion": {
    "bearing": body.bearing,
    "distance": body.distance,
    "seconds": body.seconds,
    "velocity": body.voltage
  },
  "captured_time": when,
  "sync_time": routed
}

JSONata is a powerful data-transformation language built into Notehub, and you can learn more about it and the process of creating third-party Routes in the Route Tutorial.

Additional Resources

• Standalone Tracker Example Configuration File
• Host-Controlled Tracker Firmware Example for Arduino
• Host MCU & Notecard Tutorial
• Routing Tutorial