Getting Started

This is step-by-step instruction to get a simple initial setup on Raspberry Pi (with notes about other supported platforms). In this instruction it is assumed that you already have ssh access to your Raspberry Pi and have some knowledge about installing/updating software on this platform. This article also provides useful recommendations.

Prerequisites

Platform

The recommended platform is Raspberry Pi 4B but 3B also works fine. The utility is tested on both 3B and 4B.
Metal case is better for 2 reasons:
- CPU may be hot and requires cooling. Metals better conduct heat than plastics.
- The board itself makes a lot of RF noise. Metal case screens this noise. Note that RPi 4B is more powerful but it is also hotter that RPi 3B. You may consider to get a case with fan.
  For example I am running the utility with RPi 4B inside EleDuino Raspberry PI 4 Aluminum Case with Dual Intelligent Temperature Control Fan.

EleDuino Raspberry PI 4 Aluminum Case with Dual Intelligent Temperature Control Fan

Obviously more RAM is better.
The utility is tested on Raspbian OS. It is possible to build it on Ubuntu or other Linux distributions but it is not tested and you may have some difficulties.

Receiver

Currently the utility supports 433.92MHz RF receivers and sensors with ASK/OOK modulation only. Theoretically it may work with other receiver-sensor pairs that use a different frequency if their protocol is compatible with one of supported sensor type. While it is known that some sensors have 315MHz/868MHz/915Mhz clones in different countries but they are not tested.
Receiver RX-RM-5V (it has many clones) is not recommended. It is unreliable. Probably it can be turned but it always has worse reception than other tested receivers.
The utility can work with many receivers but it is carefully tested with RXB6 and SeeedStudio RF-R-ASK only.
- You can buy RXB6 clones from many manufacturers.
- Both these receivers have good reception.
- Both these receivers can be powered with 3V. It means that you can connect them directly to you Raspberry Pi without additional resistors. See an example of wiring RXB6 to Raspberry Pi.
Antenna can be pretty simple. Obviously reception depends on the quality of the antenna but the difference is not dramatic. Actually RXB6 works even without antenna. There is no need to buy it. You can easily make it by yourself. The following antennas are tested:
- 433 MHz Coil Loaded Antenna
- Just simple jumper wire with right length (17.28 cm / 6.80 inch) can also work fine.

Sensors

There are several things that you should take into account.

The utility supports only sensor types that are listed here. Sensors uses different modulations and different ways to encode data. Currently the utility supports receivers with ASK/OOK modulation only. Almost every sensor type uses its unique protocol that is not compatible with other types. At the same time there are sensor types with many clones that can be bought under different brands with or without minor changes. For example, Fine Offset Electronics WH2 and Telldus FT007TH (and many others FT007TH clones) are almost the same and their signal modulation and encoding are the same but their packages are different in one bit.

Some sensors have notion of channels. Actually this is just some field in their RF packages. But it simplifies distinguishing of sensors of the same type. Note that your neighbor may also have sensors of the same type. You can have more sensors in your setup than the number of channels supported by a particular sensor type. It is possible because the utility distinguishes sensors by "rolling code" which is usually 7 or 8 bits. But take into account that rolling code is changed every time you replace sensor's batteries. Then you need to update rolling codes in the utility configuration. The channel number is set by dip switches on the sensor itself. In any case the number of supported channels is very limited.

Sensor type	Number of channels
AcuRite 00592TXR	3 (A,B,C)
Ambient Weather F007TH/F007TP	8 (1..8)
Auriol HG02832	3 (1..3)
LaCrosse TX3/TX6/TX7	No channels
LaCrosse TX141TH	up to 4 (1..4)
Fine Offset Electronics WH2	No channels
Telldus FT007TH	No channels
TFA Twin Plus 30.3049 / Conrad KW9010 / Ea2 BL999	3 (1..3)

Of course reliability and distance of reception is very important. There is my personal opinion about supported sensors:
- AcuRite 00592TXR sends data very frequently (probably every 15 seconds) and it can be received from longer distance. For example, I receive data from outside sensor of my neighbor and I don't even know where it is located.
- Ambient Weather F007TH sends data about once per minute and has good signal quality. The range is probably worse than AcuRite 00592TXR but it is still good. Sometimes I receive data from sensor F007TP which is probably in a pool of one of my neighbor. I currently have 9 F007TH sensors at my house.
- LaCrosse TX7U works fine after I fixed checksum comparison. It sends temperature and humidity in separate packages and repeat them several times. Cannot tell anything about its range.
- LaCrosse TX141TH-BV3 works fine and reliable. It sends temperature and humidity in every 55sec. Its signal can be received from long distance (up to 300ft/90m).
- I have never owned Fine Offset Electronics WH2 and Telldus FT007TH. Their support was implemented and tested with help of a user who owns them. It works for the user but I have never even seen them.
- TFA Twin Plus 30.3049 (also known as Conrad KW9010 or Ea2 BL999) works fine. It sends packages about once per minute and repeated it 3 times. Theoretically this sensor supports 3 channels but I could not find how to change the channel. It has have 6-bit rolling code that is changed when its battery is changed. Cannot tell anything about its range.

Setup

The following steps are for a simple configuration without support of MQTT and pushing data to REST service or InfluxDB. If you need them then you can improve your setup later.
For example, if you want to enable MQTT support (this is not usual) then please read this special instruction.

In this instruction we assume that the utility will be created in folder f007th-rpi in user home directory. Of course you can do it in any other directory but you will need to change some commands.

Choose running mode

You can run one of 2 executables on Raspberry Pi:

f007th-rpi_send uses pigpio library
- This executable requires pigpio library to be installed.
- Security concern This executable must be run as root (via sudo).
- Performance concern The accuracy of timestamping of level changes is extremely important for correct decoding of RF data. In this mode timestamps are taken in exception handlers in this utility. As result the precision highly depends on system load and CPU performance. In general decoding is worse in this mode.
- Performance concern This executable creates more load on the system than f007th-send.
- Security concern The utility may execute commands specified in its configuration (action rules and MQTT rules). Note that these commands currently are executed under the same account as the utility itself. It means that they are executed as root.
- Security concern It is always not a good idea run as root an application that serves HTTP requests. The utility uses open-source library microhttpd that potentially may have security issues.
f007th-send is the same as above but uses gpio-ts driver.
- This executable does not require root privileges but gpio-ts module must be already loaded. It can be loaded during system boot or by a command at any time.
- Maintenance concern The driver has to be re-built every time you upgrade Linux kernel. Otherwise it may fail to load. Unfortunately it cannot be fixed because this is how Linux kernel works with drivers.
- The driver processes exceptions in kernel mode and takes timestamps with better precision. It also does noise filtering and that significantly reduces amount of data to be processed by the utility. As result the created total load on the system is lower in this mode.
- This mode is used on my "production" setup at home. As result it is better tested.

This is your choice but it is recommended to use the second executable (f007th-send with gpio-ts driver).

Building gpio-ts driver

This step is only required if you decided to run the utility with gpio-ts driver.

Please follow steps from chapter How to build of the driver's README file.

Note: You have to rebuild the driver every time you update/upgrade Linux kernel. Otherwise the driver may fail to load.

Building the utility

You need to install libcurl and microhttpd libraries:

sudo apt-get update
sudo apt-get install libcurl4-openssl-dev libmicrohttpd-dev

If you want to use pigpio library then you need to install it. Note: It is recommended do not use pigpio but use gpio-ts driver. The driver works better and creates less load to Raspberry Pi CPU.
```
sudo apt-get install pigpio
```
Install git if it is not installed on your system.
```
sudo apt-get install git
```
You may need to take additional steps to configure your git setup.
Clone sources from GitHub.
The following commands will change the current directory to user's home directory then create new folder f007th-rpi and download sources from GitHub:
```
cd ~
git clone https://github.com/alex-konshin/f007th-rpi.git
```
Build binaries
```
/bin/bash f007th-rpi/build.sh
```
Executables are created in directory f007th-rpi/bin.

Re-building or updating the utility

If you later will need to update/upgrade the utility with newest changes then you just have to do the following:

Make sure that the utility is not running.
Use command pkill f007th-send (or pkill f007th-rpi_send if you run this executable) to stop the utility.
You can check that the utility is running by command pgrep f007th-send (or pgrep f007th-rpi_send if you use this executable).
Update your Git repository.
```
cd ~/f007th-rpi
git pull
```
Re-build binaries
```
/bin/bash f007th-rpi/build.sh
```
Executables will be copied in folder ~/f007th-rpi/bin
If something went wrong then it is better to build the utility from scratch:
- Don't forget to copy your configuration files to some other directory if they are located in ~/f007th-rpi.
- Go to your home directory cd ~
- Delete the folder with command rm -R ~/f007th-rpi
- Re-clone sources with command git clone https://github.com/alex-konshin/f007th-rpi.git
- Re-build binaries with command /bin/bash f007th-rpi/build.sh
- Restore your configuration file.

First start of the utility

Load gpio-ts driver if you decided to run the utility with gpio-ts driver and if it has not been already loaded.
See more detailed instruction in gpio-ts project.
```
sudo insmod gpio-ts.ko gpios=27
```
Start the utility with enabled HTTP server. In the following command port 8888 will be assigned to built-in HTTP server:
- with gpio-ts driver:
```
~/f007th-rpi/bin/f007th-send -C -A --httpd=8888
```
- with pigpio library:
```
sudo ~/f007th-rpi/bin/f007th-rpi_send -C -A --httpd=8888
```
You should observe some output on console.

! This instruction is not finished yet

Get rolling codes of your sensors. You will need them to define your sensors in the configuration file.

You can find them in console output of the utility. But it is not very convenient if you have many sensors.
Open page http://<host>:8888/api/sensors in your favorite web browser on any machine on your local network. Just replace <host> with your RPi host name or IP address. You will get JSON with the list of all sensors which data has been received and decoded. For example:

