decoders/lm75/lm75.py

   1 ##
   2 ## This file is part of the sigrok project.
   3 ##
   4 ## Copyright (C) 2012 Uwe Hermann <uwe@hermann-uwe.de>
   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 # National LM75 (and compatibles) temperature sensor protocol decoder
  22
  23 # TODO: Better support for various LM75 compatible devices.
  24
  25 import sigrokdecode as srd
  26
  27 # LM75 only supports 9 bit resolution, compatible devices usually 9-12 bits.
  28 resolution = {
  29     # CONFIG[6:5]: <resolution>
  30     0x00: 9,
  31     0x01: 10,
  32     0x02: 11,
  33     0x03: 12,
  34 }
  35
  36 ft = {
  37     # CONFIG[4:3]: <fault tolerance setting>
  38     0x00: 1,
  39     0x01: 2,
  40     0x02: 4,
  41     0x03: 6,
  42 }
  43
  44 class Decoder(srd.Decoder):
  45     api_version = 1
  46     id = 'lm75'
  47     name = 'LM75'
  48     longname = 'National LM75'
  49     desc = 'National LM75 (and compatibles) temperature sensor protocol.'
  50     license = 'gplv2+'
  51     inputs = ['i2c']
  52     outputs = ['lm75']
  53     probes = []
  54     optional_probes = [
  55         {'id': 'os', 'name': 'OS', 'desc': 'Overtemperature shutdown'},
  56         {'id': 'a0', 'name': 'A0', 'desc': 'I2C slave address input 0'},
  57         {'id': 'a1', 'name': 'A1', 'desc': 'I2C slave address input 1'},
  58         {'id': 'a2', 'name': 'A2', 'desc': 'I2C slave address input 2'},
  59     ]
  60     options = {
  61         'sensor': ['Sensor type', 'lm75'],
  62         'resolution': ['Resolution', 9], # 9-12 bit, sensor/config dependent
  63     }
  64     annotations = [
  65         ['Celsius', 'Temperature in degrees Celsius'],
  66         ['Kelvin', 'Temperature in degrees Kelvin'],
  67         ['Text (verbose)', 'Human-readable text (verbose)'],
  68         ['Text', 'Human-readable text'],
  69         ['Warnings', 'Human-readable warnings'],
  70     ]
  71
  72     def __init__(self, **kwargs):
  73         self.state = 'IDLE'
  74         self.reg = 0x00 # Currently selected register
  75         self.databytes = []
  76         self.mintemp = 0
  77         self.maxtemp = 0
  78         self.avgtemp = 0
  79
  80     def start(self, metadata):
  81         # self.out_proto = self.add(srd.OUTPUT_PROTO, 'lm75')
  82         self.out_ann = self.add(srd.OUTPUT_ANN, 'lm75')
  83
  84     def report(self):
  85         # TODO: Output min/max/avg temperature.
  86         pass
  87
  88     def putx(self, data):
  89         # Helper for annotations which span exactly one I2C packet.
  90         self.put(self.ss, self.es, self.out_ann, data)
  91
  92     def putb(self, data):
  93         # Helper for annotations which span a block of I2C packets.
  94         self.put(self.block_start, self.block_end, self.out_ann, data)
  95
  96     def warn_upon_invalid_slave(self, addr):
  97         # LM75 and compatible devices have a 7-bit I2C slave address where
  98         # the 4 MSBs are fixed to 1001, and the 3 LSBs are configurable.
  99         # Thus, valid slave addresses (1001xxx) range from 0x48 to 0x4f.
 100         if addr not in range(0x48, 0x4f + 1):
 101             s = 'Warning: I2C slave 0x%02x not an LM75 compatible sensor.'
 102             self.putx([4, [s % addr]])
 103
 104     def output_temperature(self, s):
 105         # TODO: Support for resolutions other than 9 bit.
 106         before, after = self.databytes[0], (self.databytes[1] >> 7) * 5
 107         celsius = float('%d.%d' % (before, after))
 108         kelvin = celsius + 273.15
 109         self.putb([0, ['%s: %.1f °C' % (s, celsius)]])
 110         self.putb([1, ['%s: %.1f °K' % (s, kelvin)]])
 111
 112         # Keep some statistics. Can be output in report(), for example.
 113         if celsius < self.mintemp:
 114             self.mintemp = celsius
 115         if celsius > self.maxtemp:
 116             self.maxtemp = celsius
 117         # TODO: avg. temp.
 118
 119     def handle_temperature_reg(self, b, s):
 120         # Common helper for the temperature/T_HYST/T_OS registers.
 121         if len(self.databytes) == 0:
 122             self.block_start = self.ss
 123             self.databytes.append(b)
 124             return
 125         self.databytes.append(b)
 126         self.block_end = self.es
 127         self.output_temperature(s)
 128         self.databytes = []
 129
 130     def handle_reg_0x00(self, b):
 131         # Temperature register (16bits, read-only).
 132         self.handle_temperature_reg(b, 'Temperature')
 133
 134     def handle_reg_0x01(self, b):
 135         # Configuration register (8 bits, read/write).
 136         # TODO: Bit-exact annotation ranges.
 137
 138         sd = b & (1 << 0)
 139         tmp = 'normal operation' if (sd == 0) else 'shutdown mode'
 140         s = 'SD = %d: %s\n' % (sd, tmp)
 141         s2 = 'SD = %s, ' % tmp
 142
 143         cmp_int = b & (1 << 1)
 144         tmp = 'comparator' if (cmp_int == 0) else 'interrupt'
 145         s += 'CMP/INT = %d: %s mode\n' % (cmp_int, tmp)
 146         s2 += 'CMP/INT = %s, ' % tmp
 147
 148         pol = b & (1 << 2)
 149         tmp = 'low' if (pol == 0) else 'high'
 150         s += 'POL = %d: OS polarity is active-%s\n' % (pol, tmp)
 151         s2 += 'POL = active-%s, ' % tmp
 152
 153         bits = (b & ((1 << 4) | (1 << 3))) >> 3
 154         s += 'Fault tolerance setting: %d bit(s)\n' % ft[bits]
 155         s2 += 'FT = %d' % ft[bits]
 156
 157         # Not supported by LM75, but by various compatible devices.
 158         if self.options['sensor'] != 'lm75': # TODO
 159             bits = (b & ((1 << 6) | (1 << 5))) >> 5
 160             s += 'Resolution: %d bits\n' % resolution[bits]
 161             s2 += ', resolution = %d' % resolution[bits]
 162
 163         self.putx([2, [s]])
 164         self.putx([3, [s2]])
 165
 166     def handle_reg_0x02(self, b):
 167         # T_HYST register (16 bits, read/write).
 168         self.handle_temperature_reg(b, 'T_HYST trip temperature')
 169
 170     def handle_reg_0x03(self, b):
 171         # T_OS register (16 bits, read/write).
 172         self.handle_temperature_reg(b, 'T_OS trip temperature')
 173
 174     def handle_reg_write(self, b):
 175         # TODO
 176         self.putx([0, ['LM75 write: reg 0x%02x = 0x%02x' % (self.reg, b)]])
 177
 178     def decode(self, ss, es, data):
 179         cmd, databyte = data
 180
 181         # Store the start/end samples of this I2C packet.
 182         self.ss, self.es = ss, es
 183
 184         # State machine.
 185         if self.state == 'IDLE':
 186             # Wait for an I2C START condition.
 187             if cmd != 'START':
 188                 return
 189             self.state = 'GET SLAVE ADDR'
 190         elif self.state == 'GET SLAVE ADDR':
 191             # Wait for an address read/write operation.
 192             if cmd == 'ADDRESS READ':
 193                 self.warn_upon_invalid_slave(databyte)
 194                 self.state = 'READ REGS'
 195             elif cmd == 'ADDRESS WRITE':
 196                 self.state = 'WRITE REGS'
 197         elif self.state == 'READ REGS':
 198             if cmd == 'DATA READ':
 199                 handle_reg = getattr(self, 'handle_reg_0x%02x' % self.reg)
 200                 handle_reg(databyte)
 201             elif cmd == 'STOP':
 202                 # TODO: Any output?
 203                 self.state = 'IDLE'
 204             else:
 205                 # self.putx([0, ['Ignoring: %s (data=%s)' % (cmd, databyte)]])
 206                 pass
 207         elif self.state == 'WRITE REGS':
 208             if cmd == 'DATA WRITE':
 209                 self.handle_reg_write(databyte)
 210             elif cmd == 'STOP':
 211                 # TODO: Any output?
 212                 self.state = 'IDLE'
 213             else:
 214                 # self.putx([0, ['Ignoring: %s (data=%s)' % (cmd, databyte)]])
 215                 pass
 216         else:
 217             raise Exception('Invalid state: %s' % self.state)
 218