Device Interactions

Get Device State

Changed on

Get 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

FieldTypeMeaning
powerbooleanWhether the fan is running
last_recorded_speedintegerLast reported speed, 1-6. Kept while off
sleep_modebooleanWhether sleep mode is active
ledbooleanWhether the fan light is on
is_onlinebooleanWhether the device is connected right now
timer_hoursintegerDuration the running timer was set for, 0 when none
timer_time_elapsed_minsintegerMinutes elapsed on the running timer
ts_epoch_secondsintegerWhen the device last reported
last_recorded_brightnessintegerPercentage. M1, M2, S1, S2, M3, S3, I1, I5, O1
last_recorded_colorstringwarm / cool / daylight. I1, I5, O1
rev_modebooleanWhether the fan is running in reverse. O1
buzzer_statusbooleanWhether audible feedback is on. O1

Water purifier fields

FieldTypeMeaning
modeintegerActive purification mode. 0, 1, 2, 3, 4 or 10
fallback_modeintegerMode the unit falls back to. 0, 2, 3 or 4 (RO_ONLY or a TasteTune mode)
idle_sleep0 / 1Whether the display turns off while idle
tds_thresholdintegerRO vs UF threshold in ppm. Firmware-dependent
sleep_mode0 / 1Whether the daily sleep window is on. Firmware-dependent
start_utcintegerSleep window start, epoch. Firmware-dependent
stop_utcintegerSleep window end, epoch. Firmware-dependent
input_tdsnumberRaw inlet water TDS, ppm
tank_tdsnumberRaw stored water TDS, ppm
choking_faultsobjectFlow blockage and valve faults, already decoded. Not a single fault code. Check healthy or look in codes. null if never reported
system_faultsobjectElectrical, 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.

FieldG1 Cypheo EliteAzhero Smart Door Lock / SL1
batteryYesYes
last_battery_timeYesYes
n_unlocksYes-
esp_fw_versionYes-
settingsdoor lock, motor, volume, child lock-

Request

WhereNameRequiredValue
Headerx-api-keyYesYour developer API key.
HeaderAuthorizationYesBearer <access_token>
Querydevice_idYesOne 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.

get/get_device_state

Request

  • Base URL
    https://api.developer.atomberg-iot.com/v2
  • Auth
    API key in header x-api-key and HTTP bearer

Query parameters

device_idstring required

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

statusstring

Success on a 2xx, Error otherwise.

Example response

{
  "status": "Success",
  "message": {
    "device_state": [
      {
        "series": "O1"
      }
    ]
  }
}

Changes