Send Command
Changed onSend 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:
| Command | Description | JSON | Accepted values for val | Comments |
|---|---|---|---|---|
| Power | Turn the fan ON or OFF | {"power":val} | true or false | |
| Speed Absolute | Set the speed to an absolute value | {"speed":val} | an integer from 1 to 6 | |
| Speed Relative | Increase/decrease the speed | {"speedDelta":val} | one of -5, -4, -3, -2, -1, 1, 2, 3, 4, 5 | |
| Sleep mode | Enable or disable sleep mode | {"sleep":val} | true or false | |
| Timer | Set a preset timer | {"timer":val} | one of 0, 1, 2, 3, 4 | 0: off <br>1: 1 hour <br>2: 2 hours <br>3: 3 hours <br>4: 6 hours |
| Lights ON/OFF | Turn the light ON or OFF | {"led":val} | true or false | On Aris Starlight it restores the last known colour and brightness |
| Reverse | Reverse the direction of rotation | {"rev_mode":val} | true or false | |
| Brightness Absolute | Set brightness to an absolute value | {"brightness":val} | an integer from 10 to 100 | Percentage |
| Brightness Delta | Increase/decrease brightness | {"brightnessDelta":val} | an integer from -90 to 90 | Percentage |
| Colour | Change the colour of the light | {"light_mode":val} | one of "warm", "cool", "daylight" | |
| Buzzer | Enable or disable audible feedback | {"buzzer_status":val} | true or false |
Every fan accepts the Base commands. The other columns add more commands:
| Column | Commands it adds |
|---|---|
| Base | power, speed, speedDelta, sleep, timer, led |
| Brightness | brightness, brightnessDelta |
| Colour | light_mode |
| Extras | rev_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.
| Model | Series | Base | Brightness | Colour | Extras |
|---|---|---|---|---|---|
| Renesa / Renesa+ / Studio+ | R1, R2, R3, R4, R6 | Yes | No | No | No |
| Aris | I2 | Yes | No | No | No |
| Erica | K1 | Yes | No | No | No |
| Renesa Fusion | R5 | Yes | No | No | No |
| Aris Gladius | I3, I4 | Yes | No | No | No |
| Aris Contour | M1, M2, M3 | Yes | Yes | No | No |
| Renesa Elite / Studio Nexus | S1, S2, S3 | Yes | Yes | No | No |
| Aris Starlight | I1, I5 | Yes | Yes | Yes | No |
| Emperion Magna | O1 | Yes | Yes | Yes | Yes |
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.
| Command | Description | JSON | Accepted values for val | Comments |
|---|---|---|---|---|
| Mode | Set the purification mode | {"mode":val} | 0, 1, 2, 3, 4, 10 | See the mode table below |
| Fallback mode | Mode used when the device falls back from the selected mode | {"fallback_mode":val} | 0, 2, 3, 4 | RO_ONLY or a TasteTune mode. ADAPTIVE and Vacay are not allowed |
| TDS threshold | Input TDS threshold that decides RO vs UF treatment | {"tds_threshold":val} | 100 to 300 | Parts per million |
| Idle sleep | Turn off the display and lights while the unit is idle | {"idle_sleep":val} | 0, 1 | 0: off, 1: on |
| Sleep window on | Turn on the daily sleep window | {"sleep_mode":1,<br>"start_utc":start,<br>"stop_utc":stop} | start and stop: uint32 epoch seconds | Send all three keys together in one message. See Sleep window sub-keys below |
| Sleep window off | Turn 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
| Value | Mode | Meaning |
|---|---|---|
| 0 | RO_ONLY | Always use RO treatment |
| 1 | ADAPTIVE | Bypass RO |
| 2 | TasteTune 50-100 | Keeps purified water TDS between 50 and 100 ppm |
| 3 | TasteTune 75-125 | Keeps purified water TDS between 75 and 125 ppm |
| 4 | TasteTune 100-150 | Keeps purified water TDS between 100 and 150 ppm |
| 10 | Vacay | Holiday 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-key | Sent with | Accepted values | Meaning |
|---|---|---|---|
| start_utc | "sleep_mode": 1 | uint32 epoch seconds | Start of the daily sleep window |
| stop_utc | "sleep_mode": 1 | uint32 epoch seconds | End 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
| Where | Name | Required | Value |
|---|---|---|---|
| Header | x-api-key | Yes | Your developer API key. |
| Header | Authorization | Yes | Bearer <access_token> |
| Header | Content-Type | Yes | application/json |
{
"device_id": "6867258b9d78",
"command": { "power": true, "speed": 4 }
}
| Field | Type | Required | Meaning |
|---|---|---|---|
| device_id | string | Yes | A device on your account. all is not accepted here. |
| command | object | Yes | One 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.
Request
- Base URLhttps://api.developer.atomberg-iot.com/v2
- AuthAPI key in header x-api-key and HTTP bearer
Request body
Response
OK
Example response
{
"status": "Success",
"message": "Command sent successfully"
}Changes
- info
endpoint added
- info