Robin's Blog

Hacking the Worcester Wave thermostat in Python – Part 1

When we bought a new boiler last year, we decided to install a ‘smart thermostat’. There are a wide range available these days, including the Google Nest, the Hive (from British Gas), and the Worcester Bosch ‘Wave’. As we had a Worcester Bosch boiler we got the Wave – and it wasn’t much more expensive than a standard programmer/thermostat.

The thermostat looks like this:


It is mounted on the wall at the bottom of our stairs, and is connected by a cable to the boiler. As you can see, it has a simple touch-sensitive interface: you can increase or decrease the thermostat setting, see the current temperature and the current setting, change from manual to program mode, and see whether the boiler is on or not. For anything more advanced (such as setting the programmable timer) you have to use the mobile app, which looks like this:


Looks familiar, doesn’t it? You have the same simple interface on the app ‘home screen’, but you can also configure the more advanced settings, such as the timer programme:

screen568x568 (1)

Overall, I’m pleased with the Wave thermostat: it is far easier to configure the timer settings on a phone app than on a tiny fiddly controller, and there are all sorts of advanced features you can use (for example, ‘optimisation’, where the system gradually learns how long it takes your house to warm up, and turns the heating on at the right time to get it to the temperature you want at the time you want) – combined with being able to control the heating when away from home.

Anyway, of course one of the first things that I looked for once it had been installed was an API that I could use to monitor and control the thermostat from my home server, ideally through a Python script. Unfortunately there was nothing about an API on the Worcester Bosch website, and when I phoned Customer Services they told me than there was no API available. So, I thought I’d try and reverse engineer the protocol that was used, and see if I could hack together a Python interface.

How does the system overall work?

When starting to investigate this, my a priori understanding of the system was that the app must send messages of some sort to a remote server (presumably run or controlled by Bosch), which then forwards the messages on to the thermostat itself, and vice-versa. This is because you can access the thermostat via the app wherever you are: you don’t have to be on the same wireless network. Whatever protocol or ports that are used must be ones that can reliably get through home firewalls so that the remote server can actually talk to the thermostat.

What technologies do they use?

When exploring the app I had noticed that there was a Product Information screen which showed information about the software and hardware versions, and included a button labelled Worcester Wave uses Open Source software. Tapping this shows a list of open-source packages that are used by the system, including their various license agreements. The list consisted of:

  • AndroidPlot – a plotting library for Android
  • Guava – Google Java core libraries
  • XMP Toolkit – eXtensible Metadata Platform
  • Smack – a Java XMPP (also known as Jabber) chat protocol implementation
  • JSR305 Expert Group – Annotations for Software Defect Detection in Java
  • Lucent technologies – Not sure, couldn’t find this one!
  • Chromium – I’m not sure why the Chromium web-browser was used
  • Takayua OOURA – Ooura’s Mathematical Software
  • Eigen software – matrix manipulation tools
  • libresample – resampling of data (primarily audio, but presumably other datatypes too)

So, looking at that list suggests that the eXtensible Messaging and Presence Protocol (XMPP) is used for communication, potentially with some metadata embedded with the eXtensible Metadata Platform. The rest of the libraries aren’t very relevant to our work, but are interesting to see (I suspect the mathematical ones are for doing the maths for some of the advanced features like optimisation).

What is being sent, and where to?

So, we think the communication is using XMPP – now we need to confirm that, and work out what is being sent and where it is being sent to. So, I opened up Wireshark to start sniffing the traffic. After playing around a bit with the filters, I got this (click to enlarge):

Screen Shot 2016-01-02 at 22.45.15

This shows that my guess was correct: the XMPP protocol is being used to send messages between the phone running the Wave Android app ( on my local network) and a server run by Bosch ( So, we now know what protocols we are dealing with: that is the good news.

However, the bad news is the STARTTLS messages that we see there. You may recognise this from email configuration dialog boxes, as it is one of the security options for connecting to POP3/IMAP/SMTP servers. It stands for ‘Start Transport Layer Security’, and is basically a way of saying "I want to encrypt this conversation from now onwards, is that ok?" (for reference, the alternative is to do everything with encryption right from the start of the communication). Anyway, in this case the Bosch server responds with PROCEED ("Yes, I’m happy to do this encrypted"). From that point onwards, we see the TLS security negotiation ("What sort of encryption do you support?", "I support X, Y and Z", "Ok, lets use Z", "Here are my keys" etc) followed by a lot of ‘Application Data’ messages:

Screen Shot 2016-01-02 at 22.54.06

We can’t actually see any of the content of the messages, as they are encrypted, so all we get is the raw hex dump: 80414a90ca64968de3a0acc5eb1b50108bbc5b26973626daaa….(and so on). Not very useful!

I think this is a good place to finish Part 1 of the story. We have worked out that communication goes from the app to a Bosch server, and it uses the XMPP protocol, but with TLS encryption using STARTTLS, so we haven’t been able to work out what any of the messages actually contain. Come back for Part 2 to hear how I managed to read the messages…

If you found this post useful, please consider buying me a coffee.
This post originally appeared on Robin's Blog.

Categorised as: Home Automation, Programming, Python


  1. Macaron says:

    nice post

  2. […] the previous part we had established that the Worcester Wave thermostat app communicates with a remote server (run […]

  3. […] I must say this is a bit of a departure from the normal content of my blog, but I think this is something important to post, as part of Blogging Against Disablism Day 2016. (For those who are coming here from BADD16, this blog usually talks about my academic work, Python programming, computing tips and other random things.) […]

  4. Ian Yorston says:

    Sorry to follow up so late after this posting but can you offer me any clue as to why I can’t use the Wave iOS app on the Enterprise WiFi here at school.

    The controller works fine on home wifi. The app works fine on home wifi. The app works fine on 3G and 4G. But if I connect to the school enterprise wifi then the app fails to connect.

    I’m assuming that the app fails to connect to Bosch servers – presumably because the XMPP protocol with TLS encryption (STARTTL) is somehow being blocked by the network

    Presumably meaning that the school network is blocking port 5222 (client-server) or 5269 (less likely, server-server).

    Does that sound right? Or might there be other reasons?

  5. Robin Wilson says:

    Yes, I suspect the school network firewall is blocking one of those ports – unless you can persuade the school IT technicians to open those ports then I’m afraid you’ll have to stick with 3G/4G at school.

  6. thronjuwel says:

    It came with the option of a Wave smart-thermostat and although i had been eyeing up an EcoBee it was looking doubtful it would be available in the UK by the time I was going ahead with the installation.

  7. Ben says:


    I’m having a lot of issues with the Wave – I’ve had a Synology and AirPort Extreme, and both see constant disconnections so I have to restart my boiler to reconnect the Wave.

    The Wave has a DHCP reservation and all other connections are fine – did you experience any intermittent connections in your tests? Do you know of any ports which need to be open to allow constant external uptime?


  8. Robin Wilson says:

    The only problems I’ve had with intermittent connections are when the router was too far away from the Wave. I used an old wifi access point I had lying around and connected that up as a repeater to make the connection a bit stronger. That’s all I can suggest I’m afraid – I don’t think there are any ports that need opening specifically.

Leave a Reply

Your email address will not be published. Required fields are marked *