[
{"time":"2020-12-24 13:49:16-0500","type":"F007TH","channel":"5","rolling_code":174,"name":"Kitchen","temperature":718,"humidity":26,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:51:27-0500","type":"00592TXR","channel":"A","rolling_code":92,"name":"Neighbor 1","temperature":537,"humidity":62,"battery_ok":true,"t_hist":7,"h_hist":2},
{"time":"2020-12-24 13:48:13-0500","type":"F007TH","channel":"1","rolling_code":13,"name":"Server room","temperature":813,"humidity":10,"battery_ok":true,"t_hist":2,"h_hist":2},
{"time":"2020-12-24 13:50:20-0500","type":"F007TH","channel":"4","rolling_code":12,"name":"Alex office","temperature":761,"humidity":26,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:51:52-0500","type":"00592TXR","channel":"A","rolling_code":146,"name":"Backyard","temperature":525,"humidity":69,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:48:20-0500","type":"TX7","rolling_code":104,"name":"Attic TX7U","temperature":681,"t_hist":2},
{"time":"2020-12-24 13:48:22-0500","type":"F007TH","channel":"8","rolling_code":227,"name":"Dining room","temperature":757,"humidity":24,"battery_ok":true,"t_hist":2,"h_hist":2},
{"time":"2020-12-24 13:49:48-0500","type":"F007TH","channel":"8","rolling_code":95,"name":"Dirty room","temperature":606,"humidity":79,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:49:29-0500","type":"F007TH","channel":"3","rolling_code":85,"name":"Roman room","temperature":714,"humidity":32,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:52:05-0500","type":"F007TH","channel":"6","rolling_code":139,"name":"TV room","temperature":708,"humidity":30,"battery_ok":true,"t_hist":3,"h_hist":2},
{"time":"2020-12-24 13:48:57-0500","type":"F007TH","channel":"7","rolling_code":249,"name":"Garage","temperature":526,"humidity":49,"battery_ok":true,"t_hist":2,"h_hist":2},
{"time":"2020-12-24 13:49:00-0500","type":"F007TH","channel":"2","rolling_code":184,"name":"Main bedroom","temperature":710,"humidity":33,"battery_ok":true,"t_hist":2,"h_hist":2}
]

! This instruction is not finished yet

For now please see article Running the utility.

Stopping the utility

You can check that the utility is running by command pgrep f007th-send (or pgrep f007th-rpi_send if you use it).
You can use command pkill f007th-send (or pkill f007th-rpi_send if you run it) to stop the utility.

Configuration file

While it is possible to run utility without configuration file it is highly recommended to create such file. Many utility features can be defined/enabled only in configuration file. For example, currently it is impossible to assign names to sensor but many REST API requests shows information about defined sensors only. As result, the provided sample home page will not be able to list sensors and show graphs.

Copy sample configuration files to bin folder:

cd ~/f007th-rpi
cp sample/f007th-send.cfg bin 
mkdir bin/www
cp sample/www/index.html bin/www

Review and edit configuration file bin/f007th-send.cfg. You can find more information about configuration command in articls Configuration file and Command line arguments.
```
! IMPORTANT: Define your own sensors. Definitions of sensors from the example will not work for you.
```
Note that you will not be able to define any sensor if you don't know their current rolling codes. It is recommended to enable HTTP interface (run the utility with arguments -A --httpd=8888) then after 15...60 minutes open in your favorite web browser the page http://<host>:8888/api/sensors to get the list of known sensors.
```
sensor <type> [<channel>] <rolling_code> <name>
```
Argument name defines an arbitrary name of the sensor. It is printed or sent to server with sensor's data. It can be any word without blanks or any valid quoted string.
Argument <type> could be one of (case insensitive): f007th, f007tp, 00592txr, hg02832, tx6, wh2, ft007th.
Argument <rolling_code> may be decimal number or hex number started with 0x.
Warning: Argument <channel> is not optional: You must specify it if this particular sensor type has channels:
- For sensors of type 00592txr the value of channel is A, B or C.
- For sensors f007th and f007tp it should be a number 1..8.
- For sensors hg02832 it should be a number 1..3.
- For sensors tx141 it should be a number 1..4.
- Sensors TX6/TX7U, WH2, ft007th (do not confuse with f007th) have no channels. They are distinguished by rolling code only.
- Sensors TFA Twin Plus 30.3049 (also known as Conrad KW9010 or Ea2 BL999) have 3 channels but I don't know how to change the channel - I do not see any dip switches. They have 6-bit rolling code.
```
! IMPORTANT: Rolling code is changed every time you disconnect sensor batteries.
! You have to update codes in configuration files after replacing batteries.
```
It is recommended to enable built-in HTTP server with command httpd. It provides an easy way to monitor current temperatures and other values from any web browser that has access to your setup. This functionality does not require installation of any other servers.

Running the utility

Start the utility with the configuration that you just created:

with gpio-ts driver:

~/f007th-rpi/bin/f007th-send -c ~/f007th-rpi/bin/f007th-send.cfg&

with pigpio library:

sudo ~/f007th-rpi/bin/f007th-rpi_send -c ~/f007th-rpi/bin/f007th-send.cfg&

Symbol ampersand (&) at the end of the command means running of the command in background.

! IMPORTANT: The utility may be killed when you exit the shell or close your terminal window.
! You have to run command "disown" to prevent it.

Run command disown to prevent killing of the utility after closing the shell or terminal window:

disown

View the current values with web browser

If you enabled built-in HTTP server then you can use any web browser to view the last received data from defined sensors and graph of temperature for the last 24 hours. Please note that receiving of enough data for drawing graphs takes time and usually requires several hours to get a nice graph like below:
Example of web page

! This instruction is not finished yet

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started

Prerequisites

Platform

Receiver

Sensors

Setup

Choose running mode

Building gpio-ts driver

Building the utility

Re-building or updating the utility

First start of the utility

Stopping the utility

Configuration file

Running the utility

View the current values with web browser

Overview

Getting started

How to build

Running the utility

Support of MQTT

REST API

Clone this wiki locally