Domoticz API/JSON URL's

From Domoticz
Jump to: navigation, search

Domoticz has the ability to interact with all switches and sensors using JSON. This page will describe how to use this API.

Contents

Format

http://<username:password@>domoticz-ip<:port>/json.htm?api-call
  • <username:password@> = the username and password to access Domoticz, this is optional.
  • domoticz-ip = the IP-address or hostname of your Domoticz installation.
  • <:port> = the port number of your Domoticz installation, this is optional.
eg. http://192.168.1.2:8080/json.htm?type=command&param=udevice&idx=$idx&nvalue=0&svalue=79

Hint: You can have a look at the database for the nValue/sValue, or the .cpp code.

Making output more readable

By default, your browser will display the JSON-output in a unordered mess. To make it more readable you could use a browser plugin that formats the JSON to a more human-readable layout.
For Google Chrome you could use JSONView (Chrome web store). For other browsers a similar extension will probably exist. Look in the extensions/add-on store of your browser.

There are online sites which helps to do the same like https://jsonformatter.org. This site helps to format, tree view and validate JSON.

Authorization

When using some method other than a browser to connect to Domoticz it may be necessary to do Authorization differently. Authorization over HTTP is done by setting the "Authorization" HTTP request header when sending the request to Domoticz. The value of this header is a base64 encoded string of the username and password. When connecting to Domoticz using a browser and the URL method above the browser sets the appropriate header. When creating your own app or script this is not always done for you.

  • First the username and password are combined into one string "username:password"
  • This string is encoded using the RFC2045-MIME version of base64
  • The authorization method and a space i.e. "Basic " is then put before the encoded string.

This results in a header in the following format:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

How the header is send differs per programming language. Check the documentation of the language of your choice on how to set http request headers.

This method works with both the Basic-Auth and Login page options.

Authorization with parameters

An other way to set username and password when calling the API is :

http://domoticz-ip<:port>/json.htm?username=MkE=&password=OVM=&api-call
  • MkE= is the base64 encoded username ('2A' in this example)
  • OVM= is the base64 encoded password ('9S' in this example)

Users

When you use an user and password in this api, the user must have "user" or "admin" rights.
He also must have the right to access the device (see 'SetDevices' in users page).

Base64 encode

To encode a string using base64 you could use : codebeautify.org/base64-encode

Response

All responses include a status which is either OK on success or ERR on failure

{
   "status" : "OK"
}

General usage

Retrieve status of specific device

You can get the status of a specific device with:

/json.htm?type=devices&rid=IDX
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")

Get all devices of a certain type

/json.htm?type=devices&filter=all&used=true&order=Name

This will return information about all the devices. If you want to retrieve information for a certain devicetype, you can use the following filters:

light = Get all lights/switches
weather = Get all weather devices
temp = Get all temperature devices
utility = Get all utility devices

Get all Favorite devices

/json.htm?type=devices&used=true&filter=all&favorite=1

This will return only devices that are tagged as Favorite.

Get sunrise and sunset times

/json.htm?type=command&param=getSunRiseSet
{
   "ServerTime" : "Sep 30 2013 17:15:21",
   "Sunrise" : "07:38:00",
   "Sunset" : "19:16:00",
   "status" : "OK",
   "title" : "getSunRiseSet"
}

Add a log message to the Domoticz log

You can add a log message to the system with:

/json.htm?type=command&param=addlogmessage&message=MESSAGE
  • MESSAGE = a string you want to log

Use Notification Subsystem

You can post a notification to all enabled notification systems with:

/json.htm?type=command&param=sendnotification&subject=SUBJECT&body=THEBODY

You can post a notification to a specific notification system with:

/json.htm?type=command&param=sendnotification&subject=SUBJECT&body=THEBODY&subsystem=SUBSYSTEM
  • SUBJECT = a string you want to use as subject
  • THEBODY= a string you want to use as body
  • SUBSYSTEM= the notification method you want to use
