This website requires cookies to function. Please enable cookies in order to browse this website properly. Read more here.

Philips Somneo API Client

Added on 2021-02-11 11:51:53 UTC

Project on GitHub.


My girlfriend recently bought a Philips Somneo Sleep & Wake-up Light that can be operated over wifi using an app. Since Philips Hue lamps have a well documented API, I wondered if the Somneo lamps had something similar. After some searching I found out that there was no documentation that was publicly available. However, some people did find a way to communicate with the device. This made me curious and I decided to attempt it for myself.

Figuring out the commands

On the Internet, I could find a small number of experiments from people who have tried to communicate with the Somneo. This way, I found out how to control the lights and retrieve the alarm settings, but not much else. The most important discovery was that the Somneo can be controlled using a REST API where data is sent back and forth as JSON. This gave me the idea to try and listen for HTTP traffic between the app and Somneo device to find out more.

Listening for HTTP traffic

By installing the Philips SleepMapper app on my phone I managed to listen for HTTP traffic between the app and the Somneo device. To manage this, I used Fiddler for setting up a proxy. I setup this proxy on my own phone which then let me see all HTTP traffic between the app and Somneo in Fiddler.

Finding out the functionalities

By monitoring the traffic between the app and Somneo it was easy to replicate the same requests. The hardest part was figuring out how all the data fits together. The URL's and JSON parameters are not designed to be user-friendly for other developers like what was done for the Hue lamps. For example, the parameter names are very short, mostly no more than 5 characters. And for retrieving the alarm settings you have to call multiple URLs that only return arrays of booleans and integers, without making it clear how these relate to eachother. So it requires some trial-and-error to figure everything out.

API client library

Eventually, I managed to replicate the functionalities that the app offers and I decided to make these available as a .NET 5.0 API client library. The goal of this library was to make a client available that could be implementd in a .NET application with minimal effort. All classes, methods and properties have descriptive names and comprehensive XML documentation. So it's not difficult to figure out what everything does.

While the functionalities mostly match those of the official app, there were some that needed to be separated or combined to make using the client a little bit easier. Eventually the client was made to, amongst others, offer the following actions:

  • Retrieve information about the device itself, including the product information, wifi connection, firmware version and more;
  • Read out sensor data (light, sound, humidity and temperature);
  • Controlling the lights;
  • Changed the settings of the display;
  • Playing and controlling the sounds, radio or a connected device;
  • Managing the radio station presets;
  • Managing the alarms;
  • Controlling the functionalities that can help you fall asleep more easily.

To easily test out the available functionalities, a simple console application was made that let's you call all available methods of the client.

Purpose of the project

I came up with this project for a few reasons.

The first and foremost was curiosity. These days you can control almost anything over the internet. This apparently includes alarm clocks aswell. When I found out there was no official API but other people did manage to communicatie with the device, I saw a challenge. And because no client was available anywhere I thought it would be a fun idea to develop one myself.

The second reason was home automation. At this time of writing I'm about to move to a new home. Here I'll have more possibilities for tinkering with my home network than I have where I currently live. I also bought a Raspberry Pi some time ago and I thought it would be a fun idea to connect all kinds of devices in my new home. How an alarm clock fits in all of this? That is a good question that I cannot answer yet. But I'm eager to figure out what I can come up with!

Wesley Donker

Software Engineer

The Netherlands