Devices

GET {baseURl}/devices
Returns a list of devices that the developer has access to, together with metadata and the latest device status.

https://clarity-data-api.clarity.io/v1/devices

Headers

• x-api-key: the API key string.

Response

attribute		description
_id	string	The long ID of the device. Example: "5cf56f698bfb2c5f878ff8ad"
code	string	The short ID of the device. Example: "A0000001"
location	GeoJSON object	The deployed location of the device. see example below
enabledCharacteristics	array	All characteristics the device is able to measure. Not guaranteed that all characteristics in the list will be included in a measurement. Hardware failures may result in missing characteristics. see example below
lifeStage	string	The life stage of the device. see Lifestages below
state	object	The configuration of the device. Configuration is controlled by Clarity support team See Device State below
photo	string	The URL of the device's photo. Example: https://dashboard.clarity.io/static/media/node-s.4fcbbc54.png
indoor	bool	True = indoors False = outdoors
roadDistance	number	Distance from road, in meters
aglHeight	number	Height above ground level, in meters
workingStartAt	string	Optional. The time when the device started working. Example: "2019-01-01T00:00:00.000Z"
lastReadingReceivedAt	string	Optional. The time when device uploaded the last reading. Example: "2019-01-01T00:00:00.000Z"
latestBatteryVoltage	number	Optional. The latest battery voltage, in Volts. Example: 4.121234
batteryPercentage	number	Optional. The latest battery charge, as percentage of full Example: 99.1
batteryStatus	string	Optional. The health status of battery. The possible values are listed below.
rssi	number	Optional. RSSI stands for Received Signal Strength Indicator. It is an estimated measure of power level that an RF client device is receiving from an access point. (unit: dBm) Example: -51
signalStrength	string	Optional. The quality of signal. The possible values are "marginal" < "ok" < "good" < "excellent"
sensorsHealthStatus	string	Optional. The status of sensors embedded in a device. Possible values are listed below.
overallStatus	string	Optional. The overall status of a device. Possible values are listed below.

Example GeoJSON object

    "location": {
        "coordinates": [
            -122.2687187,  // longitude
            37.8712728     // latitude
        ],
        "type": "Point"
    }

Example Characteristics array

    "enabledCharacteristics": [
    "relHumid",
    "temperature",
    "pm2_5ConcNum",
    "pm2_5ConcMass",
    "pm1ConcNum",
    "pm1ConcMass",
    "pm10ConcNum",
    "pm10ConcMass",
    "no2Conc"
]

Lifestage

• "purchased": device belongs to the user's organization but has not been configured yet.
• configured": device has been configured through Clarity Dashboard but has not uploaded any measurement yet.
• "working": device has uploaded at least one measurement after being configured. Note that "working" lifestage does not imply that the device is active or has no issues.
• "decommisioned": device has been deemed no longer usable by Clarity support team.

State (of device)

More configuration information might be added later.

nodeSleepConfig: (object)
- sleepTime: (number) the sleep time in seconds.
- sleepMultiplier: (number) the multiplier of sleep time.

Example

{
    "state": {
        "nodeSleepConfig": {
            "sleepMultiplier": 1, 
            "sleepTime": 900},
    }
}

Battery status

• normal: Battery is discharging properly.
• recoveryMode: Very low battery voltage, the device slows down and tries to recover.
• charging: Battery is charged from solar panel or power adapter.
• temperatureError: Too low or too high temperature to charge battery, or thermistor issue.
• readoutError: Cannot read battery.

Sensor health status

• nominal: No reading out of expected bound, no error codes from sensors.
• degraded: More than 1 and less than 20 of the last 25 readings are out of bound for any characteristic.
• critical: More than 20 of the last 25 readings are out of bound for any characteristic, or there is any error code.

Overall status

• needsSetup: A device needs setup if its life stage is purchased or configured
• needsAttention: A device needs attention
  • if the server hasn't received its reading for over 48 hours.
  • if its signal strength is marginal.
  • if its sensors health status is critical or degraded.
  • if its battery Status is recoveryMode, temperature Error or readoutError.
  • if its battery percentage is lower than 20%.
• healthy: This device is working properly.

Example 200 Response

[
    {
        "_id": "598d67f14dbf4a23b5a21f2a",
        "code": "A0000001",
        "lifeStage": "working",
        "location": {
            "coordinates": [
                -10.8658,
                39.576
            ],
            "type": "Point"
        },
        "enabledCharacteristics": ["pm2_5ConcMass", "pm10ConcMass"],
        "state": {
            "nodeSleepConfig": {"sleepMultiplier": 1, "sleepTime": 900},
        },
        "photo": "https://s3.bucket/photo.jpg",
        "roadDistance": 1,
        "indoor": false,
        "aglHeight": 3,
        "workingStartAt": "2020-01-18T12:05:40.340Z",
        "lastReadingReceivedAt": "2021-01-18T12:05:40.340Z",
        "latestBatteryVoltage": 4.9,
        "batteryStatus": "normal",
        "batteryPercentage": 99.2,
        "signalStrength": "excellent",
        "rssi": -51,
        "sensorsHealthStatus": "nominal",
        "overallStatus": "healthy"
    }
]