Rewrite README with proper structure and documentation
- Add comprehensive project overview and features list - Restructure architecture section with detailed explanations - Document robot states and control workflow - Add ROS communication (subscribers/publishers) details - Include obstacle avoidance algorithm explanation - Add project structure diagram - Clarify dependencies and build instructions - Expand installation and configuration sections - Add testing and running instructions Co-Authored-By: Claude Haiku 4.5 <[email protected]> Claude-Session: https://claude.ai/code
This commit is contained in:
msjid
co-authored by
Claude Haiku 4.5
Claude Haiku 4.5
parent
4104d46de7
commit
1b6f0eabcc
@@ -1,78 +1,197 @@
|
||||
# Tangent Planner Roller eye
|
||||
# Tangent Planner
|
||||
|
||||
## Project structure
|
||||
A ROS-based autonomous navigation and path planning system with obstacle avoidance capabilities for mobile robots using Time-of-Flight (ToF) sensors.
|
||||
|
||||
### Subscribers and publishers
|
||||
## Overview
|
||||
|
||||
1. odometry subscriber
|
||||
The Tangent Planner implements a tangent bug algorithm for autonomous robot navigation, allowing robots to navigate to goal positions while avoiding obstacles using ToF sensor feedback. The system uses velocity control with intelligent state management to handle different navigation scenarios.
|
||||
|
||||
subscribing to odometry for getting Pose2D message(x, y, theta)
|
||||
2. tof subscriber
|
||||
## Features
|
||||
|
||||
subscribing to the scanner for getting range message (field of view, range, max range , min range)
|
||||
3. twist publisher
|
||||
- **Autonomous Navigation**: Navigate robots from start to goal position automatically
|
||||
- **Obstacle Avoidance**: Detect and avoid obstacles using ToF sensor data
|
||||
- **Boundary Following**: Follow obstacle boundaries to circumnavigate obstacles
|
||||
- **State Machine**: Robust state management for different navigation behaviors
|
||||
- **ROS Integration**: Full ROS1 integration with standard message types
|
||||
- **Parameter Configuration**: Flexible controller tuning via configuration files
|
||||
- **Unit Tests**: Comprehensive Google Test suite for algorithm validation
|
||||
|
||||
calculating velocity based on odometry and tof message then publish twist message (linear x, linear y, angular z)
|
||||
## Architecture
|
||||
|
||||
### General workflow
|
||||
### Robot States
|
||||
|
||||
The main function calls computeVelocityCommand of the node class, and it consists of 4 main steps:
|
||||
The robot operates in five distinct states:
|
||||
|
||||
1. calculate errors
|
||||
1. **StopAtGoal** - Robot has reached the goal position
|
||||
2. **TurnToGoal** - Robot orients toward the goal before moving (when angular error exceeds threshold)
|
||||
3. **MotionToGoal** - Robot moves toward the goal with computed velocity
|
||||
4. **OrientToGoal** - Robot position is correct but orientation needs adjustment
|
||||
5. **FollowBoundary** - Robot follows obstacle boundary to navigate around obstacles
|
||||
|
||||
error here means the x, y and theta difference between current position and goal
|
||||
2. update state
|
||||
### Core Workflow
|
||||
|
||||
there are states for robot :
|
||||
`computeVelocityCommand()` executes four main steps:
|
||||
|
||||
- StopAtGoal robot has reached to goal and there isn't any error
|
||||
- TurnToGoal robot needs to turn to goal when error_angel is more than a specific value and then start_patrolling to move
|
||||
- MotionToGoal robot can move toward goal with computed velocity
|
||||
- OrientToGoal robots x and y are ok but needs to change its orientation to goal
|
||||
- FollowBoundary robot is trying to skip an obstacle by following its boundary
|
||||
1. **Calculate Errors** - Compute x, y, and angular differences between current pose and goal
|
||||
2. **Update State** - Transition to appropriate state based on errors and obstacles
|
||||
3. **Update Controller** - Configure controller parameters based on current state
|
||||
4. **Update Velocity** - Calculate linear and angular velocity using nonlinear control law
|
||||
|
||||
each time, based on changing situations, robot state will update to one of these states
|
||||
3. update controller
|
||||
### ROS Communication
|
||||
|
||||
based of robot current state that set at last step, some values will be set before computing velocity
|
||||
4. update velocity
|
||||
#### Subscribers
|
||||
|
||||
calculate the velocity for robot by using a nonlinear controller and values
|
||||
- **Odometry** (`/odom`) - Receives Pose2D messages (x, y, θ) for robot localization
|
||||
- **ToF Scanner** (`/scan`) - Receives range data (field of view, ranges, min/max distance)
|
||||
|
||||
### Obstacle avoidance and follow boundary workflow
|
||||
#### Publishers
|
||||
|
||||
An obstacle avoidance planning algorithm that guides a robot from a start_patrolling to the goal point. The robot has two main behavior: MotionToGoal and FollowBoundary.
|
||||
- **Velocity Command** (`/cmd_vel`) - Publishes twist messages (linear x, linear y, angular z)
|
||||
|
||||
It starts moving to the goal until there is no obstacle. If it encounters an obstacle then starts to follow the obstacle’s boundary.
|
||||
### Obstacle Avoidance Algorithm
|
||||
|
||||
Following a boundary with a TOF sensor that has a low field of view is a challenging problem that has been solved by saving the history of the robot’s positions as well as the obstacle’s positions, in order to decide where to go at the next step. The robot exits the FollowBoundary mode when it passes the obstacle through the goal.
|
||||
The system implements a boundary-following algorithm with history-based decision making:
|
||||
|
||||
1. Robot begins motion toward goal
|
||||
2. Upon obstacle detection, switches to FollowBoundary state
|
||||
3. Saves historical robot and obstacle positions for trajectory planning
|
||||
4. Decides next movement based on accumulated history
|
||||
5. Exits FollowBoundary when path to goal is clear
|
||||
6. Returns to MotionToGoal until reaching destination
|
||||
|
||||
It finally stops at the goal point.
|
||||
### Controllers
|
||||
|
||||
1. motion controller
|
||||
**Motion Controller**
|
||||
- Handles states requiring position changes (x, y movement)
|
||||
- Tunable parameters: `b`, `c` (gains)
|
||||
- Computed parameters: `k1`, `k2`, `k3` (derived from gains)
|
||||
|
||||
this controller is responsible for states which needs robot x and y to be changed
|
||||
b and c are the values for this controller to be adjusted and k1, k2 and k3 will be calculated
|
||||
2. turn controller
|
||||
**Turn Controller**
|
||||
- Handles pure rotation movements
|
||||
- Tunable parameters: `kp_` (proportional gain), `kp_i_` (integral gain)
|
||||
|
||||
this controller is responsible for states which robot just needs to turn around on its current place
|
||||
kp_ and kp_i_ are the values for this controller to be adjusted
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── include/
|
||||
│ ├── tangent_planner.h # Core algorithm implementation
|
||||
│ ├── tangent_planner_node.h # ROS node wrapper
|
||||
│ └── parameters_helper.h # Configuration management
|
||||
├── src/
|
||||
│ ├── main.cpp # Application entry point
|
||||
│ ├── tangent_planner.cpp # Algorithm implementation
|
||||
│ ├── tangent_planner_node.cpp # ROS node implementation
|
||||
│ └── gtest.cpp # Unit tests
|
||||
├── launch/ # ROS launch files
|
||||
├── param/ # Configuration parameters
|
||||
├── srv/ # ROS service definitions
|
||||
├── CMakeLists.txt # CMake build configuration
|
||||
├── package.xml # ROS package metadata
|
||||
└── Dockerfile # Docker build environment
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
### ROS Packages
|
||||
|
||||
- `roscpp` - C++ ROS client library
|
||||
- `std_msgs` - Standard ROS message types
|
||||
- `nav_msgs` - Navigation message types
|
||||
- `geometry_msgs` - Geometry message types
|
||||
- `sensor_msgs` - Sensor message types (for scanner data)
|
||||
|
||||
### Build Requirements
|
||||
|
||||
- CMake 2.8.3+
|
||||
- GCC/G++ compiler
|
||||
- catkin build system
|
||||
- Google Test (for unit tests)
|
||||
|
||||
## Building
|
||||
|
||||
### From Source with catkin
|
||||
|
||||
```bash
|
||||
# Create and navigate to catkin workspace
|
||||
mkdir -p catkin_ws/src
|
||||
cd catkin_ws/src
|
||||
|
||||
# Clone repository
|
||||
git clone <repository-url> tangent_planner
|
||||
cd ..
|
||||
|
||||
# Build
|
||||
catkin_make
|
||||
source devel/setup.bash
|
||||
```
|
||||
|
||||
### With Docker
|
||||
|
||||
Build a Debian package using Docker:
|
||||
|
||||
```bash
|
||||
sudo ./release.sh
|
||||
```
|
||||
|
||||
Note: Requires Docker to be installed on your system.
|
||||
|
||||
## Installation
|
||||
|
||||
### generating debian package form source code
|
||||
### From Debian Package
|
||||
|
||||
package generation form source code has been automated by docker, so it can be done by executing release.sh
|
||||
1. Generate package: `sudo ./release.sh`
|
||||
2. Install package: `dpkg -i tangent_planner_*.deb`
|
||||
3. Source ROS setup: `source /opt/ros/<distro>/setup.bash`
|
||||
4. Run the node with your ROS configuration
|
||||
|
||||
```$ sudo ./release.sh```
|
||||
### Running the Node
|
||||
|
||||
note that the script uses docker to create debian package, and you must have docker installed on your system
|
||||
```bash
|
||||
rosrun tangent_planner tangent_planner
|
||||
```
|
||||
|
||||
### installing debian package
|
||||
you can install generated package by this command:
|
||||
Or use the provided launch files:
|
||||
|
||||
```$ dpkg -i debian_package_name.deb```
|
||||
```bash
|
||||
roslaunch tangent_planner <launch-file-name>.launch
|
||||
```
|
||||
|
||||
now the package should be in ros installation directory in the share subdirectory
|
||||
you can source ros setup.bash and run the package
|
||||
## Configuration
|
||||
|
||||
### Parameter Files
|
||||
|
||||
Configuration parameters are located in the `param/` directory. Adjust controller gains and thresholds:
|
||||
|
||||
- Motion controller gains (`b`, `c`, `k1`, `k2`, `k3`)
|
||||
- Turn controller gains (`kp_`, `kp_i_`)
|
||||
- State transition thresholds
|
||||
- Obstacle following parameters
|
||||
|
||||
### Services
|
||||
|
||||
The package provides several ROS services:
|
||||
|
||||
- `nav_path_start` - Start navigation to goal
|
||||
- `nav_path_stop` - Stop current navigation
|
||||
- `nav_get_patrol_name` - Get current patrol/goal name
|
||||
- `nav_get_status` - Get current navigation status
|
||||
- `nav_low_bat` - Handle low battery conditions
|
||||
|
||||
## Testing
|
||||
|
||||
Run the unit tests:
|
||||
|
||||
```bash
|
||||
catkin_make run_tests
|
||||
# or
|
||||
rosrun tangent_planner tangent_planner_test
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
See LICENSE file for details.
|
||||
|
||||
## Maintainer
|
||||
|
||||
- **Gfuse** (gfuse@gfuse.it)
|
||||
Reference in New Issue
Block a user