Hardware Interfaces

Overview

A hardware interface is an architecture used to interconnect two devices together. The main hardware interfaces that are supported by the raspberry pi are i2c, spi, uart, hardware pwm(there is also software pwm but this belongs to the gpio interface) and gpio.

Pidevices abstracts all hardware interfaces by a common api that has 4 main functions initialize(), read(), write() and close(). So when it comes to the development of a new driver the programmer can focus on the device protocol and not get distracted by the underling protocol library.

This abstraction is done using inheritance of abstract protocol classes. For example the SPI class defines the attributes and the abstract functions of the spi interface in general and then an SPI_Implementation class inherits it and fills the functions and the setters/getters of the parent class using a specific protocol library e.x. spidev2. Basically the implementations are wrappers of the specific library but they follow a common interface so the programmer doesn’t have to know how to use the specific protocol libraries.

Classes

HardwareInterface

class pidevices.HardwareInterface

Abstract class representing a hardware interface.

initialize()

Initialize hardware resources.

read()

Read data from hardware.

write()

Write data to hardware.

close()

Free hardware resources.

GPIOPin

class pidevices.GPIOPin(number)

Class representing a gpio pin by defining it’s attributes.

Parameters

number – The bcm number of the pin.

property pin_num

An integer representing the bcm number of the pin.

property function

This attribute represents the function of the pin, it could be input for reading from the gpio pin or output for writting to the pin.

property pull

A str for the pull resistor of the pin, it could be up, down or floating. If the pin’s function is output this attribute can’t be set.

property frequency

Integer value representing the frequency of the pwm pulse.

property pwm

Boolean that indicates if the pin has pwm output. If the pin’s function is input this attribute can’t be set.

property duty_cycle

Float value between [0, 1] representing the pwm’s duty cycle.

property edge

String that represents on which edge signal the pin whould trigger a function call or a specific action. The value should be rising, falling or both.

property event

The event is a function that whould be called when an edge signal have occured.

property bounce

Integer representing the time intervel in miliseconds after an edge signal that the event function doesn’t get called with the occurence of a new edge signal.

GPIO

class pidevices.GPIO(**kwargs)

Abstract class representing the GPIO hardware interface.

The pupropse of this class is to handle every pin from the gpio pins set that a device needs to use. The implementations of this class wrap the specific library functions for handling the gpio pins.

Parameters

**kwargs – Could be multiple keyword arguments in the form of pin_name=pin_number(pin_number is the bcm number of the board). For example for the hc-sr04 sonar, it would be echo=14, trigger=25.

property pins

A dictionary that has attributes of type GPIOPin that represent each pin. Keys are the pin names and values the objects.

write(pin, value)

Write a value to an output pin.

Parameters

  • pin (str) – The pin’s name.

  • value (int) – The output value. The value should be 0 or 1 for a simple output pin and if it is pwm should be between [0, 1].

Raises

  • TypeError – Try to write non arithmetic value or use value greater than 1 or use negative value.

  • NotOutputPin – Try to write to an input pin.

read(pin)

Read the value of an input pin.

Parameters

pin (str) – The pin’s name.

Returns

that is 1 for high voltage, 0 for low voltage.

Return type

int

Raises

NotInputPin – Try to read from non input pin.

add_pins(**kwargs)

Add new pins to the pins dictionary.

Parameters

**kwargs – Keyword arguments pin_name=pin_number. For example echo=1, trigger=2.

remove_pins(*args)

Remove a pin/pins from the dictionary and free the resources.

Parameters

*args – String with the pin’s name, it could be more than one.

init_input(pin, pull)

Initialize a pin to input with initial pull up value.

Parameters

  • pin (str) – The pin name.

  • pull (str) – The pull up value.

init_output(pin, value)

Initialize a pin to output with an output value.

Parameters

  • pin (str) – The pin name.

  • value (int) – The output value.

init_pwm(pin, frequency, duty_cycle=0)

Initialize a pin to pwm with frequency and duty cycle.

Parameters

  • pin (str) – The pin name.

  • frequency (int) – The pwm frequency.

  • duty_cycle (int) – Optional parameter for initializing duty_cycle. Defaults to 0.

set_pin_function(pin, function)

Set a pin’s function.

Parameters

  • pin (str) – The pin name.

  • function (str) – The function value.

Raises

TypeError – Error occured using invalid function name.

get_pin_function(pin)

Get the pin’s function.

Parameters

pin (str) – The pin name.

Returns

A string containing the pin’s function.

set_pin_pull(pin, pull)

Set a pin’s pull up.

Parameters

  • pin (str) – The pin name.

  • pull (str) – The pull up value.

Raises

  • TypeError – Error occured using invalid pull name.

  • NotInputPin – Try to set pull up resistor to a non input pin.

