A technical introduction to Homey

In these 'Behind the Magic' series we will give in-depth information about Homey and the technology behind it. Not only because we like geeky people and hopefully provide them some new insights, but also because we're proud of what we are building at Athom! This is the first post in the 'Behind the Magic' series and will give a general overview of Homey. After reading we hope you have some idea about how Homey works, and everything that went into making our product do what we hoped for!

Hardware

In order to produce a high quality product we believe it is essential that both the hardware and software are tailor-made to best serve its intended purpose. Think for example about gaming consoles, which can produce stunning graphics with a graphics card that is already years old. When we started with Homey there was of course no hardware we could get off the shelf, so we had to design our own. Considering our high quality requirements, eight (!) wireless protocols and an unusual design, it was definitely a challenge to fit all of that in a 12 cm sphere.

1. MicroSOM (CPU, RAM, Wi-Fi & BT)
2. 4 GB eMMC Flash
3. Power Supply
4. RGB LED (24x)
5. Microphones (2x)
6. Audio Chip
7. 433 MHz
8. 868 MHz
9. Z-Wave
10. ZigBee
11. NFC (IC & antenna connector)
12. Infrared LED (6x)
13. Infrared receiver

We've often heard from respected partners that it's a miracle that we were able to get all these technologies work together without any problems. Our hardware designers really did an outstanding job here!

Homey's input/output hardware components

MicroSOM

The MicroSOM is the heart of Homey, and runs our own flavor of Linux. It communicates to all Homey's different chips over various interfaces: USB, I2C, UART and GPIO. It's IMX6 processor is clocked at a maximum speed of 1.0 GHz and has 512 MB RAM available, which allows for many apps to run on Homey.

Microcontroller

The MicroSOM's smaller brother, the Microcontroller, is placed between the 433 MHz and 868 MHz antennas. The Microcontroller takes care of those two frequencies (which in turn both have their own chip, the Texas Instruments CC1101). In addition the Microcontroller can control the LED ring while Homey is booting and manages the data stream generated by the accelerometer. A way to reset Homey was necessary, but a button wouldn't look good. This is where the accelerometer comes in handy. With the accelerometer Homey determines if it's turned upside down and can go into DFU (Device Firmware Upgrade) mode during the first 5 seconds of booting, or start Wi-Fi Recovery afterwards.

Audio

There are 2 state-of-the-art microphones placed inside Homey that record a high-quality stereo signal. The audio chip runs it's own DSP (Digital Signal Processing) software, which does noise reduction, volume optimisations and various filtering to ensure an optimised signal for our software processing. The audio chip can also play music over the internal speaker or to the jack-output, if connected. Homey also detects whether or not an audio jack has been plugged in. It can also keep track of volume states and sound muting. So, perhaps in the future if music should be playing but Homey's microphones are not hearing it, Homey can automatically attempt to turn on or unmute your speakers.

Software

Ambitious hardware simply deserves brilliant software. We have designed our own flavor of Linux based on Debian. There are multiple hand-crafted kernel modules such as the LED Ring driver and the Infrared driver. There is a system partition on Homey, where the system files reside. Most of the space, however, is reserved for user data on a separate partition. When you reset a Homey, this partition can be wiped and Homey starts like it's brand new.

SSH (terminal) access is not available on sold Homeys for legal & security reasons. We míght release a Linux image without our proprietary software in the future.

Wi-Fi Recovery

When Linux has been booted, Homey determines whether or not to go into Wi-Fi Recovery by looking at it's physical position with the accelerometer, or if user data exists. In the Wi-Fi Recovery, a hotspot is created using hostapd and a webserver is started so the user can connect to it through setup.athom.com. A cool fact about Wi-Fi Recovery is that when we found a bug in the recovery software itself, we can create a special command that executes a command on a Homey. This command must be signed by Athom using our private key, which means that only an authorized Athom employee can do so.

Homey Core

