diff --git a/README.md b/README.md index 4e2bd443..ea0a4c6d 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ npm i rclnodejs - **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#"` to your `package.json` dependency section. -Try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started. +See the [features](./docs/FEATURES.md) and try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started. ## rclnodejs-cli diff --git a/docs/FEATURES.md b/docs/FEATURES.md new file mode 100644 index 00000000..17fafebf --- /dev/null +++ b/docs/FEATURES.md @@ -0,0 +1,201 @@ +# rclnodejs Features + +This document provides an overview of the key features and capabilities available in rclnodejs, the Node.js client library for ROS 2. + +## Core ROS 2 Communication + +### Publishers and Subscribers + +- **Topic Publishing**: Publish messages to ROS 2 topics with full type safety +- **Topic Subscription**: Subscribe to ROS 2 topics with callback-based message handling +- **Raw Message Support**: Access to raw serialized message data for advanced use cases +- **Event Callbacks**: Support for subscription and publisher event handling (incompatible QoS, liveliness lost, etc.) + +### Services + +- **Service Clients**: Call ROS 2 services with request/response patterns +- **Service Servers**: Create service endpoints to handle incoming requests +- **Service Introspection**: Built-in service call monitoring and debugging capabilities +- **Asynchronous Operations**: Promise-based and callback-based service interactions +- **Type Description Service**: Support for `type_description_interfaces/srv/GetTypeDescription` to retrieve detailed type information for ROS 2 messages, services, and actions + +### Actions + +- **Action Clients**: Send goals to action servers with feedback and result handling +- **Action Servers**: Implement action endpoints with goal handling, feedback publishing, and result reporting +- **Goal Management**: Full lifecycle management including goal cancellation and preemption +- **Multiple Goal Support**: Handle multiple concurrent goals with individual goal handles + +## Node Management + +### Node Lifecycle + +- **Standard Nodes**: Create and manage regular ROS 2 nodes +- **Lifecycle Nodes**: Support for managed node lifecycle (configure, activate, deactivate, shutdown) +- **Node Options**: Comprehensive node configuration including domain ID, namespace, and parameter overrides +- **ROS Arguments**: Create nodes with ROS command-line arguments for remapping and configuration +- **Global Arguments**: Support for `useGlobalArguments` flag to use process-wide ROS arguments +- **Node Destruction**: Proper cleanup and resource management + +### Context Management + +- **ROS 2 Context**: Initialize and manage ROS 2 execution context +- **Multi-Context Support**: Support for multiple ROS 2 contexts in the same process +- **Context Configuration**: Custom context initialization with domain ID and security settings + +## Quality of Service (QoS) + +### QoS Profiles + +- **Built-in Profiles**: Access to standard ROS 2 QoS profiles (default, sensor data, services, parameters, etc.) +- **Custom QoS**: Create custom QoS policies for specific requirements +- **QoS Configuration**: Set reliability, durability, history, and depth policies +- **QoS Compatibility**: Automatic QoS negotiation and compatibility checking + +### QoS Policies + +- **Reliability**: Best effort or reliable message delivery +- **Durability**: Transient local or volatile message persistence +- **History**: Keep last N messages or keep all messages +- **Deadline and Lifespan**: Advanced timing constraints for real-time applications + +## Time and Clock Management + +### Clock Types + +- **System Clock**: Standard system time +- **ROS Time**: ROS simulation time support +- **Steady Clock**: Monotonic clock for timing measurements +- **Time Sources**: Automatic time source management and synchronization + +### Timing Features + +- **Timer Creation**: High-precision periodic timers with nanosecond resolution +- **Rate Control**: Frequency-based rate limiting for periodic operations +- **Time Conversion**: Utilities for time format conversion and manipulation +- **Simulation Time**: Full support for `/clock` topic and `use_sim_time` parameter + +## Parameter System + +### Parameter Management + +- **Parameter Declaration**: Declare node parameters with type checking and validation +- **Parameter Access**: Get and set parameter values at runtime +- **Parameter Events**: Subscribe to parameter change notifications +- **Parameter Services**: Built-in parameter services for external parameter management + +### Parameter Types + +- **Primitive Types**: Support for bool, int64, float64, string parameters +- **Array Types**: Support for arrays of primitive types +- **Parameter Descriptors**: Rich parameter metadata including ranges, descriptions, and constraints + +## Advanced Features + +### Lifecycle Publisher + +- **Managed Publishing**: Publishers that only send messages when the lifecycle node is active +- **State Synchronization**: Automatic activation/deactivation with lifecycle node state changes +- **Resource Management**: Efficient resource usage by disabling publishing when inactive + +### Guard Conditions + +- **Custom Triggers**: Create custom triggerable conditions for the ROS 2 executor +- **Event Synchronization**: Synchronize external events with ROS 2 execution +- **Wake-up Mechanisms**: Programmatically wake up the executor for immediate processing + +### Message Generation + +- **Dynamic Message Types**: Generate JavaScript message classes from ROS 2 interface definitions +- **IDL Support**: Support for Interface Definition Language (IDL) files +- **TypeScript Declarations**: Automatic generation of TypeScript type definitions +- **Custom Messages**: Support for custom message, service, and action definitions + +### ROS 2 Process Management + +- **Package Execution**: Programmatically run ROS 2 package executables using `ros2Run()` function +- **Launch File Execution**: Execute ROS 2 launch files programmatically using `ros2Launch()` function +- **Argument Support**: Pass command-line arguments to executables and launch files +- **Input Validation**: Comprehensive validation for package names, executables, and launch files + +## Development Tools + +### TypeScript Support + +- **Full Type Safety**: Complete TypeScript definitions for all APIs +- **Auto-completion**: Rich IDE support with intelligent code completion +- **Type Checking**: Compile-time type checking for ROS 2 message structures +- **Modern JavaScript**: Support for ES modules and modern JavaScript features + +### Logging + +- **ROS 2 Logging**: Integration with ROS 2's logging infrastructure +- **Log Levels**: Support for DEBUG, INFO, WARN, ERROR, and FATAL log levels +- **Logger Configuration**: Per-node logger configuration and management +- **Console Output**: Formatted console output with timestamps and severity levels + +### Introspection and Debugging + +- **Service Introspection**: Monitor service calls with detailed request/response logging +- **Graph Introspection**: Access to ROS 2 computation graph information +- **Event Monitoring**: Track publisher/subscriber events and QoS incompatibilities +- **Performance Metrics**: Built-in performance monitoring and profiling capabilities + +## Integration Features + +### Cross-Platform Support + +- **Windows**: Full support for Windows development environments +- **Linux**: Native Linux support with system package integration +- **macOS**: Complete macOS compatibility +- **Docker**: Container-friendly deployment options + +### Electron Integration + +- **Desktop Applications**: Build cross-platform desktop applications using Electron +- **Web Technologies**: Leverage HTML, CSS, and modern web frameworks +- **3D Visualization**: Integration with WebGL and Three.js for 3D robotics visualization +- **Real-time UIs**: Create responsive user interfaces for robot control and monitoring + +### Node.js Ecosystem + +- **NPM Integration**: Standard npm package management and dependency resolution +- **Module System**: Support for CommonJS and ES modules +- **Async/Await**: Modern asynchronous programming patterns +- **Event-Driven**: Built on Node.js event-driven architecture for high performance + +## Security and Reliability + +### Error Handling + +- **Exception Safety**: Robust error handling with proper exception propagation +- **Resource Cleanup**: Automatic resource cleanup on node destruction +- **Memory Management**: Efficient memory management with garbage collection integration +- **Graceful Shutdown**: Clean shutdown procedures with proper resource deallocation + +### Security Features + +- **ROS 2 Security**: Integration with ROS 2 security framework (SROS2) +- **Certificate Management**: Support for X.509 certificates and key management +- **Access Control**: Fine-grained access control for topics, services, and actions +- **Encryption**: Support for DDS security features including encryption and authentication + +## Performance Optimization + +### Efficient Execution + +- **Single-Threaded**: Efficient single-threaded execution model optimized for Node.js +- **Event Loop Integration**: Seamless integration with Node.js event loop +- **Memory Efficiency**: Optimized memory usage with minimal overhead +- **Zero-Copy Operations**: Support for zero-copy message passing where possible + +### Scalability + +- **Multiple Nodes**: Support for multiple nodes in a single process +- **High-Frequency Operations**: Optimized for high-frequency publishing and subscription +- **Large Message Support**: Efficient handling of large message payloads +- **Connection Management**: Automatic connection management and optimization + +--- + +For detailed API documentation and usage examples, see the [API Documentation](https://robotwebtools.github.io/rclnodejs/docs/index.html) and [Examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example).