Web Services

Control and configuration of a Loxone system is possible through simple HTTP commands

EASY COMMUNICATION

With Web Services and simple HTTP commands, you can retrieve information, and create or modify settings using Loxone’s Miniserver.

CONTENTS

GENERAL

  • Structure of Web Services

STATUS & CONTROL

  • Query: Status of a control
  • Push-button
  • Query: All output changes

CONFIGURATION & STATISTICS

  • PLC Commands
  • Configuration Commands
  • Statistics Commands

GENERAL

THE STRUCTURE OF WEB SERVICES

(Using RESTful Web Services technology)

http://User:[email protected]/command/control/value

  • control: can be any input or output, real or virtual. Outputs can only be used for status requests.
  • value: when ‘value’ is not available, the current control value is returned. The following values ??allowed: ‘A’, ‘On’, ‘off’, ‘Off’, ‘Impulse’, ‘Pulse’ or a decimal value (<1).
  • Virtual digital inputs with 2 outputs (up-down, left-right, starting from version 1.5.4.16), the following values are allowed.
ImpulsPlus
ImpulsMinus
PulseUp
PulseDown
ImpulsAuf
ImpulsAb
PulseOpen
PulseClose
PlusEin
PlusAus
UpOn
UpOff
AufEin
AufAus
OpenOn
OpenOff
MinusEin
MinusAus
DownOn
DownOff
AbEin
AbAus
CloseOff
CloseOff
  • ‘On’ = 1 and ‘Off’ = 0 for digital inputs and outputs.
  • Analogue (0-10V) inputs operate in a range between 0 and 10.00. There is no formal limit (for example EIB temperatures of 21.5 or -5.2).
  • A dot is used for the decimal output.

Example – Pulse Input

Before sending a pulse into the system, your Miniserver needs a Virtual Input that will accept the command.

EN_KB_Config_Virtual_Input_Test

Now once we have our Virtual Input added and saved into the Miniserver, the command will need to be sent. Below is an example of a 3rd party application* sending a pulse command into the Loxone Miniserver:

EN_KB_Computer_Postman_HTT_Command

In this example we have the default credentials (username: admin, password: admin) and the virtual input in the command which has the name ‘Test Input’. By pressing the ‘Send’ button in the application, the string will use the IP address to find the Miniserver on the network, login and then process the command.

If the send command is accepted, the returned response in an XML format will be:

EN_KB_Computer_Postman_HTT_Command_XML_Response

Code “200” means the command was accepted and processed.

You will also see in Loxone Config the Virtual Input light up for a split second if ‘Live View’ is active: EN_KB_Config_Virtual_Input_On

*In these examples, Postman is the 3rd party app being used to send the commands.

STATUS & CONTROL

QUERY: STATUS OF A CONTROL

