### getPWM usage examples

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Examples showing how to read the on-tick and off-tick values for a specific channel.

```cpp
uint16_t on  = pwm.getPWM(3);       // on-tick of channel 3
uint16_t off = pwm.getPWM(3, true); // off-tick of channel 3
```

--------------------------------

### setOscillatorFrequency usage examples

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Examples of setting the oscillator frequency before configuring PWM frequency.

```cpp
pwm.setOscillatorFrequency(27000000); // calibrated per chip with a scope
pwm.setPWMFreq(50);
```

```cpp
// Calibrate against a measured PWM update rate (examples/oscillator.ino
// automates measuring the real frequency with an interrupt counter):
pwm.setOscillatorFrequency(26000000);
```

--------------------------------

### getOscillatorFrequency usage examples

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Examples of retrieving the oscillator frequency and using it for conditional calibration.

```cpp
uint32_t f = pwm.getOscillatorFrequency(); // 25000000 before calibration
```

```cpp
// Guard: only calibrate if not already customized
if (pwm.getOscillatorFrequency() == 25000000) {
  pwm.setOscillatorFrequency(27000000);
}
```

--------------------------------

### setPin basic usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of setting a half-brightness value on a channel.

```cpp
pwm.setPin(2, 2048);   // half-brightness on channel 2
```

--------------------------------

### readPrescale basic usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of reading the prescale value.

```cpp
uint8_t prescale = pwm.readPrescale();
```

--------------------------------

### Reset and reconfigure

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of resetting the chip and manually setting the frequency.

```cpp
// Reset then reconfigure, mirroring what begin() does implicitly
pwm.reset();
pwm.setPWMFreq(50);
```

--------------------------------

### Conditional wakeup

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of waking the chip based on a button press.

```cpp
// No-op safety: waking an already-awake chip is harmless
if (digitalRead(POWER_BUTTON)) {
  pwm.wakeup();
}
```

--------------------------------

### setPin advanced usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Examples of using setPin for inverted output and full-on states.

```cpp
pwm.setPin(3, 100, true);   // inverted/sinking output
pwm.setPin(4, 4095);        // 100% on — mapped to full-ON special case
```

--------------------------------

### setPWM basic usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Examples of setting duty cycles and full-off states using setPWM.

```cpp
pwm.setPWM(0, 0, 2048); // 50% duty cycle on channel 0
pwm.setPWM(1, 0, 4096); // fully off
```

--------------------------------

### begin error handling

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of checking the return value of begin to ensure the chip is detected on the I2C bus.

```cpp
if (!pwm.begin()) {
  // chip not found on the bus — check wiring/address
  while (1) { delay(100); }
}
```

--------------------------------

### writeMicroseconds basic usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of setting a pulse width in microseconds after configuring the frequency.

```cpp
pwm.setPWMFreq(50);                 // 50 Hz period = 20000 us
pwm.writeMicroseconds(0, 1500);     // ~1.5 ms pulse = center position
```

--------------------------------

### readPrescale verification

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of verifying the prescale value after setting the PWM frequency.

```cpp
// Verify what setPWMFreq actually programmed
pwm.setPWMFreq(50);
if (pwm.readPrescale() == 0xFF) { /* max divider — very low freq */ }
```

--------------------------------

### getPWM round-trip verification

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example demonstrating how to verify that the value stored in the chip matches the requested value.

```cpp
// Round-trip check: what the chip actually has vs. what we requested
pwm.setPWM(5, 0, 2048);
uint16_t stored = pwm.getPWM(5, true);
if (stored != 2048) { /* bus-level debugging */ }
```

--------------------------------

### Power-down sequence

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of putting the chip to sleep before power removal.

```cpp
// Power-down sequence before unplugging
pwm.sleep();
delay(100);
```

--------------------------------

### setPWM error handling

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example showing how to check the return value of setPWM to handle I2C write failures.

```cpp
if (pwm.setPWM(7, 0, 1024) == 1) {
  // write failed at I2C level — retry or report
  pwm.setPWM(7, 0, 1024);
}
```

--------------------------------

### writeMicroseconds servo sweep

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of performing a full servo sweep using microsecond increments.

```cpp
// Full analog-servo sweep using microseconds
for (uint16_t us = 600; us < 2400; us += 10) {
  pwm.writeMicroseconds(servonum, us);
  delay(5);
}
```

--------------------------------

### getPWM

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Gets the current PWM value for a specified channel.

```APIDOC
## getPWM

### Description
Gets the current PWM value for a specified channel.

### Method
getPWM

### Parameters
None

### Returns
PWM value
```

