jor4000/easyservo

Readme

# Servo Component

Este componente proporciona un controlador profesional para servos hobby utilizando el periférico MCPWM del ESP32.

## Características

- Configuración simple de MCPWM para control de servos en un pin GPIO.
- Rango de ángulos configurable.
- Rango de pulsos configurable (microsegundos).
- Frecuencia PWM configurable.
- Manejo de errores consistente mediante `esp_err_t`.

## Requisitos

El componente depende de los siguientes módulos de ESP-IDF:

- `esp_driver_mcpwm`
- `esp_driver_gpio`

## Uso

Incluye el encabezado del componente y crea una instancia:

```cpp
#include "Servo.hpp"

Servo servo(GPIO_NUM_4);
```

Configura el rango de ángulo antes de inicializar el servo:

```cpp
servo.setAngleRange(-90.0f, 90.0f);
```

Inicia el componente y mueve el servo:

```cpp
esp_err_t err = servo.begin();
if (err != ESP_OK) {
    ESP_LOGE("MAIN", "No se pudo inicializar el servo: %s", esp_err_to_name(err));
    return;
}

servo.write(0.0f);
servo.write(45.0f);
servo.writeMicroseconds(1500);
```

## API

- `Servo(gpio_num_t pin, uint32_t frequencyHz = 50)`
  - Constructor que inicializa el pin de salida PWM y la frecuencia predeterminada.

- `esp_err_t begin()`
  - Configura MCPWM y arranca la señal PWM.
  - Retorna `ESP_OK` en éxito o un código de error de ESP-IDF.

- `esp_err_t write(float angle)`
  - Mueve el servo al ángulo deseado dentro del rango configurado.
  - Los valores fuera del rango se recortan automáticamente.

- `esp_err_t writeMicroseconds(uint32_t pulseWidthUs)`
  - Ajusta directamente el ancho de pulso en microsegundos.
  - El valor se recorta al rango configurado de pulsos.

- `esp_err_t setAngleRange(float minAngle, float maxAngle)`
  - Define el rango de ángulos válido para el servo.

- `esp_err_t setPulseWidthRange(uint32_t minPulseUs, uint32_t maxPulseUs)`
  - Define el rango de ancho de pulso válido para el servo.

- `esp_err_t setFrequency(uint32_t frequencyHz)`
  - Define la frecuencia del PWM antes de inicializar el componente.

- `bool isReady() const noexcept`
  - Devuelve `true` si el servo se ha inicializado correctamente.

## Ejemplo completo

```cpp
#include "Servo.hpp"
#include <esp_err.h>
#include <esp_log.h>

static const char *TAG = "SERVO_EXAMPLE";
Servo servo(GPIO_NUM_4);

extern "C" void app_main()
{
    servo.setAngleRange(-90.0f, 90.0f);

    esp_err_t err = servo.begin();
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "Error al inicializar el servo: %s", esp_err_to_name(err));
        return;
    }

    servo.write(0.0f);
    vTaskDelay(pdMS_TO_TICKS(1000));
    servo.write(90.0f);
}
```