Device API
The Notehub device API provides RESTful methods that can be used to GET
,
POST
, and DELETE
data related to devices and
fleets.
Get Devices This request can be performed using the Notehub API.Notehub
Get an array of devices associated with a Notehub project.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
pageSize
integer (optional)
Specifies the number of devices to be returned by a request (default 50).
pageNum
integer (optional)
Specifies the page number of the results returned (useful when the pageSize
is
less than the total number of devices that could be returned).
curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices'
-H 'Authorization: Bearer <access_token>'
curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices?pageSize=<pageSize>&pageNum=<pageNum>'
-H 'Authorization: Bearer <access_token>'
Response Members
uid
string
The globally-unique identifier of the device.
serial_number
string
The user-defined serial number of the device.
provisioned
string
The date and time this device was first provisioned, or put into use.
last_activity
string
The date and time this device was last seen by Notehub.
contact
object
Contact information for this device, specified via environment variables.
product_uid
string
The ProductUID this device is associated with.
fleet_uids
array
An array of globally-unique identifiers for the fleet(s) this device is associated with.
tower_info
object
An object containing data about the cellular tower last accessed by this device.
tower_info.mcc
int
The mobile country code of the cell tower.
tower_info.mnc
int
The mobile network code of the cell tower, which identifies the mobile operator.
tower_info.lac
int
The location area code of the cell tower, which is a unique identifier of the current location area.
tower_info.cell_id
int
The Cell ID or CID of the cell tower. This is a unique number used to identify each Base Transceiver Station (BTS) or sector of a BTS within a location area code.
tower_location
object
An object containing information about the physical location of the cell tower.
gps_location
object
An object containing information about the physical location of the device, based on GPS coordinates.
triangulated_location
object
An object containing information about the physical location of the device based on triangulated data calculated by multiple cell towers.
voltage
decimal
The most recent measure of the voltage from the onboard voltage monitor.
temperature
decimal
The most recent temperature measure in celsius from the onboard temperature sensor.
has_more
boolean
Defines whether or not there are additional devices beyond this list.
dfu
object
Information about the device firmware update status for the Notecard
"type":"card"
or the host MCU "type":"user"
. The mode
will be one of:
"idle"
- nothing downloading or downloaded
"error"
- halted and in the error state
"downloading"
- transferring data from cloud to module
"sideloading"
- transferring data via request to module
"ready"
- DFU data is ready/verified and waiting on external storage
"ready-retry"
- DFU data is ready/verified and retrying
"updating"
- currently updating
"completed"
- DFU is done successfully
sku
string
The SKU of the Notecard in use. See the Notecard datasheet dropdown menu for example SKUs.
disabled
boolean
Whether or not the device is disabled.
{
"devices":[
{
"uid":"dev:000000000000000",
"serial_number":"",
"provisioned":"2021-02-11T02:37:16Z",
"last_activity":"2021-05-11T19:37:08Z",
"contact":null,
"product_uid":"product:com.your-company.your-name:project",
"fleet_uids":"[fleet:00000000-0000-0000-0000-000000000000]",
"tower_info":{
"mcc":310,
"mnc":410,
"lac":12345,
"cell_id":12345678
},
"tower_location":{
"when":"2021-05-11T19:34:23Z",
"name":"Cassville MO",
"country":"US",
"timezone":"America/Chicago",
"latitude":36.665537500000006,
"longitude":-93.850109375
},
"gps_location":{
"same properties as tower_location"
},
"triangulated_location":{
"same properties as tower_location"
},
"voltage":5.15,
"temperature":23.75,
"dfu":{
"card":{
"type":"card",
"mode":"idle",
"updated":1632938485,
"version":"{\"org\":\"Blues Wireless\",\"product\":\"Notecard\",\"version\":\"notecard-1.5.6\",\"ver_major\":1,\"ver_minor\":5,\"ver_patch\":6,\"ver_build\":13695,\"built\":\"Sep 13 2021 15:37:30\"}"
},
"user":{
"type":"user",
"mode":"idle",
"updated":1632938486
}
},
"sku":"NOTE-WBNA-500"
}
],
"has_more":false
}
Get Device by UID This request can be performed using the Notehub API.Notehub
Get information about a single device by its DeviceUID.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>'
-H 'Authorization: Bearer <access_token>'
Response Members
uid
string
The globally-unique identifier of the device.
serial_number
string
The user-defined serial number of the device.
provisioned
string
The date and time this device was first provisioned, or put into use.
last_activity
string
The date and time this device was last seen by Notehub.
contact
object
Contact information for this device, specified via environment variables.
product_uid
string
The ProductUID this device is associated with.
fleet_uids
array
An array of globally-unique identifiers for the fleet(s) this device is associated with.
tower_info
object
An object containing data about the cellular tower last accessed by this device.
tower_info.mcc
int
The mobile country code of the cell tower.
tower_info.mnc
int
The mobile network code of the cell tower, which identifies the mobile operator.
tower_info.lac
int
The location area code of the cell tower, which is a unique identifier of the current location area.
tower_info.cell_id
int
The Cell ID or CID of the cell tower. This is a unique number used to identify each Base Transceiver Station (BTS) or sector of a BTS within a location area code.
tower_location
object
An object containing information about the physical location of the cell tower.
gps_location
object
An object containing information about the physical location of the device, based on GPS coordinates.
triangulated_location
object
An object containing information about the physical location of the device, based on triangulated data calculated by multiple cell towers.
voltage
decimal
The most recent measure of the voltage from the onboard voltage monitor.
temperature
decimal
The most recent temperature measure in celsius from the onboard temperature sensor.
dfu
object
Information about the device firmware update status for the Notecard
"type":"card"
or the host MCU "type":"user"
. The mode
will be one of:
"idle"
- nothing downloading or downloaded
"error"
- halted and in the error state
"downloading"
- transferring data from cloud to module
"sideloading"
- transferring data via request to module
"ready"
- DFU data is ready/verified and waiting on external storage
"ready-retry"
- DFU data is ready/verified and retrying
"updating"
- currently updating
"completed"
- DFU is done successfully
sku
string
The SKU of the Notecard in use. See the Notecard datasheet dropdown menu for example SKUs.
disabled
boolean
Whether or not the device is disabled.
{
"uid":"dev:000000000000000",
"serial_number":"",
"provisioned":"2021-02-11T02:37:16Z",
"last_activity":"2021-05-11T19:37:08Z",
"contact":null,
"product_uid":"product:com.your-company.your-name:project",
"fleet_uids":["fleet:00000000-0000-0000-0000-000000000000"],
"tower_info":{
"mcc":310,
"mnc":410,
"lac":12345,
"cell_id":12345678
},
"tower_location":{
"when":"2021-05-11T19:34:23Z",
"name":"Cassville MO",
"country":"US",
"timezone":"America/Chicago",
"latitude":36.665537500000006,
"longitude":-93.850109375
},
"gps_location":{
"same properties as tower_location"
},
"triangulated_location":{
"same properties as tower_location"
},
"voltage":5.15,
"temperature":23.75,
"dfu":{
"card":{
"type":"card",
"mode":"idle",
"updated":1632938485,
"version":"{\"org\":\"Blues Wireless\",\"product\":\"Notecard\",\"version\":\"notecard-1.5.6\",\"ver_major\":1,\"ver_minor\":5,\"ver_patch\":6,\"ver_build\":13695,\"built\":\"Sep 13 2021 15:37:30\"}"
},
"user":{
"type":"user",
"mode":"idle",
"updated":1632938486
}
},
"sku":"NOTE-WBNA-500"
}
Delete Device by UID This request can be performed using the Notehub API.Notehub
Delete a single device by its DeviceUID.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
purge
boolean
true
performs a deep delete that removes the device and all associated
data (e.g. events, settings, files, and sessions) from Notehub. false
will
perform a shallow delete that only removes the device, but other data will
persist.
curl -X DELETE
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>?purge=<purge>'
-H 'Authorization: Bearer <access_token>'
Enable Device by UID This request can be performed using the Notehub API.Notehub
Enable a disabled device by its DeviceUID.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/enable'
-H 'Authorization: Bearer <access_token>'
Disable Device by UID This request can be performed using the Notehub API.Notehub
Disable a device by its DeviceUID.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/disable'
-H 'Authorization: Bearer <access_token>'
Provision Device This request can be performed using the Notehub API.Notehub
Provision a device to a specific ProductUID.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
product_uid
string
The ProductUID from a Notehub project.
device_sn
string (optional)
The user-defined serial number of the device.
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/provision'
-H 'Authorization: Bearer <access_token>'
-d '{"product_uid":"<product_uid>"}'
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/provision'
-H 'Authorization: Bearer <access_token>'
-d '{"product_uid":"<product_uid>", "device_sn":"<serial_number>"}'
Send Device Signal This request can be performed using the Notehub API.Notehub
Send a signal from Notehub to a Notecard device.
Minimum Notehub project-level role required:
A Notecard can receive a signal with the
hub.signal
request.
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
body
JSON object
The JSON object to send.
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/signal'
-H 'Authorization: Bearer <access_token>'
-d '{"body":<body>}'
Response Members
connected
boolean
true
if the Notecard is connected to Notehub.
{
"connected": true
}
Enable Connectivity Assurance This request can be performed using the Notehub API.Notehub
Enable Connectivity Assurance on a device by its DeviceUID.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/enable-connectivity-assurance'
-H 'Authorization: Bearer <access_token>'
Disable Connectivity Assurance This request can be performed using the Notehub API.Notehub
Disable Connectivity Assurance on a device by its DeviceUID.
Minimum Notehub project-level role required:
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID from a Notehub project.
deviceUID
string
The globally-unique identifier of a device.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/disable-connectivity-assurance'
-H 'Authorization: Bearer <access_token>'