decoders/rfm12/pd.py

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