Version: 2

ConnectHome Butler API

General

For local access entry point for HTTP API is http://{controller-ip}/api/v2/, where controller-ip is IP of controller in local network and v2 - is API version.

Every call to API should be authenticated, except those, where opposite stated.

Authentication

There are two authentication methods which can be used in controller.

Basic Authentication

This is standard Basic HTTP authentication.

Every API call should contain Authorization header, value of which should be Base64-encoded combination of username, semicolon(:) and password, prepended with Basic .

For example for user with username admin and password 12345678 correct header will be: Authorization: Basic YWRtaW46MTIzNDU2Nzg= where YWRtaW46MTIzNDU2Nzg= is Base64-encoded admin:12345678.

Token-based Authentication

For this method, user should acquire token with a call to POST /api/v2/auth/login using Basic Authentication

In case of success response will contain token (see reference for response format)

Every subsequent query should contain next header:

Authorization: Bearer abcdefg1234567

where abcdefg1234567 is previously received token.

Every token has it's own expiration time, which is renewed on each query.

Controller detection

To find all controllers in local network, client application should listen on arbitrary UDP port and send broadcast packets to port 17318 of the next format:

CONNECTHOME_BUTLER_DETECT{listening_port}

i.e. if client application is listening on port 20000 then correct packet will be CONNECTHOME_BUTLER_DETECT20000.

In the response to that broadcast packet, all controllers will respond with UDP JSON packet to that port. Format:

{
 "name": "Controller name",
 "ip": "192.168.1.123",
 "mac": "01:23:45:67:89:AB"
}

Error Reporting

All errors occured while processing a request are reported as follows

{
  "errorMessage":"Error message",
 "errorCode":1,
 "errorParameters":{}
}

where errorParameters is optional and contains fields, specific for each error code (see table below)

Error codes (WIP)

Error Code	Description	Parameters
0	No error

Entities

Section

Element which encapsulates rooms into convinient, user-defined groups. Has next properties:

• id - integer
• name - string

API Reference

Room

Room is room.

Has next properties:

• id - integer
• name - string
• section_id - integer, id of parent section
• order - integer, sort order in section
• background_image - string, name of background image
• icon - string, name of icon from predefined set of icons
• main_devices - collection of assosiated sensors (devices)
• temperature_sensor - integer, id of device
• humidity_sensor - integer
• luminosity_sensor - integer

API Reference

Device

Device is main entity in controller, it represents any interactive object.

Type and abilities of device can be determined by two properties:

• type - core type of device, allows to determine which interfaces device will mandatory support (See table below)
• interfaces - list of interfaces. Here by interface is meant collection of supported parameters and actions (See table below)

Overall device is defined by next properties:

• id - integer
• name - string
• room_id - integer, id of parent room
• type - string, described above
• role - string, device role
• icon - string, name of icon from predefined set of icons
• order - integer, sort order in room
• hidden - boolean, visibility of device in UI
• interfaces - string array, described above
• params - object, collection of device parameters
• note_text - Text of device note
• note_image - Image for device note MUST be uploaded via storage API

Device types (WIP)

Device type	Description	Mandatory interfaces
DevGateway	Gateway (Z-Wave controler)	Gateway
DevSwitch	Binary switch device	SwitchBinary
DevDimmer	Light dimmer	SwitchMultilevel, SwitchBinary
DevShutter	Roller shutters	SwitchMultilevel, SwitchBinary, Shutter
DevSwitchMultilevel	Unknown multiposition switch	SwitchMultilevel, SwitchBinary
DevBinarySensor	Binary sensor	SensorBinary
DevTemperature	Temperature sensor	SensorMultilevel
DevHygrometry	Humidity sensor	SensorMultilevel
DevLuminosity	Luminosity sensor	SensorMultilevel
DevGenericSensor	Other types of multilevel sensor	SensorMultilevel
DevThermostat	HVAC Thermostat	Atleast one of: ThermostatMode, ThermostatSetpoint, ThermostatOperatingState, ThermostatFanMode
DecDimmerColor	RGB(W) dimmer	SwitchMultilevel, SwitchColor, SwitchBinary
DevUnknown	Unrecognized device	-

note

All Z-Wave devices will also have ZWaveDevice interface

Interfaces parameters (WIP)

Interface	Parameter name	Description	Parameter type
ZWave Device	nodeId	Device Node ID in ZWave network	int
Multichannel Endpoint	endpointId	ID of endpoint	int
-	parentDeviceId	Parent device ID	int
Switch Binary	Status	Status of binary switch (true = on,false = off, for multilevel switches false means off, true - non-zero level)	bool
-	pulseable	Is switch pulsable	bool
Switch Multilevel	Level	Level of multilevel switch (0-99, where 0 is off and 99 is full power)	int
Version	firmwareVersion	Version(s) of device's firmware	int array
Association	groupsCount	Count of assosiation groups	int
-	multichannelSupported	Are multichannel assosiations supported	bool
-	associations	Device's assosiated devices	json
Sensor Binary	armable	Indicates if sensor could be put into armed state	bool
-	ackable	Indicates if sensor has ability to be acknowledged by user	bool
-	Armed	Is armed	bool
-	Tripped	Sensor state(true - tripped, false - idle)	bool\xB0
-	lasttrip	Last time when device was tripped (in UNIX time)	int
Sensor Multilevel	Value	Sensor value	double
-	sensorType	Sensor type (as for now, it can be one of: Temperature, Humidity, Luminance, Power)	string
-	valueScale	Sensor scale (depends on sensor type)	string
-	valueUnit	Sensor value units (depends on sensor type)	string
Shutter	stopable	Shutter's can be stopped (ignore it, ISS compatibility only)	bool
Thermostat Mode	currentMode	Current thermostat mode (one of availableModes)	string
-	availableModes	Available thermostat modes	json
Thermostat Setpoint	currentSetpoints	Current setpoints(WIP)	json
Thermostat OperatingState	currentState	Current thermostat state (WIP)	string
SwitchColor	supportedComponents	Supported color components reported by device	json array of strings,supported element variants are WarmWhite, ColdWhite, Red,Green, Blue, Amber, Cyan, Purple, Indexed
-	currentComponentValues	Values of currently supported components	json object containing key-value pairs for color components (i.e. {"Red":100, "Green":50, "Blue":"200"})

API Reference

Authentication

HTTP: Basic Auth

This is standard Basic HTTP authentication.

Every API call should contain Authorization header, value of which should be Base64-encoded combination of username, semicolon(:) and password, prepended with Basic .

For example for user with username admin and password 12345678 correct header will be:

Authorization: Basic YWRtaW46MTIzNDU2Nzg=

where YWRtaW46MTIzNDU2Nzg= is Base64-encoded admin:12345678.

Security Scheme Type:	http
HTTP Authorization Scheme:	basic

HTTP: Bearer Auth

For this method, user should acquire token with a call to POST /api/v2/auth/login using Basic Authentication

In case of success response will contain token (see reference for response format)

Every subsequent query should contain next header:

Authorization:  Bearer abcdefg1234567

where abcdefg1234567 is previously received token.

note

Access token has expiration time, when it is expired, Refresh Token should be user to acquire new one.

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer

Contact

me: