HiPi
Perl Modules for Raspberry Pi
Version 0.92 - released 28 March 2024

HiPi::Device::SPI

The HiPi::Device::SPI module provides access to the kernel driver for the SPI bus

Several of the HiPi Interface Modules are wrappers around HiPi::Device::SPI. You can use HiPi::Device::SPI directly to interface with other SPI peripherals.

Methods

Class Functions

Returns an instance of HiPi::Device::SPI.

my $dev = HiPi::Device::SPI->new();

There are a number of optional parameters you can pass to the constructor as shown below with their default values.

use HiPi qw( :spi );
my $dev = HiPi::Device::SPI->new(
    devicename   => '/dev/spidev0.0',
    speed        => SPI_SPEED_MHZ_1,
    bitsperword  => 8,
    delay        => 0,    
);

devicename

The devicename gives the /dev/ file used by the SPI kernel driver. To connect to SPI 0 using the CEO cable select pin, use default devicename '/dev/spidev0.0'. To connect to SPI 0 using the CE1 pin, use default devicename '/dev/spidev0.1'.

speed

Set the speed in MHz of SPI transfers for this instance of HiPi::Device::SPI. This will override whatever the bus speed may be set at.

The default is 1000000 ( SPI_SPEED_MHZ_1 ). You can pass a numeric value or use one of the following constants.

SPI_SPEED_KHZ_500
SPI_SPEED_MHZ_1
SPI_SPEED_MHZ_2
SPI_SPEED_MHZ_4
SPI_SPEED_MHZ_8
SPI_SPEED_MHZ_16
SPI_SPEED_MHZ_32

bitsperword

You can set the bits per word for transfers using this instance of HiPi::Device::SPI. This will override whatever the global setting for the bus may be. Leave at the default of 8 unless you have some specific known requirement.

delay

You may set a delay in microseconds that is allowed to elapse at the end of the transer before the bus is released and the next transfer can start. Leave at the default of 0 unless you have some specific known requirement.

Transfer an array of bytes.

SPI transfers always write the same number of bytes as they read. If your SPI device requires you to write a register address or command to receive a 2 byte answer, you must write 3 bytes. One with the register address and two to receive the response.

my @writebites = ( $register, 0, 0 );
my @readbytes = $dev->transfer_byte_array( @writebytes );

# If the answer is a 16 bit number, MSB first, it is
# in bytes 1 and 2 with byte 1 containing the MSB 

my $answer = ( $readbytes[1] << 8 ) + $readbytes[2];

Transfer a buffer. The method transfer_byte_array is a wrapper for this method and is simpler to use.

SPI transfers always write the same number of bytes as they read. If your SPI device requires you to write a register address or command to receive a 2 byte answer, you must write 3 bytes. One with the register address and two to receive the response.

my @writebites = ( $register, 0, 0 );

my $writebuffer = pack( 'C3', @writebites );
my $readbuffer = $dev->transfer( $writebuffer );
my @readbytes = unpack( 'C3', $readbuffer );

# If the answer is a 16 bit number, MSB first, it is
# in bytes 1 and 2 with byte 1 containing the MSB 

my $answer = ( $readbytes[1] << 8 ) + $readbytes[2];

Set the value for delay ( as passed in the constructor ).

$dev->set_transfer_delay( 0 );

Get the current value for delay ( as passed in the constructor ).

my $val = $dev->get_transfer_delay;

Set the value for speed ( as passed in the constructor ).

$dev->set_transfer_speed( 1000_000 );

Get the current value for speed ( as passed in the constructor ).

my $val = $dev->get_transfer_speed;

Set the value for bitsperword ( as passed in the constructor ).

$dev->set_transfer_bitsperword( 8 );

Get the current value for bitsperword ( as passed in the constructor ).

my $val = $dev->get_transfer_bitsperword;

Set the mode for the SPI device. Global setting. Consult SPI documentation.

Use a mask of values:

SPI_CPHA
SPI_CPOL
SPI_MODE_0
SPI_MODE_1
SPI_MODE_2
SPI_MODE_3
SPI_CS_HIGH
SPI_LSB_FIRST
SPI_3WIRE
SPI_LOOP
SPI_NO_CS
$dev->set_bus_mode( $mask );

Get the current bus mode. Returns a mask of the values:

SPI_CPHA
SPI_CPOL
SPI_MODE_0
SPI_MODE_1
SPI_MODE_2
SPI_MODE_3
SPI_CS_HIGH
SPI_LSB_FIRST
SPI_3WIRE
SPI_LOOP
SPI_NO_CS
my $mask = $dev->get_bus_mode();

Set the maximum speed for the bus. Global setting. This can be overridden in any instance by the value for speed as set in the constructor or using method set_transfer_speed.

$dev->set_bus_maxspeed( SPI_SPEED_MHZ_1 );

Get the global maximum SPI bus speed. ( This can be overridden in any instance by the value for speed as set in the constructor or using method set_transfer_speed. )

my $speed = $dev->get_bus_maxspeed;

Returns an array containing the names of available devices.

For example ('/dev/spidev0.0', '/dev/spidev0.1').

my @devnames = HiPi::Device::SPI->get_device_list();