#include <MD_SmartCar.h>

Collaboration diagram for MD_SmartCar:

Classes
struct	actionItem_t

Public Member Functions
Class constructor and destructor.
	MD_SmartCar (SC_DCMotor ml, SC_MotorEncoder el, SC_DCMotor mr, SC_MotorEncoder er)

	~MD_SmartCar (void)

Methods for core object control.
bool	begin (uint16_t ppr, uint16_t ppsMax, uint16_t dWheel, uint16_t lBase)

void	setVehicleParameters (uint16_t ppr, uint16_t ppsMax, uint16_t dWheel, uint16_t lBase)

void	run (void)

bool	isRunning (void)

bool	isRunning (uint8_t mtr)

Methods for free running the vehicle.
void	drive (int8_t vLinear, int8_t vAngularD)

void	drive (int8_t vLinear)

void	drive (int8_t vLinear, float vAngularR)

void	stop (void)

void	setLinearVelocity (int8_t vel)

int8_t	getLinearVelocity (void)

void	setAngularVelocity (float angR)

void	setAngularVelocity (int8_t angD)

float	getAngularVelocity (void)

Methods for precision movements of the vehicle.
void	move (float angL, float angR)

void	move (int16_t angL, int16_t angR)

void	move (int16_t len)

void	spin (int16_t fraction)

void	startSequence (const actionItem_t *actionList)

void	startSequence (actionItem_t *actionList)

bool	isSequenceComplete (void)

Methods for EEPROM and Configuration Management.
void	loadConfig (void)

void	saveConfig (void)

bool	setMoveSP (uint8_t units)

uint8_t	getMoveSP (void)

bool	setKickerSP (uint8_t units)

uint8_t	getKickerSP (void)

void	setSpinSP (float adjust)

float	getSpinSP (void)

void	setMinMotorSP (uint8_t units)

void	setMaxMotorSP (uint8_t units)

uint8_t	getMinMotorSP (void)

uint8_t	getMaxMotorSP (void)

void	setPIDTuning (uint8_t mtr, float Kp, float Ki, float Kd)

void	getPIDTuning (uint8_t mtr, float &Kp, float &Ki, float &Kd)

uint16_t	getPulsePerRev ()

Utility methods.
float	deg2rad (int16_t deg)

float	len2rad (int16_t len)

Structures, Enumerated Types and Constants.
enum	actionId_t { DRIVE , MOVE , SPIN , PAUSE , STOP , END }

static const uint8_t	MAX_MOTOR = 2

Detailed Description

Core object for the MD_SmartCar library

Member Enumeration Documentation

◆ actionId_t

enum MD_SmartCar::actionId_t

Enumerated type for Action Items operation

Specifies which operation is being defined in the actionItem_t

Enumerator
DRIVE	executes drive(); param 0 lin vel, param 1 angular velocity
MOVE	executes a move(); param 0 left rotate, param 1 right rotate
SPIN	executes a spin(); param 0 spin percentage
PAUSE	executes a pause; param 0 milliseconds pause
STOP	executes a stop()
END	marks the end of the action list; should always be last item.

Constructor & Destructor Documentation

◆ MD_SmartCar()

MD_SmartCar::MD_SmartCar	(	SC_DCMotor *	ml,
		SC_MotorEncoder *	el,
		SC_DCMotor *	mr,
		SC_MotorEncoder *	er
	)

Class Constructor

Instantiate a new instance of the class. This variant is for motor controllers that have a PWM input for speed control.

The main function for the core object is to reset the internal shared variables and timers to default values.

Parameters

ml	The object for controlling the left side motor.
el	The object to use as the left side encoder input.
mr	The object for controlling the right side motor.
er	The object to use as the right side encoder input.

◆ ~MD_SmartCar()

MD_SmartCar::~MD_SmartCar ( void )

Class Destructor.

Release any allocated memory and clean up anything else.

Member Function Documentation

◆ begin()

bool MD_SmartCar::begin	(	uint16_t	ppr,
		uint16_t	ppsMax,
		uint16_t	dWheel,
		uint16_t	lBase
	)

Initialize the object.

Initialize the object data. This needs to be called during setup() to reset new items that cannot be done during object creation.

Vehicle constants are passed through to the setVehicleParameters() method. See comments for that method for more details.

See also: setVehicleParameters();

Parameters

