292 lines
13 KiB
Markdown
292 lines
13 KiB
Markdown
# robot_time
|
|
|
|
## Tổng quan
|
|
|
|
`robot_time` là một thư viện C++ cung cấp các công cụ quản lý thời gian cho các ứng dụng robot. Thư viện này được thiết kế để thay thế `ros::Time` trong ROS nhưng hoàn toàn độc lập, không phụ thuộc vào ROS hay bất kỳ framework nào khác. Đây là một giải pháp nhẹ và linh hoạt cho việc quản lý thời gian trong các hệ thống robot tự động.
|
|
|
|
## Mục đích và phạm vi ứng dụng
|
|
|
|
Thư viện `robot_time` được phát triển để giải quyết các nhu cầu quản lý thời gian trong các ứng dụng robot, bao gồm:
|
|
|
|
- **Đồng bộ hóa thời gian**: Cung cấp một hệ thống thời gian nhất quán cho toàn bộ ứng dụng robot
|
|
- **Điều khiển tần suất**: Hỗ trợ chạy các vòng lặp điều khiển ở tần suất cố định (ví dụ: 10Hz, 20Hz, 50Hz)
|
|
- **Lập lịch tác vụ**: Cho phép thực thi các tác vụ định kỳ một cách chính xác
|
|
- **Đo lường hiệu suất**: Cung cấp công cụ để đo thời gian thực thi và độ trễ
|
|
- **Mô phỏng thời gian**: Hỗ trợ cả thời gian thực (wall-clock) và thời gian mô phỏng (simulated time) cho testing và simulation
|
|
|
|
## Các thành phần chính
|
|
|
|
### 1. Time - Quản lý điểm thời gian
|
|
|
|
`Time` đại diện cho một điểm thời gian cụ thể trong hệ thống. Đây là lớp cơ bản nhất để làm việc với thời gian.
|
|
|
|
**Đặc điểm:**
|
|
- Lưu trữ thời gian với độ chính xác nanosecond (1 phần tỷ giây)
|
|
- Hỗ trợ cả thời gian thực và thời gian mô phỏng
|
|
- Có thể so sánh, cộng trừ với Duration
|
|
- Thread-safe, an toàn khi sử dụng trong môi trường đa luồng
|
|
- Cross-platform, hoạt động trên cả Linux và Windows
|
|
|
|
**Ứng dụng:**
|
|
- Đánh dấu thời điểm xảy ra sự kiện
|
|
- Ghi nhận timestamp cho dữ liệu sensor
|
|
- So sánh thời gian giữa các sự kiện
|
|
- Tính toán độ trễ và latency
|
|
|
|
### 2. Duration - Quản lý khoảng thời gian
|
|
|
|
`Duration` đại diện cho một khoảng thời gian, có thể là khoảng thời gian đã trôi qua hoặc khoảng thời gian cần chờ đợi.
|
|
|
|
**Đặc điểm:**
|
|
- Có thể dương (tương lai) hoặc âm (quá khứ)
|
|
- Hỗ trợ các phép toán cơ bản: cộng, trừ, nhân, chia
|
|
- Có thể chuyển đổi giữa các đơn vị: giây, nanosecond
|
|
- Cung cấp các hằng số tiện ích: giây, phút, giờ, ngày
|
|
- Có thể sử dụng để sleep (tạm dừng chương trình)
|
|
|
|
**Ứng dụng:**
|
|
- Tính toán thời gian thực thi của một tác vụ
|
|
- Đặt timeout cho các thao tác
|
|
- Điều chỉnh tốc độ của các vòng lặp
|
|
- Đo lường khoảng thời gian giữa các sự kiện
|
|
|
|
### 3. Rate - Điều khiển tần suất vòng lặp
|
|
|
|
`Rate` là công cụ để duy trì một vòng lặp chạy ở tần suất cố định. Đây là thành phần quan trọng cho các control loops trong robot.
|
|
|
|
**Đặc điểm:**
|
|
- Tự động tính toán thời gian sleep để duy trì tần suất mong muốn
|
|
- Có thể tạo từ tần suất (Hz) hoặc khoảng thời gian (Duration)
|
|
- Theo dõi thời gian thực tế của mỗi chu kỳ
|
|
- Tự động điều chỉnh để bù trừ cho overhead của hệ thống
|
|
|
|
**Ứng dụng:**
|
|
- Control loops với tần suất cố định (ví dụ: 20Hz cho điều khiển động cơ)
|
|
- Sensor data processing loops
|
|
- State estimation và filtering loops
|
|
- Real-time control systems
|
|
|
|
**Cơ chế hoạt động:**
|
|
Rate tự động tính toán thời gian còn lại trong mỗi chu kỳ và sleep để đảm bảo vòng lặp chạy đúng tần suất. Nếu một chu kỳ mất quá nhiều thời gian, Rate sẽ bỏ qua sleep để không làm chậm hệ thống.
|
|
|
|
### 4. Timer - Hẹn giờ định kỳ
|
|
|
|
`Timer` tạo một thread riêng để thực thi một hàm callback định kỳ. Đây là công cụ mạnh mẽ cho các tác vụ bất đồng bộ.
|
|
|
|
**Đặc điểm:**
|
|
- Chạy trong thread riêng, không chặn thread chính
|
|
- Có thể là one-shot (chỉ chạy một lần) hoặc repeating (lặp lại)
|
|
- Callback nhận thông tin chi tiết về timing (TimerEvent)
|
|
- Có thể start/stop động
|
|
- Tự động cleanup khi hủy
|
|
|
|
**TimerEvent chứa thông tin:**
|
|
- Thời gian thực tế khi callback được gọi
|
|
- Thời gian mong đợi khi callback được gọi
|
|
- Thời gian của callback trước đó
|
|
- Khoảng thời gian giữa các callback (để phát hiện drift)
|
|
|
|
**Ứng dụng:**
|
|
- Periodic sensor updates
|
|
- Background tasks
|
|
- Heartbeat và monitoring
|
|
- Scheduled maintenance tasks
|
|
- Event-driven programming
|
|
|
|
**Ưu điểm:**
|
|
- Không chặn thread chính
|
|
- Có thể quản lý nhiều timer đồng thời
|
|
- Cung cấp thông tin chi tiết về timing để debug và monitoring
|
|
|
|
### 5. WallTime - Thời gian thực (Wall-clock Time)
|
|
|
|
`WallTime` đại diện cho thời gian thực từ hệ thống, luôn sử dụng wall-clock time và không bị ảnh hưởng bởi simulated time.
|
|
|
|
**Đặc điểm:**
|
|
- Luôn sử dụng thời gian thực từ system clock
|
|
- Không cần khởi tạo (`Time::init()`)
|
|
- Không bao giờ throw exception
|
|
- Không bị ảnh hưởng bởi simulated time
|
|
- Thread-safe và cross-platform
|
|
|
|
**Khác biệt với Time:**
|
|
- `Time` có thể sử dụng simulated time (hữu ích cho testing)
|
|
- `WallTime` luôn dùng thời gian thực, không phụ thuộc vào simulated time
|
|
- `Time` cần khởi tạo, `WallTime` không cần
|
|
|
|
**Ứng dụng:**
|
|
- Đo thời gian thực thi (profiling/benchmarking)
|
|
- Timeout và thời gian chờ thực tế
|
|
- Logging với timestamp thực
|
|
- Giao tiếp với hardware cần timing chính xác
|
|
- Performance monitoring
|
|
|
|
### 6. WallTimer - Hẹn giờ định kỳ với thời gian thực
|
|
|
|
`WallTimer` tương tự như `Timer` nhưng sử dụng wall-clock time thay vì simulated time. Đây là công cụ mạnh mẽ cho các tác vụ cần timing chính xác trong thời gian thực.
|
|
|
|
**Đặc điểm:**
|
|
- Chạy trong thread riêng, không chặn thread chính
|
|
- Luôn sử dụng wall-clock time (không bị ảnh hưởng bởi simulated time)
|
|
- Có thể là one-shot (chỉ chạy một lần) hoặc repeating (lặp lại)
|
|
- Callback nhận thông tin chi tiết về timing (WallTimerEvent)
|
|
- Có thể start/stop và điều chỉnh period động
|
|
- Tự động cleanup khi hủy
|
|
|
|
**Khác biệt với Timer:**
|
|
- `Timer` sử dụng `Time`/`Duration` (có thể bị ảnh hưởng bởi simulated time)
|
|
- `WallTimer` sử dụng `WallTime`/`WallDuration` (luôn dùng thời gian thực)
|
|
- `Timer` phù hợp cho ROS messages và simulation
|
|
- `WallTimer` phù hợp cho performance monitoring, hardware interfaces, và real-time operations
|
|
|
|
**WallTimerEvent chứa thông tin:**
|
|
- Thời gian thực tế khi callback được gọi (wall-clock time)
|
|
- Thời gian mong đợi khi callback được gọi (wall-clock time)
|
|
- Thời gian của callback trước đó (wall-clock time)
|
|
- Khoảng thời gian giữa các callback (để phát hiện drift)
|
|
|
|
**Ứng dụng:**
|
|
- Performance monitoring và profiling
|
|
- Real-time deadlines và timeouts
|
|
- Hardware interfaces cần timing chính xác
|
|
- Benchmarking và measurement
|
|
- Background tasks cần chạy theo thời gian thực
|
|
|
|
**Ví dụ:**
|
|
```cpp
|
|
// Đo thời gian thực thi
|
|
robot::WallTime start = robot::WallTime::now();
|
|
doSomething();
|
|
robot::WallDuration elapsed = robot::WallTime::now() - start;
|
|
std::cout << "Took " << elapsed.toSec() << " seconds" << std::endl;
|
|
```
|
|
|
|
### 6. WallRate - Rate dùng thời gian thực
|
|
|
|
`WallRate` tương tự như `Rate` nhưng luôn sử dụng thời gian thực (wall-clock time) thay vì simulated time.
|
|
|
|
**Khác biệt với Rate:**
|
|
- Rate có thể sử dụng simulated time (hữu ích cho testing)
|
|
- WallRate luôn dùng thời gian thực, không bị ảnh hưởng bởi simulated time
|
|
|
|
**Ứng dụng:**
|
|
- Các tác vụ cần chạy theo thời gian thực tuyệt đối
|
|
- Interface với hardware cần timing chính xác
|
|
- Logging và monitoring theo thời gian thực
|
|
|
|
## Tính năng nổi bật
|
|
|
|
### 1. Simulated Time Support
|
|
|
|
Thư viện hỗ trợ cả simulated time và wall-clock time. Simulated time cho phép:
|
|
- Chạy simulation với tốc độ nhanh hơn hoặc chậm hơn thời gian thực
|
|
- Testing với các kịch bản thời gian cụ thể
|
|
- Debugging với khả năng điều khiển thời gian
|
|
|
|
### 2. Thread Safety
|
|
|
|
Tất cả các operations đều thread-safe, cho phép:
|
|
- Sử dụng an toàn trong multi-threaded applications
|
|
- Truy cập đồng thời từ nhiều thread
|
|
- Không cần mutex bổ sung cho các thao tác cơ bản
|
|
|
|
### 3. High Precision
|
|
|
|
Sử dụng nanosecond precision đảm bảo:
|
|
- Độ chính xác cao cho các ứng dụng real-time
|
|
- Khả năng đo lường chính xác các khoảng thời gian ngắn
|
|
- Phù hợp cho các hệ thống điều khiển tốc độ cao
|
|
|
|
### 4. Cross-platform Compatibility
|
|
|
|
Hỗ trợ đa nền tảng:
|
|
- Linux (sử dụng POSIX time functions)
|
|
- Windows (sử dụng Windows-specific timing APIs)
|
|
- Tự động phát hiện và sử dụng API phù hợp
|
|
|
|
## Cấu trúc thư mục
|
|
|
|
```
|
|
robot_time/
|
|
├── include/robot/ # Header files
|
|
│ ├── time.h # Time class
|
|
│ ├── duration.h # Duration class
|
|
│ ├── rate.h # Rate và WallRate classes
|
|
│ ├── timer.h # Timer class
|
|
│ └── exception.h # Exception classes
|
|
├── src/ # Implementation files
|
|
│ ├── time.cpp
|
|
│ ├── duration.cpp
|
|
│ ├── rate.cpp
|
|
│ └── timer.cpp
|
|
├── test/ # Unit tests
|
|
├── CMakeLists.txt # Build configuration
|
|
├── package.xml # Package metadata
|
|
├── README.md # Tài liệu này
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- **C++17**: Yêu cầu C++ standard 17 trở lên
|
|
- **GTest**: Chỉ cần khi build unit tests (optional)
|
|
- **Platform libraries**:
|
|
- Linux: POSIX time functions
|
|
- Windows: Windows timing APIs
|
|
|
|
## 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
|
|
|
|
### Control Loops
|
|
Sử dụng `Rate` để duy trì control loops ở tần suất cố định, đảm bảo robot phản ứng kịp thời và nhất quán.
|
|
|
|
### Sensor Processing
|
|
Sử dụng `Timer` để xử lý dữ liệu sensor định kỳ trong background thread, không làm chậm main control loop.
|
|
|
|
### Time Synchronization
|
|
Sử dụng `Time` để đồng bộ hóa dữ liệu từ nhiều nguồn sensor khác nhau, đảm bảo tất cả dữ liệu có cùng timestamp.
|
|
|
|
### Performance Monitoring
|
|
Sử dụng `Duration` để đo thời gian thực thi của các thuật toán, giúp tối ưu hóa hiệu suất.
|
|
|
|
### Simulation và Testing
|
|
Sử dụng simulated time để chạy các test cases với timing cụ thể, cho phép reproduce bugs và test edge cases.
|
|
|
|
## Best Practices
|
|
|
|
1. **Sử dụng Rate cho control loops**: Đảm bảo tần suất ổn định và có thể dự đoán được
|
|
|
|
2. **Sử dụng Timer cho background tasks**: Tránh chặn main thread với các tác vụ định kỳ
|
|
|
|
3. **Kiểm tra timing drift**: Monitor sự khác biệt giữa expected time và actual time để phát hiện vấn đề
|
|
|
|
4. **Sử dụng Duration constants**: Sử dụng các hằng số có sẵn (SECOND, MINUTE, etc.) thay vì magic numbers
|
|
|
|
5. **Thread safety**: Mặc dù các operations đều thread-safe, cần cẩn thận khi chia sẻ dữ liệu giữa các thread
|
|
|
|
## Lưu ý quan trọng
|
|
|
|
- **Initialization**: Cần khởi tạo hệ thống (gọi `robot::init()` hoặc tạo `robot::NodeHandle`) trước khi sử dụng `Time::now()`
|
|
|
|
- **Timer overhead**: Mỗi Timer tạo một thread riêng, cần quản lý số lượng timer hợp lý để tránh overhead
|
|
|
|
- **Rate accuracy**: `Rate::sleep()` có thể không chính xác 100% do overhead của system calls, nhưng thường đủ cho hầu hết các ứng dụng
|
|
|
|
- **Simulated time**: Khi sử dụng simulated time, tất cả các Time và Duration operations sẽ sử dụng simulated time, trừ WallRate
|
|
|
|
## Tài liệu tham khảo
|
|
|
|
- `WALLTIME_USAGE.md` - Hướng dẫn chi tiết về WallTime với các ví dụ và use cases
|
|
- `TIMER_USAGE.md` - Hướng dẫn chi tiết về cách sử dụng Timer với các ví dụ
|
|
- `TIMER_EVENT_EXPLANATION.md` - Giải thích chi tiết về TimerEvent structure và các trường dữ liệu
|
|
- `CHANGELOG.rst` - Lịch sử thay đổi và version history
|
|
|
|
## License
|
|
|
|
BSD License - Xem file LICENSE trong thư mục gốc của project.
|