HITI Servo

Modified on Wed, 04 Jan 2023 at 07:44 PM

A HITI Servo is a variable which lets you control the position and speed of 1 servo with sub-degrees resolution (the position resolution of a servo is around 0.1°). It internally creates and manages a Servo variable from the standard Servo library.

How does it work ?

A HITI Servo asks a servo to move in a pre-defined way. It generates a position profile that the servo will try to follow as best it can. The 2 more common methods to generate a position profile are the following:

Linear Position Profile
Trapezoidal Speed Profile

At now, only the Linear Position Profile is available. The Trapezoidal Speed Profile will be added in the future.

Before starting a motion, you must configure several setpoints (position, speed, motion time) to define the motion behavior. Once this is done, you can start and stop the motion by several means:

moveNow() and stopNow() => immediately start or stop the motion.
moveOnTrigger(trigger) and stopOnTrigger(trigger) => start or stop the motion only if the trigger (bool) is activated. This trigger can be controlled from HITIPanel using a Digital Data.

There are 2 different kinds of motion that you can use: Finite Motions which have a defined target position and which can be controlled with the above functions, and Continuous Motions which have a defined direction but no defined target position and which are controlled with the following functions:

movePositive(trigger) and moveNegative(trigger) => start and continue a motion in the specified direction at constant speed as long as the trigger (bool) is activated and stop this motion when the trigger is deactivated. This trigger can be controlled from HITIPanel using a Digital Data.

Linear Position Profile

The Linear Position Profile asks the servo to move at a constant Target Speed from an Initial Position to a Target Position. The Acceleration and Deceleration are infinite, which means the motion is started and stopped instantly, with the speed changing abruptly, not progressively.

Setpoints

Finite Motion

To set the position setpoint, use either of the following:

absolutePosition(setpoint) => setpoint (float) = Target Position (°)
relativePosition(setpoint) => setpoint (float) = Relative Motion (°)

To set the speed setpoint, use either of the following:

speed(setpoint) => setpoint (float) = Target Speed (°/s)
motionTime(setpoint) => setpoint (float) = Motion Time (s)

Continuous Motion

To set the speed setpoint:

continuousSpeed(setpoint) => setpoint (float) = Target Speed (°/s)

Max speed

This is a safety parameter which affects both Finite and Continuous Motions. It limits the Target Speed to the max speed value and increase the Motion Time accordingly. If you don’t set this parameter, the speed is not limited.

maxSpeed(max speed) => set max speed (float)
getMaxSpeed(max speed) => read max speed (float)

Servo Initialization

A HITI Servo must be initialized with several parameters.

As it internally manages a servo variable, all the parameters related to this servo variable must be set (pin to attach, min pulse and max pulse). The servo variable can be created internally by the HITI Servo or it can be supplied by you. You may need to supply your own servo variable if it must be shared and used by multiple libraries at the same time. In this case, add your servo variable as the last parameter.

Moreover, each HITI Servo has an ID number. This ID is used to access a Servo inside a HITI Motor Group.

Position offset

You can add a constant position offset to your Position Setpoint to adjust your reference position. Indeed, your mechanical mounting might not be perfect and might require a software correction using this position offset. Also, 2 servos of the same model might not have exactly the same reference position. If you need to replace one of them, it is likely that you will have to deal with this position offset.

Raw servo position = Position Setpoint + position offset.

Direction of rotation

If your servo is turning the wrong way according to your mechanical mounting, you can use the invert direction parameter to invert the direction of rotation of your servo (software correction).

The position offset is also inverted.

Syntax :

init(ID, pin, invert direction, position offset, initial position)
init(ID, pin, invert direction, position offset, min pulse, max pulse, initial position)
init(…, &servo)

Parameters :

ID (byte): identification number
pin (byte): pin number
invert direction (bool): if true, invert direction of rotation
position offset (float): permanent position offset (°)
initial position (float): initial position (°)
min pulse (unsigned int): min pulse width. Default : 544 us
max pulse (unsigned int): max pulse width. Default : 2400 us
servo (&Servo): Servo variable supplied by you

Example 1 : Servo variable internally created

#include <HITIComm.h>
#include <HC_Servo.h>

void setup()
{
    // initialize library
    HC_begin();

    // initialize HITI Servo
    servo.init(
        0,           // ID = 0
        8,           // attached to pin 8
        true,        // true => invert direction
        -4.3,        // position offset = -4.3°
        70.0);       // initial position : 70°
}

Example 2 : Servo variable created and supplied by you

#include <HITIComm.h>
#include <HC_Servo.h>

// Servo variable created by you
Servo servo;

void setup()
{
    // initialize library
    HC_begin();

    // initialize HITI Servo
    servo.init(
        0,           // ID = 0
        8,           // attached to pin 8
        true,        // true => invert direction
        -4.3,        // position offset = -4.3°
        70.0,        // initial position : 70°
        &servo);     // don’t forget the &
}

Motion monitoring

A HITI Servo can have 2 different states:

Ready => ready to start a move
Moving => being moving

Time indicators

To monitor the above states, use the following functions which return true if the Servo is in the corresponding state:

isReady()
isMoving()

You can use these functions as time indicators to synchronize other tasks which are related to the servo motion. Simply test these functions in IF statement to trigger events or tasks at different times. In addition to the above functions which are ideal to trigger continuous tasks, the following functions are ideal for triggering Punctual tasks as they return true when the motion starts and ends:

isStarting()
isEnding() => (reading this time indicator also resets it)

Position and speed

To get the raw position (°) read from the servo variable:

getRawPosition() => return the raw position (float)

The next functions return values which consider the software corrections (position offset and direction inversion):

To get the Absolute Position (°):

getTargetPosition() => return the absolute Target Position (float)
getCurrentPosition() => return the absolute Current position (float)

To get the Speed (°/s):

getTargetSpeed() => return the Target Speed (float)
getCurrentSpeed() => return the Current Speed (float)

To get the Continuous Speed (°/s):

getContinuousTargetSpeed() => return the Continuous Target Speed (float)
getContinuousCurrentSpeed() => return the Continuous Current Speed (float)

Servo

getID() => return the ID
getServo() => return the servo variable (Servo*)

Virtual travel limits (software limit switches)

The HITI Servo limits the reachable position range (after software corrections) by defining 2 positions which can’t be passed in their respective direction: a positive limit and a negative limit.

To set the Travel Limits (°):

travelLimits(negative limit, positive limit) => set the travel limits (float)

To check if Travel Limits has been reached:

isNegLimitReached() => return true if negative limit is reached
isPosLimitReached() => return true if positive limit is reached

Examples

Refer to this example : Control Parameters

Refer to this example : Motion Sequence

Refer to this example : Keyboard Control