--------------------------------

### getOscillatorFrequency

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Gets the current oscillator frequency.

```APIDOC
## getOscillatorFrequency

### Description
Gets the current oscillator frequency.

### Method
getOscillatorFrequency

### Parameters
None

### Returns
Oscillator frequency
```

--------------------------------

### setPWMFreq usage for analog servos

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Example of setting the PWM frequency to 50 Hz, commonly used for analog servos.

```cpp
pwm.setPWMFreq(50); // analog servos
```

--------------------------------

### Oscillator Frequency Calibration

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Example of calibrating the internal oscillator frequency and setting the PWM frequency, which is necessary because the internal oscillator varies per chip.

```cpp
pwm.setOscillatorFrequency(27000000);
pwm.setPWMFreq(1600);
```

--------------------------------

### begin()

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Initializes the I2C communication with the PCA9685 chip. Returns false if the I2C device initialization fails.

```APIDOC
## begin()

### Description
Initializes the I2C communication with the PCA9685 chip. Must be called before using other methods.

### Method
begin

### Signature
bool begin()

### Parameters
None

### Return Value
- **bool** - Returns `true` on success, `false` if the I2C device initialization failed (chip not found or bus error).

### Error Handling
If `begin()` returns `false`, the chip is not accessible at the configured address. Check wiring and address.

### Example
```cpp
Adafruit_PWMServoDriver pwm = Adafruit_PWMServoDriver();
if (!pwm.begin()) {
  // handle error
}
```
```

--------------------------------

### Basic begin usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Standard initialization of the PWM driver.

```cpp
Adafruit_PWMServoDriver pwm;
pwm.begin();
```

--------------------------------

### begin

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Initializes the PWM driver. This method should be called before using other methods.

```APIDOC
## begin

### Description
Initializes the PWM driver. This method should be called before using other methods.

### Method
begin

### Parameters
None

### Returns
None
```

--------------------------------

### begin method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The begin method initializes the driver. If prescale is 0, it defaults to 1000 Hz; otherwise, it uses the provided value for an external clock.

```cpp
bool begin(uint8_t prescale = 0);
```

--------------------------------

### setExtClk via begin

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Demonstrates that calling begin with a non-zero prescale internally delegates to setExtClk.

```cpp
// begin() delegates here when a nonzero prescale is passed
pwm.begin(9); // equivalent to begin() + setExtClk(9)
```

--------------------------------

### begin(uint8_t prescale = 0)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Resets the chip and applies default settings. If prescale is nonzero, it applies setExtClk(prescale); otherwise it uses the internal oscillator and sets PWM frequency to 1000 Hz.

```APIDOC
## begin(uint8_t prescale = 0)

### Description
Resets the chip and applies default settings. If prescale is nonzero, it applies setExtClk(prescale); otherwise it uses the internal oscillator and sets PWM frequency to 1000 Hz.

### Method Signature
`void begin(uint8_t prescale = 0)`

### Parameters
- **prescale** (uint8_t) - Optional - Prescale value for external clock. Default: 0 (use internal oscillator)

### Behavior
- Resets the chip
- If prescale is nonzero, calls setExtClk(prescale)
- Otherwise, sets PWM frequency to 1000 Hz
```

--------------------------------

### begin with external clock

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Initializing the driver with a specific prescale for an external clock source.

```cpp
// External 12 MHz clock on EXTCLK, prescale 9 (see setExtClk)
Adafruit_PWMServoDriver pwm(0x40, Wire);
pwm.begin(9);
```

--------------------------------

### begin

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Initializes the PWM driver. If a prescale value is provided, it configures an external clock; otherwise, it sets an internal 1000 Hz PWM frequency. Returns true on success, false if the I2C device fails to initialize.

```APIDOC
## begin

### Description
Initializes the PWM driver. If a prescale value is provided, it configures an external clock; otherwise, it sets an internal 1000 Hz PWM frequency. Returns true on success, false if the I2C device fails to initialize.

### Method
begin

### Signature
bool begin(uint8_t prescale = 0);

### Parameters
- **prescale** (uint8_t) - Optional - If nonzero, treated as an external-clock prescale and passed to setExtClk(); if 0, an internal 1000 Hz PWM frequency is configured via setPWMFreq(1000)

### Returns
- **bool** - true on success, false if Adafruit_I2CDevice::begin() fails (no device answering at _i2caddr)

### Description
begin() deletes any previous i2c_dev, allocates a new Adafruit_I2CDevice(_i2caddr, _i2c), calls reset(), sets the oscillator frequency to FREQUENCY_OSCILLATOR (25 MHz), then applies the prescale or default frequency.

### Example
```cpp
Adafruit_PWMServoDriver pwm;
pwm.begin();
```

```cpp
if (!pwm.begin()) {
  // chip not found on the bus — check wiring/address
  while (1) { delay(100); }
}
```

```cpp
// External 12 MHz clock on EXTCLK, prescale 9 (see setExtClk)
Adafruit_PWMServoDriver pwm(0x40, Wire);
pwm.begin(9);
```
```

