Class to drive one servo in position control mode. More...

#include <HkxPosControl.h>

Public Member Functions
	HkxPosControl (uint8_t ID, HkxCommunication &herkXCom, HkxPrint &print)
	Constructor. More...

boolean	tryConnect ()
	Try connect servo. More...

uint8_t	getID () const
	Get the ID. More...

hkxTorqueControl	getTorqueControl () const
	Get torque control. More...

hkxLEDControl	getLEDControl () const
	Get LED control. More...

HkxCommunication &	getCommunication () const
	Get servo communication. More...

boolean	isConnected () const
	Is the servo connected. More...

int16_t	positionRelativeToAbsolute (int16_t positionRelative) const
	Convert relative to absolute position. More...

int16_t	positionAbsoluteToRelative (int16_t positionAbsolute) const
	Convert absolute to relative position. More...

uint16_t	getMinPosition () const
	Get min position. More...

uint16_t	getMaxPosition () const
	Get max position. More...

void	setLEDControlVariable (hkxLEDControl newLEDControl)
	Set the LED variable. More...

boolean	isInPosition ()
	Check if the servo arrived. More...

uint8_t	getStatus (HkxStatus &statusED, boolean update)
	Get the status. More...

uint8_t	clearStatus ()
	Clear the status. More...

uint8_t	setLoad (uint16_t newDeadZone, uint8_t newSaturatorOffset, const uint32_t &newSaturatorSlope, int8_t newPWMOffset, uint8_t newMinPWM, uint16_t newMaxPWM)
	Set load control parameters. More...

uint8_t	setTorqueLEDControl (HkxMaybe< hkxTorqueControl > newTorqueControl, HkxMaybe< hkxLEDControl > newLEDControl)
	Set torque actuation and LED colour. More...

uint8_t	setCurrentPositionTo (int16_t currentPosition)
	Set current position. More...

uint8_t	movePosition (int16_t destinationAngle, uint16_t playTime, HkxMaybe< hkxLEDControl > LEDControl, bool waitStop)
	Move position. More...

uint8_t	getBehaviour (HkxMaybe< uint16_t > inputVoltage, HkxMaybe< uint16_t > temperature, HkxMaybe< int16_t > position, HkxMaybe< int16_t > velocity, HkxMaybe< uint16_t > PWM, HkxMaybe< int16_t > goalPosition, HkxMaybe< int16_t > trajectoryPosition, HkxMaybe< int16_t > trajectoryVelocity)
	Get the servo behaviour. More...

uint8_t	reboot ()
	Reboot servo. More...

Private Member Functions
uint8_t	updateStatus ()
	Update the status. More...

void	errorPrint (const String &message)
	Print error. More...

void	warningPrint (const String &message)
	Print warning. More...

void	infoPrint (const String &message)
	Print info. More...

Private Attributes
HkxCommunication &	_herkXCom

HkxPrint &	_print

boolean	_connected

const String	_className

int16_t	_zeroPosition

uint8_t	_id

uint8_t	_deadZone

uint8_t	_saturatorOffset

uint16_t	_saturatorSlope

int8_t	_pwmOffset

uint8_t	_minPWM

uint16_t	_maxPWM

uint16_t	_minPosition

uint16_t	_maxPosition

hkxTorqueControl	_torqueControl

hkxLEDControl	_ledControl

HkxStatus	_statusED

Detailed Description

Class to drive one servo in position control mode.

This class allows to drive one servo in position control mode.

Constructor & Destructor Documentation

HkxPosControl::HkxPosControl	(	uint8_t	ID,
		HkxCommunication &	herkXCom,
		HkxPrint &	print
	)

Constructor.

The constructor of HkxPosControl.

Parameters

[in]	ID	: id of the servo to drive. The value shall be [0 ; 253].
[in]	herkXCom	: Communication with the servos.
[in]	print	: Communication to print messages.

Example:

