Pi Servo pHAT (v2) Hookup Guide

Pages
Favorited Favorite 4

Python Package Overview

Note: This sensor and the Python library have not been tested on the newly released Raspberry Pi 4 because we don't carry it in out catalog yet.

Note: This package assumes you are using the latest version of Python 3. If this is your first time using Python or I2C hardware on a Raspberry Pi, please checkout our tutorial on Python Programming with the Raspberry Pi and the Raspberry Pi SPI and I2C Tutorial.

*On the Raspberry Pi, Python 2 and 3 are included with the Raspbian OS (with desktop and recommended software) image.

Support Tip: Don't forget to double check that the hardware I2C connection is enabled on your Raspberry Pi or other single board computer.

There are two Python packages for this product. Qwiic_PCA9685_Py is an underlying package for the operation of the PCA9685 PWM controller IC. While, PiServoHat_Py is a package, built specifically for this product, to control servos. We've written these packages to easily start controlling servos with the Pi Servo pHAT.

Installation

To install the Python packages for this product, it is recommended that users install the SparkFun Qwiic Python package, which installs all the available Python packages for our Qwiic products and includes the required I2C driver package. On systems that support PyPi installation via pip3 (use pip for Python 2) is simple, using the following commands:

For all users (note: the user must have sudo privileges):

language:bash
sudo pip3 install sparkfun-qwiic

For the current user:

language:bash
pip3 install sparkfun-qwiic
Note: Users can, alternatively, install the two python packages for this product individually (see instructions below). The required I2C driver package will still need to be installed as well.

Qwiic_PCA9685_Py

You can install the sparkfun-sparkfun-qwiic-pca9685 Python package hosted by PyPi. If you prefer to manually download and install the package from the GitHub repository, you can grab them here (*Please be aware of any package dependencies. You can also check out the repository documentation page, hosted on ReadtheDocs.):

PyPi Installation

This repository is hosted on PyPi as the sparkfun-qwiic-pca9685 package. On systems that support PyPi installation via pip3 (use pip for Python 2) is simple, using the following commands:

For all users (note: the user must have sudo privileges):

language:bash
sudo pip3 install sparkfun-qwiic-pca9685

For the current user:

language:bash
pip3 install sparkfun-qwiic-pca9685

Local Installation

To install, make sure the setuptools package is installed on the system.

Direct installation at the command line (use python for Python 2):

language:bash
python3 setup.py install

To build a package for use with pip3:

language:bash
python3 setup.py sdist

A package file is built and placed in a subdirectory called dist. This package file can be installed using pip3.

language:bash
cd dist
pip3 install sparkfun_qwiic_pca9685-<version>.tar.gz

Python Package Operation

As this is an underlying package for the PCA9685 PWM controller IC, we will not go into the details of the package operation. However, users are welcome to check out the ReadtheDocs documentation.

PiServoHat_Py

You can install the sparkfun-pi-servo-hat Python package hosted by PyPi. If you prefer to manually download and install the package from the GitHub repository, you can grab them here (*Please be aware of any package dependencies. You can also check out the repository documentation page, hosted on ReadtheDocs.):

PyPi Installation

This repository is hosted on PyPi as the sparkfun-pi-servo-hat package. On systems that support PyPi installation via pip3 (use pip for Python 2) is simple, using the following commands:

For all users (note: the user must have sudo privileges):

language:bash
sudo pip3 install sparkfun-pi-servo-hat

For the current user:

language:bash
pip3 install sparkfun-pi-servo-hat

Local Installation

To install, make sure the setuptools package is installed on the system.

Direct installation at the command line:

language:bash
python setup.py install

To build a package for use with pip3:

language:bash
python setup.py sdist

A package file is built and placed in a subdirectory called dist. This package file can be installed using pip3.

language:bash
cd dist
pip3 install sparkfun_pi_servo_hat-<version>.tar.gz

Python Package Operation

