Domoticz Wiki - User contributions [en]

Domoticz API/JSON URL's

2024-11-12T17:25:20Z

Philchillbill: /* Specifying a date/time for zone TemporaryOverride */

Domoticz allows you to interact with all your switches and sensors using JSON, either interactively through a browser or programmatically from a scripting language. In fact, when you interact with the Domoticz UI through your browser by clicking on buttons and such, under the hood it's JSON that actually communicates your changes back to the Domoticz engine (Hint: You can watch this behaviour at any time by enabling '''developer tools''' in your browser and watching the ''network'' tab's traffic when you change something through the UI. See the section on ''changing a zwave device parameter'' for an example, with screenshot). This wiki describes how to use this versatile API. 

==Warning Stable 2023.2 (and newer)==
For users using API calls from outside Domoticz there has been some changes in API calls. They now always should be of the form <code>/json.htm?type=command&param=**command**</code>

For example

<code>/json.htm?type=graph</code> will be <code>/json.htm?type=command&param=graph</code>

<code>/json.htm?type=devices</code> will be <code>/json.htm?type=command&param=getdevices</code>

More info in Forum topic https://www.domoticz.com/forum/viewtopic.php?p=303581#p303581

The following old RType commands will keep working but will give a deprecation warning eg

<code>[WebServer] Deprecated RType (devices) for API request. Handled via fallback (getdevices), please use correct API Command! (IP nnn.nnn.nnn.nnn)</code>

'''/json.htm?type=**old command** -> /json.htm?type=command&param=**new command**'''

*"settings" -> "getsettings"
*"users" -> "getusers";
*"devices" -> "getdevices"
*"hardware" -> "gethardware";
*<s>"events" -> "events"</s>
*"notifications" -> "getnotifications"
*"createdevice" -> "createdevice"
*"scenes" -> "getscenes";
*"plans" -> "getplans"
*"graph" -> "graph"
*"scenelog" -> "getscenelog"
*"mobiles" -> "getmobiles"
*"cameras"-> "getcameras"
*"cameras_user" -> "getcameras_user"
*"schedules" -> "getschedules"
*"timers" -> "gettimers"
*"scenetimers" -> "getscenetimers"
*"setpointtimers" -> "getsetpointtimers"
*"plans" -> "getplans"
*"floorplans" -> "getfloorplans"
*"lightlog" -> "getlightlog"
*"textlog" -> "gettextlog"
*"setused" -> "setused"

The following old RType command has no fallback:

*"/json.htm?type=events"

The updated syntax is "''/json.htm?type=command&param=events&'''evparam=<eventsparam>'''''"

=Format=

<nowiki>http://<username:password@>domoticz-ip<:port>/json.htm?api-call</nowiki>

*<username:password@> = the username and password to access Domoticz, this is optional, see the [[Security]] page for details setting up login.
*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, most browser will display the JSON-output in a unordered mess, but some (like FireFox) will recognize it is JSON and show it in a readable manner. 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 [https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc 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:
<source lang="json">Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==</source>

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.

==Users==
When you use an user and password in this api, the user must have "user" or "admin" rights. See also page [[User Management]] 
The user also must have the right to access the device (see 'Set Devices' in Edit Users page).

==Base64 encode==
To encode a string using base64 you could use : [https://codebeautify.org/base64-encode codebeautify.org/base64-encode]

==Response==
All responses include a status which is either '''OK''' on success or '''ERR''' on failure
<source lang="json">{
"status" : "OK"
}</source>

=General usage=

Please note that many characters are not permitted in URL strings, including spaces, brackets, etc. Depending on which options below you are using, it may be necessary to '''URL encode''' the string first. This is also called URI-encoding, escaping or percent-encoding. See [https://www.url-encode-decode.com URL encode/decode].

As an example, the string:

This is a test ! (Really)

when properly encoded, looks like this

This%20is%20a%20test%20%21%20%28Really%29

It's also allowable to use a '+' instead of '%20' to encode spaces (this is normally reserved for HTML forms processing but Domoticz accepts both).

==A note on IDXes==
There are different categories of IDX values, such as for devices, for scenes, for timers, for hardware devices, etc. Make sure that you are using the correct IDX value when trying the commands below. Device IDXes can be found by looking at the ''Setup --> Devices'' tab in the UI. Similarly, ''Setup --> Hardware'' will list the hardware category IDXes. See the section(s) on ''scenes'' and ''timers/schedules'' below to see how to retrieve their particular IDXes or timerIDs using JSON.

==Retrieve status of Domoticz instance==

You can get the status of a Domoticz instance with:

/json.htm?type=command&param=getversion
<source lang="json">{
"DomoticzUpdateURL": "http://www.domoticz.com/download.php?channel=beta&type=release&system=linux&machine=armv7l",
"HaveUpdate": false,
"Revision": 9540,
"SystemName": "linux",
"UseUpdate": true,
"build_time": "2018-05-29 14:27:24",
"dzvents_version": "2.4.6",
"hash": "30295913",
"python_version": "3.5.3 (default, Jan 19 2017, 14:11:04) \n[GCC 6.3.0 20170124]",
"status": "OK",
"title": "GetVersion",
"version": "3.9530"
}</source>

'''From Stable 2023.2''' (7-jun-2023) when a request is done without any authorisation, only the following is returned:
<code>{
"status" : "OK",
"title" : "GetVersion"
}</code>
When requested by a (non-admin) User, it gives (''which is the current default response for users''):
<code>{
"HaveUpdate" : false,
"UseUpdate" : false,
"build_time" : "2023-06-04 16:08:09",
"dzvents_version" : "3.1.8",
"hash" : "98a7d1eef-modified",
<nowiki> "python_version" : "3.8.10 (default, Nov 14 2022, 12:59:47) \n[GCC 9.4.0]",</nowiki>
"status" : "OK",
"title" : "GetVersion",
"version" : "2023.1 (build 15331)"
}</code>
And for admins
<code>{
"DomoticzUpdateURL" : "<nowiki>https://www.domoticz.com/download.php?channel=stable&type=release&system=linux&machine=x86_64</nowiki>",
"HaveUpdate" : false,
"Revision" : 15091,
"SystemName" : "linux",
"UseUpdate" : true,
"build_time" : "2023-06-04 16:08:09",
"dzvents_version" : "3.1.8",
"hash" : "98a7d1eef-modified",
<nowiki> "python_version" : "3.8.10 (default, Nov 14 2022, 12:59:47) \n[GCC 9.4.0]",</nowiki>
"status" : "OK",
"title" : "GetVersion",
"version" : "2023.1 (build 15331)"
}</code>
 
==Get list of all defined users in the system==

<code>/json.htm?type=command&param=getusers</code>

<source lang="json">{
"result": [
{
"Enabled": "true",
"Password": "abcdef1234567890abcdef1234567889",
"RemoteSharing": 1,
"Rights": 2,
"TabsEnabled": 127,
"Username": "waaren",
"idx": "2"
},
{
"Enabled": "true",
"Password": "abcdef1234567890abcdef1234567889",
"RemoteSharing": 0,
"Rights": 2,
"TabsEnabled": 0,
"Username": "IFTTTx",
"idx": "3"
},
],
"status": "OK",
"title": "Users"
}</source>

==Get settings==

<code>/json.htm?type=command&param=getsettings</code>

This will return the settings defined in "Setup" under a JSON form.
For ex. :
<source lang="json">{
"AcceptNewHardware" : 0,
"ActiveTimerPlan" : 0,
"ClickatellEnabled" : "",
"ClickatellFrom" : "",
"ClickatellPassword" : "",
...
}</source>

==Retrieve Domoticz logfile information==

You can get the last couple (fixed at max. 100) of logmessages with:

/json.htm?type=command&param=getlog&lastlogtime=LASTLOGTIME&loglevel=LOGLEVEL

*

LOGLEVEL 1 = normal
2 = status
4 = error
268435455 = all

LASTLOGTIME starting with logmessages in LASTLOGTIME seconds since last epoch ( 0 = all available)

<source lang="json">{
"LastLogTime": "1615579727",
"result": [
{
"level": 4,
"message": "2021-03-12 17:11:47.613 Error: BuienRadar: Problem Connecting to Buienradar! (Check your Internet Connection!)"
},
{
"level": 4,
"message": "2021-03-12 18:30:05.598 Error: dzVents: Error: (3.1.6) openUV: /opt/domoticz/scripts/dzVents/scripts/openUV.lua:63: attempt to index a nil value (field 'result')"
},
{
"level": 4,
"message": "2021-03-12 21:08:47.542 Error: (Evohome) status request failed with message: Timeout was reached"
}
],
"status": "OK",
"title": "GetLog"
}</source>

==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&level=LEVEL

*MESSAGE = a string you want to log. Make sure to URL-encode any unsafe non-alphanumeric characters. See [https://www.url-encode-decode.com URL encode/decode]

"LEVEL" 1 = normal // default
2 = status
4 = error

<source lang="json">{
"status": "OK",
"title": "AddLogMessage"
}</source>

==Retrieve status of specific device==

You can get the status of a device with:

/json.htm?type=command&param=getdevices&rid=IDX

*IDX = id of your device (This number can be found in the devices tab in the column "IDX")
*or IDX = 10,20,30 (for querying a range devices, in this case devices with IDX 10, 20 and 30)

<source lang="json">{
"ActTime": 1613058183,
"AstrTwilightEnd": "19:39",
"AstrTwilightStart": "06:06",
"CivTwilightEnd": "18:20",
"CivTwilightStart": "07:24",
"DayLength": "09:46",
"NautTwilightEnd": "19:00",
"NautTwilightStart": "06:45",
"ServerTime": "2021-02-11 16:43:03",
"SunAtSouth": "12:52",
"Sunrise": "08:00",
"Sunset": "17:45",
"app_version": "2020.2 (build 12936)",
"result": [
{
"AddjMulti": 1,
"AddjMulti2": 1,
"AddjValue": 0,
"AddjValue2": 0,
"BatteryLevel": 255,
"CustomImage": 0,
"Data": "On",
"Description": "Plain text",
"DimmerType": "none",
"Favorite": 0,
"HardwareDisabled": false,
"HardwareID": 3,
"HardwareName": "virtual",
"HardwareType": "Dummy (Does nothing, use for virtual switches only)",
"HardwareTypeVal": 15,
"HaveDimmer": true,
"HaveGroupCmd": true,
"HaveTimeout": false,
"ID": "00014052",
"Image": "Light",
"IsSubDevice": false,
"LastUpdate": "2021-02-10 22:47:03",
"Level": 0,
"LevelInt": 0,
"MaxDimLevel": 100,
"Name": "mySwitch",
"Notifications": "false",
"PlanID": "0",
"PlanIDs": [
0
],
"Protected": false,
"ShowNotifications": true,
"SignalLevel": "-",
"Status": "On",
"StrParam1": "",
"StrParam2": "",
"SubType": "Switch",
"SwitchType": "On/Off",
"SwitchTypeVal": 0,
"Timers": "false",
"Type": "Light/Switch",
"TypeImg": "lightbulb",
"Unit": 1,
"Used": 1,
"UsedByCamera": false,
"User": "Admin (IP: 192.168.192.41)",
"XOffset": "0",
"YOffset": "0",
"idx": "2"
}
],
"status": "OK",
"title": "Devices"
}</source>

*The array result[0] contains a hash/dict with name/value pairs of settings that are relevant to the device in question, in this example a thermostat.
*Please note that it will be something like json.result[1] in classic Lua and dzVents script because in Lua an array starts with 1.

==Retrieve name / idx of all devices==

If you are not sure of the IDX and want to do a quick lookup of name/value pairs to match a device name to its IDX, use

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

which will result in something like (fragment)

<source lang="json">
{
"name" : "Corner Light",
"value" : "156"
},
{
"name" : "Table Light",
"value" : "198"
},
</source>

==Get status of all devices of a certain type==

<code>/json.htm?type=command&param=getdevices&filter=all&used=true&order=Name</code>

This will return information about all used devices. If you want to retrieve information for a specific devicetype, you can use the following filters with &filter=:

light
weather
temp
utility
wind
rain
uv
baro
zwavealarms

<source lang="json">{
"ActTime": 1615581479,
"AstrTwilightEnd": "20:34",
"AstrTwilightStart": "05:09",
"CivTwilightEnd": "19:15",
"CivTwilightStart": "06:29",
"DayLength": "11:39",
"NautTwilightEnd": "19:54",
"NautTwilightStart": "05:50",
"ServerTime": "2021-03-12 21:37:59",
"SunAtSouth": "12:52",
"Sunrise": "07:02",
"Sunset": "18:41",
"app_version": "2020.2 (build 13065)",
"result": [
{
"List of all devices": 1
}
],
"status": "OK",
"title": "Devices"
}</source>

==Get status of all devices, including hidden ones==

<code>/json.htm?type=command&param=getdevices&used=true&displayhidden=1</code>

Device names starting with a '$' sign are invisible in both the ''Dashboard'' and ''Switches'' tabs in the Domoticz UI. If you want these devices included in the json output then ''displayhidden'' must be specified.

<source lang="json">{
"ActTime": 1615641865,
"AstrTwilightEnd": "20:36",
"AstrTwilightStart": "05:07",
"CivTwilightEnd": "19:16",
"CivTwilightStart": "06:26",
"DayLength": "11:43",
"NautTwilightEnd": "19:56",
"NautTwilightStart": "05:47",
"ServerTime": "2021-03-13 14:24:25",
"SunAtSouth": "12:51",
"Sunrise": "07:00",
"Sunset": "18:43",
"app_version": "2020.2 (build 13065)",
"result": [
{
"AddjMulti": 1,
"AddjMulti2": 1,
"AddjValue": 0,
...
"Name": "$Harmony_Mediacenter",
"Notifications": "false",
"PlanID": "0",
...
"YOffset": "0",
"idx": "2176"
},
],
"status": "OK",
"title": "Devices"
}
</source>

==Get status of all Favorite devices==

<code>/json.htm?type=command&param=getdevices&used=true&filter=all&favorite=1</code>

This will return only devices that are tagged as Favorite.

==Get server time==

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

<source lang="json">{
"ServerTime": "2021-01-13 23:10:13",
"status": "OK",
"title": "getServerTime"
}</source>

==Get sunrise and sunset times==

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

<source lang="json">{
"ServerTime" : "Sep 30 2013 17:15:21",
"Sunrise" : "07:38:00",
"Sunset" : "19:16:00",
"status" : "OK",
"title" : "getSunRiseSet"
}</source>

==Use Notification Subsystem==

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

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

<source lang="json">{
"status": "OK",
"title": "SendNotification"
}</source>

You can also post a notification to one or more notification systems with:

/json.htm?type=command&param=sendnotification&subject=SUBJECT&body=THEBODY&subsystem=SUBSYSTEM1;SUBSYSTEM2;...&extradata=EXTRADATA1;EXTRADATA2;....

*SUBJECT = a string you want to use as subject
*THEBODY= a string you want to use as body
*SUBSYSTEM= the notification system(s) you want to use (lowercase)
*EXTRADATA=Some subsystems can have extra data like for example FCM can have the specigic devices to be notified eg extradata=midx_7

Subsystems:
fcm
http
kodi
lms
nma
prowl
pushalot
pushbullet
pushover
pushsafer

==Backup and database related==

send a VACUUM request to domoticz database; sqlite.org: "The VACUUM command rebuilds the database file, repacking it into a minimal amount of disk space "

Please note that this command does require free space on the used temporary file system up to twice the current databases size.

See [[https://sqlite.org/tempfiles.html sqlite.org] ] goto ''' 5.Temporary File Storage Locations '''

<source lang="http">json.htm?type=command&param=vacuumdatabase</source>
<source lang="json">
{
"status": "OK",
"title": "VacuumDatabase"
}
</source>

<source lang="http">/backupdatabase.php</source>

this call will create a database backup in the download directory of your workstation.

==Event system==

Get overview of (internal) events

From Stable 2023.2: <code>/json.htm?type=command&param=events&evparam=list</code>

Deprecated format (no fallback possible!) <code><s>/json.htm?type=events&param=list</s></code><source lang="json">
{
"interpreters": "Blockly:Lua:dzVents:Python",
"result": [
{
"eventstatus": "0",
"id": "77",
"name": "Lua pinger"
},
{
"eventstatus": "0",
"id": "106",
"name": "Lua curl"
},
....
}
],
"status": "OK",
"title": "ListEvents"
}
</source>
Deprecated format (no fallback possible!) <code><s>/json.htm?type=events&param=updatestatus&eventid=77&eventstatus=1</s></code>

From Stable 2023.2: <code>/json.htm?type=command&param=events&evparam=updatestatus&eventid=77&eventstatus=1</code><source lang="json">
{
"status": "OK",
"title": "Events"
}
</source>

==Accept new sensors==

<source lang="http">/json.htm?type=command&param=allownewhardware&timeout=MINUTES</source>

<source lang="json">
{
"status": "OK",
"title": "AllowNewHardware"
}
</source>

==Get list of custom icons==

<source lang="http">/json.htm?type=command&param=getcustomiconset</source>
Add 100 to the Idx value to use it in the [[Domoticz API/JSON URL's#change Icon Not available for all device types|set Custom icon command]].
So listed Idx: 2 is iconNumber 102 for the command.
<source lang="json">
{
"result": [
{
"Description": "OpenAQ",
"IconFile16": "images/xfr_openaq2.png",
"IconFile48Off": "images/xfr_openaq248_Off.png",
"IconFile48On": "images/xfr_openaq248_On.png",
"Title": "OpenAQ",
"idx": 1
},
{
"Description": "Omnik Logo",
"IconFile16": "images/Omnik.png",
"IconFile48Off": "images/Omnik48_Off.png",
"IconFile48On": "images/Omnik48_On.png",
"Title": "Omnik",
"idx": 2
}
],
"status": "OK",
"title": "GetCustomIconSet"
}
</source>

=Lights and switches=

==Get details of all lights/switches==

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

OR

<code>/json.htm?type=command&param=getdevices&filter=light&used=true&order=Name</code>

Example output:
<source lang="json">

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

==Turn a light/switch on/off==

/json.htm?type=command&param=switchlight&idx=99&switchcmd=<On|Off|Toggle|Stop>
<source lang="json">{
"status": "OK",
"title": "SwitchLight"
}</source>
When error:
<source lang="json">{
"message" : "Error sending switch command, check device/hardware (idx=nnn) !",
"status" : "ERROR",
"title" : "SwitchLight"
}</source>
==Open-Close-Stop Blinds==

Open-Close Blinds

/json.htm?type=command&param=switchlight&idx=99&switchcmd=<Open|Close|Stop>

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Set%20Level&level=<0..100>

==General notes==

Commands are case sensitive!

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

<source lang="json">{
"message" : "WRONG CODE",
"status" : "ERROR",
"title" : "SwitchLight"
}</source>

Note that when you use '''&switchcmd''', the http:// or script:// on/off actions of the corresponding switch are executed. If you just want to update the status of the switch in Domoticz ''without'' running these actions, use the '''&param=udevice''' option instead (see update-section below).

==Switching RFY Blinds sun/wind detector on/off==

On some type of blinds it is possible to enable/disable the sun/wind detector.

Enable (where the number behind idx is the idx number of the screen in domoticz):
/json.htm?type=command&param=switchlight&idx=7&switchcmd=EnableSunWind
Disable:
/json.htm?type=command&param=switchlight&idx=7&switchcmd=DisableSunWind

==Set a dimmable light/selector to a certain level==

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

*dimmable:
**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
*Blinds: enter percentage, level will be 0-100
*Selector switch: enter the level number (eg 10, 20 or 30) that can be found in the edit section of a switch.
*To update in Domoticz only without running it's device actions use <code>/json.htm?type=command&param=udevice&idx=IDX&nvalue=[0,1,2]&svalue=LEVELNR</code> Statuses for Blinds Percentage when using &param=udevice:

Closed: nValue = 1 and sValue = 100
partially opened: nValue = 2 and sValue = 1-99
Open: nValue = 0 and sValue = 0
<source lang="json">{
"status" : "OK",
"title" : "SwitchLight"
}</source>

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

<source lang="json">{
"status": "OK",
"title": "SetColBrightnessValue"
}</source>

: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

<source lang="json">{
"status": "OK",
"title": "SetColBrightnessValue"
}</source>

:Note: The actual brightness of the light is a combination of RGB value and brightness. Brightness parameter may be omitted.
:A site like [http://www.colorhexa.com/ff8c00 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

<source lang="json">{
"status": "OK",
"title": "SetColBrightnessValue"
}</source>

'''Domoticz color format:'''

Domoticz color format is used as:

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

Example: <code>color={"m":3,"t":0,"r":0,"g":0,"b":50,"cw":0,"ww":0}</code>
<nowiki>
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)
}
</nowiki>

'''References'''
This API call is called internally by dzVents when using the following device object methods:

*[https://www.domoticz.com/wiki/DzVents:_next_generation_LUA_scripting#RGBW.28W.29_.2F_Lighting_Limitless.2FApplamp setColor(r, g, b, br, cw, ww, m, t)]
*[https://www.domoticz.com/wiki/DzVents:_next_generation_LUA_scripting#RGBW.28W.29_.2F_Lighting_Limitless.2FApplamp setColorBrightness()]

Please ensure local access is enabled for 127.0.0.1 or 127.0.0.*
[https://www.domoticz.com/wiki/DzVents:_next_generation_LUA_scripting#Using_dzVents_with_Domoticz (described here)].
for these to work correctly. 
The parameters r, g, b, cw, ww, m and t map to the same values in the aforementioned color object. 
The parameter br maps to brightness [0..100]. 

==Set an RGB_CW_WW or CW_WW light to a certain color temperature==

/json.htm?type=command&param=setkelvinlevel&idx=99&kelvin=1

<source lang="json">{
"status": "OK",
"title": "Set Kelvin Level"
}</source>
Range of kelvin parameter: 0..100, 0 is coldest, 100 is warmest

'''References'''
This API call is called internally by dzVents when using the following device object method:

*[https://www.domoticz.com/wiki/DzVents:_next_generation_LUA_scripting#RGBW.28W.29_.2F_Lighting_Limitless.2FApplamp setKelvin(Kelvin)]

Please ensure local access is enabled for 127.0.0.1 or 127.0.0.*
[https://www.domoticz.com/wiki/DzVents:_next_generation_LUA_scripting#Using_dzVents_with_Domoticz (described here)].
for this to work correctly. 

==Toggle a switch state between on/off==

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

<source lang="json">{
"status" : "OK",
"title" : "SwitchLight"
}</source>

=Cameras=
==Get cameras==
<code>/json.htm?type=command&param=getcameras</code><source lang="json">
{
"result": [
{
"Address": "192.168.192.111",
"Enabled": "true",
"ImageURL": "image.jpg",
"Name": "Inside",
"Password": "Secret",
"Port": 19767,
"Protocol": 0,
"Username": "anyUser",
"idx": "1"
},
{
"Address": "192.168.192.112",
"Enabled": "true",
"ImageURL": "image.jpg",
"Name": "Outside",
"Password": "verySecret",
"Port": 19765,
"Protocol": 0,
"Username": "anotherUser",
"idx": "2"
}
],
"status": "OK",
"title": "Cameras"
}
</source>

==Add camera==

imageurl must be base64 encoded

<source lang="json">

/json.htm?type=command&param=addcamera&address=192.168.192.111&port=19765&name=insideCamera&enabled=true&imageurl=aW1hZ2UuanBn&protocol=0

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

</source>

==Update camera==

imageurl must be base64 encoded

<source lang="json">

/json.htm?type=command&param=updatecamera&address=192.168.192.111&port=19767&name=test&enabled=true&idx=1&imageurl=aW1hZ2UuanBn&protocol=0

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

</source>

==Send snapshot from camera==

imageurl must be base64 encoded

&user&password optional

Sends email with a camera snapshots if email is configured in Menu Setup - Settings and set for attachments.

camidx: Send 1 or multiple camerIDs in ; separated.

Subject: Subject of email

<source lang="json">

/json.htm?type=command&param=emailcamerasnapshot&camidx=1;3&subject=Movement+at+Frontdoor

{
"status": "OK",
"title": "Email Camera Snapshot"
}

</source>

=Scenes / Groups=
==Get current state of all scenes & groups==

<code>/json.htm?type=command&param=getscenes</code>

Example output:
<source lang="json">{
"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"
}</source>

==Turn a scene / group on or off==

/json.htm?type=command&param=switchscene&idx=&switchcmd=<On|Off|Toggle>

*idx = id of your scene/group.
*switchcmd = "On", "Off" or "Toggle" (case sensitive!)
*Scenes can only be turned '''On'''

<source lang="json">{
"status" : "OK",
"title" : "SwitchScene"
}</source>

==Add a scene (0)==
<code>/json.htm?type=command&param=addscene&name=''scenename''&scenetype=0</code>

==Add a group (1)==
<code>/json.htm?type=command&param=addscene&name=''scenename''&scenetype=1</code>

==Delete a scene or group==
<code>/json.htm?type=command&param=deletescene&idx=''number''</code>

==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 activation devices of a scene==
/json.htm?type=command&param=getsceneactivations&idx=''number''

Example output:
<source lang="json">{
"result": [
{
"code": 0,
"codestr": "-",
"idx": 249,
"name": "Activator device"
},
{
"code": 0,
"codestr": "-",
"idx": 1048,
"name": "Another Activator device"
}
],
"status": "OK",
"title": "GetSceneActivations"
}</source>

==Add activation devices for a scene==

<code>/json.htm?type=command&param=addscenecode&sceneidx=<scene ID>&idx=<device ID>&cmnd=<command></code>

Example output:
<source lang="json">
{
"status": "OK",
"title": "AddSceneCode"
}</source>

==Add OnAction and OffAction to a scene or group==
This command can be issue only after a scene or group was created, so first create the scene/group, than update the scene/group specifying the On Action and/or Off Action
<code>/json.htm?type=command&param=updatescene&idx=''number''&scenetype=''scenetype''&onaction=''base64onaction''&offaction=''base64offaction''</code>

where ''number'' is the idx of the scene/group, ''scenetype'' is 0 for scenes of 1 for groups, ''base64onactions'' is the On Action coded with base64 and ''base64offaction'' is the Off Action coded with base64. It's possible to find base64 converters online, like https://www.base64encode.org/

Please note that you have to include your current description if any

Example output:

<source lang="json">{
"status": "OK",
"title": "UpdateScene"
}</source>

==List timers of a scene==
<code>/json.htm?type=command&param=getscenetimers&idx=''number''</code>

Example output:
<source lang="json">{
"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"
}</source>

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

==Enable/disable/delete specific scene schedule(timer)==
[[Domoticz_API/JSON_URL's#Enable specific schedule(timer) for Scenes/Groups|Enable specific schedule(timer) for Scenes/Groups]]

[[Domoticz_API/JSON_URL's#Disable specific schedule(timer) for Scenes/Groups|Disable specific schedule(timer) for Scenes/Groups]]

[[Domoticz_API/JSON_URL's#Delete specific schedule(timer) for Scenes/Groups|Delete specific schedule(timer) for Scenes/Groups]]

=Setpoint/Thermostat control=

==Set Setpoint==
/json.htm?type=command&param=setsetpoint&idx=&setpoint=

*idx = id of the setpoint
*setpoint = value (for temperature in Celsius (like 20.5))

=Server control=

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

<source lang="json">{
"status" : "OK",
"title" : "SystemShutdown"
}</source>

==Reboot system==
/json.htm?type=command&param=system_reboot

<source lang="json">{
"status" : "OK",
"title" : "SystemReboot"
}</source>

=Create, delete, rename, action and disable commands=

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

afterwards to get the id, either you have your last created id from an index you maintain or sort the hardware page for last ID:
<code>/json.htm?type=command&param=gethardware</code>

==Create a virtual sensor==

Basic action (see below for values)
<code>/json.htm?type=command&param=createvirtualsensor&idx=HWIDX&sensorname=SENSORNAME&sensortype=SENSORTYPE</code>

Note: It is normally easier to use the CreateDevice JSON (see next section)

Temp+Humidity example
/json.htm?type=<code>command&param=</code>createvirtualsensor&idx=HWIDX&sensorname=TempHum&sensortype=82
Electricity example
/json.htm?type=<code>command&param=c</code>reatevirtualsensor&idx=HWIDX&sensorname=Energy&sensortype=90

and then get the device id from the list:
/json.htm?type=<code>command&param=get</code>devices&filter=all&used=true&order=Name

Values:

*HWIDX = id of your (Dummy) hardware (not the device!). This number can be found in the hardware tab in the column "IDX".

Note: If a non existing hardware IDX is used the created device is greyed out in the user interface!

*SENSORNAME = sensor name
*SENSORTYPE = See list below (this is an incomplete list. For more devices see page [[Developing a Python plugin]])

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 5 Time: svalue=COUNTER
type 4 Energy generated: svalue=POWER;ENERGY
type 3 Counter: svalue=COUNTER
type 2 Water: svalue=VOLUME
type 1 Gas: svalue=VOLUME
type 0 Energy: svalue=POWER;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 (switchtype). URL is:
<code>/json.htm?type=command&param=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true</code>

where DEVICE_IDX is the device idx, SENSORNAME is device name, and the SUBTYPE_VALUE is one of:
0 for Energy
1 for Gas
2 for Water
3 for Custom Counter
4 for Energy Generated
5 for Time

==Create a device==
An overview of all available devices can be found in wiki page [[Developing_a_Python_plugin#Available_Device_Types]]

Basic Action:

<code>/json.htm?type=command&param=createdevice&idx=HWIDX&name=SENSORNAME&sensormappedtype=MAPPEDTYPE".</code>

*HWIDX = id of your (Dummy) hardware. This number can be found in the hardware tab in the column "IDX".

Note: If a non existing hardware IDX is used the created device is greyed out in the user interface!

*SENSORNAME = sensor name
*DEVICETYPE = type of device, see overview [[Developing_a_Python_plugin#Available_Device_Types]]

Source: https://github.com/domoticz/domoticz/blob/development/hardware/hardwaretypes.h or https://github.com/domoticz/domoticz/blob/development/main/RFXtrx.h

*DEVICESUBTYPE = subtype of device, see overview [[Developing_a_Python_plugin#Available_Device_Types]]

Source: https://github.com/domoticz/domoticz/blob/development/hardware/hardwaretypes.h or https://github.com/domoticz/domoticz/blob/development/main/RFXtrx.h

Example Result
<source lang="json">{
"idx" : "142",
"status" : "OK",
"title" : "CreateSensor"
}</source>

'''Examples:'''

Temp (Type: pTypeTEMP, subType: sTypeTEMP5)
/json.htm?type=<code>command&param=</code>createdevice&idx=HWIDX&sensorname=Temp5&devicetype=50&devicesubtype=5
Voltage (Type: pTypeGeneral, subType: sTypeVoltage)
/json.htm?type=<code>command&param=</code>createdevice&idx=HWIDX&sensorname=Voltage0&devicetype=243&devicesubtype=8
Electric (Instant+Counter)
/json.htm?type=<code>command&param=</code>createdevice&idx=HWIDX&sensorname=ElecInstCount&devicetype=243&devicesubtype=29
Counter Incremental
/json.htm?type=<code>command&param=</code>createdevice&idx=HWIDX&sensorname=Counter%20Increment2&devicetype=243&devicesubtype=28

For the Counter Incremental, Counter and managed Counter and Switches another request is needed to set the type(switchtype). URL is:
/json.htm?type=<code>command&param=</code>setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true
where for counters DEVICE_IDX is the device idx, SENSORNAME is device name, and the SUBTYPE_VALUE is one of:
0 for Energy
1 for Gas
2 for Water
3 for Custom Counter
4 for Energy Generated
5 for Time

For switches
SubType Name
0 On/Off
1 Doorbell
2 Contact
3 Blinds
4 X10 Siren
5 Smoke Detector
6 Blinds Inverted
7 Dimmer
8 Motion Sensor
9 Push On Button
10 Push Off Button
11 Door Contact
12 Dusk Sensor
13 Blinds Percentage
14 Venetian Blinds US
15 Venetian Blinds EU
16 Blinds Percentage Inverted
17 Media Player
18 Selector
19 Door Lock
20 Door Lock Inverted
21 Blinds Percentage with Stop
22 Blinds Percentage with Stop Inverted

==Rename hardware==
/json.htm?type=command&param=updatehardware&htype=<type>&name=<new name>&enabled=<true or false>&idx=<hardware idx>
 
To get the required data from the hardware first do
<code>/json.htm?type=command&param=gethardware</code> 

==Rename device / sensor==
<code>/json.htm?type=command&param=setused&idx=<device ID>&name=<new name>&used=true</code> 

==Enable hardware==
/json.htm?type=command&param=updatehardware&htype=<type>&name=<name>&enabled=true&port=<port name>&idx=<hardware idx>&loglevel=<log level>

'''note''' Use the complete set of parms that you find when entering the enable command on the GUI because if not completely entered it will destroy your hardware table. Test first on a test system !!

==Disable hardware==
/json.htm?type=command&param=updatehardware&htype=<type>&name=<name>&enabled=false&idx=<hardware idx>
To get the required data from the hardware first do
 
<code>/json.htm?type=command&param=gethardware</code>

 
'''note''' Use the complete set of parms that you find when entering the disable command on the GUI because if not completely entered it will remove data from the parms. Test on a test system first !!

==Delete hardware==
/json.htm?type=command&param=deletehardware&idx=<hardware idx>

<source lang="json">{
"status" : "OK",
"title" : "DeleteHardware"
}</source>

==Delete a device or sensor==
<code>/json.htm?type=command&param=setused&used=false&idx=<device idx></code><source lang="json">{
"status" : "OK",
"title" : "SetUsed"
}</source>

==Enable/Disable a device or sensor==
/json.htm?type=command&param=setdevused&idx=<device idx>&used=<true/false>&name=<device name>
(device name is a optional parameter)
<source lang="json">{
"status" : "OK",
"title" : "SetDeviceUsed"
}</source>

==Enable a disabled device or sensor==

/json.htm?idx=<device idx>&name=<new name>&type=setused&used=true
or
/json.htm?idx=<device idx>&type=setused&used=true

<source lang="json">{
"status" : "OK",
"title" : "SetUsed"
}</source>

==Add an On action and/or an Off action to a device or sensor==

/json.htm?type=setused&used=true&idx=IDX&strparam1=base64Encoded(ON ACTION STRING)&strparam2=base64Encoded(OFF ACTION STRING)

<source lang="json">{
"status": "OK",
"title": "SetUsed"
}</source>

==Transfer device==

<code>/json.htm?type=command&param=transferdevice&idx=IDX_1&newidx=IDX_2</code>

Transfer sensor log of device with oldest lastUpdate value to device with most recent lastUpdate value. So not necessarily from IDX_1 to IDX_2 or the other way around.
Source device is removed after transfer of logs.

<source lang="json">{
"status": "OK",
"title": "TransferDevice"
}</source>

=Update devices/sensors=
Note that when you use this &param=udevice option with the additional option &parsetrigger=false, the device is updated ''without'' running the associated on/off- and script actions.

Expert usage. Directly set device parameters via JSON.
 

Be careful when firing values to domoticz.db as there is a chance to crash the database if parameters are wrong or missing.
First go to the devices tab and notice the device index (idx) of the device you want to change 

==Generic update API's==

Note make sure stringparms must be urlenecoded (eg. <space> %20, <Double quote> %27 etc..

===update a sensor device===
Note: for switches/lights/dimmers see Lights and Switches section.

/json.htm?type=command&param=udevice&idx=<idx>&nvalue=<numeric value>&svalue=<string value>

<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

===change Icon Not available for all device types===

<code>/json.htm?type=command&param=setused&used=true&name=<devicename>&description=<description>&idx=<idx>&switchtype=<switchType>&customimage=<iconNumber></code>

Use the [[Domoticz API/JSON URL's#Get list of custom icons|getcustomiconset command]] to get a list of all custom icons. Add 100 the given Idx value to set the iconnumber. So listed Idx:2 is iconNumber 102<source lang="json">{
"status": "OK",
"title": "SetUsed"
}</source>

===change name===

/json.htm?type=command&param=renamedevice&name=<new devicename>&idx=<idx>

<source lang="json">{
"status": "OK",
"title": "RenameDevice"
}</source>

===protection On / Off===

<code>/json.htm?type=command&param=setused&used=true&protected=<true/falseidx=<idx></code><source lang="json">{
"status": "OK",
"title": "SetUsed"
}</source>

===update in domoticz only===

does not parse the actual command to the hardware (like MQTT)

with parsetrigger=false -->> No event is triggered either

/json.htm?type=command&param=udevice&idx=<idx>&nvalue=<numeric value>&svalue=<string value>&parsetrigger=<false/true>

<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

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

 
<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

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

 

<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

==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 
5 = Unknown 
6 = Cloudy/Rain 

 

Barometer forecast of other device types can be one of: 
0 = Heavy Snow 
1 = Snow 
2 = Heavy Rain 
3 = Rain 
4 = Cloudy 
5 = Some Clouds 
6 = Sunny 
7 = Unknown 
8 = Unstable 
9 = Stable 

 

<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

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

 
<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

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

 
HUM_STAT can be one of: 

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

 
Barometer forecast of device type "General" (Virtual) can be one of: 

0 = No Info 
1 = Sunny 
2 = Partly Cloudy 
3 = Cloudy 
4 = Rain 

 

<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

==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= Optional. Not used at the moment, can be 0 

 
Barometer forecast can be one of: 
0 = Stable 
1 = Sunny 
2 = Cloudy 
3 = Unstable 
4 = Thunderstorm 
5 = Unknown 
6 = Cloudy/Rain 
 

Barometer forecast of other device types can be one of: 
0 = Heavy Snow 
1 = Snow 
2 = Heavy Rain 
3 = Rain 
4 = Cloudy 
5 = Some Clouds 
6 = Sunny 
7 = Unknown 
8 = Unstable 
9 = Stable 

 

<source lang="json">{
"status": "OK",
"title": "Update Device"
}</source>

==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 counter (Energy, Volume, Custom). 

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

*Energy (reports kWh), give COUNTER value in Wh, integer 
*Energy Generated (reports kWh). give COUNTER value in Wh, integer 
*Gas (reports m3) , give COUNTER value in liter (1000 liter = 1 m³), integer 
*Water (reports m3), give COUNTER value in liter (1000 liter = 1 m³), integer 
*Counter (no unit) 
*Time (min?), seems to be obsolete, use Counter instead and use the time units as desired (eg Sec, min, hrs) 

The counter will be treated with the divider which is defined in the parameters in the application settings (menu setup-settings, tab counters). 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).

==Counter Incremental==

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

INCREMENT = Integer of the increment of the counter. For Counters the standard counter dividers apply (menu setup - settings - tab counters)

will increment the counter value by 1. To reset an incremental counter, set the svalue to a ''negative'' integer equal to the current total of the 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 (W)
*ENERGY = Integer, total cumulative energy in Watt-hours (Wh) 

(Energy Read type (use edit button to change): Default: From Device. If the device is not able to send the ENERGY counter values you choose "Energy read : Computed". This will ignore ENERGY counter values and Domoticz will calculate the Energy (kWh) internally based on the (previous/current) POWER (Watt) values. By design this is less accurate then using the ENERGY counter when using them "from Device".)

Domoticz will calculate the today values based on the delta's in the total cumulative energy of today.

For Counters the standard counter dividers apply (menu setup - settings - tab counters)

Note: This device will show in Domoticz as type "General, kWh"

==Managed counter==

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

*IDX = id of your device (This number can be found in the devices tab in the column "IDX")
*COUNTER = Integer, total cumulative counter energy (Wh, can be set to -1 if unknown or unused, in that case it won't show on dashboard or in logs)
*USAGE = energy usage in Watt-hours (Wh).

Managed counter will not transfer automatically every day data from device status to history log, it's up to an external script or plugin to insert data in history log database (useful to show non realtime consumption of energy provider that put energy information "in the cloud").

For Counters the standard counter dividers apply (menu setup - settings - tab counters)

To insert data in history log:
/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=COUNTER;USAGE;DATE

*IDX = id of your device (This number can be found in the devices tab in the column "IDX")
*COUNTER = total cumulative counter energy (Wh, can be set to -1 if unknown or unused, in that case it won't show on dashboard or in logs)
*USAGE = energy usage in Watt-hours (Wh)
*DATE = date with %Y-%m-%d format (for instance 2019-09-24) to put data in last week/month/year history log, or "%Y-%m-%d %H:%M:%S" format (for instance 2019-10-03 14:00:00) to put data in last days history log

==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= integer, total cumulative energy usage meter tariff 1 in Wh.
*USAGE2= integer, total cumulative energy usage meter tariff 2 in Wh.
*RETURN1= integer, total cumulative energy return meter tariff 1 in Wh.
*RETURN2= integer, total cumulative energy return meter tariff 2 in Wh.
*CONS= actual usage power (Watt)
*PROD= actual return power (Watt)

USAGE and RETURN are total cumulative 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) 
Domoticz will calculate the today values based on the delta's in the total cumulative energy of today.

For Counters the standard counter dividers apply (menu setup - settings - tab counters)

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

Calculated status from PPM value:

airquality < 700 status text: "Excellent"

airquality < 900 status text: "Good"

airquality < 1100 status text:"Fair"

airquality < 1600 status text: "Mediocre"

airquality >= 1600 status text: "Bad"

==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= Integer, 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.
For Counters the divider is used from menu setup - settings, tab Counters

==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) 

==Opentherm Gateway Custom command==

/json.htm?type=command&param=sendopenthermcommand&idx=IDX&cmnd=COMMAND

*IDX = id of your hardware Opentherm device (This number can be found in the ID column in menu Setup-Hardware)
*COMMAND = The actual custom OTGW command like TC=20 

==Note on counters==
Usually, counters are updated daily to feed week/month/year history log views. Starting version 4.11774, if you want to disable that behavior to control everything from an external script or a plugin (already the case for managed counter), you can set the "DisableLogAutoUpdate" device option to "true", for instance in a Python plugin:
Domoticz.Device(Name="MyCounter", Unit=1, Type=0xfa, Subtype=0x01, Options={"DisableLogAutoUpdate" : "true").Create()

Starting version 4.11774, you can too directly insert data in in history log. Set the "AddDBLogEntry" device option to "true", for instance in a Python plugin:
Domoticz.Device(Name="MyCounter", Unit=1, Type=0xfa, Subtype=0x01, Options={"AddDBLogEntry" : "true").Create()
With a json the parameter AddDBLogEntry:true should first base64 encoded
/json.htm?type=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true&options=CODE
To set AddDBLogEntry:true, you must call:
/json.htm?type=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true&options=QWRkREJMb2dFbnRyeTp0cnVl

AddDBLogEntry can be combined with other entries in the options field if separated by a semicolon for example to set:
ValueQuantity:2;AddDBLogEntry:true

You call:
/json.htm?type=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true&options=VmFsdWVRdWFudGl0eToyO0FkZERCTG9nRW50cnk6dHJ1ZQ==
Also please note if the device is edited using the domoticz device screen then this AddDBLogEntry disappears and needs to be added again.

Then, depending on counters, you can insert values in history log. For most counters:
/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=COUNTER;USAGE;DATE

*IDX = id of your device (This number can be found in the devices tab in the column "IDX")
*COUNTER = total cumulative counter energy (Wh)
*USAGE = energy usage in Watt-hours (Wh)
*DATE = date with %Y-%m-%d format (for instance 2019-09-24) to put data in last week/month/year history log, or "%Y-%m-%d %H:%M:%S" format (for instance 2019-10-03 14:00:00) to put data in last days history log

Note: COUNTER and USAGE should be positive. Any negative value will result in 0 instead

For multi meters (P1 Smart Meter, CM113, Electrisave and CM180i):
/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE1;USAGE2;RETURN1;RETURN2;CONS;PROD;DATE

*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)
*DATE = date with %Y-%m-%d format (for instance 2019-09-24) to put data in last week/month/year history log, or "%Y-%m-%d %H:%M:%S" format (for instance 2019-10-03 14:00:00) to put data in last days history log

or
/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE1;USAGE2;RETURN1;RETURN2;CONS;PROD;COUNTER1;COUNTER2;COUNTER3;COUNTER4;DATE
as previously, plus absolute counter values
 

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

/json.htm?type=command&param=udevice&idx=<idx>&nvalue=<numeric value>&svalue=<string value>&rssi=<numeric value>&battery=<numeric value>

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

=Security=

==Get Password==
to be able to set the security status, the (encoded) password is required.

<code>/json.htm?type=command&param=getsettings</code><source lang="json">{
"AcceptNewHardware": 0,
"ActiveTimerPlan": 2,
"AllowWidgetOrdering": 1,
"AuthenticationMethod": 1,
"BatterLowLevel": 0,
"CM113DisplayType": 0,
.....
"SecPassword": "bfa2bea3x",
....
"WindUnit": 4,
"cloudenabled": true,
"status": "OK",
"title": "settings"
}</source>

get the value from key "SecPassword" ;for the purpose of this wiki we assume the value read is "bfa2bea3x"

==Get security state==
/json.htm?type=command&param=getsecstatus
<source lang="json">{
"secondelay": 2,
"secstatus": 1,
"status": "OK",
"title": "GetSecStatus"
}</source>
where secstatus is
0 = Disarmed
1 = Arm Home
2 = Arm Away
3 = Unknown

==Set security state==
/json.htm?type=command&param=setsecstatus&secstatus=<status>&seccode=bfa2bea3x
<source lang="json">{
"status": "OK",
"title": "SetSecStatus"
}</source>

=Smoke Detection=
==Activate==
<code>/json.htm?type=command&param=switchlight&idx=<IDX>&switchcmd=On</code>
<source lang="json">{
"status": "OK",
"title": "SwitchLight"
}</source>

==Deactivate==
<code>/json.htm?type=command&param=switchlight&idx=<IDX>&switchcmd=Off</code>
<source lang="json">{
"status": "OK",
"title": "SwitchLight"
}</source>
==Reset==
<code>/json.htm?type=command&param=resetsecuritystatus&idx=<IDX>&switchcmd=Off</code>
<source lang="json">{
"status": "OK",
"title": "ResetSecurityStatus"
}</source>

<code>/json.htm?type=command&param=resetsecuritystatus&idx=3456&switchcmd=Normal</code>
<source lang="json">{
"status": "OK",
"title": "SwitchLight"
}</source>

=User variables=

==Add a new variable==

*USERVARIABLENAME with the name of the variable
*USERVARIABLETYPE is a digit (0,1,2,3,4) or a string (Integer, Float, String, Date, Time)

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

*USERVARIABLEVALUE with the value

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

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

<source lang="json">{
"status": "OK",
"title": "AddUserVariable"
}</source>

==Update an existing variable==

Remember to change:

*USERVARIABLENAME with the name of your variable
*USERVARIABLETYPE according to the table from [[Domoticz_API/JSON_URL's#Add_a_new_variable|"Add a new variable"]]
*USERVARIABLEVALUE with the new value

Note: events will only be triggered when the variabletype and variablename are not changed by the update command.

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

<source lang="json">{
"status": "OK",
"title": "UpdateUserVariable"
}</source>

==List all variables==

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

<source lang="json">{
"result": [
{
"LastUpdate": "2020-01-13 09:04:17",
"Name": "setup-test",
"Type": "2",
"Value": "Hi",
"idx": "1"
},
{
"LastUpdate": "2020-02-17 16:48:03",
"Name": "presence-test",
"Type": "0",
"Value": "1",
"idx": "2"
},
....
{
"LastUpdate": "2021-03-02 21:10:54",
"Name": "UV_Night",
"Type": "2",
"Value": "21:11",
"idx": "44"
}
],
"status": "OK",
"title": "GetUserVariables"
}
</source>

==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)

<source lang="json">{
"result": [
{
"LastUpdate": "2021-03-02 21:10:54",
"Name": "UV_Night",
"Type": "2",
"Value": "21:11",
"idx": "44"
}
],
"status": "OK",
"title": "GetUserVariable"
}</source>

==Delete a variable==

*IDX = id of your variable (This number can be found using the "List all variables" call above)

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

<source lang="json">{
"status": "OK",
"title": "DeleteUserVariable"
}</source>

=trigger dzVents script using customEvent dzVents 3.0.0=

/json.htm?type=command&param=customevent&event=MyEvent&data=MyData

<source lang="json">{
"status": "OK",
"title": "Custom Event"
}</source>

=Room Plans=

==List all rooms==

<code>/json.htm?type=command&param=getplans&order=name&used=true</code>
<source lang="json">{
"result": [
{
"Devices": 6,
"Name": "Google Calendars",
"Order": "2",
"idx": "2"
},
{
"Devices": 2,
"Name": "Private",
"Order": "3",
"idx": "3"
},
{
"Devices": 1,
"Name": "EVOHome",
"Order": "4",
"idx": "4"
},
{
"Devices": 0,
"Name": "testPlan",
"Order": "5",
"idx": "5"
}
],
"status": "OK",
"title": "Plans"
}</source>

==List all devices in a room==

*IDX = id of your room

/json.htm?type=command&param=getplandevices&idx=IDX
Show idx, name of the device like:
<source lang="json">{
"result": [
{
"DevSceneRowID": "492",
"Name": "device name",
"devidx": "492",
"idx": "9",
"order": "9",
"type": 0
}
],
"status": "OK",
"title": "GetPlanDevices"
}</source>

/json.htm?type=devices&plan=IDX
show details of the devices like

<source lang="json">{
"ActTime": 1569909986,
"AstrTwilightEnd": "21:14",
"AstrTwilightStart": "05:50",
"CivTwilightEnd": "19:54",
"CivTwilightStart": "07:09",
"DayLength": "11:39",
"NautTwilightEnd": "20:34",
"NautTwilightStart": "06:30",
"ServerTime": "2019-10-01 08:06:26",
"SunAtSouth": "13:32",
"Sunrise": "07:42",
"Sunset": "19:21",
"app_version": "4.11337",
"result": [
{
"AddjMulti": 1,
"AddjMulti2": 1,
"AddjValue": 0,
"AddjValue2": 0,
"BatteryLevel": 255,
"CustomImage": 0,
"Data": "19.5 C, (13.5 C), PermanentOverride",
"Description": "",
"Favorite": 1,
"HardwareID": 30,
"HardwareName": "Evohome",
"HardwareType": "Evohome via Web API",
"HardwareTypeVal": 75,
"HaveTimeout": false,
"ID": "1168736",
"LastUpdate": "2019-10-01 08:05:35",
"Name": "Device name",
"Notifications": "false",
"PlanID": "4",
"PlanIDs": [
4
],
"Protected": false,
"SetPoint": 13.5,
"ShowNotifications": true,
"SignalLevel": 10,
"Status": "PermanentOverride",
"SubType": "Zone",
"Temp": 19.5,
"Timers": "false",
"Type": "Heating",
"TypeImg": "override_mini",
"Unit": 7,
"Used": 1,
"XOffset": "0",
"YOffset": "0",
"idx": "492"
}
],
"status": "OK",
"title": "Devices"
}</source>

=Timer Plans=

==List all Timerplans==

<code>/json.htm?type=command&param=gettimerplans</code>
<source lang="json">{
"result": [
{
"Active": false,
"Name": "Default",
"idx": 0
},
{
"Active": true,
"Name": "Holiday",
"idx": 1
},
{
"Active": false,
"Name": "Day off (including weekend)",
"idx": 2
}
],
"status": "OK",
"title": "GetTimerPlans"
}</source>

==Add Timerplan==

<code>/json.htm?type=command&param=addtimerplan&name=newTimerplan</code>
<source lang="json">{
"status": "OK",
"title": "AddTimerPlan"
}</source>

==Change Timerplan name==

<code>/json.htm?type=command&param=updatetimerplan&idx=3&name=newname</code>
<source lang="json">{
"status": "OK",
"title": "UpdateTimerPlan"
}</source>

==Duplicate Timerplan==

This will copy all existing timers from timerplan with idx 3 to a new plan

<code>/json.htm?type=command&param=duplicatetimerplan&idx=3&name=duplicatename</code>
<source lang="json">{
"status": "OK",
"title": "DuplicateTimerPlan"
}</source>

==Make Timerplan active==

This will make the timerplan with idx 2 the active one

<code>/json.htm?type=command&param=setactivetimerplan&ActiveTimerPlan=2</code>
<source lang="json">{
"status": "OK",
"title": "SetActiveTimerPlan"
}</source>

=History=

==Switch devices==
<code>/json.htm?type=command&param=getlightlog&idx=IDX</code>

===Delete===
<code>/json.htm?type=command&param=clearlightlog&idx=<idx></code>

==Text devices==
<code>/json.htm?type=command&param=gettextlog&idx=IDX</code>

===Delete===
/json.htm?type=command&param=clearlightlog&idx=<idx>

==Temperature==
<code>/json.htm?type=command&param=graph&sensor=temp&idx=IDX&range=[day|month|year]&actyear=YYYY</code>

==Custom sensor==

Totals by period :
<code>/json.htm?type=command&param=graph&sensor=Percentage&idx=IDX&range=day</code><source lang="json">{{
"result" :
[
{
"d" : "2021-02-04 16:40",
"v" : "308.6"
},
{
"d" : "2021-02-04 16:45",
"v" : "308.6"
},
.....

],
"status" : "OK",
"title" : "Graph Percentage day"
}
</source>

<code>/json.htm?type=command&param=graph&sensor=Percentage&idx=IDX&range=[day|month|year|year&actyear=YYYY]</code><source lang="json">{
"result" :
[
{
"d" : "2021-01-18",
"v_avg" : "308.6",
"v_max" : "309.6",
"v_min" : "307.6"
},
{
"d" : "2021-01-19",
"v_avg" : "308.6",
"v_max" : "310.6",
"v_min" : "306.6"
},
{
"d" : "2021-01-21",
"v_avg" : "308.6",
"v_max" : "310.6",
"v_min" : "306.6"
},
...

{
"d" : "2021-02-18",
"v_avg" : "308.6",
"v_max" : "310.6",
"v_min" : "306.6"
}
],
"status" : "OK",
"title" : "Graph Percentage <...>"
}
</source>

==Energy, Gas, Water==

Instantaneous consumption :

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

Totals by period :
<code>/json.htm?type=command&param=graph&sensor=counter&idx=IDX&range=[day|month|year|year&actyear=YYYY|YYYY-MM-DDTYYYY-MM-DD]</code>

Only for counters it is possible to specify a date range for long history data (not for short log data):
&range=YYYY-MM-DDTYYYY-MM-DD
Notice the "T" between the dates in range.

==Deleting History log entries==

===delete a single data point or day===

/json.htm?type=command&param=deletedatapoint&idx=IDX&date=DATE

*IDX = id of your device (This number can be found in the devices tab in the column "IDX")
*DATE = date in %Y-%m-%d format (for instance 2021-02-26) will delete history data of that particular day (one entry from long term history and max 120 entries from short term history log)
*DATE = date in "%Y-%m-%d%20%H:%M:%S" format (for instance 2019-10-03%2014:00:00) will delete history data of that particular time (one entry from short term history log)

<source lang="json">{
"status": "OK",
"title": "deletedatapoint"
}
</source>

===delete a date range of data points===

/json.htm?type=command&param=deletedaterange&idx=IDX&fromdate=FROMDATE&todate=TODATE V2020.2 build >= 13027 

*IDX = id of your device (This number can be found in the devices tab in the column "IDX")
*FROMDATE = date in %Y-%m-%d or date in "%Y-%m-%d%20%H:%M:%S"format (for instance 2021-02-26 / 2019-10-03%2014:00:00) will delete history data (from short and long history tables) starting with that day / time
*TODATE = date in %Y-%m-%d or date in "%Y-%m-%d%20%H:%M:%S"format (for instance 2021-02-26 / 2019-10-03%2014:00:00) will delete history data (from short and long history tables) ending with that day / time

<source lang="json">{
"status": "OK",
"title": "deletedaterange"
}
</source>

=Device Timer Schedules=
==Get all schedules (timers)==
/json.htm?type=command&param=getschedules

<source lang="json">{
"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"
},
</source>

==Get all schedules(timers) for all Devices==

/json.htm?type=command&param=getschedules&filter=device

<source lang="json">{
"result": [
{
"Active": "true",
"Color": "",
"Date": "",
"Days": 128,
"DevName": "coffeeSwitch",
"DeviceRowID": 1014,
"IsThermostat": "false",
"Level": 100,
"MDay": 0,
"Month": 0,
"Occurence": 0,
"Randomness": "false",
"ScheduleDate": "2021-03-11 06:01:00",
"Time": "06:01",
"TimerCmd": 0,
"TimerID": 62,
"TimerType": 2,
"TimerTypeStr": "On Time",
"Type": "Device"
},
{
"Active": "true",
"Color": "",
"Date": "",

"TimerType": 2,
"TimerTypeStr": "On Time",
"Type": "Device"
}
],
"status": "OK",
"title": "Schedules"
}
</source>

==Get all schedules(timers) for one Device==

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

===Type returns===

*0: Before Sunrise
*1: After Sunrise
*2: On Time
*3: Before Sunset
*4: After Sunset
*5: Fixed Date/Time
*6: Odd Day Numbers
*7: Even Day Numbers
*8: Odd Week Numbers
*9: Even Week Numbers
*10: Monthly
*11: Monthly (Weekday)
*12: Yearly
*13: Yearly (Weekday)
*14: Before Sun at South
*15: After Sun at South
*16: Before Civil Twilight Start
*17: After Civil Twilight Start
*18: Before Civil Twilight End
*19: After Civil Twilight End
*20: Before Nautical Twilight Start
*21: After Nautical Twilight Start
*22: Before Nautical Twilight End
*23: After Nautical Twilight End
*24: Before Astronomical Twilight Start
*25: After Astronomical Twilight Start
*26: Before Astronomical Twilight End
*27: After Astronomical Twilight End

<source lang="json">{
"result" :
[
{
"Active" : "true",
"Cmd" : 0,
"Color" : "",
"Date" : "",
"Days" : 128,
"Level" : 100,
"MDay" : 0,
"Month" : 0,
"Occurence" : 0,
"Randomness" : "false",
"Time" : "08:30",
"Type" : 23,
"idx" : "45"
}
],
"status" : "OK",
"title" : "Timers"
}
</source>

==Get all schedules(timers) for all Scenes==
/json.htm?type=command&param=getschedules&filter=scene

<source lang="json">{
"result" :
[
{
"Active" : "true",
"Color" : "",
"Date" : "",
"Days" : 128,
"DevName" : "Lights",
"DeviceRowID" : 6,
"IsThermostat" : "false",
"Level" : 100,
"MDay" : 0,
"Month" : 0,
"Occurence" : 0,
"Randomness" : "false",
"ScheduleDate" : "2021-03-12 07:01:00",
"Time" : "00:03",
"TimerCmd" : 1,
"TimerID" : 4,
"TimerType" : 0,
"TimerTypeStr" : "Before Sunrise",
"Type" : "Scene"
},
{
"Active" : "true",
"Color" : "",
"Date" : "",
"Days" : 128,
"DevName" : "Garden lights",
"DeviceRowID" : 6,
"IsThermostat" : "false",
"Level" : 100,
"MDay" : 0,
"Month" : 0,
"Occurence" : 0,
"Randomness" : "false",
"ScheduleDate" : "2021-03-12 09:00:00",
"Time" : "09:00",
"TimerCmd" : 1,
"TimerID" : 6,
"TimerType" : 2,
"TimerTypeStr" : "On Time",
"Type" : "Scene"
},
{
"Active" : "true",
"Color" : "",
"Date" : "",
"Days" : 128,
"DevName" : "Frontdoor",
"DeviceRowID" : 5,
"IsThermostat" : "false",
"Level" : 100,
"MDay" : 0,
"Month" : 0,
"Occurence" : 0,
"Randomness" : "false",
"ScheduleDate" : "2021-03-12 01:30:00",
"Time" : "01:30",
"TimerCmd" : 0,
"TimerID" : 2,
"TimerType" : 2,
"TimerTypeStr" : "On Time",
"Type" : "Scene"
}
],
"status" : "OK",
"title" : "Schedules"
}
</source>

==Get all schedules(timers) for one Scene==
/json.htm?type=command&param=getscenetimers&idx=sceneID

<source lang="json">{
"result": [{
"Active": "true",
"Cmd": 0,
"Date": "",
"Days": 128,
"Level": 100,
"MDay": 0,
"Month": 0,
"Occurence": 0,
"Randomness": "false",
"Time": "01:30",
"Type": 2,
"idx": "2"
}
],
"status": "OK",
"title": "SceneTimers"
}</source>

==Get all schedules(timers) for all Thermostats==

/json.htm?type=command&param=getschedules&filter=thermostat
<source lang="json">{
"status": "OK",
"title": "Schedules"
}</source>

==Get all schedules(timers) for one Thermostat==

/json.htm?type=command&param=getsetpointtimers&idx=timerID
<source lang="json">{
"status": "OK",
"title": "SetpointTimers"
}</source>

==Enable specific schedule(timer) for Devices==

/json.htm?type=command&param=enabletimer&idx=timerID
<source lang="json">{
"status": "OK",
"title": "EnableTimer"
}</source>

==Disable specific schedule(timer) for Devices==

/json.htm?type=command&param=disabletimer&idx=timerID
<source lang="json">{
"status": "OK",
"title": "DisableTimer"
}</source>

==Delete a specific schedule(timer) for Devices==

/json.htm?type=command&param=deletetimer&idx=timerID
<source lang="json">{
"status": "OK",
"title": "DeleteTimer"
}</source>

==Enable specific schedule(timer) for Thermostats==

/json.htm?type=command&param=enablesetpointtimer&idx=timerID
<source lang="json">{
"status": "OK",
"title": "EnableSetpointTimer"
}</source>

==Disable specific schedule(timer) for Thermostats==

/json.htm?type=command&param=disablesetpointtimer&idx=timerID
<source lang="json">{
"status": "OK",
"title": "DisableSetpointTimer"
}</source>

==Delete a specific schedule(timer) for Thermostats==
/json.htm?type=command&param=deletesetpointtimer&idx=timerID

<source lang="json">{
"status": "OK",
"title": "DeleteSetpointTimer"
}</source>

==Update parameters for a specific schedule(timer) for Devices==
/json.htm?type=command&param=updatetimer&idx=timerID&active=true&timertype=3&hour=0&min=20&randomness=true&command=0&days=12345<nowiki></source></nowiki>

*idx = timerID
*active = true/false
*timertype - see Get all schedules(timers) for one Device for timerTypeDefinition
*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

<source lang="json">{
"status": "OK",
"title": "AddTimer"
}</source>

*idx = DeviceRowID = index of your device (other commands use a timerID as idx but here we use DeviceRowID).
*active = true/false
*timertype - see Get all schedules(timers) for one Device for timerTypeDefinition
*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

<source lang="json">{
"status": "OK",
"title": "ClearTimer"
}
</source>

*idx = DeviceRowID = index of your device (other commands use a timerID as idx but here we use DeviceRowID).

==Enable specific schedule(timer) for Scenes/Groups==

/json.htm?type=command&param=enablescenetimer&idx=sceneID

<source lang="json">{
"status": "OK",
"title": "EnableSceneTimer"
}</source>

==Disable specific schedule(timer) for Scenes/Groups==

/json.htm?type=command&param=disablescenetimer&idx=sceneID

<source lang="json">{
"status": "OK",
"title": "DisableSceneTimer"
}
</source>

==Delete a specific schedule(timer) for Scenes/Groups==

/json.htm?type=command&param=deletescenetimer&idx=sceneID

<source lang="json">{
"status": "OK",
"title": "DeleteSceneTimer"
}
</source>

=Notifications=

==Get all notification types==

<code>/json.htm?type=command&param=getnotifications</code><source lang="json">{
"notifiers": [{
"description": "browser",
"name": "browser"
}, {
"description": "clickatell",
"name": "clickatell"
}, {
"description": "email",
"name": "email"
}, {
"description": "fcm",
"name": "fcm"
}, {
"description": "http",
"name": "http"
}, {
"description": "kodi",
"name": "kodi"
}, {
"description": "lms",
"name": "lms"
}, {
"description": "prowl",
"name": "prowl"
}, {
"description": "pushalot",
"name": "pushalot"
}, {
"description": "pushbullet",
"name": "pushbullet"
}, {
"description": "pushover",
"name": "pushover"
}, {
"description": "pushsafer",
"name": "pushsafer"
}, {
"description": "telegram",
"name": "telegram"
}
],
"status": "OK",
"title": "Notifications"
}</source>

==Get device notifications==

/json.htm?idx=<deviceIDX>&param=getnotificationtypes&type=command
 <source lang="json">{
"result":
[
{
"ptag": "S",
"text": "Switch On",
"val": 7
}
],
"status": "OK",
"title": "GetNotificationTypes"
}</source>

<code>/json.htm?type=command&param=getnotifications&idx=<deviceIDX></code><source lang="json">{
"notifiers": [{
"description": "browser",
"name": "browser"
}, {
"description": "clickatell",
"name": "clickatell"
}, {
"description": "email",
"name": "email"
}, {
"description": "fcm",
"name": "fcm"
}, {
"description": "http",
"name": "http"
}, {
"description": "kodi",
"name": "kodi"
}, {
"description": "lms",
"name": "lms"
}, {
"description": "prowl",
"name": "prowl"
}, {
"description": "pushalot",
"name": "pushalot"
}, {
"description": "pushbullet",
"name": "pushbullet"
}, {
"description": "pushover",
"name": "pushover"
}, {
"description": "pushsafer",
"name": "pushsafer"
}, {
"description": "telegram",
"name": "telegram"
}
],
"result": [{
"ActiveSystems": "clickatell;email;fcm;http;kodi;lms;prowl;pushalot;pushbullet;pushover;pushsafer;telegram",
"CustomMessage": "test",
"Params": "S",
"Priority": 0,
"SendAlways": false,
"idx": 3
}
],
"status": "OK",
"title": "Notifications"
}</source>

==Add device notification==

/json.htm?idx=<deviceIDX>&param=addnotification&tmsg=test&tpriority=0&tsendalways=true&tsystems=fcm;http&ttype=7&tvalue=0&twhen=0&type=command

<source lang="json">{
"status": "OK",
"title": "AddNotification"
}</source>

==Update device notifications==

/json.htm?devidx=<DeviceID>&idx=<notificationID>&param=updatenotification&tmsg=<msgText>&tpriority=<pri>&tsendalways=<true/false>&tsystems=<list of notification subsystems>&ttype=<notificationType>&tvalue=0&twhen=0&type=command
<source lang="json">{
"status": "OK",
"title": "UpdateNotification"
}</source>

==Delete device notification==

json.htm?idx=<notificationID>&param=deletenotification&type=command

<source lang="json">{
"status": "OK",
"title": "DeleteNotification"
}</source>

==Delete all device notifications==

/json.htm?idx=<deviceID>&param=clearnotifications&type=command
<source lang="json">{
"status": "OK",
"title": "ClearNotification"
}</source>

=LMS and Kodi (Media Players)=
While both Logitech Media Server and Kodi can be controlled by JSON RPC commands sent directly to the URL of the LMS server or Kodi instance, it can be useful to use Domoticz as a tunnel/proxy to send a number of widely-used commands because you may have an external port already open for Domoticz and because Domoticz also supports HTTPS.

==LMS==

<source lang="json">/json.htm?type=command&param=lmsmediacommand&idx=nnn&action=ACTION</source>

where ACTION can be: Left, Right, Up, Down, Favorites, Browse, NowPlaying, Shuffle, Repeat, Play, Pause, Stop, Rewind, Forward, Mute, VolumeUp, VolumeDown, PowerOn and PowerOff.

==Kodi==

<source lang="json">/json.htm?type=command&param=kodimediacommand&idx=nnn&action=ACTION</source>

where ACTION can be: PlayPause, Stop, FastForward, BigStepForward, Rewind, BigStepBack, ShowSubtitles, FullScreen, VolumeUp, VolumeDown, ChannelUp, ChannelDown, Channels
Home, Back, ContextMenu, Info, Select, Down, Right, Up, Left

=Evohome=

These commands work regardless of which of the 3 implementation-modes for Evohome you have chosen for your system (WebAPI, USB device, Scripting). Some of them will also work for e.g. the Honeywell Round WiFi thermostat.

==Updating the evohome controller mode==

<source lang="json"> /json.htm?type=command&param=switchmodal&idx=<idx>&status=<status>&action=<action>&ooc=<ooc></source>

*'''<idx>''' id number of the evohome controller device in Domoticz
*'''<status>''' Auto, AutoWithReset, AutoWithEco, Away, DayOff, Custom, HeatingOff
*'''<action>''' (1 = run on action script, 0 = disable)
*'''<ooc>''' (1 = only trigger the event & log on change, 0 = always trigger & log)

===Specify an until date===

<source lang="json"> /json.htm?type=command&param=switchmodal&idx=<idx>&status=<status>&action=<action>&ooc=<ooc>&until=<until></source>

*as above
*'''<until>''' ISO date time to run until. Format example ''2018-09-15T15:53:00'' or ''2018-09-15T15:53:00+01:00'' with timezone.

Note: most controller modes do not support the ''time'' part of the ISO data and will only act upon the ''date'' portion - this will require at least the next day to be reflected in the date number to successfully trigger an update.

==Updating a zone setpoint==

<code>/json.htm?type=command&param=setsetpoint&idx=<idx>&setpoint=<setpoint>&mode=<mode>&used=true</code>

*'''<idx>''' id number of the relevant evohome zone device in Domoticz
*'''<setpoint>''' set point in degrees (will be ignored for Auto)
*'''<mode>''' Auto, TemporaryOverride, PermanentOverride, FollowSchedule
*'''used''' must be true

===Specifying a date/time for zone TemporaryOverride===

<code>/json.htm?type=command&param=setsetpoint&idx=<idx>&setpoint=<setpoint>&mode=TemporaryOverride&until=<until>&used=true</code>

*as above
*'''<until>''' ISO date time for the set point override. Format example ''2018-09-15T15:53:00'' or ''2018-09-15T15:53:00+01:00'' with timezone.

In this case, any combination of a date portion and a time portion that are in the future will meet with success.

==Turning HotWater ON/OFF==

<code>/json.htm?type=command&param=setused&idx=<idx>&setpoint=<setpoint>&state=<state>&mode=<mode>&used=true</code>

*'''<idx>''' id number of the evohome DHW temp device in Domoticz
*'''<setpoint>''' set point in degrees (will be ignored)
*'''<state>''' On, Off
*'''<mode>''' Auto, TemporaryOverride, PermanentOverride, FollowSchedule
*'''used''' must be true

=Configuring zwave devices=
Below mentioned commands are for the to be deprecated OpenZwave integration. Switch to [[Zwave-JS-UI]] as soon as possible!! 
==Listing zwave node parameters==
<source lang="json"> json.htm?type=command&param=getopenzwavenodes&idx=ControllerIDX</source>

*ControllerIDX = the idx of your OpenZWave USB controller device, as listed under the 'Setup --> Hardware' tab.

Example output:

<source lang="json">
{
"NodesQueried" : true,
"ownNodeId" : 1,
"result" : [
{
"Description" : "Neo CoolCam Door/Window Detector",
"HaveUserCodes" : false,
"HomeID" : 3554707869,
"IsPlus" : true,
"LastUpdate" : "2018-08-04 20:09:02",
"Manufacturer_id" : "0x0258",
"Manufacturer_name" : "Neo CoolCam",
"Name" : "Garage DOor",
"NodeID" : 40,
"PollEnabled" : "false",
"Product_id" : "0x1082",
"Product_name" : "Door/Window Detector",
"Product_type" : "0x0003",
"State" : "Sleeping",
"Version" : 4,
"config" : [
{
"LastUpdate" : "2018-08-01 09:06:45",
"help" : "This configuration parameter that can be used to adjust the amount of delay before the OFF command is transmitted. This parameter can be configured with the value of 0 through 65535, where 0 means send OFF command immediately and 65535 means 65535 seconds of delay.",
"index" : 1,
"label" : "Configuring the OFF Delay",
"type" : "short",
"units" : "second",
"value" : "0"
},
{
"LastUpdate" : "2018-08-01 09:06:45",
"help" : "Basic Set Command will be sent where contains a value when the door/window is opened or closed, the receiver will take it for consideration; for instance, if a lamp module is received the Basic Set Command of which value is decisive as to how bright of dim level of lamp module shall be.",
"index" : 2,
"label" : "Basic Set Level",
"type" : "byte",
"units" : "",
"value" : "255"
},
{
"LastUpdate" : "2018-08-03 07:55:52",
"help" : "",
"index" : 2000,
"label" : "Wake-up Interval",
"type" : "int",
"units" : "Seconds",
"value" : "43200"
}
],
"idx" : "11"
},
{
"Description" : "FIBARO System FGWPE/F Wall Plug",
"HaveUserCodes" : false,
"HomeID" : 3554707869,
"IsPlus" : false,
"LastUpdate" : "2018-08-05 12:12:24",
"Manufacturer_id" : "0x010f",
"Manufacturer_name" : "FIBARO System",
"Name" : "Studio",
"NodeID" : 5,
.
.
.

</source>

Note the ''node_idx'' towards the end of each device's entry (the "idx" : "11" in the example above for the Neo CoolCam Door/Window Detector). You don't see this node_idx in the regular devices tab for Domoticz, but it is the idx you'll need when changing a parameter through JSON (next section).

==Getting the battery levels==
<source lang="json"> /json.htm?type=command&param=zwavegetbatterylevels&idx=controlleridx</source>

*controlleridx = the idx of your OpenZWave USB controller device, as listed under the 'Setup --> Hardware' tab.

Example output:

<source lang="json">
{
"result" : [
{
"battery" : 255,
"nodeID" : 17,
"nodeName" : "Designlamp bij TV"
},
{
"battery" : 255,
"nodeID" : 19,
"nodeName" : "Lichtknopje voorkamer"
},
{
"battery" : 100,
"nodeID" : 33,
"nodeName" : "Rookmelder"
}
],
"status" : "OK",
"title" : "GetBatteryLevels"
}</source>

Note: a Battery level of 255 indicates either a non battery powered device, or a battery powered device which has not yet send a battery measurement to OpenZWave yet.

==Changing a zwave device parameter==
<source lang="json"> /json.htm?type=command&param=applyzwavenodeconfig&idx=node_idx&valuelist=plist</source>

*node_idx = the value found by searching through the output of ''openzwavenodes'' for the node in question (see above)
*plist = the (partially) URI encoded and BASE64 encoded parameter list

The ''plist'' entries start with an unencoded decimal item number preceded by and followed by an underscore (e.g. _7_), followed by the correctly-encoded string. You can check out the encodings at the following links: [https://www.base64decode.org base64decode] and at [https://www.urlencoder.org urlencode]. In Base64, 'Enable' is written as 'RW5hYmxl', so it looks odd but it's easy once you grasp it.

For example, if you are configuring a NEO Coolcam Siren through JSON,

<source lang="json"> /json.htm?type=command&param=applyzwavenodeconfig&idx=10&valuelist=7_QWxhcm0gbXVzaWM%3D</source>

would change parameter 7 (Configure Default Siren On Mode) to 'Alarm music', while

<source lang="json"> /json.htm?type=command&param=applyzwavenodeconfig&idx=10&valuelist=7_RG9vciBiZWxsIG11c2lj%3D</source>

would change it to 'Door bell music' (because 'RG9vciBiZWxsIG11c2lj' is the result of Base64 encoding 'Door bell music'). Note: Any '%3D' and such in the ''plist'' are the result of URI encoding an '=' or other non-alphanumeric character.

The easiest way to learn about this is to change a zwave device parameter manually using your browser while you have '''developer tools''' enabled (hit 'ctrl-shift-i' in Chrome). Look under the ''network'' tab at the JSON sent back by the browser to Domoticz when you click on 'Apply Configuration for This Device'.

<source lang="json"> /json.htm?type=command&param=applyzwavenodeconfig&idx=10&valuelist=3_MjU1_1_SGlnaA%3D%3D_
2_MSBtaW51dGU%3D_4_TG93_5_MTA%3D_6_MQ%3D%3D_7_QWxhcm0gbXVzaWM%3D_8_RW5hYmxl_9_RGlzYWJsZQ%3D%3D_</source>

The browser will actually send the full parameter list to Domoticz, including the unchanged values of any parameters you didn't alter. If you modify one of them, however, you'll see that edit reflected in the Base64-encoded JSON string.

[[File:Screenshotjsondebug.png]]

=Language-specific JSON examples=
The following tiny code snippets demonstrate the syntax for using JSON with Domoticz from some popular programming languages.

==Bash==
<source lang="bash">
#!/bin/bash
curl -s 'http://192.168.178.12:8080/json.htm?type=devices&rid=104' | jq .result[0].Temp | sed 's/\"//g' | awk '{ print $1 }'
</source>

==PHP==
<source lang="php">
#!/usr/bin/php

<?php
$json_string = file_get_contents("http://192.168.178.12:8080/json.htm?type=devices&rid=110");
$parsed_json = json_decode($json_string, true);
$test_link = "/home/pi/output.txt";
$test_data = fopen ($test_link, "w+");
fwrite ($test_data, print_R($parsed_json, TRUE));
fclose ($test_data);
?>

</source>

==Python==
<source lang="python">
#!/usr/bin/python

import urllib
import urllib2
import requests

...

url = 'http://192.168.178.12:8080/json.htm?type=command&param=udevice&nvalue=0&idx='+idx+'&svalue='+sval
try:
request = urllib2.Request(url)
response = urllib2.urlopen(request)
except urllib2.HTTPError, e:
print e.code; time.sleep(60)
except urllib2.URLError, e:
print e.args; time.sleep(60)
</source>

==Perl==
<source lang="perl">

#!/usr/bin/perl

use LWP::UserAgent;
use JSON::XS;

$url{domo}=>'http://192.168.178.12:8080';
$idx=301;

$ua=LWP::UserAgent->new; $ua->timeout(5);
$retrieve=$ua->get($url{domo}.'/json.htm?type=devices&rid='.$idx);
$res=$retrieve->decoded_content;
if ($retrieve->is_success) { $jres = JSON::XS->new->allow_nonref->decode($res) } else { warn $retrieve->status_line };
$state=$$jres{result}[0]->{Status}; # 'On', 'Off', 'Open', 'Closed', etc
print "The switch state for idx $idx is currently '$state'\n";

</source>

Logitech Media Server

2019-07-11T07:07:15Z

Philchillbill: /* Setup process */

Documentation for Logitech Media Server

==Introduction==
Logitech Media Server (formerly SlimServer, SqueezeCenter and Squeezebox Server) is a streaming audio server supported by Logitech (formerly Slim Devices), developed in particular to support their Squeezebox range of digital audio receivers. Logitech EOL'd the product line in 2012 but the open-source LMS software is still actively developed in a so-called community effort.
The latest version can be downloaded here - http://downloads.slimdevices.com/nightly. Synology provides updates to a fairly recent community build from time to time on their beta channel.

==Logitech Media Server in Domoticz==

===Logitech Media Server Settings===
Your Logitech Media Server must be configured to allow Domoticz to control the attached players. Default port for Web Server connections is 9000 or 9002.

[[File:LMS Server.png]]

===Adding Hardware===
Add the Logitech Media Server via the Hardware page under Settings. Fill in the IP of your Logitech Media Server and the port you specified.

[[File:LMS Hardware.png]]

====Domoticz Settings====
Click 'Setup' to see the detected/connected players.
* Poll interval controls how often Domoticz will attempt to reconnect to the Logitech Media Server to poll the player's status.
* Ping timeout controls how long Domoticz will try to contact the Logitech Media Server.

[[File:LMS Settings.png]]

====Detected Players====
If you entered the correct IP & port of your Logitech Media Server, your players will be detected and displayed under Devices.
It displays names and MAC-addresses.

====Supported Models====
The supported models are:
* Squeezebox 1
* Squeezebox 2
* Squeezebox 3
* Squeezebox Receiver
* Squeezebox Boom
* Squeezebox Controller
* SqueezePlay
* Squeezebox Radio
* Squeezebox Touch
* iPeng iOS App (iPhone & iPad)
* Max2Play SqueezePlug
* [https://www.picoreplayer.org/ PiCoreplayer] based on Squeezelite software

===Troubleshooting===
If your player model is not supported, it will be reported in the logfile. The logfile also reports detected players when starting the Logitech Media Server hardware.

===Events and Notifications===
Domoticz device events work for Logitech Media Players using both Blockly and LUA.

Events and notifications are triggered for:
{| class="wikitable"
|-
|On
|-
|Off/Disconnected
|-
|Play
|-
|Pause
|-
|Stop
|}

The following actions can be performed by using 'Set' on a Logitech Media Player.

{| class="wikitable"
|-
|On or Group On
|Will turn the device on.
|-
|Off or Group Off
|Will turn the device off.
|-
|Play
|Will send a Play command.
|-
|Pause
|Will toggle between Play and Pause.
|-
|Stop
|Will send a Stop command.
|-
|Set Volume <0-100>
|Will set the volume of the player-output.
|-
|Play Playlist <name>
|Will play the playlist with name <name>.
|-
|Play Favorites
|Will play the favorites.
|}

Example: 
<code>commandArray['SqueezeBox']='On'</code> 
<code>commandArray['SqueezeBox']='Play'</code> 
<code>commandArray['SqueezeBox']='Set Volume 30'</code> 
<code>commandArray['SqueezeBox']='Play Playlist WakeUpList1'</code> 
<code>commandArray['SqueezeBox']='Play Favorites</code> 

==On Screen Notifications==
Domoticz can display notification messages on the screens of certain Logitech Media Players. This is configured via the Notifications tab on the Settings page as shown here:

[[File:LMS Notifications.png]]

Fill in the MAC-address (separated by a semicolon) and the duration that the message will be displayed on the screen (in seconds)
The MAC-address of your player(s) can be found in the Hardware-settings of your Logitech Media Server hardware.

==Known Issues==
* (Song-)Titles with special characters will show wrong symbols in the logfile.

==Work in Progress==
* Add support for Timers (schedule your player to play playlists)

==Audio Alerts via Squeezebox Players==

The Squeezebox radio and boom players can be used to play audio alerts from Domoticz via the following perl scripts. The concept will work with any type of player (including software players) but the radio and boom are well-suited as they have their own amplifier and can therefore act autonomously.

Two different approaches are shown. The first one uses a script that's ''multi-threaded'' and will play alerts on multiple players around your home at more or less the same time (but not truly synced). This has the advantage of not interfering with any syncgroups you may habitually use. The second approach assembles/disassembles a temporary ''syncgroup'' from the players in question, meaning no echo around the house if you deploy alerts to a lot of players at the same time. You can try both approaches and see which one works best for you. One thing worth knowing about syncgroups is that they often start out with a small time-difference between players which is then quickly corrected by LMS (it speeds up a lagging player to catch up). If this happens when playing an audio alert then part of the speech will be skipped over as the sync progresses. YMMV but if it happens a lot in your situation then it's best to use the multi-threaded version.

=== How it works ===
The basic idea (with both approaches) is to first retrieve and save several current parameters from each player: power state (on/off), play-mode (play/pause/stop), repeat-mode (none/song/playlist), current-playlist (if any), current time-position within currently-playing song (if any), plus the current volume setting. Next we play the desired alert audio clips - first a 'pre-chime' to get our attention, then the actual alert message MP3 audio file (you can pre-generate a series of these using e.g. text-to-speech software). In doing this we power-on each player if it was off, pause the current song if the player was active, set repeat to 'none' so we don't play an infinite loop of alerts, and set the desired volume-level. When we see the alert has come to an end, we return everything back the way it was prior to the alert. In the case of the second approach which builds temporary syncgroups, the group is also disassembled.

The heavy-lifting is done by a perl subroutine called ''&squeezeAlert'' which is contained in a perl script ''squeezealert.pl''. In use, we will call this from a tiny bash script ''sqalert.sh'' which takes care of running the perl job as a background process so we return immediately to Domoticz and there's no waiting. This bash pre-script also allows us to use ''ssh'' to execute the perl on a remote machine if we need to (see below).

In the on-action / off-action fields of a Domoticz switch, you can now use a construct along the lines of

script://sqalert.sh kitchen Ring06.wav downloadReady.mp3 60
script://sqalert.sh livingroom none garageDoorClosed.mp3 50
script://sqalert.sh "kitchen, livingroom" Ring06.wav garageDoorOpen.mp3 55
script://sqalert.sh "livingroom, office, studio" Ring06.wav washingmachineFinished.mp3 70

See the comments in the code for an exact description of the 4 parameters (''players, prechime, ttsfile, volume''). If it doesn't work for you, try specifying the full path to the bash file with a triple-slash

script:///home/pi/domoticz/scripts/sqalert.sh livingroom none garageDoorClosed.mp3 50

''Tip:'' You can copy some of the audio clip files in a Windows ''/media'' folder over to your ''alerts'' directory as pre-alert chimes (the RingXX.wav ones are nice for this purpose). The spoken messages alerting for things like 'Motion detected in Hallway' or 'Garage door has been left open longer than 10 minutes' can be saved to mp3 files using an online service like Amazon Polly.

=== Setup Considerations ===

With all the perl scripts in this LMS wiki, some modules from ''CPAN'' (Comprehensive Perl Archive Network) need to be installed. This is no problem on Linux and on Windows, but is a major problem on Synology NAS devices which have a rather stripped-down Linux under the hood with no build environment. There is a simple workaround for this using remote scripting, but let's first get something clear about where/what needs to be installed. When any one of the perl scripts here are active, 3 different pieces of software are ultimately involved:

1. LMS server software
2. Domoticz
3. Our perl script(s)

These 3 can all run on the same computer but they can also be run on 3 ''different'' computers with no problems whatsoever. Synology users can run both LMS and Domoticz e.g. on their Synology, but run the perl script(s) on a separate perl-friendly machine such as a spare RPi. This is possible because we can get a Domoticz on/off action to run a script on a remote machine by using ''ssh'' (explained below) with ''Public-Key Authentication''. You also only need '''one''' instance of Domoticz running, so if you are using a separate machine for the perl-scripts then it does ''not'' need to have a slave Domoticz instance installed on it. Please keep this in mind when deciding on what machine(s) to run these packages. Also note that the ''ssh'' remote-scripting option is only needed when the perl-script is remote to the Domoticz machine - it doesn't matter if LMS is remote or not.

=== Setup process ===

'''Note:''' The temporary now-playing playlist saved for restoring after the alert is played will be stored in your regular LMS ''playlists'' folder as defined in your LMS configuration. You '''must''' define a playlists folder (even if you use Spotify) or else resuming the current song after the alert plays will go wrong and Spotty will just stop after the alert. In the LMS web interface, go to ''settings --> basic settings --> playlists folder''. Also, please ensure that the folder has read/write permissions set correctly (on Linux, chmod 666).

For the local audio files, it's best to create a subfolder in your LMS ''music'' folder called ''alerts'' and to put all your pre-chimes and alert-TTS files in there.

First make sure perl is installed (it very likely is on a linux-based OS) and then install the modules from CPAN that we need (''note'': Parallel::Loops is not needed for the syncgroup version):

sudo apt-get update
sudo cpan install Parallel::Loops
sudo cpan install JSON::RPC::Client
sudo cpan install JSON::XS

Create a bash script called ''sqalert.sh'' with the following content. Substitute the ''.../domoticz/scripts'' for the path to the directory that Domoticz accesses by default when you use the ''on/off actions'' for a switch (on a pi that would nominally be ''/home/pi/domoticz/scripts'', on Synology ''/volume1/homes/USERNAME/domoticz/scripts'')

<syntaxhighlight lang="bash">
#! /bin/sh
/usr/bin/perl .../domoticz/scripts/squeezealert.pl $1 $2 $3 $4 > /dev/null 2>&1 &
</syntaxhighlight>

Put it in that ''.../domoticz/scripts'' directory on whichever machine in your setup runs Domoticz and of course do a ''chmod +x'' afterwards.

If you are using the remote script option (i.e. Domoticz and perl-script on separate machines), use this version of ''sqalert.sh'' instead (''note'': it is still installed in the .../domoticz/scripts directory on the ''local'' machine running Domoticz):

<syntaxhighlight lang="bash">
#! /bin/sh
ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy /usr/bin/perl /path/to/remote/scriptdir/squeezealert.pl $1 $2 $3 $4 > /dev/null 2>&1 &
</syntaxhighlight>

where 192.168.xxx.yyy is the IP address of the remote machine that the perl script will actually run on, the ''-p'' specifies the port to use for ssh on the remote machine (usually 22), ''privatekey'' is the keyfile in the local ~/.ssh directory (on the Domoticz machine) allowing ssh login to the remote machine without specifying a password, and ''/path/to/remote/scriptdir'' is the arbitrary path to the directory your perl scripts are stored in on that remote machine.

If you plan on using the remote-scripting option and you haven't already set up ''ssh'' for non-interactive login on the target/remote machine, use the command ''ssh-keygen -t rsa'' to generate the two files with public/private keys and put the ''public'' key in the ~/.ssh directory on the target/remote machine and the ''private'' key in ~/.ssh on the local machine where Domoticz is running. You will also have to do a ''chmod 700'' on the ~/.ssh directory itself and ''chmod 600'' on the key files themselves or it won't work.

Next, create a perl script called ''squeezealert.pl'' in the directory/machine pointed to by the path you just used in the bash script, with the following content (and do a ''chmod +x'' afterwards). ''Note:'' You will need to edit the parameters for player-mac's, the URL of your LMS instance, plus the full linux pathname to your alerts directory after creating this script (all parameters are case-sensitive too).

====First variant of squeezealert.pl, not using syncgroups but using threading====

This script implements semi-synchronised alerts on multiple players through multi-threading using the ''Parallel::Loops'' module. You can use either this one or the next script below (''second variant''):

<syntaxhighlight lang="perl">
#!/usr/bin/perl

# Plays a text-to-speech (TTS) alert on a Squeezebox, temporarily interrupting any music that's playing and then restoring
# An optional pre-chime doodle is played to first get our attention

# Author: philchillbill, 2017-2018

use JSON::RPC::Client;
use JSON::XS;
use Parallel::Loops;
no warnings 'uninitialized';

# -----------------------------------------------------------------------------
# We call this perl script from the command line, passing 4 parameters to it:

# 1. 'players' is a string consisting of a comma-separated list of player names (no spaces!) in quotes.
# e.g. "kitchen" or "kitchen, livingroom, bedroom" but NOT "kitchen, living room, bedroom"
# 2. 'prechime' is the filename of the jingle to be played just prior to the spoken alert to grab our attention. e.g. 'Ring06.wav'.
# If no pre-chime is desired, use 'none'. The folder 'C:\Windows\media' has nice examples (files RingXX.wav).
# 3. 'ttsfile' is the filename of the spoken alert message. e.g. 'garageDoorOpen.mp3'
# 4. 'avol' is the volume that the alert is to be played at and should be 0-100. In practice, values of 40-80 are realistic.

# Edit the following parameters to suit your setup:

# The mac addresses for all the squeezebox players that will use alerting
%uuids = (
kitchen => '00:04:20:aa:bb:cc',
livingroom => '00:04:20:aa:bb:cc',
office => '00:04:20:aa:bb:cc'
);

# The full path to the directory where all the TTS mp3/wav files are stored. Please use the name 'alerts' somewhere in it.
%dir = (
alerts => 'file:///volume1/music/alerts'
);

# The URL for the LMS server instance, usually on port 9000 or 9002
%url = (
lms => 'http://192.168.1.3:9002/jsonrpc.js'
);

# -----------------------------------------------------------------------------

sub squeezeAlert {
($player, $prechime, $afile, $avol)=@_;
$client=new JSON::RPC::Client; $playerid=$uuids{$player};
# Get the player's present state so it can be restored later, but not if last-playing was an alert (path is checked)
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'path', '?'] ] });
if (!$res) { return }; # player must be disconnected/offline so return
if ($res->is_success) {
$jres=$res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres); $path=$$jdata{result}{_path} || 'empty';
$restore=($path!~m/alerts|^empty$/) || 0;
if ($restore) {
$res = ( $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['status', '-', '1', 'tags' ] ] }) ) || 0;
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres);
$repeat=$$jdata{result}{'playlist repeat'};
$power=$$jdata{result}{power};
$mode=$$jdata{result}{mode}; $noplay=($mode!~m/play/) || 0;
$mvol=$$jdata{result}{'mixer volume'};
$time=$$jdata{result}{time};
if ($mode eq 'play') { $res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['pause'] ] }); }
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'save', "nowplaying$player", 'silent:1'] ] });
}}
# now we have the present state of the player, get ready to play the alert:
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', '1'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mixer', 'volume', $avol ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'repeat', '0'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'clear'] ] });
# build the temporary alert playlist
if ($prechime eq 'none') { @play=($afile) } else { @play=($prechime, $afile) };
foreach $file (@play) {
$filetoplay="$dir{alerts}/$file";
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'add', "$filetoplay"] ] });
}
# now play the alert-playlist
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['play'] ] });
# and wait for it to stop
do {
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mode', '?'] ] });
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres); $mode=$$jdata{result}{_mode};
sleep 1;
} until ($mode eq 'stop');
# ok, we are done playing so either restore the music playlist we interrupted, or power off if nothing was playing
if ($restore) {
# Restore player to previous state
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mixer', 'volume', $mvol ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'repeat', $repeat ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'resume', "nowplaying$player", "noplay:$noplay" ] ] }); ;
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['time', $time ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', $power] ] });
}
else { # no restore, just clear and power-off
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'clear'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', '0'] ] });
}
return;
}

($players, $prechime, $ttsfile, $avol)=@ARGV;
@players=split(/,\s?/, $players);

$maxProcs = 6;
$pl = Parallel::Loops->new($maxProcs);
$pl->foreach (\@players, sub { &squeezeAlert( $_, $prechime, $ttsfile, $avol ) });

</syntaxhighlight>

====Second variant of squeezealert.pl, using temporary syncgroups====

This script assembles/disassembles temporary syncgroups when alerts are played on multiple players (note: you should use ''either'' this script ''or'' the ''first variant'' above, but not both!):

<syntaxhighlight lang="perl">
#!/usr/bin/perl

# Plays a text-to-speech (TTS) alert on a Squeezebox, temporarily interrupting any music that's playing and then restoring
# An optional pre-chime doodle is played to first get our attention

# THIS VERSION ASSEMBLES/DISASSEMBLES TEMPORARY SYNCGROUPS FOR THE DURATION OF THE ALERT

# Author: philchillbill, 2017-2018

use JSON::RPC::Client;
use JSON::XS;
no warnings 'uninitialized';

# -----------------------------------------------------------------------------
# We call this perl script from the command line, passing 4 parameters to it:

# 1. 'players' is a string consisting of a comma-separated list of player names (no spaces!) in quotes.
# e.g. "kitchen" or "kitchen, livingroom, bedroom" but NOT "kitchen, living room, bedroom"
# 2. 'prechime' is the filename of the jingle to be played just prior to the spoken alert to grab our attention. e.g. 'Ring06.wav'.
# If no pre-chime is desired, use 'none'. The folder 'C:\Windows\media' has nice examples RingXX.wav.
# 3. 'ttsfile' is the filename of the spoken alert message. e.g. 'garageDoorOpen.mp3'
# 4. 'avol' is the volume the alert is to be played at and should be 0-100. In practice, values of 40-80 are realistic.

# Edit the following parameters to suit your setup:

# The mac addresses for all the squeezebox players that will use alerting
%uuids = (
kitchen => '00:04:20:aa:bb:cc',
livingroom => '00:04:20:aa:bb:cc',
office => '00:04:20:aa:bb:cc'
);

# The full path to the directory where all the TTS mp3/wav files are stored. Please use the name 'alerts' somewhere in it.
%dir = (
alerts => 'file:///volume1/music/alerts'
);

# The URL for the LMS server instance, usually on port 9000 or 9002
%url = (
lms => 'http://192.168.1.3:9002/jsonrpc.js'
);

# -----------------------------------------------------------------------------

sub squeezeAlert {
($sbgroup, $prechime, $afile, $avol)=@_; @players=@{$sbgroup};
$client=new JSON::RPC::Client;
# Get each player's present state so it can be restored later, but not if last-playing was an alert (path is checked)
foreach $sb (@players) {
$playerid=$uuids{$sb};
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'path', '?'] ] });
if (!$res) { if (scalar(@players)==1) { return } else { next } }; # player must be disconnected/offline so skip
if ($res->is_success) {
push(@alive, $sb); # add sb to the array of connected players
$jres=$res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres); $path=$$jdata{result}{_path} || 'empty';
$restore{$sb}=($path!~m/alerts|^empty$/) || 0;
if ($restore{$sb}) {
$res = ( $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['status', '-', '1', 'tags' ] ] }) ) || 0;
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres);
$repeat{$sb}=$$jdata{result}{'playlist repeat'};
$power{$sb}=$$jdata{result}{power};
$mode{$sb}=$$jdata{result}{mode}; $noplay{$sb}=($mode{$sb}!~m/play/) || 0;
$mvol{$sb}=$$jdata{result}{'mixer volume'};
$time{$sb}=$$jdata{result}{time};
if ($mode{$sb} eq 'play') { $res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['pause'] ] }); }
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'save', "nowplaying$sb", 'silent:1'] ] });
}}
# now we have the present state of the player, get ready to play the alert:
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', '1'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mixer', 'volume', $avol ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'repeat', '0'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'clear'] ] });
}
# replace the players-list by the list of verified connected players
@players=@alive;
# build the sync group, if more than one player specified
$master=shift @players;
foreach $sb (@players) {
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$master}, ['sync', $uuids{$sb} ] ] });
}
# build the temporary alert playlist
if ($prechime eq 'none') { @play=($afile) } else { @play=($prechime, $afile) };
foreach $file (@play) {
$filetoplay="$dir{alerts}/$file";
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $uuids{$master}, ['playlist', 'add', "$filetoplay"] ] });
}
# now play the alert-playlist
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $uuids{$master}, ['play'] ] });
# and wait for it to stop
do {
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $uuids{$master}, ['mode', '?'] ] });
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres); $mode=$$jdata{result}{_mode};
sleep 1;
} until ($mode eq 'stop');
# ok, we are done playing so either restore the music playlist we interrupted, or power off if nothing was playing
foreach $sb ($master, @players) {
$playerid=$uuids{$sb}; $res = $client->call($url{lms}, { method => 'slim.request', params => [ $playerid, ['sync', '-' ] ] });
if ($restore{$sb}) {
# Restore player to previous state
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mixer', 'volume', $mvol{$sb} ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'repeat', $repeat{$sb} ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'resume', "nowplaying$sb", "noplay:$noplay{$sb}" ] ] }); ;
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['time', $time{$sb} ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', $power{$sb}] ] });
}
else { # no restore, just clear and power-off
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'clear'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', '0'] ] });
}
}
return;
}

($players, $prechime, $ttsfile, $avol)=@ARGV;
@players=split(/,\s?/, $players);
&squeezeAlert( \@players, $prechime, $ttsfile, $avol );

</syntaxhighlight>

=== Testing ===
To test either script first (outside Domoticz), you should ''cd'' to the directory where you placed the bash script and issue the following command (assuming you have a player called ''livingroom'', plus files called ''Ring06.wav'' and ''garageDoorOpen.mp3'' in your alerts folder - change as appropriate to your setup):

./sqalert.sh livingroom Ring06.wav garageDoorOpen.mp3 60

If that works OK and you hear the pre-chime and message, you should then be good to go to use the script within Domoticz. If you have issues getting the remote (''ssh'') scripting working, you can first verify that the remote-login keys are working by typing

ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy

from the command line on the ''local'' machine. If it works then you will just silently receive a terminal-prompt from the remote machine (you might have to accept the remote machine as trusted the first time this is done - just go ahead and do it). If it doesn't work then check the permissions (not higher than 600 on the keyfiles!) and check that the keyfiles are in the home directory for the correct user (are you going to run Domoticz as root, pi, another user... ?). At a minimum, you should already be able to login via ssh to the remote machine using a username and password - if that's not working then this certainly won't work (e.g. check port 22 open, check that the ''ssh'' service is started).

==Using Ambient Light Sensor in SB-Radio and SB-Touch ==

Both the SB Radio and SB Touch have an internal sensor to detect the ambient light level and dim the display when the room is darker or to brighten it when it's light. It's possible to install a background-running script on the player that will regularly update Domoticz with this measured light level (don't worry - it still operates when the player is in standby). This only works meaningfully for a player located in a normally-dark room such as a bathroom with no windows. It can then be used to check if the bathroom is occupied because the light will usually be on when somebody is in there. Use this info e.g. to change the colour of a Hue lamp downstairs so you know when the toilet is occupied upstairs, to start a ventilator if the light in the bathroom is on for a while, or even to autoplay music on the player when somebody turns on the light in the room.

===Setup===
First of all, you should enable ''ssh'' login on the SB in question. On the player's own UI, go to:

''Settings --> Advanced --> Remote Login'' and make sure ''Enable SSH'' is ticked/selected.

Now use a program such as ''putty'' or ''smarTTY'' to ssh into the player, using username ''root'' and default password ''1234''. This will log you into the ''/root'' home directory on the SB. IF you have problems with ssh, try ''ssh -oKexAlgorithms=+diffie-hellman-group1-sha1 -c 3des-cbc root@192.168.XXX.XXX'' instead. Use smarTTY or a program like Cyberduck to upload the following shell script to that /root directory. Call this file ''domosb.sh'' and make sure you have Unix file-endings in it (LF) if you copy/paste from here. When it's copied to the SB, don't forget to ''chmod +x'' to make it executable.

<syntaxhighlight lang="bash">

#!/bin/sh
# script to read the ambient light sensor on a Squeezebox Radio or Touch and send the data to Domoticz
# it returns a value of 100000 in near darkness and a value of typically ~100-500 when illuminated

# Author: philchillbill, 2017. Inspired by https://github.com/luebbers/bathroomd
# Improved: Robert Lagus 2018 with logic checker for near darkness values

DOMO="192.168.XXX.XXX:8080" # IP and port of your Domoticz instance
PLAYER="Smart%20Radio" # Name of the player to appear in the Domoticz log (URI encoded)
LEVEL=XX # idx of the Domoticz 'lux' device to update with the ambient light level
SWITCH=XX # idx of the on/off switch used to indicate presence

# for the SB Radio use this as the path to the SENSOR data
SENSOR="/sys/class/i2c-adapter/i2c-1/1-0010/ambient"
# Note: for the SB Touch use the following instead
# SENSOR="/sys/class/i2c-adapter/i2c-0/0-0039/lux"

# say Hello World to the Domoticz Log after waiting a bit for network to be up
sleep 20
wget -O /dev/null -q "http://"$DOMO"/json.htm?type=command&param=addlogmessage&message=SB%20"$PLAYER"%20commenced%20ambient%20light%20monitoring."

# read out the sensor every 2 seconds in an infinite loop
# we only update Domoticz when a meaningful change in Lux occurs (but at least once every 30 minutes to keep the sensor active)
PREV=0; LOOPS=0; SET=0
while /bin/true; do
LOOPS=$(( $LOOPS + 1 )); if [ "$LOOPS" -gt 1000000 ]; then LOOPS=0; fi
VAL=`cat $SENSOR | tr -d "\n"`
if [ "$VAL" -gt 90000 ]; then
VAL=0
fi
DELTA=$(($VAL - $PREV))
if [ "$DELTA" -ge 0 ]; then
STEP=$DELTA
else
STEP=$((0 - $DELTA)) # step is the absolute-value of the delta in lux
fi
# this updates the sensor-level value shown in the Domoticz 'Lux' meter
if [ "$STEP" -gt 20 ] || [ $(($LOOPS % 900)) -eq 0 ]; then
wget -O /dev/null -q "http://"$DOMO"/json.htm?type=command&param=udevice&idx="$LEVEL"&svalue="$VAL""
fi
# this sets the on/off switch in Domoticz, with a little hysteresis to prevent the switch 'chattering'
if [ "$VAL" -lt 400 ] && [ "$SET" -eq 0 ]; then
wget -O /dev/null -q "http://"$DOMO"/json.htm?type=command&param=switchlight&idx="$SWITCH"&switchcmd=On"
SET=1
else
if [ "$VAL" -gt 500 ] && [ "$SET" -eq 1 ]; then
wget -O /dev/null -q "http://"$DOMO"/json.htm?type=command&param=switchlight&idx="$SWITCH"&switchcmd=Off"
SET=0
fi
fi
PREV=$VAL
sleep 2
# echo $VAL "=VAL"
# echo $STEP "=STEP"
# echo $DELTA "=DELTA"
# echo $PREV "=PREV"
# echo $LOOPS "=LOOPS"
# echo " "
done

</syntaxhighlight>

The ''i2c'' sensor in the SB-Radio produces a value of 100,000 in (almost) darkness and a value of ~100 - ~500 when the lights in the room are on. This script makes sure that Domoticz only gets updated if there is a meaningful change in light level (>20) to mask tiny fluctuations and keep network traffic down. It sends something at least every 30 minutes just to make sure Domoticz doesn't mark it as an offline sensor if it hears nothing for too long.

===Testing===
After transferring the script into the /root folder on the SB you can play around with it first interactively (command: ''./domosb.sh'') to make sure you got it all set up right and also that the thresholds work for you. I created a ''Lux'' sensor-type in Domoticz (via ''Setup-->Hardware-->Dummy-->Create Virtual Sensors'') to display the raw sensor data (in the example above it had an idx of LEVEL) and also an on/off switch (with idx of SWITCH) to act as a toggled occupancy-sensor. When you are satisfied that the script works OK you can get it to autostart upon booting of the SB by adding a line to the very end of the ''/etc/init.d/rcS'' file (vi was the only editor on my SB - there was no nano editor).

<syntaxhighlight lang="bash">
# Add the following to the very end of the file '/etc/init.d/rcS':

# Start Domoticz Script
echo "Starting Domoticz script"
/root/domosb.sh &
</syntaxhighlight>

Don't forget that ''&'' at the end or it won't run in the background. The load of running this script makes the SB user interface a tiny bit laggy but does not affect audio playback. You can type ''reboot'' to restart the player and get the script auto-running. Of course the data produced by this script is not really a lux value (due to the inversion and high non-linearity) but for our purposes here that's irrelevant.

==Transfer Playlist Among Players==

As you move around a house with multiple Squeezebox players, it can be useful to transfer the parameters of the currently-playing player (in a room you are about to leave, for example) to a player in a room you are about to go to. For example, you were listening to music on the SB-Touch in the livingroom and now you're going to take a shower so you want to transfer to the SB-Radio in the bathroom. The following script achieves that by saving the state of the ''source'' player and restoring those parameters to the ''target'' player before powering off the source. If the source player was not playing anything at that time then nothing happens because there's nothing to transfer. The volume-level and repeat-mode of the source are also transferred to the target. This script can be used e.g. with Alexa/HA-Bridge or it can be linked to a Domoticz switch-event such as an occupancy-sensor.

In the on-action / off-action fields of a Domoticz switch, you can use a construct along the lines of

script://sqxfer.sh livingroom bathroom
script://sqxfer.sh kitchen livingroom

If it doesn't work for you, try specifying the full path to the bash file with a triple-slash

script:///home/pi/domoticz/scripts/sqxfer.sh livingroom bathroom

=== Setup Considerations ===

With all the perl scripts in this LMS wiki, some modules from ''CPAN'' (Comprehensive Perl Archive Network) need to be installed. This is no problem on Linux and on Windows, but is a major problem on Synology NAS devices which have a rather stripped-down Linux under the hood with no build environment. There is a simple workaround for this using remote scripting, but let's first get something clear about where/what needs to be installed. When any one of the perl scripts here are active, 3 different pieces of software are ultimately involved:

1. LMS server software
2. Domoticz
3. Our perl script(s)

These 3 can all run on the same computer but they can also be run on 3 ''different'' computers with no problems whatsoever. Synology users can run both LMS and Domoticz e.g. on their Synology, but run the perl script(s) on a separate perl-friendly machine such as a spare RPi. This is possible because we can get a Domoticz on/off action to run a script on a remote machine by using ''ssh'' (explained below) with ''Public-Key Authentication''. You also only need '''one''' instance of Domoticz running, so if you are using a separate machine for the perl-scripts then it does ''not'' need to have a slave Domoticz instance installed on it. Please keep this in mind when deciding on what machine(s) to run these packages. Also note that the ''ssh'' remote-scripting option is only needed when the perl-script is remote to the Domoticz machine - it doesn't matter if LMS is remote or not.

===Setup===
First make sure perl is installed (it very likely is on a linux-based OS) and then install the 2 modules from CPAN that we need:

sudo apt-get update
sudo cpan install JSON::RPC::Client
sudo cpan install JSON::XS

Create a bash script called ''sqxfer.sh'' with the following content. Substitute the ''.../domoticz/scripts'' for the path to the directory that Domoticz accesses by default when you use the ''on/off actions'' for a switch (on a pi that would nominally be ''/home/pi/domoticz/scripts'', on Synology ''/volume1/homes/USERNAME/domoticz/scripts'')

<syntaxhighlight lang="bash">
#! /bin/sh
/usr/bin/perl .../domoticz/scripts/sqxfer.pl $1 $2 > /dev/null 2>&1 &
</syntaxhighlight>

Put it in that ''.../domoticz/scripts'' directory on whichever machine in your setup runs Domoticz and of course do a ''chmod +x'' afterwards.

If you are using the remote script option (i.e. Domoticz and perl-script on separate machines), use this version of ''sqxfer.sh'' instead (''note'': it is still installed in the .../domoticz/scripts directory on the ''local'' machine running Domoticz):

<syntaxhighlight lang="bash">
#! /bin/sh
ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy /usr/bin/perl /path/to/remote/scriptdir/sqxfer.pl $1 $2 > /dev/null 2>&1 &
</syntaxhighlight>

where 192.168.xxx.yyy is the IP address of the remote machine that the perl script will actually run on, the ''-p'' specifies the port to use for ssh on the remote machine (usually 22), ''privatekey'' is the keyfile in the local ~/.ssh directory (on the Domoticz machine) allowing ssh login to the remote machine without specifying a password, and ''/path/to/remote/scriptdir'' is the arbitrary path to the directory your perl scripts are stored in on that remote machine.

If you plan on using the remote-scripting option and you haven't already set up ''ssh'' for non-interactive login on the target/remote machine, use the command ''ssh-keygen -t rsa'' to generate the two files with public/private keys and put the ''public'' key in the ~/.ssh directory on the target/remote machine and the ''private'' key in ~/.ssh on the local machine where Domoticz is running. You will also have to do a ''chmod 700'' on the ~/.ssh directory itself and ''chmod 600'' on the key files themselves or it won't work.

Next, create a perl script called ''sqxfer.pl'' in the directory/machine pointed to by the path you just used in the bash script, with the following content (and do a ''chmod +x'' afterwards). If you are using the remote-script option, the file is placed in the /path/to/remote/scriptdir directory on the remote machine. '''Note:''' You will need to edit the parameters for player-mac's and the URL of your LMS instance after creating this script (all parameters are case-sensitive too):

<syntaxhighlight lang="perl">
#!/usr/bin/perl

use JSON::RPC::Client;
use JSON::XS;

no warnings 'uninitialized';

# Transfers a playlist from one squeezebox player ('source') to another ('target') while maintaining current song and time-position within that song.
# The volume level and repeat-mode from the source player are also transferred to the target.

# Author: philchillbill, 2018

# -----------------------------------------------------------------------------
# Edit the following parameters to suit your setup:

# The mac addresses for all the squeezebox players in your setup
%uuids = (
kitchen => '00:04:20:aa:bb:cc',
livingroom => '00:04:20:aa:bb:cc',
bathroom => '00:04:20:aa:bb:cc'
);

# The URL for the LMS server instance, usually on port 9000 or 9002
%url = (
lms => 'http://192.168.1.3:9002/jsonrpc.js'
);

# -----------------------------------------------------------------------------

($source, $target)=@ARGV;

$client=new JSON::RPC::Client;
$playerid=$uuids{$source};

# First make sure that an alert isn't by chance playing at the moment of transfer (pity to transfer that)
do {
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'path', '?'] ] });
if (!$res) { print "Source player inactive, exiting.\n" ; exit };
$jres=$res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres); $path=$$jdata{result}{_path} || 'empty';
$cnt++; $forced=($cnt==30) || 0;
} until ( ($path!~m/alerts/) || ($forced) );

# Get the source player's present state so it can be transferred, then power it off
$res = ( $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['status', '-', '1', 'tags' ] ] }) ) || 0;
if (!$res) { print "Source player inactive, exiting.\n" ; exit };
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres);
$power=$$jdata{result}{power}; if ($power==0) { print "Source player inactive, exiting.\n" ; exit };
$curvol=$$jdata{result}{'mixer volume'};
$repeat=$$jdata{result}{'playlist repeat'};
$time=$$jdata{result}{time};
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'save', "transfer", 'silent:1'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', 0 ] ] });

# now setup the target player and get it playing
$playerid=$uuids{$target};
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['power', '1'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mixer', 'volume', $curvol ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'repeat', $repeat] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'resume', "transfer", "wipePlaylist:1" ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['time', $time ] ] });

</syntaxhighlight>

Note that the temporary playlist generated from the source for restoring on the target is automatically deleted upon transfer due to the ''wipePlaylist:1'' in the code.

===Testing===
To test the script first outside Domoticz, ''cd'' to the directory where you placed the bash script and issue the following command (assuming you have players called ''kitchen'' and ''livingroom'' - change as appropriate to your setup). Make sure something is also actually playing on the ''source'' player or the script will just quietly exit.

./sqxfer.sh kitchen livingroom

The song playing on ''kitchen'' should transfer to ''livingroom'' at exactly the same moment in the same song and then power off ''kitchen'' for you. Note that the script will wait for an alert (see section 6 above) to finish playing if one accidentally commences just as you requested the transfer. If you have issues getting the remote (''ssh'') scripting working, you can first verify that the remote-login keys are working by typing

ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy

from the command line on the ''local'' machine. If it works then you will just silently receive a terminal-prompt from the remote machine (you might have to accept the remote machine as trusted the first time this is done - just go ahead and do it). If it doesn't work then check the permissions (not higher than 600 on the keyfiles!) and check that the keyfiles are in the home directory for the correct user (are you going to run Domoticz as root, pi, another user... ?). At a minimum, you should already be able to login via ssh to the remote machine using a username and password - if that's not working then this certainly won't work (e.g. check port 22 open, check that the ''ssh'' service is started).

==Sync/Unsync a Group of Players from Domoticz==

A cool feature of Squeezeboxes is their ability to play multi-room synchronised music, whereby a group of players all plays the same song at the exact same timestamp. The web UI for LMS allows assembling and disassembling groups, as does e.g. the iPeng app. However, the concept really flies when you can assemble and disassemble sync-groups at the flick of a switch.
This script can be used e.g. with Alexa/HA-Bridge or it can be linked to a bunch of Domoticz switches that setup different groups for you for different purposes. We need to first provide a ''sync'' or ''unsync'' parameter, next define a player as ''master'', and finally list the other players in the group that will become ''slaves''. If only one slave is involved, no quotes are needed around the slave-name. If multiple slaves are desired then place names in quotes and separate with commas (see example). When done, anything that happens on the master is mirrored on the slaves.

In the on-action / off-action fields of a Domoticz switch, you can use a construct along the lines of

script://sqsync.sh sync livingroom "kitchen, studio, office"
script://sqsync.sh sync livingroom bedroom
script://sqsync.sh unsync kitchen "livingroom, bedroom"

If it doesn't work for you, try specifying the full path to the bash file with a triple-slash

script:///home/pi/domoticz/scripts/sqsync.sh sync livingroom bedroom

=== Setup Considerations ===

With all the perl scripts in this LMS wiki, some modules from ''CPAN'' (Comprehensive Perl Archive Network) need to be installed. This is no problem on Linux and on Windows, but is a major problem on Synology NAS devices which have a rather stripped-down Linux under the hood with no build environment. There is a simple workaround for this using remote scripting, but let's first get something clear about where/what needs to be installed. When any one of the perl scripts here are active, 3 different pieces of software are ultimately involved:

1. LMS server software
2. Domoticz
3. Our perl script(s)

These 3 can all run on the same computer but they can also be run on 3 ''different'' computers with no problems whatsoever. Synology users can run both LMS and Domoticz e.g. on their Synology, but run the perl script(s) on a separate perl-friendly machine such as a spare RPi. This is possible because we can get a Domoticz on/off action to run a script on a remote machine by using ''ssh'' (explained below) with ''Public-Key Authentication''. You also only need '''one''' instance of Domoticz running, so if you are using a separate machine for the perl-scripts then it does ''not'' need to have a slave Domoticz instance installed on it. Please keep this in mind when deciding on what machine(s) to run these packages. Also note that the ''ssh'' remote-scripting option is only needed when the perl-script is remote to the Domoticz machine - it doesn't matter if LMS is remote or not.

===Setup===
First make sure perl is installed (it very likely is on a linux-based OS) and then install the 2 modules from CPAN that we need:

sudo apt-get update
sudo cpan install JSON::RPC::Client
sudo cpan install JSON::XS

Create a bash script called ''sqsync.sh'' with the following content. Substitute the ''.../domoticz/scripts'' for the path to the directory that Domoticz accesses by default when you use the ''on/off actions'' for a switch (on a pi that would nominally be ''/home/pi/domoticz/scripts'', on Synology ''/volume1/homes/USERNAME/domoticz/scripts'')

<syntaxhighlight lang="bash">
#! /bin/sh
/usr/bin/perl .../domoticz/scripts/sqsync.pl $1 $2 $3 > /dev/null 2>&1 &
</syntaxhighlight>

Put it in that ''.../domoticz/scripts'' directory on whichever machine in your setup runs Domoticz and of course do a ''chmod +x'' afterwards.

If you are using the remote script option (i.e. Domoticz and perl-script on separate machines), use this version of ''sqsync.sh'' instead (''note'': it is still installed in the .../domoticz/scripts directory on the ''local'' machine running Domoticz):

<syntaxhighlight lang="bash">
#! /bin/sh
ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy /usr/bin/perl /path/to/remote/scriptdir/sqsync.pl $1 $2 $3 > /dev/null 2>&1 &
</syntaxhighlight>

where 192.168.xxx.yyy is the IP address of the remote machine that the perl script will actually run on, the ''-p'' specifies the port to use for ssh on the remote machine (usually 22), ''privatekey'' is the keyfile in the local ~/.ssh directory (on the Domoticz machine) allowing ssh login to the remote machine without specifying a password, and ''/path/to/remote/scriptdir'' is the arbitrary path to the directory your perl scripts are stored in on that remote machine.

If you plan on using the remote-scripting option and you haven't already set up ''ssh'' for non-interactive login on the target/remote machine, use the command ''ssh-keygen -t rsa'' to generate the two files with public/private keys and put the ''public'' key in the ~/.ssh directory on the target/remote machine and the ''private'' key in ~/.ssh on the local machine where Domoticz is running. You will also have to do a ''chmod 700'' on the ~/.ssh directory itself and ''chmod 600'' on the key files themselves or it won't work.

Next, create a perl script called ''sqsync.pl'' in the directory/machine pointed to by the path you just used in the bash script, with the following content (and do a ''chmod +x'' afterwards). If you are using the remote-script option, the file is placed in the /path/to/remote/scriptdir directory on the remote machine. '''Note:''' You will need to edit the parameters for player-mac's and the URL of your LMS instance after creating this script (all parameters are case-sensitive too):

<syntaxhighlight lang="perl">
#!/usr/bin/perl

use JSON::RPC::Client;
use JSON::XS;
no warnings 'uninitialized';

# -----------------------------------------------------------------------------
# Syncs or unsyncs a group of Squeezebox players in one operation
# The first parameter should be either 'sync' or 'unsync'.
# Next parameter is the master player name
# Finally, a comma-separated list of slave players to join/leave the sync-group, in quotes

# Author: philchillbill, 2018

# Edit the following parameters to suit your setup:

# The mac addresses of all the squeezebox players in your setup
%uuids = (
kitchen => '00:04:20:aa:bb:cc',
livingroom => '00:04:20:aa:bb:cc',
bathroom => '00:04:20:aa:bb:cc'
);

# The URL for the LMS server instance, usually on port 9000 or 9002
%url = (
lms => 'http://192.168.1.3:9002/jsonrpc.js'
);

# -----------------------------------------------------------------------------

($action, $master, $slaves)=@ARGV;
@slaves=split(/,\s?/, $slaves);

$client=new JSON::RPC::Client;

if (lc $action eq 'sync') {
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$master}, ['power', '1' ] ] });
foreach $player (@slaves) {
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$player}, ['power', '1' ] ] });
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$master}, ['sync', $uuids{$player} ] ] });
}
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$master}, ['play'] ] });
}

if (lc $action eq 'unsync') {

foreach $player ($master, @slaves) {
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$player}, ['pause'] ] });
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$player}, ['sync', '-' ] ] });
$res = $client->call($url{lms}, { method => 'slim.request', params => [ $uuids{$player}, ['power', '0' ] ] });
}

}

</syntaxhighlight>

===Testing===
To test the script first outside Domoticz, ''cd'' to the directory where you placed the bash script and issue the following command (assuming you have players called ''livingroom'' and ''kitchen'' - change as appropriate to your setup).

./sqsync.sh sync livingroom kitchen

Both the ''livingroom'' and ''kitchen'' players should now start playing in sync, with whatever was playing before on the master (here, ''livingroom'') also playing on the slave: ''kitchen''. It does not matter if livingroom was already playing or not as it will just start playing if it wasn't. Next, try

./sqsync.sh unsync livingroom kitchen

and both players will pause, unsync and finally power-off. If you have issues getting the remote (''ssh'') scripting working, you can first verify that the remote-login keys are working by typing

ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy

from the command line on the ''local'' machine. If it works then you will just silently receive a terminal-prompt from the remote machine (you might have to accept the remote machine as trusted the first time this is done - just go ahead and do it). If it doesn't work then check the permissions (not higher than 600 on the keyfiles!) and check that the keyfiles are in the home directory for the correct user (are you going to run Domoticz as root, pi, another user... ?). At a minimum, you should already be able to login via ssh to the remote machine using a username and password - if that's not working then this certainly won't work (e.g. check port 22 open, check that the ''ssh'' service is started).

==Spoken ''Now-Playing'' using Amazon Polly TTS==

The following perl script allows your Squeezebox players to literally tell you what song is currently playing using a female English-language voice. It queries all active players in your system for their currently-playing ''artist'' and ''title'' information and sends this off to the ''Amazon Polly'' TTS (Text-to-Speech) cloud service to generate mp3 files containing each player's artist/title information in spoken form. Just as with the ''audio-alerts'' script above, the current song is temporarily paused, the TTS information mp3 is played audibly on each active player, and the player(s) then resume playing as they were before the query, with the temporary mp3 being deleted when finished. Kicking it off can be linked e.g. to a Domoticz switch event or to HA-Bridge so that you can ask Alexa to tell you what's currently playing (although Alexa won't answer - her sister Polly will answer through your Squeezebox rather than through the Echo). The following example video demonstrates the principle via a command 'Tell Me' through Alexa to HA-Bridge to a Domoticz switch:

[https://youtu.be/NxqP8lu8LnA Youtube Video showing sqnowplaying.pl in action]

Amazon reserves the utterance ''Now Playing'' for music played via Alexa herself so that's why I chose 'Tell Me' as the utterance, but you can use whatever you like that's not reserved. After you have re-created all this in your own setup, in the on-action / off-action fields of a Domoticz switch, you can use

script://sqnowplaying.sh

If it doesn't work for you, try specifying the full path to the bash file with a triple-slash, e.g.

script:///home/pi/domoticz/scripts/sqnowplaying.sh

=== Setup Considerations ===

With all the perl scripts in this LMS wiki, some modules from ''CPAN'' (Comprehensive Perl Archive Network) need to be installed. This is no problem on Linux and on Windows, but is a major problem on Synology NAS devices which have a rather stripped-down Linux under the hood with no build environment. There is a simple workaround for this using remote scripting, but let's first get something clear about where/what needs to be installed. When any one of the perl scripts here are active, 3 different pieces of software are ultimately involved:

1. LMS server software
2. Domoticz
3. Our perl script(s)

These 3 can all run on the same computer but they can also be run on 3 ''different'' computers with no problems whatsoever. Synology users can run both LMS and Domoticz e.g. on their Synology, but run the perl script(s) on a separate perl-friendly machine such as a spare RPi. This is possible because we can get a Domoticz on/off action to run a script on a remote machine by using ''ssh'' (explained below) with ''Public-Key Authentication''. You also only need '''one''' instance of Domoticz running, so if you are using a separate machine for the perl-scripts then it does ''not'' need to have a slave Domoticz instance installed on it. Please keep this in mind when deciding on what machine(s) to run these packages. Also note that the ''ssh'' remote-scripting option is only needed when the perl-script is remote to the Domoticz machine - it doesn't matter if LMS is remote or not.

===Setup===

First of all, you will need a (free) account with the AWS Amazon Polly service because you need to provide login details for the perl script (''AWS_ACCESS_KEY'' and ''AWS_SECRET_KEY''). The following ''Getting Started'' article will guide you through that process:

[https://docs.aws.amazon.com/polly/latest/dg/getting-started.html Getting started with AWS Polly]

Next, make sure perl is installed (it very likely is on a linux-based OS) and then install the 4 modules from CPAN that we need:

sudo apt-get update
sudo cpan install Parallel::Loops
sudo cpan install JSON::RPC::Client
sudo cpan install JSON::XS

Because our heavy-lifter ''Paws::Polly'' has a lot of dependencies, it's best to install it via ''cpanminus'' which you should install first if you don't have it already:

curl -L http://cpanmin.us | perl - --sudo App::cpanminus
sudo cpanm install Paws::Polly

''Warning:'' Installing Paws:Polly will take a ''long'' time (139 dependencies) so be patient and let it finish its course.

Now create a bash script called ''sqnowplaying.sh'' with the following content. Substitute the ''.../domoticz/scripts'' for the path to the directory that Domoticz accesses by default when you use the ''on/off actions'' for a switch (on a pi that would nominally be ''/home/pi/domoticz/scripts'', on Synology ''/volume1/homes/USERNAME/domoticz/scripts'')

<syntaxhighlight lang="bash">
#! /bin/sh
/usr/bin/perl .../domoticz/scripts/sqnowplaying.pl > /dev/null 2>&1 &
</syntaxhighlight>

Put it in that ''.../domoticz/scripts'' directory on whichever machine in your setup runs Domoticz and of course do a ''chmod +x'' afterwards.

If you are using the remote script option (i.e. Domoticz and perl-script on separate machines), use this version of ''sqnowplaying.sh'' instead (''note'': it is still installed in the .../domoticz/scripts directory on the ''local'' machine running Domoticz):

<syntaxhighlight lang="bash">
#! /bin/sh
ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy /usr/bin/perl /path/to/remote/scriptdir/sqnowplaying.pl > /dev/null 2>&1 &
</syntaxhighlight>

where 192.168.xxx.yyy is the IP address of the remote machine that the perl script will actually run on, the ''-p'' specifies the port to use for ssh on the remote machine (usually 22), ''privatekey'' is the keyfile in the local ~/.ssh directory (on the Domoticz machine) allowing ssh login to the remote machine without specifying a password, and ''/path/to/remote/scriptdir'' is the arbitrary path to the directory your perl scripts are stored in on that remote machine.

If you plan on using the remote-scripting option and you haven't already set up ''ssh'' for non-interactive login on the target/remote machine, use the command ''ssh-keygen -t rsa'' to generate the two files with public/private keys and put the ''public'' key in the ~/.ssh directory on the target/remote machine and the ''private'' key in ~/.ssh on the local machine where Domoticz is running. You will also have to do a ''chmod 700'' on the ~/.ssh directory itself and ''chmod 600'' on the key files themselves or it won't work.

Next, create a perl script called ''sqnowplaying.pl'' in the directory/machine pointed to by the path you just used in the bash script, with the following content (and do a ''chmod +x'' afterwards). If you are using the remote-script option, the file is placed in the /path/to/remote/scriptdir directory on the remote machine. '''Note:''' You will need to provide your AWS login credentials, edit the parameters for your player-mac's, provide the URL of your LMS instance, plus define the path to your LMS ''playlists'' directory after creating this script (all parameters are case-sensitive too):

<syntaxhighlight lang="perl">
#!/usr/bin/perl
use Parallel::Loops;
use JSON::RPC::Client;
use JSON::XS;
use Paws;
no warnings 'uninitialized';

# Uses Amazon Polly TTS to read out the nowplaying song Title and Artist on an active Squeezebox
# Author: philchillbill, 2018

# ----------------------------------------------------------------------------------------------
# Edit the following parameters to suit your setup:

$ENV{AWS_ACCESS_KEY} = 'AJKTYRE764JOKL0LSH74';
$ENV{AWS_SECRET_KEY} = 'v8tRFJzPkkj876TgYPnua90eWrEaioqnmMd88AZw';

# The mac addresses of all the squeezebox players in your setup
%uuids = (
livingroom => '00:04:20:aa:bb:cc',
kitchen=> '00:04:20:aa:bb:cc',
office => '00:04:20:aa:bb:cc'
);

# The URL for the LMS server instance, usually on port 9000 or 9002
%url = (
lms => 'http://192.168.1.3:9002/jsonrpc.js'
);

# The full path to your LMS playlists directory
%dir = (
playlists => 'file:///volume1/music/playlists'
);

# ----------------------------------------------------------------------------------------------

sub tts {
($voice, $filename, $text)=@_;
my $polly = Paws->service('Polly', region => 'eu-west-1');
my $res = $polly->SynthesizeSpeech( VoiceId => $voice, Text => $text, OutputFormat => 'mp3' );
open(MP3, '>', "$filename.mp3"); binmode(MP3); print MP3 $res->AudioStream; close(MP3);
}

sub nowplayingTTS {
$player=shift; $playerid=$uuids{$player};
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['artist', '?'] ] });
$response=$res->jsontext; $jdata=decode_json $response; $artist=$$jdata{result}{_artist};
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['title', '?'] ] });
$response=$res->jsontext; $jdata=decode_json $response; $title=$$jdata{result}{_title};
if ($title=~m/\(/) { $title=~s/\(/, (/ };
&tts('Amy', "$dir{playlists}/tts_$player", "This song is, '$title', by '$artist'");

$res = ( $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['status', '-', '1', 'tags' ] ] }) ) || 0;
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres);
$repeat=$$jdata{result}{'playlist repeat'};
$mvol=$$jdata{result}{'mixer volume'};
$time=$$jdata{result}{time};
if ($mode eq 'play') { $res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['pause'] ] }); }
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'save', "nowplaying$player", 'silent:1'] ] });

$avol=$mvol+25; if ($avol>80) { $avol=80 };
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mixer', 'volume', $avol ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'repeat', '0'] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'play', "$dir{playlists}/tts_$player.mp3"] ] });

do {
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mode', '?'] ] });
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres); $mode=$$jdata{result}{_mode};
sleep 1;
} until ($mode eq 'stop');

$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['mixer', 'volume', $mvol ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'repeat', '2' ] ] });
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['playlist', 'resume', "nowplaying$player" ] ] }); ;
$res = $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['time', $time ] ] });

unlink("$dir{playlists}/tts_$player.mp3");
}

$client = new JSON::RPC::Client;

# find out which of our players are currently active, if any
foreach $sb (keys %uuids) {
$playerid=$uuids{$sb};
$res = ( $client->call( $url{lms}, { method => 'slim.request', params => [ $playerid, ['status', '-', '1', 'tags' ] ] }) ) || 0;
if (!$res) { next }; # offline
$jres = $res->jsontext; $jdata=JSON::XS->new->allow_nonref->decode($jres);
$power=$$jdata{result}{power}; $mode=$$jdata{result}{mode};
if ( ($power==0) || ($mode ne 'play') ) { next } else { $active{$sb}=1 };
}

# play the created TTS file(s) on any active player(s), or else silently exit
$maxProcs = 6;
$pl = Parallel::Loops->new($maxProcs);
@tgt=(keys %active);

$pl->foreach (\@tgt, sub {
&nowplayingTTS($_);
});
</syntaxhighlight>

===Testing===
To test the script first outside Domoticz, ''cd'' to the directory where you placed the bash script and issue the following command. Make sure something is also actually playing on one or more of your players or the script will just quietly exit.

./sqnowplaying.sh

After a slight delay (due to going up and back to the cloud for Polly), all active players (active meaning 'powered on' and in 'play' mode) should have their current song temporarily paused, the name of the song and the artist should be called out through the relevant player at a slightly-higher volume than the music was at, and then the song(s) that were playing should finally continue where they were at before the pause.

If you have issues getting the remote (''ssh'') scripting working, you can first verify that the remote-login keys are working by typing

ssh -p 22 -i ~/.ssh/privatekey 192.168.xxx.yyy

from the command line on the ''local'' machine. If it works then you will just silently receive a terminal-prompt from the remote machine (you might have to accept the remote machine as trusted the first time this is done - just go ahead and do it). If it doesn't work then check the permissions (not higher than 600 on the keyfiles!) and check that the keyfiles are in the home directory for the correct user (are you going to run Domoticz as root, pi, another user... ?). At a minimum, you should already be able to login via ssh to the remote machine using a username and password - if that's not working then this certainly won't work (e.g. check port 22 open, check that the ''ssh'' service is started).

==Resources==
The HTML documentation for all possible JSON RPC interactions with LMS is included in every LMS install so you already have it. Browse in the UI of your LMS instance to ''Help'' down in the bottom left corner, then click on ''Technical Information'', then on ''The Logitech Media Server Command Line Interface''. The perl scripts above were built entirely on the basis of the information there. There is also plenty of information on how to interact with LMS using JSON from e.g. a web-browser or a UserAgent online. See [http://tutoriels.domotique-store.fr/content/54/95/fr/api-logitech-squeezebox-server-_-player-http.html tutoriels.domotique], for example.

If you want to read more on the subject of ''Public-Key Authentication'' and the use of ''ssh-keygen'', consult [https://www.ssh.com/ssh/keygen/ ssh-keygen] or for details on editing the ''sshd_config'' file, see [https://www.digitalocean.com/community/tutorials/how-to-use-ssh-to-connect-to-a-remote-server-in-ubuntu digitalocean]

As mentioned in the section ''Setup Considerations'' above, a big issue with trying to use the above perl scripts natively on Synology is the lack of CPAN support for installing/building the JSON::RPC::Client and JSON::XS modules (Synology uses a rather stripped Linux variant). A simple workaround (detailed above) is for LMS (and your music) to be on your Synology (with Domoticz too) and to have only the perl scripts running on a different Linux machine in the network. However, if you really want to run things on your Synology natively because you don't want the overhead/cost of an additional machine, the JSON RPC calls can be made from ''bash'' using ''curl'' without having to install anything special, although the scripts will of course need total modification. Here's an example of what the calls look like in bash:

<syntaxhighlight lang="bash">
#!/bin/bash

JSONRPC="http://192.168.1.3:9002/jsonrpc.js"
UUID="00:04:20:1a:4d:5e"

curl -i -X POST -H "Content-Type: application/json" -d '{"id":1,"method":"slim.request","params":[ "'$UUID'", ["power", "1"] ]}' $JSONRPC
curl -i -X POST -H "Content-Type: application/json" -d '{"id":1,"method":"slim.request","params":[ "'$UUID'", ["playlist", "resume", "Trance_Daylist"] ]}' $JSONRPC
</syntaxhighlight>

[[Category:Domoticz]]
[[Category:Manual]]
[[Category:Setup]]
[[Category:Software]]
[[Category:Media]]

Kodi

2019-01-13T08:37:55Z

Philchillbill: /* Kodi Settings */

Documentation for Kodi Media Player.

==Introduction==
Kodi™ (formerly known as XBMC™) is an award-winning free and open source (GPL) software media center for playing videos, music, pictures, games, and more. Kodi runs on Linux, OS X, Windows, iOS, and Android, featuring a 10-foot user interface for use with televisions and remote controls. It allows users to play and view most videos, music, podcasts, and other digital media files from local and network storage media and the internet.

For more details go to the Kodi site here - http://kodi.tv/about/

==On Screen Notifications==
Domoticz can display notification messages on screens linked to Kodi Media Players. Notifications will work even if Kodi has not been added as a hardware type and no Kodi devices have been defined.

Your Kodi media Player must be configured to allow control by remote programs. To see where to do this using the default Confluence skin see: [http://kodi.wiki/view/Settings/Services#Remote_control Allow Remote Control].

This is configured via the Notifications tab on the Settings page as shown here:

[[File:2015-09-19 Kodi.jpg|Settings]]

The default setting should work for almost everyone on a home network. 224.0.0.1 is a multicast address so the message will be sent to the whole local network. Port 9777 is a special port on Kodi Media Players to listen for these broadcasts so always try these settings first. If the messages don't appear, bump the number of 'hops' to any number less than 20.

For Kodis that still don't get messages, or are not on your local network, semicolon delimited IP addresses can be specified.

If you want to send notifications to Kodi outside of the formal Domoticz stream you can do something along the lines of this in bash:

<syntaxhighlight lang="bash">
#! /bin/bash

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"GUI.ShowNotification","params":{"title":"Domoticz","message":"Hall PIR detected motion !"},"id":1}' http://192.168.178.5:80/jsonrpc

</syntaxhighlight>

or from perl using

<syntaxhighlight lang="perl">
#!/usr/bin/perl
use LWP::UserAgent;
use Net::Ping;
no warnings 'uninitialized';

$kodi_url = '192.168.178.5';
$ua=LWP::UserAgent->new; $ua->timeout(5);

$p = Net::Ping->new();
$alive = ($p->ping($kodi_url, 2));

if ($alive) {
$title='Garage Door';
$message='Open for > 10 mins !';
$res=$ua->get("http://$kodi_url/jsonrpc?request={\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"GUI.ShowNotification\",\"params\":{\"title\":\"$title\",\"message\":\"$message\"}}");
unless ($res->is_success) { warn $res->status_line };
}
</syntaxhighlight>

==Kodi in Domoticz==

===Kodi Settings===
Your Kodi media Player must be configured to allow control by remote programs to work with Domoticz. To see where to do this using the default Confluence skin see: [http://kodi.wiki/view/Settings/Services#Remote_control Allow Remote Control].

By default Kodi exposes an asynchronous interface on port 9090 in addition to the web server it runs on 80 or 8080. If required, it can be changed by updating the underlying XML configuration, details are here [http://kodi.wiki/view/Advancedsettings.xml#.3Cjsonrpc.3E Override Default Port] but this should not be required.

Do not change any of these [http://kodi.wiki/view/Settings/Services#Webserver web server settings] in an attempt to make this plugin work. It does not use the Kodi Webserver so it will make no difference.

===Adding Hardware===
Add the Kodi Media Player via the Hardware page under Settings:

[[File:KodiHardware.jpg]]

====Domoticz Settings====

Click 'Setup' and the add individual devices.
* Poll interval controls how often Domoticz will attempt to reconnect to a Kodi that it has lost contact with.
* Ping timeout controls how many missed pings (sent once per Poll Interval) can be missed before a Kodi is consider 'Off'. For backwards compatibility, if the number specified is greater than 1000 it will be divided by 1000. Recommended value is 2 or 3.
The port specified needs to match the port confingured on the Kodi itself, see below for detail

[[File:KodiDetail.jpg]]

Unless you have explicitly made port changes to your Kodi as described below, just use the default 9090 port number. Once you have saved your changes check the log and you should see something similar to this:

{| class="wikitable"
|- style="font-style: italic; font-size:80%;"
|2015-09-25 09:44:44.962 Kodi: (Lounge) Connected.
|}

Note that this message will be shown if Domoticz attaches to any valid port! To check it is functioning correctly, play some media as you normally would and you should see somthing similar to this if you play then stop some music:

{| class="wikitable"
|- style="font-style: italic; font-size:80%;"
|2015-09-25 10:01:11.699 Kodi: (Lounge) Event: 'Audio - Coldplay (A Rush Of Blood To The Head), The Scientist (2002)'.
|- style="font-style: italic; font-size:80%;"
|2015-09-25 10:01:18.483 Kodi: (Lounge) Event: 'On'.
|}

if you see the connection message but no activity you have connected to the wrong port.

If you want to use custom Kodi icons there is a set here: [https://www.domoticz.com/forum/download/file.php?id=4243 Custom Icons]. Just upload them via the Custom Icon page under settings then Edit the devices from the 'Switches' tab select the icons from the list.

===Troubleshooting===
If you are having issues, go back to the device set up page (under Hardware) and make the port number negative for your kodi, this will turn on debug mode for the device. e.g if using the default port 9090, make the port -9090 and your log will be spammed with messages.

Connection to the correct port will show results similar to:

{| class="wikitable"
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:03:02.429 Kodi: (Lounge) Connected to '192.168.37.127:-9090'.
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:03:02.430 Kodi: (Lounge) Sending data: '{"jsonrpc":"2.0","method":"System.GetProperties","params":{"properties":["canhibernate","cansuspend","canshutdown"]},"id":7}'
|- style="font-style: italic; font-size:80%; font-weight:bold;"
|2015-10-03 13:03:02.565 Kodi: (Lounge) Parsing data: '{"id":7,"jsonrpc":"2.0","result":{"canhibernate":false,"canshutdown":false,"cansuspend":false}}'.
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:03:02.567 Kodi: (Lounge) Sending data: '{"jsonrpc":"2.0","method":"Player.GetActivePlayers","id":5}'
|- style="font-style: italic; font-size:80%; font-weight:bold;"
|2015-10-03 13:03:02.570 Kodi: (Lounge) Parsing data: '{"id":5,"jsonrpc":"2.0","result":[]}'.
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:03:03.459 Kodi: (Lounge) Sending data: '{"jsonrpc":"2.0","method":"JSONRPC.Ping","id":1}'
|- style="font-style: italic; font-size:80%; font-weight:bold;"
|2015-10-03 13:03:03.463 Kodi: (Lounge) Parsing data: '{"id":1,"jsonrpc":"2.0","result":"pong"}'.
|}

Connecting to an incorrect (but active) port will show:

{| class="wikitable"
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:07:10.882 Kodi: (Lounge) Connected to '192.168.0.246:-8080'.
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:07:10.883 Kodi: (Lounge) Sending data: '{"jsonrpc":"2.0","method":"System.GetProperties","params":{"properties":["canhibernate","cansuspend","canshutdown"]},"id":7}'
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:07:11.919 Kodi: (Lounge) Sending data: '{"jsonrpc":"2.0","method":"JSONRPC.Ping","id":1}'
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:07:22.420 Kodi: (Lounge) Sending data: '{"jsonrpc":"2.0","method":"JSONRPC.Ping","id":1}'
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:07:32.920 Kodi: (Lounge) Missed 1 pings, assumed off.
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:07:32.956 Kodi: (Lounge) Event: 'Off'.
|- style="font-style: italic; font-size:80%;"
|2015-10-03 13:07:32.985 Kodi: (Lounge) Disonnected.
|}

Always post this log output into forum requests for assistance.

===Events and Notifications===
Domoticz device events work for Kodi using both Blockly and lua.

Events and notifications are triggered for:
{| class="wikitable"
|-
|On
|When the device is turned on (network connection established) or returns to an idle state.
|-
|Off
|When the device is turned off or network connectivity is lost.
|-
|Video
|When the device starts streaming Live TV, TV Shows or Movies.
|-
|Audio
|When the device starts streaming Music.
|-
|Photo
|When the device starts showing an image.
|-
|Pause
|When the device is streaming media and is paused.
|}

The following actions can be performed by using 'Set' on a Kodi.

{| class="wikitable"
|-
|Off or Group Off
|Will turn the device off if this is supported in settings on the device.
|-
|Stop
|Will send a Stop command, only effective if the device is streaming.
|-
|Play
|Will send a Play command, only effective if the device was streaming and has been paused.
|-
|Pause
|Will send a Pause command, only effective if the device is streaming.
|-
|Set Volume ''<0-100>''
|Will set the volume of the player-output.
|-
|Play Playlist ''<name>'' ''<position>''
|Will play a music or video [http://kodi.wiki/view/Smart_playlists Smart Playlist] with name ''<name>'' optionally starting at position ''<position>''. Playlist positions start from 0 which is the default.
|-
|Play Favorites ''<position>''
|Will play an item from the Kodi's Favorites list optionally starting at position ''<position>''. Favorite positions start from 0 which is the default.
|-
|Execute ''<addonid>''
|Will send an Execute Addon command sending no parameters. Addon IDs are embedded in the addon configuration and are not to be confused with the Addon Name. For example: http://forums.homeseer.com/showthread.php?p=1213403
|}

Lua example: 
<syntaxhighlight lang="lua">
commandArray['Lounge']='Off'
commandArray['Lounge']='Off AFTER 30'
commandArray['Lounge']='Pause'
commandArray['Lounge']='Set Volume 30'
commandArray['Lounge']='Play Playlist Indierock'
commandArray['Lounge']='Play Playlist ActionMovies 15'
commandArray['Lounge']='Play Favorites'
commandArray['Lounge']='Play Favorites 3'
commandArray['Lounge']='Execute script.securitycam'
</syntaxhighlight>

== JSON ==

Kodi has support for [http://kodi.wiki/view/JSON-RPC_API JSON]

This can be used in many fun things, for example my television can not do audio passthrough but my receiver can. So detecting that using a [[CEC]] script, or an alive ping on both devices (red. reference here) and [http://forum.kodi.tv/showthread.php?tid=192491 setting the audio passthrough in Kodi]. Makes that switching inputs from my receiver to my TV also enables audio (instead of silence)!

== Philips HUE (No Longer Maintained) ==

Kodi has [[Philips_Hue_Lights | Philips HUE]] support

The latest version can be downloaded at this location [https://github.com/michaelrcarroll/script.kodi.hue.ambilight], remember to exclude that lamp from your scences (like group all off).

== CEC ==
[[:Category:CEC | CEC]] can be used to switch your input, set your volume or even get your TV out of standby.
Kodi has a build in support for CEC with more infomation in [[:Category:CEC | CEC]] and the [http://kodi.wiki/view/CEC Kodi Wiki]

==OpenElec/LibreElec==
Remote control is disabled by default (for security reasons) so Domoticz won't be able to connect until it is enabled in Control Settings on the Kodi : 
[[File:Kodi_remote_control_setting.PNG]]
 
On OpenElec or LibreElec, you '''MAY''' need to add a few lines to your advanced settings xml file...try it first and only do this if it does not work 
If you dont know how to do that, check this out : http://kodi.wiki/view/advancedsettings.xml 
 
Once you have your head around that, you need to add these lines : 
<syntaxhighlight lang="bash">
<jsonrpc>
<tcpport>9090</tcpport>
</jsonrpc>
</syntaxhighlight>
[[Category:Domoticz]]
[[Category:Manual]]
[[Category:Setup]]
[[Category:Software]]
[[Category:Media]]
[[Category:CEC]]
[[Category:Scripting‏‎]]
[[Category:JSON]]

Sonoff - failsafe switching

2018-11-27T17:59:15Z

Philchillbill:

==Failsafe switching of Sonoff relay devices==

If you have flashed a Sonoff relay device with ESPeasy, you can have Domoticz turn the device on/off from a dummy switch using a http:// call to the relevant URL in the action field. For example, for a device at octet 27
http://192.168.1.27/control?cmd=gpio,12,1
turns the relay on, while ?cmd=gpio,12,0 turns it off again. In the real world, you will regularly encounter missed packets with this approach (it's as if the Sonoffs aren't always listening). When this happens, Domoticz and the Sonoff are out of sync - you think/hope you've switched something on or off but in fact there was no response from the Sonoff and Domoticz is none the wiser.

One way around this is to use script:// instead of http:// in the dummy-switch action field and have an external script send the http:// command to the Sonoff, poll the Sonoff to ensure that the relay has actually switched, and resend the http:// if needed (repeatedly) in case a discrepancy is found. To check the current state of a Sonoff, we can use
http://192.168.1.27/json?view=sensorupdate&tasknr=1
and we will then see something along the lines of:

{
"TaskValues": [
{"ValueNumber":1,
"Name":"state",
"NrDecimals":0,
"Value":1
}],
"TTL":60000,
"TaskEnabled":"true",
"TaskNumber":1
}

with the Mega version of ESPeasy, or with e.g. version 120 we get simpler JSON:

{
"TaskName": "relay",
"state": 0.00
}

Our script can check for either format automatically. The ''TaskName'' of 'relay' has a ''state'' of 0.00, indicating the relay is currently off - the state is 1.00 if it's on. Our script uses this approach to verify that the Sonoff received a command and will keep resending until the state changes as required. With our script installed, in the on-action / off-action fields of a Domoticz switch, you can use a construct along the lines of

script://sonoffs.sh 27 12 0
script://sonoffs.sh 148 12 1

where the 27 or 148 (say) are the least-significant octet of the IP address of the Sonoff, the 12 is the gpio number to switch, and 0 or 1 is the required state.

=== Setup ===

Our script is written in perl but when using it with Domoticz we will call it from a pre-processor script written in bash. The reason for this is that the perl script has a deliberate (short) sleep-delay built-in before it retries a failed command. As Domoticz waits for scripts to finish before continuing its own execution, this delay would hold up Domoticz and we don't want that. The bash wrapper-script kicks off execution of the perl script and passes along our command-line parameters, but suppresses output from the perl and - most importantly - makes it run as a separate process (thanks to the final '&') so that control immediately returns to Domoticz. Perfect.

Create a bash script called ''sonoffs.sh'' with the following content, and put it in your ''/home/pi/domoticz/scripts'' directory (and of course, do a ''chmod +x'').

<syntaxhighlight lang="bash">
#! /bin/sh
/usr/bin/perl /home/pi/domoticz/scripts/sonoffs.pl $1 $2 $3 > /dev/null 2>&1 &
</syntaxhighlight>

Make sure perl is installed (it very likely is on a linux-based OS) and then install the modules from CPAN that we need:

sudo apt-get update
sudo cpan install JSON::XS
sudo cpan install LWP::UserAgent
sudo cpan install URI::Escape

Now create a perl script called ''sonoffs.pl'' with the following content, and put it in your ''/home/pi/domoticz/scripts'' directory (and of course, do a ''chmod +x''). You will need to edit the $domoticz and $baseUrl variables to match your particular setup.

<syntaxhighlight lang="perl">
#!/usr/bin/perl
use JSON::XS;
use LWP::UserAgent;
use URI::Escape;

no warnings 'uninitialized';

# Switches a Sonoff device on/off on behalf of Domoticz and then checks that it actually switched accordingly (in case of packet-loss)
# Autor: philchillbill, 2018

($octet, $gpio, $value)=@ARGV;
$tries=0;

$domoticz='http://192.168.1.12:8080'; # full URL of your Domoticz instance
$baseUrl='http://192.168.1.'; # The most significant 3 octets of your local area IP addresses for the Sonoffs

sub postDomoticzLog {
my $msg=shift;
$message=uri_escape($msg);
$msg_url=$domoticz.'/json.htm?type=command&param=addlogmessage&message='.$message;
$ua=LWP::UserAgent->new; $ua->timeout(5); $res=$ua->put($msg_url);
unless ($res->is_success) { warn "oops... ", $res->status_line };
}

$ua=LWP::UserAgent->new; $ua->timeout(1); $ua->env_proxy;

# first check we are not clashing with another process handling the same Sonoff device
while ( -e "/tmp/.busy.$octet" ) {
$secs++; sleep 1; $waited=1;
if ($secs==30) {
unlink ("/tmp/.busy.$octet") or die $!;
&postDomoticzLog("Early exit of lockfile-wait loop with Sonoff '$octet'");
last;
}
}
if ($waited) { print "Waited for other process...\n"; sleep 5 };

# now place our own lockfile to hold off other processes
open(TMP, '>', "/tmp/.busy.$octet") or die $!;

do {
# First send the command to the Sonoff
$url=$baseUrl.$octet."/control?cmd=gpio,".$gpio.",".$value; # e.g. http://192.168.178.27/control?cmd=gpio,12,0
$c=0;
do { $c++;
$response=$ua->get($url);
} until ( ($response->is_success) || ($c==5) );

# Now check if it reacted, using the /json endpoint
$url=$baseUrl.$octet."/json?view=sensorupdate&tasknr=1";
$d=0;
do {
sleep 1; $d++;
$response=$ua->get($url);
} until ( ($response->is_success) || ($d==10) );

if ($response->is_success) {
$tasks=$response->decoded_content; $data=decode_json $tasks;
if (exists $$data{state}) { $state=$$data{state} } else { $state=$$data{TaskValues}[0]{Value} }; # Both espeasy R120 / Mega JSON formats
}
else { &postDomoticzLog("No response from Sonoff '$octet'"); exit 0 };

$ok=( ($value eq '0') && ($state==0) ) || ( ($value eq '1') && ($state==1) ); $tries++;

} until ( ($ok) || ($tries==5) );

if ( -e "/tmp/.busy.$octet" ) { unlink ("/tmp/.busy.$octet") or die $!};

if (!$ok) { &postDomoticzLog("Error setting Sonoff '$octet' to state '$value'") };

print "c: $c, d: $d, tries: $tries\n";

exit 0;
</syntaxhighlight>

That's it. You can debug things if necessary by running the perl script directly from the linux command line: e.g. ''./sonoffs.pl 27 12 1'' and seeing if any error messages are thrown. Also, if the bash script won't run from Domoticz, try specifying the full path to the bash file with a triple-slash:
script:///home/pi/domoticz/scripts/sonoffs.sh 27 12 0

File:Screenshotjsondebug.png

2018-08-05T11:26:27Z

Philchillbill: Screenshot of JSON debugging in Domoticz using the developer tools of the browser

Screenshot of JSON debugging in Domoticz using the developer tools of the browser

Trigger perl

2017-07-24T18:55:33Z

Philchillbill: /* Purpose */

=Purpose=
This script will trigger a perl script every 1 minute as an alternative to running a cronjob. Make sure your perl script starts with a correct shebang line such as #!/usr/bin/perl

=Dependencies - hardware / software / operating system=
This script will work on all type of hardware / software / operating system.

It could be used to trigger any perl script such as:
* [[Domoticz_Pings_any_IP_in_LAN,_and_switching_a_device,_using_Perl | ping_by_ip.pl ]]
* Any other perl script

=Domoticz Setup - switches, variables, version=
* Replace ping_by_ip.pl by the name of your perl script
* Make sure ping_by_ip.pl is located in : /usr/bin/ping_by_ip.pl
* Make sure ping_by_ip.pl is executable : sudo chmod +x ping_by_ip.pl

=Installation instructions=
Copy this script to your '''domoticz\scripts\lua\''' folder.

=Script with comments=
-- Script name : script_time_ping.lua
-- This script will trigger a perl script every 1 minute
-- Replace ping_by_ip.pl by the name of your perl script
-- Make sure ping_by_ip.pl is located in : /usr/bin/ping_by_ip.pl
-- Make sure ping_by_ip.pl is executable : sudo chmod +x ping_by_ip.pl

commandArray = {}

ping_success=os.execute('ping_by_ip.pl')

if ping_success then
print("ping success")
else
print("ping fail")
end

return commandArray

=Example of use (if relevant) i.e. output files / screen displays=
N/A

[[Category:Domoticz]]
[[Category:Manual]]
[[Category:Setup]]
[[Category:Scripting]]
[[Category:Perl]]

Doorbel a virtual Switch

2017-07-24T18:45:40Z

Philchillbill: /* Your doorbell as switch in Domoticz. */

=Your doorbell as switch in Domoticz.=

First you need to connect your 12 AV relays in parallel with your doorbell.

When your doorbell button is pressed, the contact of your relays will connect GPIO18 to ground.

Now install the software

<pre>
sudo apt-get install python-dev python-pip
sudo install --upgrade distribute
sudo install ipython
sudo install --upgrade RPi.GPIO
</pre>

This is the python script I made

<syntaxhighlight lang="python">
# Doorbell py with read contact uitlezen,
# GPIO 18 to Ground when button is pushed
# Release 0.1/
# Author J. Jeurissen
# Copyright (c) 2015 J. Jeurissen
# Python 3

import urllib
import urllib.request
import json
import RPi.GPIO as GPIO
import time

# Settings for the domoticz server
domoticzserver="ipadres:8080"
domoticzusername = ""
domoticzpassword = ""

domoticzurl = 'http://'+domoticzserver+'/json.htm?type=command&param=switchlight&idx=170&switchcmd=On'

GPIO.setmode(GPIO.BCM)

GPIO.setup(18, GPIO.IN, pull_up_down=GPIO.PUD_UP)

while True:
input_state = GPIO.input(18)
if input_state == False:
print('Button Pressed')
time.sleep(5.0)

</syntaxhighlight>

Add in crontab the following line
so your python script is always running
<pre>
@reboot python3 /path/doorbel.py
</pre>
[[Category:Python]]
[[Category:ToBeFormatted]]