# robot_cpp

## Tổng quan

`robot_cpp` là một thư viện C++ cung cấp các công cụ tiện ích cốt lõi cho phát triển ứng dụng robot, tương tự như các utilities trong ROS nhưng hoàn toàn độc lập, không phụ thuộc vào ROS. Thư viện này cung cấp nền tảng cơ bản cho việc xây dựng các hệ thống robot tự động.

## Mục đích và phạm vi ứng dụng

Thư viện `robot_cpp` được thiết kế để giải quyết các nhu cầu cơ bản trong phát triển ứng dụng robot:

- **Logging và Debugging**: Cung cấp hệ thống logging với màu sắc để dễ dàng phân biệt các loại thông điệp
- **Quản lý cấu hình**: Hỗ trợ quản lý tham số từ file YAML, tương tự ROS parameter server
- **Quản lý vòng đời**: Cung cấp cơ chế quản lý lifecycle của hệ thống robot, xử lý shutdown graceful
- **Plugin Loading**: Hỗ trợ tìm kiếm và load các dynamic plugins sử dụng boost::dll

## Các thành phần chính

### 1. Console Module - Hệ thống Logging

Module Console cung cấp hệ thống logging với hỗ trợ màu sắc ANSI để phân biệt các loại thông điệp.

**Đặc điểm:**
- Hỗ trợ nhiều mức độ logging: info, success, warning, error, debug
- Tự động phát hiện khả năng hỗ trợ màu của terminal
- Throttle logging để giới hạn tần suất log, tránh spam console
- Hỗ trợ logging với thông tin file và line number để debug
- Tự động reset màu sau khi in để tránh ảnh hưởng đến output tiếp theo
- Có thể bật/tắt màu sắc tùy theo môi trường

**Cơ chế hoạt động:**
- Kiểm tra biến môi trường `NO_COLOR` và `TERM` để xác định hỗ trợ màu
- Sử dụng static variables để lưu timestamp cho throttle logging
- Tự động thêm newline nếu format string không kết thúc bằng newline
- Hỗ trợ nhiều màu sắc: red, green, yellow, blue, cyan, magenta, white và các biến thể bright

**Ứng dụng:**
- Debug và monitoring trong quá trình phát triển
- Hiển thị trạng thái hệ thống với màu sắc dễ phân biệt
- Logging có điều kiện với throttle để tránh spam
- Tích hợp vào các hệ thống logging lớn hơn

### 2. NodeHandle Module - Quản lý Tham số

Module NodeHandle cung cấp interface quản lý tham số giống ROS parameter server, sử dụng YAML files làm backend.

**Đặc điểm:**
- Hỗ trợ namespace phân cấp giống ROS
- Tự động load YAML files từ config directory
- Hỗ trợ nhiều kiểu dữ liệu: bool, int, double, float, string, vector, map
- Merge nhiều YAML files vào một parameter tree
- Thread-safe parameter access
- Hỗ trợ nested parameters với cấu trúc phân cấp

**Cơ chế hoạt động:**
- Sử dụng `YAML::Node` để lưu trữ tham số trong memory
- Static `root_` node chứa toàn bộ parameter tree, được chia sẻ giữa tất cả NodeHandle instances
- Mỗi NodeHandle instance scope vào một namespace cụ thể
- Tự động tìm và load YAML files từ config directory khi khởi tạo
- Hỗ trợ remapping parameters tương tự ROS

**Namespace System:**
- Root namespace (`""` hoặc `"/"`): Truy cập toàn bộ parameter tree
- Private namespace (`"~"`): Map tới config directory của node hiện tại
- Nested namespaces: Sử dụng `/` separator (ví dụ: `"robot/base/velocity"`)
- Tất cả NodeHandle instances chia sẻ cùng một static parameter tree

**Ứng dụng:**
- Quản lý cấu hình robot từ file YAML
- Truyền tham số giữa các modules
- Runtime configuration changes
- Testing với các bộ tham số khác nhau

### 3. Init Module - Quản lý Vòng đời Hệ thống

Module Init quản lý vòng đời của robot system, tương tự `ros::init()` và `ros::ok()` trong ROS.

