Once the Notecard is connected to a cell network or GPS, there are a number of requests available for obtaining the time, location, and using the onboard GPS module for location tracking.
To obtain the current time, expressed as a Unix epoch value, use the
card.time
request. Note: Upon power-up, the Notecard must complete a
sync to Notehub in order to obtain time and location data.
{"req": "card.time"}
Sending this request yields a response that includes the current UNIX Epoch
time
, local time zone
, minutes
East of GMT, latitude (lat
), longitude
(lon
), and country
.
{
"time": 1598478570,
"area": "Beverly, MA",
"zone": "CDT,America/New York",
"minutes": -300,
"lat": 42.577600,
"lon": -70.871340,
"country": "US",
}
Tower Location vs. Notecard Location
It's important to note that the location values returned by a card.time
request correspond to the cellular tower to which the Notecard
last connected. This may differ widely from the physical location of the
Notecard. For greater accuracy of location, you'll want to use
card.location
APIs described below.
Until the Notecard has connected to a cellular network, it does not know the
time. In those cases, card.location
requests respond with a zone
value of
UTC,Unknown
.
{"zone":"UTC,Unknown"}
For increased location accuracy without using GPS, the Notecard provides a triangulation capability that gathers information about surrounding cell towers or local Wi-Fi access points before every connection to the Notehub, if enabled. This feature should be used sparingly if your device is battery-powered as it adds several minutes of connection time each time the Notecard powers on the cellular modem to establish a connection with Notehub.
card.triangulate
does not itself perform Notecard triangulation. Rather,
it gathers cell tower and Wi-Fi access point data that Notehub uses
to perform device triangulation, if enabled. This feature does not
affect the location data returned by the card.location
request, but is
intended to increase the accuracy of tower location data sent from Notehub to
any Routes defined in your project.
To turn triangulation on, use the card.triangulate
request, with the mode
argument set to wifi
, cell
, or both, separated by a comma:
{ "req": "card.triangulate", "mode": "wifi,cell" }
This request will return an object confirming that triangulation is enabled with
the mode provided, and a motion
field indicating the last time device
movement was detected.
{ "mode": "wifi,cell", "motion": 1606761044 }
The wifi
mode enables the Notecard and Notehub to use nearby Wi-Fi access
points to determine the position of the Device. See
Providing Wi-Fi Information to the Notecard
below for more information.
The card.triangulation
request provides options for configuring the Notecard
based on its power state and movement. Set the usb
argument to true
to instruct the Notecard to only perform triangulation when connected to USB
power, and set on
to true
if you want the Notecard to triangulate even when
the device has not moved. Both flags require the set
argument in order to
take effect.
{ "req": "card.triangulate", "mode": "wifi,cell", "on": true, "usb": true, "set": true }
This request will return an object with the current triangulation
configuration parameters, a motion
field indicating the time of the last
device movement, and time
field indicating the time of the last triangulation
scan.
{ "mode": "wifi,cell", "usb": true, "on": true, "time": 1606758961, "motion": 1606761044 }
To turn triangulation off, set the mode
argument to -
:
{ "req": "card.triangulate", "mode": "-" }
This request will return an object with no mode
argument, indicating that
triangulation is disabled. The motion
and time
fields may still be present
after triangulation is disabled.
{"motion": 1606761044}
If your host has an onboard Wi-Fi module, you can perform a manual
access point scan and send this information to the Notecard using the text
argument. The format of the text
field must be a newline-terminated list
of Wi-Fi access points that follows a pattern similar to the
ESP32's AT+CWLAP
command output.
{ "req": "card.triangulate", "text": "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\r\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\r\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\r\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\r\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\r\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\r\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\r\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\r\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\r\n\r\n" }
This request will return an object with the current triangulation
configuration parameters, and a length
field indicating the size of the
text
buffer provided in the request.
{ "usb": true, "mode": "wifi,cell", "length": 398, "on": true, "time": 1606770857, "motion": 1606770581 }
The Notecard includes an onboard GPS module that can be used for location
tracking, when paired with an appropriate antenna. To conserve power, the GPS
module on the Notecard is off, by default. You can confirm this with the
card.location
request:
{"req":"card.location"}
Which will return the following:
{
"status": "GPS is off {gps-inactive}",
"mode": "off"
}
When using GPS mode, you'll want to decide whether your application should enable GPS periodically to conserve battery at the cost of accuracy between readings, or continuously in real-time.
If you prefer to enable GPS readings on an interval, use periodic mode. In this mode, the Notecard enables GPS at a frequency you define using either a set number of seconds or using a voltage-variable value. In both cases, regardless of the periodic value, the GPS module will only turn on to update the location if the Notecard has moved since the last time GPS was enabled. The 'seconds' value sets the minimum interval at which the Notecard will enable its GPS.
For example, to enable the Notecard's GPS no more frequently than once every
600 seconds (10 minutes), set mode
to periodic
and use the seconds
argument in a card.location.mode
request:
{
"req": "card.location.mode",
"mode": "periodic",
"seconds": 600
}
This will return an object confirming that the Notecard is in periodic mode and that GPS should be enabled no more frequently than once every 600 seconds:
{
"mode": "periodic",
"seconds": 600
}
Once enabled, use the card.location
request to monitor connection status
and location.
{"req": "card.location"}
While waiting for the Notecard to obtain a GPS fix, expect to see intermediate
status
messages in response to card.location
requests.
// When the module is still inactive
{
"status": "GPS inactive {gps-inactive}",
"mode": "periodic"
}
// When the module has started
{
"status": "GPS started {gps-active} {gps-active}",
"mode": "periodic"
}
// When the module is active, but searching for GPS
{
"status": "GPS search (19 sec, 41dB SNR, 5 sats) {gps-active}
{gps-signal} {gps-sats}",
"mode": "periodic"
}
You may see several variations of the second message before the module obtains
a fix. Once obtained, future card.location
requests include the current
Notecard latitude (lat
) and longitude (lon
) values, as well as the Unix
epoch time that location was captured.
{
"status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active}
{gps-signal} {gps-sats} {gps}",
"mode": "periodic",
"lat": 42.577600,
"lon": -70.871340,
"time": 1598554399
}
To preserve battery, when the Notecard is in periodic mode, GPS is only enabled
if the built-in accelerometer detects movement since the last GPS enable. If
the Notecard has not moved, a card.location
request will indicate that GPS is
inactive and provide the last location reading.
{
"status": "GPS inactive {gps-inactive} {gps}",
"mode": "periodic",
"lat": 42.577600,
"lon": -70.871340,
"time": 1598557149
}
When operating in periodic mode, use the
card.location.track
request to configure the Notecard to store
GPS readings in a Notefile. Note that the behavior in this section only
applies to the capture of location events. The rules for how and when those
events sync are the same as general sync settings defined with hub.set
.
{
"req": "card.location.track",
"start": true
}
This will return an object confirming that tracking mode has started and
the minimum duration in seconds between Notes being placed in a Notefile. The
seconds
value is the value set in a request to card.location.mode
.
{
"seconds": 10,
"start": true
}
By default, tracking notes are placed into a Notefile named _track.qo
. To
define your own Notefile, use the file
argument.
{
"req": "card.location.track",
"start": true,
"file": "locations.qo"
}
Tracking data is available to view in Notehub, once synced, and includes a number of helpful fields that can be Routed to your cloud applications.
{
"bearing": 194.8890307950282,
"distance": 5.591816976119877,
"seconds": 36,
"temperature": 49.625,
"time": 1598560691,
"usb": true,
"velocity": 0.014337992246461224,
"voltage": 4.727260437757979
}
By default, tracking data will only be captured if the Notecard detects motion.
To add periodic tracking Notes when there is no movement, use the heartbeat
argument. You can also use the optional hours
argument to capture heartbeat
tracking notes at a rate that differs from the rate when there is motion.
{
"req": "card.location.track",
"start": true,
"heartbeat": true,
"hours": 1
}
To turn tracking mode off, set the stop
argument to true
.
{
"req": "card.location.track",
"stop": true
}
To set your Notecard to GPS Continuous mode, use the card.location.mode
request:
{
"req": "card.location.mode",
"mode": "continuous"
}
Which will return an object confirming that the Notecard is in continuous mode:
{"mode": "continuous"}
Once enabled, use the card.location
request to monitor connection status
and location:
{"req": "card.location"}
While waiting for the Notecard to obtain a GPS fix, expect to see intermediate
status
messages in response to card.location
requests. Note: the Notecard
will not turn on the GPS module until it has made a successful cellular
connection upon startup to obtain the current time. Once the Notecard has
the time, GPS is available for use, regardless of the state of a cellular
connection.
// When the module is still inactive
{
"status": "GPS inactive {gps-inactive}",
"mode": "continuous"
}
// When the module is active, but searching for GPS
{
"status": "GPS search (19 sec, 41dB SNR, 5 sats) {gps-active}
{gps-signal} {gps-sats}",
"mode": "continuous"
}
You may see several variations of the status message before the module obtains
a fix. Once obtained, future card.location
requests include the current
Notecard latitude (lat
) and longitude (lon
) values, as well as the Unix
epoch time that location was captured.
{
"status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active}
{gps-signal} {gps-sats} {gps}",
"mode": "continuous",
"lat": 42.577600,
"lon": -70.871340,
"time": 1598554399
}
Continuous Cellular & Continuous GPS
The Notecard does not support running both a continuous
cellular connection ({"req":"hub.set", "mode":"continuous"}
) and continuous
GPS. If you attempt to set both cellular and GPS to continuous mode, the
Notecard will return an error. This applies both to card.location.mode
when the cellular connection is continuous, as well as hub.set
if GPS has
been set in continuous mode.
{"err": "cannot simultaneously use continuous card.location.mode and hub.set modes"}
At any point, the GPS mode of the Notecard can be obtained by calling the
card.location.mode
command with no arguments.
{ "req": "card.location.mode" }
The Notecard can be configured to trigger an immediate sync to Notehub when the
device moves beyond a geofence you
define. Use the lat
and lon
arguments
to set the center, and the max
argument to specify the
number of meters from the center to set the geofence. You can also optionally
pass the minutes
argument to specify a number of minutes the Notecard must
be outside of the geofence before its location is tracked.
The default value for minutes
is 5.
{
"req": "card.location.mode",
"mode": "periodic",
"lat": 42.577600,
"lon": -70.871340,
"max": 100,
"minutes": 2
}
This will return an object confirming that the geofence is enabled using the parameters provided.
{
"max": 100,
"mode": "periodic",
"lat": 42.577600,
"lon": -70.871340,
"minutes": 2
}
When you no longer need to capture GPS data from the Notecard, turn it off with
a card.location.mode
request and mode
field set to off
.
{
"req": "card.location.mode",
"mode": "off"
}
Which will return an object confirming that GPS is off:
{"mode": "off"}
Even after GPS has been disabled, the Notecard keeps the last location obtained,
which can be retrieved at any time with a card.location
request.
{"req": "card.location"}
{
"status": "GPS is off {gps-inactive} {gps}",
"mode": "off",
"lat": 42.577600,
"lon": -70.871340,
"time": 1598555070
}
If you wish to delete the last known location stored in the Notecard, use the
delete
argument in a card.location.mode
request.
{
"req": "card.location.mode",
"delete": true
}
Subsequent requests to card.location
no longer provide location data, until
GPS is re-enabled and a new reading is captured.
{
"status": "GPS is off {gps-inactive} {gps}",
"mode": "off"
}