139 lines
5.3 KiB
Markdown
139 lines
5.3 KiB
Markdown
# Enhanced Servo Library for ESP32
|
||
|
||
Compatible with Arduino ESP32 v3.0.0+ with advanced PWM hardware support.
|
||
|
||
https://github.com/espressif/arduino-esp32/releases
|
||
|
||
This library provides enhanced PWM control for ESP32 boards, faithfully replicating Arduino Servo semantics while adding advanced hardware support:
|
||
|
||
## Key Features
|
||
|
||
- **ESP32S3 MCPWM Support**: Hardware-accelerated servo control for optimal timing precision
|
||
- **Dual Hardware Architecture**: 20 PWM channels (8 LEDC + 12 MCPWM) with intelligent allocation
|
||
- **Flexible Frequency Modes**: Variable-frequency PWM and fixed-frequency servo control
|
||
- **Automatic Fallback**: Seamless hardware allocation when preferred resources are unavailable
|
||
- **Backward Compatible**: Drop-in replacement for existing Arduino Servo code
|
||
|
||
## Hardware Support
|
||
|
||
| ESP32 Variant | LEDC Channels | MCPWM Channels | Total Channels |
|
||
|---------------|---------------|----------------|----------------|
|
||
| ESP32S3 | 8 | 12 | 20 |
|
||
| ESP32S2 | 8 | - | 8 |
|
||
| ESP32 | 16 | - | 16 |
|
||
| ESP32C3 | 6 | - | 6 |
|
||
| ESP32C5 | 6 | 6 (not implemented) | 12 (6 supported) |
|
||
|
||
## Usage Examples
|
||
|
||
### Basic Servo Control
|
||
```cpp
|
||
#include <ESP32Servo.h>
|
||
|
||
Servo myservo;
|
||
myservo.attach(18); // Attach to pin 18
|
||
myservo.write(90); // Set to 90 degrees
|
||
```
|
||
|
||
### Advanced PWM Control
|
||
```cpp
|
||
#include <ESP32PWM.h>
|
||
|
||
// Variable frequency (default) - LEDC preferred
|
||
ESP32PWM pwm1; // or ESP32PWM pwm1(true);
|
||
|
||
// Fixed frequency - MCPWM preferred
|
||
ESP32PWM pwm2(false); // Optimal for servos
|
||
|
||
pwm1.attachPin(19, 1000, 10); // 1kHz, 10-bit resolution
|
||
pwm2.attachPin(21, 50, 10); // 50Hz, 10-bit resolution
|
||
```
|
||
# Documentation by Doxygen
|
||
|
||
[ESP32Servo Doxygen](https://madhephaestus.github.io/ESP32Servo/annotated.html)
|
||
|
||
## License
|
||
|
||
Copyright (c) 2017 John K. Bennett. All right reserved.
|
||
|
||
This library is free software; you can redistribute it and/or
|
||
modify it under the terms of the GNU Lesser General Public
|
||
License as published by the Free Software Foundation; either
|
||
version 2.1 of the License, or (at your option) any later version.
|
||
|
||
This library is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
Lesser General Public License for more details.
|
||
|
||
You should have received a copy of the GNU Lesser General Public
|
||
License along with this library; if not, write to the Free Software
|
||
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
||
|
||
## Library Description:
|
||
```
|
||
Servo - Class for manipulating servo motors connected to ESP32 pins.
|
||
|
||
int attach(pin ) - Attaches the given GPIO pin to the next free channel
|
||
(channels that have previously been detached are used first),
|
||
returns channel number or 0 if failure. All pin numbers are allowed,
|
||
but only pins 2,4,12-19,21-23,25-27,32-33 are recommended.
|
||
|
||
int attach(pin, min, max ) - Attaches to a pin setting min and max
|
||
values in microseconds; enforced minimum min is 500, enforced max
|
||
is 2500. Other semantics are the same as attach().
|
||
|
||
void write () - Sets the servo angle in degrees; a value below 500 is
|
||
treated as a value in degrees (0 to 180). These limit are enforced,
|
||
i.e., values are constrained as follows:
|
||
Value Becomes
|
||
----- -------
|
||
< 0 0
|
||
0 - 180 value (treated as degrees)
|
||
181 - 499 180
|
||
500 - (min-1) min
|
||
min-max (from attach or default) value (treated as microseconds)
|
||
(max+1) - 2500 max
|
||
|
||
void writeMicroseconds() - Sets the servo pulse width in microseconds.
|
||
min and max are enforced (see above).
|
||
|
||
int read() - Gets the last written servo pulse width as an angle between 0 and 180.
|
||
|
||
int readMicroseconds() - Gets the last written servo pulse width in microseconds.
|
||
|
||
bool attached() - Returns true if this servo instance is attached to a pin.
|
||
|
||
void detach() - Stops an the attached servo, frees the attached pin, and frees
|
||
its channel for reuse.
|
||
```
|
||
|
||
### **New ESP32-specific functions**
|
||
|
||
```
|
||
setTimerWidth(value) - Sets the PWM timer width (must be 16-20) (ESP32 ONLY);
|
||
as a side effect, the pulse width is recomputed.
|
||
|
||
int readTimerWidth() - Gets the PWM timer width (ESP32 ONLY)
|
||
```
|
||
|
||
### Useful Defaults:
|
||
|
||
default min pulse width for attach(): 544us
|
||
|
||
default max pulse width for attach(): 2400us
|
||
|
||
default timer width 16 (if timer width is not set)
|
||
|
||
default pulse width 1500us (servos are initialized with this value)
|
||
|
||
MINIMUM pulse with: 500us
|
||
|
||
MAXIMUM pulse with: 2500us
|
||
|
||
MAXIMUM number of servos: Varies by ESP32 variant
|
||
- ESP32S3: 20 channels (8 LEDC + 12 MCPWM)
|
||
- ESP32: 16 channels (16 LEDC)
|
||
- ESP32S2: 8 channels (8 LEDC)
|
||
- ESP32C3: 6 channels (6 LEDC)
|
||
- ESP32C5: 12 (6 implemented) channels (6 LEDC + 6 MCPWM (not supported))
|