view release on metacpan or  search on metacpan

lib/Device/Chip/Adapter.pm  view on Meta::CPAN

=head2 tris_gpios

   await $protocol->tris_gpios( \@pin_names );

Sets the named GPIO pins as high-impedence inputs ("tristate"). Any GPIO pins
not named here are left as they are.

This method is similar to L</read_gpios> except that it does not return the
current pin values to the caller. Adapter implementations may implement this
by simply calling L</read_gpios> or they may have a more efficient variant
that does not have to transfer these extra readings back from the adapter
hardware.

=cut

=head1 GPIO PROTOCOL

The GPIO protocol adds no new abilities or methods; it is the most basic form
of protocol that simply provides access to the generic GPIO pins of the
device.

=head1 SPI PROTOCOL

=head2 Configuration Options

The following configuration options are recognised:

=over 4

=item mode => 0 | 1 | 2 | 3

The numbered SPI mode used to communicate with the chip.

=item max_bitrate => INT

The highest speed, in bits per second, that the chip can accept. The adapter
must pick a rate that is no higher than this. Note specifically that not all
adapters are able to choose a rate arbitrarily, and so the actually
communication may happen at some rate slower than this.

=item wordsize => INT

The number of bits per word transferred. Many drivers will not be able to
accept a number other than 8.

For values less than 8, the value should be taken from the least-significant
bits of each byte given to the C<readwrite> or C<write> methods.

For values greater than 8, use character strings with wide codepoints inside;
such as created by the C<chr()> function.

=back

=head2 readwrite

   $words_in = await $spi->readwrite( $words_out );

Performs a complete SPI transaction; assert the SS pin, synchronously clock
the data given by the I<$words_out> out of the MOSI pin of the adapter while
simultaneously capturing the data coming in to the MISO pin, then release the
SS pin again. The values clocked in are eventually returned as the result of
the returned future.

=head2 write

   await $spi->write( $words );

A variant of C<readwrite> where the caller does not intend to make use of the
data returned by the device, and so the adapter does not need to return it.
This may or may not make a material difference to the actual communication
with the adapter or device; it could be implemented simply by calling the
C<readwrite> method and ignoring the return value.

=head2 read

   $words = await $spi->read( $len );

A variant of C<readwrite> where the chip will not care what data is written
to it, so the caller does not need to supply it. This may or may not make a
material difference to the actual communication with the adapter or device;
it could be implemented simply by calling the C<readwrite> method and passing
in some constant string of appropriate length.

=head2 write_then_read

    $words_in = await $spi->write_then_read( $words_out, $len_in );

Performs a complete SPI transaction; assert the SS pin, synchronously clock
the data given by I<$words_out> out of the MOSI pin of the adapter, then clock
in more data from the MISO pin, finally releasing the SS pin again. These two
operations must be performed within a single assert-and-release SS cycle. It
is unspecified what values will be sent out during the read phase; adapters
should typically send all-bits-low or all-bits-high, but in general may not
allow configuration of what that will be.

This differs from the C</readwrite> method in that it works sequentially;
sending out words while ignoring the result, then reading in words while
sending unspecified data.

=head2 assert_ss

=head2 release_ss

   await $spi->assert_ss;

   await $spi->release_ss;

Lower-level access methods to directly assert or release the SS pin of the
adapter. These would typically be used in conjunction with L</readwrite_no_ss>
or L</write_no_ss>.

=head2 readwrite_no_ss

=head2 write_no_ss

=head2 read_no_ss

   $words_in = await $spi->readwrite_no_ss( $words_out );

   await $spi->write_no_ss( $words );