--------------------------------

### Constructor Overloads for Adafruit_PWMServoDriver

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Demonstrates the three ways to instantiate the driver: using default address and bus, specifying a custom I2C address, or specifying both address and a secondary I2C bus.

```cpp
Adafruit_PWMServoDriver pwm;            // 0x40 on Wire
Adafruit_PWMServoDriver pwm(0x41);      // 0x41 on Wire
Adafruit_PWMServoDriver pwm(0x40, Wire1); // 0x40 on second bus
```

--------------------------------

### Basic wakeup usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Resuming chip operation.

```cpp
pwm.wakeup(); // resume oscillation after sleep()
```

--------------------------------

### Basic setExtClk usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Setting the external clock prescale.

```cpp
pwm.setExtClk(4);
```

--------------------------------

### wakeup

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Wakes up the PWM driver from sleep mode.

```APIDOC
## wakeup

### Description
Wakes up the PWM driver from sleep mode.

### Method
wakeup

### Parameters
None

### Returns
None
```

--------------------------------

### setExtClk

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Sets an external clock source for the PWM driver.

```APIDOC
## setExtClk

### Description
Sets an external clock source for the PWM driver.

### Method
setExtClk

### Parameters
None

### Returns
None
```

--------------------------------

### setOutputMode for open-drain output

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Configures the driver for open-drain output, recommended for LEDs with integrated zener diodes.

```cpp
pwm.setOutputMode(false); // open-drain for LEDs with zener protection
```

--------------------------------

### setOutputMode method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for configuring the output drive mode.

```cpp
void setOutputMode(bool totempole);
```

--------------------------------

### Adafruit_PWMServoDriver() Constructor

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The default constructor binds the driver to I2C address 0x40 and the global Wire instance.

```cpp
Adafruit_PWMServoDriver();
```

```cpp
#include <Wire.h>
#include <Adafruit_PWMServoDriver.h>

Adafruit_PWMServoDriver pwm; // default address 0x40 on Wire
```

```cpp
// Default-construct, then reconfigure the oscillator before begin()
Adafruit_PWMServoDriver pwm;
pwm.setOscillatorFrequency(27000000); // per-chip calibration (see configuration.md)
pwm.begin();
```

--------------------------------

### wakeup method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The wakeup method resumes oscillation after the chip has been put to sleep.

```cpp
void wakeup();
```

--------------------------------

### reset

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Sends a software reset to the chip by writing MODE1_RESTART to PCA9685_MODE1 and waiting 10 ms.

```APIDOC
## reset

### Description
Sends a software reset to the chip by writing MODE1_RESTART to PCA9685_MODE1 and waiting 10 ms.

### Method
reset

### Signature
void reset();

### Example
```cpp
pwm.reset(); // re-initialize chip registers after brownout
```

```cpp
// Reset then reconfigure, mirroring what begin() does implicitly
pwm.reset();
pwm.setPWMFreq(50);
```
```

--------------------------------

### Adafruit_PWMServoDriver()

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Default constructor that binds the driver to I2C address 0x40 on the global Wire instance.

```APIDOC
## Adafruit_PWMServoDriver()

### Description
Default constructor that initializes the driver with the default I2C address (0x40) and the global Wire instance.

### Method
Constructor

### Signature
```cpp
Adafruit_PWMServoDriver();
```

### Parameters
None.

### Example
```cpp
#include <Wire.h>
#include <Adafruit_PWMServoDriver.h>

Adafruit_PWMServoDriver pwm; // default address 0x40 on Wire
```

### Example with Oscillator Configuration
```cpp
// Default-construct, then reconfigure the oscillator before begin()
Adafruit_PWMServoDriver pwm;
pwm.setOscillatorFrequency(27000000); // per-chip calibration
pwm.begin();
```
```

--------------------------------

### setPin()

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Sets a channel to a specific duty cycle (0-4095). Delegates to setPWM(); return value is ignored.

