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

创建命令

创建虚拟硬件

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

之后想拿到设备id，你可以取索引中最后创建的那个id号或者在硬件页面排序获取最后一个id号：

 /json.htm?type=hardware

创建一个虚拟传感器

温湿度 (取值如下)

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

电量 (取值如下)

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

然后从列表中获得设备id号：

/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

对于RFXMeter, 还有一个请求需要设置，链接如下：

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

DEVICE_ID就是设备名，SUBTYPE_VALUE如下：

0 为能耗
1 为耗气量
2 为用水量
3 为计数

更新设备或传感器

高级应用。直接通过JSON设置设备参数。
向domoticz.db发送大量数据时一定要小心谨慎。如果参数错误或缺失可能损毁数据库
特别是Domoticz发布版（版本号小于Beta 1.1634）或稳定版（版本号小于1.1396）会更加敏感。之后发布的版本则会有更强的保护性。

首先到设备页面记住你要更改的设备的设备id号(idx)

温度

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• TEMP = 温度
  

湿度

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

以上为如何为湿度设备设置参数

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• HUM = 湿度: 45%
  
• HUM_STAT = 湿度状态
  

湿度状态为以下几种:

• 0=普通
  
• 1=舒适
  
• 2=干燥
  
• 3=潮湿
  

大气压

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

以上为如何给大气压设备设置参数

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• BAR = 大气压
  
• BAR_FOR = 气压预报
  

气压预报为以下几种:

• 0 = 无信息
  
• 1 = 晴朗
  
• 2 = 少云
  
• 3 = 多云
  
• 4 = 下雨
  

温湿度

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• TEMP = 温度
  
• HUM = 湿度
  
• HUM_STAT = 湿度状态
  

湿度状态为以下几种:

• 0=普通
  
• 1=舒适
  
• 2=干燥
  
• 3=潮湿
  

温湿气压

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

以上为如何给温湿气压设备设置参数

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• TEMP = 温度
  
• HUM = 湿度
  
• HUM_STAT = 湿度状态
  
• BAR = 大气压
  
• BAR_FOR = 气压预报
  

气压预报为以下几种:

• 0 = 无信息
  
• 1 = 晴朗
  
• 2 = 少云
  
• 3 = 多云
  
• 4 = 下雨
  

雨量

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• RAINRATE = 过去1小时雨量
• RAINCOUNTER = 持续雨量，单位毫米

风速风量

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=WB;WD;WS;WG;22;24

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• WB = 刮风方向 (0-359)
  
• WD = 刮风方位 (东南西北)
  
• WS = 10 * 风速 [m/s]
  
• WG = 10 * 阵风速 [m/s]
  
• 22 = 温度
  
• 24 = 温度指数
  

紫外强度

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• COUNTER = 紫外线度数，浮点
  
  

最后的";0"不能少 - 如果缺失将损坏数据库。

计数器

/json.htm?type=command&param=udevice&idx=IDX&svalue=COUNTER

以上为如何为计数器设备设置参数

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• COUNTER = 计数器数值（整数）
  
  

创建一个计数器之后, 可以在utility里面修改该计数器的单位。

• 电能 (kWh)
  
• 燃气 (m³)
  
• 水量 (m³)
  
• 计数器 (没有单位)
  

计数器将使用应用程序设置中设置的分段进行换算处理。 例如 "水量" 为用水量统计, 分段纸就必须设置成1000 (对应其单位 m³). 设备会显示两个值:

• 状态显示的是该设备的总值 (或者总数).
  
• 今天的值 (位于右上角).
  

今天的值（数）是总值的一部分。

电气 (触发+计数器)

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• POWER = 当前功率
  
• ENERGY = 总功耗(Wh) (如果你选择 "Energy read : Computed",那么这只是个虚拟计数器,其结果由domoticz自己计算，不能进行手动更新)
  

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)

空气质量（二氧化碳）

/json.htm?type=command&param=udevice&idx=IDX&nvalue=PPM

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• PPM = CO₂-浓度

气压计

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• BAR = 气压值

在硬件分类下创建> 硬件（Dummy)> 创建虚拟传感器

百分比

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• PERCENTAGE = 百分比

气体

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

• USAGE= 燃气用量（升）(1000 升 = 1 m³)
  

如果你的燃气表显示值为 145,332 m³ ，那么你需要发送 145332.
USAGE应为燃气用量的总计, 而不是日常使用量。

Lux照度计

/json.htm?type=command&param=udevice&idx=IDX&svalue=VALUE

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• VALUE = 光强度值（单位Lux)

电压

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• VALUE = 电压值

在硬件分类下创建> 硬件（Dummy)> 创建虚拟传感器

文本

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• TEXT = 你想要显示的文本

报警仪

/json.htm?type=command&param=udevice&idx=IDX&nvalue=LEVEL&svalue=TEXT

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• Level = (0=灰色, 1=绿色, 2=黄色, 3=橙色, 4=红色)
• TEXT = 你想显示的文字内容

距离

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• DISTANCE = 使用厘米或英寸表示，可以使用小数点。

多段开关

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

• IDX = 设备id号 (这个编号可以在设备页面“IDX”栏下找到)
• LEVEL = 多段开关的档位 (可在编辑传感器Level中查看, 0 = 关)

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