Skip to main content

Library with protocol support for different 433MHz switches and weather stations for the RFControl Arduino library.

Project description

Python library rfcontrolpy

Python GitHub Release Licence Maintainer
Github Sponsors PayPal BuyMeCoffee Patreon

Introduction

rfcontrolpy is a Python library and port of the node.js rfcontroljs module for parsing and constructing 433mhz On-Off Keying (OOK) signals for various devices, switches and weather stations.

It works together with the RFControl Arduino library for receiving the signals.

The Python port now contains a working controller and a dozen of protocols. Not all protocols are ported yet due to low demand or lack of hardware.

You can find a list of all supported protocols here.

The Processing Pipeline

Receiving

The arduino is connected via serial bus to the processing computer (for example a raspberry pi) and waits for rf signal.

Mostly all 433mhzw OOK signals from devices are send multiple times directly in row and have a longer footer pulse in between. They differ by the pulse lengths used to encode the data and footer and the pulse count.

RFControl running on the Arduino detects the start of a signal by its longer footer pulse and verifies it one time by comparing it with the next signal. It is unaware of the specific protocol, it just uses the stated fact above. Also we are not interested in it if the pulse was a high or low pulse (presence or absence of a carrier wave), because the information is decoded in the pulse lengths.

We will call the received sequence of pulse lengths now timings sequence. For example a timing sequence in microseconds could look like this:

288  972  292  968  292  972  292  968  292  972  920  344  288  976  920  348  
284  976  288  976  284  976  288  976  288  976  916  348  284  980  916  348  
284  976  920  348  284  976  920  348  284  980  280  980  284  980  916  348  
284  9808

You can clearly see the two different pulse lengths (around 304 and 959 microseconds) for the data encoding and the longer footer pulse (9808 microseconds).

All observed protocols have less than 8 different pulse length and all pulse length do differ by at least a factor of 2. This makes a further compression and simplification possible: We map each pulse length to a number from 0 to 7 (a bucket) and calculate for a better accuracy the average of all timings mapped to each of the bucket. The result is something like that:

buckets: 304, 959, 9808
pulses: 01010101011001100101010101100110011001100101011002

To make the representation unique, we choose the buckets in ascending order (respectively we are sorting it after receiving from the Arduino).

We call the sorted buckets pulse lengths, the compressed timings pulse sequence and the length of the pulse sequence (inclusive footer) pulse count.

Protocol Matching

We detect possible protocols by two criteria. The pulse length must match with a small tolerance and the pulse count must match.

Protocol Parsing

If a protocol matches, its parse function is called with the pulse sequence. Most protocols are parsed almost the same way. First the pulse sequence must be converted to a binary representation.

In almost all cases there exist a mapping from pulse sequences to a binary 0 and 1. In this example the pulse sequence 0110 represents a binary 0 and 0101 maps to a binary 1:

pulses2binary_mapping = {
  ["0110": "0"], # Binary 0
  ["0101": "1"], # Binary 1 
  ["02": ""]     # Footer
}
binary = helpers.pulses2binary(pulses, pulses2binary_mapping)

The binary representation now looks like this:

110011000010

As last step the protocol dependent information must be extracted from the binary representation:

decoded = {
  "id": int(binary[:6], 2),
  "unit": int(binary[6:11], 2),
  "state": binary[12] == "1"
}

Details

RFControl is more sensitive than needed for most protocols. So we get sometimes, depending of the accuracy of the sender/remote, different bucket counts.

This is by design, to catch up further protocols that maybe need a higher sensitivity. The specific protocol has not to deal with this issue, because rfcontrolpy auto merges similar buckets before calling the decodePulses function of each protocol.

The algorithm is the following:

  1. Record the (maybe to many) buckets and compressed pulses with RFControl (Arduino / c++)
  2. Sort the buckets in rfcontrolpy prepare_compressed_pulses
  3. Try to find a matching protocol in rfcontrolpy decode_pulses
  4. If we have more than 3 buckets and two of the buckets are similar (b1*2 < b2) we merge them to just one bucket by averaging and adapting the pulses in rfcontrolpy fix_pulses
  5. Go to step 3

Adding a new Protocol

Preparation

  1. Fork the rfcontrolpy repository and clone your fork into a local directory.
  2. We are using unittest for automating tests.
  3. You should be able to run the tests with python3 -m unittest discover.
  4. Running python3 -m build let it compile all files and whats for changes.

Protocol development

  1. Create a new protocol file (like the others) in rfcontrol/protocols/.
  2. Add a test case in tests/protocols with the data from the Arduino.
  3. Adapt the protocol file, so that the test get passed.

Support my work

Do you enjoy using this Python library? Then consider supporting my work using one of the following platforms, your donation is greatly appreciated and keeps me motivated:

Github Sponsors PayPal BuyMeCoffee Patreon

Hire me

If you're in need for a freelance Python developer for your project please contact me, you can find my email address on my GitHub profile.


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rfcontrolpy-0.0.9.tar.gz (36.5 kB view details)

Uploaded Source

Built Distribution

rfcontrolpy-0.0.9-py3-none-any.whl (42.1 kB view details)

Uploaded Python 3

File details

Details for the file rfcontrolpy-0.0.9.tar.gz.

File metadata

  • Download URL: rfcontrolpy-0.0.9.tar.gz
  • Upload date:
  • Size: 36.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.19

File hashes

Hashes for rfcontrolpy-0.0.9.tar.gz
Algorithm Hash digest
SHA256 5c3e735cf37017fa55909bf071f7ab371d12f83b15c3f075d41c2d8fc1dc7658
MD5 c59742ab3f9cfa9dbd85e1d104dfb679
BLAKE2b-256 c0c9ae37462ecec34093338cd23665c08c7c0da3503137bc13f7f6a0e0f15810

See more details on using hashes here.

File details

Details for the file rfcontrolpy-0.0.9-py3-none-any.whl.

File metadata

  • Download URL: rfcontrolpy-0.0.9-py3-none-any.whl
  • Upload date:
  • Size: 42.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.9.19

File hashes

Hashes for rfcontrolpy-0.0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 d0f042dc79127e21014c7c03a5ef658ac77525a48347184c05ecbd7eee66a685
MD5 6913cd51401e4ad409aa48e996ab416a
BLAKE2b-256 43940bdd2e49431126ebfe8b73004eef3cf63776c36cb5ce5844978ab4043d12

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page