```APIDOC
## setPin()

### Description
Sets a channel to a specific duty cycle value (0-4095).

### Method
setPin

### Signature
void setPin(uint8_t num, uint16_t val, bool invert = false)

### Parameters
- **num** (uint8_t) - Required - Channel number (0-15)
- **val** (uint16_t) - Required - Duty cycle value (0-4095)
- **invert** (bool) - Optional - If `true`, inverts the output. Default is `false`.

### Return Value
None (void)

### Error Handling
Delegates to `setPWM()`; its return value is ignored. No error indication.

### Example
```cpp
pwm.setPin(0, 2048); // 50% duty cycle
```
```

--------------------------------

### setExtClk method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Configures the chip to use an external clock source with a specific prescale value.

```cpp
void setExtClk(uint8_t prescale);
```

--------------------------------

### setExtClk(uint8_t prescale)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Switches the chip to use an external clock and writes the prescaler value.

```APIDOC
## setExtClk(uint8_t prescale)

### Description
Switches the chip to use an external clock and writes the prescaler value.

### Method Signature
`void setExtClk(uint8_t prescale)`

### Parameters
- **prescale** (uint8_t) - Required - Prescale value for the external clock.
```

--------------------------------

### setOutputMode for push-pull output

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Configures the driver for totem-pole (push-pull) output, typically used for servos.

```cpp
pwm.setOutputMode(true);  // push-pull outputs for servos
```

--------------------------------

### Adafruit_PWMServoDriver(const uint8_t addr, TwoWire& i2c) Constructor

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Use this constructor to specify both a custom I2C address and a specific TwoWire bus instance.

```cpp
Adafruit_PWMServoDriver(const uint8_t addr, TwoWire& i2c);
```

```cpp
Adafruit_PWMServoDriver pwm(0x40, Wire); // explicit bus
```

```cpp
// Dual bus: PCA9685 on Wire1 while Wire stays free for sensors
Adafruit_PWMServoDriver pwm(0x40, Wire1);
pwm.begin();
```

--------------------------------

### Adafruit_PWMServoDriver(const uint8_t addr) Constructor

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Use this constructor to bind the driver to a custom 7-bit I2C address on the global Wire bus.

```cpp
Adafruit_PWMServoDriver(const uint8_t addr);
```

```cpp
Adafruit_PWMServoDriver pwm(0x40); // chip with address pins cut for 0x40
```

```cpp
// Two chips on the same bus: one at 0x40, one at 0x41
Adafruit_PWMServoDriver pwmA(0x40);
Adafruit_PWMServoDriver pwmB(0x41);
pwmA.begin();
pwmB.begin();
```

--------------------------------

### setPin

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Simplified PWM control that hides on/off tick placement and handles full-on/full-off special cases.

```APIDOC
## setPin

### Description
Simplified PWM control that hides on/off tick placement and handles full-on/full-off special cases. Values are clamped to 0-4095.

### Method
void setPin(uint8_t num, uint16_t val, bool invert = false)

### Parameters
- **num** (uint8_t) - Required - PWM output channel, 0-15
- **val** (uint16_t) - Required - Active ticks out of 4096 (0-4095); clamped with min(val, 4095)
- **invert** (bool) - Optional (default: false) - When true, inverts the pulse (sinking to ground)

### Returns
Nothing

### Behavior
- val == 4095: fully ON (setPWM(num, 4096, 0))
- val == 0: fully OFF (setPWM(num, 0, 4096))
- Otherwise: setPWM(num, 0, val) or setPWM(num, 0, 4095 - val) when inverted

### Example
```cpp
pwm.setPin(2, 2048);   // half-brightness on channel 2
pwm.setPin(3, 100, true);   // inverted/sinking output
pwm.setPin(4, 4095);        // 100% on - mapped to full-ON special case
```
```

--------------------------------

### Constructor Overloads

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Three constructor overloads control the I2C address and bus. The default constructor uses address 0x40 on Wire, the one-argument constructor takes an address, and the two-argument constructor takes an address and a TwoWire bus object.

```APIDOC
## Constructor Overloads

### Description
Create an Adafruit_PWMServoDriver object with optional I2C address and bus.

### Constructors
- `Adafruit_PWMServoDriver()` - Default: address 0x40, bus Wire
- `Adafruit_PWMServoDriver(uint8_t addr)` - Address, bus Wire
- `Adafruit_PWMServoDriver(uint8_t addr, TwoWire& i2c)` - Address and bus

### Parameters
- **addr** (uint8_t) - Required - 7-bit I2C slave address of the PCA9685. Default: 0x40 (PCA9685_I2C_ADDRESS)
- **i2c** (TwoWire&) - Required - TwoWire bus object to communicate over. Default: Wire

### Example
```cpp
Adafruit_PWMServoDriver pwm;            // 0x40 on Wire
Adafruit_PWMServoDriver pwm(0x41);      // 0x41 on Wire
Adafruit_PWMServoDriver pwm(0x40, Wire1); // 0x40 on second bus
```
```

