[Task] Generic DC Motor Control via PWM

[vasilaking]

Task: Generic DC Motor Control via PWM (HAL Integration)

Summary

Implement a generic DC motor control module using PWM within the sparq embedded framework, enabling speed control and direction control through the HAL layer (initially targeting ESP32).

Objective

Provide a reusable abstraction for controlling DC motors using PWM and GPIO direction pins.

• Enable speed control via PWM duty cycle
• Enable direction control (forward/reverse/stop)
• Integrate cleanly into HAL architecture (PAL/HAL separation)
• Prepare interface for future motor drivers and hardware targets

Scope

Included

• DC motor driver abstraction (generic interface)
• PWM-based speed control
• GPIO-based direction control (H-bridge compatible)
• Basic API:
  • set_speed(percent)
  • set_direction(forward/reverse/stop)
• ESP32 implementation (initial target)
• Support for single motor instance (expandable design)

Not Included

• Closed-loop control (PID, encoders)
• Advanced motor profiling or calibration
• Multi-motor orchestration system
• Safety systems beyond basic stop control

Requirements

• Must use PWM for speed control (ESP32 LEDC or equivalent)
• Must use GPIO abstraction for direction pins (no direct register access)
• Must support H-bridge style motor drivers (e.g., L298N, DRV8833)
• Must be non-blocking (no delays in control path)
• Must be portable to future embedded targets via HAL interface

Acceptance Criteria

Conditions that must be met for the task to be considered complete.

• Motor speed can be controlled via PWM duty cycle
• Motor direction can be set (forward/reverse/stop)
• Works on ESP32 hardware with real motor driver
• No direct hardware access outside HAL layer
• Clean API usable by higher-level application layer
• Code compiles and integrates into sparq build system

Deliverables

Expected outputs from this task.

• DC motor HAL driver module
• PWM + GPIO integration layer for motor control
• Example usage (test/demo controlling motor speed & direction)
• Basic documentation of API

Dependencies

• Depends on:
  • GPIO input/output abstraction layer (HAL-level)
  • PWM abstraction layer (for ESP32 LEDC or equivalent)
• Blocked by:
  • Generic GPIO HAL implementation (input/output pins not yet finalized in framework)
  • PWM abstraction layer (if not already implemented)

Priority

• Critical
• High
• Medium
• Low

Estimated Effort

• Estimated time: 2–4 days (once GPIO + PWM HAL exists)
• Complexity:
  • Small
  • Medium
  • Large

Assignee

@StefanAngelovski

Notes

Additional implementation details, references, links or instructions.

• Design should assume future support for multiple motor types (DC, stepper, servo)
• Keep interface hardware-agnostic to allow reuse across ESP32, STM32, etc.
• H-bridge control should be abstracted, not hardcoded to a specific driver
• Future extension: encoder feedback + closed-loop control (PID) can be layered on top of this module