HkxPrint print = HkxPrint(Serial, 9600); 
HkxCommunication communication = HkxCommunication(HKX_115200, Serial1, print); 
HkxPosControl servo = HkxPosControl(10, communication, print); // ID=10, print can be different to communication

Member Function Documentation

uint8_t HkxPosControl::clearStatus ( )

Clear the status.

Clear the status of the servo to leave the "error state" and stop the LED blink and torque deactivation (see p.33 of the user manual for more details about LED and torque policies).

Warning: If the problem still present (e.g. low input voltage), the servo will switch again to error just after clearing.

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
HkxStatus currentStatus;
byte error = servo.getStatus(currentStatus, true);
if(error==0 && currentStatus.isError(HKX_STAT_ALL)){ // check if any error
  servo.clearStatus(); 
}

void HkxPosControl::errorPrint ( const String & message )

inlineprivate

Print error.

Print an error message if setup.

Parameters

[in] message : content to print as an error.

uint8_t HkxPosControl::getBehaviour	(	HkxMaybe< uint16_t >	inputVoltage,
		HkxMaybe< uint16_t >	temperature,
		HkxMaybe< int16_t >	position,
		HkxMaybe< int16_t >	velocity,
		HkxMaybe< uint16_t >	PWM,
		HkxMaybe< int16_t >	goalPosition,
		HkxMaybe< int16_t >	trajectoryPosition,
		HkxMaybe< int16_t >	trajectoryVelocity
	)

Get the servo behaviour.

Get the current servo behaviour. See the user manual for more details about the parameters.

Parameters

[out]	inputVoltage	: Current servo input voltage. Its value is given in millivolts. This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.
[out]	temperature	: Current temperature of the servo. Its value is given in 10^-2 °C (degree Celsius). This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.
[out]	position	: Current relative position of the servo. Its value is given in 10^-1 degrees. This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.
[out]	velocity	: Current angle velocity of the servo. Its value is given in degree / second. This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.
[out]	PWM	: Current PWM (load) of the servo. Its value is given in PWM (raw). This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.
[out]	goalPosition	: Goal position of the current move of the servo. Its value is given in 10^-1 degrees. This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.
[out]	trajectoryPosition	: Current trajectory position - desired position at a given time according the trajectory - of the servo. Its value is given in 10^-1 degrees. This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.
[out]	trajectoryVelocity	: Current trajectory velocity - desired velocity at a given time according the trajectory - of the servo. Its value is given in degree / second. This parameter is optional, either set the address of a `uint16_t` (or `unsigned` `int`) variable to return the value, or set `HKX_NO_VALUE` to ignore it.

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected

Example 1: How to get all the values.

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
uint16_t inputVoltage, temperature, PWM;
int16_t position, velocity, goalPosition, trajectoryPosition, trajectoryVelocity;
servo->getBehaviour(&inputVoltage, &temperature, &position, &velocity, &PWM, &goalPosition, &trajectoryPosition, &trajectoryVelocity);

Example 2: How to get the current position only.

int16_t position;

servo->getBehaviour(HKX_NO_VALUE, HKX_NO_VALUE, &position, HKX_NO_VALUE, HKX_NO_VALUE, HKX_NO_VALUE, HKX_NO_VALUE, HKX_NO_VALUE);

HkxCommunication& HkxPosControl::getCommunication ( ) const

inline

Get servo communication.

Get the communication of the servo.

Returns: Return the communication.

uint8_t HkxPosControl::getID ( ) const

inline

Get the ID.

Get the ID of the driven servo.

Returns: Return the ID.

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
...
byte idOfMyServo = servo.getID();

hkxLEDControl HkxPosControl::getLEDControl ( ) const

inline

Get LED control.

Get the current LED control (colour) of the driven servo (see hkxLEDControl for more details about the options).

Returns: Return the LED control.

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
hkxLEDControl ledControlOfMyServo = servo.getLEDControl();

uint16_t HkxPosControl::getMaxPosition ( ) const

