Skip to content
This repository was archived by the owner on Mar 30, 2021. It is now read-only.

HTTP API Documentation

Jump to bottom
Marco Realacci edited this page Dec 7, 2017 · 29 revisions

HomeAutomation v4 HTTP API

THIS IS THE OLD (OB1RC2 AND LOWER) API AND IS NOT WORKING ANYMORE, WE'RE WRITING THE DOC FOR THE NEW API, PLEASE BE PATIENT.

HomeAutomation's API provides you full control to HomeAutomation Server. With this API you can create your own client with your own UI to control HomeAutomation.

How it works

This API is based on HTTP/GET requests, every request is following this format: https://server-ip:port/api?interface={sub API and methods}

The protocol by default is HTTP, read the how to configure an SSL certificate page.

*This API is organized in different sub APIs (or modules), every module has got his own methods (you can learn more about the structure by visiting the work in progress page).

Index

These are all the modules's API

GET data API

This module provides you all the data of the Server, like for example the current color of an RGB light, or if a relay is on or off. All the data are provided in JSON.

API methods

This API is the only one who (for now) is not using the format of the other requests.

Rooms

server-ip:port/api?get=rooms&password=password

Room json data:

Parameter Description Type
Name Name of the room String
FriendlyNames Aliases of the name String[]
Objects Devices in the room (see the next paragraph) IObject[]
Hidden Tells to the client if a room should be shown Boolean

Devices

server-ip:port/api?get=devices&password=password

IObject json data:

Parameter Description Type
Name Name of the device String
FriendlyNames Aliases of the name String[]
Description What the devices is/do in real life String
ObjectType What device is (e.g. an RGB light or a relay) Integer

Remember that every device has got his own properties, thease are the properties that every device has got.

Switchable devices

server-ip:port/api?get=switchabledevices&password=password

ISwitchableObject json data:

Parameter Description Type
Name Name of the device String
FriendlyNames Aliases of the name String[]
Description What the devices is/do in real life String
Switch Is the device on or off? Boolean
ObjectType What device is (e.g. an RGB light or a relay) Integer

Remember that every device has got his own properties, thease are the properties that every device has got, and a ISwitchableObject can be parsed into an IObject.

Raspi-Clients

server-ip:port/api?get=clients&password=password

Client json data:

Parameter Description Type
Name Name of the Raspi-Client String
PigpioID ID of pigpio library (is always 0) Unsigned Int32
Connected Is the Raspi-Client online? Boolean

RGB Lights API

This API allows you to control every RGB light in HomeAutomation.

JSON structure

Parameter Description Type
Name Name of the device String
FriendlyNames Aliases of the name String[]
Description What the devices is/do in real life String
Switch Is the device on or off? Boolean
ObjectType What device is (e.g. a light or a relay) (lights are 0) Integer
LightType What light is (ObjectType is the same for all the lights) (RGB is 0) Integer
PinR Red GPIO pin Unsigned Int32
PinG Green GPIO pin Unsigned Int32
PinB Blue GPIO pin Unsigned Int32
ValueR Red RGB value Unsigned Int32
ValueG Green RGB value Unsigned Int32
ValueB Blue RGB value Unsigned Int32
Brightness % of brightness (returns 100% on every color change) Unsigned Int32
ClientName Raspi-Client's name String

API methods

Change color

server-ip:port/api?interface=light_rgb&objname=objname&R=R&G=G&B=B&dimmer=dimmer&password=password

Parameter Description Type
objname Name of the light String
R, G and B RGB values Byte
Dimmer Fade animation's duration (can be 0) Unsinged Int32
Password Server's password String

Set color from name

server-ip:port/api?interface=light_rgb&objname=objname&color=color&dimmer=dimmer&password=password

Parameter Description Type
objname Name of the light String
Color Name of the color (English only for OB1RC1, other versions supports custom names) String
Dimmer Fade animation's duration (can be 0) Unsinged Int32
Password Server's password String

Dimm the light

server-ip:port/api?interface=light_rgb&objname=objname&percentage=dimm_percentage&dimmer=dimmer&password=password

Parameter Description Type
objname Name of the light String
dimm_percentage Percentage of dimming (for example 40 means 40%), returns 100% on every color change Byte
Dimmer Fade animation's duration (can be 0) Unsinged Int32
Password Server's password String

