diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 0000000..85c0f6e --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1 @@ +Anybody willing to contribute is very welcome! Please submit pull-requests against branch 'master' at https://github.com/ntruchsess/perl-firmata. diff --git a/Changes b/Changes index ad310d6..5d2d168 100644 --- a/Changes +++ b/Changes @@ -1,15 +1,19 @@ Revision history for Device-Firmata -0.64 2018.01.03 - Jens Beyer +0.65 2018.06.09 - Jens B. + fix push on reference in method attach of Device::Firmata::IO::NetIO + added and updated POD + +0.64 2018.01.03 - Jens B. support Firmata protocol version 2.5 feature PIN_PULLUP (Constants, Platform, Protocol) -0.63 2016.03.19 - Jens Beyer +0.63 2016.03.19 - Jens B. supported protocol version detection modified (Protocol) -0.62 2016.02.22 - Jens Beyer +0.62 2016.02.22 - Jens B. added software serial support (Platform, Protocol) -0.61 2016.01.09 - Jens Beyer +0.61 2016.01.09 - Jens B. added serial pin support (Platform, Protocol, Constants) added protocol version query (Platform) fixed messages_handle: REPORT_VERSION returns protocol version (Platform) diff --git a/LICENSE b/LICENSE index 0a0e82f..6a9e3ba 100644 --- a/LICENSE +++ b/LICENSE @@ -1,10 +1,10 @@ COPYRIGHT AND LICENSE -Copyright (C) 2010 amimato -Copyright (C) 2012 ntruchsess -Copyright (C) 2016 jnsbyr +Copyright (C) 2010 Aki Mimoto +Copyright (C) 2012 Norbert Truchsess +Copyright (C) 2016 Jens B. -This is free software; you can redistribute it and/or modify it under -the same terms as the Perl 5 programming language system itself. +This is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. See http://dev.perl.org/licenses/ for more information. diff --git a/MANIFEST b/MANIFEST index 6acfd86..6e449dd 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1,4 +1,6 @@ Changes +CONTRIBUTING +dist.ini environment ignore.txt LICENSE diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP index ce18b4f..ddcd5c8 100644 --- a/MANIFEST.SKIP +++ b/MANIFEST.SKIP @@ -1 +1,2 @@ -^.*~$ \ No newline at end of file +^.*~$ +MANIFEST.SKIP diff --git a/Makefile.PL b/Makefile.PL index 618fb29..63df8a4 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -38,6 +38,7 @@ WriteMakefile( }, META_MERGE => { 'meta-spec' => { version => 2 }, + homepage => 'https://github.com/ntruchsess/perl-firmata/', resources => { repository => { type => 'git', diff --git a/README b/README index ff6b807..b68505b 100644 --- a/README +++ b/README @@ -11,36 +11,43 @@ To install this module, run the following commands: make test make install + SUPPORT AND DOCUMENTATION After installing, you can find documentation for this module with the perldoc command. perldoc Device::Firmata + +You will find a web presentation on "Controlling an Arduino with Perl" +at file://presentation/index.html. -You can also look for information at: +The folder "example" holds more than 15 Perl example applications for +various Firmata IO implementations incl. I2C and 1-Wire. - RT, CPAN's request tracker - http://rt.cpan.org/NoAuth/Bugs.html?Dist=Device-Firmata +You can also look for information at: AnnoCPAN, Annotated CPAN documentation http://annocpan.org/dist/Device-Firmata + Search meta::cpan + https://metacpan.org/release/Device-Firmata + + RT, CPAN's request tracker + http://rt.cpan.org/NoAuth/Bugs.html?Dist=Device-Firmata + CPAN Ratings http://cpanratings.perl.org/d/Device-Firmata - Search CPAN - http://search.cpan.org/dist/Device-Firmata/ - COPYRIGHT AND LICENSE -Copyright (C) 2010 amimato -Copyright (C) 2012 ntruchsess -Copyright (C) 2016 jnsbyr +Copyright (C) 2010 Aki Mimoto +Copyright (C) 2012 Norbert Truchsess +Copyright (C) 2016 Jens B. -This is free software; you can redistribute it and/or modify it under -the same terms as the Perl 5 programming language system itself. +This is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. See http://dev.perl.org/licenses/ for more information. diff --git a/dist.ini b/dist.ini index 0045670..6cf1036 100644 --- a/dist.ini +++ b/dist.ini @@ -4,7 +4,7 @@ license = Perl_5 copyright_holder = Aki Mimoto, Norbert Truchsess, Jens B. copyright_year = 2010 -version = 0.64 +version = 0.65 [GatherDir] [MetaYAML] diff --git a/lib/Device/Firmata.pm b/lib/Device/Firmata.pm index 751d309..9eb6e95 100644 --- a/lib/Device/Firmata.pm +++ b/lib/Device/Firmata.pm @@ -11,15 +11,17 @@ use Device::Firmata::Base =head1 NAME -Device::Firmata - Perl interface to Firmata for the arduino platform. +Device::Firmata - A Perl implementation of the Firmata protocol. + +This module allows a computer running Perl to connect to Firmata devices (Arduinos and compatible, including ESP8266), either via serial IO (RS-232, USB, etc.) or TCP/IP (LAN, WiFi). Protocol details can be found at L. =head1 VERSION -Version 0.64 +Version 0.65 =cut -our $VERSION = '0.64'; +our $VERSION = '0.65'; our $DEBUG = 0; @@ -46,11 +48,11 @@ our $DEBUG = 0; sleep 0.5; } -=head1 SUBROUTINES/METHODS +=head1 METHODS -=head2 open(serialPort) +=head2 open ( serialPort , [opts] ) -Establish a serial connection with an Arduino micro-controller. The first argument is the name of the serial device mapped to the arduino, e.g. '/dev/ttyUSB0' or 'COM9'. +Establish a serial connection with a Firmata device. The first parameter is the name of the serial device connected with the Firmata device, e.g. '/dev/ttyUSB0' or 'COM9'. The second parameter is an optional hash of parameters for the serial port. The parameter C is supported and defaults to C<57600>. Returns a L object. =cut @@ -74,9 +76,9 @@ sub open { return $platform; } -=head2 listen(host, port) +=head2 listen ( host, port ) -Start a TCP server bound to given local address and port for the arduino to connect to. +Start a TCP server bound to given local address and port for the Arduino to connect to. Returns a L object. An implementation example can be found in file F. =cut @@ -92,16 +94,26 @@ sub listen { return $netio->listen( $ip, $port, $opts ) || die "Could not bind to socket"; } +=head1 EXAMPLES + +In the folder F you will find more than 15 implementation examples for various Firmata IO operations including digital I/O, PWM, stepper and encoder as well as bus I/O for I2C and 1-Wire. + +=head1 SEE ALSO + +L + =head1 LICENSE - Copyright (C) 2010 amimato - Copyright (C) 2012 ntruchsess - Copyright (C) 2016 jnsbyr +Copyright (C) 2010 Aki Mimoto + +Copyright (C) 2012 Norbert Truchsess + +Copyright (C) 2016 Jens B. - This is free software; you can redistribute it and/or modify it under - the same terms as the Perl 5 programming language system itself. +This is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. - See http://dev.perl.org/licenses/ for more information. +See http://dev.perl.org/licenses/ for more information. =cut diff --git a/lib/Device/Firmata/IO/NetIO.pm b/lib/Device/Firmata/IO/NetIO.pm index 46d8e40..f87c2c9 100644 --- a/lib/Device/Firmata/IO/NetIO.pm +++ b/lib/Device/Firmata/IO/NetIO.pm @@ -1,8 +1,8 @@ package Device::Firmata::IO::NetIO; -=head1 NAME +=head1 Device::Firmata::IO::NetIO -Device::Firmata::IO::NetIO - implement the low level TCP/IP IO +Implements the low level TCP/IP server socket IO. =cut @@ -17,8 +17,11 @@ use Device::Firmata::Base FIRMATA_ATTRIBS => { }; +=head2 METHODS -=head2 listen +=head3 listen ( host, port ) + +Start a TCP server bound to given local address and port for the Firmata device to connect to. Returns a C object. Typically called by method C of L. An implementation example can be found in file F. =cut @@ -47,6 +50,12 @@ sub listen { return $self; } +=head3 accept ( timeout ) + +Wait until timeout seconds for an Firmata device to connect. Returns a L object on success or C. An implementation example can be found in file F. + +=cut + sub accept { my ($self,$timeout) = @_; @@ -70,6 +79,12 @@ sub accept { return undef; } +=head3 close ( ) + +Closes the TCP server socket and disconnects all Firmata devices. An implementation example can be found in file F. + +=cut + sub close { my $self = shift; if ($self->{'select'} && $self->{'socket'}) { @@ -88,19 +103,25 @@ sub close { } } +=head3 attach ( connectedSocket ) + +Assign a connected L as IO port and return a L object. Typically used internally by the C method. + +=cut + sub attach { - my ( $pkg, $client_socket, $opts ) = @_; + my ( $pkg, $client_socket, $opts ) = @_; - my $self = ref $pkg ? $pkg : $pkg->new($opts); + my $self = ref $pkg ? $pkg : $pkg->new($opts); my $clientpackage = "Device::Firmata::IO::NetIO::Client"; eval "require $clientpackage"; my $clientio = $clientpackage->attach($client_socket); - my $package = "Device::Firmata::Platform"; - eval "require $package"; - my $platform = $package->attach( $clientio, $opts ) or die "Could not connect to Firmata Server"; + my $package = "Device::Firmata::Platform"; + eval "require $package"; + my $platform = $package->attach( $clientio, $opts ) or die "Could not connect to Firmata Server"; my $s = $self->{'select'}; if (!($s)) { @@ -113,14 +134,20 @@ sub attach { $clients = []; $self->{clients} = $clients; } - push $clients, $platform; + push @$clients, $platform; # Figure out what platform we're running on - $platform->probe(); + $platform->probe(); - return $platform; + return $platform; } +=head3 poll ( timeout ) + +Wait for timeout seconds for data from Firmata devices. If data is received the method C of L will be called for processing. An implementation example can be found in file F. + +=cut + sub poll { my ($self,$timeout) = @_; my $s = $self->{'select'}; @@ -146,6 +173,12 @@ sub poll { package Device::Firmata::IO::NetIO::Client; +=head1 Device::Firmata::IO::NetIO::Client + +Implements the low level TCP/IP client socket IO. + +=cut + use strict; use warnings; use IO::Socket::INET; @@ -156,53 +189,60 @@ use Device::Firmata::Base FIRMATA_ATTRIBS => { }; +=head2 METHODS + +=head3 attach ( connectedSocket ) + +Assign a connected L as IO port and return a C object. Typically used internally by the C method of L. + +=cut + sub attach { - my ( $pkg, $client_socket, $opts ) = @_; + my ( $pkg, $client_socket, $opts ) = @_; - my $self = ref $pkg ? $pkg : $pkg->new($opts); + my $self = ref $pkg ? $pkg : $pkg->new($opts); - $self->{client} = $client_socket; + $self->{client} = $client_socket; - return $self; + return $self; } -=head2 data_write +=head3 data_write ( buffer ) -Dump a bunch of data into the comm port +Send a bunch of data to the Firmata device. Typically used internally by L. =cut sub data_write { # -------------------------------------------------- - my ( $self, $buf ) = @_; - $Device::Firmata::DEBUG and print ">".join(",",map{sprintf"%02x",ord$_}split//,$buf)."\n"; - return $self->{client}->write( $buf ); + my ( $self, $buf ) = @_; + $Device::Firmata::DEBUG and print ">".join(",",map{sprintf"%02x",ord$_}split//,$buf)."\n"; + return $self->{client}->write( $buf ); } -=head2 data_read +=head3 data_read ( bytes ) -We fetch up to $bytes from the comm port -This function is non-blocking +Fetch up to given number of bytes from the client socket. This function is non-blocking. Returns the received data. Typically used internally by L. =cut sub data_read { # -------------------------------------------------- - my ( $self, $bytes ) = @_; + my ( $self, $bytes ) = @_; my ($buf, $res); $res = $self->{client}->sysread($buf, 512); - $buf = "" if(!defined($res)); + $buf = "" if(!defined($res)); - if ( $Device::Firmata::DEBUG and $buf ) { - print "<".join(",",map{sprintf"%02x",ord$_}split//,$buf)."\n"; - } - return $buf; + if ( $Device::Firmata::DEBUG and $buf ) { + print "<".join(",",map{sprintf"%02x",ord$_}split//,$buf)."\n"; + } + return $buf; } -=head2 close +=head3 close -close the underlying connection +Close the TCP client socket to the Firmata device. The listening socket will not be affected. Typically used internally by L and C. =cut @@ -211,4 +251,10 @@ sub close { $self->{client}->close() if (($self->{client}) and $self->{client}->connected()); } +=head1 SEE ALSO + +L + +=cut + 1; diff --git a/lib/Device/Firmata/IO/SerialIO.pm b/lib/Device/Firmata/IO/SerialIO.pm index e33c7e5..664f83e 100644 --- a/lib/Device/Firmata/IO/SerialIO.pm +++ b/lib/Device/Firmata/IO/SerialIO.pm @@ -2,7 +2,7 @@ package Device::Firmata::IO::SerialIO; =head1 NAME -Device::Firmata::IO::SerialIO - implement the low level serial IO +Device::Firmata::IO::SerialIO - implement the low level serial IO. =cut @@ -22,7 +22,9 @@ $SERIAL_CLASS = $^O eq 'MSWin32' ? 'Win32::SerialPort' eval "require $SERIAL_CLASS"; -=head2 open +=head2 open ( serialPort , [opts] ) + +Establish a serial connection with a Firmata device. The first parameter is the name of the serial device connected with the Firmata device, e.g. '/dev/ttyUSB0' or 'COM9'. The second parameter is an optional hash of parameters for the serial port. The parameter C is supported and defaults to C<57600>. Returns a C object. Typically called internally by the C method of L. =cut @@ -38,6 +40,12 @@ sub open { return $self; } +=head2 attach ( serialPort ) + +Assign a L (or L) as IO port and return a L object. Typically used internally by the C method. + +=cut + sub attach { my ( $pkg, $serial_obj, $opts ) = @_; my $self = ref $pkg ? $pkg : $pkg->new($opts); @@ -47,7 +55,7 @@ sub attach { =head2 data_write -Dump a bunch of data into the comm port +Send a bunch of data to the Firmata device. Typically used internally by L. =cut @@ -61,8 +69,7 @@ sub data_write { =head2 data_read -We fetch up to $bytes from the comm port -This function is non-blocking +Fetch up to given number of bytes from the serial port. This function is non-blocking. Returns the received data. Typically used internally by L. =cut @@ -74,4 +81,10 @@ sub data_read { return $string; } +=head1 SEE ALSO + +L + +=cut + 1; diff --git a/lib/Device/Firmata/Platform/Arduino.pm b/lib/Device/Firmata/Platform/Arduino.pm index b5e4945..67230d0 100644 --- a/lib/Device/Firmata/Platform/Arduino.pm +++ b/lib/Device/Firmata/Platform/Arduino.pm @@ -2,12 +2,12 @@ package Device::Firmata::Platform::Arduino; =head1 NAME -Device::Firmata::Platform::Arduino - subclass for the arduino itself +Device::Firmata::Platform::Arduino - subclass for the Arduino itself =head1 DESCRIPTION -No customization requried at this time so this is just a specification of the -Device::Firmata::Platform class +No customization required at this time so this is just a specification of the +Device::Firmata::Platform class. =cut