When everything seems to be fine, the core of Homey is started by Linux. This is a Node.js application, which means that it's written mostly JavaScript. Because we are using this high-level language we can increase our development speed. Not only does Node.js offer the advantage of a relatively easy language, there are also many modules available made by the open source community that Homey utilises. We also give back to that open source community! For example our node-nfc, node-pcm2wav, node-linux-device and imx6-usermode-ocotp libraries are all open source. Homey Core creates a webserver, which is essentially an API for all of its features. It also serves the front-end HTML, CSS and JavaScript files for your browser to render. If you're connecting to your homey remotely these files are served from our CDN (Content Delivery Network), but more about that in a future post. Most API calls require authorization, so only you and the people you have granted access can control your Homey. We are also aiming to make access control more advanced in the future, comparable to sharing a folder on e.g. Dropbox. Homey Core talks to the Microcontroller, the LED Ring, the Audio Chip, the Z-Wave and ZigBee chips, the NFC chip and the Infrared LEDs and Infrared receiver. Mostly using native bindings, so code is executed in their own threads to keep things fast.

Apps

While Homey Core runs its own process, apps run in their own. An App is sandboxed, which means that it can't access the system it runs in, only specifically what an app has requested permission for. If we hadn't designed apps like this, every app would for example be able to control all your devices! An App talks through our own 'abstraction layer' to Homey Core. So every API call on the Developers API page is transmitted securely and reviewed by Homey Core before it executes. Apps can even talk to each other if they request permission before they are installed!

Apps can be profiled for performance to make sure they don't take Homey down with them

Devices

On a software architecture level the aim with Homey is to create a database of devices that 'can do things'. Those 'things' are called capabilities. Capabilities are what glues devices together in the Devices overview, but also in the Flow Editor, Insights and Speech. For example, a Philips Hue light bulb can do certain things. It can turn on or off, change color and change brightness. These are all seperate 'capabilities' of a device class 'light' in Homey. A paired Philips Hue device is registered with the capabilities `onoff`, `dim`, `light_hue`, `light_saturation` and `light_temperature`. Or a subset of these capabilities, when the light can only dim, for example. When you say "Turn all lights in the Living Room to red", Homey finds all devices you have in the Living Room that can turn to red. The Hue is matched from this database of devices, and a signal is sent to the app to turn that device to red, which in turn sends the signal to the light itself using the appropriate wireless technology. The Flow Editor also shows only the cards that are applicable for this device when you drag it around. The mobile card only shows the color wheel if your device can change color, etc. We designed the devices model like this so that regardless of the brand or a device's functionalities so it fits neatly in Homey. Even if your light has a native 'Disco Mode', you can simply add a Flow action in your App which smoothly integrates next to the default Flow actions such as 'Turn on' and 'Dim'. In general our aim is to connect different devices in the way that creates the smoothest user experience!

Cloud

We've designed Homey to be mostly independent of Cloud services, because there's nothing more frustrating than not being able to turn your lights on because some 3rd party doesn't feel like it that day. So Homey itself is fully accessible locally, and in the improbable event that Athom goes bankrupt and is forced to shutdown the servers, most Homey functionality will still work. That doesn't mean that our Cloud isn't a work of art in itself though. We maintain various services running to extend Homey. Most of them can also be found on our Athom Status, as well as their health.

My Athom

This is the portal to your Homey(s). It is also the server that your Homey is always connected with, so you can reach it from anywhere in the world. When you're visiting my.athom.com on your local network, it automatically detects this. That way, when you click on your Homey, the browser is redirected to the Homey's LAN address for the quickest interaction. When your Homey can not be reached locally, a proxy URL will be used. This looks like https://your_homey_id.homey.athom.com and is unique for that specific Homey. All traffic that goes to that URL is proxied through My Athom, and from there to your Homey over the persistent connection it has with My Athom. When using this proxy, you can imagine we have to handle a lot of traffic. Luckily we've built the system so that all content such as images, fonts, html etc. is downloaded from our CDN, a Content Delivery Network that has servers across the world. So only the Homey-specific traffic, or 'API calls', are proxied. Not bad, right? This might seem cumbersome, but the alternative would have been to let the user open ports in his or her router, disable firewalls etc. That would be a technical hassle we didn't want our users to have to go through, as it goes against our 'even my mom can use it'-philosophy. (Sorry, mom.)

App Store