ppr	Number of encoder pulses per wheel revolution.
ppsMax	Maximum number of encoder pulses per second at top speed (100% velocity).
dWheel	Wheel diameter in mm.
lBase	Base length (distance between wheel centers) in mm

Returns: false if either encoder did not reset, true otherwise.

◆ deg2rad()

float MD_SmartCar::deg2rad ( int16_t deg )

Convert degrees to radians.

Convert the degrees measure specified into radians.

Parameters

deg	the value in degrees to be converted.

Returns: the converted value

◆ drive() [1/3]

void MD_SmartCar::drive ( int8_t vLinear )

Drive the vehicle along a straight path.

Run the vehicle along a straight path with the specified velocity. Moves the motors under PID control.

The velocity is specified as a percentage of the maximum vehicle velocity [0..100]. Positive velocity move the vehicle forward, negative moves it in reverse.

See also: getLinearVelocity(), setPIDTuning()

Parameters

vLinear the linear velocity as a percentage of full scale [-100..100].

◆ drive() [2/3]

void MD_SmartCar::drive	(	int8_t	vLinear,
		float	vAngularR
	)

Drive the vehicle along specified path (radians).

Run the vehicle along a path with the specified velocity and angular orientation. Moves the motors under PID control.

The velocity is specified as a percentage of the maximum vehicle velocity [0..100]. Positive velocity move the vehicle forward, negative moves it in reverse.

Angular velocity direction is specified in radians per second [-pi/2..pi/2]. Positive angle is clockwise rotation.

See also: getLinearVelocity(), getAngularVelocity(), setPIDTuning()

Parameters

vLinear	the linear velocity as a percentage of full scale [-100..100].
vAngularR	the angular velocity in radians per second [-pi/2..pi/2].

◆ drive() [3/3]

void MD_SmartCar::drive	(	int8_t	vLinear,
		int8_t	vAngularD
	)

Drive the vehicle along specified path (degrees).

Run the vehicle along a path with the specified velocity and angular orientation. Moves the motors under PID control.

The velocity is specified as a percentage of the maximum vehicle velocity [0..100]. Positive velocity move the vehicle forward, negative moves it in reverse.

Angular velocity is specified in degrees per second [-90..90]. Positive angle is clockwise rotation.

See also: getLinearVelocity(), getAngularVelocity(), setPIDTuning()

Parameters

vLinear	the linear velocity as a percentage of full scale [-100..100].
vAngularD	the angular velocity in degrees per second [-90..90].

◆ getAngularVelocity()

float MD_SmartCar::getAngularVelocity ( void )

Get the current angular velocity.

Angular velocity is expressed in radians relative to the forward direction [-PI/2..PI/2]. Positive angle is turn to the right, negative left.

See also: drive()

Returns: the current angular speed setting.

◆ getKickerSP()

uint8_t MD_SmartCar::getKickerSP ( void )

Get the drive kicker speed.

Get the drive() kicker speed units for the motors. These units will be passed on directly to DCMotorControl and are meaningful to that class.

The Kicker is needed to overcome the static friction when the motor is stopped and should be determined as the minimum that reliably gets a motor rotation started.

See also: drive(), setKickerSP(), saveConfig()

Returns: the previously configured speed.

◆ getLinearVelocity()

int8_t MD_SmartCar::getLinearVelocity ( void )

Get the current linear velocity.

Linear velocity is expressed as a percentage of the maximum velocity [0..100]. The Master velocity is used to regulate all the speed functions for the motors.

See also: drive()

Returns: the current linear speed setting.

◆ getMaxMotorSP()

uint8_t MD_SmartCar::getMaxMotorSP ( void )

Get the maximum motor set point.

Get the currently configured maximum set point. The units are meaningful to the motor controller (eg, PWM setting).

See also: setMaxMotorSP(), saveConfig()

Returns: speed units currently configured.

◆ getMinMotorSP()

uint8_t MD_SmartCar::getMinMotorSP ( void )

Get the minimum motor set point.

Get the currently configured minimum set point. The units are meaningful to the motor controller (eg, PWM setting).

See also: setMinMotorSP(), saveConfig()

Returns: speed units currently configured.

◆ getMoveSP()

uint8_t MD_SmartCar::getMoveSP ( void )

Get the move speed.

Get the move() speed units for the motors. These units will be passed on directly to DCMotorControl and are meaningful to that class.

