This document provides a comprehensive overview of the interface between the asservissement program in the STM32 and the robot's global program. This interface offers lot of functions to control the robot, which are grouped into different categories.
A significant portion of the interface is automatically generated from a CSV file, which also includes part of this documentation.
The beginning of this document explains general information about the interface, followed by detailed descriptions of each function with its purpose, parameters, and usage.
| Category | usage |
|---|---|
| LED | Use to debug |
| COORDINATE | get or set coordinate |
| COMMANDE | Send all commands to move the robot from a point A to B. You can send until 1000 basic command in one time and the robot will execute all command successively. The get buffer size tells you how many commands the robot still has to execute. |
| STATUS | Give all robot status |
| MOTOR | Instante command apply to motor. Use only for emerengcy or at the beging or the end of the match |
| PARAMETER | maximum static parameter (don't change during the match) |
| CALIBRATION | TODO use to calibrate the odometrie (don't change during the match) |
| OPTIMIZATION | TODO |
This is a small example of a move with a collect and an avoid action in 2-step (wait 5 seconds if the opposing robot leaves, otherwise abandon the action)
robot.set_motor_state(true); //enable the motor if not
robot.set_coordinates(0,0,90); //set the coordinate if differente of 0
robot.go_to_point(500,500);
robot.go_to_point(1000,500);
robot.go_to_point(1000,1000);
robot.set_linear_max_speed(20); //go slowly for the next action
robot.go_to_point(1000,1300); //action like clolect something
robot.set_linear_max_speed(0); //reset slowly speed with default value
while(robot.get_command_buffer_size() != 0) //wait end of all action above
{
if(robot.get_direction_side() == Direction::FORWARD){
if(robot.get_braking_distance() > lidar.collideDistanceFORWARD()){ //stop befor collide the opponent
if(robotIsStall == false){ //to send only one time pause command
robot.pause();
robotIsStall = true;
}
if(WAIT_5S_BEFORE_TO_FIND_A_NEW_PATH_OR_AN_OTHER_ACTION){
robot.stop(); //to reset the command buffer and delete all command not yet execute
break;
}
}
else{
if(robotIsStall == true){ //to send only one time resume
robot.resume();
robotIsStall = false;
}
}
}
else if(robot.get_direction_side() == Direction::BACKWARD){
if(robot.get_braking_distance > lidar.collideDistanceBACKWARD())
// ....
}
}
list of enum type use in the interface
enum class Rotation {
NONE = 0,
SHORTEST = 1,
ANTICLOCKWISE = 2,
CLOCKWISE = 3
};enum class Direction {
NONE = 0,
FORWARD = 1,
BACKWARD = 2
};| type | unit |
|---|---|
| linear position | mm |
| angular position | degres |
| linear speed | mm/s |
| angular speed | degres/s |
| linear acceleration/decelaration | mm/s² |
| angular acceleration/decelaration | degres/s² |
| torque | TODO |
| current | TODO |
Part of files are auto generate depending of the csv file commands.csv. Use autoGen.py to regenerate the content.
python3 autoGen.pyReturn: void
Parameters:
uint16_t &part1uint16_t &part2uint16_t &part3uint16_t &part4
Description: get version of the librairie-commune
Return:
uint16_t
Parameters: void
Description: get log size. This command freeze the buffer for next commande if the size is different of 0
Return: void
Parameters:
&uint16_t
Description: get log
Return: void
Parameters:
bool status
Description: set status led 1
Usage: debug i2c interface
Return: void
Parameters:
bool status
Description: set status led 2
Usage: debug i2c interface
Return: void
Parameters:
int16_t &xint16_t &yint16_t &theta
Description: get coordinates (in mm and degres)
Return: void
Parameters:
int16_t xint16_t yint16_t theta
Description: set coordinates (in mm and degres)
Return: void
Parameters: void
Description: stop (a clean deceleration is provide and the command buffer is clean)
Usage: ex: stop if you want change the path
Return: void
Parameters: void
Description: pause (a clean deceleration is provide and the current command and all next command is keep for a future resume)
Usage: ex: when you want to wait for what the opponent robot pass (you can use stop after pause if you don't want to resume)
Return: void
Parameters: void
Description: resume after pause
Usage: ex: resume when the opponent robot is no longer in front
Return: void
Parameters:
int16_t xint16_t yRotation rotation = Rotation::SHORTESTDirection direction = Direction::FORWARD
Description: the robot go to point
Return: void
Parameters:
int16_t xint16_t yint16_t thetaRotation rotationFirst = Rotation::SHORTESTDirection direction = Direction::FORWARDRotation rotationSecond = Rotation::SHORTEST
Description: the robot go to point and turn at the final position
Return: void
Parameters:
int16_t angleRotation rotation = Rotation::SHORTEST
Description: to make the robot turn on itself by indicating an angle
Return: void
Parameters:
int16_t xint16_t yRotation rotation = Rotation::SHORTESTDirection direction = Direction::FORWARD
Description: to make the robot turn on itself by indicating a point to look
Return: void
Parameters:
int16_t max_speedint16_t max_acceleration = 0int16_t max_deceleration = 0
Description: set max speed for nexts commands. Use a value of 0 to reset with the max value set in parameter
Usage: limit speed for an action
Return: void
Parameters:
int16_t max_speedint16_t max_acceleration = 0int16_t max_deceleration = 0
Description: set max speed for nexts commands. Use a value of 0 to reset with the max value set in parameter
Usage: limit speed for an action
Return:
int16_t
Parameters: void
Description: give the distance to stop the robot when stop or pause is use (not applicable with brake)
Usage: This allows you to determine the distance at which to start braking. Used with lidar, it allows you to determine when to start stopping the robot
Return:
int16_t
Parameters: void
Description: number of command remaining (with the current command)
Usage: can be use to determine the free space in the command buffer if you want send a path with lot of got to point or angle. It can also be use to dertermine when the robot movement is finish
Return:
Direction
Parameters: void
Description: give the direction (NONE when the robot don't move backward or forward). When the robot is paused, it continues to give the direction it should go when resuming
Usage: usefull to dermine wich side of the lidar point is usefull to look when you want avoid the opponent robot
Return:
Rotation
Parameters: void
Description: give the rotation. When the robot is paused, it continues to give the rotation it should go when resuming
Return: void
Parameters:
int16_t &xint16_t &yint16_t &theta
Description: get current static consigne (angular consigne may change as robot moves forward or backward to compensate path variations)
Return: void
Parameters: void
Description: Overloading
Return:
bool
Parameters: void
Description: return true when the current consigne is finish (is equal to between get_running_is_finish or get_turning_is_finish)
Usage: when you pause the robot, to know when the robot is stop because you can't use get_commande_buffer_size. Otherwise, prefere to use get_commande_buffer_size.
Return:
bool
Parameters: void
Description: return true when the linear current consigne is finish
Return:
bool
Parameters: void
Description: return true when the angular current consigne is finish
Return:
int16_t
Parameters: void
Description: return the error between the dynamic consigne and the robot
Return:
int16_t
Parameters: void
Description: return the error between the dynamic consigne and the robot
Return: void
Parameters:
int16_t ¤tRightint16_t ¤tLeft
Description: gives the current average since the last reading for each motor
Return: void
Parameters:
int16_t &speedRightint16_t &speedLeft
Description: gives the speed average since the last reading for each motor
Return: void
Parameters:
bool motorEnable
Description: enable enables the motors (disabled at startup)
Usage: enable motor at the begening of a match and stop motor when the main program is finish or kill to avoid problems and to move freely the robot
Return: void
Parameters:
bool brakeEnable
Description: enable brake (the brake are disable at startup).
Usage: use to stop quickly the robot, but prefere to use pause or stop
Return: void
Parameters:
int16_t max_torque
Description: set max torque
Usage: constant
Return: void
Parameters:
int16_t max_speed_forint16_t max_speed_backint16_t max_acceleration_forint16_t max_acceleration_backint16_t max_deceleration_forint16_t max_deceleration_back
Description: set max speed forward
Usage: constant
Return: void
Parameters:
int16_t max_speed_clockint16_t max_speed_antiint16_t max_acceleration_clockint16_t max_acceleration_antiint16_t max_deceleration_clockint16_t max_deceleration_anti
Description: set max speed forward
Usage: constant
Return: void
Parameters:
int16_t pint16_t iint16_t d
Description: set pid linear static
Usage: constant
Return: void
Parameters:
int16_t pint16_t iint16_t d
Description: set pid linear dynamic
Usage: constant
Return: void
Parameters:
int16_t pint16_t iint16_t d
Description: set pid angular static
Usage: constant
Return: void
Parameters:
int16_t pint16_t iint16_t d
Description: set pid angular dynamic
Usage: constant
Return: void
Parameters:
int16_t sizeWheelLeftint16_t sizeWheelRightint16_t spaceInterWheel
Description: set odometry metric
Usage: constant
Return:
int16_t
Parameters: void
Description: get max torque
Usage: constant
Return: void
Parameters:
int16_t &max_speed_forint16_t &max_speed_backint16_t &max_acceleration_forint16_t &max_acceleration_backint16_t &max_deceleration_forint16_t &max_deceleration_back
Description: set max speed forward
Usage: constant
Return: void
Parameters:
int16_t &max_speed_clockint16_t &max_speed_antiint16_t &max_acceleration_clockint16_t &max_acceleration_antiint16_t &max_deceleration_clockint16_t &max_deceleration_anti
Description: set max speed forward
Usage: constant
Return: void
Parameters:
int16_t &pint16_t &iint16_t &d
Description: get pid linear static
Usage: constant
Return: void
Parameters:
int16_t &pint16_t &iint16_t &d
Description: get pid linear dynamic
Usage: constant
Return: void
Parameters:
int16_t &pint16_t &iint16_t &d
Description: get pid angular static
Usage: constant
Return: void
Parameters:
int16_t &pint16_t &iint16_t &d
Description: get pid angular dynamic
Usage: constant
Return: void
Parameters:
int16_t &sizeWheelLeftint16_t &sizeWheelRightint16_t &spaceInterWheel
Description: get odometry metric
Usage: constant
Return: void
Parameters: void
Description: future (calculate odometrie metric)
Return: void
Parameters: void
Description: future (calculate odometrie metric)
Return: void
Parameters: void
Description: future (calculate odometrie metric)
Return: void
Parameters: void
Description: future (get all informations in one command for more optimisation)
Usage: to optimise the main code with a loop: get, compute, set
Return: void
Parameters: void
Description: future (get all informations in one command for more optimisation)
Usage: to optimise the main code with a loop: get, compute, set
Return: void
Parameters: void
Description: future (get all informations in one command for more optimisation)
Usage: to optimise the main code with a loop: get, compute, set
Return: void
Parameters: void
Description: future (set all informations in one command for more optimisation)
Usage: to optimise the main code with a loop: get, compute, set
Return: bool
Parameters: void
Description: return true if the compiled interface of the stm32 and the main program is identical (same commit)
- All parameters with
&are references and will be modified to store results or inputs. - Ensure proper initialization and configuration of the robot before using these commands.