jlb_pid repository

Repository Summary

Checkout URI https://gitlab.com/Juulbl/ros2-pid
VCS Type git
VCS Version ros2
Last Updated 2020-12-27
Dev Status MAINTAINED
CI status No Continuous Integration
Released UNRELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

Name Version
jlb_pid 0.1.3

README

ROS 2 PID

PID controller for ROS2

Installation

This library can be used in two ways, as a library and as a node. See the documentation section. Using the library as a PID library should not require extra steps. If you want to use the pre-built PID nodes, you will need to do the following:

mkdir -p ~/jlb_pid_ws/src
cd ~/jlb_pid_ws
wget https://gitlab.com/Juulbl/ros2-pid/-/raw/ros2/jlb_pid.repos
vcs import src < jlb_pid.repos
colcon build --symlink-install

# Add them to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
echo 'source ~/jlb_pid_ws/install/setup.sh' >> ~/.bashrc

Adding to a project

Once this is set up, we will need to setup the dependencies of the package.

package.xml:

<!-- As a generic dependency -->
<depend>jlb_pid</depend>

<!-- Or, as a build dependency (when using the library) -->
<build_depend>jlb_pid</build_depend>

<!-- Or, as an exec dependency (when using the topic interface)-->
<exec_depend>jlb_pid</exec_depend>

CMakeLists.txt:

find_package(jlb_pid REQUIRED)

# Add the following if you want to use the library

ament_target_dependencies(<PACKAGE_NAME> 
  jlb_pid
)

Documentation

This section will go over the interaction with the PID node.

Library

This section will go over the documentation when using the library.

Below you will find an example of how to use the library, the example does not work properly but should give you an idea of how to use it.

#include <jlb_pid/controller.hpp>
// Create a controller with a PID and config.
// We will be the default controller, see `Controller::Controller`.
jlb_pid::Controller controller;

// Change the setpoint
controller.set_setpoint(100);

// Create a state mock object
double state = 0;

// Create a loop to update the `plant_state` and log the control effort.
// Since we cannot actually measure the `plant_state`, we will use the return value of our
// control effort to do this
while(true){
  controller.set_plant_state(state);
  controller.update();
  state = controller.get_control_effort();

  std::cout << "State:" << state << std::endl;
}

// If the above-mentioned functions need to be executed in the same order within the same scope
// An overload of `Controller::update` can be used to simplify the process.
while(true){
  state = controller.update(state);

  std::cout << "State:" << state << std::endl;
}

In the example it is assumed all functions are executed within the same scope. For a more ROS related implementation, see the ControllerNode object. This is source code for the pre-delivered controller_node and should give you an idea of how to use a PID controller inside a ROS node.

Node

This section will go over the documentation when using the controller_node.

Topics

Name Type Description
state std_msgs/Float64 input data used for the PID system, e.g. current angle
setpoint std_msgs/Float64 the setpoint of the PID system, e.g. target angle
enable std_msgs/Bool if true, updates the PID system. If false, disables the PID system
control_effort std_msgs/Float64 the control effort, or output of the PID system

Parameters

Required
Name Type Description
kp double Proportional gain, default = 1.0
ki double Integral gain, default = 0.0
kd double Derivative gain, default = 0.0

Note: kp, ki and kd must all be either positive or negative (a mixture of signs results in an error)

Optional
Name Type Description
plant_topic string allows the user to configure an alternative topic name for the plant, default = state
setpoint_topic string allows the user to configure an alternative topic name for the setpoint, default = setpoint
enable_topic string allows the user to configure an alternative topic name to turn the system on and of, default = enable
controller_topic string allows the user to configure an alternative topic name for the control effort, default = control_effort
- - -
update_rate double update rate of the node expressed in Hz, default = 1000
- - -
upper_limit double maximum control effort value, default = double_max
lower_limit double minimum control effort value, default = double_lowest
windup_limit double limits the error increase or decrease for the integrator (mainly used for hardware restrictions), default = double_max

Usage

To setup this PID control library, add a new node to the launch file.

The following snippet is an example of a node. In this example we specify that we want to use the pid package. We will add the node to the namespace example/distance_controller, such that every topic will be append after it. We want to use the executable of the control node, using controller_node. Finally, we will specify all launch parameters.

Node(
    package='jlb_pid',
    namespace='example/distance_controller',
    executable='controller_node',
    name='distance_controller',
    parameters=[
        # Required
        {'kp': 2.0},
        {'ki': 0.01},
        {'kd': 0.02},
        # Optional
        {'upper_limit': 0.6},
        {'lower_limit': -0.6},
        {'windup_limit': 0.001}
    ]
)


Examples

A set of example projects have been created and can be found here.

CONTRIBUTING

No CONTRIBUTING.md found.