See also: move(), setMoveSP(), saveConfig()

Returns: the previously configured speed.

◆ getPIDTuning()

void MD_SmartCar::getPIDTuning	(	uint8_t	mtr,
		float &	Kp,
		float &	Ki,
		float &	Kd
	)

Get PID tuning parameters.

Return the current set of PID tuning parameters for the specified motor.

See also: saveConfig()

Parameters

mtr	the motor number [0..MAX_MOTOR].
Kp	the proportional PID parameter.
Ki	the integral PID parameter.
Kd	the derivative PID parameter.

◆ getPulsePerRev()

uint16_t MD_SmartCar::getPulsePerRev ( )

Read pulses per encoder revolution

Returns the number of pulses per encoder revolution. This may be needed to change from number of pulses to revolutions and then distance.

See also: setVehicleParameters()

Returns: The number of pulses per revolution.

◆ getSpinSP()

float MD_SmartCar::getSpinSP ( void )

Get the spin adjustment factor.

Get the spin() inertia adjustment. When the vehicle is spinning and the motors turn off, it may continue spinning due to its inertia. This factor is applied to proportionately reduce the pulses used to execute the spin to account for the additional free spin movement after the powered spin stops.

See also: spin(), getSpinSP(), saveConfig()

Returns: the previously configured spin adjustment.

◆ isRunning() [1/2]

bool MD_SmartCar::isRunning ( uint8_t mtr )

Check if specific motor is running

Check if motors are commanded to run. This method is useful to check when drive() or move() have completed their motions.

Parameters

mtr	The motor number being queried [0..MAX_MOTOR-1]

Returns: true if any of the motors are not idle

◆ isRunning() [2/2]

bool MD_SmartCar::isRunning ( void )

Check if motors are running

Check if motors are commanded to run. This method is useful to check when drive() or move() have completed their motions.

Returns: true if any of the motors are not idle

◆ isSequenceComplete()

bool MD_SmartCar::isSequenceComplete ( void )

Check if the current action sequence has completed.

Once an action sequence is started it will automatically execute to completion unless interrupted. This method checks to see if the action sequence has completed.

See also: startSequence()

Returns: true if the sequence has finished executing

◆ len2rad()

float MD_SmartCar::len2rad ( int16_t len )

Convert a length to angle of wheel rotation.

Convert a length in mm to travel into the radan of wheel rotation required for that travel.

Parameters

len	length in mm to convert.

Returns: the angle in radians of wheel rotation to achieve that distance.

◆ loadConfig()

void MD_SmartCar::loadConfig ( void )

Load settings from EEPROM.

Load the configuration settings from EEPROM. These will have been saved to EEPROM by saveConfig(). If there is no currently saved settings, defaults are set.

See also: saveConfig()

◆ move() [1/3]

void MD_SmartCar::move	(	float	angL,
		float	angR
	)

Precisely move the vehicle (radians).

Controls the movement by counting the encoder pulses rather that PID, which should make it more precise and controlled. This is useful for specific movements run at slow speed.

The call to move() specifies the angle each wheels will turn, independently. This method is designed to allow close movements such as spin-in-place or other short precise motions.

The motion for each wheel is specified as speed as the total angle subtended by the turned by the wheel in radians. Negative angle is a reverse wheel rotation.

See also: drive(), spin(), setMoveSP(), len2rad()

Parameters

angL	left wheel angle subtended by the motion in radians.
angR	right wheel angle subtended by the motion in radians.

◆ move() [2/3]

void MD_SmartCar::move	(	int16_t	angL,
		int16_t	angR
	)

Precisely move the vehicle (degrees).

Controls the movement by counting the encoder pulses rather that PID, which should make it more precise and controlled. This is useful for specific movements run at slow speed.

The call to move() specifies the precise motion of the motors, independently. This method is designed to allow close movements such as spin-in-place or other short precise motions.

The motion for each wheel is specified as speed as the total angle subtended by the turned by the wheel in degrees. Negative angle is a reverse wheel rotation.

See also: drive(), spin(), setMoveSP()

Parameters

angL	left wheel angle subtended by the motion in degrees.
angR	right wheel angle subtended by the motion in degrees.

◆ move() [3/3]

void MD_SmartCar::move ( int16_t len )

Precisely move the vehicle (millimeter).

Controls the movement by counting the encoder pulses rather that PID, which should make it more precise and controlled. This is useful for specific movements run at slow speed.