**Đặc điểm:**
- Quản lý trạng thái system (đang chạy hay đã shutdown)
- Xử lý shutdown graceful với signal handling
- Tự động xử lý SIGINT (Ctrl-C) để shutdown an toàn
- Hỗ trợ custom signal handler
- Thread-safe với `std::atomic`

**Cơ chế hoạt động:**
- Sử dụng `std::atomic` để đảm bảo thread-safety
- Tự động cài đặt SIGINT handler để xử lý Ctrl-C
- Quản lý trạng thái shutdown với 2 flags: `shutdown_requested` và `shutdown_complete`
- Hỗ trợ custom signal handler nếu cần xử lý đặc biệt

**Các trạng thái:**
- **Running**: System đang chạy bình thường
- **Shutdown Requested**: Shutdown đã được yêu cầu (ngay lập tức khi gọi `shutdown()`)
- **Shutdown Complete**: System đã shutdown hoàn toàn

**Ứng dụng:**
- Main loops với kiểm tra `robot::ok()`
- Thread loops cần kiểm tra trạng thái system
- Long-running callbacks cần early exit khi shutdown
- Graceful shutdown với cleanup resources

### 4. PluginLoaderHelper Module - Tìm kiếm Plugin Libraries

Module PluginLoaderHelper giúp tìm đường dẫn library file (.so) từ tên symbol (export name) được sử dụng với `BOOST_DLL_ALIAS`.

**Đặc điểm:**
- Map tên symbol (export name) sang đường dẫn library file
- Đọc cấu hình từ YAML file hoặc NodeHandle
- Tự động tìm build directory tại runtime
- Hỗ trợ nhiều cách tìm kiếm: từ config, từ build directory, từ system paths

**Cơ chế hoạt động:**
- Đọc file YAML (`boost_dll_plugins.yaml`) hoặc từ NodeHandle
- Map symbol names (ví dụ: "CustomPlanner") sang library paths
- Tự động tìm build directory từ environment variables hoặc config
- Hỗ trợ fallback mechanisms nếu không tìm thấy trong config

**Ứng dụng:**
- Dynamic loading của global planners, local planners, recovery behaviors
- Plugin discovery trong runtime
- Tích hợp với boost::dll để load plugins
- Quản lý plugin registry

## Kiến trúc

### Cấu trúc thư mục

```
robot_cpp/
├── include/robot/
│   ├── console.h              # Console logging API
│   ├── node_handle.h          # NodeHandle parameter management API
│   ├── init.h                 # System initialization and shutdown API
│   └── plugin_loader_helper.h # Plugin loader helper API
├── src/
│   ├── console.cpp            # Console implementation
│   ├── node_handle.cpp        # NodeHandle implementation
│   ├── init.cpp               # Init implementation
│   └── plugin_loader_helper.cpp # PluginLoaderHelper implementation
├── test/
│   └── test_node_handle.cpp   # Unit tests
├── INIT_USAGE.md              # Hướng dẫn chi tiết về Init module
├── PLUGIN_LOADER_README.md    # Hướng dẫn về PluginLoaderHelper
└── CMakeLists.txt
```

### Mối quan hệ giữa các modules

- **Console** là module độc lập, không phụ thuộc vào modules khác
- **NodeHandle** sử dụng yaml-cpp để parse YAML files
- **Init** quản lý lifecycle chung của system, được sử dụng bởi tất cả modules khác
- **PluginLoaderHelper** sử dụng NodeHandle để đọc cấu hình plugins

## Dependencies

- **yaml-cpp**: Thư viện parse YAML files (cho NodeHandle và PluginLoaderHelper)
- **robot_xmlrpcpp**: Hỗ trợ XmlRpcValue conversion (optional, cho NodeHandle)
- **robot_time**: Thư viện quản lý thời gian (cho Init module với Rate/Duration)
- **C++17**: Yêu cầu C++ standard 17 trở lên
- **Boost.DLL**: Được sử dụng bởi PluginLoaderHelper (thông qua boost::dll)

## Build và Installation

Thư viện hỗ trợ cả Catkin và Standalone CMake:

- **Với Catkin**: Tích hợp vào catkin workspace và build như các ROS packages khác
- **Với Standalone CMake**: Có thể build độc lập, không cần ROS

