High-level driver for DC motors. More...

Detailed Description

High-level driver for DC motors.

This API aims to handle DC motor analogic driver. Driver boards using serial communication protocols (I2C, UART, etc...) are not in the scope of this driver. Mainly designed for H-bridge, it could also drive some brushless drivers.

Some H-bridge driver circuits handle several motors. Maximum motor number by H-bridge is set to 2 with CONFIG_MOTOR_DRIVER_MAX macro. This macro can be overridden to support H-bridge drivers with more outputs. However, CONFIG_MOTOR_DRIVER_MAX should not exceed PWM channels number.

motor_driver_t structure represents an H-bridge. As several H-bridge can share a same PWM device, motor_driver_t can represent a group of H-bridge.

Most of H-bridge boards uses the following I/Os for each motor :

Enable/disable GPIO
One or two direction GPIOs
A PWM signal

*
* Each motor direction is controlled (assuming it is enabled) according to
* the following truth table :
*  __________________________
* | DIR0 | DIR1 |  BEHAVIOR  |
* |--------------------------|
* |  0   |  0   | BRAKE LOW  |
* |  0   |  1   |     CW     |
* |  1   |  0   |     CCW    |
* |  1   |  1   | BRAKE HIGH |
* |______|______|____________|
*
* In case of single GPIO for direction, only DIR0 is used without brake
* capability :
*  ___________________
* | DIR0 |  BEHAVIOR  |
* |-------------------|
* |   0  |     CW     |
* |   1  |     CCW    |
* |______|____________|
*
* Some boards add a brake pin with single direction GPIO :
*  ________________________
* | DIR | BRAKE | BEHAVIOR |
* |------------------------|
* |  0  |   0   |    CW    |
* |  0  |   1   |   BRAKE  |
* |  1  |   0   |    CCW   |
* |  1  |   1   |   BRAKE  |
* |_____|_______|__________|
*
*

From this truth tables we can extract two direction states :

CW (ClockWise)
CCW (Counter ClockWise) and a brake capability

BRAKE LOW is functionally the same than BRAKE HIGH but some H-bridge only brake on BRAKE HIGH due to hardware. In case of single direction GPIO, there is no BRAKE.

In case of brake, PWM duty cycle is always set to 0.

Topics
	motor_driver driver build configuration

Files
file	motor_driver.h
	High-level driver for DC motors.

file	motor_driver_params.h
	Default configuration for motor driver.

Data Structures
struct	motor_t
	Describe DC motor with PWM channel and GPIOs. More...

struct	motor_driver_params_t
	Describe DC motor driver with PWM device and motors array. More...

struct	_motor_driver_t
	Motor driver. More...

Typedefs
typedef struct _motor_driver_t	motor_driver_t
	Motor driver.

typedef void(*	motor_set_post_cb_t) (const motor_driver_t *motor_driver, uint8_t motor_id, int32_t pwm_duty_cycle)
	Motor callback.

typedef void(*	motor_set_cb_t) (const motor_t *motor, motor_direction_t direction)
	Motor set callback.

typedef void(*	motor_brake_cb_t) (const motor_t *motor, bool brake)
	Motor brake callback.

Enumerations
enum	motor_driver_mode_t { MOTOR_DRIVER_2_DIRS = 0 , MOTOR_DRIVER_1_DIR = 1 , MOTOR_DRIVER_1_DIR_BRAKE = 2 }
	Describe DC motor driver modes. More...

enum	motor_direction_t { MOTOR_CW = 0 , MOTOR_CCW = 1 }
	Describe DC motor direction states. More...

Functions
int	motor_driver_init (motor_driver_t motor_driver, const motor_driver_params_t params)
	Initialize DC motor driver board.

int	motor_set (const motor_driver_t *motor_driver, uint8_t motor_id, int32_t pwm_duty_cycle)
	Set motor speed and direction.

int	motor_brake (const motor_driver_t *motor_driver, uint8_t motor_id)
	Brake the motor of a given motor driver.

