all decoders: introduce a reset() method
[libsigrokdecode.git] / decoders / rfm12 / pd.py
1 ##
2 ## This file is part of the libsigrokdecode project.
3 ##
4 ## Copyright (C) 2014 SÅ‚awek Piotrowski <sentinel@atteo.org>
5 ##
6 ## This program is free software; you can redistribute it and/or modify
7 ## it under the terms of the GNU General Public License as published by
8 ## the Free Software Foundation; either version 2 of the License, or
9 ## (at your option) any later version.
10 ##
11 ## This program is distributed in the hope that it will be useful,
12 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 ## GNU General Public License for more details.
15 ##
16 ## You should have received a copy of the GNU General Public License
17 ## along with this program; if not, see <http://www.gnu.org/licenses/>.
18 ##
19
20 import sigrokdecode as srd
21
22 class Decoder(srd.Decoder):
23     api_version = 3
24     id = 'rfm12'
25     name = 'RFM12'
26     longname = 'RFM12 control protocol'
27     desc = 'HopeRF RFM12 wireless transceiver control protocol.'
28     license = 'gplv2+'
29     inputs = ['spi']
30     outputs = ['rfm12']
31     annotations = (
32         ('cmd', 'Command'),
33         ('params', 'Command parameters'),
34         ('disabled', 'Disabled bits'),
35         ('return', 'Returned values'),
36         ('disabled_return', 'Disabled returned values'),
37         ('interpretation', 'Interpretation'),
38     )
39     annotation_rows = (
40         ('commands', 'Commands', (0, 1, 2)),
41         ('return', 'Return', (3, 4)),
42         ('interpretation', 'Interpretation', (5,)),
43     )
44
45     def __init__(self):
46         self.reset()
47
48     def reset(self):
49         self.mosi_bytes, self.miso_bytes = [], []
50         self.mosi_bits, self.miso_bits = [], []
51         self.row_pos = [0, 0, 0]
52
53         self.ann_to_row = [0, 0, 0, 1, 1, 2]
54
55         # Initialize with Power-On-Reset values.
56         self.last_status = [0x00, 0x00]
57         self.last_config = 0x08
58         self.last_power = 0x08
59         self.last_freq = 0x680
60         self.last_data_rate = 0x23
61         self.last_fifo_and_reset = 0x80
62         self.last_afc = 0xF7
63         self.last_transceiver = 0x00
64         self.last_pll = 0x77
65
66     def advance_ann(self, ann, length):
67         row = self.ann_to_row[ann]
68         self.row_pos[row] += length
69
70     def putx(self, ann, length, description):
71         if not isinstance(description, list):
72             description = [description]
73         row = self.ann_to_row[ann]
74         bit = self.row_pos[row]
75         self.put(self.mosi_bits[bit][1], self.mosi_bits[bit + length - 1][2],
76                  self.out_ann, [ann, description])
77         bit += length
78         self.row_pos[row] = bit
79
80     def describe_bits(self, data, names):
81         i = 0x01 << len(names) - 1
82         bit = 0
83         while i != 0:
84             if names[bit] != '':
85                 self.putx(1 if (data & i) else 2, 1, names[bit])
86             i >>= 1
87             bit += 1
88
89     def describe_return_bits(self, data, names):
90         i = 0x01 << len(names) - 1
91         bit = 0
92         while i != 0:
93             if names[bit] != '':
94                 self.putx(3 if (data & i) else 4, 1, names[bit])
95             else:
96                 self.advance_ann(3, 1)
97             i >>= 1
98             bit += 1
99
100     def describe_changed_bits(self, data, old_data, names):
101         changes = data ^ old_data
102         i = 0x01 << (len(names) - 1)
103         bit = 0
104         while i != 0:
105             if names[bit] != '' and changes & i:
106                 s = ['+', 'Turning on'] if (data & i) else ['-', 'Turning off']
107                 self.putx(5, 1, s)
108             else:
109                 self.advance_ann(5, 1)
110             i >>= 1
111             bit += 1
112
113     def start(self):
114         self.out_ann = self.register(srd.OUTPUT_ANN)
115
116     def handle_configuration_cmd(self, cmd, ret):
117         self.putx(0, 8, ['Configuration command', 'Configuration'])
118         NAMES = [['Internal data register', 'el'], ['FIFO mode', 'ef']]
119
120         bits = (cmd[1] & 0xC0) >> 6
121         old_bits = (self.last_config & 0xC0) >> 6
122         self.describe_bits(bits, NAMES)
123         self.describe_changed_bits(bits, old_bits, NAMES)
124
125         FREQUENCIES = ['315', '433', '868', '915']
126         f = FREQUENCIES[(cmd[1] & 0x30) >> 4] + 'MHz'
127         self.putx(1, 2, ['Frequency: ' + f, f])
128         if cmd[1] & 0x30 != self.last_config & 0x30:
129             self.putx(5, 2, ['Changed', '~'])
130
131         c = '%.1fpF' % (8.5 + (cmd[1] & 0xF) * 0.5)
132         self.putx(1, 4, ['Capacitance: ' + c, c])
133         if cmd[1] & 0xF != self.last_config & 0xF:
134             self.putx(5, 4, ['Changed', '~'])
135
136         self.last_config = cmd[1]
137
138     def handle_power_management_cmd(self, cmd, ret):
139         self.putx(0, 8, ['Power management', 'Power'])
140         NAMES = [['Receiver chain', 'er'], ['Baseband circuit', 'ebb'],
141                  ['Transmission', 'et'], ['Synthesizer', 'es'],
142                  ['Crystal oscillator', 'ex'], ['Low battery detector', 'eb'],
143                  ['Wake-up timer', 'ew'], ['Clock output off switch', 'dc']]
144
145         self.describe_bits(cmd[1], NAMES)
146
147         power = cmd[1]
148
149         # Some bits imply other, even if they are set to 0.
150         if power & 0x80:
151             power |= 0x58
152         if power & 0x20:
153             power |= 0x18
154         self.describe_changed_bits(power, self.last_power, NAMES)
155
156         self.last_power = power
157
158     def handle_frequency_setting_cmd(self, cmd, ret):
159         self.putx(0, 4, ['Frequency setting', 'Frequency'])
160         f = ((cmd[1] & 0xF) << 8) + cmd[2]
161         self.putx(0, 12, ['F = %3.4f' % f])
162         self.row_pos[2] -= 4
163         if self.last_freq != f:
164             self.putx(5, 12, ['Changing', '~'])
165         self.last_freq = f
166
167     def handle_data_rate_cmd(self, cmd, ret):
168         self.putx(0, 8, ['Data rate command', 'Data rate'])
169         r = cmd[1] & 0x7F
170         cs = (cmd[1] & 0x80) >> 7
171         rate = 10000 / 29.0 / (r + 1) / (1 + 7 * cs)
172         self.putx(0, 8, ['%3.1fkbps' % rate])
173         if self.last_data_rate != cmd[1]:
174             self.putx(5, 8, ['Changing', '~'])
175         self.last_data_rate = cmd[1]
176
177     def handle_receiver_control_cmd(self, cmd, ret):
178         self.putx(0, 5, ['Receiver control command'])
179         s = 'interrupt input' if (cmd[0] & 0x04) else 'VDI output'
180         self.putx(0, 1, ['pin16 = ' + s])
181         VDI_NAMES = ['Fast', 'Medium', 'Slow', 'Always on']
182         vdi_speed = VDI_NAMES[cmd[0] & 0x3]
183         self.putx(0, 2, ['VDI: %s' % vdi_speed])
184         BANDWIDTH_NAMES = ['Reserved', '400kHz', '340kHz', '270kHz', '200kHz',
185                            '134kHz', '67kHz', 'Reserved']
186         bandwidth = BANDWIDTH_NAMES[(cmd[1] & 0xE0) >> 5]
187         self.putx(0, 3, ['Bandwidth: %s' % bandwidth])
188         LNA_GAIN_NAMES = [0, -6, -14, -20]
189         lna_gain = LNA_GAIN_NAMES[(cmd[1] & 0x18) >> 3]
190         self.putx(0, 2, ['LNA gain: %ddB' % lna_gain])
191         RSSI_THRESHOLD_NAMES = ['-103', '-97', '-91', '-85', '-79', '-73',
192                                 'Reserved', 'Reserved']
193         rssi_threshold = RSSI_THRESHOLD_NAMES[cmd[1] & 0x7]
194         self.putx(0, 3, ['RSSI threshold: %s' % rssi_threshold])
195
196     def handle_data_filter_cmd(self, cmd, ret):
197         self.putx(0, 8, ['Data filter command'])
198         if cmd[1] & 0x80:
199             clock_recovery = 'auto'
200         elif cmd[1] & 0x40:
201             clock_recovery = 'fast'
202         else:
203             clock_recovery = 'slow'
204         self.putx(0, 2, ['Clock recovery: %s mode' % clock_recovery])
205         self.advance_ann(0, 1) # Should always be 1.
206         s = 'analog' if (cmd[1] & 0x10) else 'digital'
207         self.putx(0, 1, ['Data filter: ' + s])
208         self.advance_ann(0, 1) # Should always be 1.
209         self.putx(0, 3, ['DQD threshold: %d' % (cmd[1] & 0x7)])
210
211     def handle_fifo_and_reset_cmd(self, cmd, ret):
212         self.putx(0, 8, ['FIFO and reset command'])
213         fifo_level = (cmd[1] & 0xF0) >> 4
214         self.putx(0, 4, ['FIFO trigger level: %d' % fifo_level])
215         last_fifo_level = (self.last_fifo_and_reset & 0xF0) >> 4
216         if fifo_level != last_fifo_level:
217             self.putx(5, 4, ['Changing', '~'])
218         else:
219             self.advance_ann(5, 4)
220         s = 'one byte' if (cmd[1] & 0x08) else 'two bytes'
221         self.putx(0, 1, ['Synchron length: ' + s])
222         if (cmd[1] & 0x08) != (self.last_fifo_and_reset & 0x08):
223             self.putx(5, 1, ['Changing', '~'])
224         else:
225             self.advance_ann(5, 1)
226
227         if cmd[1] & 0x04:
228             fifo_fill = 'Always'
229         elif cmd[1] & 0x02:
230             fifo_fill = 'After synchron pattern'
231         else:
232             fifo_fill = 'Never'
233         self.putx(0, 2, ['FIFO fill: %s' % fifo_fill])
234         if (cmd[1] & 0x06) != (self.last_fifo_and_reset & 0x06):
235             self.putx(5, 2, ['Changing', '~'])
236         else:
237             self.advance_ann(5, 2)
238
239         s = 'non-sensitive' if (cmd[1] & 0x01) else 'sensitive'
240         self.putx(0, 1, ['Reset mode: ' + s])
241         if (cmd[1] & 0x01) != (self.last_fifo_and_reset & 0x01):
242             self.putx(5, 1, ['Changing', '~'])
243         else:
244             self.advance_ann(5, 1)
245
246         self.last_fifo_and_reset = cmd[1]
247
248     def handle_synchron_pattern_cmd(self, cmd, ret):
249         self.putx(0, 8, ['Synchron pattern command'])
250         if self.last_fifo_and_reset & 0x08:
251             self.putx(0, 8, ['Pattern: 0x2D%02X' % pattern])
252         else:
253             self.putx(0, 8, ['Pattern: %02X' % pattern])
254
255     def handle_fifo_read_cmd(self, cmd, ret):
256         self.putx(0, 8, ['FIFO read command', 'FIFO read'])
257         self.putx(3, 8, ['Data: %02X' % ret[1]])
258
259     def handle_afc_cmd(self, cmd, ret):
260         self.putx(0, 8, ['AFC command'])
261         MODES = ['Off', 'Once', 'During receiving', 'Always']
262         mode = (cmd[1] & 0xC0) >> 6
263         self.putx(0, 2, ['Mode: %s' % MODES[mode]])
264         if (cmd[1] & 0xC0) != (self.last_afc & 0xC0):
265             self.putx(5, 2, ['Changing', '~'])
266         else:
267             self.advance_ann(5, 2)
268
269         range_limit = (cmd[1] & 0x30) >> 4
270         FREQ_TABLE = [0.0, 2.5, 5.0, 7.5]
271         freq_delta = FREQ_TABLE[(self.last_config & 0x30) >> 4]
272
273         if range_limit == 0:
274             self.putx(0, 2, ['Range: No limit'])
275         elif range_limit == 1:
276             self.putx(0, 2, ['Range: +/-%dkHz' % (15 * freq_delta)])
277         elif range_limit == 2:
278             self.putx(0, 2, ['Range: +/-%dkHz' % (7 * freq_delta)])
279         elif range_limit == 3:
280             self.putx(0, 2, ['Range: +/-%dkHz' % (3 * freq_delta)])
281
282         if (cmd[1] & 0x30) != (self.last_afc & 0x30):
283             self.putx(5, 2, ['Changing', '~'])
284         else:
285             self.advance_ann(5, 2)
286
287         NAMES = ['Strobe edge', 'High accuracy mode', 'Enable offset register',
288                  'Enable offset calculation']
289         self.describe_bits(cmd[1] & 0xF, NAMES)
290         self.describe_changed_bits(cmd[1] & 0xF, self.last_afc & 0xF, NAMES)
291
292         self.last_afc = cmd[1]
293
294     def handle_transceiver_control_cmd(self, cmd, ret):
295         self.putx(0, 8, ['Transceiver control command'])
296         self.putx(0, 4, ['FSK frequency delta: %dkHz' % (15 * ((cmd[1] & 0xF0) >> 4))])
297         if cmd[1] & 0xF0 != self.last_transceiver & 0xF0:
298             self.putx(5, 4, ['Changing', '~'])
299         else:
300             self.advance_ann(5, 4)
301
302         POWERS = [0, -2.5, -5, -7.5, -10, -12.5, -15, -17.5]
303         self.advance_ann(0, 1)
304         self.advance_ann(5, 1)
305         self.putx(0,3, ['Relative power: %dB' % (cmd[1] & 0x07)])
306         if (cmd[1] & 0x07) != (self.last_transceiver & 0x07):
307             self.putx(5, 3, ['Changing', '~'])
308         else:
309             self.advance_ann(5, 3)
310         self.last_transceiver = cmd[1]
311
312     def handle_pll_setting_cmd(self, cmd, ret):
313         self.putx(0, 8, ['PLL setting command'])
314         self.advance_ann(0, 1)
315         self.putx(0, 2, ['Clock buffer rise and fall time'])
316         self.advance_ann(0, 1)
317         self.advance_ann(5, 4)
318         NAMES = [['Delay in phase detector', 'dly'], ['Disable dithering', 'ddit']]
319         self.describe_bits((cmd[1] & 0xC) >> 2, NAMES)
320         self.describe_changed_bits((cmd[1] & 0xC) >> 2, (self.last_pll & 0xC) >> 2, NAMES)
321         s = '256kbps, high' if (cmd[1] & 0x01) else '86.2kbps, low'
322         self.putx(0, 1, ['Max bit rate: %s noise' % s])
323
324         self.advance_ann(5, 1)
325         if (cmd[1] & 0x01) != (self.last_pll & 0x01):
326             self.putx(5, 1, ['Changing', '~'])
327
328         self.last_pll = cmd[1]
329
330     def handle_transmitter_register_cmd(self, cmd, ret):
331         self.putx(0, 8, ['Transmitter register command', 'Transmit'])
332         self.putx(0, 8, ['Data: %s' % cmd[1], '%s' % cmd[1]])
333
334     def handle_software_reset_cmd(self, cmd, ret):
335         self.putx(0, 16, ['Software reset command'])
336
337     def handle_wake_up_timer_cmd(self, cmd, ret):
338         self.putx(0, 3, ['Wake-up timer command', 'Timer'])
339         r = cmd[0] & 0x1F
340         m = cmd[1]
341         time = 1.03 * m * pow(2, r) + 0.5
342         self.putx(0, 13, ['Time: %7.2f' % time])
343
344     def handle_low_duty_cycle_cmd(self, cmd, ret):
345         self.putx(0, 16, ['Low duty cycle command'])
346
347     def handle_low_battery_detector_cmd(self, cmd, ret):
348         self.putx(0, 8, ['Low battery detector command'])
349         NAMES = ['1', '1.25', '1.66', '2', '2.5', '3.33', '5', '10']
350         clock = NAMES[(cmd[1] & 0xE0) >> 5]
351         self.putx(0, 3, ['Clock output: %sMHz' % clock, '%sMHz' % clock])
352         self.advance_ann(0, 1)
353         v = 2.25 + (cmd[1] & 0x0F) * 0.1
354         self.putx(0, 4, ['Low battery voltage: %1.2fV' % v, '%1.2fV' % v])
355
356     def handle_status_read_cmd(self, cmd, ret):
357         self.putx(0, 8, ['Status read command', 'Status'])
358         NAMES = ['RGIT/FFIT', 'POR', 'RGUR/FFOV', 'WKUP', 'EXT', 'LBD',
359                  'FFEM', 'RSSI/ATS', 'DQD', 'CRL', 'ATGL']
360         status = (ret[0] << 3) + (ret[1] >> 5)
361         self.row_pos[1] -= 8
362         self.row_pos[2] -= 8
363         self.describe_return_bits(status, NAMES)
364         receiver_enabled = (self.last_power & 0x80) >> 7
365
366         if ret[0] & 0x80:
367             if receiver_enabled:
368                 s = 'Received data in FIFO'
369             else:
370                 s = 'Transmit register ready'
371             self.putx(5, 1, s)
372         else:
373             self.advance_ann(5, 1)
374         if ret[0] & 0x40:
375             self.putx(5, 1, 'Power on Reset')
376         else:
377             self.advance_ann(5, 1)
378         if ret[0] & 0x20:
379             if receiver_enabled:
380                 s = 'RX FIFO overflow'
381             else:
382                 s = 'Transmit register under run'
383             self.putx(5, 1, s)
384         else:
385             self.advance_ann(5, 1)
386         if ret[0] & 0x10:
387             self.putx(5, 1, 'Wake-up timer')
388         else:
389             self.advance_ann(5, 1)
390         if ret[0] & 0x08:
391             self.putx(5, 1, 'External interrupt')
392         else:
393             self.advance_ann(5, 1)
394         if ret[0] & 0x04:
395             self.putx(5, 1, 'Low battery')
396         else:
397             self.advance_ann(5, 1)
398         if ret[0] & 0x02:
399             self.putx(5, 1, 'FIFO is empty')
400         else:
401             self.advance_ann(5, 1)
402         if ret[0] & 0x01:
403             if receiver_enabled:
404                 s = 'Incoming signal above limit'
405             else:
406                 s = 'Antenna detected RF signal'
407             self.putx(5, 1, s)
408         else:
409             self.advance_ann(5, 1)
410         if ret[1] & 0x80:
411             self.putx(5, 1, 'Data quality detector')
412         else:
413             self.advance_ann(5, 1)
414         if ret[1] & 0x40:
415             self.putx(5, 1, 'Clock recovery locked')
416         else:
417             self.advance_ann(5, 1)
418         self.advance_ann(5, 1)
419
420         self.putx(3, 5, ['AFC offset'])
421         if (self.last_status[1] & 0x1F) != (ret[1] & 0x1F):
422             self.putx(5, 5, ['Changed', '~'])
423         self.last_status = ret
424
425     def handle_cmd(self, cmd, ret):
426         if cmd[0] == 0x80:
427             self.handle_configuration_cmd(cmd, ret)
428         elif cmd[0] == 0x82:
429             self.handle_power_management_cmd(cmd, ret)
430         elif cmd[0] & 0xF0 == 0xA0:
431             self.handle_frequency_setting_cmd(cmd, ret)
432         elif cmd[0] == 0xC6:
433             self.handle_data_rate_cmd(cmd, ret)
434         elif cmd[0] & 0xF8 == 0x90:
435             self.handle_receiver_control_cmd(cmd, ret)
436         elif cmd[0] == 0xC2:
437             self.handle_data_filter_cmd(cmd, ret)
438         elif cmd[0] == 0xCA:
439             self.handle_fifo_and_reset_cmd(cmd, ret)
440         elif cmd[0] == 0xCE:
441             self.handle_synchron_pattern_cmd(cmd, ret)
442         elif cmd[0] == 0xB0:
443             self.handle_fifo_read_cmd(cmd, ret)
444         elif cmd[0] == 0xC4:
445             self.handle_afc_cmd(cmd, ret)
446         elif cmd[0] & 0xFE == 0x98:
447             self.handle_transceiver_control_cmd(cmd, ret)
448         elif cmd[0] == 0xCC:
449             self.handle_pll_setting_cmd(cmd, ret)
450         elif cmd[0] == 0xB8:
451             self.handle_transmitter_register_cmd(cmd, ret)
452         elif cmd[0] == 0xFE:
453             self.handle_software_reset_cmd(cmd, ret)
454         elif cmd[0] & 0xE0 == 0xE0:
455             self.handle_wake_up_timer_cmd(cmd, ret)
456         elif cmd[0] == 0xC8:
457             self.handle_low_duty_cycle_cmd(cmd, ret)
458         elif cmd[0] == 0xC0:
459             self.handle_low_battery_detector_cmd(cmd, ret)
460         elif cmd[0] == 0x00:
461             self.handle_status_read_cmd(cmd, ret)
462         else:
463             c = '%02x %02x' % tuple(cmd)
464             r = '%02x %02x' % tuple(ret)
465             self.putx(0, 16, ['Unknown command: %s (reply: %s)!' % (c, r)])
466
467     def decode(self, ss, es, data):
468         ptype, mosi, miso = data
469
470         # For now, only use DATA and BITS packets.
471         if ptype not in ('DATA', 'BITS'):
472             return
473
474         # Store the individual bit values and ss/es numbers. The next packet
475         # is guaranteed to be a 'DATA' packet belonging to this 'BITS' one.
476         if ptype == 'BITS':
477             if mosi is not None:
478                 self.mosi_bits.extend(reversed(mosi))
479             if miso is not None:
480                 self.miso_bits.extend(reversed(miso))
481             return
482
483         # Append new bytes.
484         self.mosi_bytes.append(mosi)
485         self.miso_bytes.append(miso)
486
487         # All commands consist of 2 bytes.
488         if len(self.mosi_bytes) < 2:
489             return
490
491         self.row_pos = [0, 8, 8]
492
493         self.handle_cmd(self.mosi_bytes, self.miso_bytes)
494
495         self.mosi_bytes, self.miso_bytes = [], []
496         self.mosi_bits, self.miso_bits = [], []