Squashed 'vendor/ruvector/' content from commit b64c2172
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
337
crates/agentic-robotics-node/README.md
Normal file
337
crates/agentic-robotics-node/README.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# agentic-robotics-node
|
||||
|
||||
[](https://crates.io/crates/agentic-robotics-node)
|
||||
[](https://docs.rs/agentic-robotics-node)
|
||||
[](../../LICENSE)
|
||||
[](https://www.npmjs.com/package/agentic-robotics)
|
||||
|
||||
**Node.js/TypeScript bindings for Agentic Robotics**
|
||||
|
||||
Part of the [Agentic Robotics](https://github.com/ruvnet/vibecast) framework - high-performance robotics middleware with ROS2 compatibility.
|
||||
|
||||
## Features
|
||||
|
||||
- 🌐 **TypeScript Support**: Full type definitions included
|
||||
- ⚡ **Native Performance**: Rust-powered via NAPI
|
||||
- 🔄 **Async/Await**: Modern JavaScript async patterns
|
||||
- 📡 **Pub/Sub**: ROS2-compatible topic messaging
|
||||
- 🎯 **Type-Safe**: Compile-time type checking in TypeScript
|
||||
- 🚀 **High Performance**: 540ns serialization, 30ns messaging
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install agentic-robotics
|
||||
# or
|
||||
yarn add agentic-robotics
|
||||
# or
|
||||
pnpm add agentic-robotics
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### TypeScript
|
||||
|
||||
```typescript
|
||||
import { Node, Publisher, Subscriber } from 'agentic-robotics';
|
||||
|
||||
// Create a node
|
||||
const node = new Node('robot_node');
|
||||
|
||||
// Create publisher
|
||||
const pubStatus = node.createPublisher<string>('/status');
|
||||
|
||||
// Create subscriber
|
||||
const subCommands = node.createSubscriber<string>('/commands');
|
||||
|
||||
// Publish messages
|
||||
pubStatus.publish('Robot initialized');
|
||||
|
||||
// Subscribe to messages
|
||||
subCommands.onMessage((msg) => {
|
||||
console.log('Received command:', msg);
|
||||
});
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
|
||||
```javascript
|
||||
const { Node } = require('agentic-robotics');
|
||||
|
||||
const node = new Node('robot_node');
|
||||
|
||||
const pubStatus = node.createPublisher('/status');
|
||||
pubStatus.publish('Robot active');
|
||||
|
||||
const subSensor = node.createSubscriber('/sensor');
|
||||
subSensor.onMessage((data) => {
|
||||
console.log('Sensor data:', data);
|
||||
});
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Autonomous Navigator
|
||||
|
||||
```typescript
|
||||
import { Node } from 'agentic-robotics';
|
||||
|
||||
interface Pose {
|
||||
x: number;
|
||||
y: number;
|
||||
theta: number;
|
||||
}
|
||||
|
||||
interface Velocity {
|
||||
linear: number;
|
||||
angular: number;
|
||||
}
|
||||
|
||||
const node = new Node('navigator');
|
||||
|
||||
// Subscribe to current pose
|
||||
const subPose = node.createSubscriber<Pose>('/robot/pose');
|
||||
|
||||
// Publish velocity commands
|
||||
const pubCmd = node.createPublisher<Velocity>('/cmd_vel');
|
||||
|
||||
// Navigation logic
|
||||
subPose.onMessage((pose) => {
|
||||
const target = { x: 10, y: 10 };
|
||||
const cmd = computeVelocity(pose, target);
|
||||
pubCmd.publish(cmd);
|
||||
});
|
||||
|
||||
function computeVelocity(current: Pose, target: { x: number; y: number }): Velocity {
|
||||
const dx = target.x - current.x;
|
||||
const dy = target.y - current.y;
|
||||
const distance = Math.sqrt(dx * dx + dy * dy);
|
||||
const targetAngle = Math.atan2(dy, dx);
|
||||
const angleError = targetAngle - current.theta;
|
||||
|
||||
return {
|
||||
linear: Math.min(distance * 0.5, 1.0),
|
||||
angular: angleError * 2.0,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Vision Processing
|
||||
|
||||
```typescript
|
||||
import { Node } from 'agentic-robotics';
|
||||
|
||||
interface Image {
|
||||
width: number;
|
||||
height: number;
|
||||
data: Uint8Array;
|
||||
}
|
||||
|
||||
interface Detection {
|
||||
label: string;
|
||||
confidence: number;
|
||||
bbox: { x: number; y: number; w: number; h: number };
|
||||
}
|
||||
|
||||
const node = new Node('vision_node');
|
||||
|
||||
const subImage = node.createSubscriber<Image>('/camera/image');
|
||||
const pubDetections = node.createPublisher<Detection[]>('/detections');
|
||||
|
||||
subImage.onMessage(async (image) => {
|
||||
const detections = await detectObjects(image);
|
||||
pubDetections.publish(detections);
|
||||
});
|
||||
|
||||
async function detectObjects(image: Image): Promise<Detection[]> {
|
||||
// Your ML inference here
|
||||
return [
|
||||
{ label: 'person', confidence: 0.95, bbox: { x: 100, y: 100, w: 50, h: 100 } },
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Robot Coordination
|
||||
|
||||
```typescript
|
||||
import { Node } from 'agentic-robotics';
|
||||
|
||||
class RobotAgent {
|
||||
private node: Node;
|
||||
private id: string;
|
||||
|
||||
constructor(id: string) {
|
||||
this.id = id;
|
||||
this.node = new Node(`robot_${id}`);
|
||||
|
||||
// Subscribe to team status
|
||||
const subTeam = this.node.createSubscriber<TeamStatus>('/team/status');
|
||||
subTeam.onMessage((status) => this.onTeamUpdate(status));
|
||||
|
||||
// Publish own status
|
||||
const pubStatus = this.node.createPublisher<RobotStatus>(`/robot/${id}/status`);
|
||||
setInterval(() => {
|
||||
pubStatus.publish({
|
||||
id: this.id,
|
||||
position: this.getPosition(),
|
||||
battery: this.getBatteryLevel(),
|
||||
});
|
||||
}, 100);
|
||||
}
|
||||
|
||||
private onTeamUpdate(status: TeamStatus) {
|
||||
console.log(`Robot ${this.id} received team update:`, status);
|
||||
// Coordinate with other robots
|
||||
}
|
||||
|
||||
private getPosition() {
|
||||
return { x: 0, y: 0, z: 0 };
|
||||
}
|
||||
|
||||
private getBatteryLevel() {
|
||||
return 95;
|
||||
}
|
||||
}
|
||||
|
||||
// Create robot swarm
|
||||
const robots = [
|
||||
new RobotAgent('scout_1'),
|
||||
new RobotAgent('scout_2'),
|
||||
new RobotAgent('worker_1'),
|
||||
];
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Node
|
||||
|
||||
```typescript
|
||||
class Node {
|
||||
constructor(name: string);
|
||||
|
||||
createPublisher<T>(topic: string): Publisher<T>;
|
||||
createSubscriber<T>(topic: string): Subscriber<T>;
|
||||
|
||||
shutdown(): void;
|
||||
}
|
||||
```
|
||||
|
||||
### Publisher
|
||||
|
||||
```typescript
|
||||
class Publisher<T> {
|
||||
publish(message: T): Promise<void>;
|
||||
getTopic(): string;
|
||||
}
|
||||
```
|
||||
|
||||
### Subscriber
|
||||
|
||||
```typescript
|
||||
class Subscriber<T> {
|
||||
onMessage(callback: (message: T) => void): void;
|
||||
getTopic(): string;
|
||||
}
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
The Node.js bindings maintain near-native performance:
|
||||
|
||||
| Operation | Node.js | Rust Native | Overhead |
|
||||
|-----------|---------|-------------|----------|
|
||||
| **Publish** | 850 ns | 540 ns | 57% |
|
||||
| **Subscribe** | 120 ns | 30 ns | 4x |
|
||||
| **Serialization** | 1.2 µs | 540 ns | 2.2x |
|
||||
|
||||
Still significantly faster than traditional ROS2 Node.js bindings!
|
||||
|
||||
## Building from Source
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/ruvnet/vibecast
|
||||
cd vibecast
|
||||
|
||||
# Build Node.js addon
|
||||
npm install
|
||||
npm run build:node
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
```
|
||||
|
||||
## TypeScript Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2020",
|
||||
"module": "commonjs",
|
||||
"strict": true,
|
||||
"esModuleInterop": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See the [examples directory](../../examples) for complete working examples:
|
||||
|
||||
- `01-hello-robot.ts` - Basic pub/sub
|
||||
- `02-autonomous-navigator.ts` - A* pathfinding
|
||||
- `06-vision-tracking.ts` - Object tracking with Kalman filters
|
||||
- `08-adaptive-learning.ts` - Experience-based learning
|
||||
|
||||
Run any example:
|
||||
|
||||
```bash
|
||||
npm run build:ts
|
||||
node examples/01-hello-robot.ts
|
||||
```
|
||||
|
||||
## ROS2 Compatibility
|
||||
|
||||
The Node.js bindings are fully compatible with ROS2:
|
||||
|
||||
```typescript
|
||||
// Publish to ROS2 topic
|
||||
const pubCmd = node.createPublisher<Twist>('/cmd_vel');
|
||||
pubCmd.publish({
|
||||
linear: { x: 0.5, y: 0, z: 0 },
|
||||
angular: { x: 0, y: 0, z: 0.1 },
|
||||
});
|
||||
|
||||
// Subscribe from ROS2 topic
|
||||
const subPose = node.createSubscriber<PoseStamped>('/robot/pose');
|
||||
```
|
||||
|
||||
Bridge with ROS2:
|
||||
|
||||
```bash
|
||||
# Terminal 1: Node.js app
|
||||
node my-robot.js
|
||||
|
||||
# Terminal 2: ROS2
|
||||
ros2 topic echo /cmd_vel
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Licensed under either of:
|
||||
|
||||
- Apache License, Version 2.0 ([LICENSE-APACHE](../../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
|
||||
- MIT License ([LICENSE-MIT](../../LICENSE-MIT) or http://opensource.org/licenses/MIT)
|
||||
|
||||
at your option.
|
||||
|
||||
## Links
|
||||
|
||||
- **Homepage**: [ruv.io](https://ruv.io)
|
||||
- **Documentation**: [docs.rs/agentic-robotics-node](https://docs.rs/agentic-robotics-node)
|
||||
- **npm Package**: [npmjs.com/package/agentic-robotics](https://www.npmjs.com/package/agentic-robotics)
|
||||
- **Repository**: [github.com/ruvnet/vibecast](https://github.com/ruvnet/vibecast)
|
||||
|
||||
---
|
||||
|
||||
**Part of the Agentic Robotics framework** • Built with ❤️ by the Agentic Robotics Team
|
||||
Reference in New Issue
Block a user