The call to move() specifies the precise motion of the motors, independently. This method is designed to allow close movements such as spin-in-place or other short precise motions.

The motion for each wheel will be identical to move the vehicle the required distance. Negative length is a reverse wheel rotation.

See also: drive(), spin(), setMoveSP()

Parameters

len	distance to move in mm.

◆ run()

void MD_SmartCar::run ( void )

Run the Robot Management Services.

This is called every iteration through loop() to run all the required Smart Car Management functions.

◆ saveConfig()

void MD_SmartCar::saveConfig ( void )

Save settings to EEPROM.

Save the current settings to EEPROM. These will overwrite any previously saved settings.

See also: loadConfig()

◆ setAngularVelocity() [1/2]

void MD_SmartCar::setAngularVelocity ( float angR )

Set the angular velocity (radians).

Sets the angular velocity without changing any other parameters. Useful for adjusting turning when already in motion.

Angular velocity is expressed in radians relative to the forward direction [-PI/2..PI/2]. Positive angle is turn to the right, negative left.

See also: getAngularVelocity(), drive()

Parameters

angR	the new turning rate in radians.

◆ setAngularVelocity() [2/2]

void MD_SmartCar::setAngularVelocity ( int8_t angD )

Set the angular velocity (degrees).

Sets the angular velocity without changing any other parameters. Useful for adjusting turning when already in motion.

Angular velocity is expressed in degrees relative to the forward direction [-90..90]. Positive angle is turn to the right, negative left.

See also: getAngularVelocity(), drive()

Parameters

angD	the new turning rate in degrees.

◆ setKickerSP()

bool MD_SmartCar::setKickerSP ( uint8_t units )

Set the drive kicker speed.

Set the drive() kicker speed for the motors. These units will be passed on directly to DCMotorControl and are meaningful to that class.

The Kicker is needed to overcome the static friction when the motor is stopped and should be determined as the minimum that reliably gets a motor rotation started.

See also: drive(), getKickerSP(), saveConfig()

Parameters

units speed units to be used with the motor controller.

Returns: true if the value was set, false if it fails sanity checks.

◆ setLinearVelocity()

void MD_SmartCar::setLinearVelocity ( int8_t vel )

Set the linear velocity

Sets the linear velocity without changing any other parameters. Useful for adjusting the speed when already in motion.

The velocity is specified as a percentage of the maximum vehicle velocity [0..100]. Positive velocity move the vehicle forward, negative moves it in reverse.

/sa getLinearVelocity(), drive()

Parameters

vel	the new value for the linear velocity [-100..100].

◆ setMaxMotorSP()

void MD_SmartCar::setMaxMotorSP ( uint8_t units )

Set the maximum motor set point.

Set the maximum set point for the motor will turn. This is used as the upper bound by the PID controller. The units are meaningful to the motor controller (eg, PWM setting). This is applicable to all motors.

See also: setMinMotorSP(), saveConfig()

Parameters

units speed units to be used with the motor controller.

◆ setMinMotorSP()

void MD_SmartCar::setMinMotorSP ( uint8_t units )

Set the minimum motor set point.

Set the minimum set point at which the motor will turn. This is used as a lower bound by the PID controller. The units are meaningful to the motor controller (eg, PWM setting). This is applicable to all motors.

See also: setMaxMotorSP(), saveConfig()

Parameters

units speed units to be used with the motor controller.

◆ setMoveSP()

bool MD_SmartCar::setMoveSP ( uint8_t units )

Set the move speed.

Set the move() speed units for the motors. These units will be passed on directly to DCMotorControl and are meaningful to that class.

See also: move(), getMoveSP(), saveConfig()

Parameters

units speed units to be used with the motor controller.

Returns: true if the value was set, false if it fails sanity checks.

◆ setPIDTuning()

void MD_SmartCar::setPIDTuning	(	uint8_t	mtr,
		float	Kp,
		float	Ki,
		float	Kd
	)

Set PID tuning parameters.

Change the current set of PID tuning parameters for the specified motor.

See also: saveConfig()

Parameters

mtr	the motor number [0..MAX_MOTOR].
Kp	the proportional PID parameter.
Ki	the integral PID parameter.
Kd	the derivative PID parameter.

◆ setSpinSP()

void MD_SmartCar::setSpinSP ( float adjust )

Set the spin adjustment factor.

