Device Interactions

Send a command to a device. You need the device_id of the device you want to control. You can get it from the 'Get List of Devices' API. The full list of commands is:

CommandDescriptionJSONAccepted values for valComments
PowerTurn the fan ON or OFF{"power":val}true or false
Speed AbsoluteSet the speed to an absolute value{"speed":val}an integer from 1 to 6
Speed RelativeIncrease/decrease the speed{"speedDelta":val}one of -5, -4, -3, -2, -1, 1, 2, 3, 4, 5
Sleep modeEnable or disable sleep mode{"sleep":val}true or false
TimerSet a preset timer{"timer":val}one of 0, 1, 2, 3, 40: off <br>1: 1 hour <br>2: 2 hours <br>3: 3 hours <br>4: 6 hours
Lights ON/OFFTurn the light ON or OFF{"led":val}true or falseOn Aris Starlight it restores the last known colour and brightness
ReverseReverse the direction of rotation{"rev_mode":val}true or false
Brightness AbsoluteSet brightness to an absolute value{"brightness":val}an integer from 10 to 100Percentage
Brightness DeltaIncrease/decrease brightness{"brightnessDelta":val}an integer from -90 to 90Percentage
ColourChange the colour of the light{"light_mode":val}one of "warm", "cool", "daylight"
BuzzerEnable or disable audible feedback{"buzzer_status":val}true or false

Every fan accepts the Base commands. The other columns add more commands:

ColumnCommands it adds
Basepower, speed, speedDelta, sleep, timer, led
Brightnessbrightness, brightnessDelta
Colourlight_mode
Extrasrev_mode, buzzer_status

If you send a command that a series does not support (No in its column), you get a 400 error. The message lists the commands that series accepts.

ModelSeriesBaseBrightnessColourExtras
Renesa / Renesa+ / Studio+R1, R2, R3, R4, R6YesNoNoNo
ArisI2YesNoNoNo
EricaK1YesNoNoNo
Renesa FusionR5YesNoNoNo
Aris GladiusI3, I4YesNoNoNo
Aris ContourM1, M2, M3YesYesNoNo
Renesa Elite / Studio NexusS1, S2, S3YesYesNoNo
Aris StarlightI1, I5YesYesYesNo
Emperion MagnaO1YesYesYesYes

Water purifier commands

Water purifiers have their own set of commands. Send one command key per message. A request with two commands is rejected. The only exception is the sleep_mode sub-keys (start_utc and stop_utc). They are sent with sleep_mode and do not count as separate commands.

CommandDescriptionJSONAccepted values for valComments
ModeSet the purification mode{"mode":val}0, 1, 2, 3, 4, 10See the mode table below
Fallback modeMode used when the device falls back from the selected mode{"fallback_mode":val}0, 2, 3, 4RO_ONLY or a TasteTune mode. ADAPTIVE and Vacay are not allowed
TDS thresholdInput TDS threshold that decides RO vs UF treatment{"tds_threshold":val}100 to 300Parts per million
Idle sleepTurn off the display and lights while the unit is idle{"idle_sleep":val}0, 10: off, 1: on
Sleep window onTurn on the daily sleep window{"sleep_mode":1,<br>"start_utc":start,<br>"stop_utc":stop}start and stop: uint32 epoch secondsSend all three keys together in one message. See Sleep window sub-keys below
Sleep window offTurn off the daily sleep window{"sleep_mode":0}-Send it on its own. start_utc and stop_utc are not accepted with 0

Purification modes

ValueModeMeaning
0RO_ONLYAlways use RO treatment
1ADAPTIVEBypass RO
2TasteTune 50-100Keeps purified water TDS between 50 and 100 ppm
3TasteTune 75-125Keeps purified water TDS between 75 and 125 ppm
4TasteTune 100-150Keeps purified water TDS between 100 and 150 ppm
10VacayHoliday mode

Sleep window sub-keys

start_utc and stop_utc are sub-keys of sleep_mode. Send them only with sleep_mode set to 1, in the same message. They do not count as separate commands. In 'Get List of Devices', sleep_mode lists them under requires, and each one has sub_key_of: "sleep_mode".

Sub-keySent withAccepted valuesMeaning
start_utc"sleep_mode": 1uint32 epoch secondsStart of the daily sleep window
stop_utc"sleep_mode": 1uint32 epoch secondsEnd of the daily sleep window
{
  "device_id": "a0764ee4210c",
  "command": { "sleep_mode": 1, "start_utc": 1767304800, "stop_utc": 1767330000 }
}

