Protocol decoder:ook

From sigrok
Revision as of 12:16, 19 June 2018 by SteveR (talk | contribs) (fixed formatting of Output, tweaked sigrok-cli examples and tidied up Resource links)
Jump to navigation Jump to search
ook
Ook.png
Name On Off Keying
Description Decodes On Off Keying waveforms which are frequently used for remote control protocols
Status possible candidate
License GPLv2+
Source code decoders/ook
Input logic
Output ook
Probes none
Optional probes —
Options invert, decodeas, preamble, preamlen, diffmanvar

The ook protocol decoder takes a logic level input and decodes NRZ, Manchester and Differential Manchester encoding.

It decodes based on sample lengths rather than on sampling rate or inter pulse delays, so should be capable of decoding a variety of signals.

Getting a signal to Analyse

There are two main ways of getting a signal to decode. Opening up the device and attaching the probes from a logic analyser directly to the logic level signal (if you can find and safely connect to it) or using a receiver to demodulate the Radio Frequency (RF) signal to recover the logic level signal.

Opening up the device is going to get you the cleanest signal but carries the risk of breaking the device and any warranty.

Using a demodulator is much lower risk but comes with its own challenges which mainly resolve around the extra noise and other signals that the RF receiver picks up that are nothing to do with the signal that you are interested in. If another device transmits at the same time as the wanted signal then the two will interfere with each other and add up to a mangled mess. Similarly if something creates noise at the same time as the wanted signal then there are going to be some holes in it. One coping strategy is to take a decent number of samples and hopefully get one that is clean.

Sigrok has a very useful feature that allows the cursors in PulseView to be used to highlight part of the waveform and "Save Selected Range As" to manually cut out a useful signal from the noise and other signals around it. Important when using this feature make sure that you leave at least five times the preamble period on the end of the signal or the stacked decoders will not get triggered.

In an ideal world the decoder would be able to do the manual identification for you and chop the garbage out too. There are a couple of extra things that have been built into this decoder that will try and improve your chances of getting a good result from a less than ideal waveform. Good electrical design and layout of the receiver are major factors too.

How it works

The ook decoder assumes that the signal that it needs to decode will have a square wave preamble which can be analysed to work out the original clock period (in samples) which it needs to recover the sending clock and decode the signal. Note that it does not look for specific inter pulse times which would limit what it could decode.

It is important to make sure that the preamble is correctly identified and that the decoder doesn't try and use random noise or other garbage as the preamble.

To give the demodulator option a better chance of working from the output of an RF receiver, this decoder contains some garbage removal code. The code requires 7 pulses (adjustable from 3 to 10) in a row that have lengths within a factor of 5 of each other before it will start decoding. This is designed to reject random background noise and noise which is created by the way that RF receivers work.

If garbage removal and Advanced clock recovery (see below) are not needed then these features can be totally disabled by selecting a preamlen of '0'. Don't disable this feature unless you are opening up the device and attaching the probes from a logic analyser directly to the logic level signal.

A genuine preamble will pass intact through the garbage filter.

Only decoding from a genuine preamble does several good things, it reduces the work that the higher levels have to do and it frames the wanted signals.

At the end of receiving a good signal the super regenerative RF receivers go low for a few hundred milliseconds. This is a useful marker to spot when looking at captured waveforms. Find the blanks and go backwards to the signal and its preamble.

The decoder imitates this behaviour to detects the end of each set of pulses by looking for a low for five times the preamble period. Once the decode has timed out the resulting OOK pattern is sent up the stack to the higher level decoders and the decoder is reset ready for the next set of pulses which may be from a completely different device.

Advanced Clock Recovery

The example waveforms in the articles in the Resources section below all use a clock that is a pure square wave (50:50 mark/space) which have equal high and low times. It makes it much easier to understand what is going on and also makes it easier to decode at the other end.

Decoding is based upon spotting long and short pulses, so its essential to recover the clock accurately to work out what is a long and short pulse.

