# SPDX-FileCopyrightText: 2016 Radomir Dopieralski for Adafruit Industries
# SPDX-FileCopyrightText: 2017 Scott Shawcroft for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
`adafruit_pca9685`
====================================================
Driver for the PCA9685 PWM control IC. Its commonly used to control servos, leds and motors.
.. seealso:: The `Adafruit CircuitPython Motor library
<https://github.com/adafruit/Adafruit_CircuitPython_Motor>`_ can be used to control the PWM
outputs for specific uses instead of generic duty_cycle adjustments.
* Author(s): Scott Shawcroft
Implementation Notes
--------------------
**Hardware:**
* Adafruit `16-Channel 12-bit PWM/Servo Driver - I2C interface - PCA9685
<https://www.adafruit.com/product/815>`_ (Product ID: 815)
**Software and Dependencies:**
* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
https://github.com/adafruit/circuitpython/releases
* Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
* Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
"""
__version__ = "0.0.0+auto.0"
__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_PCA9685.git"
import time
from adafruit_register.i2c_struct import UnaryStruct
from adafruit_register.i2c_struct_array import StructArray
from adafruit_bus_device import i2c_device
try:
from typing import Optional, Type
from types import TracebackType
from busio import I2C
except ImportError:
pass
[docs]
class PWMChannel:
"""A single PCA9685 channel that matches the :py:class:`~pwmio.PWMOut` API.
:param PCA9685 pca: The PCA9685 object
:param int index: The index of the channel
"""
def __init__(self, pca: "PCA9685", index: int):
self._pca = pca
self._index = index
@property
def frequency(self) -> float:
"""The overall PWM frequency in Hertz (read-only).
A PWMChannel's frequency cannot be set individually.
All channels share a common frequency, set by PCA9685.frequency."""
return self._pca.frequency
@frequency.setter
def frequency(self, _):
raise NotImplementedError("frequency cannot be set on individual channels")
@property
def duty_cycle(self) -> int:
"""16 bit value that dictates how much of one cycle is high (1) versus low (0). 0xffff will
always be high, 0 will always be low and 0x7fff will be half high and then half low.
"""
pwm = self._pca.pwm_regs[self._index]
if pwm[0] == 0x1000:
return 0xFFFF
if pwm[1] == 0x1000:
return 0x0000
return pwm[1] << 4
@duty_cycle.setter
def duty_cycle(self, value: int) -> None:
if not 0 <= value <= 0xFFFF:
raise ValueError(f"Out of range: value {value} not 0 <= value <= 65,535")
if value == 0xFFFF:
# Special case for "fully on":
self._pca.pwm_regs[self._index] = (0x1000, 0)
elif value < 0x0010:
# Special case for "fully off":
self._pca.pwm_regs[self._index] = (0, 0x1000)
else:
# Shift our value by four because the PCA9685 is only 12 bits but our value is 16
value = value >> 4
# value should never be zero here because of the test for the "fully off" case
# (the LEDn_ON and LEDn_OFF registers should never be set with the same values)
self._pca.pwm_regs[self._index] = (0, value)
[docs]
class PCAChannels: # pylint: disable=too-few-public-methods
"""Lazily creates and caches channel objects as needed. Treat it like a sequence.
:param PCA9685 pca: The PCA9685 object
"""
def __init__(self, pca: "PCA9685") -> None:
self._pca = pca
self._channels = [None] * len(self)
def __len__(self) -> int:
return 16
def __getitem__(self, index: int) -> PWMChannel:
if not self._channels[index]:
self._channels[index] = PWMChannel(self._pca, index)
return self._channels[index]
[docs]
class PCA9685:
"""
Initialise the PCA9685 chip at ``address`` on ``i2c_bus``.
The internal reference clock is 25mhz but may vary slightly with environmental conditions and
manufacturing variances. Providing a more precise ``reference_clock_speed`` can improve the
accuracy of the frequency and duty_cycle computations. See the ``calibration.py`` example for
how to derive this value by measuring the resulting pulse widths.
:param ~busio.I2C i2c_bus: The I2C bus which the PCA9685 is connected to.
:param int address: The I2C address of the PCA9685.
:param int reference_clock_speed: The frequency of the internal reference clock in Hertz.
"""
# Registers:
mode1_reg = UnaryStruct(0x00, "<B")
mode2_reg = UnaryStruct(0x01, "<B")
prescale_reg = UnaryStruct(0xFE, "<B")
pwm_regs = StructArray(0x06, "<HH", 16)
def __init__(
self,
i2c_bus: I2C,
*,
address: int = 0x40,
reference_clock_speed: int = 25000000,
) -> None:
self.i2c_device = i2c_device.I2CDevice(i2c_bus, address)
self.channels = PCAChannels(self)
"""Sequence of 16 `PWMChannel` objects. One for each channel."""
self.reference_clock_speed = reference_clock_speed
"""The reference clock speed in Hz."""
self.reset()
[docs]
def reset(self) -> None:
"""Reset the chip."""
self.mode1_reg = 0x00 # Mode1
@property
def frequency(self) -> float:
"""The overall PWM frequency in Hertz."""
prescale_result = self.prescale_reg
if prescale_result < 3:
raise ValueError(
"The device pre_scale register (0xFE) was not read or returned a value < 3"
)
return self.reference_clock_speed / 4096 / (prescale_result + 1)
@frequency.setter
def frequency(self, freq: float) -> None:
prescale = int(self.reference_clock_speed / 4096.0 / freq + 0.5) - 1
if prescale < 3:
raise ValueError("PCA9685 cannot output at the given frequency")
old_mode = self.mode1_reg # Mode 1
self.mode1_reg = (old_mode & 0x7F) | 0x10 # Mode 1, sleep
self.prescale_reg = prescale # Prescale
self.mode1_reg = old_mode # Mode 1
time.sleep(0.005)
# Mode 1, autoincrement on, fix to stop pca9685 from accepting commands at all addresses
self.mode1_reg = old_mode | 0xA0
def __enter__(self) -> "PCA9685":
return self
def __exit__(
self,
exception_type: Optional[Type[type]],
exception_value: Optional[BaseException],
traceback: Optional[TracebackType],
) -> None:
self.deinit()
[docs]
def deinit(self) -> None:
"""Stop using the pca9685."""
self.reset()