MySensors: a C++ library for DIY sensor networks that talk to a home automation gateway

Two tiers in one repository: node firmware and gateway

MySensors is a library and a set of examples, and the repository description is only that. The interesting structure is that the same tree contains both ends of a sensor network.

The node side is the part most people meet first. It is a C++ library that runs on Arduino boards and on the ESP8266 and ESP32, and the topic tags name the supported hardware families: arduino, esp32, esp8266, samd, stm32, teensyduino, nrf5x and raspberry. The library lives in core/, with the hardware abstraction in hal/ and the per-device drivers in drivers/. MySensors.h is the main header, MyConfig.h holds the compile-time configuration, and MyASM.S is the assembly support file. library.json and library.properties are the manifests that let the Arduino IDE recognise it, and keywords.txt is the syntax highlighting definition for the editor.

The gateway side is less obvious from the top-level listing, and it is where the Makefile becomes important. The Makefile builds a binary called mysgw, and the sources for it are the Linux hardware abstraction layer plus examples_linux/mysgw.cpp:

GATEWAY_BIN=mysgw
GATEWAY=$(BINDIR)/$(GATEWAY_BIN)
GATEWAY_C_SOURCES=$(wildcard hal/architecture/Linux/drivers/core/*.c)
GATEWAY_CPP_SOURCES=$(wildcard hal/architecture/Linux/drivers/core/*.cpp) examples_linux/mysgw.cpp
INCLUDES=-I. -I./core -I./hal/architecture/Linux/drivers/core

The comment at the top of the Makefile says the Arduino library build part was inspired by the Arduino-Makefile project, and the description says to use make all and make install to install the gateway. The config comes from a Makefile.inc file that the Makefile includes.

So the architecture is a two-tier one. Nodes are cheap, battery-powered microcontrollers that sense and report. A gateway, running on a Linux machine, receives their radio traffic and relays it onward to a home automation controller. The examples directory makes the split visible in the names: GatewayESP8266, GatewayESP32, GatewayESP8266MQTTClient, GatewayESP32MQTTClient, GatewaySerial, GatewaySerialRS485, GatewayW5100, GatewayGSMMQTTClient, GatewayESP8266SecureMQTTClient and GatewayESP8266OTA, against sensor-side examples like AirQualitySensor, CO2Sensor, DustSensor, BatteryPoweredSensor, BinarySwitchSleepSensor, DimmableLight and EnergyMeterPulseSensor.

The audience is therefore the person with a soldering iron and a home automation system, and the person who wants to replace a proprietary sensor with one they built.

The gateway is the piece that chooses your controller

Looking at the example names more closely tells you what the gateway is for. A gateway exists to be the bridge between the radio network and whatever already runs your house.

GatewaySerial and GatewaySerialRS485 are the plain cases: the gateway speaks the serial protocol to a controller over a serial line or an RS485 bus, which is the wiring a local controller expects. GatewayW5100 does the same over a wired network using the W5100 Ethernet controller, and the MQTTClient variants do it over MQTT, which is how a controller that expects MQTT is fed.

The client name matters because the gateway is not a translator between everything. It implements one upstream protocol, and you pick the example that matches your controller. That is the single most important decision in a MySensors build, and it is why the repository ships around a dozen gateway examples rather than one configurable one.

The two secure and OTA variants are worth noting separately. GatewayESP8266SecureMQTTClient is a gateway that talks to its controller over an encrypted MQTT connection, and the presence of several GatewayESP8266OTA and GatewayESP32OTA examples tells you the gateway's own firmware is updatable over the air, so you are not walking to the machine with a serial cable every time something changes. LogOTAGateway is the same idea applied to logging the gateway's own output.

The GSM variant, GatewayGSMMQTTClient, is the one that changes the topology rather than the protocol. A cellular-connected gateway does not need to be on the same network as the controller, which is the way to cover a site where the radio network and the building network are far apart, or where the site has no wired network at all.

The result is that the choice of controller constrains the hardware, and the hardware constrains where the gateway can live. For a house, that is usually straightforward. For a site with several buildings, a GSM gateway with an MQTT client is a different plan from a serial gateway next to the controller, and the examples are the catalogue of those plans.

Building the gateway on a Raspberry Pi, which the Makefile branches for

The Makefile has a conditional block for the Raspberry Pi SoCs, and it is the clearest place to see how the project handles platform variation.

ifeq ($(SOC),$(filter $(SOC),BCM2835 BCM2836 BCM2837 BCM2711))
BCM_C_SOURCES=$(wildcard hal/architecture/Linux/drivers/BCM/*.c)
BCM_CPP_SOURCES=$(wildcard hal/architecture/Linux/drivers/BCM/*.cpp)
GATEWAY_OBJECTS+=$(patsubst %.c,$(BUILDDIR)/%.o,$(BCM_C_SOURCES)) $(patsubst %.cpp,$(BUILDDIR)/%.o,$(BCM_CPP_SOURCES))

INCLUDES+=-I./hal/architecture/Linux/drivers/BCM
endif

So a Raspberry Pi build pulls in an extra driver directory under hal/architecture/Linux/drivers/BCM on top of the common Linux core drivers, and the specific SoC is selected by setting SOC on the make command line. The four identifiers cover the Pi generations the project has been kept up with, and the general pattern is that each platform has its own subtree under hal/architecture/.

Two details of the build configuration are worth knowing before you start. The compile flags are set globally as CPPFLAGS+=-Ofast -g -Wall -Wextra, so the build enables aggressive optimisation and keeps the warning set wide, and it keeps debug information even in an optimised build. The dependency tracking uses DEPFLAGS=-MT $@ -MMD -MP, which is the standard make pattern for tracking header dependencies so that a changed header triggers a rebuild of the objects that include it.

The get_library_includes and get_library_files functions in the Makefile handle the Arduino library layout, and they are written to cope with two different directory conventions. For the old 1.0.x layout they look in the current directory and in a utility directory, and for the new 1.5.x layout they look in src and recursively in its subdirectories. That is a small piece of engineering that says the build supports libraries laid out the old way, which is common in the Arduino ecosystem where libraries predate the src/ convention.

The build also expects a Makefile.inc for its configuration, since CONFIG_FILE=Makefile.inc is included at the top. That file is not in the repository listing, so it is created locally, and it is where the build directory, the install directory and the SOC setting will go.

Alongside the gateway there are the supporting directories: Logparser/ for parsing the serial log output, initscripts/ for starting the gateway as a service, projects/ for the Arduino IDE project files, tests/ for the test suite, and Documentation/ with the Doxyfile that generates the API documentation.

The two documentation tracks, and the release state that follows from them

The README is short, and the interesting part is that it describes a project with two parallel documentation and release lines rather than one.

The first line is master. Its API documentation is at www.mysensors.org/apidocs/index.html, and the master branch has its own CI badge for the normal build and a second badge for the nightly build of the Arduino IDE. The second line is development, with its documentation at the apidocs-beta path, and its own pair of CI badges for the normal and nightly builds.

So there are four build jobs in total: master and development, each in a regular and an Arduino IDE nightly variant. The nightly IDE build is the one that produces the package the Arduino IDE badge points at, and the README says the current version in the Arduino IDE is MySensors Library v2.4.0-rc.1, which is a release candidate.

The release list tells the rest of the story. The tags are 2.3.2 from 2019-12-09, 2.3.1 from 2018-12-14 and 2.3.0 from 2018-06-18. So the newest tagged release is 2.3.2, from December 2019, while the version in the Arduino IDE is a 2.4.0 release candidate, and the default branch of the repository is development rather than master.

Read that combination carefully. The library that most people install through the Arduino IDE is a release candidate, not a final release, and the last tagged version is considerably older than both the release candidate and the branch activity. The repository is not archived, but the last push was on 2026-04-18, so the tip has been quiet for months and no final 2.4.0 has been tagged.

That has a concrete consequence. A node firmware you flash is coupled to the version of the library it was built against, and the gateway has to be compatible with the nodes. If the Arduino IDE currently serves 2.4.0-rc.1 while the tags stop at 2.3.2, you are building against a moving target, and a project that needs a reproducible firmware image should pin to a tag rather than take whatever the IDE resolves to.

Where MySensors is the wrong tool

There are three limits, and they are of different kinds.

The first is the hardware floor. MySensors is firmware for microcontrollers, and a node has to be something you can flash, usually an ESP8266 or ESP32 or an Arduino-compatible board, and you need a radio link between the nodes and the gateway. The topic tags name the supported families, but a specific board variant with a specific radio is a question the drivers/ directory has to answer, and the README does not enumerate them. If your sensor has to be a mains-powered Linux box on Ethernet, MySensors is the wrong layer, because what it provides is a way to make cheap battery nodes talk to a gateway.

The second is the controller dependency, and it is the one that decides the whole project. A gateway example implements one upstream protocol, so the controller in your house, Home Assistant, openHAB, Domoticz or whatever else, and the version of it, determine which example you can use. Changing controller means changing gateway firmware. And because the upstream protocol is the one thing MySensors does not abstract, this is a hard coupling that no amount of configuration removes.

The third is the release state described above: a 2.4.0 release candidate in the Arduino IDE, tags stopping at 2.3.2 in December 2019, and a development branch as the default. For a hobby project that is fine, and the rc suffix in a version number is a normal thing to accept. For a product, or for a house with a hundred nodes that have to keep working for a decade, the absence of a final 2.4.0 release and the age of the last tag are legitimate concerns about how long a given firmware image stays buildable.

The licence is the fourth, quieter point. No licence is stated in the repository metadata, and the repository listing does not show an obvious LICENSE file among the top-level entries, where there is a Doxyfile, a Makefile, a configure script, a library.json and library.properties, but no licence file. The project ships prebuilt through the Arduino Library Manager, and Arduino libraries are conventionally distributed under a permissive licence, so the terms are probably present in the library.properties or in the upstream documentation, but this article cannot confirm that from what is visible here, and a project that has not stated a licence in the repository is a project whose terms you have to go and look up.

Editorial conclusion

Adopt MySensors if you are building your own home automation sensors, you want a node firmware library and a gateway in the same tree, and you are prepared to wire the hardware and the controller integration yourself. Do not adopt it if you want a finished product with a commercial support contract, since the release tags stop at 2.3.2 while the tree carries a 2.4.0 release candidate. Verify first that the controller you use speaks the protocol your gateway example targets, that your node's radio hardware has a driver in drivers/, and that the licence terms in the repository cover your use, since no licence is stated in the metadata.

Frequently asked questions

Official sources

1. Issues
2. mysensors/MySensors on GitHub
3. Project website
4. README
5. Releases