Send start_utc and stop_utc as numbers, not strings. Only the time of day is used (epoch modulo 86400), so the window repeats every day. To turn the window off, send {"sleep_mode":0} on its own.

Smart locks

Locks do not accept commands through this API. A command sent to a G1 Cypheo Elite or an Azhero Smart Door Lock / SL1 returns a 400. This is also why supported_commands is empty for locks in 'Get List of Devices'. Use 'Get Device State' to read a lock and 'Get Lock Dynamic PIN' to create a guest PIN.

Sending the command locally

Local control over UDP is currently available for fans only. To control water purifiers, use the 'Send Command' API.

You can control the fans locally over UDP, without having to rely on the cloud API. The steps involved are as follows:

Step 1: Check if the device is available on the local network.

Each device sends a beacon packet over UDP every one second on port 5625. This beacon packet contains the MAC address of the device, followed by the series (mac_series). You can have a background service that listens for the beacon packets and stores the mapping of MAC against the IP address. A sample implementation in Python is given below:

import socket
import threading
import time

# Define the UDP port to listen on
UDP_IP = "0.0.0.0"  # Listen on all available interfaces
UDP_PORT = 5625
BUFFER_SIZE = 4096  # Adjust as needed
TIMEOUT = 2  # seconds

available_devices = {}
lock = threading.Lock()

def cleanup_inactive_devices():
    while True:
        now = time.time()
        with lock:
            inactive_devices = [mac for mac, (ip, ts) in available_devices.items() if now - ts > TIMEOUT]
            for mac in inactive_devices:
                print(f"Removing inactive device: {mac}")
                del available_devices[mac]
        time.sleep(1) 

def main():
    # Create a UDP socket
    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

    # Bind the socket to the IP and port
    sock.bind((UDP_IP, UDP_PORT))
    print(f"Listening for UDP packets on port {UDP_PORT}...")

    # Start background cleanup thread
    threading.Thread(target=cleanup_inactive_devices, daemon=True).start()

    try:
        while True:
            data, addr = sock.recvfrom(BUFFER_SIZE)  # Receive packet
            ip, port = addr
            content = data.decode(errors='replace')
            if len(content) <= 15:
                print("Beacon packet received")
                mac = content[:12]
                with lock:
                    available_devices[mac] = (ip,time.time())
            print(f"Received packet from {ip}:{port}")
            print(f"available device data: {available_devices}")
            # You can also store this in a file or database if needed
    except KeyboardInterrupt:
        print("\nStopped by user.")
    finally:
        sock.close()

if __name__ == "__main__":
    main()

Step 2: Send the command to the device

If you have identified the MAC address of the device to which you wish to send the command, you can use the command JSONs (described above) to send the command to the intended device. An example implementation in Python is given below:

import json
import socket 

TARGET_IP = "192.168.29.233"
TARGET_PORT = 5600

# JSON command to send command = {
    "led":False
}

# Convert to JSON string and encode to bytes
message = json.dumps(command).encode('utf-8')

# Create UDP socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# Send the message
sock.sendto(message, (TARGET_IP, TARGET_PORT))
print(f"Sent JSON command to {TARGET_IP}:{TARGET_PORT}")

# Close the socket
sock.close()

Request

WhereNameRequiredValue
Headerx-api-keyYesYour developer API key.
HeaderAuthorizationYesBearer <access_token>
HeaderContent-TypeYesapplication/json
{
  "device_id": "6867258b9d78",
  "command": { "power": true, "speed": 4 }
}
FieldTypeRequiredMeaning
device_idstringYesA device on your account. all is not accepted here.
commandobjectYesOne or more command keys, as a JSON object (not an array or a string).

Every key in command is checked against the device's series before anything is sent. If one key is invalid, the whole message is rejected and nothing is applied. The 400 error names the wrong key and lists what that series accepts.

Response

{
  "status": "Success",
  "message": "Command sent successfully"
}

Accepted does not mean applied

200 means the command was checked and sent to the device. It does not mean the device has acted on it yet.

If the device is offline, you get a 503 error and the command is not delivered. A device can still miss a command if it drops off Wi-Fi at that moment. To confirm the change, call 'Get Device State' after a second or two and compare the values.

post/send_command

Request

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

Request body

device_idstring required

From 'Get List of Devices'.

commandobject required

One or more command keys. Water purifiers accept only one key per message.

Response

OK

statusstring

Success on a 2xx, Error otherwise.

messagestring

Confirms that the command was checked and sent. It does not mean the device has acted on it yet.

Example response

{
  "status": "Success",
  "message": "Command sent successfully"
}

Changes