void	motor_enable (const motor_driver_t *motor_driver, uint8_t motor_id)
	Enable a motor of a given motor driver.

void	motor_disable (const motor_driver_t *motor_driver, uint8_t motor_id)
	Disable a motor of a given motor driver.

Typedef Documentation

◆ motor_brake_cb_t

typedef void(* motor_brake_cb_t) (const motor_t *motor, bool brake)

Motor brake callback.

Called to brake a motor.

Definition at line 161 of file motor_driver.h.

◆ motor_driver_t

typedef struct _motor_driver_t motor_driver_t

Motor driver.

Definition at line 143 of file motor_driver.h.

◆ motor_set_cb_t

typedef void(* motor_set_cb_t) (const motor_t *motor, motor_direction_t direction)

Motor set callback.

Called to set motor speed.

Definition at line 155 of file motor_driver.h.

◆ motor_set_post_cb_t

typedef void(* motor_set_post_cb_t) (const motor_driver_t *motor_driver, uint8_t motor_id, int32_t pwm_duty_cycle)

Motor callback.

It is called at end of motor_set()

Definition at line 148 of file motor_driver.h.

Enumeration Type Documentation

◆ motor_direction_t

enum motor_direction_t

Describe DC motor direction states.

Enumerator
MOTOR_CW	clockwise
MOTOR_CCW	counter clockwise

Definition at line 121 of file motor_driver.h.

◆ motor_driver_mode_t

enum motor_driver_mode_t

Describe DC motor driver modes.

Enumerator
MOTOR_DRIVER_2_DIRS	2 GPIOs for direction, \ handling brake
MOTOR_DRIVER_1_DIR	single GPIO for direction, \ no brake
MOTOR_DRIVER_1_DIR_BRAKE	single GPIO for direction, \ single GPIO for brake

Definition at line 109 of file motor_driver.h.

Function Documentation

◆ motor_brake()

int motor_brake	(	const motor_driver_t *	motor_driver,
		uint8_t	motor_id )

Brake the motor of a given motor driver.

Parameters

[in]	motor_driver	motor driver to which motor is attached
[in]	motor_id	motor ID on driver

Return values

0	on success
-EINVAL	on bad motor ID

◆ motor_disable()

void motor_disable	(	const motor_driver_t *	motor_driver,
		uint8_t	motor_id )

Disable a motor of a given motor driver.

Parameters

[in]	motor_driver	motor driver to which motor is attached
[in]	motor_id	motor ID on driver

◆ motor_driver_init()

int motor_driver_init	(	motor_driver_t *	motor_driver,
		const motor_driver_params_t *	params )

Initialize DC motor driver board.

Parameters

[out]	motor_driver	motor driver to initialize
[in]	params	motor driver parameters

Return values

0	on success
-EINVAL	on bad parameter value
-EIO	on failed GPIO init

◆ motor_enable()

void motor_enable	(	const motor_driver_t *	motor_driver,
		uint8_t	motor_id )

Enable a motor of a given motor driver.

Parameters

[in]	motor_driver	motor driver to which motor is attached
[in]	motor_id	motor ID on driver

◆ motor_set()

int motor_set	(	const motor_driver_t *	motor_driver,
		uint8_t	motor_id,
		int32_t	pwm_duty_cycle )

Set motor speed and direction.

Parameters

[in]	motor_driver	motor driver to which motor is attached
[in]	motor_id	motor ID on driver
[in]	pwm_duty_cycle	signed PWM duty_cycle to set motor speed and direction

Return values

0	on success
-EINVAL	on bad motor ID

Detailed Description

Topics

Files

Data Structures

Typedefs

Enumerations

Functions

Typedef Documentation

◆ motor_brake_cb_t

◆ motor_driver_t

◆ motor_set_cb_t

◆ motor_set_post_cb_t

Enumeration Type Documentation

◆ motor_direction_t

◆ motor_driver_mode_t

Function Documentation

◆ motor_brake()

◆ motor_disable()

◆ motor_driver_init()

◆ motor_enable()

◆ motor_set()