inline

Get max position.

Get maximum position (raw unit) the servo is allowed to reach.

Returns: Return the max position.

uint16_t HkxPosControl::getMinPosition ( ) const

inline

Get min position.

Get minimum position (raw unit) the servo is allowed to reach.

Returns: Return the min position.

uint8_t HkxPosControl::getStatus	(	HkxStatus &	statusED,
		boolean	update
	)

Get the status.

Get the last received status from the servo.

Parameters

[out]	statusED	: Last received status of the servo.
[out]	update	: `true` to update the status, then to get the current status. `false` to get the last received status.

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected
3 = Data not consistent

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
HkxStatus currentStatus;
byte error = servo.getStatus(currentStatus, true);
if(error==0 && currentStatus.isError(HKX_STAT_VOLTAGE)){ // check voltage error
  print.errorPrint(F("Please check input voltage")); 
}

hkxTorqueControl HkxPosControl::getTorqueControl ( ) const

inline

Get torque control.

Get the current torque control of the driven servo (see hkxTorqueControl for more details about the options).

Returns: Return the torque control

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
hkxTorqueControl torqueControlOfMyServo = servo.getTorqueControl();

void HkxPosControl::infoPrint ( const String & message )

inlineprivate

Print info.

Print an info message if setup.

Parameters

[in] message : content to print as an info.

boolean HkxPosControl::isConnected ( ) const

inline

Is the servo connected.

Return if the servo is connected.

Returns

true: if the servo is connected (last communication worked),
false: if the servo is NOT connected (last communication failed).

boolean HkxPosControl::isInPosition ( )

inline

Check if the servo arrived.

Check if the servo is arrived at its goal position.

Returns

true if the servo reached its goal position.
false if the servo is still moving.

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
servo.move(900, 2000, HKX_NO_VALUE, false); // move to 90° in 2 seconds
... // different actions done during the movement
while(!servo.isInPosition()){} // wait the servo to be arrived in position

uint8_t HkxPosControl::movePosition	(	int16_t	destinationAngle,
		uint16_t	playTime,
		HkxMaybe< hkxLEDControl >	LEDControl,
		bool	waitStop
	)

Move position.

Move the servo.

Parameters

[in]	destinationAngle	: Relative position to reach. Its value shall be set in 10^-1 degrees. Its range depends on _zeroPosition, _minPosition and _maxPosition.
[in]	playTime	: Time of the action trajectory for the move. Its value shall be set in milliseconds within the range [0 ; 2845ms].
[in]	LEDControl	: LED control to apply. This parameter is optional, either set a hkxLEDControl variable, the value (list below), or set `HKX_NO_VALUE` to ignore it. `HKX_LED_OFF`, `HKX_LED_GREEN`, `HKX_LED_BLUE`, `HKX_LED_RED`, `HKX_LED_CYAN`, `HKX_LED_YELLOW`, `HKX_LED_PINK`, `HKX_LED_WHITE`,
[in]	waitStop	: `true` to wait the servo reach the goal position `destinationAngle` (isInPosition()). `false` to continue running the programme during the move. This could same computation time but the user shall check with isInPosition() that the servo reached the goal before setting the next move.

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
servo.move(1200, 1500, HKX_NO_VALUE, true); // move to position 120° in 1.5 seconds and wait arrival 

int16_t HkxPosControl::positionAbsoluteToRelative ( int16_t positionAbsolute ) const

inline

Convert absolute to relative position.

Conversion from the absolute position to the relative position: relative = absolute - _zeroPosition [degree]

Returns: Return the relative position (in degrees).

int16_t HkxPosControl::positionRelativeToAbsolute ( int16_t positionRelative ) const

inline

Convert relative to absolute position.

Conversion from the relative position to the absolute position: absolute = relative + _zeroPosition [degree]

Returns: Return the absolute position (in degrees).

uint8_t HkxPosControl::reboot ( )

Reboot servo.