get_pin_pull(pin)

Get a pin’s pull up.

Parameters

pin (str) – The pin’s name.

Returns

containing the pin’s pull value.

Return type

str

set_pin_pwm(pin, pwm)

Set a pwm pin.

Parameters

  • pin (str) – The pin’s name.

  • pwm (int) – The pwm value.

Raises

  • TypeError – Invalid pwm type.

  • NotOutputPin – Error occured trying to drive a non output pin.

get_pin_pwm(pin)

Get a pin’s pwm value.

Parameters

pin (str) – The pin’s name.

Returns

that represents if the pin is pwm.

Return type

bool

set_pin_frequency(pin, frequency)

Set a pwm pin’s frequency.

Parameters

  • pin (str) – The pin’s name.

  • frequency (int) – The frequency value.

Raises

NotPwmPin – Error occured trying to set pwm frequency to a non pwm pin.

get_pin_frequency(pin)

Get a pin’s frequency.

Parameters

pin (str) – The pin’s name.

Returns

with the pin’s pwm frequency.

Return type

int

set_pin_duty_cycle(pin, duty_cycle)

Set a pwm pin’s duty_cycle.

Maybe it is unnecessary.

Parameters

  • pin (str) – The pin’s name.

  • duty_cycle (int) – The duty_cycle value.

get_pin_duty_cycle(pin)

Get a pin’s duty_cycle value.

Parameters

pin (str) – The pin’s name.

Returns

Representing the duty cycle.

Return type

float

set_pin_edge(pin, edge)

Set a pin’s edge value.

Parameters

  • pin (str) – The pin’s name.

  • edge (str) – The edge value.

Raises

NotInputPin – Try to set edge to a non input pin.

get_pin_edge(pin)

Get a pin’s edge value.

Parameters

pin (str) – The pin’s name.

Returns

A str with the pin’s edge.

set_pin_event(pin, event, *args)

Set the function that will be called with a new edge.

Parameters

  • pin (str) – Pin name

  • event (function) – Function pointer to the target function.

  • *args – The arguments of the target function.

Raises

NotInputPin – Try to set event to a non input pin.

get_pin_event(pin)

Get a pin’s event function.

Parameters

pin (str) – The pin’s name.

Returns

The function that is called when an edge signal occurs.

set_pin_bounce(pin, bounce)

Set a pin’s bounce time.

Parameters

  • pin (str) – The pin’s name.

  • bounce (int) – The bounce value.

get_pin_bounce(pin)

Get a pin’s bounce value.

Parameters

pin (str) – The pin’s name.

Returns

Representing the pin’s bounce time.

Return type

int

close()

Free hardware resources.

initialize()

Initialize hardware resources.

SPI

class pidevices.SPI

Abstract class representing spi hardware interface. It is higly inspired from gpiozero <https://gpiozero.readthedocs.io/en/stable/api_spi.html> SPI abstract class.

property clock_polarity

Boolean representing the polarity of the SPI clock. If it is False the clock will idle low and pulse high. Otherwise it will idle high and pulse low.

property clock_phase

Boolean representing the phase of the SPI clock. If it is False the data will be read from the MISO pin when the clock pin activates. Else it the data will be read from the MISO pin when the clock pin deactivates.

property clock_mode

Integer representing the four combinations of clock_polarity and clock_phase.

property lsb_first

Boolean that controls if the data are read and written in LSB.

property select_high

Boolean that indicates if the chip select line is considered active when it is pulled down.

property bit_per_word

An integer representing the number of bits that make up a word.

property max_speed_hz

Integer that sets the maximum bus speed in Hz.

close()

Free hardware resources.

initialize()

Initialize hardware resources.

read()

Read data from hardware.

write()

Write data to hardware.

HPWM

class pidevices.HPWM(pin)

Abstract class representing hardware pwm.

The raspberry pi has two channels of hardware pwm. This channels comes in pairs that only one could be activated. This pairs are pins (12, 13), (18, 19), (40, 41), (52, 53).

Parameters

pin (int) – The pin number.

Raises

InvalidHPWMPin – Error with invalid pwm pin.

property frequency

Frequency of the pwm pulse.

property duty_cycle

Duty cycle of the pwm pulse.

property enable

Enable hardware pwm.

property polarity

Polarity of the pulse.

close()

Free hardware resources.

initialize()

Initialize hardware resources.

read()

Read data from hardware.

write()

Write data to hardware.

I2C

class pidevices.I2C

Abstract base class representing i2c hardware interface.

property bus

Hardware bus of the i2c interface.

close()

Free hardware resources.

initialize()

Initialize hardware resources.

read()

Read data from hardware.

write()

Write data to hardware.