--------------------------------

### wakeup

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Wakes the chip from sleep mode by clearing the MODE1_SLEEP bit.

```APIDOC
## wakeup

### Description
Wakes the chip from sleep mode by clearing the MODE1_SLEEP bit.

### Method
wakeup

### Signature
void wakeup();

### Example
```cpp
pwm.wakeup(); // resume oscillation after sleep()
```

```cpp
// No-op safety: waking an already-awake chip is harmless
if (digitalRead(POWER_BUTTON)) {
  pwm.wakeup();
}
```
```

--------------------------------

### Basic sleep usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Putting the chip to sleep, which freezes the outputs.

```cpp
pwm.sleep(); // oscillator stopped, outputs frozen
```

--------------------------------

### setPin(..., bool invert = false)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Sets a pin's output and optionally inverts the output pulse (sinking). The invert flag defaults to false.

```APIDOC
## setPin(..., bool invert = false)

### Description
Sets a pin's output and optionally inverts the output pulse (sinking). The invert flag defaults to false.

### Method Signature
`void setPin(..., bool invert = false)`

### Parameters
- **invert** (bool) - Optional - Invert the output pulse. Default: false.
```

--------------------------------

### setPin function signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for the setPin helper method.

```cpp
void setPin(uint8_t num, uint16_t val, bool invert = false);
```

--------------------------------

### setOutputMode

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Configures the output drive mode for the PCA9685. When totempole is true, outputs are push-pull; when false, outputs are open-drain. This is important for LEDs with zener diodes.

```APIDOC
## setOutputMode

### Description
Configures the output drive mode for the PCA9685. When totempole is true, outputs are push-pull; when false, outputs are open-drain. This is important for LEDs with zener diodes.

### Method
setOutputMode

### Signature
void setOutputMode(bool totempole);

### Parameters
- **totempole** (bool) - Required - true = totem-pole (push-pull) drive; false = open-drain

### Behavior
Reads PCA9685_MODE2 and sets (MODE2_OUTDRV) or clears it accordingly. Doxygen warning in source: LEDs with integrated zener diodes should only be driven in open-drain mode.

### Example
```cpp
pwm.setOutputMode(true);  // push-pull outputs for servos
```

### Example
```cpp
pwm.setOutputMode(false); // open-drain for LEDs with zener protection
```

### Source
Adafruit_PWMServoDriver.h:86, Adafruit_PWMServoDriver.cpp:189
```

--------------------------------

### reset

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Resets the PWM driver to its default state.

```APIDOC
## reset

### Description
Resets the PWM driver to its default state.

### Method
reset

### Parameters
None

### Returns
None
```

--------------------------------

### setPWMFreq clamping behavior

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Demonstrates how out-of-range frequency values are silently clamped to the supported 1–3500 Hz range.

```cpp
// Requesting out-of-range values is clamped silently:
pwm.setPWMFreq(0.5);   // clamped to 1 Hz
pwm.setPWMFreq(10000); // clamped to 3500 Hz
pwm.setPWMFreq(1600);  // near the practical maximum
```

--------------------------------

### setPin

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Sets a pin to a specified value (on/off).

```APIDOC
## setPin

### Description
Sets a pin to a specified value (on/off).

### Method
setPin

### Parameters
None

### Returns
None
```

--------------------------------

### Adafruit_PWMServoDriver(const uint8_t addr)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Constructor that binds the driver to a custom I2C address on the global Wire instance.

```APIDOC
## Adafruit_PWMServoDriver(const uint8_t addr)

### Description
Constructor that initializes the driver with a custom I2C address on the global Wire instance.

### Method
Constructor

### Signature
```cpp
Adafruit_PWMServoDriver(const uint8_t addr);
```

### Parameters
- **addr** (uint8_t) - Required - The 7-bit I2C address of the chip.

### Example
```cpp
Adafruit_PWMServoDriver pwm(0x40); // chip with address pins cut for 0x40
```

### Example with Multiple Chips
```cpp
// Two chips on the same bus: one at 0x40, one at 0x41
Adafruit_PWMServoDriver pwmA(0x40);
Adafruit_PWMServoDriver pwmB(0x41);
pwmA.begin();
pwmB.begin();
```
```

