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&param=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

此链接仅返回标记为收藏的设备。

获取日出日落时间

/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"
}

添加一条日志信息至Domoticz日志

用以下链接添加一条信息至系统日志：

/json.htm?type=command&param=addlogmessage&message=MESSAGE

• MESSAGE = 你想记录的日志信息

灯光与开关

== ==获取所有灯光与开关

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

或

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

输出范例：

{
   "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"
}

开启灯光或开关

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

关闭灯光或开关

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

• idx = 设备的id号 (这个例子中是99).
• switchcmd = "On" or "Off" (大小写敏感！)

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

请注意如果开关被设置了“保护”那么状态会显示如下

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

把调光灯设置到某一亮度

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Set%20Level&level=6

• 有限调光灯调光范围有100级（zwave等），其他设备（kaku或lightwaverf）可能只有16或32级。
• 调光级数必须是绝对的级数不能是百分数，如0-16级或0-100级，这取决于你的硬件。
• 当灯是关闭状态时，调光会把灯打开

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

设置七彩灯（调光）RGB(W)至某一颜色或亮度

/json.htm?type=command&param=setcolbrightnessvalue&idx=99&hue=274&brightness=40&iswhite=false

• Fibaro RGBW与Hue已测试

开关状态切换

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

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

场景与组别

获取所有场景与组别

/json.htm?type=scenes

输出范例：

{
   "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"
}

场景与组别的开关

/json.htm?type=command&param=switchscene&idx=&switchcmd=

• idx = 场景或组别的id号
• switchcmd = "On" or "Off" (大小写敏感！)
• 场景类的只能开不能关

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

添加一个场景(0)

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

添加一个组别(1)

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

删除一个场景或组别

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

列表显示某场景里的所有设备

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

添加设备至一个场景

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

从一个场景中删除设备

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

列表显示一个场景中所有定时器

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

输出范例：

{
   "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"
}

添加定时器至一个场景

/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

服务器控制

关闭系统

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

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

重启系统

/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

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 = No info
  
• 1 = Sunny
  
• 2 = Partly cloudy
  
• 3 = Cloudy
  
• 4 = Rain
  

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
  
• 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
  

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
• RAINCOUNTER = continues counter of fallen Rain in mm

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=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&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 (m³)
  
• Water (m³)
  
• 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 m³). 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) (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&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
• 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&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 = CO₂-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

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

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

用户变量

新建变量

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

记得更改:

• USERVARIABLENAME 变量名，请使用英文开头，不要用中文
• USERVARIABLETYPE 变量类型
• USERVARIABLEVALUE 变量值

变量类型：

0 = 整数, 例如 -1, 1, 0, 2, 10 
1 = 浮点数, 例如 -1.1, 1.2, 3.1
2 = 字符串
3 = 日期 DD/MM/YYYY
4 = 时间 HH:MM
5 = 日期时间 (但不检查格式)

api会检测所有类型的数据格式(除了5), 当传入数据格式不正确时，数据不会被保存。

更新已有变量

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

记得更改:

• USERVARIABLENAME 变量名，请使用英文开头，不要用中文
• USERVARIABLETYPE 变量类型 (具体类型在上方的"新建变量"中有说明)
• USERVARIABLEVALUE 变量值

列出所有变量

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

列出某一变量

/json.htm?type=command&param=getuservariable&idx=IDX

• IDX = 变量编号 (可以通过上面的"列出所有变量"来获取，也可以通过Domoticz网页设置中的用户变量查看)

删除变量

/json.htm?type=command&param=deleteuservariable&idx=IDX

• IDX = 变量编号 (可以通过上面的"列出所有变量"来获取，也可以通过Domoticz网页设置中的用户变量查看)

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

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&param=enabletimer&idx=timerID

Disable specific schedule(timer)

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