Get Device State
Changed onGet the last known state of the device.
Some developers, especially those who keep querying the state of their fan(s) frequently, may soon hit the API limit with this API. For these developers, it is better to listen to the state of the fan(s) locally over UDP. If you would rather access the device state using an API rather than locally over UDP, skip the next section.
Reading the state from the fan over UDP
UDP state broadcasts are currently available for fans only. To retrieve the state of water purifiers and smart locks, use the 'Get Device State' API.
Once the fan receives any command and takes action, it updates its state over UDP on the broadcast port (5625). The message is received in the hex format, and needs to be converted to ASCII. For example, the message received may be
7b226465766963655f6964223a22613037363465356165653938222c226d6573736167655f6964223a2241636d42696a6d6f6d666e424a62486341222c2273746174655f737472696e67223a2232302c312c422c352c35302e30302c302c302c52312c323830322c312c34353134322c302c302c302c302c302e30302c302e30302c302c302c302c454e44227d
When converted to ASCII, the state message reads
{
"device_id":"a0764e5aee98",
"message_id":"AcmBijmomfnBJbHcA",
"state_string":"20,1,B,5,50.00,0,0,R1,2802,1,45142,0,0,0,0,0.00,0.00,0,0,0,END"
}
The message_id is a unique identifier for each message. This can help the system discard duplicates.
The state_string contains the current state of the fan, apart from a lot of other debug fields. The current state (speed, power, light brightness, etc.) can be decoded from the first field of the state string itself (the first field is 20 in the above example). Its decoding logic is given below:
var power = (0x10) & value > 0 ? true : false;
var led = (0x20) & value > 0 ? true : false;
var sleep = (0x80) & value > 0 ? true : false;
var speed = (0x07) & value;
var fanTimer = ((0x0F0000 & value) / 65536).round();
var fanTimerElapsedMins = ((0xFF000000 & value) * 4 / 16777216).round();
//Aris Starlight Specific
var Brightness = (((0x7F00) & value) / 256).round();
var Cool = ((0x08) & value) > 0 ? true : false;
var Warm = ((0x8000) & value) > 0 ? true : false;
If both Cool and Warm are true, then color is 'Daylight'
Response fields by device type
The fields depend on the type of device. Fans report power and speed. Purifiers report water quality and mode. Locks report battery and firmware. There is a response example for each type below.
Fields marked firmware-dependent are only sent when the device's firmware reports them. On older units these keys are missing from the response (they are not null), so your code should handle missing keys.
Fan fields
| Field | Type | Meaning |
|---|---|---|
| power | boolean | Whether the fan is running |
| last_recorded_speed | integer | Last reported speed, 1-6. Kept while off |
| sleep_mode | boolean | Whether sleep mode is active |
| led | boolean | Whether the fan light is on |
| is_online | boolean | Whether the device is connected right now |
| timer_hours | integer | Duration the running timer was set for, 0 when none |
| timer_time_elapsed_mins | integer | Minutes elapsed on the running timer |
| ts_epoch_seconds | integer | When the device last reported |
| last_recorded_brightness | integer | Percentage. M1, M2, S1, S2, M3, S3, I1, I5, O1 |
| last_recorded_color | string | warm / cool / daylight. I1, I5, O1 |
| rev_mode | boolean | Whether the fan is running in reverse. O1 |
| buzzer_status | boolean | Whether audible feedback is on. O1 |
Water purifier fields
| Field | Type | Meaning |
|---|---|---|
| mode | integer | Active purification mode. 0, 1, 2, 3, 4 or 10 |
| fallback_mode | integer | Mode the unit falls back to. 0, 2, 3 or 4 (RO_ONLY or a TasteTune mode) |
| idle_sleep | 0 / 1 | Whether the display turns off while idle |
| tds_threshold | integer | RO vs UF threshold in ppm. Firmware-dependent |
| sleep_mode | 0 / 1 | Whether the daily sleep window is on. Firmware-dependent |
| start_utc | integer | Sleep window start, epoch. Firmware-dependent |
| stop_utc | integer | Sleep window end, epoch. Firmware-dependent |
| input_tds | number | Raw inlet water TDS, ppm |
| tank_tds | number | Raw stored water TDS, ppm |
| choking_faults | object | Flow blockage and valve faults, already decoded. Not a single fault code. Check healthy or look in codes. null if never reported |
| system_faults | object | Electrical, sensor and leak faults, already decoded. A separate bitmask with its own code table. null if never reported |
Smart lock fields
Locks report battery, firmware and their settings. Credentials are never returned. This means no PINs, fingerprint data or card IDs, and no credential names or counts.
| Field | G1 Cypheo Elite | Azhero Smart Door Lock / SL1 |
|---|---|---|
| battery | Yes | Yes |
| last_battery_time | Yes | Yes |
| n_unlocks | Yes | - |
| esp_fw_version | Yes | - |
| settings | door lock, motor, volume, child lock | - |
Request
| Where | Name | Required | Value |
|---|---|---|---|
| Header | x-api-key | Yes | Your developer API key. |
| Header | Authorization | Yes | Bearer <access_token> |
| Query | device_id | Yes | One device_id, or all for every supported device. |
No request body.
Passing all returns every supported device on the account in one call, which counts as one request against your quota. Reading six devices one by one costs six. Devices that this API does not support are left out.
Response
{
"status": "Success",
"message": {
"device_state": [
{
"device_id": "6867258b9d78",
"power": true,
"last_recorded_speed": 4,
"sleep_mode": false,
"led": true,
"is_online": true,
"timer_hours": 1,
"timer_time_elapsed_mins": 12,
"ts_epoch_seconds": 1756200000
}
]
}
}
device_state is always an array, even for one device_id. The fields in each item depend on the device type. The tables above list them.
What the values mean
This endpoint returns the last state the device reported. It does not read the device live.
is_online tells you if the device is connected now. When it is false, the other fields show the last known values. That is fine for a dashboard, but do not treat them as current.
If the firmware has never reported a field, the field is missing (it is not null). Older firmware on the same series can return fewer fields than newer firmware. Use .get(key) in Python or ?. in JavaScript to handle this.
Request
- Base URLhttps://api.developer.atomberg-iot.com/v2
- AuthAPI key in header x-api-key and HTTP bearer
Query parameters
One device_id, or all for every supported device on the account. With all, devices that this API does not support are left out.
Response
OK
Example response
{
"status": "Success",
"message": {
"device_state": [
{
"series": "O1"
}
]
}
}Changes
- warning
removed the optional property
////from the response with the status
- warning
- info
endpoint added
- info