rfcontroljs is a node.js module written to parse and construct 433mhz On-off keying (OOK) signals for various devices switches or weather stations.
It works well together with the RFControl Arduino library for receiving the signals.
You can find a list of all supported protocols here.
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 it 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.
We detect possible protocols by two criteria. The pulse length must match with a small tolerance and the pulse count must match.
If a protocol matches, its parse
function is called with the pulse sequence. Most protocols are
parsed almost the same way. First the pulse squence 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
:
pulsesToBinaryMapping = {
'0110': '0' #binary 0
'0101': '1' #binary 1
'02': '' #footer
}
binary = helper.map(pulses, pulsesToBinaryMapping)
The binary reprsentation now looks like this:
110011000010
As last step the protocol dependent information must be extracted from the binary representation:
result = {
houseCode: helper.binaryToNumber(binary, 0, 5)
unitCode: helper.binaryToNumber(binary, 6, 10)
state: helper.binaryToBoolean(binary, 12)
}
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 rfcontroljs
auto merges similar buckets before
calling the decodePulses
function of each protocol.
The algorithm is the following:
rfcontroljs
prepareCompressedPulses
decodePulses
b1*2 < b2
) we merge them to just one bucket by averaging and adapting the pulses in rfcontroljs fixPulses
npm install
inside the cloned directory, so that all dependencies get installed.npm install --global gulp
gulp test
.gulp
let it compile all files and whats for changes. So always keep in running while editing coffee-files.src/protocols
.src/controller.coffee
file to the protocol list.#decodePulses()
test case list in test/lib-controller.coffee
with the data from the arduino (like this one). For the pulseLengths
: strip the zero's at the end and sort them in ascending order, also adapt the pulse
to the changed sorting. [1][1] You can also use this script to convert the output to a valid test input:
controller = require './index.js'
result = controller.prepareCompressedPulses('255 2904 1388 771 11346 0 0 0 0100020002020000020002020000020002000202000200020002000200000202000200020000020002000200020002020002000002000200000002000200020002020002000200020034')
console.log result
result2 = controller.fixPulses(result.pulseLengths, result.pulses)
console.log result2
sample output:
coffee convert.coffee
{ pulseLengths: [ 255, 771, 1388, 2904, 11346 ],
pulses: '0300020002020000020002020000020002000202000200020002000200000202000200020000020002000200020002020002000002000200000002000200020002020002000200020014' }
{ pulseLengths: [ 255, 1079, 2904, 11346 ],
pulses: '0200010001010000010001010000010001000101000100010001000100000101000100010000010001000100010001010001000001000100000001000100010001010001000100010013' }
The second line should be used for protocol developing.