[libsigrokdecode.git] / decoders / lm75 / pd.py

##
## This file is part of the libsigrokdecode project.
##
## Copyright (C) 2012 Uwe Hermann <uwe@hermann-uwe.de>
##
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
##

# National LM75 (and compatibles) temperature sensor protocol decoder

# TODO: Better support for various LM75 compatible devices.

import sigrokdecode as srd

# LM75 only supports 9 bit resolution, compatible devices usually 9-12 bits.
resolution = {
    # CONFIG[6:5]: <resolution>
    0x00: 9,
    0x01: 10,
    0x02: 11,
    0x03: 12,
}

ft = {
    # CONFIG[4:3]: <fault tolerance setting>
    0x00: 1,
    0x01: 2,
    0x02: 4,
    0x03: 6,
}

class Decoder(srd.Decoder):
    api_version = 1
    id = 'lm75'
    name = 'LM75'
    longname = 'National LM75'
    desc = 'National LM75 (and compatibles) temperature sensor.'
    license = 'gplv2+'
    inputs = ['i2c']
    outputs = ['lm75']
    probes = []
    optional_probes = [
        {'id': 'os', 'name': 'OS', 'desc': 'Overtemperature shutdown'},
        {'id': 'a0', 'name': 'A0', 'desc': 'I2C slave address input 0'},
        {'id': 'a1', 'name': 'A1', 'desc': 'I2C slave address input 1'},
        {'id': 'a2', 'name': 'A2', 'desc': 'I2C slave address input 2'},
    ]
    options = {
        'sensor': ['Sensor type', 'lm75'],
        'resolution': ['Resolution', 9], # 9-12 bit, sensor/config dependent
    }
    annotations = [
        ['Celsius', 'Temperature in degrees Celsius'],
        ['Kelvin', 'Temperature in Kelvin'],
        ['Text (verbose)', 'Human-readable text (verbose)'],
        ['Text', 'Human-readable text'],
        ['Warnings', 'Human-readable warnings'],
    ]

    def __init__(self, **kwargs):
        self.state = 'IDLE'
        self.reg = 0x00 # Currently selected register
        self.databytes = []
        self.mintemp = 0
        self.maxtemp = 0
        self.avgvalues = []

    def start(self):
        # self.out_proto = self.add(srd.OUTPUT_PROTO, 'lm75')
        self.out_ann = self.add(srd.OUTPUT_ANN, 'lm75')

    def report(self):
        # TODO: print() or self.put() or return xyz, or... ?
        avg = sum(self.avgvalues) / len(self.avgvalues)
        temperatures = (self.mintemp, self.maxtemp, avg)
        # TODO: Configurable report() output, e.g. for Kelvin.
        return 'Min/max/avg temperature: %f/%f/%f °C' % temperatures

    def putx(self, data):
        # Helper for annotations which span exactly one I2C packet.
        self.put(self.ss, self.es, self.out_ann, data)

    def putb(self, data):
        # Helper for annotations which span a block of I2C packets.
        self.put(self.block_start, self.block_end, self.out_ann, data)

    def warn_upon_invalid_slave(self, addr):
        # LM75 and compatible devices have a 7-bit I2C slave address where
        # the 4 MSBs are fixed to 1001, and the 3 LSBs are configurable.
        # Thus, valid slave addresses (1001xxx) range from 0x48 to 0x4f.
        if addr not in range(0x48, 0x4f + 1):
            s = 'Warning: I2C slave 0x%02x not an LM75 compatible sensor.'
            self.putx([4, [s % addr]])

    def output_temperature(self, s, rw):
        # TODO: Support for resolutions other than 9 bit.
        before, after = self.databytes[0], (self.databytes[1] >> 7) * 5
        celsius = float('%d.%d' % (before, after))
        kelvin = celsius + 273.15
        self.putb([0, ['%s: %.1f °C' % (s, celsius)]])
        self.putb([1, ['%s: %.1f K' % (s, kelvin)]])

        # Warn about the temperature register (0x00) being read-only.
        if s == 'Temperature' and rw == 'WRITE':
            s = 'Warning: The temperature register is read-only!'
            self.putb([4, [s]])

        # Keep some statistics. Can be output in report(), for example.
        if celsius < self.mintemp:
            self.mintemp = celsius
        if celsius > self.maxtemp:
            self.maxtemp = celsius
        self.avgvalues.append(celsius)

    def handle_temperature_reg(self, b, s, rw):
        # Common helper for the temperature/T_HYST/T_OS registers.
        if len(self.databytes) == 0:
            self.block_start = self.ss
            self.databytes.append(b)
            return
        self.databytes.append(b)
        self.block_end = self.es
        self.output_temperature(s, rw)
        self.databytes = []

    def handle_reg_0x00(self, b, rw):
        # Temperature register (16bits, read-only).
        self.handle_temperature_reg(b, 'Temperature', rw)

    def handle_reg_0x01(self, b, rw):
        # Configuration register (8 bits, read/write).
        # TODO: Bit-exact annotation ranges.

        sd = b & (1 << 0)
        tmp = 'normal operation' if (sd == 0) else 'shutdown mode'
        s = 'SD = %d: %s\n' % (sd, tmp)
        s2 = 'SD = %s, ' % tmp

        cmp_int = b & (1 << 1)
        tmp = 'comparator' if (cmp_int == 0) else 'interrupt'
        s += 'CMP/INT = %d: %s mode\n' % (cmp_int, tmp)
        s2 += 'CMP/INT = %s, ' % tmp

        pol = b & (1 << 2)
        tmp = 'low' if (pol == 0) else 'high'
        s += 'POL = %d: OS polarity is active-%s\n' % (pol, tmp)
        s2 += 'POL = active-%s, ' % tmp

        bits = (b & ((1 << 4) | (1 << 3))) >> 3
        s += 'Fault tolerance setting: %d bit(s)\n' % ft[bits]
        s2 += 'FT = %d' % ft[bits]

        # Not supported by LM75, but by various compatible devices.
        if self.options['sensor'] != 'lm75': # TODO
            bits = (b & ((1 << 6) | (1 << 5))) >> 5
            s += 'Resolution: %d bits\n' % resolution[bits]
            s2 += ', resolution = %d' % resolution[bits]

        self.putx([2, [s]])
        self.putx([3, [s2]])

    def handle_reg_0x02(self, b, rw):
        # T_HYST register (16 bits, read/write).
        self.handle_temperature_reg(b, 'T_HYST trip temperature', rw)

    def handle_reg_0x03(self, b, rw):
        # T_OS register (16 bits, read/write).
        self.handle_temperature_reg(b, 'T_OS trip temperature', rw)

    def decode(self, ss, es, data):
        cmd, databyte = data

        # Store the start/end samples of this I2C packet.
        self.ss, self.es = ss, es

        # State machine.
        if self.state == 'IDLE':
            # Wait for an I2C START condition.
            if cmd != 'START':
                return
            self.state = 'GET SLAVE ADDR'
        elif self.state == 'GET SLAVE ADDR':
            # Wait for an address read/write operation.
            if cmd in ('ADDRESS READ', 'ADDRESS WRITE'):
                self.warn_upon_invalid_slave(databyte)
                self.state = cmd[8:] + ' REGS' # READ REGS / WRITE REGS
        elif self.state in ('READ REGS', 'WRITE REGS'):
            if cmd in ('DATA READ', 'DATA WRITE'):
                handle_reg = getattr(self, 'handle_reg_0x%02x' % self.reg)
                handle_reg(databyte, cmd[5:]) # READ / WRITE
            elif cmd == 'STOP':
                # TODO: Any output?
                self.state = 'IDLE'
            else:
                # self.putx([0, ['Ignoring: %s (data=%s)' % (cmd, databyte)]])
                pass
        else:
            raise Exception('Invalid state: %s' % self.state)
