2017年3月23日 (四) 10:16的版本

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

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

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 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 an RGB(W) light to a certain color and brightness

/json.htm?type=command&param=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&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" 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&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

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

@@ 第626行： / 第626行： @@
 记得更改:
 * USERVARIABLENAME 变量名，请使用英文开头，不要用中文
-* USERVARIABLETYPE 变量类型 [[Domoticz_API/JSON_URL's#Store_a_new_variable|"Store a new variable"]]
+* USERVARIABLETYPE 变量类型 (具体类型在上方的"新建变量"中有说明)
 * USERVARIABLEVALUE 变量值