gcm
http
kodi
lms
nma
prowl
pushalot
pushbullet
pushover
pushsafer

Lights and switches

Get all lights/switches

/json.htm?type=command&param=getlightswitches

OR

 /json.htm?type=devices&filter=light&used=true&order=Name

Example output:


{
   "result" : [
      {
         "IsDimmer" : false,
         "Name" : "Bedroom lights",
         "SubType" : "Energenie",
         "Type" : "Lighting 1",
         "idx" : "43"
      },
      {
         "IsDimmer" : false,
         "Name" : "Hall",
         "SubType" : "Energenie",
         "Type" : "Lighting 1",
         "idx" : "30"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge Light Front",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "32"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge Lights All",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "66"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge light back",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "33"
      }
   ],
   "status" : "OK",
   "title" : "GetLightSwitches"
}

Turn a light/switch on

/json.htm?type=command&param=switchlight&idx=99&switchcmd=On

Turn a light/switch off

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Off
  • idx = id of your device (in this example 99).
  • switchcmd = "On" or "Off" (case sensitive!)


{
   "status" : "OK",
   "title" : "SwitchLight"
}

beware that if the switch has the 'protected' attribute set then you need add key `passcode` (with the right passcode)

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Off&passcode=YOUR_SWITCH_PASSWORD_AS_SET_IN_SETTINGS

or the status will be

{  
   "message" : "WRONG CODE",
   "status" : "ERROR",
   "title" : "SwitchLight"
}

Set a dimmable light to a certain level

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Set%20Level&level=6
  • Some lights have 100 dim levels (like zwave and others), other hardware (kaku/lightwaverf) have other ranges like 16/32
  • Level should be the dim level (not percentage), like 0-16 or 0-100 depending on the hardware used
  • When the light is off, it will be turned on
{
   "status" : "OK",
   "title" : "SwitchLight"
}

Set a light to a certain color or color temperature

Color can be specified as either hue + brightness, RGB + optional brightness or a Domoticz JSON color object