Commit	Line	Data
44f7ba18	1	##
50bd5d25	2	## This file is part of the libsigrokdecode project.
44f7ba18 UH	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'
d523eae6	49	desc = 'National LM75 (and compatibles) temperature sensor.'
44f7ba18 UH	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'],
f84d82c0	66	['Kelvin', 'Temperature in Kelvin'],
44f7ba18 UH	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
b5d3ea69	78	self.avgvalues = []
44f7ba18	79
8915b346	80	def start(self):
44f7ba18 UH	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):
b5d3ea69 UH	85	# TODO: print() or self.put() or return xyz, or... ?
	86	avg = sum(self.avgvalues) / len(self.avgvalues)
	87	temperatures = (self.mintemp, self.maxtemp, avg)
	88	# TODO: Configurable report() output, e.g. for Kelvin.
	89	return 'Min/max/avg temperature: %f/%f/%f °C' % temperatures
44f7ba18 UH	90
	91	def putx(self, data):
	92	# Helper for annotations which span exactly one I2C packet.
	93	self.put(self.ss, self.es, self.out_ann, data)
	94
	95	def putb(self, data):
	96	# Helper for annotations which span a block of I2C packets.
	97	self.put(self.block_start, self.block_end, self.out_ann, data)
	98
	99	def warn_upon_invalid_slave(self, addr):
	100	# LM75 and compatible devices have a 7-bit I2C slave address where
	101	# the 4 MSBs are fixed to 1001, and the 3 LSBs are configurable.
	102	# Thus, valid slave addresses (1001xxx) range from 0x48 to 0x4f.
	103	if addr not in range(0x48, 0x4f + 1):
	104	s = 'Warning: I2C slave 0x%02x not an LM75 compatible sensor.'
	105	self.putx([4, [s % addr]])
	106
5b30440e	107	def output_temperature(self, s, rw):
44f7ba18 UH	108	# TODO: Support for resolutions other than 9 bit.
	109	before, after = self.databytes[0], (self.databytes[1] >> 7) * 5
	110	celsius = float('%d.%d' % (before, after))
	111	kelvin = celsius + 273.15
	112	self.putb([0, ['%s: %.1f °C' % (s, celsius)]])