Set on / off

server-ip:port/api?interface=light_rgb&objname=objname&switch=status&password=password

Parameter Description Type
objname Name of the light String
Status true for on, false for off Boolean
Password Server's password String

W Lights API

This API allows you to control every W light (or any PWM single-channel device) in HomeAutomation.

JSON structure

Parameter Description Type
Name Name of the device String
FriendlyNames Aliases of the name String[]
Description What the devices is/do in real life String
Switch Is the device on or off? Boolean
ObjectType What device is (e.g. a light or a relay) (lights are 0) Integer
LightType What light is (ObjectType is the same for all the lights) (W lights are 1) Integer
Pin GPIO pin Unsigned Int32
Value PWM value (brightness from 0 to 255) Unsigned Int32
Brightness % of brightness (returns 100% on every value change) Unsigned Int32
ClientName Raspi-Client's name String

API methods

Change brightness

server-ip:port/api?interface=light_w&objname=objname&W=brightness&dimmer=dimmer&password=password

Parameter Description Type
objname Name of the light String
brightness Brightness (from 0 to 255) Byte
Dimmer Fade animation's duration (can be 0) Unsinged Int32
Password Server's password String

Set on / off

server-ip:port/api?interface=light_w&objname=objname&switch=status&password=password

Parameter Description Type
objname Name of the light String
Status true for on, false for off Boolean
Password Server's password String

Relay's API

This API allows you to switch on and off a relay. For web relays see this page.

JSON structure

Parameter Description Type
Name Name of the device String
FriendlyNames Aliases of the name String[]
Description What the devices is/do in real life String
Eanbled Is the relay on or off? Boolean
ObjectType What device is (e.g. a light or a relay) (relays are 2) Integer
Pin GPIO pin Unsigned Int32
ClientName Raspi-Client's name String

Set on / off

server-ip:port/api?interface=relay&objname=objname&switch=status&password=password

Parameter Description Type
objname Name of the relay String
Status true for on, false for off Boolean
Password Server's password String

Buttons's API

This API allows you to switch on and off remote buttons on non-Raspberry Pi platforms (such as Arduino or ESP8266)

Button JSON structure

Parameter Description Type
Name Name of the device String
ObjectType What device is (e.g. a light or a relay) (buttons are 4) Integer
Pin GPIO pin Unsigned Int32
ClientName Raspi-Client's name String
IsRemote Is the button on a Raspi-Client (false) or on a non-Raspberry Pi board (true)? Boolean
Commands Execute API commands on every click String[]
Objects Switch on and off any switchable device ISwitchableDevices[]

Remember that if IsRemote is true, ClientName will always be "local".

Switch button JSON structure

Parameter Description Type
Name Name of the device String
ObjectType What device is (e.g. a light or a relay) (switch buttons are 5) Integer
Pin GPIO pin Unsigned Int32
ClientName Raspi-Client's name String
IsRemote Is the button on a Raspi-Client (false) or on a non-Raspberry Pi board (true)? Boolean
CommandsOn Execute API commands on every switch on String[]
CommandsOff Execute API commands on every switch off String[]
Objects Switch on and off any switchable device ISwitchableDevices[]

API methods

Click a button

server-ip:port/api?interface=button&objname=objname&switch=true&password=password

Parameter Description Type
objname Name of the button String
Password Server's password String

Switch a switch button

server-ip:port/api?interface=switch_button&objname=objname&switch=status&password=password

Parameter Description Type
objname Name of the switch String
Status true for on, false for off Boolean
Password Server's password String

Configuration API

This API allows you to create new HomeAutomation devices.

API methods

Add a new room

server-ip:port/api?interface=configuration&addroom=objname&setfriendlynames=friendlynames&hiddenroom=hiddenroom&password=password

Parameter Description Type
objname Name of the room String
friendlynames Aliases of the name (separated by comma [,]) String
hiddenroom Tells to the client if a room should be shown or hidden Boolean
Password Server's password String

Remove a room

server-ip:port/api?interface=configuration&removeroom=objname&password=password

Parameter Description Type
objname Name of the room to remove String
Password Server's password String

Add a new RGB light

