HerkuleXLib  1.1
Arduino library to drive HerkuleX DRS-0101 and DRS-0201
Public Member Functions | Private Member Functions | Private Attributes | List of all members
HkxPosControl Class Reference

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...
 
HkxCommunicationgetCommunication () 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: