|====================================| | ArtiAPI Protocol Version 1.28 | | Written by: Michel van Osenbruggen | | CopyRight 2024 ArtiLED B.V. | |====================================| Hub version : 0.555 beta Latest change : 14-09-2024 ======================= | Protocol Definition | ======================= Protocol : HTTP(S) Port : 80/443 URL : http(s)://hub_ip/api DATA : POST with variables |=============| | Definitions | |=============| House : All lights are located in a House Room : Every light can be located in only one Room Zone : Every light can be located in multiple Zones Strip : Whole led strip -> All leds (Number of leds) Multi Strip : Multiple led strips with channel -> All leds Segment : Part of a led strip -> Start, End -> Start and End (0-1000) Part : Part of a led strip -> Start, End -> Start and End (0-1000) (Used for different scaling with Palette Part) Multi Segment : Multiple Parts of a led strip -> Array of n x (Start, End) -> Start and End (0-1000) Pixel : Single pixel of a led strip -> Pixel number -> Pixel numbers (0-1000) Multi Pixels : Multiple pixels of a led strip -> Array of Pixel Numbers -> Pixel numbers (0-1000) Pixel String : Multiple pixels of a led strip with a start (msb, lsb) then followed by an Array of Pixel Numbers (0-1000) Palette : Collection of Colors -> Max 16 colors |==================== | Channel Structure | ===================== 0 : 0 = All Channels 1 : 1 = Channel 1 2 : 2 = Channel 2 3 : 3 = Channel 3 4 : 4 = Channel 4 12 : 12 = Channel 1 + 2 13 : 13 = Channel 1 + 3 14 : 14 = Channel 1 + 4 23 : 23 = Channel 2 + 3 24 : 24 = Channel 2 + 4 34 : 34 = Channel 3 + 4 123 : 123 = Channel 1 + 2 + 3 124 : 124 = Channel 1 + 2 + 4 134 : 134 = Channel 1 + 3 + 4 234 : 234 = Channel 2 + 3 + 4 |===================| | Command Structure | |===================| > Command : /command + Token + Data -> example http://hub_ip/api/rooms # Privileged Command : /command + Token + Data (requires admin rights) $ Data : Depends on Command -> Send Data as json variable -> example: {"zone":1} or {"room":2} $ Token : Send as variable with each request token="Token" (Token is case sensitive) ! Future Command : Command not done yet, coming soon |=============| | Error Codes | |=============| 1 : Login Failed (invalid username or password) 2 : Token Invalid (request new token) 3 : Incomplete data (not all data supplied) 4 : Invalid data (data value incorrect) 5 : Invalid item (id does not exist) 6 : Command Invalid 7 : Command Execution Failed ====================== | Response Structure | ====================== $ response : Command Response => { "success":1/0, "Error":error Number, "error_text":"Error Text", "data": { data } } $ success : 1 = Command Succesful, 0 = Error (See Error) $ error : Error Number (See List) $ error_text : Error Text $ execution_time : Time in miliseccond it took to execute the Command $ data : See Data Structure ================== | Data Structure | ================== $ name : {"name":"name"} -> Node Name $ ident : {"ident":"ident"} -> Node Ident $ version : {"version":"version"} -> Node Software Version $ state : {"state":state} -> State 0=Off, 1=On $ online : {"online":online} -> Node/Light Status 0=Offline, 1=Online $ active : {"active":active} -> Active 0=Not Active, 1=Active $ channel : {"channel":channel} -> See Channel Structure $ brightness : {"brigntess":brightness} -> Brightness Value (0-255) $ Hue : {"hue":hue} -> Hue Value (0-255) $ saturation : {"saturation":saturation} -> Saturation Value (0-255) $ color : {"color":"rgb(red,green,blue)"} $ colors : {"colors":["rgb(red,green,blue)","rgb(red,green,blue)", ....]} $ color_rgbw : {"red":red,"green":green,"blue":blue,"white":white} -> Values (0-255) $ color_rgb : {"red":red,"green":green,"blue":blue} -> Values (0-255) $ color_hsv : {"hue":hue,"saturation":saturation,"value":value} -> Values (0-255) $ color_w : {"temperature":temperature,"intensity":intensity} -> Values (0-255) $ segment : {"start":start,"end":end} -> Values (0-1000) $ part : {"start":start,"end":end} -> Values (0-1000) $ clear : {"clear":clear,"commit":commit} -> Values (0-1) $ room : {"id":id,"name":"name","icon":"icon","status":"status:,"state":state,"brightness":brightness,"colors":["rgb(red,green,blue)", "rgb(red,green,blue)", ...]} $ zone : {"id":id,"name":"name","icon":"icon:,"status":"status","state":state,"brightness":brightness,"colors":["rgb(red,green,blue)", "rgb(red,green,blue)", ...]} $ scene : {"id":id,"name":"name","image_url","image_url","running",0/1} -> Running 0=Done, 1=Running $ mode : {"id":id,"name":"name","image_url","image_url"} $ light : {"id":id,'name':"name","image_url","image_url","disbled':disabled,"down":down,"state":state,"brightness":brightness} $ node : {"id":id,'name':"name","enabled":enabled,"down",down} $ palette : {"palette":{"palette":palette_id,"blend":blend,"scale":scale,"alternate":alternate,"start_index":start_index,"end_index",end_index} $ palette_custom : {"palette_custom":{"start_color":{"red":red,"green":green,"blue":blue},"end_color":{"red":red,"green"green,"blue":blue},"blend":blend,"scale":scale,"alternate":alternate,"start_index":start_index,"end_index":end_index} $ palette_advanced : {"palette_advanced":{"color_array":[[pos,red,green,blue],[pos,red,green,blue],...],"blend":blend,"scale":scale,"alternate":alternate,"start_index":start_index,"end_index":end_index}} $ notification : {"id":id, "priority":priority,"ident":"ident","name":"name","datetime","datetime","text":"text"} $ capabilities : {"dim":1/0,"colors":1/0,"color_profile":"w/rgb/rgbw","segments",0-16} ============ | Commands | ============ ----------------- | Alive Command | ----------------- > /Alive : No Data -> Returns Hub Name and Ident -> See Data Structure 'name' and 'ident' ----------------- | Login Command | ----------------- > /login : Data -> username and password -> Returns Token -> User Authenticates once with login screen ----------------- | Info Commands | ----------------- > /version : No Data -> Returns Hub Version -> See Data Structure 'version' ---------------- | Get Commands | ---------------- > /rooms : No Data or {"room":room_id} and {"order":"id"} or {"order":"name"} -> Returns Rooms -> {"rooms":[{room1, room2, ....}]} See Data Structure 'room' > /zones : No Data or {"zone":zone_id} and {"order":"id"} or {"order":"name"} -> Returns Zones -> {"zones":[{zone1, zone2, ....}]} See Data Structure 'zone' > /scenes : No Data or {"zone":zone_id} or {"room":room_id} and {"order":"id"} or {"order":"name"} -> Returns Scenes -> {"scenes":[{scene1, scene2, ....}]} See Data Structure 'scene' > /modes : No Data or {"zone":zone_id} or {"room":room_id} and {"order":"id"} or {"order":"name"} -> Returns Modes -> {"modes":[{mode1, mode2, ....}]} See Data Structure 'mode' > /lights : No Data or {"zone":zone_id} or {"room":room_id} -> Returns Lights -> {"lights":[{light1, light2, ....}]} See Data Structure 'light' > /notifications : No Data or {"order":id} or {"order":"date"}, {"limit":limit} -> Returns Notifications -> {"notifications":[{notification1, notification2, ....}]} See Data Structure 'notification' ! /nodes : No Data or {"zone":zone_id} or {"room":room_id} -> Returns Nodes -> {"nodes":[{node1, node2, ....}]} See Data Structure 'node' ! /strips : ! /segments : ---------------- | Set Commands | ---------------- > /house : Data {"channel":channel},{"state":state},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"} -> Sets Room (-> Returns Response See Data structure 'response' > /room : Data {"room":room_id} and {"channel":channel},{"state":state},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"} -> Sets Room (-> Returns Response See Data structure 'response' > /zone : Data {"zone":zone_id} and {"channel":channel},{"state":state},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"} -> Sets Zone (-> Returns Response See Data structure 'response' > /light : Data {"light":light_id} and {"channel":channel},{"state":state},{"clear":clear},{"brightness":brightness},{"color_w"},{"color_rgb"},{"color_rgbw"},{"color_hsv"},{"palette*"},{"segment"} -> Sets Light (-> Returns Response See Data structure 'response' : You can add {"hue":1} if you also want to control added or associated Philips Hue Lights (Please note you cannot update them as often as ArtiLED lights). ------------------ | Scene Commands | ------------------ > /scene : Data {"scene":scene_id) or ("scene":"scene_name") and {"room":room_id} or {"zone":zone_id} or {"light":light_id} -> Runs scene in Room, Zone or Light (-> Returns Response See Data structure 'response' ! /scene_stop? ------------------ | Mode Commands | ------------------ > /mode : Data {"mode":mode_id) or ("mode":"mode_name") and {"room":room_id} or {"zone":zone_id} or {"light":light_id} -> Starts mode in Room, Zone or Light (-> Returns Response See Data structure 'response'