Domoticz API及JSON网址
Domoticz可以通过API接收JSON数据来影响开关或传感器。本页面介绍如何使用Domoticz API。
格式
http://<username:password@>domoticz-ip<:port>/json.htm?api请求
- <username:password@> = 登录Domoticz的用户名及密码，可选。
- domoticz-ip = Domoticz服务器的IP或域名。
- <:port> = Domoticz服务器的端口号，可选。
例如 http://192.168.1.2:8080/json.htm?type=command¶m=udevice&idx=3&nvalue=0&svalue=21
提示: 你可以通过数据库查看nValue/sValue
使输出更易读
默认情况下，浏览器返回的json数据都在一行，可读性很差。你可以安装浏览器扩展来格式化json，使其排列整齐。
例如谷歌Chrome浏览器可以使用JSONView (Chrome商店)。其它浏览器也都有类似插件。
授权
当使用浏览器以外的方法连接到Domoticz时，可能需要以不同的方式进行授权。 通过HTTP授权，需要在HTTP请求头中设置"Authorization"。请求头的值是经过base64编码的用户名和密码。当使用浏览器访问Domoticz时，浏览器会自动设置好请求头信息。当你使用自建应用或者脚本时，请求头需要单独设置。
- 首先，用户名及密码放到一个字符串中："username:password"
- 此字符串使用RFC2045-MIME版base64编码
- 编码后的字符串前要加入授权方式及一个空格，例如"Basic "。
最后的请求头信息格式如下:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
请求头的发送方式跟所用编程语言相关。具体如何发送HTTP请求头，请查看你所用编程语言的文档。
此方法同时适用于Basic-Auth及登录页面选项。
返回
所有返回信息都包含一个status状态，成功时返回OK，失败时返回ERR
{
"status" : "OK"
}
一般用法
检索特定设备的状态
查看特定设备的状态使用:
/json.htm?type=devices&rid=IDX
- IDX = 设备编号 (可以通过Domoticz网页中的设备页查看，列名为"IDX")
获取某种类型的所有设备
/json.htm?type=devices&filter=all&used=true&order=Name
此链接返回所有设备信息。如果想获取特定类型的设备信息，可以为"filter"设置以下关键字:
light = 获取所有照明、开关设备 weather = 获取所有天气设备 temp = 获取所有温度设备 utility = 获取所有附加设备
获取所有收藏的设备
/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¶m=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¶m=addlogmessage&message=MESSAGE
- MESSAGE = a string you want to log
Lights and switches
Get all lights/switches
/json.htm?type=command¶m=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¶m=switchlight&idx=99&switchcmd=On
Turn a light/switch off
/json.htm?type=command¶m=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 the status will be
{
"message" : "WRONG CODE",
"status" : "ERROR",
"title" : "SwitchLight"
}
Set a dimmable light to a certain level
/json.htm?type=command¶m=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 an RGB(W) light to a certain color and brightness
/json.htm?type=command¶m=setcolbrightnessvalue&idx=99&hue=274&brightness=40&iswhite=false
- Tested on Fibaro RGBW and Hue
Toggle a switch state between on/off
/json.htm?type=command¶m=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¶m=switchscene&idx=&switchcmd=
- idx = id of your scene/group.
- switchcmd = "On" or "Off" (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¶m=getscenedevices&idx=number&isscene=true
Add device to a scene
/json.htm?type=command¶m=addscenedevice&idx=number&isscene=true&devidx=deviceindex&command=1&level=number&hue=number
Delete device from a scene
/json.htm?type=command¶m=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¶m=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¶m=system_shutdown
{
"status" : "OK",
"title" : "SystemShutdown"
}
Reboot system
/json.htm?type=command¶m=system_reboot
{
"status" : "OK",
"title" : "SystemReboot"
}
Create commands
Create virtual hardware
/json.htm?type=command¶m=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
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¶m=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¶m=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¶m=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 = No info
- 1 = Sunny
- 2 = Partly cloudy
- 3 = Cloudy
- 4 = Rain
Temperature/humidity
/json.htm?type=command¶m=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
- 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¶m=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
Rain
/json.htm?type=command¶m=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
- RAINCOUNTER = continues counter of fallen Rain in mm
Wind
/json.htm?type=command¶m=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¶m=udevice&idx=IDX&nvalue=0&svalue=COUNTER;0
- IDX = id of your device (This number can be found in the devices tab in the column "IDX")
- COUNTER = Float (in example: 2.1) with current UV reading.
Don't loose the ";0" at the end - without it database may corrupt.
Counter
/json.htm?type=command¶m=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¶m=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) (if you choose "Energy read : Computed", this is just a "dummy" counter, not updatable because it's the result of DomoticZ calculs from POWER)
Electricity P1 smart meter
/json.htm?type=command¶m=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
- USAGE2= energy usage meter tariff 2
- RETURN1= energy return meter tariff 1
- RETURN2= energy return meter tariff 2
- 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¶m=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¶m=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¶m=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
Gas
/json.htm?type=command¶m=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¶m=udevice&idx=IDX&svalue=VALUE
- IDX = device ID of Lux device
- VALUE = value of luminosity in Lux
Voltage
/json.htm?type=command¶m=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¶m=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¶m=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¶m=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¶m=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¶m=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¶m=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¶m=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¶m=getuservariables
List one variable
/json.htm?type=command¶m=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¶m=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¶m=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
Not yet documented
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¶m=enabletimer&idx=timerID
Disable specific schedule(timer)
../json.htm?type=command¶m=disabletimer&idx=timerID