Specify hue and brightness
Hue in degrees, 0..360
Brightness 0..100
/json.htm?type=command&param=setcolbrightnessvalue&idx=99&hue=274&brightness=40&iswhite=false
Note: There is no saturation parameter, specify RGB format Domoticz JSON color format for full color control
Specify RGB and brightness (optional)
RGB as hexadecimal number, RRGGBB without prefix (no 0x or #)
/json.htm?type=command&param=setcolbrightnessvalue&idx=99&hex=RRGGBB&brightness=100&iswhite=false
Note: The actual brightness of the light is a combination of RGB value and brightness. Brightness parameter may be omitted.
A site like colorhexa can be used to help pick hex values according to desired colours.
Specify Domoticz JSON color object and brightness
Example: Specify color mode with a dim blue color
/json.htm?type=command&param=setcolbrightnessvalue&idx=130&color={"m":3,"t":0,"r":0,"g":0,"b":50,"cw":0,"ww":0}&brightness=100

Domoticz color format:

Domoticz color format is used as:

  • input parameter to:
    - setcolbrightnessvalue
    - updatetimer
    - addtimer
    - addscenedevice
    - updatescenedevice
  • In response from:
    - devices
    - getscenedevices
    - timers

Example: color={"m":3,"t":0,"r":0,"g":0,"b":50,"cw":0,"ww":0}

ColorMode {
	ColorModeNone = 0,   // Illegal
	ColorModeWhite = 1,  // White. Valid fields: none
	ColorModeTemp = 2,   // White with color temperature. Valid fields: t
	ColorModeRGB = 3,    // Color. Valid fields: r, g, b.
	ColorModeCustom = 4, // Custom (color + white). Valid fields: r, g, b, cw, ww, depending on device capabilities
	ColorModeLast = ColorModeCustom,
};

Color {
	ColorMode m;
	uint8_t t;     // Range:0..255, Color temperature (warm / cold ratio, 0 is coldest, 255 is warmest)
	uint8_t r;     // Range:0..255, Red level
	uint8_t g;     // Range:0..255, Green level
	uint8_t b;     // Range:0..255, Blue level
	uint8_t cw;    // Range:0..255, Cold white level
	uint8_t ww;    // Range:0..255, Warm white level (also used as level for monochrome white)
}

Set an RGB_CW_WW or CW_WW light to a certain color temperature

/json.htm?type=command&param=setkelvinlevel&idx=99&kelvin=1
Range of kelvin parameter: 0..100, 0 is coldest, 100 is warmest

Toggle a switch state between on/off

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Toggle
{
   "status" : "OK",
   "title" : "SwitchLight"
}

Scenes / Groups

Get all the scenes & groups

/json.htm?type=scenes

Example output:

{
   "result" : [
      {
         "Favorite" : 1,
         "HardwareID" : 0,
         "LastUpdate" : "2013-09-29 19:11:01",
         "Name" : "My Scene",
         "Status" : "Off",
         "Timers" : "true",
         "Type" : "Scene",
         "idx" : "9"
      },
      {
         "Favorite" : 1,
         "HardwareID" : 0,
         "LastUpdate" : "2013-09-30 11:49:13",
         "Name" : "My Group",
         "Status" : "Off",
         "Timers" : "false",
         "Type" : "Group",
         "idx" : "3"
      }
   ],
   "status" : "OK",
   "title" : "Scenes"
}

Turn a scene / group on or off

/json.htm?type=command&param=switchscene&idx=&switchcmd=
  • idx = id of your scene/group.
  • switchcmd = "On", "Off" or "Toggle" (case sensitive!)
  • Scenes can only be turned On
{
   "status" : "OK",
   "title" : "SwitchScene"
}

Add a scene (0)

/json.htm?type=addscene&name=scenename&scenetype=0

Add a group (1)

/json.htm?type=addscene&name=scenename&scenetype=1

Delete a scene or group

/json.htm?type=deletescene&idx=number

List devices in a scene

/json.htm?type=command&param=getscenedevices&idx=number&isscene=true

Add device to a scene

/json.htm?type=command&param=addscenedevice&idx=number&isscene=true&devidx=deviceindex&command=1&level=number&hue=number

Delete device from a scene

/json.htm?type=command&param=deletescenedevice&idx=number

List timers of a scene

/json.htm?type=scenetimers&idx=number

Example output:

{
   "result" : [
      {
         "Active" : "true",
         "Cmd" : 0,
         "Date" : "07-02-2016",
         "Days" : 128,
         "Hue" : 0,
         "Level" : 100,
         "Randomness" : true,
         "Time" : "00:01",
         "Type" : 5,
         "idx" : "16"
      }
   ],
   "status" : "OK",
   "title" : "SceneTimers"
}

Add timer to a scene

/json.htm?type=command&param=addscenetimer&idx=number&active=&timertype=&date=&hour=&min=&randomness=&command=&level=&days=
  • idx = index of your scene/group.
  • active = true/false
  • timertype = 0 = Before Sunrise, 1 = After Sunrise, 2 = On Time, 3 = Before Sunset, 4 = After Sunset, 5 = Fixed Date/Time
  • date = MM-DD-YYYY
  • hour = hour
  • min = minute
  • randomness = true/false
  • command = On/Off
  • level = 0..100 (%)
  • days = 0x80 = Everyday, 0x100 = Weekdays, 0x200 = Weekends, 0x01 = Mon, 0x02 = Tue, 0x04 = Wed, 0x08 = Thu, 0x10 = Fri, 0x20 = Sat, 0x40 = Sun

Server control

Shutdown system

/json.htm?type=command&param=system_shutdown
{
   "status" : "OK",
   "title" : "SystemShutdown"
}

Reboot system

/json.htm?type=command&param=system_reboot
{
   "status" : "OK",
   "title" : "SystemReboot"
}

Create commands

Create virtual hardware

/json.htm?type=command&param=addhardware&htype=15&port=1&name=Sensors1&enabled=true

afterward to get the id, either you have your last created id from an index you maintain or sort the hardware page for last ID:

 /json.htm?type=hardware

Create a virtual sensor

Temp+Humidity (see below for values)

/json.htm?type=createvirtualsensor&idx=29&sensorname=TempHum&sensortype=82

Electricity (see below for values)

/json.htm?type=createvirtualsensor&idx=29&sensorname=Energy&sensortype=90

and then get the device id from the list:

/json.htm?type=devices&filter=all&used=true&order=Name
1 Pressure (Bar) 0.0 	      	     nvalue=BAR (TBC)        
2 Percentage     0.0 	      	     nvalue=PCT (TBC)	        
80 TEMP          0.0     	     svalue=TEMP
81 HUM           1		     nvalue=HUM svalue=1 to 3
82 TEMP_HUM      0.0;50;1 	     svalue=TEMP;HUM;HUM_STATUS
84 TEMP_HUM_BARO 0.0;50;1;1010;1    svalue=TEMP;HUM;HUM_STATUS;BARO;BARO_FCST
85 RAIN          0;0		     svalue=RAIN;Rain in mm/h
86 WIND          0;N;0;0;0;0  	     svalue=WIN_SPD;WIND_DIR;?;?;?;?
87 UV            0;0		     svalue= (TBC)
113 RFXMeter     0		     Can have several values, another order has to be sent to set the sub type:	   
							type 3	Counter:   svalue=COUNTER
							type 2	Water:	   svalue=VOLUME
							type 1	Gas:
							type 0	Energy:
90 ENERGY        0;0.0		     svalue=POWER;ENERGY
249 TypeAirQuality    0	     nvalue=PPM

For the RFXMeter, another request is needed to set the utility, url is:

/json.htm?type=setused&idx=DEVICE_ID&name=RFXMeter&switchtype=SUBTYPE_VALUE&used=true

where DEVICE_ID is the device name, and the SUBTYPE_VALUE is one of:

0 for Energy
1 for Gas
2 for Water
3 for Counter

Create a device

Temp (Type: pTypeTEMP, subType: sTypeTEMP5)

/json.htm?type=createdevice&idx=29&sensorname=Temp5&devicetype=50&devicesubtype=5

Voltage (Type: pTypeGeneral, subType: sTypeVoltage)

/json.htm?type=createdevice&idx=29&sensorname=Voltage0&devicetype=243&devicesubtype=8

Update devices/sensors

Expert usage. Directly set device parameters via JSON.
Be very carefully when firing values to domoticz.db. There is a chance to crash the database if parameters are wrong or missing.
Especially Domoticz release <=Beta 1.1634 or stable <=1.1396 are more sensitive. Later releases will have more protection.

First go to the devices tab and notice the device index (idx) of the device you want to change

Temperature

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEMP = Temperature


Humidity

/json.htm?type=command&param=udevice&idx=IDX&nvalue=HUM&svalue=HUM_STAT

The above sets the parameters for a Humidity device

  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • HUM = Humidity: 45%
  • HUM_STAT = Humidity_status


Humidity_status can be one of:

  • 0=Normal
  • 1=Comfortable
  • 2=Dry
  • 3=Wet


Barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=BAR;BAR_FOR

The above sets the parameters for a Barometer device from hardware type 'General'

  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • BAR = Barometric pressure
  • BAR_FOR = Barometer forecast


Barometer forecast can be one of:

  • 0 = Stable
  • 1 = Sunny
  • 2 = Cloudy
  • 3 = Unstable
  • 4 = Thunderstorm


Temperature/humidity

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;HUM;HUM_STAT
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEMP = Temperature
  • HUM = Humidity (0-100 %)
  • HUM_STAT = Humidity status


HUM_STAT can be one of:

  • 0=Normal
  • 1=Comfortable
  • 2=Dry
  • 3=Wet


Temperature/humidity/barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;HUM;HUM_STAT;BAR;BAR_FOR

The above sets the parameters for a Temp+Humidity+Barometer device

  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEMP = Temperature
  • HUM = Humidity
  • HUM_STAT = Humidity status
  • BAR = Barometric pressure
  • BAR_FOR = Barometer forecast


Barometer forecast can be one of:

  • 0 = No info
  • 1 = Sunny
  • 2 = Partly cloudy
  • 3 = Cloudy
  • 4 = Rain


Temperature/barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;BAR;BAR_FOR;ALTITUDE

The above sets the parameters for a Temp+Humidity+Barometer device

  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEMP = Temperature
  • BAR = Barometric pressure
  • BAR_FOR = Barometer forecast
  • ALTITUDE= Not used at the moment, can be 0


Barometer forecast can be one of:
0 = No Info
1 = Sunny
2 = Paryly Cloudy
3 = Cloudy
4 = Rain

Rain

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=RAINRATE;RAINCOUNTER
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • RAINRATE = amount of rain in last hour in [mm x 100]
  • RAINCOUNTER = continues counter of fallen Rain in [mm]

Soil Moisture

/json.htm?type=command&param=udevice&idx=IDX&nvalue=MOISTURE
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • MOISTURE = moisture content in cb 0-200 where:

00 - 09 = saturated, 10 - 19 = adequately wet, 20 - 59 = irrigation advice, 60 - 99 = irrigation, 100-200 = Dangerously dry,

Wind

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=WB;WD;WS;WG;22;24
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • WB = Wind bearing (0-359)
  • WD = Wind direction (S, SW, NNW, etc.)
  • WS = 10 * Wind speed [m/s]
  • WG = 10 * Gust [m/s]
  • 22 = Temperature
  • 24 = Temperature Windchill

UV

 /json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=UV;TEMP
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • UV = Float (example: 2.1) with current UV reading.

  • TEMP = temperature (only for UV subtype TFA (3), else specify 0)

Don't loose the ";0" at the end - without it database may corrupt.

If no temp is in use, specify 0 as temperature

Counter

/json.htm?type=command&param=udevice&idx=IDX&svalue=COUNTER
  • IDX = id of your device (this number can be found in the devices tab in the column "IDX")
  • COUNTER = Integer of the overall total volume.

When there is a counter created, there is a possibility to change the units by clicking on "Change" at the utility tab.

  • Energy (kWh)
  • Gas (m3)
  • Water (m3)
  • Counter (no unit)

The counter will be treated with the divider which is defined in the parameters in the application settings. For example if the counter is set to "Water" and the value is passed as liters, the divider must set to 1000 (as the unit is m3). The device displays 2 values:

  • The status is the overall total volume (or counter).
  • The volume (or counter) of the day (in the top right corner).

The today's volume (or counter) is calculated from the total volume (or counter).

Electricity (instant and counter)

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=POWER;ENERGY
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • POWER = current power
  • ENERGY = cumulative energy in Watt-hours (Wh) This is an incrementing counter. (if you choose as type "Energy read : Computed", this is just a "dummy" counter, not updatable because it's the result of DomoticZ calculs from POWER)

Electricity Current/Ampere 3 Phase

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=Ampere_1;=Ampere_2;=Ampere_3;
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • Ampere_1 = Ampere value Phase 1
  • Ampere_2 = Ampere value Phase 2
  • Ampere_3 = Ampere value Phase 3

Electricity P1 smart meter

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE1;USAGE2;RETURN1;RETURN2;CONS;PROD
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • USAGE1= energy usage meter tariff 1, This is an incrementing counter
  • USAGE2= energy usage meter tariff 2, This is an incrementing counter
  • RETURN1= energy return meter tariff 1, This is an incrementing counter
  • RETURN2= energy return meter tariff 2, This is an incrementing counter
  • CONS= actual usage power (Watt)
  • PROD= actual return power (Watt)

USAGE and RETURN are counters (they should only count up).
For USAGE and RETURN supply the data in total Wh with no decimal point.
(So if your meter displays f.i. USAGE1= 523,66 KWh you need to send 523660)

Air quality

/json.htm?type=command&param=udevice&idx=IDX&nvalue=PPM
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • PPM = CO2-concentration

Pressure

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=BAR
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • BAR = Pressure in Bar

Create sensor under Hardware > Dummy > Create virtual sensor

Percentage

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=PERCENTAGE
  • IDX = id of your device (this number can be found in the devices tab in the column "IDX")
  • PERCENTAGE = Percentage

Visibility

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VISIBILITY
  • IDX = id of your device (this number can be found in the devices tab in the column "IDX")
  • VISIBILITY = in KM

Gas

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE
  • USAGE= Gas usage in liter (1000 liter = 1 m³)

So if your gas meter shows f.i. 145,332 m³ you should send 145332.
The USAGE is the total usage in liters from start, not f.i. the daily usage.

Lux

/json.htm?type=command&param=udevice&idx=IDX&svalue=VALUE
  • IDX = device ID of Lux device
  • VALUE = value of luminosity in Lux (INTEGER/FLOAT)

Voltage

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VOLTAGE
  • IDX = device ID of Voltage device
  • VALUE = value of voltage sensor in Volts

Create sensor under Hardware > Dummy > Create virtual sensor

Text sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEXT
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • TEXT = Text you want to display

Alert sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=LEVEL&svalue=TEXT
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • Level = (0=gray, 1=green, 2=yellow, 3=orange, 4=red)
  • TEXT = Text you want to display

Distance sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=DISTANCE
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • DISTANCE = distance in cm or inches, can be in decimals. For example 12.6

Selector Switch

/json.htm?type=command&param=switchlight&idx=IDX&switchcmd=Set%20Level&level=LEVEL
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • LEVEL = level of your selector (This number can be found in the edit selectors page, in the column "Level", 0 = Off)

Custom Sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VALUE
  • IDX = id of your device (This number can be found in the devices tab in the column "IDX")
  • VALUE = Value (like 12.345)


Additional parameters (signal level & battery level)

There are two additional parameters for the above commands, to specify the signal level (default 12) and the battery level (default 255)

battery level 255 = no battery device, else 0-100
example: &rssi=10&battery=89

User variables

Store a new variable

json.htm?type=command&param=saveuservariable&vname=uservariablename&vtype=uservariabletype&vvalue=uservariablevalue

Where type is 0 to 4:

0 = Integer, e.g. -1, 1, 0, 2, 10 
1 = Float, e.g. -1.1, 1.2, 3.1
2 = String
3 = Date in format DD/MM/YYYY
4 = Time in 24 hr format HH:MM
5 = DateTime (but the format is not checked)

All formats (except 5) are checked by the api, when the variable does not match the required format it is not stored.

Update an existing variable

/json.htm?type=command&param=updateuservariable&vname=USERVARIABLENAME&vtype=USERVARIABLETYPE
&vvalue=USERVARIABLEVALUE

Remember to change:

  • USERVARIABLENAME with the name of your variable
  • USERVARIABLETYPE according to the table from "Store a new variable"
  • USERVARIABLEVALUE with the new value

List all variables

/json.htm?type=command&param=getuservariables

List one variable

/json.htm?type=command&param=getuservariable&idx=IDX
  • IDX = id of your variable (This number can be found using the "List all variables" call above)

Delete a variable

/json.htm?type=command&param=deleteuservariable&idx=IDX
  • IDX = id of your variable (This number can be found using the "List all variables" call above)


Room Plans

List all rooms

/json.htm?type=plans&order=name&used=true

List all devices in a room

/json.htm?type=command&param=getplandevices&idx=IDX
  • IDX = id of your room

History

Switch

/json.htm?type=lightlog&idx=IDX

Temperature

/json.htm?type=graph&sensor=temp&idx=IDX&range=day
/json.htm?type=graph&sensor=temp&idx=IDX&range=month
/json.htm?type=graph&sensor=temp&idx=IDX&range=year

Setpoint

See Temperature

Energy, Gas, Water

Instantaneous consumption :

/json.htm?type=graph&sensor=counter&idx=IDX&range=day&method=1

Totals by period :

/json.htm?type=graph&sensor=counter&idx=IDX&range=day  
/json.htm?type=graph&sensor=counter&idx=IDX&range=month
/json.htm?type=graph&sensor=counter&idx=IDX&range=year

Device Timer Schedules

Get all schedules (timers)

../json.htm?type=schedules

Typical result :

{
   "result" : [
      {
         "Active" : "true",
         "Date" : "",
         "Days" : 128,
         "DevName" : "Porch Light",
         "DeviceRowID" : 52,
         "Hue" : 0,
         "IsThermostat" : "false",
         "Level" : 100,
         "MDay" : 0,
         "Month" : 0,
         "Occurence" : 0,
         "Randomness" : "false",
         "ScheduleDate" : "2016-04-01 20:33:00",
         "Time" : "00:20",
         "TimerCmd" : 0,
         "TimerID" : 9,
         "TimerType" : 4,
         "TimerTypeStr" : "After Sunset",
         "Type" : "Device"
      },

Get all schedules(timers) for Devices

../json.htm?type=schedules&filter=device

Get all schedules(timers) for Scenes

../json.htm?type=schedules&filter=scene

Get all schedules(timers) for Thermostats

../json.htm?type=schedules&filter=thermostat

Enable specific schedule(timer)

../json.htm?type=command&param=enabletimer&idx=timerID

Disable specific schedule(timer)

../json.htm?type=command&param=disabletimer&idx=timerID

Delete a specific schedule(timer)

../json.htm?type=command&param=deletetimer&idx=timerID

Update parameters for a specific schedule(timer)

../json.htm?type=command&param=updatetimer&idx=timerID&active=true&timertype=3&hour=0&min=20&randomness=true&command=0&days=12345
  • idx = timerID
  • active = true/false
  • timertype = 0 = Before Sunrise, 1 = After Sunrise, 2 = On Time, 3 = Before Sunset, 4 = After Sunset, 5 = Fixed Date/Time
  • hour = hour
  • min = minute
  • randomness = true/false
  • command = On=0 / Off=1 (inverted logic)
  • days = 1=Mon, 2=Tue, 3=Wed, 4=Thurs, 5=Fri, 6=Sat, 7=Sun

Create a new schedule(timer) for an existing device

../json.htm?type=command&param=addtimer&idx=DeviceRowID&active=true&timertype=2&hour=0&min=20&randomness=false&command=0&days=1234567
  • idx = DeviceRowID = index of your device (other commands use a timerID as idx but here we use DeviceRowID).
  • active = true/false
  • timertype = 0 = Before Sunrise, 1 = After Sunrise, 2 = On Time, 3 = Before Sunset, 4 = After Sunset, 5 = Fixed Date/Time
  • hour = hour
  • min = minute
  • randomness = true/false
  • command = On=0 / Off=1 (inverted logic)
  • days = 1=Mon, 2=Tue, 3=Wed, 4=Thurs, 5=Fri, 6=Sat, 7=Sun

Clear all schedules(timers) for a particular device

../json.htm?type=command&param=cleartimers&idx=DeviceRowID
  • idx = DeviceRowID = index of your device (other commands use a timerID as idx but here we use DeviceRowID).