Device Monitoring

Owned by Nikolay Abrosimov
Last updated: Dec 05, 2023
6 min read

Nwave API provides endpoints for device health monitoring. They allow you to build your own monitoring system, device health dashboards, or alerting systems.

The full API documentation is available at the end of the page.

Terms

  • Incident - something out of the ordinary happened with a device

  • Device state - the last or highest priority incident with additional information about device damaging/activation/positioning

  • Severity - level of importance. The higher it is the higher attention you have to pay to a device.

    • OK - there is no reason to worry about the devices

    • Info - detected a low-priority issue with a device, it can even be temporal

    • Warning - detected a high-priority problem, it can be possibly resolved by yourselves

    • Critical - detected a critical problem, the device need to be replaced

  • Error types - short description of an action that happened with the device and created an incident

    • Manual - someone has marked a device as damaged

    • Hardware Error - issue with device hardware (sensors, battery, radio, or Bluetooth module)

    • Last Message Time Error - no messages had been receiving at least for last 24

    • Anomalous Status Duration - temporarily disabled

    • Positioned But Inactive - a device is bound to a position, not damaged, but inactive

    • Positioned But Not Calibrated - the device is bound to a position, but Nwave Cloud has not received a notification about the device calibration

  • Incident reasons - a result of incident reason detection using the Nwave Replacement App and visual control.

    • Missing - a device has been lost from its position

    • Hidden Problem - a device is not fully functional or not functional at all, but visually it is ok

    • Not Confirmed - the detected problem is not confirmed

    • Not Specified - reason has not been specified, but the problem is confirmed

    • Broken Casing - a device body is broken

    • No Reason - the incident reason has not been investigated yet

Relation between error types and severity:

Severity

Error

Severity

Error

OK

  • No error

Info

  • Last Message Time Error (5 days ago or less)

  • Bluetooth Error

Warning

  • Last Message Time Error (more than 5 days ago)

  • Positioned But Inactive

  • Positioned But Not Calibrated

Critical

  • Hardware Error

  • Manual

  • Low battery

API

Before using this API you should create an Authorization Token. You can find instructions here: Generating Authorization Tokens

Getting current device states

URL: https://api.nwave.io/monitoring/v1/devices/states

The endpoint responds with a list of devices with information about an active incident. New incidents are placed at the beginning of the list.

API arguments (more details in the OpenAPI documentation at the end of the document):

  • Filters by:

    • Project

      • Project ID

    • Zone

      • Zone ID

    • Level

      • Level ID

      • Floor number

    • Group

      • Group ID

    • Position

      • Network ID

    • Device

      • Device ID

      • Damaging status

      • Activation status

    • Incident

      • Error type

      • Reason

  • Pagination

    • Limit

    • Offset

  • Additional abilities

    • Download - flag for getting response as CSV file

The following example shows how to request 1 device that has not been sending messages for 24 hours and more:

curl --request GET 'https://api.nwave.io/monitoring/v1/devices/states?incident_type=last_message_time_error&limit=1&offset=0' --header 'X-Auth-Token: YOURTOKEN'

The response example:

{ "reason": "ok", "data": [ { "device_id": "3e583f", "zone_name": "Foo", "zone_id": 6781, "group_name": "Bar", "group_id": 1712038, "project_name": "FooBar", "incident_type": "last_message_time_error", "reason": null, "incident_date": "2023-02-22T19:55:35.835968+00:00", "incident_id": 625497955, "days_broken": 4 "latitude": 50.7794461486047, "longitude": -1.08391361741045, "severity": "info", "network_id": "d690ac73-dcf2-feeb-daed-3e583ff79a2" } ], "message": null, "total": 49 }

Response data object fields:

  • device_id - Device unique ID

  • zone_name - Name of the zone containing the device

  • zone_id - ID of the zone containing the device

  • group_name - Name of the group containing the device

  • group_id - ID of the group containing the device

  • project_name - Name of the project containing the device

  • incident_type - see the term “Error types” above

  • reason - see the term “Incident reasons” above

  • incident_date - date and time of the incident detection

  • incident_id - ID of the incident

  • days_broken - how many days ago the incident was registered

  • latitude/latitude - device position coordinates

  • severity - see the term Severity above

  • network_id - network ID of the position to which the device is bound to

Getting a history of device incidents

URL: https://api.nwave.io/monitoring/v1/incidents

The endpoint responds with a list of devices containing information about all incidents. New incidents are placed at the beginning of the list.

API arguments (more details in the OpenAPI documentation at the end of the document):

  • Filters by:

    • Project

      • Project ID

    • Zone

      • Zone ID

    • Level

      • Level ID

      • Floor number

    • Group

      • Group ID

    • Position

      • Network ID

    • Device

      • Device ID

      • Damaging status

      • Activation status

    • Incident

      • Error type

      • Reason

      • Creation time period

      • Resolving time period

      • Resolving status

      • Comment

      • Is damaged incident

      •  

  • Pagination

    • Limit

    • Offset

  • Additional abilities

    • Download - flag for getting response as CSV file

The following example shows a request for the last 10 incidents which automatically marks devices as damaged:

curl --location 'https://api.nwave.io/monitoring/v1/incidents?damaging=true&limit=10&offset=0' --header 'X-Auth-Token: YOURTOKEN'

Response example:

{ "reason": "ok", "data": [ { "device_id": "13d45a", "network_id": "d618f2dc-a5c0-40c6-aaf2-4e32df090abf", "zone_id": 2, "zone_name": "Nwave_Test", "error_type": "manual", "is_resolved": true, "created_time": "2023-01-29T09:55:42.475167+00:00", "reason": "broken_casing", "resolved_time": "2023-01-29T09:55:42.475261+00:00", "resolving_type": "manual", "group_id": 24368, "group_name": "Group_test", "damaging": true, "id": 6230232153, "state": { "trace_id": null, "error_datetime": "2023-01-29T09:55:42.389000+00:00" }, "comment": "Found broken sensor", "user_id": "88954cc3-851a-4a2d-b8d4-6351ab574b8d", "activation_status": false, "damaged_status": false }, ... ], "message": null, "total": 144 }

Response data object fields:

  • device_id - Device unique ID

  • zone_name - Name of the zone containing the device

  • zone_id - ID of the zone containing the device

  • group_name - Name of the group containing the device

  • group_id - ID of the group containing the device

  • project_name - Name of the project containing the device

  • reason - see the term “Incident reasons” above

  • id - ID of the incident

  • days_broken - how many days ago the incident was registered

  • latitude/latitude - device position coordinates

  • network_id - network ID of the position to which the device is bound to

  • error_type - see the term “Error types” above

  • is_resolved - true if someone has diagnosed the problem with the Nwave Replacement App or changed the device damaging status to False

  • resolving_time - time of the incident resolving. see “is_resolved” filed

  • created_time - time of the incident registration

  • resolving_type - auto if the incident has been resolved by itself. manual if someone resolved it using Nwave Replacement App or changed the device damaging status to False

  • damaging - True if a consequence of the error detection was setting the device damaged status

  • state.trace_id - Trace ID of Raw Messages which led to the incident creation

  • state.error_datetime - time of the incident creation

  • comment - a user who resolves the incident can leave a comment

  • user_id - ID of a user who resolved the incident

  • activation_status - current activation status of the device

  • damaged_status - current damaged status of the device

OpenAPI documentation