Introduction

This program can read data from cheap 433 MHz wireless temperature and humidity sensors and integrate with home automation systems using MQTT broker. It was designed to work with popular ARM boards like Raspberry Pi, Orange Pi, and many others. Home Assistant MQTT sensor discovery is available.

To make it work you need only one external component – 433 MHz receiver. It has to be connected to one of the I/O pins, the program can decode directly data from sensors without any third-party additional components. It supports Nexus sensor protocol which is implemented in many cheap sensors.

Features

• Works on popular ARM Linux boards
• Only 1 EUR external part required
• Supports 5 EUR cheap Temperature and Humidity sensors
• Tracks sensor connection quality
• Reports sensor online and offline status
• Seamless integration with Home Assistant
• Easy integration with MQTT home automation systems
• Many configuration options

Applications

• Home automation
• Temperature monitoring
• 433 MHz to MQTT gateway
• 433 MHz sensor diagnostics

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Hardware

Supported boards

Any board that can run Linux with block device gpiod I/O driver can be used. That means any board with a modern version of Linux is supported. Specifically:

• Orange Pi running Armbian version 5.x. All boards.
• Raspberry Pi running Raspbian. All boards.
• Any board running ≥ Armbian 5.

433 MHz receiver

Any of the cheap and popular receivers can be used. Make sure it is superheterodyne and supports ASK/OOK modulation. The cost of the receiver is about 1 EUR when ordering directly from China.

Sensors

There are many vendors that produce temperature sensors compatible with Nexus protocol. Here are a few that are confirmed to use Nexus protocol:

1. Digoo DG-R8H – Temperature and Humidity sensor. No longer available under Digoo brand.
2. Sencor SWS 21TS – temperature only.
3. Explore scientific 1004H. Temperature and Humidity sensor. Cost 14 EUR.
4. Clas Ohlson

Nexus protocol

A device sends every minute or so (Sencor every 58 seconds, Digoo every 80 seconds) 12 data frames.

Each data frame consists of 36 bits. There is no checksum.

The meaning of bits:

| Bits | 8 | 1 | 1 | 2 | 12 | 4 | 8 | |---------|-----|---------|-----|---------|-------------|------|----------| | Meaning | ID | Battery | 0 | Channel | Temperature | 1111 | Humidity |

1. ID – unique ID; Sencor generates a new ID when the battery is changed, Digoo keeps the same ID all the time.
2. Battery – low battery indicator; 1 – battery ok, 0 – low battery
3. Channel – channel number, 0 – first channel, 1 – second and so on.
4. Temperature – signed (ones' complement) integer; temperature in Celsius degrees scaled by 10.
5. Humidity – unisgned integer; humidity

Every bit starts with 500 µs high pulse. The length of the following low state decides if this is 1 (2000 µs) or 0 (1000 µs). There is a 4000 µs long low state period before every 36 bits.

How it works

The program is written in C++. It supports the new block device GPIO subsystem. It uses libgpiod C library for I/O operations. For MQTT communication Mosquitto client libmosquittpp is linked. INI file parsing with the help of https://github.com/jtilly/inih.

One input pin is used to read data from 433 MHz receiver. Any pin can be used for this operation. There is no requirement the pin supports events.

The state of the pin is probed to detect valid frames. When 36 bits are read the data is converted to JSON and pushed to MQTT broker. In addition, the program tracks when a new transmitter is detected and when the transmitter becomes silent. This information is also pushed to MQTT.

New transmitters can be automatically detected by the popular home automation system Home Assistant.

Standard operations

Nexus protocol does not offer any way to check if the frame was received properly. The software accepts data from the sensor only when the minimum 2 valid frames were received. A valid frame is when temperature and humidity values are reasonable and fixed 4 bits are set to 1.

All sensor data is sent as one JSON package in topic nexus433/sensor/XXXX/state when XXXX is a unique transmitter ID made of MAC address, ID (first byte), and channel number (second byte) in hex format. For example ae01 means transmitter with id 0xAE and channel 2 (channels are 0 based).

In addition, when the transmitter first sends data program sends online on topic nexus433/sensor/XXXX/connection. If there is no data from the sensor for 90 seconds, the program sends offline to the same topic.

When the program starts and stops it sends online or offline to the global connection topic: nexus433/[MAC]/connection.

For newly detected transmitters specially formatted JSON data is sent to homeassistant topic to make Home Assistant automatically discovers the sensor. For one transmitter 4 sensors are created: temperature, humidity, battery, and quality.

Battery value is either 100 (normal) or 0 (low). These values are compatible with Home Assistant battery class. They can be changed in the configuration file.

Quality is the percentage of received frames. 100% is when all 12 frames are received.

Configuration

Command line options

| Short | Long              | Description | |-------|------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | | --verbose | Enable verbose mode. More information is printed on the screen. | | | --daemon | Run in daemon mode. The program works in the background without a console. When verbose mode is on, it will prints messages. | | -g | --config | Path to configuration file. Configuration options from the file got higher priority than command line options. The default config file is /usr/local/etc/nexus433.ini. | | -c | --chip | GPIO chip device name, by default /dev/gpiochip0. | | -n | --pin | Pin number to use from specified GPIO chip, default 1. This is not a physical pin number but a number assigned by the block device GPIO. See the discussion below for more info. | | -a | --address | MQTT broker host, default 127.0.0.1. | | -p | --port | MQTT port number, default 1883. | | -h | --help | Displays help message. |

Port number and GPIO chip name

Pin numbers are assigned by the block GPIO device driver. To see available lines you can use gpioinfo utility from the libgpiod library.

Raspberry Pi

Only one GPIO device is available /dev/gpiochip0. Pin numbers are the same as GPIO line numbers, for example, physical pin 11 is GPIO17. Pin number for that line is 17.

Orange Pi

Boards based on Allwinner H3 chip got 2 I/O devices:

1. /dev/gpiochip0 with 223 I/O lines
2. /dev/gpiochip1 with 32 I/O lines

Port PA lines are assigned to 0–7, PBB to 8–15, and so on. PL port is the first assigned to chip number 2.

Configuration file

Thanks to the configuration file you can alter the way the program behaves. The file is a typical INI file divided into sections. Every section got its configuration keys.

By default, the program tries to open /usr/local/etc/nexus433.ini file. This location can be changed using -g/--config command line option.

Strings must be entered without " characters. Boolean values accepted: true/false, yes/no, 1/0. Comments must begin with ;.

`[transmi