Command http://miniserver/dev/sps/io/LivingroomLight/state
Function Returns the status at the input
Answer <LL control=”dev/sps/io/LivingroomLight” value=”0″ Code=”200″/>
Command http://miniserver/dev/sps/io/LivingroomLight/astate
Function Returns the value at the requested outputs (either a unique value for all – or a ? for different values.
Answer <LL control=”dev/sps/io/LivingroomLight” value=”1″ Code=”200″/>
Command http://miniserver/dev/sps/io/LivingroomLight/all
Function Returns the number of requested outputs and a list of the values at those outputs
Answer <LL control=”dev/sps/io/LivingroomLight/all” value=”8″ Code=”200″
n1=”Aktor (Relais) Q1″ u1=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v1=”0″
n2=”Aktor (Relais) Q2″ u2=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v2=”0″
n3=”Aktor (Relais) Q3″ u3=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v3=”0″
n4=”Aktor (Relais) Q4″ u4=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v4=”0″
n5=”Aktor (Relais) Q5″ u5=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v5=”0″
n6=”Aktor (Relais) Q6″ u6=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v6=”1″
n7=”Aktor (Relais) Q7″ u7=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v7=”0″
n8=”Aktor (Relais) Q8″ u8=”68347a0e-3bfc-11df-85f6ea34eeb9b08a” v8=”0″/>
Command http://miniserver/status
Function Lists all the devices that are connected to the Miniserver, along with status
Antwort <Status Modified=” “>
<Miniserver Name=”LoxMiniserver” Internalname=” ” IP=” ” Mask=” ” Gateway=” ” DHCP=” ” DNS1=” ” DNS2=” ” MAC=” ” Device=” ” Version=” “><Extension Name=” ” Internalname=” ” Serial=” ” Version=” ” Online=” “/></Miniserver></Status>

Icon Exclamation Mark LoxoneStatus requests via web service are only possible with inputs and outputs and are not possible with function blocks.

PUSH BUTTON

Command http://miniserver/dev/sps/io/PushbuttonLivingRoomLight/On
Function Control the analogue or digital input
Answer <LL control=”dev/sps/io/PushbuttonLivingRoomLight” value=”1″ Code=”200″/>

Example – Push Button

Before sending a command into the system, your Miniserver needs a Push Button function block that will accept the command.

EN_KB_Config_Push_Button

Now once we have our Push Button added and saved into the Miniserver, the command will need to be sent. Below is an example of a 3rd party application* sending an ‘On’ command into the Loxone Miniserver:

EN_KB_Computer_Postman_HTTP_Command

In this example we have the default credentials (username: admin, password: admin) and the Push Button in the command which has the name ‘Push-Button’. By pressing the ‘Send’ button in the application, the string will use the IP address to find the Miniserver on the network, login and then process the command. We can change the last part of the command to be ‘On’ or ‘Off’, depending on different situations.

If the send command is accepted, the returned response in an XML format will be:

EN_KB_Computer_Postman_HTT_Command_XML_Response

Code “200” means the command was accepted and processed.

You will also see in the Loxone Interface the Push Button will change state depending on which command is sent (on/off).

EN_KB_UI_Push_Button

*In these examples, Postman is the 3rd party app being used to send the commands.

QUERY: ALL OUTPUT CHANGES

Command http://miniserver/dev/sps/changes
Function Sends all the outputs that have changed since the last request
Answer <LL control=”dev/sps/changes” value=”5″ Code=”200″
n1=”Aktor (Relais) Q1″ u1=”68347a0e-3bfc-11df-8604ea34eeb9b08a” v1=”0″
n2=”Aktor (Relais) Q2″ u2=”68347a0e-3bfc-11df-8605ea34eeb9b08a” v2=”0″
n3=”Aktor (Relais) Q3″ u3=”68347a0e-3bfc-11df-8606ea34eeb9b08a” v3=”0″
n4=”Aktor (Relais) Q4″ u4=”68347a0e-3bfc-11df-8607ea34eeb9b08a” v4=”0″
n5=”Aktor (Relais) Q5″ u5=”68347a0e-3bfc-11df-8608ea34eeb9b08a” v5=”1″/>
Command http://miniserver/dev/sps/event
Function Generates an Eventserver in the Webserver. An Eventhandler must be programed in the Webclient (e.g., new EventSource (http://miniserver/dev/sps/event)).
Answer Sends all the outputs that have changed without a renewed request to send.
http://www.w3.org/TR/eventsource/
Event: changed
data: Name
data: uuid
data: Wert
Command http://miniserver/dev/sps/enablestatusupdate
Function Enables automatic sending of status changes in WebSocket.
Answer Sends the current status via WebSocket

CONFIGURATION AND STATISTICS

PLC COMMANDS

Command Function
http://miniserver/dev/sps/state PLC status query
0 – No status
1 – PLC booting
2 – PLC program is loaded
3 – PLC has started
4 – Loxone Link has started
5 – PLC running
6 – PLC change
7 – PLC error
8 – Update is occuring
http://miniserver/dev/sps/status Current PLC frequency
http://miniserver/dev/sps/restart PLC restart
http://miniserver/dev/sps/stop PLC stop
http://miniserver/dev/sps/run PLC continue
http://miniserver/dev/sps/log PLC permit global logging
http://miniserver/dev/sps/nolog PLC disable global logging
http://miniserver/dev/sps/enumdev List all PLC devices (Miniserver, extensions)
http://miniserver/dev/sps/enumin List all PLC inputs
http://miniserver/dev/sps/enumout List all PLC outputs
http://miniserver/dev/sps/identify Identify Miniserver (version 1.5.6.7 and higher)
For extensions, the serial number must given as a parameter

CONFIGURATION COMMANDS

Command Function
http://miniserver/dev/cfg/mac Retrieve MAC address
http://miniserver/dev/cfg/version Holt firmware version
http://miniserver/dev/cfg/versiondate Holt firmware production date
http://miniserver/dev/cfg/dhcp Retrieve or set DHCP configuration
http://miniserver/dev/cfg/ip Retrieve or set IP address
http://miniserver/dev/cfg/mask Retrieve or set IP mask
http://miniserver/dev/cfg/gateway Retrieve or set Gateway address
http://miniserver/dev/cfg/device Retrieve or set Miniserver device name
http://miniserver/dev/cfg/dns1 Retrieve or set DNS address 1
http://miniserver/dev/cfg/dns2 Retrieve or set DNS address 2
http://miniserver/dev/cfg/ntp Retrieve or set NTP address
http://miniserver/dev/cfg/timezoneoffset Retrieve or set time zone offset
http://miniserver/dev/cfg/http Retrieve or set HTTP port
http://miniserver/dev/cfg/ftp Retrieve or set FTP port
http://miniserver/dev/cfg/LoxPLAN Retrieve or set configuration software port
http://miniserver/dev/cfg/ftllocalonly Retrieve or set ‘FTP, Telnet, local software access only’

SYSTEM COMMANDS

Command Function
http://miniserver/dev/lan/txp Retrieve number of LAN packets sent
http://miniserver/dev/lan/txe Retrieve number of LAN packets sent with errors
http://miniserver/dev/lan/txc Retrieve number of LAN packets sent with collisions
http://miniserver/dev/lan/exh Retrieve number of LAN buffer errors
http://miniserver/dev/lan/txu Retrieve number of LAN under-run errors
http://miniserver/dev/lan/rxp Retrieve number of LAN packets recieved
http://miniserver/dev/lan/eof Retrieve number of LAN EOF errors
http://miniserver/dev/lan/rxo Retrieve number of LAN receive overflow errors
http://miniserver/dev/lan/nob Retrieve number of LAN ‘No receive buffer’ errors
http://miniserver/dev/bus/packetssent Retrieve number of Packets sent to CAN-bus
http://miniserver/dev/bus/packetsreceived Retrieve number of packets received on CAN-bus
http://miniserver/dev/bus/receiveerrors Retrieve number of receive errors on CAN-bus
http://miniserver/dev/bus/frameerrors Retrieve number of frame errors on CAN-bus
http://miniserver/dev/bus/overruns Retrieve number of overflow errors on CAN-bus
http://miniserver/dev/bus/parityerrors Retrieve number of parity errors on CAN-bus
http://miniserver/dev/sys/numtasks Retrieve number of tasks
http://miniserver/dev/sys/cpu Retrieve CPU load
http://miniserver/dev/sys/contextswitches Retrieve number of switchings between tasks
http://miniserver/dev/sys/contextswitchesi Retrieve number of switchings between tasks that were triggered interrupts
http://miniserver/dev/sys/heap Retrieve memory size
http://miniserver/dev/sys/ints Retrieve number of system interrupts
http://miniserver/dev/sys/comints Retrieve number of communication interrupts
http://miniserver/dev/sys/lanints Retrieve number of LAN interrupts
http://miniserver/dev/sys/watchdog Retrieve watchdog bits
http://miniserver/dev/sys/date Returns the local date
http://miniserver/dev/sys/time Returns the local time
http://miniserver/dev/sys/setdatetime Set system date and time. Format: 2013-06-18 16:58:00 or 18/06/2013 16:58:00
http://miniserver/dev/sys/spscycle Retrieve number of PLC cycles
http://miniserver/dev/sys/ntp Force NTP request
http://miniserver/dev/task0/name Retrieve task 0 name (0-http://nubuserver/dev/sys/numtasks – 1)
http://miniserver/dev/task0/priority Retrieve task 0 priority
http://miniserver/dev/task0/stack Retrieve task 0 stack
http://miniserver/dev/task0/contextswitches Retrieve number of task 0 switchings
http://miniserver/dev/task0/waittimeout Retrieve task 0 wait time in ms
http://miniserver/dev/task0/state Retrieve task 0 status
http://miniserver/dev/sys/reboot Reboot Miniserver
http://10.44.44.48/dev/sys/wsextension/1310520C/Reboot Reboots the specified extension. Value will read “timeout” whilst the extension reboots.
http://miniserver/dev/sys/check Displays active connections in Loxone Config
http://miniserver/dev/sys/logoff Ends any existing connections in Loxone Config
http://miniserver/dev/sys/sdtest Tests the SD card
http://miniserver/dev/sys/lastcpu Shows the last value of the CPU utilisation and the number of PLC cycles
http://miniserver/dev/sys/search Performs a search for connected extensions
http://miniserver/dev/sys/searchdata Lists the search results
http://miniserver/dev/fslist/ Lists the root directory of the SD card
http://miniserver/dev/fslist/path/ Lists the directory path on the SD card
http://miniserver/dev/fsget/filepath/ Retrieves a file (replace filepath with the file name)
http://miniserver/dev/fsdel/filepath/ Deletes a file (replace filepath with the file name)
http://miniserver/data/status Shows the status of the Miniserver and all connected extensions
http://miniserver/stats Shows the statistics
http://miniserver/data/LoxAPP2.xml Structure file for the visualisation
http://miniserver/dev/fsget/log/def.log Retrieve the log
http://miniserver/dev/sys/ExtStatistics/05000001 Retrieve the statistics of a 1-Wire Extension (replace 05000001 with the actual serial number)
http://miniserver/dev/sys/AirStatistics
/0C000001/DeviceIndex
Retrieve the statistics of an Air Base Extension (replace 0C000001 with the actual serial number)
http://miniserver/dev/sys/updateext Start an update of extensions