view release on metacpan or  search on metacpan

lib/Device/AVR/UPDI.pm  view on Meta::CPAN

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2019-2024 -- leonerd@leonerd.org.uk

use v5.26;
use warnings;
use Object::Pad 0.807 ':experimental(inherit_field)';

package Device::AVR::UPDI 0.19;
class Device::AVR::UPDI :strict(params);

use Carp;

use Future::AsyncAwait;
use Future::IO 0.03; # ->sysread_exactly
use Sublike::Extended 'method';

use File::ShareDir qw( module_dir );
use YAML ();

my $SHAREDIR = module_dir( __PACKAGE__ );

use Object::Pad::ClassAttr::Struct 0.04;

use constant DEBUG => $ENV{UPDI_DEBUG} // 0;

class Device::AVR::UPDI::_PartInfo :Struct {
   field $name;

   field $signature;
   field $baseaddr_nvmctrl;
   field $baseaddr_fuse;
   field $baseaddr_sigrow;

   field $baseaddr_flash;
   field $pagesize_flash;
   field $size_flash;

   field $baseaddr_eeprom;
   field $pagesize_eeprom;
   field $size_eeprom;

   field $fusenames;
}

my %partinfos;
{
   while( readline DATA ) {
      m/^#/ and next;
      chomp;
      my ( $name, $signature, @fields ) = split m/\|/, $_;
      $signature = pack "H*", $signature;
      my $fuses = [ map { length $_ ? $_ : undef } split m/,/, pop @fields ];
      m/^0x/ and $_ = hex $_ for @fields;

      my $partinfo = Device::AVR::UPDI::_PartInfo->new_values( $name, $signature, @fields, $fuses );

      $partinfos{lc $name} = $partinfo;
      $partinfos{"m$1"} = $partinfo if $name =~ m/^ATmega(.*)$/;
      $partinfos{"t$1"} = $partinfo if $name =~ m/^ATtiny(.*)$/;
   }

   close DATA;
}

=head1 NAME

C<Device::AVR::UPDI> - interact with an F<AVR> microcontroller over F<UPDI>

=head1 DESCRIPTION

This module provides a class for interacting with an F<AVR> microcontroller
over the F<UPDI> programming and debug interface. This is used by chips in the
newer F<ATmega> 0-series, or F<ATtiny> 0-series or 1-series, or F<AVR DA> or
F<AVR DB> families.

=head2 Hardware Interface

This code expects to find a serial port connected to the UPDI pin of the
microcontroller as a shared single-wire interface. Suitable hardware to
provide this can be created using a USB-UART adapter, connecting the C<RX>
line directly to the MCU's C<UPDI> pin, and connecting C<TX> via a
current-limiting resistor of 1kohm.

=for highlighter

   +------------+                    +-------------------+
   |         RX-|-------------+      |                   |
   | USB-UART   |             +------|-UPDI              |
   |         TX-|---[ 1k  ]---+      |  ATmega or ATtiny |
   +------------+                    +-------------------|

=cut

=head1 CONSTRUCTORS

=for highlighter language=perl

=cut

=head2 new

   $updi = Device::AVR::UPDI->new( ... );

Constructs and returns a new C<Device::AVR::UPDI> instance.

Takes the following named arguments:

=over 4

=item dev => STRING

Path to the device node representing the serial port connection.