## Use Cases

### Configuration Management
Sử dụng NodeHandle để quản lý tất cả cấu hình robot từ file YAML, cho phép thay đổi cấu hình mà không cần recompile.

### System Logging
Sử dụng Console module để log thông tin, cảnh báo, và lỗi với màu sắc, giúp dễ dàng debug và monitor hệ thống.

### Lifecycle Management
Sử dụng Init module để quản lý vòng đời của ứng dụng, đảm bảo shutdown graceful khi nhận Ctrl-C hoặc signal khác.

### Plugin Discovery
Sử dụng PluginLoaderHelper để tìm và load các plugins động tại runtime, cho phép mở rộng hệ thống mà không cần recompile.

### Multi-threaded Applications
Tất cả các modules đều thread-safe, cho phép sử dụng an toàn trong các ứng dụng đa luồng.

## Best Practices

1. **Sử dụng NodeHandle cho tất cả cấu hình**: Tránh hardcode parameters, sử dụng YAML files

2. **Sử dụng Console logging thay vì printf/cout**: Có màu sắc và throttle logging tự động

3. **Luôn kiểm tra robot::ok() trong loops**: Đảm bảo có thể shutdown gracefully

4. **Sử dụng throttle logging cho frequent messages**: Tránh spam console với các messages lặp lại

5. **Namespace organization**: Sử dụng namespace phân cấp để tổ chức parameters một cách logic

6. **Plugin configuration**: Sử dụng PluginLoaderHelper thay vì hardcode library paths

## Tính năng nổi bật

### 1. Color Support với Auto-detection
Console module tự động phát hiện khả năng hỗ trợ màu của terminal và tự động tắt màu nếu:
- Biến môi trường `NO_COLOR` được set
- Terminal không hỗ trợ ANSI colors
- Output được redirect vào file

### 2. Throttle Logging
Mỗi hàm throttle sử dụng static variable riêng để lưu timestamp, cho phép:
- Giới hạn tần suất log của các messages lặp lại
- Tránh spam console với các messages thường xuyên
- Tự động reset sau một khoảng thời gian

### 3. YAML Auto-loading
NodeHandle tự động tìm và load YAML files từ config directory khi khởi tạo:
- Tìm tất cả `.yaml` và `.yml` files trong config directory
- Merge tất cả files vào một parameter tree
- Hỗ trợ nested structures và arrays

### 4. Thread-safe Operations
Tất cả các operations đều thread-safe:
- NodeHandle sử dụng static parameter tree với thread-safe access
- Init module sử dụng `std::atomic` cho flags
- Console logging thread-safe với static variables

### 5. Graceful Shutdown
Init module cung cấp cơ chế shutdown graceful:
- Tự động xử lý SIGINT (Ctrl-C)
- Hỗ trợ custom signal handlers
- Phân biệt giữa "shutdown requested" và "shutdown complete"
- Cho phép early exit trong long-running callbacks

## Lưu ý quan trọng

- **NodeHandle static tree**: Tất cả NodeHandle instances chia sẻ cùng một static parameter tree, thay đổi từ một instance sẽ ảnh hưởng đến tất cả instances khác

- **YAML loading order**: YAML files được load và merge theo thứ tự filesystem, file sau sẽ override parameters của file trước nếu có conflict

- **Throttle logging scope**: Mỗi hàm throttle sử dụng static variable riêng, các lời gọi từ cùng một vị trí code sẽ chia sẻ cùng một throttle counter

- **Plugin path resolution**: PluginLoaderHelper tìm library paths theo thứ tự: config file → build directory → system paths

- **Init timing**: Cần gọi `robot::init()` trước khi sử dụng các modules khác, đặc biệt là `robot::Time::now()`

## Tài liệu tham khảo

- `INIT_USAGE.md` - Hướng dẫn chi tiết về Init module với các use cases và best practices
- `PLUGIN_LOADER_README.md` - Hướng dẫn về PluginLoaderHelper và cách cấu hình plugins
- `README.md` (file này) - Tổng quan về toàn bộ thư viện

## License

BSD License - Xem file LICENSE trong thư mục gốc.
