# HITI Servo

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.

## 1) 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.

## 2) 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. ## 3) 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)

## 4) 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)

## 5) 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

Refer to this Quick Start Example : Control parameters

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

// run once at power on
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;

// run once at power on
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 &
}
``````

## 6) Motion monitoring

A HITI Servo can have 2 different states:

• 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:

• 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()

### 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*)

## 7) 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