Difference between revisions of "OWN OpenWebNet Language Reference"

From piMyHome Project
Jump to navigation Jump to search
 
(54 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
The [http://en.wikipedia.org/wiki/OpenWebNet OpenWebNet protocol] was defined in 2000 by [http://www.myopen-legrandgroup.com Bticino/Legrand] to specify the communication with a Bticino domotic gateway, connected via LAN, RS-232 (serial) or USB.
+
The [http://en.wikipedia.org/wiki/OpenWebNet OpenWebNet protocol] was defined in 2000 by [http://www.myopen-legrandgroup.com Bticino/Legrand] to specify the communication with a Bticino home automation gateway, connected via LAN, RS-232 (serial) or USB. Here you'll get a brief overview of the OWN language syntax. To watch the OWN messages of your Bticino gateway, you should try the [[Code_Snippets#A_Python_Monitor_Session_with_Bticino_Gateway|Python Monitor]] in our [[Code Snippets]] section.
 +
 
 +
----
 +
 
  
 
== Basic Syntax Rules ==
 
== Basic Syntax Rules ==
−
A Bticino gateway receives and sends '''''OPEN messages''''':
+
A Bticino gateway sends and receives '''''messages'''''.
−
* A message is a simple string, containing the characters asterisk ('''*'''), hash ('''#''') and numbers from '''0 to 9'''.
+
* a message begins with an asterisk ('''*''') and is terminated with a double hash ('''##''').  
−
* each message begins with an asterisk ('''*''') and ends with a double hash ('''##''').
+
* each message contains fields separated by an asterisk ('''*''').
−
* within the message, fields are separated by an asterisk ('''*''').
+
* a field can contain dimensions and values separated by an asterisk ('''*''') and/or a hash ('''#''')
  
−
Example: <code>'''*field1*field2*field3*...fieldN##'''</code>
+
Example: <code>'''*field1*field2#dim1#value1*field3...fieldN##'''</code>
  
−
The following table shows the allowed syntax:
+
====The OWN message syntax====
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 34: Line 37:
 
|Dimension Request
 
|Dimension Request
 
|<tt>*#WHO*WHERE*DIMENSION##</tt>
 
|<tt>*#WHO*WHERE*DIMENSION##</tt>
−
|Request a dimension
+
|Request dimension value
 
|-
 
|-
 
|Dimension Write
 
|Dimension Write
 
|<tt>*#WHO*WHERE*#DIMENSION*VAL1*VAL2*...*VALn##</tt>
 
|<tt>*#WHO*WHERE*#DIMENSION*VAL1*VAL2*...*VALn##</tt>
−
|Write a dimension
+
|Write dimension value(s)
 
|}
 
|}
  
−
== Standard Message ==
+
We know already that a standard message consists of <code>''' *WHO*WHAT*WHERE##'''</code>.
−
In the table above, we learned a Standard Message consists of <code>''' *WHO*WHAT*WHERE## ''' </code>.
+
* <tt>'''WHO'''</tt> identifies the service, such as scenario, light or automation. See WHO table below.
−
* <tt>'''WHO'''</tt> identifies the service, such as scenario, light or automation
 
 
* <tt>'''WHAT'''</tt> is the action to be performed, such as light ON/OFF or dimmer, shutter up/down etc.
 
* <tt>'''WHAT'''</tt> is the action to be performed, such as light ON/OFF or dimmer, shutter up/down etc.
−
* <tt>'''WHERE'''</tt> identifies the object, which can be an area, group, an environment, or just a single light or shutter etc. A <tt>'''WHERE'''</tt> field can also come with optional parameters, separated by a hash ('''#'''), e.g. <tt>'''*WHERE#PAR1#PAR2#...#PARn'''</tt>
+
* <tt>'''WHERE'''</tt> identifies the object, which can be an area, group, an environment, or just a single light or shutter etc. Check out the WHERE table below.
 +
* <tt>'''##'''</tt> terminates a message. Larger facilities might have extension interfaces. Addresses connected to on one of these extension interfaces have the prefix '''<tt>"#4#nn</tt>''', where '''<tt>nn</tt>''' reflects the 2-digit value of the extension interface number.  So a message with an address on interface 7 is terminated with a '''<tt>"#4#07##</tt>'''.
  
−
== Some Examples ==
+
==== Some Examples ====
 
'''<pre>
 
'''<pre>
−
*1*0*25##          Turn off light 2.5 on local interface (e.g. F
+
*1*0*25##          Turn off light 2.5 on local interface  
 +
| | |
 +
| | +- light address 25
 +
| +- 0=OFF
 +
+- WHO=1 lighting
 +
 
 +
*0*13*19#4#06##    Launch scenario 13 of scenario list 19 on interface 6
 +
| |  | |
 +
| |  | +- #4#06 = interface 6
 +
| |  +- 19 = address of scenario list
 +
| +- scenario #13
 +
+- WHO=0 scenarios
 +
 
 
*1*1*47#4#01##      Turn on light 4.7 on interface 1 (#4#01)
 
*1*1*47#4#01##      Turn on light 4.7 on interface 1 (#4#01)
 
*1*1*0415##        Turn on light 4.15 on local interface
 
*1*1*0415##        Turn on light 4.15 on local interface
 
*1*0*0##            Turn off all lights on local interface
 
*1*0*0##            Turn off all lights on local interface
−
*0*13*19#4#06##    Launch command 13 of Scenariolist 19 (e.g a F420 is addressed by 19) on interface 6
 
 
*2*1*91#4#03##      open (1) shutter 9.1 in on interface 3 (#4#03)
 
*2*1*91#4#03##      open (1) shutter 9.1 in on interface 3 (#4#03)
 
*#4*#1*#14*0225*3## Set heating zone 1 manually ON to 22.5°C
 
*#4*#1*#14*0225*3## Set heating zone 1 manually ON to 22.5°C
 
</pre>'''
 
</pre>'''
  
 +
== WHERE Table ==
 +
The WHERE field identifies the object, which can be an area, group, an environment, or just a single light or shutter etc.
  
 +
{| class="wikitable"
 +
! style="text-align:left;"| WHERE
 +
! style="text-align:left;"| Address
 +
! style="text-align:left;"| Info
 +
|-
 +
|0
 +
|General
 +
|The whole system, be careful!
 +
|-
 +
|1..9
 +
|Environment 1 to 9
 +
|Can be a zone or a room
 +
|-
 +
|11..99
 +
|Light point 1.1 to 9.9
 +
|Single addresses
 +
|-
 +
|0110..0915
 +
|Light point 1.10 to 9.15
 +
|Extended addresses on newer gateways
 +
|-
 +
|#1..#9
 +
|Group 1 to 9
 +
|A set of single addresses
 +
|}
  
−
== A Monitor Session with Python ==
+
* A WHERE field can also come with optional parameters, separated by a hash (<tt>#</tt>), e.g. <tt>*WHERE#PAR1#PAR2#...#PARn</tt>.
−
To understand the OWN messages better, you should start a monitor session on your Raspberry Pi and watch the OWN messages flying in from your domotic system. Analyzing these messages gives you an idea how it works. Below is a simple monitor script in Python.  
 
−
 
 
−
start editor nano and create monitor.py
 
−
<pre>nano monitor.py</pre>
 
  
−
Copy and paste the script below into that file and save it.
+
== WHO Table ==
−
After you saved the file, you have to make the file executable:
 
−
<pre>chmod 755 monitor.py</pre>
 
  
−
Copy the content of this script to moniotr.py
+
The WHO value describes the service. Click the service name in table below to get detailed information:
−
<pre>#! /usr/bin/python
 
−
# -*- coding: utf-8 -*-
 
−
import socket
 
  
−
# IP address and port to connect to the gateway, please attapt to your environment
+
{| class="wikitable"  
−
default_gateway_host = "192.168.60.201"
 
−
default_gateway_port = 20000
 
−
 
 
−
gateway_addr_port = default_gateway_host, default_gateway_port
 
−
 
 
−
def monitor():
 
−
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
 
−
    try:
 
−
        sock.connect(gateway_addr_port)
 
−
        data = sock.recv(1024)
 
−
        # expect ACK from gateway
 
−
        if data != "*#*1##":
 
−
            raise Exception("Did not receive expected ACK, but: "+data)
 
−
        # Switch session to MONITOR mode
 
−
        sock.send("*99*1##")
 
−
        data = ""
 
−
        while 1:
 
−
            # Read data from MyHome(R) BUS
 
−
            next = sock.recv(1024)
 
−
            if next == "":
 
−
                break              # EOF
 
−
            data = data + next
 
−
            eom = data.find("##")
 
−
            if eom < 0:
 
−
                continue;          # Not a complete message, need more
 
−
            if data[0] != "*":
 
−
                raise Exception("Message does not start with '*': "+data)
 
−
            print data
 
−
            msg = data[1:eom]
 
−
            data = data[eom+2:]
 
−
    finally:
 
−
        sock.close()
 
−
 
 
−
monitor()</pre>
 
−
 
 
−
Now start the monitor and watch the messages fly by. Exit with CTRL-C.
 
−
<pre>./monitor.py</pre>
 
−
 
 
−
== The Tables of WHO WHAT WHERE ==
 
−
{| class="wikitable" style="float:left; "
 
 
! style="text-align:left;"| WHO
 
! style="text-align:left;"| WHO
 
! style="text-align:left;"| Service
 
! style="text-align:left;"| Service
Line 129: Line 121:
 
|-
 
|-
 
|3
 
|3
−
|[[WHO=3 - Load Control|Load Control]]
+
|[[WHO=3 - Power Management|Power Management]]
 
|-
 
|-
 
|4
 
|4
Line 153: Line 145:
 
|-
 
|-
 
|15
 
|15
−
|[[WHO=15 - CEN MH200N|CEN MH200N]]
+
|[[WHO=15 - CEN]]
 
|-
 
|-
 
|16
 
|16
Line 168: Line 160:
 
|-
 
|-
 
|25
 
|25
−
|[[WHO=25 - CEN F454|CEN F454]]
+
|[[WHO=25 - CEN plus]]
 
|-
 
|-
 
|1000
 
|1000
Line 178: Line 170:
 
|1004
 
|1004
 
|[[WHO=1004 - Heating Diagnostic|Heating Diagnostic]]
 
|[[WHO=1004 - Heating Diagnostic|Heating Diagnostic]]
 +
|-
 +
|1008
 +
|[[WHO=1008 - Door Entry System Diagnostic|Door Entry System Diagnostic]]
 
|-
 
|-
 
|1013
 
|1013
 
|[[WHO=1013 - Device Diagnostic|Device Diagnostic]]
 
|[[WHO=1013 - Device Diagnostic|Device Diagnostic]]
 
|-
 
|-
−
|}
+
|1018
−
{| class="wikitable" style="float:left; margin-left: 10px;width:200px;"
+
|[[WHO=1018 - Energy Management Diagnostic|Energy Management Diagnostic]]
−
! style="text-align:left;"| WHAT
 
−
! style="text-align:left;"| Adress
 
−
|-
 
−
|
 
−
|The WHAT table depends on the WHO service. Please click on the appropriate service in WHO table.
 
−
|}
 
−
{| class="wikitable" style="float:left; margin-left: 10px;"
 
−
! style="text-align:left;"| WHERE
 
−
! style="text-align:left;"| Location
 
−
|-
 
−
|0
 
−
|General
 
 
|-
 
|-
−
|1..9
+
|1023
−
|Zone 1 to 9
+
|[[WHO=1023 - Access Control Diagnostic|Access Control Diagnostic]]
 
|-
 
|-
−
|11..99
 
−
|Light point 11 to 99
 
−
|-
 
−
|#1..#9
 
−
|Group 1 to 9
 
 
|}
 
|}
 +
 +
Those last 2 are used by MHSuite to scan the bus... But I don't have any of those to test, yet
 +
 +
1023 scan request messages don't show up in the monitor (wireshark to the rescue)

Latest revision as of 14:08, 14 May 2018

The OpenWebNet protocol was defined in 2000 by Bticino/Legrand to specify the communication with a Bticino home automation gateway, connected via LAN, RS-232 (serial) or USB. Here you'll get a brief overview of the OWN language syntax. To watch the OWN messages of your Bticino gateway, you should try the Python Monitor in our Code Snippets section.


Basic Syntax Rules

A Bticino gateway sends and receives messages.

  • a message begins with an asterisk (*) and is terminated with a double hash (##).
  • each message contains fields separated by an asterisk (*).
  • a field can contain dimensions and values separated by an asterisk (*) and/or a hash (#)

Example: *field1*field2#dim1#value1*field3...fieldN##

The OWN message syntax

Message Type Message Note
ACK *#*1## Message accepted/understood
NACK *#*0## Message not accepted/understood
Standard *WHO*WHAT*WHERE## Standard message
Status Request *#WHO*WHERE## Request a state (e.g. if a light is ON or OFF)
Dimension Request *#WHO*WHERE*DIMENSION## Request dimension value
Dimension Write *#WHO*WHERE*#DIMENSION*VAL1*VAL2*...*VALn## Write dimension value(s)

We know already that a standard message consists of *WHO*WHAT*WHERE##.

  • WHO identifies the service, such as scenario, light or automation. See WHO table below.
  • WHAT is the action to be performed, such as light ON/OFF or dimmer, shutter up/down etc.
  • WHERE identifies the object, which can be an area, group, an environment, or just a single light or shutter etc. Check out the WHERE table below.
  • ## terminates a message. Larger facilities might have extension interfaces. Addresses connected to on one of these extension interfaces have the prefix "#4#nn, where nn reflects the 2-digit value of the extension interface number. So a message with an address on interface 7 is terminated with a "#4#07##.

Some Examples

*1*0*25##           Turn off light 2.5 on local interface 
 | | |
 | | +- light address 25
 | +- 0=OFF
 +- WHO=1 lighting

*0*13*19#4#06##     Launch scenario 13 of scenario list 19 on interface 6
 | |  | |
 | |  | +- #4#06 = interface 6
 | |  +- 19 = address of scenario list
 | +- scenario #13 
 +- WHO=0 scenarios

*1*1*47#4#01##      Turn on light 4.7 on interface 1 (#4#01)
*1*1*0415##         Turn on light 4.15 on local interface
*1*0*0##            Turn off all lights on local interface
*2*1*91#4#03##      open (1) shutter 9.1 in on interface 3 (#4#03)
*#4*#1*#14*0225*3## Set heating zone 1 manually ON to 22.5°C

WHERE Table

The WHERE field identifies the object, which can be an area, group, an environment, or just a single light or shutter etc.

WHERE Address Info
0 General The whole system, be careful!
1..9 Environment 1 to 9 Can be a zone or a room
11..99 Light point 1.1 to 9.9 Single addresses
0110..0915 Light point 1.10 to 9.15 Extended addresses on newer gateways
#1..#9 Group 1 to 9 A set of single addresses
  • A WHERE field can also come with optional parameters, separated by a hash (#), e.g. *WHERE#PAR1#PAR2#...#PARn.

WHO Table

The WHO value describes the service. Click the service name in table below to get detailed information:

WHO Service
0 Scenarios
1 Lighting
2 Automation
3 Power Management
4 Heating
5 Burglar Alarm
6 Door Entry System
7 Multimedia
9 Auxiliary
13 Device Communication
14 Light+shutters actuators lock
15 WHO=15 - CEN
16 Sound System
17 Scenario Programming
18 Energy Management
24 Lighting Management
25 WHO=25 - CEN plus
1000 Diagnostic
1001 Automation Diagnostic
1004 Heating Diagnostic
1008 Door Entry System Diagnostic
1013 Device Diagnostic
1018 Energy Management Diagnostic
1023 Access Control Diagnostic

Those last 2 are used by MHSuite to scan the bus... But I don't have any of those to test, yet

1023 scan request messages don't show up in the monitor (wireshark to the rescue)

Retrieved from "http://www.pimyhome.org/wiki/index.php?title=OWN_OpenWebNet_Language_Reference&oldid=498"