FHEM/fhem-mirror
2
0
Fork 0
mirror of https://github.com/fhem/fhem-mirror.git synced 2025-02-08 05:15:10 +00:00
Code Issues Releases Wiki Activity
fhem-mirror/fhem/FHEM/51_I2C_TSL2561.pm
kaihs f45eb66f7b I2C_TSL2561: set gain/integrationTime attributes correctly during fhem startup 
git-svn-id: https://svn.fhem.de/fhem/trunk@8697 2b470e98-0d58-463d-a4d8-8e2adae1ed80
2015-06-05 21:41:08 +00:00

1570 lines
54 KiB
Perl
Raw Blame History

=head1
51_I2C_TSL2561.pm
=head1 SYNOPSIS
Modul for FHEM for reading a TSL2561 ambient light sensor via I2C
connected to the Raspberry Pi.
contributed by Kai Stuke 2014
$Id$
=head1 DESCRIPTION
51_I2C_TSL2561.pm reads the illumination of the the ambient light sensor TSL2561
via i2c bus connected to the Raspberry Pi.
This module needs IODev FHEM modules or the HiPi perl modules
IODev see: <a href="#RPII2C">RPII2C</a>, <a href="#FRM">FRM</a> or <a href="#NetzerI2C">NetzerI2C</a>
HiPi see: http://raspberrypi.znix.com/hipidocs/
For a simple automated installation of the HiPi perl modules:<br>
wget http://raspberry.znix.com/hipifiles/hipi-install
perl hipi-install
HiPi Example:
define Luminosity I2C_TSL2561 /dev/i2c-0 0x39
attr Luminosity poll_interval 5
IODev Example:
define Luminosity I2C_TSL2561 0x39
attr Luminosity IODev I2CModule
attr Luminosity poll_interval 5
=head1 HiPi CAVEATS
Make sure that the user fhem.pl is running as has read/write access to the i2c device file
(e.g. /dev/i2c-0).
This can be achieved by adding the user to the group i2c (sudo usermod -G i2c -a fhem).
The pinout of the i2c-bus pins differs between revision 1 and revision 2 Raspberry Pi Model B boards.
On revision 1, only bus 0 is accessible, on revision 2 bus 1 is connected to the standard pin header instead.
There is a problem with newer kernel versions (>3.9?) when both i2c and 1-wire are used.
If i2cdetect shows devices on all addresses you are affected by this bug.
To avoid this the kernel modules must be loaded in a specific order.
Try these settings in /etc/modules
w1_therm
w1-gpio
i2c-dev
i2c-bcm2708
snd-bcm2835
and in /etc/modprobe.d/raspi-blacklist.conf
blacklist spi-bcm2708
blacklist i2c-bcm2708
=head1 CHANGES
18.03.2015 jensb
IODev support added as alternative to HiPi
I2C error detection for IODev mode added
hotplug support (reinit TLS2561 afer each I2C error)
luminosity calculation alternative with float arithmetic for improved precision, especially with ir ratio below 50% and below 10 lux (new default, can be disabled)
scale readings 'broadband' and 'ir' with actual gain and integration time ratios to get values that can be directly used (e.g. for plots)
'luminosity', 'broadband' and 'ir' readings are not updated if state is 'Saturated' or 'I2C Error' so that timestamp of readings show last valid time
attribute and reading restoration added in I2C_TSL2561_Define
autoGain attribute inversion fix
'Saturation' state freeze fix
22.03.2015 jensb
round luminosity to 3 significant digits or max. 1 fractional digit when float arithmetics are enabled
11.04.2015 jensb
unblock FHEM while waiting for end of integration time - this makes using long integration times preferable
changing attribute 'gain' or 'integrationTime' no longer powers up the TSL2561
attribute 'disable' added
attribute 'autoIntegrationTime' added (decrease when measurement gets saturated, increase when value gets low)
I2C auto address mode added for IODev to compensate floating address selection
improved I2C read error handling for RPII2C IODev
16.04.2015 jensb
make scaling of readings 'broadband' and 'ir' dependend on new attribute 'normalizeRawValues'
18.04.2015 jensb
new readings 'gain' and 'integrationTime'
20.04.2015 jensb
update reading 'state' in bulk along with luminusity when toggling between 'Initialized' and 'Saturated'
=head1 TODO
HiPi, FRM and NetzerI2C I2C error detection (optional)
manual integration time (optional)
=head1 CREDITS
Based on the module 51_I2C_BMP180.pm by Dirk Hoffmann and Klaus Wittstock
TSL2651 specific code based on the python module by schwabbel as posted on
http://forums.adafruit.com/viewtopic.php?f=8&t=34922&start=75
which in turn is based on the code by Adafruit
https://github.com/adafruit/Adafruit_TSL2561
Lux calculation algorithm is based on the code in the TSL2561 datasheet
http://www.adafruit.com/datasheets/TSL2561.pdf
newer version
http://www.ams.com/eng/content/download/250094/975485/142937
=head1 AUTHOR - Kai Stuke
kaihs@FHEM_Forum (forum.fhem.de)
modified by Jens Beyer jensb@FHEM_Forum (forum.fhem.de)
=cut
package main;
use strict;
use warnings;
use Time::HiRes qw(tv_interval);
use Scalar::Util qw(looks_like_number);
use constant {
# I2C address options
TSL2561_ADDR_LOW => '0x29',
TSL2561_ADDR_FLOAT => '0x39', # Default address (pin left floating)
TSL2561_ADDR_HIGH => '0x49',
TSL2561_ADDR_AUTO => 'AUTO',
# I2C registers
TSL2561_REGISTER_CONTROL => 0x00,
TSL2561_REGISTER_TIMING => 0x01,
TSL2561_REGISTER_THRESHHOLDL_LOW => 0x02,
TSL2561_REGISTER_THRESHHOLDL_HIGH => 0x03,
TSL2561_REGISTER_THRESHHOLDH_LOW => 0x04,
TSL2561_REGISTER_THRESHHOLDH_HIGH => 0x05,
TSL2561_REGISTER_INTERRUPT => 0x06,
TSL2561_REGISTER_CRC => 0x08,
TSL2561_REGISTER_ID => 0x0A,
TSL2561_REGISTER_CHAN0_LOW => 0x0C,
TSL2561_REGISTER_CHAN0_HIGH => 0x0D,
TSL2561_REGISTER_CHAN1_LOW => 0x0E,
TSL2561_REGISTER_CHAN1_HIGH => 0x0F,
# I2C values
TSL2561_COMMAND_BIT => 0x80, # Must be 1,
TSL2561_CLEAR_BIT => 0x40, # Clears any pending interrupt (write 1 to clear)
TSL2561_WORD_BIT => 0x20, # 1 = read/write word (rather than byte)
TSL2561_BLOCK_BIT => 0x10, # 1 = using block read/write
TSL2561_CONTROL_POWERON => 0x03,
TSL2561_CONTROL_POWEROFF => 0x00,
TSL2561_PACKAGE_CS => 0b0001,
TSL2561_PACKAGE_T_FN_CL => 0b0101,
TSL2561_GAIN_1X => 0x00, # No gain
TSL2561_GAIN_16X => 0x10, # 16x gain
TSL2561_INTEGRATIONTIME_13MS => 0x00, # 13.7ms
TSL2561_INTEGRATIONTIME_101MS => 0x01, # 101ms
TSL2561_INTEGRATIONTIME_402MS => 0x02, # 402ms
TSL2561_INTEGRATIONTIME_MANUAL_STOP => 0x03, # stop manual integration cycle
TSL2561_INTEGRATIONTIME_MANUAL_START => 0x0b, # start manual integration cycle
# Auto-gain thresholds
TSL2561_AGC_THI_13MS => 4850, # Max value at Ti 13.7ms = 5047,
TSL2561_AGC_TLO_13MS => 100,
TSL2561_AGC_THI_101MS => 36000, # Max value at Ti 101ms = 37177,
TSL2561_AGC_TLO_101MS => 200,
TSL2561_AGC_THI_402MS => 63000, # Max value at Ti 402ms = 65535,
TSL2561_AGC_TLO_402MS => 500,
# Saturation clipping thresholds
TSL2561_CLIPPING_13MS => 4946, # 2% below 13.7 ms max. of 5047
TSL2561_CLIPPING_101MS => 36433, # 2% below 101 ms max. of 37177
TSL2561_CLIPPING_402MS => 64224, # 2% below 402 ms max. of 65535
# Lux calculations differ slightly for CS package
TSL2561_LUX_LUXSCALE =>14, # Scale by 2^14,
TSL2561_LUX_RATIOSCALE =>9, # Scale ratio by 2^9,
TSL2561_LUX_CHSCALE =>10, # Scale channel values by 2^10,
TSL2561_LUX_CHSCALE_TINT0 =>0x7517, # 322/11 * 2^TSL2561_LUX_CHSCALE
TSL2561_LUX_CHSCALE_TINT1 =>0x0FE7, # 322/81 * 2^TSL2561_LUX_CHSCALE
# T, FN and CL package values
TSL2561_LUX_K1T =>0x0040, # 0.125 * 2^RATIO_SCALE
TSL2561_LUX_B1T =>0x01f2, # 0.0304 * 2^LUX_SCALE
TSL2561_LUX_M1T =>0x01be, # 0.0272, * 2^LUX_SCALE
TSL2561_LUX_K2T =>0x0080, # 0.250 * 2^RATIO_SCALE
TSL2561_LUX_B2T =>0x0214, # 0.0325 * 2^LUX_SCALE
TSL2561_LUX_M2T =>0x02d1, # 0.0440 * 2^LUX_SCALE
TSL2561_LUX_K3T =>0x00c0, # 0.375 * 2^RATIO_SCALE
TSL2561_LUX_B3T =>0x023f, # 0.0351, * 2^LUX_SCALE
TSL2561_LUX_M3T =>0x037b, # 0.0544, * 2^LUX_SCALE
TSL2561_LUX_K4T =>0x0100, # 0.50 * 2^RATIO_SCALE
TSL2561_LUX_B4T =>0x0270, # 0.0381 * 2^LUX_SCALE
TSL2561_LUX_M4T =>0x03fe, # 0.0624, * 2^LUX_SCALE
TSL2561_LUX_K5T =>0x0138, # 0.61 * 2^RATIO_SCALE
TSL2561_LUX_B5T =>0x016f, # 0.0224, * 2^LUX_SCALE
TSL2561_LUX_M5T =>0x01fc, # 0.0310, * 2^LUX_SCALE
TSL2561_LUX_K6T =>0x019a, # 0.80, * 2^RATIO_SCALE
TSL2561_LUX_B6T =>0x00d2, # 0.0128 * 2^LUX_SCALE
TSL2561_LUX_M6T =>0x00fb, # 0.0153, * 2^LUX_SCALE
TSL2561_LUX_K7T =>0x029a, # 1.3, * 2^RATIO_SCALE
TSL2561_LUX_B7T =>0x0018, # 0.00146 * 2^LUX_SCALE
TSL2561_LUX_M7T =>0x0012, # 0.00112 * 2^LUX_SCALE
TSL2561_LUX_K8T =>0x029a, # 1.3, * 2^RATIO_SCALE
TSL2561_LUX_B8T =>0x0000, # 0.000 * 2^LUX_SCALE
TSL2561_LUX_M8T =>0x0000, # 0.000 * 2^LUX_SCALE
# CS package values
TSL2561_LUX_K1C =>0x0043, # 0.130 * 2^RATIO_SCALE
TSL2561_LUX_B1C =>0x0204, # 0.0315 * 2^LUX_SCALE
TSL2561_LUX_M1C =>0x01ad, # 0.0262, * 2^LUX_SCALE
TSL2561_LUX_K2C =>0x0085, # 0.260 * 2^RATIO_SCALE
TSL2561_LUX_B2C =>0x0228, # 0.0337 * 2^LUX_SCALE
TSL2561_LUX_M2C =>0x02c1, # 0.0430 * 2^LUX_SCALE
TSL2561_LUX_K3C =>0x00c8, # 0.390 * 2^RATIO_SCALE
TSL2561_LUX_B3C =>0x0253, # 0.0363 * 2^LUX_SCALE
TSL2561_LUX_M3C =>0x0363, # 0.0529 * 2^LUX_SCALE
TSL2561_LUX_K4C =>0x010a, # 0.520, * 2^RATIO_SCALE
TSL2561_LUX_B4C =>0x0282, # 0.0392 * 2^LUX_SCALE
TSL2561_LUX_M4C =>0x03df, # 0.0605, * 2^LUX_SCALE
TSL2561_LUX_K5C =>0x014d, # 0.65, * 2^RATIO_SCALE
TSL2561_LUX_B5C =>0x0177, # 0.0229 * 2^LUX_SCALE
TSL2561_LUX_M5C =>0x01dd, # 0.0291, * 2^LUX_SCALE
TSL2561_LUX_K6C =>0x019a, # 0.80, * 2^RATIO_SCALE
TSL2561_LUX_B6C =>0x0101, # 0.0157 * 2^LUX_SCALE
TSL2561_LUX_M6C =>0x0127, # 0.0180 * 2^LUX_SCALE
TSL2561_LUX_K7C =>0x029a, # 1.3, * 2^RATIO_SCALE
TSL2561_LUX_B7C =>0x0037, # 0.00338 * 2^LUX_SCALE
TSL2561_LUX_M7C =>0x002b, # 0.00260, * 2^LUX_SCALE
TSL2561_LUX_K8C =>0x029a, # 1.3, * 2^RATIO_SCALE
TSL2561_LUX_B8C =>0x0000, # 0.000 * 2^LUX_SCALE
TSL2561_LUX_M8C =>0x0000, # 0.000 * 2^LUX_SCALE
TSL2561_VISIBLE =>2, # channel 0 - channel 1
TSL2561_INFRARED =>1, # channel 1
TSL2561_FULLSPECTRUM =>0, # channel 0
STATE_UNDEFINED => 'Undefined',
STATE_DEFINED => 'Defined',
STATE_INITIALIZED => 'Initialized',
STATE_SATURATED => 'Saturated',
STATE_I2C_ERROR => 'I2C Error',
STATE_DISABLED => 'Disabled',
ACQUI_STATE_DISABLED => 0,
ACQUI_STATE_ENABLED => 1,
ACQUI_STATE_DATA_AVAILABLE => 2,
ACQUI_STATE_DATA_CH0_RECEIVED => 3,
ACQUI_STATE_DATA_CH1_RECEIVED => 4,
ACQUI_STATE_ERROR => 5,
CALC_STATE_IDLE => 0,
CALC_STATE_DATA_REQUESTED => 1,
CALC_STATE_DATA_RECEIVED => 2,
CALC_STATE_ERROR => 3,
};
##################################################
# Forward declarations
#
sub I2C_TSL2561_Initialize($);
sub I2C_TSL2561_Define($$);
sub I2C_TSL2561_Attr(@);
sub I2C_TSL2561_Poll($);
sub I2C_TSL2561_Set($@);
sub I2C_TSL2561_Get($);
sub I2C_TSL2561_Undef($$);
sub I2C_TSL2561_Enable($);
sub I2C_TSL2561_Disable($);
sub I2C_TSL2561_GetData($);
sub I2C_TSL2561_SetIntegrationTime($$);
sub I2C_TSL2561_SetGain($$);
sub I2C_TSL2561_GetLuminosity($);
sub I2C_TSL2561_CalculateLux($);
my $libcheck_hasHiPi = 1;
my %sets = (
"update" => "",
);
my %validAdresses = (
"0x29" => TSL2561_ADDR_LOW,
"0x39" => TSL2561_ADDR_FLOAT,
"0x49" => TSL2561_ADDR_HIGH,
"auto" => TSL2561_ADDR_AUTO,
);
my %validPackages = (
"CS" => TSL2561_PACKAGE_CS,
"T" => TSL2561_PACKAGE_T_FN_CL,
"FN" => TSL2561_PACKAGE_T_FN_CL,
"CL" => TSL2561_PACKAGE_T_FN_CL,
);
my @fsmSubs = (\&I2C_TSL2561_StartMeasurement, \&I2C_TSL2561_GetMeasurement);
=head2 I2C_TSL2561_Initialize
Title: I2C_TSL2561_Initialize
Function: Implements the initialize function.
Returns: -
Args: named arguments:
-argument1 => hash
=cut
sub I2C_TSL2561_Initialize($) {
my ($hash) = @_;
eval "use HiPi::Device::I2C;";
$libcheck_hasHiPi = 0 if($@);
$hash->{DefFn} = 'I2C_TSL2561_Define';
$hash->{AttrFn} = 'I2C_TSL2561_Attr';
$hash->{SetFn} = 'I2C_TSL2561_Set';
$hash->{UndefFn} = 'I2C_TSL2561_Undef';
$hash->{I2CRecFn} = 'I2C_TSL2561_I2CRec';
$hash->{AttrList} = 'IODev do_not_notify:0,1 showtime:0,1 ' .
'loglevel:0,1,2,3,4,5,6 poll_interval:1,2,5,10,20,30 ' .
'gain:1,16 integrationTime:13,101,402 ' .
'autoGain:0,1 autoIntegrationTime:0,1 normalizeRawValues:0,1 ' .
'floatArithmetics:0,1 disable:0,1 ' . $readingFnAttributes;
$hash->{AttrList} .= " useHiPiLib:0,1 " if ($libcheck_hasHiPi);
}
sub I2C_TSL2561_Define($$) {
my ($hash, $def) = @_;
my @a = split('[ \t][ \t]*', $def);
my $name = $a[0];
my $device;
readingsSingleUpdate($hash, 'state', STATE_UNDEFINED, 1);
Log3 $name, 1, "I2C_TSL2561_Define start: " . @a . "/" . join(' ', @a);
$hash->{HiPi_exists} = $libcheck_hasHiPi if ($libcheck_hasHiPi);
$hash->{HiPi_used} = 0;
my $address = undef;
my $msg = '';
if (@a < 3) {
$msg = 'wrong syntax: define <name> I2C_TSL2561 [devicename] address';
} elsif (@a == 3) {
$address = lc($a[2]);
} else {
$device = $a[2];
$address = lc($a[3]);
if ($libcheck_hasHiPi) {
$hash->{HiPi_used} = 1;
delete $validAdresses{'auto'};
} else {
$msg = '$name error: HiPi library not installed';
}
}
if ($msg) {
Log3 ($hash, 1, $msg);
return $msg;
}
$address = $validAdresses{$address};
if (!defined($address)) {
$msg = "Wrong address, must be one of " . join(' ', keys %validAdresses);
Log3 ($hash, 1, $msg);
return $msg;
}
$hash->{I2C_Address} = hex($address);
if (!$hash->{HiPi_used}) {
if ($address eq TSL2561_ADDR_AUTO) {
# start with lowest address in auto mode
$hash->{autoAddress} = 1;
$address = TSL2561_ADDR_LOW;
} else {
$hash->{autoAddress} = 0;
}
}
# create default attributes
if (AttrVal($name, 'poll_interval', '?') eq '?') {
$msg = CommandAttr(undef, $name . ' poll_interval 5');
if ($msg) {
Log (1, $msg);
return $msg;
}
}
if (AttrVal($name, 'floatArithmetics', '?') eq '?') {
$msg = CommandAttr(undef, $name . ' floatArithmetics 1');
if ($msg) {
Log (1, $msg);
return $msg;
}
}
# preset some internal readings
if (!defined($hash->{tsl2561IntegrationTime})) {
my $attrVal = AttrVal($name, 'integrationTime', 13);
$hash->{tsl2561IntegrationTime} = $attrVal == 402? TSL2561_INTEGRATIONTIME_402MS : $attrVal == 101? TSL2561_INTEGRATIONTIME_101MS : TSL2561_INTEGRATIONTIME_13MS;
}
if (!defined($hash->{tsl2561Gain})) {
my $attrVal = AttrVal($name, 'gain', 1);
$hash->{tsl2561Gain} = $attrVal == 16? TSL2561_GAIN_16X : TSL2561_GAIN_1X;
}
if (!defined($hash->{acquiState})) {
$hash->{acquiState} = ACQUI_STATE_DISABLED;
}
if (!defined($hash->{calcState})) {
$hash->{calcState} = CALC_STATE_IDLE;
}
readingsSingleUpdate($hash, 'state', STATE_DEFINED, 1);
eval {
I2C_TSL2561_Init($hash, $device);
};
Log3 ($hash, 1, $hash->{NAME} . ': ' . I2C_TSL2561_Catch($@)) if $@;;
Log3 $name, 5, "I2C_TSL2561_Define end";
return undef;
}
sub I2C_TSL2561_Init($$) {
my ($hash, $dev) = @_;
my $name = $hash->{NAME};
if ($hash->{HiPi_used}) {
# check for existing i2c device
my $i2cModulesLoaded = 0;
$i2cModulesLoaded = 1 if -e $dev;
if ($i2cModulesLoaded) {
if (-r $dev && -w $dev) {
$hash->{devTSL2561} = HiPi::Device::I2C->new(
devicename => $dev,
address => $hash->{I2C_Address},
busmode => 'i2c',
);
Log3 $name, 3, "I2C_TSL2561_Define device created";
} else {
my @groups = split '\s', $(;
return "$name :Error! $dev isn't readable/writable by user " . getpwuid( $< ) . " or group(s) " .
getgrgid($_) . " " foreach(@groups);
}
} else {
return $name . ': Error! I2C device not found: ' . $dev . '. Please check that these kernelmodules are loaded: i2c_bcm2708, i2c_dev';
}
} else {
AssignIoPort($hash);
}
readingsSingleUpdate($hash, 'state', STATE_INITIALIZED, 1);
return undef;
}
sub I2C_TSL2561_Catch($) {
my $exception = shift;
if ($exception) {
$exception =~ /^(.*)( at.*FHEM.*)$/;
return $1;
}
return undef;
}
=head2 I2C_TSL2561_Attr
Title: I2C_TSL2561_Attr
Function: Implements AttrFn function.
Returns: string|undef
Args: named arguments:
-argument1 => array
=cut
sub I2C_TSL2561_Attr (@) {
my ($cmd, $name, $attr, $val) = @_;
my $hash = $defs{$name};
my $msg = '';
Log3 $name, 5, "I2C_TSL2561_Attr: start cmd=$cmd attr=$attr";
if ($attr eq 'poll_interval') {
my $pollInterval = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
if ($val > 0) {
RemoveInternalTimer($hash);
InternalTimer(gettimeofday() + 1, 'I2C_TSL2561_Poll', $hash, 0);
} elsif (defined($val)) {
$msg = 'Wrong poll intervall defined. poll_interval must be a number > 0';
}
} elsif ($attr eq 'gain') {
my $gain = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
Log3 $name, 5, "I2C_TSL2561_Attr: attr gain is " . $gain;
if ($gain == 1) {
I2C_TSL2561_SetGain($hash, TSL2561_GAIN_1X);
} elsif ($gain == 16) {
I2C_TSL2561_SetGain($hash, TSL2561_GAIN_16X);
} elsif (defined($val)) {
$msg = 'Wrong gain defined. must be 1 or 16';
}
} elsif ($attr eq 'integrationTime') {
my $time = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
if ($time == 13) {
I2C_TSL2561_SetIntegrationTime($hash, TSL2561_INTEGRATIONTIME_13MS);
} elsif ($time == 101) {
I2C_TSL2561_SetIntegrationTime($hash, TSL2561_INTEGRATIONTIME_101MS);
} elsif ($time == 402) {
I2C_TSL2561_SetIntegrationTime($hash, TSL2561_INTEGRATIONTIME_402MS);
} elsif (defined($val)) {
$msg = 'Wrong integrationTime defined. must be 13 or 101 or 402';
}
} elsif ($attr eq 'autoGain') {
my $autoGain = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
if (!$autoGain) {
I2C_TSL2561_Attr($hash, $name, 'gain', AttrVal($name, 'gain', 1));
}
} elsif ($attr eq 'autoIntegrationTime') {
my $autoIntegrationTime = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
if (!$autoIntegrationTime) {
I2C_TSL2561_Attr($hash, $name, 'integrationTime', AttrVal($name, 'integrationTime', 13));
}
} elsif ($attr eq 'normalizeRawValues') {
my $normalizeRawValues = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
} elsif ($attr eq 'floatArithmetics') {
my $floatArithmetics = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
} elsif ($attr eq "disable") {
my $disable = (defined($val) && looks_like_number($val) && $val > 0) ? $val : 0;
}
return ($msg) ? $msg : undef;
}
=head2 I2C_TSL2561_Poll
Title: I2C_TSL2561_Poll
Function: Start polling the sensor at interval defined in attribute
Returns: -
Args: named arguments:
-argument1 => hash
=cut
sub I2C_TSL2561_Poll($) {
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 5, "I2C_TSL2561_Poll: start";
my $pollDelay = 60*AttrVal($hash->{NAME}, 'poll_interval', 0); # seconds polling
if (!AttrVal($hash->{NAME}, "disable", 0)) {
# Read new values
my $state = ReadingsVal($name, 'state', '');
if ($state eq STATE_I2C_ERROR) {
# try to turn off the device to check I2C communication (hotplug and error recovery)
if (I2C_TSL2561_Disable($hash)) {
$state = STATE_INITIALIZED;
readingsSingleUpdate($hash, 'state', $state, 1);
} elsif ($hash->{autoAddress}) {
# auto address mode, scan bus for device
if ($hash->{I2C_Address} == hex(TSL2561_ADDR_LOW)) {
$hash->{I2C_Address} = hex(TSL2561_ADDR_FLOAT);
} elsif ($hash->{I2C_Address} == hex(TSL2561_ADDR_FLOAT)) {
$hash->{I2C_Address} = hex(TSL2561_ADDR_HIGH);
} else {
$hash->{I2C_Address} = hex(TSL2561_ADDR_LOW);
}
$pollDelay = 10; # seconds retry delay
}
$hash->{tsl2561Package} = undef;
}
if ($state ne STATE_I2C_ERROR) {
# Request new samples from TSL2561 and calculate luminosity
my $lux = I2C_TSL2561_GetLuminosity($hash);
if ($hash->{calcState} == CALC_STATE_DATA_REQUESTED) {
$pollDelay = I2C_TSL2561_GetIntegrationTime($hash) + 0.001; # seconds integration time
} else {
if ($hash->{calcState} == CALC_STATE_IDLE) {
my $chScale = 1;
if (AttrVal($hash->{NAME}, "normalizeRawValues", 0)) {
$chScale = I2C_TSL2561_GetChannelScale($hash);
}
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, "gain", I2C_TSL2561_GetGain($hash));
readingsBulkUpdate($hash, "integrationTime", I2C_TSL2561_GetIntegrationTime($hash));
readingsBulkUpdate($hash, "broadband", ceil($chScale*$hash->{broadband}));
readingsBulkUpdate($hash, "ir", ceil($chScale*$hash->{ir}));
if (defined($lux)) {
readingsBulkUpdate($hash, "luminosity", $lux);
}
if ($state eq STATE_INITIALIZED && $hash->{saturated}) {
readingsBulkUpdate($hash, 'state', STATE_SATURATED, 1);
} elsif ($state eq STATE_SATURATED && !$hash->{saturated}) {
readingsBulkUpdate($hash, 'state', STATE_INITIALIZED, 1);
}
readingsEndUpdate($hash, 1);
}
}
}
} else {
readingsSingleUpdate($hash, 'state', STATE_DISABLED, 1);
}
# Schedule next polling
Log3 $name, 5, "I2C_TSL2561_Poll: $pollDelay s";
if ($pollDelay > 0) {
InternalTimer(gettimeofday() + $pollDelay, 'I2C_TSL2561_Poll', $hash, 0);
}
}
sub I2C_TSL2561_Set($@) {
my ( $hash, @args ) = @_;
my $name = $hash->{NAME};
my $cmd = $args[1];
if(!defined($sets{$cmd})) {
return 'Unknown argument ' . $cmd . ', choose one of ' . join(' ', keys %sets)
}
RemoveInternalTimer($hash);
I2C_TSL2561_Poll($hash);
return undef;
}
sub I2C_TSL2561_Undef($$) {
my ($hash, $arg) = @_;
RemoveInternalTimer($hash);
if ($hash->{HiPi_used}) {
$hash->{devTSL2561}->close()
}
return undef;
}
#
# process received control register
#
sub I2C_TSL2561_I2CRcvControl($$) {
my ($hash, $control) = @_;
my $name = $hash->{NAME};
my $enabled = $control & 0x3;
if ($enabled == TSL2561_CONTROL_POWERON) {
Log3 $name, 5, "I2C_TSL2561_I2CRcvControl: is enabled";
$hash->{sensorEnabled} = 1;
$hash->{acquiState} = ACQUI_STATE_ENABLED;
$hash->{acquiStarted} = [gettimeofday];
} else {
Log3 $name, 5, "I2C_TSL2561_I2CRcvControl: is disabled";
$hash->{sensorEnabled} = 0;
$hash->{acquiState} = ACQUI_STATE_DISABLED;
}
}
#
# process received ID register
#
sub I2C_TSL2561_I2CRcvID($$) {
my ($hash, $sensorId) = @_;
my $name = $hash->{NAME};
if ( !($sensorId & 0b00010000) ) {
return $name . ': Error! I2C failure: Please check your i2c bus and the connected device address: ' . $hash->{I2C_Address};
}
my $package = '';
$hash->{tsl2561Package} = $sensorId >> 4;
if ($hash->{tsl2561Package} == TSL2561_PACKAGE_CS) {
$package = 'CS';
} else {
$package = 'T/FN/CL';
}
$hash->{sensorType} = 'TSL2561 Package ' . $package . ' Rev. ' . ( $sensorId & 0x0f );
Log3 $name, 5, 'I2C_TSL2561_I2CRcvID: sensorId ' . $hash->{sensorType};
}
#
# process received timing register
#
sub I2C_TSL2561_I2CRcvTiming ($$) {
my ($hash, $timing) = @_;
my $name = $hash->{NAME};
$hash->{tsl2561IntegrationTime} = $timing & 0x03;
$hash->{tsl2561Gain} = $timing & 0x10;
Log3 $name, 5, "I2C_TSL2561_I2CRcvTiming: $timing, $hash->{tsl2561IntegrationTime}, $hash->{tsl2561Gain}";
}
#
# process received ADC channel 0 register
#
sub I2C_TSL2561_I2CRcvChan0 ($$) {
my ($hash, $broadband) = @_;
my $name = $hash->{NAME};
Log3 $name, 5, 'I2C_TSL2561_I2CRcvChan0 ' . $broadband;
$hash->{broadband} = $broadband;
$hash->{acquiState} = ACQUI_STATE_DATA_CH0_RECEIVED;
}
#
# process received ADC channel 1 register
#
sub I2C_TSL2561_I2CRcvChan1 ($$) {
my ($hash, $ir) = @_;
my $name = $hash->{NAME};
Log3 $name, 5, 'I2C_TSL2561_I2CRcvChan1 ' . $ir;
$hash->{ir} = $ir;
$hash->{acquiState} = ACQUI_STATE_DATA_CH1_RECEIVED;
}
#
# preprocess received data from I2C bus
#
sub I2C_TSL2561_I2CRec ($$) {
my ($hash, $clientmsg) = @_;
my $name = $hash->{NAME};
my $pname = undef;
unless ($hash->{HiPi_used}) { #nicht nutzen wenn HiPi Bibliothek in Benutzung
my $phash = $hash->{IODev};
$pname = $phash->{NAME};
while (my ( $k, $v ) = each %$clientmsg) { #erzeugen von Internals f<>r alle Keys in $clientmsg die mit dem physical Namen beginnen
$hash->{$k} = $v if $k =~ /^$pname/;
}
}
if ($clientmsg->{direction} && $clientmsg->{reg} &&
(($pname && $clientmsg->{$pname . "_SENDSTAT"} && $clientmsg->{$pname . "_SENDSTAT"} eq "Ok")
|| $hash->{HiPi_used})) {
if ( $clientmsg->{direction} eq "i2cread" && defined($clientmsg->{received})) {
my $register = $clientmsg->{reg} & 0xF;
Log3 $hash, 5, "$name RX register $register, $clientmsg->{nbyte} byte: $clientmsg->{received}";
my $byte = undef;
my $word = undef;
my @raw = split(" ", $clientmsg->{received});
if ($clientmsg->{nbyte} == 1) {
$byte = $raw[0];
} elsif ($clientmsg->{nbyte} == 2) {
$word = $raw[1] << 8 | $raw[0];
}
if ($register == TSL2561_REGISTER_CONTROL) {
I2C_TSL2561_I2CRcvControl($hash, $byte);
} elsif ($register == TSL2561_REGISTER_ID) {
I2C_TSL2561_I2CRcvID($hash, $byte);
} elsif ($register == TSL2561_REGISTER_TIMING) {
I2C_TSL2561_I2CRcvTiming($hash, $byte);
} elsif ($register == TSL2561_REGISTER_CHAN0_LOW) {
I2C_TSL2561_I2CRcvChan0($hash, $word);
} elsif ($register == TSL2561_REGISTER_CHAN1_LOW) {
I2C_TSL2561_I2CRcvChan1($hash, $word);
} else {
Log3 $name, 3, "I2C_TSL2561_I2CRec unsupported register $register";
}
}
}
}
=head2 I2C_TSL2561_Enable
Title: I2C_TSL2561_Enable
Function: Enables the device
Returns: 1 if sensor was enabled, 0 if enabling sensor failed
Args: named arguments:
-argument1 => hash: $hash hash of device
=cut
sub I2C_TSL2561_Enable($) {
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 5, 'I2C_TSL2561_Enable: start ';
# Detect TLS2561 package type and init integration time and gain
my $initialized = 1;
if (!defined($hash->{tsl2561Package})) {
# Get TLS2561 package type
$initialized = 0;
if (I2C_TSL2561_i2cread($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_ID, 1)) {
# Preset integration time and gain
if (I2C_TSL2561_SetGain($hash, $hash->{tsl2561Gain})) {
$initialized = 1;
}
}
}
# Enable TLS2561
$hash->{sensorEnabled} = 0;
if ($initialized) {
if (I2C_TSL2561_i2cwrite($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_CONTROL, TSL2561_CONTROL_POWERON)) {
I2C_TSL2561_i2cread($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_CONTROL, 1);
}
if (!$hash->{sensorEnabled}) {
# Enable failed (no sensor at address or wrong I2C device)
$hash->{tsl2561Package} = undef;
}
}
Log3 $name, 5, 'I2C_TSL2561_Enable: end ';
return $hash->{sensorEnabled};
}
=head2 I2C_TSL2561_Disable
Title: I2C_TSL2561_Disable
Function: Enables the device
Returns: 1 if write was successful, 0 if write failed
Args: named arguments:
-argument1 => hash: $hash hash of device
=cut
sub I2C_TSL2561_Disable($) {
my ($hash) = @_;
my $name = $hash->{NAME};
Log3 $name, 5, 'I2C_TSL2561_Disable: start ';
my $success = I2C_TSL2561_i2cwrite($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_CONTROL, TSL2561_CONTROL_POWEROFF);
$hash->{sensorEnabled} = 0;
Log3 $name, 5, 'I2C_TSL2561_Disable: end ';
return $success;
}
=head2 I2C_TSL2561_GetData
Title: I2C_TSL2561_GetData
Function: Private function to read luminosity on both channels
Returns: -
Args: named arguments:
-argument1 => hash: $hash hash of device
=cut
sub I2C_TSL2561_GetData($) {
my ($hash) = @_;
my $name = $hash->{NAME};
# Data acquisition state machine with asynchronous wait
my $success = 1;
my $operations = 0;
while (1) {
$operations++;
if ($hash->{acquiState} == ACQUI_STATE_ERROR) {
$hash->{calcState} = CALC_STATE_ERROR;
readingsSingleUpdate($hash, 'state', STATE_I2C_ERROR, 1);
# Turn the device off to save power
I2C_TSL2561_Disable($hash);
$hash->{acquiState} = ACQUI_STATE_DISABLED;
$success = 0;
last; # Abort, Start again at next slow poll
} elsif ($operations > 10) {
# Too many consecutive operations, abort
$hash->{acquiState} = ACQUI_STATE_ERROR;
Log3 $name, 5, "I2C_TSL2561_GetData: state machine stuck, aborting";
} elsif ($hash->{acquiState} == ACQUI_STATE_DISABLED) {
# Enable the device by setting the control bit to 0x03
if (!I2C_TSL2561_Enable($hash)) {
$hash->{acquiState} = ACQUI_STATE_ERROR;
}
} elsif ($hash->{acquiState} == ACQUI_STATE_ENABLED) {
# Wait x ms for ADC to complete
$hash->{calcState} = CALC_STATE_DATA_REQUESTED;
my $now = [gettimeofday];
if (tv_interval($hash->{acquiStarted}, $now) >= I2C_TSL2561_GetIntegrationTime($hash)) {
$hash->{acquiState} = ACQUI_STATE_DATA_AVAILABLE;
} else {
last; # Wait, check again after next fast poll
}
} elsif ($hash->{acquiState} == ACQUI_STATE_DATA_AVAILABLE) {
# Reads a two byte value from channel 0 (visible + infrared)
if (!I2C_TSL2561_i2cread($hash, TSL2561_COMMAND_BIT | TSL2561_WORD_BIT | TSL2561_REGISTER_CHAN0_LOW, 2)) {
$hash->{acquiState} = ACQUI_STATE_ERROR;
}
} elsif ($hash->{acquiState} == ACQUI_STATE_DATA_CH0_RECEIVED) {
# Reads a two byte value from channel 1 (infrared)
if (!I2C_TSL2561_i2cread($hash, TSL2561_COMMAND_BIT | TSL2561_WORD_BIT | TSL2561_REGISTER_CHAN1_LOW, 2)) {
$hash->{acquiState} = ACQUI_STATE_ERROR;
}
} elsif ($hash->{acquiState} == ACQUI_STATE_DATA_CH1_RECEIVED) {
$hash->{calcState} = CALC_STATE_DATA_RECEIVED;
# Done, turn the device off to save power
I2C_TSL2561_Disable($hash);
$hash->{acquiState} = ACQUI_STATE_DISABLED;
last; # Done, start again at next slow poll
} else {
# Undefined state
$hash->{acquiState} = ACQUI_STATE_ERROR;
}
}
return $success;
}
=head2 I2C_TSL2561_SetIntegrationTime
Title: I2C_TSL2561_SetIntegrationTime
Function: Sets the integration time for the TSL2561
Returns: -
Args: named arguments:
-argument1 => hash: $hash hash of device
-argument1 => number: $time constant for integration time setting
=cut
sub I2C_TSL2561_SetIntegrationTime($$) {
my ($hash, $time) = @_;
my $name = $hash->{NAME};
# store the value even if $hash->{tsl2561Package} ist not set (yet). That happens
# during fhem startup.
$hash->{tsl2561IntegrationTime} = $time;
# Enable the device by setting the control bit to 0x03
my $success = 0;
if (!AttrVal($hash->{NAME}, "disable", 0) && defined($hash->{tsl2561Package})) {
my $state = ReadingsVal($name, 'state', '');
if ($state ne STATE_I2C_ERROR) {
# Update the timing register
Log3 $name, 5, "I2C_TSL2561_SetIntegrationTime: time " . $time ;
Log3 $name, 5, "I2C_TSL2561_SetIntegrationTime: gain " . $hash->{tsl2561Gain};
if (I2C_TSL2561_i2cwrite($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_TIMING, $time | $hash->{tsl2561Gain})) {
if (I2C_TSL2561_i2cread($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_TIMING, 1)) {
$success = 1;
}
}
}
}
return $success;
}
#
# decode TSL2561 integration time into decimal value
# @param device hash
# @return integration time in seconds that was last reported by the TSL2561
#
sub I2C_TSL2561_GetIntegrationTime($) {
my ($hash) = @_;
my $tsl2561IntegrationTime = $hash->{tsl2561IntegrationTime};
my $integrationTime = 0.402; # 402 ms
if ($tsl2561IntegrationTime == TSL2561_INTEGRATIONTIME_13MS) {
$integrationTime = 0.0137; # 13.7 ms
} elsif ($tsl2561IntegrationTime == TSL2561_INTEGRATIONTIME_101MS) {
$integrationTime = 0.101; # 101 ms
}
return $integrationTime;
}
=head2 I2C_TSL2561_SetGain
Title: I2C_TSL2561_SetGain
Function: Adjusts the gain on the TSL2561 (adjusts the sensitivity to light)
Returns: -
Args: named arguments:
-argument1 => hash: $hash hash of device
-argument1 => number: $gain constant for gain
=cut
sub I2C_TSL2561_SetGain($$) {
my ($hash, $gain) = @_;
my $name = $hash->{NAME};
# store the value even if $hash->{tsl2561Package} ist not set (yet). That happens
# during fhem startup.
$hash->{tsl2561Gain} = $gain;
# Enable the device by setting the control bit to 0x03
my $success = 0;
if (!AttrVal($hash->{NAME}, "disable", 0) && defined($hash->{tsl2561Package})) {
my $state = ReadingsVal($name, 'state', '');
if ($state ne STATE_I2C_ERROR) {
# Update the timing register
Log3 $name, 5, "I2C_TSL2561_SetGain: gain " . $gain ;
Log3 $name, 5, "I2C_TSL2561_SetGain: time " . $hash->{tsl2561IntegrationTime};
if (I2C_TSL2561_i2cwrite($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_TIMING, $gain | $hash->{tsl2561IntegrationTime})) {
if (I2C_TSL2561_i2cread($hash, TSL2561_COMMAND_BIT | TSL2561_REGISTER_TIMING, 1)) {
$success = 1;
}
}
}
}
return $success;
}
#
# decode TSL2561 gain into decimal value
# @param device hash
# @return decimal gain factor that was last reported by the TSL2561
#
sub I2C_TSL2561_GetGain($) {
my ($hash) = @_;
my $tsl2561Gain = $hash->{tsl2561Gain};
my $gain = 1;
if (defined($tsl2561Gain) && $tsl2561Gain) {
$gain = 16;
}
return $gain;
}
=head2 I2C_TSL2561_GetLuminosity
Title: I2C_TSL2561_GetLuminosity
Function: Gets the broadband (mixed lighting) and IR only values from the TSL2561, adjusting gain if auto-gain is enabled and calculate luminosity
Returns: luminosity
Args: named arguments:
-argument1 => hash: $hash hash of device
=cut
sub I2C_TSL2561_GetLuminosity($) {
my ($hash) = @_;
my $name = $hash->{NAME};
# Log3 $name, 5, "I2C_TSL2561_GetLuminosity: start";
# Luminosity calculation state machine
my $lux = undef;
my $operations = 0;
while(1) {
$operations++;
Log3 $name, 5, "I2C_TSL2561_GetLuminosity: calc state $hash->{calcState} acqui state $hash->{acquiState}";
if ($hash->{calcState} == CALC_STATE_ERROR) {
$hash->{calcState} = CALC_STATE_IDLE;
Log3 $name, 5, "I2C_TSL2561_GetLuminosity: error, aborting";
last; # Abort, start again at next slow poll
} elsif ($operations > 10) {
# Too many consecutive operations, abort
$hash->{calcState} = CALC_STATE_ERROR;
Log3 $name, 5, "I2C_TSL2561_GetLuminosity: state machine stuck, aborting";
} elsif ($hash->{calcState} == CALC_STATE_IDLE) {
# Request data
Log3 $name, 5, "I2C_TSL2561_GetLuminosity: starting new measurement";
if (!I2C_TSL2561_GetData($hash)) {
$hash->{calcState} = CALC_STATE_ERROR;
}
} elsif ($hash->{calcState} == CALC_STATE_DATA_REQUESTED) {
# Wait for data
if (I2C_TSL2561_GetData($hash)) {
if ($hash->{acquiState} == ACQUI_STATE_ENABLED) {
last; # Wait for data to arrive, check again at next fast poll
}
} else {
$hash->{calcState} = CALC_STATE_ERROR;
}
} elsif ($hash->{calcState} == CALC_STATE_DATA_RECEIVED) {
# Data was received, optimize gain
my $autoGain = AttrVal($name, 'autoGain', 1);
if ($autoGain) {
# Get the hi/low threshold for the current integration time
my $it = $hash->{tsl2561IntegrationTime};
my $hi = TSL2561_AGC_THI_402MS;
my $lo = TSL2561_AGC_TLO_402MS;
if ($it==TSL2561_INTEGRATIONTIME_13MS) {
$hi = TSL2561_AGC_THI_13MS;
$lo = TSL2561_AGC_TLO_13MS;
} elsif ( $it==TSL2561_INTEGRATIONTIME_101MS) {
$hi = TSL2561_AGC_THI_101MS;
$lo = TSL2561_AGC_TLO_101MS;
}
if (($hash->{broadband} < $lo) && ($hash->{tsl2561Gain} == TSL2561_GAIN_1X)) {
# Increase gain and try again
I2C_TSL2561_SetGain($hash, TSL2561_GAIN_16X);
# Drop the previous conversion results
$hash->{calcState} = CALC_STATE_IDLE;
next;
} elsif (($hash->{broadband} > $hi) && ($hash->{tsl2561Gain} == TSL2561_GAIN_16X)) {
# Drop gain and try again
I2C_TSL2561_SetGain($hash, TSL2561_GAIN_1X);
# Drop the previous conversion results
$hash->{calcState} = CALC_STATE_IDLE;
next;
} else {
# Reading is either valid, or we're already at the chips limits
}
} else {
# Auto gain disabled, always valid
}
# Optimize integration time (make sure the sensor isn't saturated at 402 ms)
my $clipThreshold = 0;
if ($hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_13MS) {
$clipThreshold = TSL2561_CLIPPING_13MS;
} elsif ($hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_101MS) {
$clipThreshold = TSL2561_CLIPPING_101MS;
} else {
$clipThreshold = TSL2561_CLIPPING_402MS;
}
my $autoIntegrationTime = AttrVal($name, 'autoIntegrationTime', 0);
if (($hash->{broadband} > $clipThreshold) || ($hash->{ir} > $clipThreshold)) {
# ADC saturated, try to decrease integration time
if ($autoIntegrationTime && $hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_402MS) {
# Drop integration time and try again
I2C_TSL2561_SetIntegrationTime($hash, TSL2561_INTEGRATIONTIME_101MS);
# Drop the previous conversion results
$hash->{calcState} = CALC_STATE_IDLE;
next;
} else {
# Integration time fixed or already below 402 ms, give up
$hash->{saturated} = 1;
}
} elsif ($autoIntegrationTime
&& ($hash->{broadband} < ($clipThreshold >> 2) && $hash->{ir} < ($clipThreshold >> 2))
&& ($hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_13MS || $hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_101MS)) {
# Integration time below 178 ms, maximize
I2C_TSL2561_SetIntegrationTime($hash, TSL2561_INTEGRATIONTIME_402MS);
# Drop the previous conversion results
$hash->{calcState} = CALC_STATE_IDLE;
next;
} else {
# Readings are not saturated or auto integration time is disabled
$hash->{saturated} = 0;
}
# Received data is valid, calculate luminosity
$lux = I2C_TSL2561_CalculateLux($hash);
$hash->{calcState} = CALC_STATE_IDLE;
last; # Done, start again at next slow poll
} else {
# Undefined state
$hash->{calcState} = CALC_STATE_ERROR;
}
}
# Log3 $name, 5, "I2C_TSL2561_GetLuminosity: end";
return $lux;
}
# get channel scale
sub I2C_TSL2561_GetChannelScale($) {
my ($hash) = @_;
my $name = $hash->{NAME};
my $chScale = 0;
if (AttrVal($name, 'floatArithmetics', 0)) {
# Get the correct scale depending on the integration time
if (!defined($hash->{tsl2561IntegrationTime})) {
$chScale = 1.0;
} elsif ($hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_13MS) {
$chScale = 322.0/11;
} elsif ($hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_101MS) {
$chScale = 322.0/81;
} else {
$chScale = 1.0;
}
# Scale for gain (1x or 16x)
if (!defined($hash->{tsl2561Gain}) || !$hash->{tsl2561Gain}) {
$chScale = $chScale*16;
}
} else {
# Get the correct scale depending on the integration time
if ($hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_13MS) {
$chScale = TSL2561_LUX_CHSCALE_TINT0;
} elsif ($hash->{tsl2561IntegrationTime} == TSL2561_INTEGRATIONTIME_101MS) {
$chScale = TSL2561_LUX_CHSCALE_TINT1;
} else {
$chScale = (1 << TSL2561_LUX_CHSCALE);
}
# Scale for gain (1x or 16x)
if (!defined($hash->{tsl2561Gain}) || !$hash->{tsl2561Gain}) {
$chScale = $chScale << 4;
}
}
return $chScale;
}
=head2 I2C_TSL2561_CalculateLux
Title: I2C_TSL2561_CalculateLux
Function: Converts the raw sensor values to the standard SI lux equivalent. Returns 0 if the sensor is saturated and the values are unreliable.
Returns: number
Args: named arguments:
-argument1 => hash: $hash hash of device
=cut
sub I2C_TSL2561_CalculateLux($) {
my ($hash) = @_;
my $name = $hash->{NAME};
# Get the correct scale depending on gain and integration time
my $chScale = I2C_TSL2561_GetChannelScale($hash);
if (AttrVal($name, 'floatArithmetics', 0)) {
# Scale the channel values
my $channel0 = $chScale*$hash->{broadband};
my $channel1 = $chScale*$hash->{ir};
# Find the ratio of the channel values (Channel1/Channel0)
my $ratio = 0.0;
if ($channel0 != 0) {
$ratio = $channel1/$channel0;
}
# Calculate luminosity (see TSL2561 data sheet)
my $lux = undef;
if ($hash->{tsl2561Package} == TSL2561_PACKAGE_CS) {
# CS package
if ($ratio <= 0.52) {
$lux = 0.0315*$channel0 - 0.0593*$channel1*pow($ratio, 1.4);
} elsif ($ratio <= 0.65) {
$lux = 0.0229*$channel0 - 0.0291*$channel1;
} elsif ($ratio <= 0.80) {
$lux = 0.0157*$channel0 - 0.0180*$channel1;
} elsif ($ratio <= 1.30) {
$lux = 0.00338*$channel0 - 0.00260*$channel1;
} else {
$lux = 0.0;
}
} else {
# T, FN and CL package
if ($ratio <= 0.50) {
$lux = 0.0304*$channel0 - 0.062*$channel1*pow($ratio, 1.4);
} elsif ($ratio <= 0.61) {
$lux = 0.0224*$channel0 - 0.031*$channel1;
} elsif ($ratio <= 0.80) {
$lux = 0.0128*$channel0 - 0.0153*$channel1;
} elsif ($ratio <= 1.30) {
$lux = 0.00146*$channel0 - 0.00112*$channel1;
} else {
$lux = 0.0;
}
}
if ($lux >= 100) {
# Round to 3 significant digits if at least 100
my $roundFactor = 10**(floor(log($lux)/log(10)) - 2);
$lux = $roundFactor*floor($lux/$roundFactor + 0.5);
} else {
# Round to 1 fractional digit if less than 100
$lux = floor(10*$lux + 0.5)/10;
}
return $lux;
} else {
# Scale the channel values
my $channel0 = ($hash->{broadband} * $chScale) >> TSL2561_LUX_CHSCALE;
my $channel1 = ($hash->{ir} * $chScale) >> TSL2561_LUX_CHSCALE;
# Find the ratio of the channel values (Channel1/Channel0)
my $ratio1 = 0;
if ($channel0 != 0) {
$ratio1 = ($channel1 << (TSL2561_LUX_RATIOSCALE+1)) / $channel0;
}
# round the ratio value
my $ratio = ($ratio1 + 1) >> 1;
my $b=0;
my $m=0;
if ($hash->{tsl2561Package} == TSL2561_PACKAGE_CS) {
# CS package
if (($ratio >= 0) && ($ratio <= TSL2561_LUX_K1C)) {
$b=TSL2561_LUX_B1C;
$m=TSL2561_LUX_M1C;
} elsif ($ratio <= TSL2561_LUX_K2C) {
$b=TSL2561_LUX_B2C;
$m=TSL2561_LUX_M2C;
} elsif ($ratio <= TSL2561_LUX_K3C) {
$b=TSL2561_LUX_B3C;
$m=TSL2561_LUX_M3C;
} elsif ($ratio <= TSL2561_LUX_K4C) {
$b=TSL2561_LUX_B4C;
$m=TSL2561_LUX_M4C;
} elsif ($ratio <= TSL2561_LUX_K5C) {
$b=TSL2561_LUX_B5C;
$m=TSL2561_LUX_M5C;
} elsif ($ratio <= TSL2561_LUX_K6C) {
$b=TSL2561_LUX_B6C;
$m=TSL2561_LUX_M6C;
} elsif ($ratio <= TSL2561_LUX_K7C) {
$b=TSL2561_LUX_B7C;
$m=TSL2561_LUX_M7C;
} elsif ($ratio > TSL2561_LUX_K8C) {
$b=TSL2561_LUX_B8C;
$m=TSL2561_LUX_M8C;
}
} elsif ($hash->{tsl2561Package} == TSL2561_PACKAGE_T_FN_CL) {
# T, FN and CL package
if (($ratio >= 0) && ($ratio <= TSL2561_LUX_K1T)) {
$b=TSL2561_LUX_B1T;
$m=TSL2561_LUX_M1T;
} elsif ($ratio <= TSL2561_LUX_K2T) {
$b=TSL2561_LUX_B2T;
$m=TSL2561_LUX_M2T;
} elsif ($ratio <= TSL2561_LUX_K3T) {
$b=TSL2561_LUX_B3T;
$m=TSL2561_LUX_M3T;
} elsif ($ratio <= TSL2561_LUX_K4T) {
$b=TSL2561_LUX_B4T;
$m=TSL2561_LUX_M4T;
} elsif ($ratio <= TSL2561_LUX_K5T) {
$b=TSL2561_LUX_B5T;
$m=TSL2561_LUX_M5T;
} elsif ($ratio <= TSL2561_LUX_K6T) {
$b=TSL2561_LUX_B6T;
$m=TSL2561_LUX_M6T;
} elsif ($ratio <= TSL2561_LUX_K7T) {
$b=TSL2561_LUX_B7T;
$m=TSL2561_LUX_M7T;
} elsif ($ratio > TSL2561_LUX_K8T) {
$b=TSL2561_LUX_B8T;
$m=TSL2561_LUX_M8T;
}
}
my $temp = (($channel0 * $b) - ($channel1 * $m));
# Do not allow negative lux value
if ($temp < 0) {
$temp = 0;
}
# Round lsb (2^(LUX_SCALE-1))
$temp += (1 << (TSL2561_LUX_LUXSCALE-1));
# Strip off fractional portion
my $lux = $temp >> TSL2561_LUX_LUXSCALE;
# Signal I2C had no errors
return $lux;
}
}
sub I2C_TSL2561_i2cread($$$) {
my ($hash, $reg, $nbyte) = @_;
my $success = 1;
local $SIG{__WARN__} = sub {
my $message = shift;
# turn warnings from RPII2C_HWACCESS_ioctl into exception
if ($message =~ /Exiting subroutine via last at.*00_RPII2C.pm/) {
die;
} else {
warn($message);
}
};
if ($hash->{HiPi_used}) {
eval {
my @values = $hash->{devTSL2561}->bus_read($reg, $nbyte);
I2C_TSL2561_I2CRec($hash, {
direction => "i2cread",
i2caddress => $hash->{I2C_Address},
reg => $reg,
nbyte => $nbyte,
received => join (' ',@values),
});
};
Log3 ($hash, 1, $hash->{NAME} . ': ' . I2C_TSL2561_Catch($@)) if $@;
} elsif (defined (my $iodev = $hash->{IODev})) {
eval {
CallFn($iodev->{NAME}, "I2CWrtFn", $iodev, {
direction => "i2cread",
i2caddress => $hash->{I2C_Address},
reg => $reg,
nbyte => $nbyte
});
};
if ($hash->{$iodev->{NAME}.'_SENDSTAT'} eq 'error') {
readingsSingleUpdate($hash, 'state', STATE_I2C_ERROR, 1);
$success = 0;
}
} else {
Log3 ($hash, 1, $hash->{NAME} . ': ' . "no IODev assigned to '$hash->{NAME}'");
$success = 0;
}
return $success;
}
sub I2C_TSL2561_i2cwrite($$$) {
my ($hash, $reg, @data) = @_;
my $success = 1;
if ($hash->{HiPi_used}) {
eval {
$hash->{devTSL2561}->bus_write($reg, join (' ',@data));
I2C_TSL2561_I2CRec($hash, {
direction => "i2cwrite",
i2caddress => $hash->{I2C_Address},
reg => $reg,
data => join (' ',@data),
});
};
Log3 ($hash, 1, $hash->{NAME} . ': ' . I2C_TSL2561_Catch($@)) if $@;
} elsif (defined (my $iodev = $hash->{IODev})) {
eval {
CallFn($iodev->{NAME}, "I2CWrtFn", $iodev, {
direction => "i2cwrite",
i2caddress => $hash->{I2C_Address},
reg => $reg,
data => join (' ',@data),
});
};
if ($hash->{$iodev->{NAME}.'_SENDSTAT'} eq 'error') {
readingsSingleUpdate($hash, 'state', STATE_I2C_ERROR, 1);
$success = 0;
}
} else {
Log3 ($hash, 1, $hash->{NAME} . ': ' . "no IODev assigned to '$hash->{NAME}'");
$success = 0;
}
return $success;
}
1;
=pod
=begin html
<a name="I2C_TSL2561"></a>
<h3>I2C_TSL2561</h3>
<ul>
<a name="I2C_TSL2561"></a>
<p>
With this module you can read values from the ambient light sensor TSL2561
via the i2c bus on Raspberry Pi.<br>
The luminosity value returned is a good human eye reponse approximation of an
illumination measurement in the range of 0.1 to 40000+ lux (but not a replacement for a
precision measurement, relation between measured value and true value may vary by 40%).
<br><br>
<b>There are two possibilities connecting to I2C bus:</b><br>
<ul>
<li><b>via IODev module</b><br>
The I2C messages are send through an I2C interface module like <a href="#RPII2C">RPII2C</a>, <a href="#FRM">FRM</a>
or <a href="#NetzerI2C">NetzerI2C</a> so this device must be defined first.<br>
<b>attribute IODev must be set</b><br>
<br>
</li>
<li><b>via HiPi library</b><br>
Add these two lines to your <b>/etc/modules</b> file to load the I2C relevant kernel modules
automaticly during booting your Raspberry Pi.<br>
<code><pre>
i2c-bcm2708
i2c-dev
</pre></code>
Install HiPi perl modules:<br>
<code><pre> wget http://raspberry.znix.com/hipifiles/hipi-install perl hipi-install</pre></code>
To change the permissions of the I2C device create file:<br>
<code><pre> /etc/udev/rules.d/98_i2c.rules</pre></code>
with this content:<br>
<code><pre> SUBSYSTEM=="i2c-dev", MODE="0666"</pre></code>
<b>Reboot</b><br>
<br>
To use the sensor on the second I2C bus at P5 connector
(only for version 2 of Raspberry Pi) you must add the bold
line of following code to your FHEM start script:
<code><pre>
case "$1" in
'start')
<b>sudo hipi-i2c e 0 1</b>
...
</pre></code>
</li>
</ul>
<p>
<b>Define</b>
<ul>
<code>define TSL2561 I2C_TSL2561 [&lt;I2C device&gt;] &lt;I2C address&gt</code><br><br>
&lt;I2C device&gt; mandatory for HiPi, must be omitted if you connect via IODev<br>
&lt;I2C address&gt; may be 0x29, 0x39 or 0x49 (and 'AUTO' when using IODev to search for device at startup and after an I2C error)<br>
<br>
Examples:
<pre>
define TSL2561 I2C_TSL2561 /dev/i2c-0 0x39
attr TSL2561 poll_interval 5
</pre>
<pre>
define TSL2561 I2C_TSL2561 0x39
attr TSL2561 IODev I2CModule
attr TSL2561 poll_interval 5
</pre>
<pre>
define TSL2561 I2C_TSL2561 AUTO
attr TSL2561 IODev I2CModule
attr TSL2561 poll_interval 5
</pre>
</ul>
<b>Set</b>
<ul>
<code>get &lt;name&gt; update</code><br><br>
Force immediate illumination measurement and restart a new poll_interval.<br><br>
Note that the new readings are not yet available after set returns because the
measurement is performed asynchronously. Depending on the attributes integration time,
autoGain and autoIntegrationTime this may require more than one second to complete.
</ul>
<p>
<b>Readings</b>
<ul>
<li>luminosity<br>
Good human eye reponse approximation of an illumination measurement in the range of 0.1 to 40000+ lux.<br>
Rounded to 3 significant digits or one fractional digit.
</li>
<li>broadband<br>
Broadband spectrum sensor sample.<br>
Enable attribute normalizeRawValues for continuous readings independed of actual gain and integration time settings.
</li>
<li>ir<br>
Infrared spectrum sensor sample.<br>
Enable attribute normalizeRawValues for continuous readings independed of actual gain and integration time settings.
</li>
<li>gain<br>
sensor gain used for current luminosity measurement (1 or 16)<br>
</li>
<li>integrationTime<br>
integration time in seconds used for current luminosity measurement<br>
</li>
<li>state<br>
Default: Initialized, valid values: Undefined, Defined, Initialized, Saturated, Disabled, I2C Error
</li>
</ul>
<p>
<a name="I2C_TSL2561attr"></a>
<b>Attributes</b>
<ul>
<li>IODev<br>
Set the name of an IODev module. If undefined the perl modules HiPi::Device::I2C are required.<br>
Default: undefined<br>
</li>
<li>poll_interval<br>
Set the polling interval in minutes to query the sensor for new measured values.<br>
Default: 5, valid values: 1, 2, 5, 10, 20, 30<br>
</li>
<li>gain<br>
Set gain factor. Attribute will be ignored if autoGain is enabled.<br>
Default: 1, valid values: 1, 16
</li>
<li>integrationTime<br>
Set time in ms the sensor takes to measure the light. Attribute will be ignored if autoIntegrationTime is enabled.<br>
Default: 13, valid values: 13, 101, 402<br>
See this <a href="https://learn.sparkfun.com/tutorials/tsl2561-luminosity-sensor-hookup-guide/using-the-arduino-library">tutorial</a>
for more details.
</li>
<li>autoGain<br>
Enable auto gain. If set to 1, the gain parameter is adjusted automatically depending on light conditions.<br>
Default: 1, valid values: 0, 1<br>
</li>
<li>autoIntegrationTime<br>
Enable auto integration time. If set to 1, the integration time parameter is adjusted automatically depending on light conditions.<br>
Default: 0, valid values: 0, 1<br>
</li>
<li>normalizeRawValues<br>
Scale the sensor raw values broadband and ir depending on actual gain and integrationTime to the equivalent of the settings for maximum sensitivity (gain=16 and integrationTime=403ms). This feature may be useful when autoGain or autoIntegrationTime is enabled to provide continuous values instead of jumping values when gain or integration time changes.<br>
Default: 0, valid values: 0, 1<br>
</li>
<li>floatArithmetics<br>
Enable float arithmetics.<br>
If set to 0, the luminosity is calculated using int arithmetics (for very low powered platforms).<br>
If set to 1, the luminosity is calculated using float arithmetics, yielding some additional precision.
Default: 1, valid values: 0, 1<br>
</li>
<li>disable<br>
Disable I2C bus access.<br>
Default: 0, valid values: 0, 1
</li>
</ul>
<br>
</ul>
=end html
=cut
Reference in New Issue View Git Blame Copy Permalink