--------------------------------

### setExtClk

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Switches the chip from the internal 25 MHz oscillator to the EXTCLK pin, configuring the prescale register for the external clock.

```APIDOC
## setExtClk

### Description
Switches the chip from the internal 25 MHz oscillator to the EXTCLK pin, configuring the prescale register for the external clock.

### Method
setExtClk

### Signature
void setExtClk(uint8_t prescale);

### Parameters
- **prescale** (uint8_t) - Required - Prescale value to write to PCA9685_PRESCALE for the external clock

### Example
```cpp
pwm.setExtClk(4);
```

```cpp
// begin() delegates here when a nonzero prescale is passed
pwm.begin(9); // equivalent to begin() + setExtClk(9)
```
```

--------------------------------

### Basic reset usage

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Resetting the chip registers, useful after a brownout.

```cpp
pwm.reset(); // re-initialize chip registers after brownout
```

--------------------------------

### setPWMFreq method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for setting the PWM update frequency.

```cpp
void setPWMFreq(float freq);
```

--------------------------------

### setOutputMode(bool totempole)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Sets the output mode to push-pull (true) or open-drain (false). This controls the MODE2_OUTDRV bit.

```APIDOC
## setOutputMode(bool totempole)

### Description
Sets the output mode to push-pull (true) or open-drain (false). This controls the MODE2_OUTDRV bit.

### Method Signature
`void setOutputMode(bool totempole)`

### Parameters
- **totempole** (bool) - Required - true for push-pull, false for open-drain.
```

--------------------------------

### getOscillatorFrequency method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for retrieving the currently tracked oscillator frequency.

```cpp
uint32_t getOscillatorFrequency(void);
```

--------------------------------

### setOscillatorFrequency method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for setting the internal oscillator frequency.

```cpp
void setOscillatorFrequency(uint32_t freq);
```

--------------------------------

### reset method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The reset method performs a software reset of the PCA9685 chip.

```cpp
void reset();
```

--------------------------------

### Adafruit_PWMServoDriver(const uint8_t addr, TwoWire& i2c)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Constructor that binds the driver to a custom I2C address on a specified TwoWire bus instance.

```APIDOC
## Adafruit_PWMServoDriver(const uint8_t addr, TwoWire& i2c)

### Description
Constructor that initializes the driver with a custom I2C address on a specified TwoWire bus instance, useful for secondary I2C buses.

### Method
Constructor

### Signature
```cpp
Adafruit_PWMServoDriver(const uint8_t addr, TwoWire& i2c);
```

### Parameters
- **addr** (uint8_t) - Required - The 7-bit I2C address of the chip.
- **i2c** (TwoWire&) - Required - Reference to the TwoWire bus object to use (e.g., Wire, Wire1).

### Example
```cpp
Adafruit_PWMServoDriver pwm(0x40, Wire); // explicit bus
```

### Example with Dual Bus
```cpp
// Dual bus: PCA9685 on Wire1 while Wire stays free for sensors
Adafruit_PWMServoDriver pwm(0x40, Wire1);
pwm.begin();
```
```

--------------------------------

### readPrescale

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Reads the prescale register value.

```APIDOC
## readPrescale

### Description
Reads the prescale register value.

### Method
readPrescale

### Parameters
None

### Returns
Prescale value
```

--------------------------------

### setPWMFreq(float freq)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Sets the PWM frequency in Hz, clamped to 1-3500 Hz. This affects all 16 channels. The default frequency set by begin() is 1000 Hz.

```APIDOC
## setPWMFreq(float freq)

### Description
Sets the PWM frequency in Hz, clamped to 1-3500 Hz. This affects all 16 channels. The default frequency set by begin() is 1000 Hz.

### Method Signature
`void setPWMFreq(float freq)`

### Parameters
- **freq** (float) - Required - PWM frequency in Hz. Clamped to 1-3500.

### Example
```cpp
pwm.setPWMFreq(1600);
```
```

--------------------------------

### setPWM()

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Sets the PWM output for a specific channel. Returns 1 if the I2C write fails, 0 on success.

```APIDOC
## setPWM()

### Description
Sets the PWM output for a specific channel by writing the on and off values.

### Method
setPWM

### Signature
int setPWM(uint8_t num, uint16_t on, uint16_t off)

### Parameters
- **num** (uint8_t) - Required - Channel number (0-15)
- **on** (uint16_t) - Required - Value for the ON counter (0-4095)
- **off** (uint16_t) - Required - Value for the OFF counter (0-4095)

### Return Value
- **int** - Returns `0` on success, `1` if the 5-byte I2C write failed.

### Error Handling
A return value of `1` indicates a transient bus error. Retry or halt.

### Example
```cpp
pwm.setPWM(0, 0, 2048); // set channel 0 to 50% duty cycle
```
```

