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

Nwave Docs

Device Monitoring

Terms

API

Getting current device states

Getting a history of device incidents

OpenAPI documentation