Skip to content

Commit 721f05e

Browse files
minggangwminggangw
committed
Add FEATURES.md file (#1235)
This PR adds comprehensive documentation about rclnodejs features by creating a new FEATURES.md file and updating the README to reference it. The purpose is to provide users with a detailed overview of all capabilities available in the rclnodejs library. - Creates a comprehensive FEATURES.md documentation file covering all major rclnodejs capabilities - Updates README.md to include a reference to the new features documentation Fix: #1234
1 parent f21546d commit 721f05e

File tree

2 files changed

+202
-1
lines changed

2 files changed

+202
-1
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ npm i rclnodejs
4848

4949
- **Note:** to install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
5050

51-
Try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started.
51+
See the [features](./docs/FEATURES.md) and try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started.
5252

5353
## rclnodejs-cli
5454

‎docs/FEATURES.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# rclnodejs Features
2+
3+
This document provides an overview of the key features and capabilities available in rclnodejs, the Node.js client library for ROS 2.
4+
5+
## Core ROS 2 Communication
6+
7+
### Publishers and Subscribers
8+
9+
- **Topic Publishing**: Publish messages to ROS 2 topics with full type safety
10+
- **Topic Subscription**: Subscribe to ROS 2 topics with callback-based message handling
11+
- **Raw Message Support**: Access to raw serialized message data for advanced use cases
12+
- **Event Callbacks**: Support for subscription and publisher event handling (incompatible QoS, liveliness lost, etc.)
13+
14+
### Services
15+
16+
- **Service Clients**: Call ROS 2 services with request/response patterns
17+
- **Service Servers**: Create service endpoints to handle incoming requests
18+
- **Service Introspection**: Built-in service call monitoring and debugging capabilities
19+
- **Asynchronous Operations**: Promise-based and callback-based service interactions
20+
- **Type Description Service**: Support for `type_description_interfaces/srv/GetTypeDescription` to retrieve detailed type information for ROS 2 messages, services, and actions
21+
22+
### Actions
23+
24+
- **Action Clients**: Send goals to action servers with feedback and result handling
25+
- **Action Servers**: Implement action endpoints with goal handling, feedback publishing, and result reporting
26+
- **Goal Management**: Full lifecycle management including goal cancellation and preemption
27+
- **Multiple Goal Support**: Handle multiple concurrent goals with individual goal handles
28+
29+
## Node Management
30+
31+
### Node Lifecycle
32+
33+
- **Standard Nodes**: Create and manage regular ROS 2 nodes
34+
- **Lifecycle Nodes**: Support for managed node lifecycle (configure, activate, deactivate, shutdown)
35+
- **Node Options**: Comprehensive node configuration including domain ID, namespace, and parameter overrides
36+
- **ROS Arguments**: Create nodes with ROS command-line arguments for remapping and configuration
37+
- **Global Arguments**: Support for `useGlobalArguments` flag to use process-wide ROS arguments
38+
- **Node Destruction**: Proper cleanup and resource management
39+
40+
### Context Management
41+
42+
- **ROS 2 Context**: Initialize and manage ROS 2 execution context
43+
- **Multi-Context Support**: Support for multiple ROS 2 contexts in the same process
44+
- **Context Configuration**: Custom context initialization with domain ID and security settings
45+
46+
## Quality of Service (QoS)
47+
48+
### QoS Profiles
49+
50+
- **Built-in Profiles**: Access to standard ROS 2 QoS profiles (default, sensor data, services, parameters, etc.)
51+
- **Custom QoS**: Create custom QoS policies for specific requirements
52+
- **QoS Configuration**: Set reliability, durability, history, and depth policies
53+
- **QoS Compatibility**: Automatic QoS negotiation and compatibility checking
54+
55+
### QoS Policies
56+
57+
- **Reliability**: Best effort or reliable message delivery
58+
- **Durability**: Transient local or volatile message persistence
59+
- **History**: Keep last N messages or keep all messages
60+
- **Deadline and Lifespan**: Advanced timing constraints for real-time applications
61+
62+
## Time and Clock Management
63+
64+
### Clock Types
65+
66+
- **System Clock**: Standard system time
67+
- **ROS Time**: ROS simulation time support
68+
- **Steady Clock**: Monotonic clock for timing measurements
69+
- **Time Sources**: Automatic time source management and synchronization
70+
71+
### Timing Features
72+
73+
- **Timer Creation**: High-precision periodic timers with nanosecond resolution
74+
- **Rate Control**: Frequency-based rate limiting for periodic operations
75+
- **Time Conversion**: Utilities for time format conversion and manipulation
76+
- **Simulation Time**: Full support for `/clock` topic and `use_sim_time` parameter
77+
78+
## Parameter System
79+
80+
### Parameter Management
81+
82+
- **Parameter Declaration**: Declare node parameters with type checking and validation
83+
- **Parameter Access**: Get and set parameter values at runtime
84+
- **Parameter Events**: Subscribe to parameter change notifications
85+
- **Parameter Services**: Built-in parameter services for external parameter management
86+
87+
### Parameter Types
88+
89+
- **Primitive Types**: Support for bool, int64, float64, string parameters
90+
- **Array Types**: Support for arrays of primitive types
91+
- **Parameter Descriptors**: Rich parameter metadata including ranges, descriptions, and constraints
92+
93+
## Advanced Features
94+
95+
### Lifecycle Publisher
96+
97+
- **Managed Publishing**: Publishers that only send messages when the lifecycle node is active
98+
- **State Synchronization**: Automatic activation/deactivation with lifecycle node state changes
99+
- **Resource Management**: Efficient resource usage by disabling publishing when inactive
100+
101+
### Guard Conditions
102+
103+
- **Custom Triggers**: Create custom triggerable conditions for the ROS 2 executor
104+
- **Event Synchronization**: Synchronize external events with ROS 2 execution
105+
- **Wake-up Mechanisms**: Programmatically wake up the executor for immediate processing
106+
107+
### Message Generation
108+
109+
- **Dynamic Message Types**: Generate JavaScript message classes from ROS 2 interface definitions
110+
- **IDL Support**: Support for Interface Definition Language (IDL) files
111+
- **TypeScript Declarations**: Automatic generation of TypeScript type definitions
112+
- **Custom Messages**: Support for custom message, service, and action definitions
113+
114+
### ROS 2 Process Management
115+
116+
- **Package Execution**: Programmatically run ROS 2 package executables using `ros2Run()` function
117+
- **Launch File Execution**: Execute ROS 2 launch files programmatically using `ros2Launch()` function
118+
- **Argument Support**: Pass command-line arguments to executables and launch files
119+
- **Input Validation**: Comprehensive validation for package names, executables, and launch files
120+
121+
## Development Tools
122+
123+
### TypeScript Support
124+
125+
- **Full Type Safety**: Complete TypeScript definitions for all APIs
126+
- **Auto-completion**: Rich IDE support with intelligent code completion
127+
- **Type Checking**: Compile-time type checking for ROS 2 message structures
128+
- **Modern JavaScript**: Support for ES modules and modern JavaScript features
129+
130+
### Logging
131+
132+
- **ROS 2 Logging**: Integration with ROS 2's logging infrastructure
133+
- **Log Levels**: Support for DEBUG, INFO, WARN, ERROR, and FATAL log levels
134+
- **Logger Configuration**: Per-node logger configuration and management
135+
- **Console Output**: Formatted console output with timestamps and severity levels
136+
137+
### Introspection and Debugging
138+
139+
- **Service Introspection**: Monitor service calls with detailed request/response logging
140+
- **Graph Introspection**: Access to ROS 2 computation graph information
141+
- **Event Monitoring**: Track publisher/subscriber events and QoS incompatibilities
142+
- **Performance Metrics**: Built-in performance monitoring and profiling capabilities
143+
144+
## Integration Features
145+
146+
### Cross-Platform Support
147+
148+
- **Windows**: Full support for Windows development environments
149+
- **Linux**: Native Linux support with system package integration
150+
- **macOS**: Complete macOS compatibility
151+
- **Docker**: Container-friendly deployment options
152+
153+
### Electron Integration
154+
155+
- **Desktop Applications**: Build cross-platform desktop applications using Electron
156+
- **Web Technologies**: Leverage HTML, CSS, and modern web frameworks
157+
- **3D Visualization**: Integration with WebGL and Three.js for 3D robotics visualization
158+
- **Real-time UIs**: Create responsive user interfaces for robot control and monitoring
159+
160+
### Node.js Ecosystem
161+
162+
- **NPM Integration**: Standard npm package management and dependency resolution
163+
- **Module System**: Support for CommonJS and ES modules
164+
- **Async/Await**: Modern asynchronous programming patterns
165+
- **Event-Driven**: Built on Node.js event-driven architecture for high performance
166+
167+
## Security and Reliability
168+
169+
### Error Handling
170+
171+
- **Exception Safety**: Robust error handling with proper exception propagation
172+
- **Resource Cleanup**: Automatic resource cleanup on node destruction
173+
- **Memory Management**: Efficient memory management with garbage collection integration
174+
- **Graceful Shutdown**: Clean shutdown procedures with proper resource deallocation
175+
176+
### Security Features
177+
178+
- **ROS 2 Security**: Integration with ROS 2 security framework (SROS2)
179+
- **Certificate Management**: Support for X.509 certificates and key management
180+
- **Access Control**: Fine-grained access control for topics, services, and actions
181+
- **Encryption**: Support for DDS security features including encryption and authentication
182+
183+
## Performance Optimization
184+
185+
### Efficient Execution
186+
187+
- **Single-Threaded**: Efficient single-threaded execution model optimized for Node.js
188+
- **Event Loop Integration**: Seamless integration with Node.js event loop
189+
- **Memory Efficiency**: Optimized memory usage with minimal overhead
190+
- **Zero-Copy Operations**: Support for zero-copy message passing where possible
191+
192+
### Scalability
193+
194+
- **Multiple Nodes**: Support for multiple nodes in a single process
195+
- **High-Frequency Operations**: Optimized for high-frequency publishing and subscription
196+
- **Large Message Support**: Efficient handling of large message payloads
197+
- **Connection Management**: Automatic connection management and optimization
198+
199+
---
200+
201+
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).

0 commit comments

Comments
 (0)