--------------------------------

### writeMicroseconds

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Converts microseconds to 12-bit ticks and sets the PWM output. Useful for analog servo control.

```APIDOC
## writeMicroseconds

### Description
Converts microseconds to 12-bit ticks using the formula pulselength = 1000000 * (readPrescale() + 1) / _oscillator_freq, then calls setPWM(num, 0, pulse). Note: output is not precise.

### Method
void writeMicroseconds(uint8_t num, uint16_t Microseconds)

### Parameters
- **num** (uint8_t) - Required - PWM output channel, 0-15
- **Microseconds** (uint16_t) - Required - Pulse width in microseconds to turn the output ON

### Returns
Nothing

### Example
```cpp
pwm.setPWMFreq(50);                 // 50 Hz period = 20000 us
pwm.writeMicroseconds(0, 1500);     // ~1.5 ms pulse = center position
```
```

--------------------------------

### writeMicroseconds function signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for converting microseconds to PWM ticks.

```cpp
void writeMicroseconds(uint8_t num, uint16_t Microseconds);
```

--------------------------------

### setOutputMode

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Sets the output mode (totem-pole or open-drain) for the PWM outputs.

```APIDOC
## setOutputMode

### Description
Sets the output mode (totem-pole or open-drain) for the PWM outputs.

### Method
setOutputMode

### Parameters
None

### Returns
None
```

--------------------------------

### setPWMFreq

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Sets the PWM frequency for the driver.

```APIDOC
## setPWMFreq

### Description
Sets the PWM frequency for the driver.

### Method
setPWMFreq

### Parameters
None

### Returns
None
```

--------------------------------

### sleep

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Puts the PWM driver into sleep mode.

```APIDOC
## sleep

### Description
Puts the PWM driver into sleep mode.

### Method
sleep

### Parameters
None

### Returns
None
```

--------------------------------

### writeMicroseconds

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Writes a pulse width in microseconds to a specified channel.

```APIDOC
## writeMicroseconds

### Description
Writes a pulse width in microseconds to a specified channel.

### Method
writeMicroseconds

### Parameters
None

### Returns
None
```

--------------------------------

### Adafruit_PWMServoDriver Class

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

The main class for controlling the PWM servo driver. Provides methods to initialize and control PWM outputs.

```APIDOC
## Adafruit_PWMServoDriver Class

### Description
The Adafruit_PWMServoDriver class provides an interface to control PWM outputs for servos and LEDs. It includes methods for initialization, frequency setting, output mode configuration, and PWM control.

### Methods
- begin
- reset
- sleep
- wakeup
- setExtClk
- setPWMFreq
- setOutputMode
- getPWM
- setPWM
- setPin
- readPrescale
- writeMicroseconds
- setOscillatorFrequency
- getOscillatorFrequency

### Constants
- FREQUENCY_OSCILLATOR
```

--------------------------------

### setPWM

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Sets the PWM value for a specified channel.

```APIDOC
## setPWM

### Description
Sets the PWM value for a specified channel.

### Method
setPWM

### Parameters
None

### Returns
None
```

--------------------------------

### getPWM function signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for reading the 12-bit tick count from the PWM registers.

```cpp
uint16_t getPWM(uint8_t num, bool off = false);
```

--------------------------------

### sleep method signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The sleep method puts the chip into a low-power mode by turning off the oscillator.

```cpp
void sleep();
```

--------------------------------

### readPrescale function signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for reading the current prescale register value.

```cpp
uint8_t readPrescale(void);
```

--------------------------------

### setPWM function signature

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

The function signature for setting the on and off ticks for a PWM channel.

```cpp
uint8_t setPWM(uint8_t num, uint16_t on, uint16_t off);
```

--------------------------------

### sleep

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Puts the chip into low-power mode by setting the MODE1_SLEEP bit, stopping the oscillator and freezing outputs.

```APIDOC
## sleep

### Description
Puts the chip into low-power mode by setting the MODE1_SLEEP bit, stopping the oscillator and freezing outputs.

### Method
sleep

### Signature
void sleep();

### Example
```cpp
pwm.sleep(); // oscillator stopped, outputs frozen
```

```cpp
// Power-down sequence before unplugging
pwm.sleep();
delay(100);
```
```