In real life the ideal square wave preamble doesn't always happen and the signal can frequently end up skewed with significantly longer on than off periods or vice versa. This makes some devices much harder to see and decode than others. The RF decoder chosen will have a significant effect too.

This decoder copes with the problem by treating the clock high and low reference lengths independently. It looks at the preamble and if the preamble is skewed then it assumes that the signal will be too and compensates by comparing high pulses with the high reference and low pulses with the low reference.

Decoder

The ook decoder has the following options and defaults 

   invert - Yes/No - default No
   decodeas - Manchester/Differential Manchester/NRZ - Decode As - default Manchester
   preamble - '1010 ...'/'1111 ...' - Preamble pattern - default '1111 ...' 
   preamlen - 0/3/4/5/6/7/8/9/10 - Preamble filter length - default 7 - 0 turns it off
   diffmanver - 1/0 Differential Manchester - transition at start is a - default 1

Manchester encoding

This can send a 50:50 mark/space square wave to transmit a signal that is '1111 ...' or '1010 ...'. In one case the pulse samples represent the clock period in the other only half. Which one was intended cannot be easily detected by the receiver, so there is an option for the user to make the choice. Making the right choice should remove most of the decoding errors.

There are also two variants, as per G.E Thomas and IEEE 802.3 These are the opposite way up to each other. The default here is IEEE 802.3 but the option is there to invert the result and comply with G.E Thomas. The diffmanver option will be ignored as it only applies to Differential Manchester decoding.

Differential Manchester encoding

Again there are two options, to treat a transition at the start of the clock cycle as a 1 or 0 and no transition as a 0 or 1. The default is to treat a transition as a 1 and no transition as a 0. Note. Inverting a Differential Manchester signals does nothing, so although the invert option does work here, it won't effect the result. The preamble pattern only applies to Manchester encoding and is ignored inside this decoder.

NRZ

Or Binary Encoding as it is called in Computer Networks 2nd Edition - Andrew S. Tannenbaum only has one option which is invert The decodeas, preamble and diffmanver options are ignored.

Output

The results of decoding each bit can be 

'0'   zero (low)
'1'   one (high)
'E'   Error (invalid)

Error bits can be caused by missing transitions or the wrong pulse lengths according to the rules for the particular encoding. In some cases this is intentional (Oregon v1 preamble) and is part of the sync pattern. In other cases the signal could simply be broken.

If you get large numbers of 'E's then you are probably using the wrong decoder, using the wrong options with the right decoder, there is simply too much noise or more rarely the sample rate is too low for the decoder to work properly. The ideal sample rate is 50 to 100 times higher than the preamble clock and becomes more of an issue with badly skewed signals.

sigrok-cli examples

You can show the available options with the --show command: 

$ sigrok-cli -P ook --show

To use ook to decode a Manchester (default) encoded trace with a preamble starting 1010. 

sigrok-cli -P ook:data=D1:preamble='1010 ...' -i thgr228n.sr

To decode a Manchester (default) encoded trace with a preamble starting 1111 (default) 

sigrok-cli -P ook:data=D0 -i oregon_pcr800.sr

The ook output from the ook decoder can also be stacked with another decoder that accepts ook input such as the Oregon Scientific decoder To decode a Manchester (default) encoded trace with a preamble starting 1010 (Oregon V2.1 sensor) and then pass the result to the oregon decoder and only display the oregon output 

sigrok-cli -P ook:data=D1:preamble='1010 ...',oregon -i thgr228n.sr -A oregon

The ook decoder can optionally display the pulse lengths in micro seconds by using the Binary output switch with an option called "pulse-lengths" 

sigrok-cli -P ook:data=D0,ook_oregon -B ook=pulse-lengths -i oregon_pcr800.sr

Resources

Other interesting articles

Retrieved from "https://sigrok.org/w/index.php?title=Protocol_decoder:Ook&oldid=13576"