Bugfixes
[rtl-433.git] / include / pulse_demod.h
1 /**
2  * Pulse demodulation functions
3  * 
4  * Binary demodulators (PWM/PPM/Manchester/...) using a pulse data structure as input
5  *
6  * Copyright (C) 2015 Tommy Vestermark
7  * This program is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 2 of the License, or
10  * (at your option) any later version.
11  */
12
13 #ifndef INCLUDE_PULSE_DEMOD_H_
14 #define INCLUDE_PULSE_DEMOD_H_
15
16 #include <stdint.h>
17 #include "pulse_detect.h"
18 #include "rtl_433.h"
19
20
21 /// Demodulate a Pulse Code Modulation signal
22 ///
23 /// Demodulate a Pulse Code Modulation (PCM) signal where bit width
24 /// is fixed and each bit starts with a pulse or not. It may be either
25 /// Return-to-Zero (RZ) encoding, where pulses are shorter than bit width
26 /// or Non-Return-to-Zero (NRZ) encoding, where pulses are equal to bit width
27 /// The presence of a pulse is:
28 /// - Presence of a pulse equals 1
29 /// - Absence of a pulse equals 0
30 /// @param device->short_limit: Nominal width of pulse [us]
31 /// @param device->long_limit:  Nominal width of bit period [us]
32 /// @param device->reset_limit: Maximum gap size before End Of Message [us].
33 /// @return number of events processed
34 int pulse_demod_pcm(const pulse_data_t *pulses, struct protocol_state *device);
35
36
37 /// Demodulate a Pulse Position Modulation signal
38 ///
39 /// Demodulate a Pulse Position Modulation (PPM) signal consisting of pulses with variable gap.
40 /// Pulse width may be fixed or variable.
41 /// Gap between pulses determine the encoding:
42 /// - Short gap will add a 0 bit
43 /// - Long  gap will add a 1 bit
44 /// @param device->short_limit: Threshold between short and long gap [us]
45 /// @param device->long_limit:  Maximum gap size before new row of bits [us]
46 /// @param device->reset_limit: Maximum gap size before End Of Message [us].
47 /// @return number of events processed
48 int pulse_demod_ppm(const pulse_data_t *pulses, struct protocol_state *device);
49
50
51 /// Demodulate a Pulse Width Modulation signal
52 ///
53 /// Demodulate a Pulse Width Modulation (PWM) signal consisting of short and long high pulses.
54 /// Gap between pulses may be of fixed size or variable (e.g. fixed period)
55 /// - Short pulse will add a 1 bit
56 /// - Long  pulse will add a 0 bit
57 /// @param device->short_limit: Threshold between short and long pulse [us]
58 /// @param device->long_limit:  Maximum gap size before new row of bits [us]
59 /// @param device->reset_limit: Maximum gap size before End Of Message [us].
60 /// @param device->demod_arg = 0: Do not remove any startbits
61 /// @param device->demod_arg = 1: First bit in each message is considered a startbit and not stored in bitbuffer
62 /// @return number of events processed
63 int pulse_demod_pwm(const pulse_data_t *pulses, struct protocol_state *device);
64
65
66 /// Parameters for pulse_demod_pwm_precise
67 typedef struct {
68         int     pulse_sync_width;               // Width of a sync pulse [samples] (optional, ignored if 0)
69         int     pulse_tolerance;                // Tolerance of pulse widths [samples]
70 } PWM_Precise_Parameters;
71
72
73 /// Demodulate a Pulse Width Modulation signal with precise timing
74 ///
75 /// Demodulate a Pulse Width Modulation (PWM) signal consisting of short and long high pulses.
76 /// Gap between pulses may be of fixed size or variable (e.g. fixed period)
77 /// - Short pulse will add a 1 bit
78 /// - Long  pulse will add a 0 bit
79 /// - Sync  pulse will add a new row to bitbuffer
80 /// @param device->short_limit: Width in samples of '1' [us]
81 /// @param device->long_limit:  Width in samples of '0' [us]
82 /// @param device->reset_limit: Maximum gap size before End Of Message [us].
83 /// @param device->demod_arg: pointer to PWM_Precise_Parameters
84 /// @return number of events processed
85 int pulse_demod_pwm_precise(const pulse_data_t *pulses, struct protocol_state *device);
86
87
88 /// Demodulate a Pulse Width Modulation signal with three pulse widths
89 ///
90 /// Demodulate a Pulse Width Modulation (PWM) signal consisting of short, middle and long high pulses.
91 /// Gap between pulses may be of fixed size or variable (e.g. fixed period)
92 /// The sync bit will add a new row to the bitbuffer
93 /// @param device->short_limit: Threshold between short and middle pulse [us]
94 /// @param device->long_limit:  Threshold between middle and long pulse [us]
95 /// @param device->reset_limit: Maximum gap size before End Of Message [us].
96 /// @param device->demod_arg = 0: Short pulse is sync, middle is 0, long is 1
97 /// @param device->demod_arg = 1: Short pulse is 0, middle is sync, long is 1
98 /// @param device->demod_arg = 2: Short pulse is 0, middle is 1, long is sync
99 /// @return number of events processed
100 int pulse_demod_pwm_ternary(const pulse_data_t *pulses, struct protocol_state *device);
101
102
103 /// Demodulate a Manchester encoded signal with a hardcoded zerobit in front
104 ///
105 /// Demodulate a Manchester encoded signal where first rising edge is counted as a databit 
106 /// and therefore always will be zero (Most likely a hardcoded Oregon Scientific peculiarity)
107 ///
108 /// Clock is recovered from the data based on pulse width. When time since last bit is more 
109 /// than 1.5 times the clock half period (short_width) it is declared a data edge where:
110 /// - Rising edge means bit = 0
111 /// - Falling edge means bit = 1
112 /// @param device->short_limit: Nominal width of clock half period [us]
113 /// @param device->long_limit:  Not used
114 /// @param device->reset_limit: Maximum gap size before End Of Message [us].
115 /// @return number of events processed
116 int pulse_demod_manchester_zerobit(const pulse_data_t *pulses, struct protocol_state *device);
117
118
119 /// No level shift within the clock cycle translates to a logic 0
120 /// One level shift within the clock cycle translates to a logic 1
121 /// Each clock cycle begins with a level shift
122 ///
123 /// +---+   +---+   +-------+       +  high
124 /// |   |   |   |   |       |       |
125 /// |   |   |   |   |       |       |
126 /// +   +---+   +---+       +-------+  low
127 ///
128 /// ^       ^       ^       ^       ^  clock cycle
129 /// |   1   |   1   |   0   |   0   |  translates as
130 ///
131 /// @param device->short_limit: Width in samples of '1' [us]
132 /// @param device->long_limit:  Width in samples of '0' [us]
133 /// @param device->reset_limit: Maximum gap size before End Of Message [us].
134 /// @param device->demod_arg: pointer to PWM_Precise_Parameters (only pulse_tolerance used)
135 /// @return number of events processed
136 int pulse_demod_clock_bits(const pulse_data_t *pulses, struct protocol_state *device);
137
138
139 int pulse_demod_osv1(const pulse_data_t *pulses, struct protocol_state *device);
140
141 #endif /* INCLUDE_PULSE_DEMOD_H_ */