server-ip:port/api?interface=configuration&addlightrgb=objname&setfriendlynames=friendlynames&description=description&addpinr=Pin R&addping=Pin G&addpinb=Pin B&client=raspi-client&room=room&password=password

Parameter Description Type
objname Name of the light String
friendlynames Aliases of the name (separated by comma [,]) String
description What the device is / does (shown in json) String
Pin R RGB R GPIO pin Unsigned Int32
Pin G RGB G GPIO pin Unsigned Int32
Pin B RGB B GPIO pin Unsigned Int32
raspi-client Name of the Raspi-Client String
room Name of the room String
Password Server's password String

Add a new W light

server-ip:port/api?interface=configuration&addlightw=objname&setfriendlynames=friendlynames&description=description&addpin=pin&client=raspi-client&room=room&password=password

Parameter Description Type
objname Name of the light String
friendlynames Aliases of the name (separated by comma [,]) String
description What the device is / does (shown in json) String
pin GPIO pin Unsigned Int32
raspi-client Name of the Raspi-Client String
room Name of the room String
Password Server's password String

Add a new relay

server-ip:port/api?interface=configuration&addrelay=objname&setfriendlynames=friendlynames&description=description&addpin=pin&client=raspi-client&room=room&password=password

Parameter Description Type
objname Name of the relay String
friendlynames Aliases of the name (separated by comma [,]) String
description What the device is / does (shown in json) String
pin GPIO pin Unsigned Int32
raspi-client Name of the Raspi-Client String
room Name of the room String
Password Server's password String

Add a new web relay

server-ip:port/api?interface=configuration&addwebrelay=objname&id=id&setfriendlynames=friendlynames&description=description&room=room&createbutton=button type&password=password

Parameter Description Type
objname Name of the relay String
id ID of the web relay (so you can change objname without flashing the code again) String
friendlynames Aliases of the name (separated by comma [,]) String
description What the device is / does (shown in json) String
room Name of the room String
button type Add also a remote button linked to the web relay (it can be "none", "button" or "switch_buitton") String
Password Server's password String

Add a new button

server-ip:port/api?interface=configuration&addbutton=objname&addpin=pin&room=room&client=raspi-client&remote=remote button&password=password

Parameter Description Type
objname Name of the button String
pin GPIO pin (if it's a remote button don't put this parameter) Unsigned Int32
room Name of the room String
remote button Is the button on a Raspi-Client's GPIO or remote (like web relay) Boolean
raspi-client Name of the Raspi-Client (must be "local" if remote button is true) String
Password Server's password String

Add a device to a button

server-ip:port/api?interface=configuration&buttonaddobject=objname&object=device name&password=password

Parameter Description Type
objname Name of the button String
device name Name of the switchable device to add String
Password Server's password String

Add an API command to a button

server-ip:port/api?interface=configuration&buttonaddcommand=objname&command=command&password=password

Remember that you can put "%EmulatedSwitchStatus%" on the command, it will be replaced with "true" and "false" alternately.

Parameter Description Type
objname Name of the button String
command API command to add String
Password Server's password String

Add a new switch button

server-ip:port/api?interface=configuration&addswitchbutton=objname&addpin=pin&room=room&client=raspi-client&remote=remote button&password=password

Parameter Description Type
objname Name of the switch button String
pin GPIO pin (if it's a remote button don't put this parameter) Unsigned Int32
room Name of the room String
remote button Is the button on a Raspi-Client's GPIO or remote (like web relay) Boolean
raspi-client Name of the Raspi-Client (must be "local" if remote button is true) String
Password Server's password String

Add a device to a switch button

server-ip:port/api?interface=configuration&switchbuttonaddobject=objname&object=device name&password=password

Parameter Description Type
objname Name of the switch button String
device name Name of the switchable device to add String
Password Server's password String

Add an API command to a switch button

server-ip:port/api?interface=configuration&switchbuttonaddcommand=objname&command=command&type=type&password=password

Parameter Description Type
objname Name of the button String
command API command to add String
type Execute the command on switch on (put "on") or on switch off (put "off") String
Password Server's password String

Remove a device

server-ip:port/api?interface=configuration&removeobject=objname&password=password

Parameter Description Type
objname Name of the object to remove String
Password Server's password String

Clone this wiki locally