Below is a description of the basic functionality of the Python package. This includes the package organization, built-in methods, and their inputs and/or outputs. For more details on how the Python package works, check out the source code and the sensor datasheet.

Dependencies

This Python package has a very few dependencies in the code, listed below:

language:python
import time             # Time access and conversion package
import math             # Basic math package
import qwiic_pca9685    # PCA9685 LED driver package
Default Variables

The default variables, in the code, for this Python package are listed below:

language:python
# Device Name:
_DEFAULT_NAME = "Pi Servo HAT"

# Fixed Address:
_AVAILABLE_I2C_ADDRESS = [0x40]

# Default Servo Frequency:
_DEFAULT_SERVO_FREQUENCY = 50   # Hz

# Special Use Addresses:
gcAddr = 0x00       # General Call address for software reset
acAddr = 0x70       # All Call address- used for modifications to
                    # multiple PCA9685 chips reguardless of thier
                    # I2C address set by hardware pins (A0 to A5).
subAddr_1 = 0x71    # 1110 001X or 0xE2 (7-bit)
subAddr_2 = 0x72    # 1110 010X or 0xE4 (7-bit)
subAddr_3 = 0x74    # 1110 100X or 0xE8 (7-bit)
Class

PiServoHat() or PiServoHat(address, debug=None)
This Python package operates as a class object, allowing new instances of that type to be made. An __init__() constructor is used that creates a connection to an I2C device over the I2C bus using the default or specified I2C address.

The Constructor

A constructor is a special kind of method used to initialize (assign values to) the data members needed by the object when it is created.

__init__(address, debug)

Input: value
The value of the device address. If not defined, the Python package will use the default I2C address (0x40) stored under _AVAILABLE_I2C_ADDRESS variable. The All Call address is 0x70.
Input: value
Designates whether or not to print debug statements.

0: Don't print debug statements.
1: Print debug statements.

Output: Boolean

True: Connected to I2C device on the default (or specified) address.
False: No device found or connected.

Functions

A function that is an attribute of the class, which defines a method for instances of that class. In simple terms, they are objects for the operations (or methods) of the class.

.restart()
Soft resets the PCA9685 chip and then clears the MODE1 register to restart the PWM functionality. The PWM frequency is also returned to the default 50 Hz setting.

.get_pwm_frequency()
Reads the PWM frequency used on the outputs.

Output: Integer

Range: 24 Hz to 1526 Hz

.set_pwm_frequency(frequency)
Configures the PWM frequency used on outputs. 50 Hz is the default and recommended for most servos.

Input: Integer

Range: 24 Hz to 1526 Hz

.get_servo_position(channel) or .get_servo_position(channel, swing)
Estimates the orientation of the servo arm in degrees. The estimation is based upon the timing that is configured for the PWM signal, on the specified channel.

Input: value

Channel of Interest
Range: 0 to 15

Input: Value

90: Servo with 90° arm swing.
180: Servo with 180° arm swing.

Output: Float

Estimated servo arm position.

.move_servo_position(channel, position) or .move_servo_position(channel, position, swing)
Moves servo to specified location in degrees.

Input: value

Channel of Interest
Range: 0 to 15

Input: Float

Specified servo arm position.

Input: Value

90: Servo with 90° arm swing.
180: Servo with 180° arm swing.

.set_duty_cycle(channel, duty_cycle)
Moves servo to specified location based on duty-cycle.

Input: value

Channel of Interest
Range: 0 to 15

Input: Float

Duty-Cycle (Percentage)
Range: 0 to 100 (%) (Resolution: 1/4096)

Upgrading Packages

In the future, changes to the Python packages might be made. Updating the installed packages has to be done individually for each package (i.e. sub-modules and dependencies won't update automatically and must be updated manually). For the SomePackage Python package, use the following command (use pip for Python 2):

For all users (note: the user must have sudo privileges):

language:bash
sudo pip3 install --upgrade SomePackage

For the current user:

language:bash
pip3 install --upgrade SomePackage