Reboot the servo. This action will erase the ram, then reinitialize the parameters with the EEP (ROM) values. Wait some time (> 500 ms) before asking any action from the servo.

Returns: 0 = OK
2 = Servo not connected

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
servo->reboot();
wait(500); // wait for the servo to restart
...

uint8_t HkxPosControl::setCurrentPositionTo ( int16_t currentPosition )

Set current position.

Set the current position of the servo in order to change its relative position (by modifying the _zeroPosition).
_zeroPosition = absolute - current;

Parameters

[in] currentPosition : The current position to calibrate the servo. The value shall be set in 10^-1 degrees within the range [-360° ; 360°].

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
servo.setCurrentPositionTo(0); // set current position as the reference
servo.move(-450, 500, HKX_NO_VALUE, true); // move to +45° (compared to reference) in 0.5 seconds and wait arrival 

void HkxPosControl::setLEDControlVariable ( hkxLEDControl newLEDControl )

inline

Set the LED variable.

Set the LED variable in the class without applying.

Warning: This member is for HkxGroupPosControl use only.

Parameters

[in] newLEDControl : Colour of the led (see hkxLEDControl for more details).

uint8_t HkxPosControl::setLoad	(	uint16_t	newDeadZone,
		uint8_t	newSaturatorOffset,
		const uint32_t &	newSaturatorSlope,
		int8_t	newPWMOffset,
		uint8_t	newMinPWM,
		uint16_t	newMaxPWM
	)

Set load control parameters.

Set the load control parameters of the servo on the RAM (not kept after servo reboot).

         PWM+
          |  ___________........................................ PWM max
          |             \
          |              \ Saturator slope
          |               \..................................... Saturator offset
          |                |<dead zone> <dead zone>
          |                |___________ ........................ PWM min
          |                            |
          |  --------------------------|------------------------ PWM offset
          |                            |__________
Position- |____________________________*__________|_____________ Position+
          |                          goal         |
          |                        position        \
          |                                         \__________
          |
         PWM-

Parameters

[in]	newDeadZone	: The dead zone is the angle error before the servo applies a load compensation to maintain its position (see the above figure). Its value shall be set in 10^-1 degrees within the range [0 ; 82.8°].
[in]	newSaturatorOffset	: The saturator offset is the step PWM value of the saturator once dead zone the position goes out of the dead zone (see the above figure). Its value shall be set in PWM within the range [0 ; 254].
[in]	newSaturatorSlope	: The saturator slop is a gradient of the saturator, going from the saturator offset and increasing gradually the PWM with the error position to the goal (see the above figure). It provides a flexible and elastic response of the servo to external forces. Its value shall be set in 10^-2 PWM / degree within the range [0 ; 393 PWM/degree].
[in]	newPWMOffset	: The PWM offset allows compensating permanent load (e.g. gravity) by shifting the saturator by the same value (see the above figure). Its value shall be set in PWM within the range [-128 ; 127].
[in]	newMinPWM	: The min PWM is the minimum PWM that is applied by the servo (see the above figure). As specified in the user manual p.37, this may lead to unstable system. Use 0 as default value. The value shall be set in PWM within the range [0 ; 254].
[in]	newMaxPWM	: The max PWM is the maximum PWM that is applied by the servo (see the above figure). It could be used to limit the load of the servo, to avoid damages or injuries or instance. The value shall be set in PWM within the range [0 ; 1023].

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
servo.setLoad(9, 0, 39300, 0, 0, 1023); // non-flexible control
servo.move(900, 2000, HKX_NO_VALUE, true); // move to 90° in 2 seconds and wait arrival
servo.setLoad(9, 0, 1000, 0, 0, 1023); // flexible control
servo.move(-900, 500, HKX_NO_VALUE, true); // move to -90° in 0.5 seconds and wait arrival

uint8_t HkxPosControl::setTorqueLEDControl	(	HkxMaybe< hkxTorqueControl >	newTorqueControl,
		HkxMaybe< hkxLEDControl >	newLEDControl
	)

