Rate this page

★
★
★
★
★
★
★
★
★
★

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

Get an array of devices associated with a Notehub project.

Minimum Notehub project-level role required:

Arguments

`authToken`

string

A Notehub API authentication 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).

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

Example Response


{
   "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
            }
         }
      }
   ],
   "has_more":false
}

Get Device by UID

Get information about a single device by its DeviceUID.

Minimum Notehub project-level role required:

Arguments

`authToken`

string

A Notehub API authentication token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string

The globally-unique identifier of a device.


curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>'
     -H 'X-SESSION-TOKEN: <authToken>'

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:

Example Response


{
    "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
      }
}

Delete Device by UID

Delete a single device by its DeviceUID.

Minimum Notehub project-level role required:

Arguments

`authToken`

string

A Notehub API authentication token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string

The globally-unique identifier of a 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 'X-SESSION-TOKEN: <authToken>'

Enable Device by UID

Enable a disabled device by its DeviceUID.

Minimum Notehub project-level role required:

Arguments

`authToken`

string

A Notehub API authentication token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string

The globally-unique identifier of a device.


curl -X POST
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/enable'
     -H 'X-SESSION-TOKEN: <authToken>'

Disable Device by UID

Disable a device by its DeviceUID.

Minimum Notehub project-level role required:

Arguments

`authToken`

string

A Notehub API authentication token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string

The globally-unique identifier of a device.


curl -X POST
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/disable'
     -H 'X-SESSION-TOKEN: <authToken>'

Provision Device

Provision a device to a specific ProductUID.

Minimum Notehub project-level role required:

Arguments

`authToken`

string

A Notehub API authentication 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.


curl -X POST
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/provision'
     -H 'X-SESSION-TOKEN: <authToken>'
     -d '{"product_uid":"<product_uid>"}'

Billing Account API Environment Variable API