f84d82c0	113	self.putb([1, ['%s: %.1f K' % (s, kelvin)]])
44f7ba18	114
86aac5f0 UH	115	# Warn about the temperature register (0x00) being read-only.
	116	if s == 'Temperature' and rw == 'WRITE':
	117	s = 'Warning: The temperature register is read-only!'
	118	self.putb([4, [s]])
	119
44f7ba18 UH	120	# Keep some statistics. Can be output in report(), for example.
	121	if celsius < self.mintemp:
	122	self.mintemp = celsius
	123	if celsius > self.maxtemp:
	124	self.maxtemp = celsius
b5d3ea69	125	self.avgvalues.append(celsius)
44f7ba18	126
5b30440e	127	def handle_temperature_reg(self, b, s, rw):
44f7ba18 UH	128	# Common helper for the temperature/T_HYST/T_OS registers.
	129	if len(self.databytes) == 0:
	130	self.block_start = self.ss
	131	self.databytes.append(b)
	132	return
	133	self.databytes.append(b)
	134	self.block_end = self.es
5b30440e	135	self.output_temperature(s, rw)
44f7ba18 UH	136	self.databytes = []
44f7ba18 UH	137
5b30440e	138	def handle_reg_0x00(self, b, rw):
44f7ba18	139	# Temperature register (16bits, read-only).
5b30440e	140	self.handle_temperature_reg(b, 'Temperature', rw)
44f7ba18	141
5b30440e	142	def handle_reg_0x01(self, b, rw):
44f7ba18 UH	143	# Configuration register (8 bits, read/write).
	144	# TODO: Bit-exact annotation ranges.
	145
	146	sd = b & (1 << 0)
	147	tmp = 'normal operation' if (sd == 0) else 'shutdown mode'
	148	s = 'SD = %d: %s\n' % (sd, tmp)
	149	s2 = 'SD = %s, ' % tmp
	150
	151	cmp_int = b & (1 << 1)
	152	tmp = 'comparator' if (cmp_int == 0) else 'interrupt'
	153	s += 'CMP/INT = %d: %s mode\n' % (cmp_int, tmp)
	154	s2 += 'CMP/INT = %s, ' % tmp
	155
	156	pol = b & (1 << 2)
	157	tmp = 'low' if (pol == 0) else 'high'
	158	s += 'POL = %d: OS polarity is active-%s\n' % (pol, tmp)
	159	s2 += 'POL = active-%s, ' % tmp
	160
	161	bits = (b & ((1 << 4) \| (1 << 3))) >> 3
	162	s += 'Fault tolerance setting: %d bit(s)\n' % ft[bits]
	163	s2 += 'FT = %d' % ft[bits]
	164
	165	# Not supported by LM75, but by various compatible devices.
	166	if self.options['sensor'] != 'lm75': # TODO
	167	bits = (b & ((1 << 6) \| (1 << 5))) >> 5
	168	s += 'Resolution: %d bits\n' % resolution[bits]
	169	s2 += ', resolution = %d' % resolution[bits]
	170
	171	self.putx([2, [s]])
	172	self.putx([3, [s2]])
	173
5b30440e	174	def handle_reg_0x02(self, b, rw):
44f7ba18	175	# T_HYST register (16 bits, read/write).
5b30440e	176	self.handle_temperature_reg(b, 'T_HYST trip temperature', rw)
44f7ba18	177
5b30440e	178	def handle_reg_0x03(self, b, rw):
44f7ba18	179	# T_OS register (16 bits, read/write).
5b30440e	180	self.handle_temperature_reg(b, 'T_OS trip temperature', rw)
44f7ba18 UH	181
	182	def decode(self, ss, es, data):
	183	cmd, databyte = data
	184
	185	# Store the start/end samples of this I2C packet.
	186	self.ss, self.es = ss, es
	187
	188	# State machine.
	189	if self.state == 'IDLE':
	190	# Wait for an I2C START condition.
	191	if cmd != 'START':
	192	return
	193	self.state = 'GET SLAVE ADDR'
	194	elif self.state == 'GET SLAVE ADDR':
	195	# Wait for an address read/write operation.
5b30440e	196	if cmd in ('ADDRESS READ', 'ADDRESS WRITE'):
44f7ba18	197	self.warn_upon_invalid_slave(databyte)
5b30440e UH	198	self.state = cmd[8:] + ' REGS' # READ REGS / WRITE REGS
	199	elif self.state in ('READ REGS', 'WRITE REGS'):
	200	if cmd in ('DATA READ', 'DATA WRITE'):
44f7ba18	201	handle_reg = getattr(self, 'handle_reg_0x%02x' % self.reg)
5b30440e	202	handle_reg(databyte, cmd[5:]) # READ / WRITE
44f7ba18 UH	203	elif cmd == 'STOP':
	204	# TODO: Any output?
	205	self.state = 'IDLE'
	206	else:
	207	# self.putx([0, ['Ignoring: %s (data=%s)' % (cmd, databyte)]])
	208	pass
	209	else:
	210	raise Exception('Invalid state: %s' % self.state)
	211