The App Store is where you go to get new Apps for your Homey. When logged in, you can select which Homey you want to install the app to. Developers can submit their Apps here as well, which are then reviewed by someone at Athom to assure the quality is up to par. This review process will get better over time, because we also have to learn what non-Athom developers come up with!

API

This is the service that connects to our database where all Homeys are stored, which user has access to whichs Homeys, etc. In the end, a Homey itself decides if a user may access it. So the API is more of a telephone book than a master key. We can't access a Homey, even if we wanted to, without a Homey owner's permissions.

Setup

The Setup service has been built to connect your Homey to Wi-Fi. When Homey hasn't been set up yet, or Homey is turned upside down, the Wi-Fi Recovery is started on Homey. This is essentially a webserver where the Setup service can send commands to. These commands can be things like 'Which Wi-Fi networks do you see?' or 'Connect to this network with this password'. Additionally, we can execute a shell script on Homey, to fix any bugs we might encounter after a Homey leaves the factory. These scripts are signed and thus can only be made by Athom, which leaves Homey secure, yet updatable.

Speech to Text

This is the service that converts audio into a piece of text of what you said. When Homey has heard 'OK Homey', a connection to this server is opened, and the microphone's recordings are streamed to this server, until a certain amount of silence has been heard. This server then forwards the audio to 3rd party services, and when they come back, we compare them to pick the best result. A few factors are weighted here such as speed, accuracy and 'dynamic-ness'. Some servers are very good at dynamic words such as artists or movie names, but they are generally slower. So when we detect words that hint on dynamic words, such as 'music', 'movie', 'play' etc, the Speech to Text service at least waits for the 3rd party service that's best at detecting those to finish. This way we can ensure the best results for each scenario.

Firmware

The Firmware service is where all Homey's updates are coming from. Homey checks for updates regularly, and the Firmware service returns an update when it's available, depending on your channel (stable or experimental) and current Homey version. Usually the service returns a list of patches to get your Homey from version A to version B. For example, if you're on version 0.8.20, and 0.8.29 is the latest version, and you're in the stable channel, then all patches in the stable channel are returned, for example 0.8.20-to-0.8.27 and 0.8.27-to-0.8.29. These are then installed by Homey in that exact order. This way we guarantee that every Homey has the same software installed. If your version is corrupt, because an update was interrupted yet Homey still magically is able to work (usually a 0.0.0 version), a full image is served. This contains the complete filesystem, and is flashed at once to get your Homey to the latest software. In the future, we will release a tool for Mac and PC that will completely wipe a Homey to its factory state, even if a homey can't be accessed anymore because an update went wrong.

Notifications

This service makes sure that your Homey can send Push notifications to your smartphone. It keeps track of installed smartphone apps, and connects them to a Homey. In the future, more types of Push notifications will be added. For example, we have recently added a 'morse code', so you can vibrate your phone in a pattern from a Flow!

Webhooks

A Homey is usually placed behind a router at home, and is not reachable by external servers. The Webhooks service is made for developers to let their Apps receive notifications from external services. For example, when an App has support for a thermostat, it has two options to detect if the temperature has changed. It can ask every x seconds for a value, calling polling, or wait for the thermostat itself to notify of a change, calling push. Polling is very inefficient and, as you can imagine, creates a delay between changes. The Webhooks service allows external services, such as the thermostat from the example, to notify a Homey directly without caring about firewalls. It just sends a HTTP request to https://webhooks.athom.com/webhook/the_webhook_id, which is then forwarded to the right Homey, which forwards it to the right App, which in return shows the right temperature on your screen.

Callback

This is a very simple service that enables apps to make use of OAuth2 access, which you might know from 'Do you want to give this application access to ...' dialogs. Because these services usually require a static callback URL, but Homey's own URL is dynamic, this service forwards that data to a Homey. That's all!

Other services

There are more services running, such as the website, forum, a service for in our factory, a service for infrared codes, and soon a new support service that will give our support people a way to remotely assist on a Homey!  

  I really hope that this blog gave some insight in how Homey works, and how complex it is to create a product so diverse! In the upcoming blogs, we will go into more depth about how things work, and additionally some non-technical blogs about the business world of Homey. Love, Emile