Public/fhem-mirror
1
0
Fork 0
mirror of https://github.com/fhem/fhem-mirror.git synced 2024-06-17 05:40:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

20_FRM_I2C.pm: feature update, see forum #114552 msg #1087982

Browse Source 
- init register image before updating received bytes
- moved receive processing from FRM module to FRM_I2C module
- added I2C read function "get register"
- added I2C write function "set register"
- improve live modification of IODev
- issue I2C stop reading command if device is initialized with zero byte count or is deleted
- check for IODev install error in Init, Get, Set, Attr and Undef
- missing get/set argument metadata added
- get/set argument verifier improved
- moved define argument verification and decoding from Init to Define
- error behaviour of Init, Get, Set and Attr standardized
- annotaded module help of attributes for FHEMWEB

git-svn-id: https://svn.fhem.de/fhem/trunk/fhem@23053 2b470e98-0d58-463d-a4d8-8e2adae1ed80
This commit is contained in:
jensb 2020-10-30 17:51:43 +00:00
parent 35ae2fe6f3
commit fb82c7f272
1 changed files with 393 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

485
FHEM/20_FRM_I2C.pm
View File

@ -1,137 +1,438 @@
##############################################
################################################################################
# $Id$
##############################################
################################################################################
=encoding UTF-8
=head1 NAME
FHEM module to read continuously from and to write to a I2C device connected to
a Firmata device
=head1 LICENSE AND COPYRIGHT
Copyright (C) 2013 ntruchess
Copyright (C) 2018 jensb
All rights reserved
This script 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 script 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 script; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
A copy of the GNU General Public License, Version 2 can also be found at
http://www.gnu.org/licenses/old-licenses/gpl-2.0.
This copyright notice MUST APPEAR in all copies of the script!
=cut
package main;
use strict;
use warnings;
#add FHEM/lib to @INC if it's not allready included. Should rather be in fhem.pl than here though...
use Scalar::Util qw(looks_like_number);
#add FHEM/lib to @INC if it's not already included. Should rather be in fhem.pl than here though...
BEGIN {
if (!grep(/FHEM\/lib$/,@INC)) {
foreach my $inc (grep(/FHEM$/,@INC)) {
push @INC,$inc."/lib";
};
};
if (!grep(/FHEM\/lib$/,@INC)) {
foreach my $inc (grep(/FHEM$/,@INC)) {
push @INC,$inc."/lib";
};
};
};
use Device::Firmata::Constants qw/ :all /;
#####################################
sub
FRM_I2C_Initialize($)
# number of arguments
my %sets = (
"register" => 2,
);
# number of arguments
my %gets = (
"register" => 1,
);
sub FRM_I2C_Initialize
{
my ($hash) = @_;
$hash->{DefFn} = "FRM_Client_Define";
$hash->{InitFn} = "FRM_I2C_Init";
$hash->{UndefFn} = "FRM_Client_Undef";
$hash->{AttrFn} = "FRM_I2C_Attr";
$hash->{AttrList} = "IODev $main::readingFnAttributes";
$hash->{DefFn} = "FRM_I2C_Define";
$hash->{InitFn} = "FRM_I2C_Init";
$hash->{UndefFn} = "FRM_I2C_Undef";
$hash->{AttrFn} = "FRM_I2C_Attr";
$hash->{GetFn} = "FRM_I2C_Get";
$hash->{SetFn} = "FRM_I2C_Set";
$hash->{I2CRecFn} = "FRM_I2C_Receive";
$hash->{AttrList} = "IODev $main::readingFnAttributes";
main::LoadModule("FRM");
}
sub
FRM_I2C_Init($)
sub FRM_I2C_Define
{
my ($hash,$args) = @_;
my $u = "wrong syntax: define <name> FRM_I2C address register numbytes";
my ($hash, $def) = @_;
return $u if(int(@$args) < 3);
$hash->{"i2c-address"} = @$args[0];
$hash->{"i2c-register"} = @$args[1];
$hash->{"i2c-bytestoread"} = @$args[2];
# verify define arguments
my $usage = "usage: define <name> FRM_I2C address register numbytes";
eval {
FRM_Client_AssignIOPort($hash);
FRM_Client_FirmataDevice($hash)->i2c_read(@$args[0],@$args[1],@$args[2]);
};
if ($@) {
$@ =~ /^(.*)( at.*FHEM.*)$/;
$hash->{STATE} = "error initializing: ".$1;
return "error initializing '".$hash->{NAME}."': ".$1;
}
my @a = split("[ \t]+", $def);
return $usage if (scalar(@a) < 5);
my $args = [@a[2..scalar(@a)-1]];
return "error calling i2c_read: ".$@ if ($@);
if (! (defined AttrVal($hash->{NAME},"event-min-interval",undef))) {
$main::attr{$hash->{NAME}}{"event-min-interval"} = 5;
}
return undef;
$hash->{I2C_Address} = @$args[0];
$hash->{I2C_READ_REGISTER} = @$args[1];
$hash->{I2C_READ_BYTES} = @$args[2];
my $ret = FRM_Client_Define($hash, $def);
if ($ret) {
return $ret;
}
return undef;
}
sub
FRM_I2C_Attr($$$$) {
my ($command,$name,$attribute,$value) = @_;
my $hash = $main::defs{$name};
sub FRM_I2C_Init
{
my ($hash, $args) = @_;
my $name = $hash->{NAME};
if (defined($main::defs{$name}{IODev_ERROR})) {
return 'Perl module Device::Firmata not properly installed';
}
# stop reading
if ($main::init_done && defined($hash->{IODev})) {
eval {
FRM_Client_FirmataDevice($hash)->i2c_stopreading($hash->{I2C_Address});
};
}
# assign IODev
eval {
if ($command eq "set") {
ARGUMENT_HANDLER: {
$attribute eq "IODev" and do {
if ($main::init_done and (!defined ($hash->{IODev}) or $hash->{IODev}->{NAME} ne $value)) {
FRM_Client_AssignIOPort($hash,$value);
FRM_Init_Client($hash) if (defined ($hash->{IODev}));
}
last;
};
}
}
FRM_Client_AssignIOPort($hash);
};
if ($@) {
$@ =~ /^(.*)( at.*FHEM.*)$/;
$hash->{STATE} = "error setting $attribute to $value: ".$1;
return "cannot $command attribute $attribute to $value for $name: ".$1;
my $ret = FRM_Catch($@);
readingsSingleUpdate($hash, 'state', "error assigning IODev: $ret", 1);
return $ret;
}
# start reading
if ($hash->{I2C_READ_BYTES} > 0) {
eval {
FRM_Client_FirmataDevice($hash)->i2c_read(@$args[0], @$args[1], @$args[2]);
};
if ($@) {
my $ret = FRM_Catch($@);
readingsSingleUpdate($hash, 'state', "error initializing periodic I2C read: $ret", 1);
return $ret;
}
}
readingsSingleUpdate($hash, 'state', 'Initialized', 1);
return undef;
}
sub FRM_I2C_Undef
{
my ($hash, $arg) = @_;
my $name = $hash->{NAME};
# try to stop reading
eval {
FRM_Client_FirmataDevice($hash)->i2c_stopreading($hash->{I2C_Address});
};
return FRM_Client_Undef($hash, $arg);
}
sub FRM_I2C_Attr
{
my ($command, $name, $attribute, $value) = @_;
my $hash = $main::defs{$name};
if (defined ($command)) {
eval {
if ($command eq "set") {
ARGUMENT_HANDLER: {
$attribute eq "IODev" and do {
if ($main::init_done) {
# stop reading on old IODev
if (defined($hash->{IODev}) && $hash->{IODev}->{NAME} ne $value) {
if (defined($main::defs{$name}{IODev_ERROR})) {
die 'Perl module Device::Firmata not properly installed';
}
eval {
FRM_Client_FirmataDevice($hash)->i2c_stopreading($hash->{I2C_Address});
};
}
# assign new IODev and init FRM client
if (!defined($hash->{IODev}) || $hash->{IODev}->{NAME} ne $value) {
FRM_Client_AssignIOPort($hash, $value);
if (!defined($hash->{IODev}) || $hash->{IODev}->{NAME} ne $value) {
die "$value not valid";
}
FRM_Init_Client($hash) if (defined ($hash->{IODev}));
}
}
last;
};
}
}
};
if ($@) {
my $ret = FRM_Catch($@);
$hash->{STATE} = "$command $attribute error: " . $ret;
return $hash->{STATE};
}
} else {
return "no command specified";
}
}
sub FRM_I2C_Get
{
my ($hash, $name, $cmd, @a) = @_;
return "get command missing" if(!defined($cmd));
return "unknown get command '$cmd', choose one of " . join(" ", sort keys %gets) if(!defined($gets{$cmd}));
my @match = grep( $_ =~ /^$cmd($|:)/, keys %gets );
return "$cmd requires at least $gets{$match[0]} number as argument" unless (@a >= $gets{$match[0]});
if ($cmd eq 'register') {
my $usage = "usage: get $name register &lt;register&gt; [&lt;bytes-to-read&gt;]";
if (scalar(@a) == 1 || scalar(@a) == 2) {
my $register = shift @a;
my $numberOfBytes = scalar(@a) == 2? shift @a : 1;
if (looks_like_number($register) && $register >= 0 && looks_like_number($numberOfBytes) && $numberOfBytes > 0) {
my $iodev = $hash->{IODev};
my %package = (direction => 'i2cread',
i2caddress => $hash->{I2C_Address},
reg => $register,
nbyte => $numberOfBytes
);
eval {
CallFn($iodev->{NAME}, 'I2CWrtFn', $iodev, \%package);
};
if ($@) {
my $ret = FRM_Catch($@);
$hash->{STATE} = "get $cmd error: " . $ret;
return $hash->{STATE};
}
my $sendStat = $package{$iodev->{NAME} . '_SENDSTAT'};
if (defined($sendStat) && $sendStat ne 'Ok') {
return "get $cmd $register failed: $sendStat";
}
} else {
return $usage;
}
} else {
return $usage;
}
}
return undef;
}
sub FRM_I2C_Set
{
my ($hash, $name, $cmd, @a) = @_;
return "set command missing" if(!defined($cmd));
return "unknown set command '$cmd', choose one of " . join(" ", sort keys %sets) if(!defined($sets{$cmd}));
my @match = grep( $_ =~ /^$cmd($|:)/, keys %sets );
return "$cmd requires at least $sets{$match[0]} numbers as arguments" unless (@a >= $sets{$match[0]});
if (defined($main::defs{$name}{IODev_ERROR})) {
return 'Perl module Device::Firmata not properly installed';
}
if ($cmd eq 'register') {
my $usage = "usage: set $name register <register> <byte> [<byte> ... <byte>]";
my $register = shift @a;
if (looks_like_number($register) && $register >= 0 && looks_like_number($a[0]) && $a[0] >= 0) {
my $iodev = $hash->{IODev};
my %package = (direction => 'i2cwrite',
i2caddress => $hash->{I2C_Address},
reg => $register,
data => join(' ', @a)
);
eval {
CallFn($iodev->{NAME}, 'I2CWrtFn', $iodev, \%package);
};
if ($@) {
my $ret = FRM_Catch($@);
$hash->{STATE} = "set $cmd error: " . $ret;
return $hash->{STATE};
}
my $sendStat = $package{$iodev->{NAME} . '_SENDSTAT'};
if (defined($sendStat) && $sendStat ne 'Ok') {
return "set $cmd $register failed: $sendStat";
}
} else {
return $usage;
}
}
return undef;
}
sub FRM_I2C_Receive
{
my ($hash, $clientmsg) = @_;
my $name = $hash->{NAME};
my $iodevName = $hash->{IODev}->{NAME};
my $sendStat = defined($iodevName) && defined($clientmsg->{$iodevName . '_SENDSTAT'})? $clientmsg->{$iodevName . '_SENDSTAT'} : '?';
if ($sendStat ne 'Ok') {
readingsBeginUpdate($hash);
readingsBulkUpdateIfChanged($hash, 'state', "error: $sendStat", 1);
readingsEndUpdate($hash, 1);
} elsif (defined($clientmsg->{direction}) && $clientmsg->{direction} eq 'i2cread' &&
defined($clientmsg->{reg}) && defined($clientmsg->{received})) {
my @raw = split(' ', $clientmsg->{received});
my @values = split(' ', ReadingsVal($name, 'values', ''));
while (scalar(@values) < 256) {
push(@values, 0);
}
splice(@values, $clientmsg->{reg}, scalar(@raw), @raw);
readingsBeginUpdate($hash);
readingsBulkUpdate($hash, 'values', join (' ', @values), 1);
readingsBulkUpdateIfChanged($hash, 'state', 'active', 1);
readingsEndUpdate($hash, 1);
}
return undef;
}
1;
=pod
=head1 CHANGES
28.12.2018 jensb
o moved I2C receive processing from FRM module to FRM_I2C module
o added I2C read function "get register"
o added I2C write function "set register"
o improve live modification of IODev
23.12.2018 jensb
o issue I2C stop reading command if device is initialized with zero byte count or is deleted
o updated module help
24.08.2020 jensb
o check for IODev install error in Init, Set, Attr and Undef
o prototypes removed
o moved define argument verification and decoding from Init to Define
19.10.2020 jensb
o annotaded module help of attributes for FHEMWEB
=cut
=pod
=head1 FHEM COMMANDREF METADATA
=over
=item device
=item summary Firmata: read/write I2C register
=item summary_DE Firmata: I2C Register lesen/schreiben
=back
=head1 INSTALLATION AND CONFIGURATION
=begin html
<a name="FRM_I2C"></a>
<a name="FRM_I2C"/>
<h3>FRM_I2C</h3>
<ul>
represents an integrated curcuit connected to the i2c-pins of an <a href="http://www.arduino.cc">Arduino</a>
running <a href="http://www.firmata.org">Firmata</a><br>
Requires a defined <a href="#FRM">FRM</a>-device to work.<br>
this FRM-device has to be configures for i2c by setting attr 'i2c-config' on the FRM-device<br>
it reads out the ic-internal storage in intervals of 'sampling-interval' as set on the FRM-device<br><br>
<a name="FRM_I2Cdefine"></a>
<b>Define</b>
This module provides read and write capabilities for an I2C device that is wired to a <a href="http://www.firmata.org">Firmata device</a>. It requires a defined <a href="#FRM">FRM</a> device to work. I2C bus support must be enabled on the FRM device by setting the attribute <code>i2c-config</code> to a valid value.<br><br>
If periodic reading is enabled the requested bytes will be updated depending on the attribute <code>sampling-interval</code> of the FRM device as soon as the Firmata device is connected.<br><br>
<a name="FRM_I2Cdefine"/>
<b>Define</b><br><br>
<code>define &lt;name&gt; FRM_I2C &lt;i2c-address&gt; &lt;register&gt; &lt;bytes-to-read&gt;</code> <br><br>
<ul>
<code>define &lt;name&gt; FRM_I2C &lt;i2c-address&gt; &lt;register&gt; &lt;bytes-to-read&gt;</code> <br>
Specifies the FRM_I2C device.<br>
<li>i2c-address is the (device-specific) address of the ic on the i2c-bus</li>
<li>register is the (device-internal) address to start reading bytes from.</li>
<li>bytes-to-read is the number of bytes read from the ic</li>
</ul>
<br>
<a name="FRM_I2Cset"></a>
<b>Set</b><br>
<ul>
N/A<br>
</ul>
<a name="FRM_I2Cget"></a>
<li>i2c-address is the I2C bus address (decimal) of the I2C device</li>
<li>register is the I2C register address (decimal) to start reading bytes from</li>
<li>bytes-to-read is the number of bytes to read periodically from the I2C device, the maximum number of bytes that can be read at the same time is limited by the Firmata firmware, the I2C device capabilities and the <code>sampling-interval</code> attribute of the FRM device, set to zero to disable periodic reading</li>
</ul><br>
<a name="FRM_I2Cget"/>
<b>Get</b><br>
<ul>
N/A<br>
<li><code>register &lt;register&gt; [&lt;bytes-to-read&gt;]</code><br>
request single asynchronous read of the specified number of bytes from the I2C register<br>
bytes-to-read defaults to 1 if not specified, the maximum number of bytes that can be read at the same time is limited by the Firmata firmware and the I2C device capabilities
</li>
</ul><br>
<a name="FRM_I2Cattr"></a>
<a name="FRM_I2Cset"/>
<b>Set</b><br>
<ul>
<li><code>register &lt;register&gt; &lt;byte&gt; [&lt;byte&gt; ... &lt;byte&gt;]</code><br>
write the space separated list of byte values to the specified I2C register
</li>
</ul><br>
<a name="FRM_I2Cattr"/>
<b>Attributes</b><br>
<ul>
<li><a href="#IODev">IODev</a><br>
Specify which <a href="#FRM">FRM</a> to use. (Optional, only required if there is more
than one FRM-device defined.)
</li>
<li><a href="#eventMap">eventMap</a><br></li>
<li><a href="#readingFnAttributes">readingFnAttributes</a><br></li>
</ul>
<a name="IODev"/>
<li><a href="#IODev">IODev</a><br>
Specify which <a href="#FRM">FRM</a> to use. Only required if there is more than one FRM-device defined.
</li>
<li><a href="#attributes">global attributes</a></li>
<li><a href="#readingFnAttributes">readingFnAttributes</a></li>
</ul><br>
<a name="FRM_I2Creadings"/>
<b>Readings</b><br>
<ul>
<li>values<br>
space separated list of 256 byte register image using decimal values - may be preset to any value, only the requested bytes will be updated
</li>
</ul>
<br>
</ul><br>
=end html
=begin html_DE
<a name="FRM_I2C"/>
<h3>FRM_I2C</h3>
<ul>
Die Modulbeschreibung von FRM_I2C gibt es nur auf <a href="commandref.html#FRM_I2C">Englisch</a>. <br>
</ul> <br>
=end html_DE
=cut