Long time no see!

In the last weeks I’ve been working on a new project called PyOWN. It’s a Python library to interact with the OpenWebNet protocol, which is used in home automation systems like MyHome by Legrand.

The library is still in development, but it already has some features implemented. You can check the code on GitHub

Why I’m doing this?

I’ve been wanting to start a serious Python project for some time. I’ve been using Python for quite a few years now, but everything I’ve done so far has been abandoned or is just something that I use for myself. I wanted to do something that could be useful for other people. So, why not implement some obscure protocol that nobody uses? Well, I don’t know, but I’m doing it anyway.

Also, I have a MyHome system at home and I wanted to be able to control it from my computer. I’ve tried some other libraries, but none of them worked for me. So, I decided to write my own.

What is OpenWebNet?

OpenWebNet is a protocol used and invented by Bticino, a company that is now part of the Legrand group. It’s used in home automation systems like MyHome, which is what I have at home. Basically, it allows communication with a gateway which then sends commands on a physical bus to the actuators. It was invented in the 2000s and it’s still used today. It also has a registered port in the IANA list and it is the 20005. However, most systems by default use port 20000 and no system supports the UDP protocol. I don’t understand why they have registered the 20005 port for both TCP and UDP.

It’s a simple protocol, but it has quite some quirks that makes it a bit difficult to implement nicely.

For example, the protocol consists of strings of numbers separated by asterisk or hashtag, like *1*0*11## which means “turn off the light in the area 1 point 1 “. The fact that is composed of strings makes it difficult to implement in a language without a good string manipulation library, like C. But in Python, it’s somewhat easier. There are still some difficulties regarding the documentation: not all features are documented, and the ones that are documented are not always clear.

Message syntax

There are several types of messages that can be sent to the gateway, then there are also system messages used for handshaking and acknowledgment that follow a unique syntax. But, they all follow the pattern. *tag1*tag2*tag3*tagN##. Each tag is a number and can optionally have arguments separated by ‘#’ that are also numbers. In some cases, tags are also optional, like in this case: *#*0## which is the NACK message, *#13**10## which is a command for the gateway.

If you want to learn more about the protocol, you can check the official documentation or for a more general overview the Wikipedia page.

What’s next?

I will continue to work on this project for some time. I want to implement all the publicly documented features. I also want to fully document it and write some tests.

Probably, after that, I will start to work on a plugin for Home Assistant because the current plugin for OpenWebNet only implements a few features and it’s not maintained anymore.

Fun fact

With the MadrHacks team, I’ve written a challenge for the SnakeCTF 2023 that was about the OpenWebNet protocol, more specifically on the brute-force vulnerability of the password “hashing” algorithm for sending the password over the network (the protocol is not encrypted).

Disclaimer

  • This library is not associated by any means with BTicino or Legrand companies
  • The Open Web Net protocol is maintained and Copyright by BTicino/Legrand. The documentation of the protocol if freely accessible for developers on the Legrand developer website
  • “Open Web Net”, “SCS”, “MyHOME_Up”, “MyHOME”, “MyHOME_Play” and “Living Now” are registered trademarks by BTicino/Legrand