Set torque actuation and LED colour.

Set the torque actuation (hkxTorqueControl for more details) and the LED colour (hkxLEDControl for more details).

Parameters

[in]	newTorqueControl	: Torque control to apply. This parameter is optional, either set a hkxTorqueControl variable, the value (list below), or set `HKX_NO_VALUE` to ignore it. `HKX_TORQUE_FREE:` no resistance to the movements (or let say mechanical resistance only) `HKX_TORQUE_BREAK:` the motor resists but allows the movements `HKX_TORQUE_ON:` the motor maintain its position (don't allow movements)
[in]	newLEDControl	: LED control to apply. This parameter is optional, either set a hkxLEDControl variable, the value (list below), or set `HKX_NO_VALUE` to ignore it. `HKX_LED_OFF`, `HKX_LED_GREEN`, `HKX_LED_BLUE`, `HKX_LED_RED`, `HKX_LED_CYAN`, `HKX_LED_YELLOW`, `HKX_LED_PINK`, `HKX_LED_WHITE`,

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected

Example:

... 
HkxPosControl servo = HkxPosControl(10, communication, print);
servo.setTorqueLEDControl(HKX_LED_GREEN, HKX_NO_VALUE); // set the led to green
servo.setTorqueLEDControl(HKX_LED_WHITE, HKX_TORQUE_BREAK); // set the led to white and the torque to break 

boolean HkxPosControl::tryConnect ( )

Try connect servo.

Try to connect to the servo.

Returns

true: if the servo is connected,
false: if the servo is NOT connected.

uint8_t HkxPosControl::updateStatus ( )

private

Update the status.

Perform a status request to update the stored status _statusED.

Returns: 0 = OK
1 = Input not correct
2 = Servo not connected
3 = Data not consistent

void HkxPosControl::warningPrint ( const String & message )

inlineprivate

Print warning.

Print a warning message if setup.

Parameters

[in] message : content to print as a warning.

Member Data Documentation

const String HkxPosControl::_className

private

Class name to print the messages

boolean HkxPosControl::_connected

private

Connexion with the servo to drive

uint8_t HkxPosControl::_deadZone

private

Current RAM value of the dead zone (saturator curve) of the servo [raw]

HkxCommunication& HkxPosControl::_herkXCom

private

Communication with servos

uint8_t HkxPosControl::_id

private

ID of the servo

hkxLEDControl HkxPosControl::_ledControl

private

Current RAM value of the LED of the servo

uint16_t HkxPosControl::_maxPosition

private

Max Position the servo is allowed to reach [raw]

uint16_t HkxPosControl::_maxPWM

private

Current RAM value of the max PWM (saturator curve) of the servo [raw]

uint16_t HkxPosControl::_minPosition

private

Min Position the servo is allowed to reach [raw]

uint8_t HkxPosControl::_minPWM

private

Current RAM value of the min PWM (saturator curve) of the servo [raw]

HkxPrint& HkxPosControl::_print

private

Communication to print messages

int8_t HkxPosControl::_pwmOffset

private

Current RAM value of the PWM offset (saturator curve) of the servo [raw]

uint8_t HkxPosControl::_saturatorOffset

private

Current RAM value of the saturator offset (saturator curve) of the servo [raw]

uint16_t HkxPosControl::_saturatorSlope

private

Current RAM value of the saturator slope (saturator curve) of the servo [raw]

HkxStatus HkxPosControl::_statusED

private

Last status received from the servo

hkxTorqueControl HkxPosControl::_torqueControl

private

Current RAM value of the torque control of the servo

int16_t HkxPosControl::_zeroPosition

private

Shift of the neutral position [in degrees]

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

/home/benoit/sketchbook/libraries/HerkuleXLib/HkxPosControl.h
/home/benoit/sketchbook/libraries/HerkuleXLib/HkxPosControl.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation