View source for MyHome OpenWebNet Via LAN Interface

== Overview ==
Open Web Net is a language through which it is possible to exchange data and send commands between a remote unit and the BTicino My Home system. The protocol is thought to be independent of the means of communication used, considering as a minimum requirement the possibility of being able to use DTMF tones on the normal PSTN telephone line.
This language was also designed to allow devices such as PCs, Smartphones and tablets to communicate with the My Home system remotely.
The Open Web Net was introduced to provide an abstract level that allows the supervision and control of My Home systems focusing on the functions without caring about the details of the installation and without having to know the SCS technology.

Detailed information can be found on the manufacturer site:
[https://www.myopen-legrandgroup.com/it/developers/]

=Myhome gateway support=
Domoticz supports both official and unofficial gateways.
The supported devices are:
*F454 Web Server A/V
*MyHome Server1
*MyHome Screen 3.5"(eg. LN4890)
*MyHome Screen 10"
*MH202 Scenario programmer
*others not yet tested ..

=Myhome gateway authentication=
Authentication can be performed in 3 ways:
*Without password, via IP of the device within the IP range enabled in the gateway
*With numeric password (at least 5 characters) for unofficial gateways that require a hash calculation
*With alphanumeric password (from 5 to 16 characters) for the gateways that implement HMAC authentication (eg MHS1 or F454 with the HMAC option enabled)

=Domoticz integrated OpenWebNet support=
The OpenWebNet protocol is now partially supported out-of-the-box in the current version.
*Setup -> Hardware.
*Configuration:
**'''Model''': select 'MyHome OpenWebNet with LAN interface'.
**'''Remote addess''': set the ip of your OWN gateway.
**'''Port''': set default 20000, or your personalized port.
**'''Rate Limit''': set the seconds between the complete scans of your system. Set 0 to disable continuous scanning. If there are many devices in the system, it is advisable to leave this value at 0.
**'''Date/time synchronization''' (available with stable version > 2020.2): set the minutes between the date / time synchronization checks. Set 0 disable the synchronization of your Bticino domotics system.
**'''User name''': used only with HMAC authentication
**'''Password''': from 5 to 16 alphanumeric characters (for unofficial gateways must be a numeric password).
*Press Add.
*At the first connection, the system will be scanned and the supported devices will be created automatically*.
*Setup -> Devices will show all the newly added devices.

 *Some devices, such as dry contacts and temperature probes, are added only when they spontaneously update their status. This means that before they are visible in the device list you have to wait for the first event captured by the connection in monitor mode.

==Manual addition of devices==
Some types of devices can also be added manually. These devices are:
*lights
*blinds
*auxiliary contacts
To do this it is necessary:
*go to Switches -> light / manual switch
*Select your OpenWebNet Hardware
*Select the switch type you want
*Select the model:
**'Lights OpenWebNet Bus'
**'Blinds OpenWebNet Bus'
**'Auxiliary OpenWebNet Bus'
**'Dry Contact OpenWebNet Bus'
**'IR Detection OpenWebNet Bus'
**'Custom OpenWebNet Bus'
*Select the area code and light point of the device you want to add
*Then add device

=OpenWebNet message=
An OpenWebNet message is structured with variable length fields separated by the special character '*' and closed by '##'.

The characters admitted in the fields are numbers and the character “#”.

{|class="wikitable"
|+
! Fields
! Description
|-
| WHO || home automation system function to which the OpenWebNet message is referenced 

(example WHO = 1 for the messages for lighting system management)
|-
| WHAT || an action to do or a status to read. For every WHO there is a specific WHAT table. 

(example of actions/status: switch OFF light, active alarm ..)
|-
| WHERE ||  the set of objects to which the OpenWebNet message is referred. 

It can be a single object, a group of objects, a specific environment, the entire system, etc. 

For every WHO (and therefore for every function) there is a specified WHERE table.
|-
| DIMENSION || a range of value of the dimension of the object to which the message is referred. 

For every WHO (and therefore for every function) there is a specific DIMENSION table.
|-
| VALUE ||  the read/written value of a written/required/read dimension
|-
|}

The following table shows the different types of messages that can be sent and received within an Open Client-Server conversation.
{|class="wikitable"
|+
! Message Type
! Format
|-
| ACK || *#*1##
|-
| NACK || *#*0##
|-
| Command / Status || *WHO*WHAT*WHERE##
|-
| Status Request || *#WHO*WHERE##
|-
| Dimension Request || *#WHO*WHERE*DIMENSION##
|-
| Dimension Read || *#WHO*WHERE*DIMENSION*VALUE1*...*VALUEn##
|-
| Dimension Write || *#WHO*WHERE*#DIMENSION*VAL1*VAL2*...*VALn##
|-
|}


=Domoticz OpenWebNet WHO support=
The WHOs supported or not are listed below:
{|class="wikitable"
|+
! Description
! WHO Code
! Support
|-
|SCENARIO || 0 || not supported
|-
|LIGHTING || 1 || <span style="color:green">supported</span>
|-
|AUTOMATION || 2 || <span style="color:green">supported</span>
|-
|LOAD CONTROL || 3 || not supported
|-
|TEMPERATURE CONTROL || 4 || <span style="color:green">supported</span>
|-
|BURGLAR_ALARM || 5 || <span style="color:green">supported</span>
|-
|DOOR ENTRY SYSTEM || 6 || not supported
|-
|AUXILIARY || 9 || <span style="color:green">supported</span>
|-
|GATEWAY INTERFACES MANAGEMENT || 13 || <span style="color:green">supported</span>
|-
|SCENARIO SCHEDULER SWITCH || 15 || not supported
|-
|SOUND DIFFUSION || 16/22 || not supported
|-
|SCENARIO PROGRAMMING (MH200N) || 17 || not supported
|-
|ENERGY MANAGEMENT || 18 || <span style="color:green">supported</span>
|-
|CEN PLUS DRY CONTACT IR DETECTION || 25 || <span style="color:green">supported</span>
|-
|}

=Device description=
The devices are automatically added via bus scan commands and subsequent feeedback on the monitoring connection.
Each device uses an ID made up of WHO and WHERE (as far as possible and compatible with Domoticz).
In addition, only certain types of devices can be added manually.
All the types of devices present are described below.

==Lighting (WHO = 1)==
This device is added as a general switch, below is an example of ID construction:

 Lighting message: *1*0*42##
 WHO = 1
 WHAT = 0 (OFF)
 WHERE = 42 (AREA = 1 + POINT = 7)

The ID consists of an 8 hexadecimal digit number composed as follows:

 ID = (WHO << 16) || WHERE

In this example we have:

 ID = (0x0001 << 16) | 0x002A = 0001002A

NOTE: when a device with a specific area is added, an additional AREA type device is added. 
This new device can control all the lights associated with the same area.

==Automation (WHO = 2)==
This device is added as a general switch, below is an example of ID construction:

 Automation message: *2*2*92##
 WHO = 2
 WHAT = 2 (DOWN)
 WHERE = 92 (AREA = 9 + POINT = 2)

The ID consists of an 8 hexadecimal digit number composed as follows:

 ID = (WHO << 16) || WHERE

In this example we have:

 ID = (0x0002 << 16) | 0x005C = 0002005C

NOTE: when a device with a specific area is added, an additional AREA type device is added. 
This new device can control all the lights associated with the same area.

==Temperature Control (WHO = 4)==
This device is added as a temperature device, below is an example of ID construction:

 Temperature control message: *#4*5*0*0244##
 WHO = 4
 WHERE = 5 (N = 5 + S = 0)
 DIMENSION = 0
 VALUE = 0244 (24,4 °C)

The ID consists of an 4 decimal digit number composed as follows:

 ID = (WHO << 12) || WHERE

In this example we have:

 ID = (4 << 12) | 5 = 4005

==Burglar Alarm(WHO = 5)==
This system add some devices with fixed ID witohu WHO information:
{|class="wikitable"
|+
! ID
! Device description
|-
| 1 - 8 || Alarm sensor zone 
|-
| 17 || System status
|-
| 18 || Network status
|-
| 19 || Battery status
|-
| 20 || System engagement
|-
|}
===Alarm Control with Auxiliary===
With the myhome system it is possible to monitor the alarm system status, but it cannot be controlled directly via the OpenWebNet protocol.
The only possibility is to use AUXILIARY devices, configuring your alarm control panel to execute some commands (eg Activate alarm)
when it receives a particular auxiliary OpenWebNet command.

Automation must be configured via a special alarm system menu.
Automations allow you to run an OPEN command when a particular event occurs.
In this case, the events are the changes of state of the auxiliary device (who = 9) and the command to be performed is a burglar alarm command(who = 5).

Configuration Automation 1: when AUX-1 go OFF, then DISENGAGE all Zones
 Name: Disengaged all zones
 Event: command OPEN = *9*0*1##
 OPEN command to execute: *5*9##

Configuration Automation 2: when AUX-2 go ON, then ENGAGE active Zones
 Name: Engaged active zones
 Event: command OPEN = *9*1*2##
 OPEN command to execute: *5*8##

Configuration Automation 3: when AUX-3 go ON, then ENGAGE Zone 1 and Zone 4
 Name: Engaged zone 1 and zone 4
 Event: command OPEN = *9*1*3##
 OPEN command to execute: *5*8#14##

Now it is possible to create auxiliary devices in domoticz through the manual procedure, first of type 'push OFF button' and the others of type 'push ON button'.

===Alarm notification by LUA script===
Here is a LUA script to receive some notifications.
It is only necessary to change the name of the devices:

"Home alarm status"
'Alarm Zone 1' .. 'Alarm Zone N'
'Battery status'
"Network status"

with those of your devices.

  commandArray = {}
  if devicechanged then
     for deviceName,deviceValue in pairs(devicechanged) do
         
         -- Alarm Engagement
         if (deviceName=='Home Alarm Status') then
             print(deviceName.. ': ' .. deviceValue)
             if deviceValue == 'Engaged' then
                 commandArray['SendNotification']='Alarm Engaged'
             elseif deviceValue == 'DisEngaged' then
                  commandArray['SendNotification']='Alarm DisEngaged'
             end
         end
         
         -- Alarm sensor zones
         if (deviceName=='Alarm Zone 1') or (deviceName=='Alarm Zone 2')) then
             print(deviceName .. ': '.. deviceValue)
             if (deviceValue == 'Intrusion') then
                 commandArray['SendNotification']="Intrusion ON#" .. deviceName
             else --if ((deviceValue == 'Active') or (deviceValue == 'Inactive')) then
                 commandArray['SendNotification']="Intrusion OFF#" .. deviceName
             end
         end
    
         -- General system status alarm
         -- if (deviceName=='Alarm System Status') then
         -- end
        
         -- Alarm battery status
         if (deviceName=='Battery Status') then
             print(deviceName.. ': ' .. deviceValue)
             if deviceValue == 'Battery Ok' then
                 commandArray['SendNotification']='Battery is OK'
             elseif deviceValue == 'Battery Fault' then
                 commandArray['SendNotification']='Battery is FAULT!'
             elseif deviceValue == 'Battery Unloads' then
                 commandArray['SendNotification']='Battery is Unloads!'
             end
         end
    
         -- Alarm Network status
         if (deviceName=='Network Status') then
             print(deviceName.. ': ' .. deviceValue)
             if deviceValue == 'Network OK' then
                 commandArray['SendNotification']='Network is OK'
             elseif deviceValue == 'No network' then
                 commandArray['SendNotification']='No network!'
             end
         end    
     end
   end
   return commandArray

==Auxiliary (WHO = 9)==
This device is added as a general switch, below is an example of ID construction:

 Lighting message: *9*0*4##
 WHO = 9
 WHAT = 0 (OFF)
 WHERE = 4 (AUX number)

The ID consists of an 8 hexadecimal digit number composed as follows:

 ID = (WHO << 16) || WHERE

In this example we have:

 ID = (0x0009 << 16) | 0x00004 = 0009004

NOTE: The auxiliary devices can be used to send commands to the alarm system if the alarm control unit (eg 3486) has been appropriately configured.

==Gateway Interface Management(WHO = 13)==
TODO

==Energy Management (WHO = 18)==
TODO

==CEN Plus, Dry Contact and IR Detection (WHO = 25)==
TODO

==Custom Command==
TODO