Set the spin() inertia adjustment. When the vehicle is spinning and the motors turn off, it may continue spinning due to its inertia. This factor is applied to proportionately reduce the pulses used to execute the spin to account for the additional free spin movement after the powered spin stops.

See also: spin(), getSpinSP(), saveConfig()

Parameters

adjust factor applied to the spin pulses (pulses * adjust)

◆ setVehicleParameters()

void MD_SmartCar::setVehicleParameters	(	uint16_t	ppr,
		uint16_t	ppsMax,
		uint16_t	dWheel,
		uint16_t	lBase
	)

Set the vehicle constants

Sets the number of pulses per encoder revolution, maximum speed reading and important dimensions for the vehicle. This depends on the hardware and could vary between different vehicle configurations.

For encoder ppr, there is only one value for all whole vehicle, so all encoders need to operate the same way.

See also: begin(), Setting up a new SmartCar

Parameters

ppr	Number of encoder pulses per wheel revolution.
ppsMax	Maximum number of encoder pulses per second at top speed (100% velocity).
dWheel	Wheel diameter in mm.
lBase	Base length (distance between wheel centers) in mm

◆ spin()

void MD_SmartCar::spin ( int16_t fraction )

Precisely spin the vehicle.

Controls the movement by spinning the vehicle about its central vertical axis. It works similar to move() to spin the wheels in an directions to effect the turning motion.

The call to spin() specifies the percentage (-100 to 100) of the full circle rotation about the central axis passing through the vehicle base length. Positive angle is a turn to the right, negative to the left.

See also: drive(), move(), setMoveSP()

Parameters

fraction Percentage fraction of full revolution [-100..100]. Positive spins right; negative pins left.

◆ startSequence() [1/2]

void MD_SmartCar::startSequence ( actionItem_t * actionList )

Start an action sequence stored in RAM.

This method passed the reference to an action sequence array stored in RAM to the library for background execution. The array must remain in scope (ie, global or static declaration) for the duration of the sequence running.

Details on actions sequences can be found at Action Sequences

See also: isSequenceComplete()

Parameters

actionList pointer to the array of actionItem_t ending with and END record.

◆ startSequence() [2/2]

void MD_SmartCar::startSequence ( const actionItem_t * actionList )

Start an action sequence stored in PROGMEM.

This method passed the reference to an action sequence array stored in PROGMEM to the library for background execution.

Details on actions sequences can be found at Action Sequences

See also: isSequenceComplete()

Parameters

actionList pointer to the array of actionItem_t ending with and END record.

◆ stop()

void MD_SmartCar::stop ( void )

Stop the smart car.

This method will sets all velocities to 0 and disables all the motor functions to bring the smart car to a complete stop.

See also: setSpeed()

Member Data Documentation

◆ MAX_MOTOR

const uint8_t MD_SmartCar::MAX_MOTOR = 2

static

Maximum number of motors

Define the maximum number of motors that this library can control

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Structures, Enumerated Types and Constants.

Detailed Description

Member Enumeration Documentation

◆ actionId_t

Constructor & Destructor Documentation

◆ MD_SmartCar()

◆ ~MD_SmartCar()

Member Function Documentation

◆ begin()

◆ deg2rad()

◆ drive() [1/3]

◆ drive() [2/3]

◆ drive() [3/3]

◆ getAngularVelocity()

◆ getKickerSP()

◆ getLinearVelocity()

◆ getMaxMotorSP()

◆ getMinMotorSP()

◆ getMoveSP()

◆ getPIDTuning()

◆ getPulsePerRev()

◆ getSpinSP()

◆ isRunning() [1/2]

◆ isRunning() [2/2]

◆ isSequenceComplete()

◆ len2rad()

◆ loadConfig()

◆ move() [1/3]

◆ move() [2/3]

◆ move() [3/3]

◆ run()

◆ saveConfig()

◆ setAngularVelocity() [1/2]

◆ setAngularVelocity() [2/2]

◆ setKickerSP()

◆ setLinearVelocity()

◆ setMaxMotorSP()

◆ setMinMotorSP()

◆ setMoveSP()

◆ setPIDTuning()

◆ setSpinSP()

◆ setVehicleParameters()

◆ spin()

◆ startSequence() [1/2]

◆ startSequence() [2/2]

◆ stop()

Member Data Documentation

◆ MAX_MOTOR