--------------------------------

### setOscillatorFrequency

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Sets the oscillator frequency used for PWM calculations.

```APIDOC
## setOscillatorFrequency

### Description
Sets the oscillator frequency used for PWM calculations.

### Method
setOscillatorFrequency

### Parameters
None

### Returns
None
```

--------------------------------

### setPWM

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Sets the on and off ticks for a PWM output channel. Supports special values for fully ON and fully OFF states.

```APIDOC
## setPWM

### Description
Sets the on and off ticks for a PWM output channel. Supports special values for fully ON (on=4096, off=0) and fully OFF (on=0, off=4096) states.

### Method
uint8_t setPWM(uint8_t num, uint16_t on, uint16_t off)

### Parameters
- **num** (uint8_t) - Required - PWM output channel, 0-15
- **on** (uint16_t) - Required - Tick (0-4095) in the 4096-step cycle where the output turns ON
- **off** (uint16_t) - Required - Tick (0-4095) where the output turns OFF

### Returns
uint8_t: 0 on success, 1 if the 5-byte I2C write failed

### Special Values
- on=4096, off=0: fully ON
- on=0, off=4096: fully OFF

### Example
```cpp
pwm.setPWM(0, 0, 2048); // 50% duty cycle on channel 0
pwm.setPWM(1, 0, 4096); // fully off
```
```

--------------------------------

### setOscillatorFrequency(uint32_t freq)

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/configuration.md

Sets the assumed oscillator frequency in Hz. This is used for prescale and pulse calculations. The default is 25000000 Hz (FREQUENCY_OSCILLATOR), set inside begin().

```APIDOC
## setOscillatorFrequency(uint32_t freq)

### Description
Sets the assumed oscillator frequency in Hz. This is used for prescale and pulse calculations. The default is 25000000 Hz (FREQUENCY_OSCILLATOR), set inside begin().

### Method Signature
`void setOscillatorFrequency(uint32_t freq)`

### Parameters
- **freq** (uint32_t) - Required - Oscillator frequency in Hz. Typical calibration range: 23-27 MHz.

### Example
```cpp
pwm.setOscillatorFrequency(27000000);
```
```

--------------------------------

### FREQUENCY_OSCILLATOR

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/keywords.txt

Constant representing the default oscillator frequency.

```APIDOC
## FREQUENCY_OSCILLATOR

### Description
Constant representing the default oscillator frequency.

### Type
Constant
```

--------------------------------

### getPWM

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Reads the 12-bit tick count from the selected register pair for a PWM channel. Can read either the ON or OFF registers based on the off parameter.

```APIDOC
## getPWM

### Description
Reads the 12-bit tick count (0-4095) from the selected register pair for a PWM output channel. Can read either the ON or OFF registers based on the off parameter.

### Method
uint16_t getPWM(uint8_t num, bool off = false)

### Parameters
- **num** (uint8_t) - Required - PWM output channel, 0-15
- **off** (bool) - Optional (default: false) - true to read the LEDn OFF registers; false to read the LEDn ON registers

### Returns
uint16_t: the 12-bit tick count (0-4095) from the selected register pair (low byte | high byte << 8)

### Example
```cpp
uint16_t on  = pwm.getPWM(3);       // on-tick of channel 3
uint16_t off = pwm.getPWM(3, true); // off-tick of channel 3
```
```

--------------------------------

### setOscillatorFrequency

Source: https://github.com/adafruit/adafruit-pwm-servo-driver-library/blob/master/_autodocs/api-reference/Adafruit_PWMServoDriver.md

Sets the internal oscillator frequency used for all frequency and pulse calculations. Call before setPWMFreq() or writeMicroseconds() to take effect.

```APIDOC
## setOscillatorFrequency

### Description
Sets the internal `_oscillator_freq` used for all frequency and pulse calculations. Call **before** `setPWMFreq()`/`writeMicroseconds()` to take effect.

### Method
void setOscillatorFrequency(uint32_t freq);

### Parameters
- **freq** (uint32_t) - Required - Assumed oscillator frequency in Hz (default is `FREQUENCY_OSCILLATOR` = 25000000, applied in `begin()`)

### Example
```cpp
pwm.setOscillatorFrequency(27000000); // calibrated per chip with a scope
pwm.setPWMFreq(50);
```

```cpp
// Calibrate against a measured PWM update rate (examples/oscillator.ino
// automates measuring the real frequency with an interrupt counter):
pwm.setOscillatorFrequency(26000000);
```
```