Developer Documentation

Everything you need to connect your robots to VnRobo Fleet Monitor.

Get Started in 2 Minutes

Install the agent, connect your robot, see it on your dashboard.

1. Install the agent

vnrobo-agent is a lightweight Python package. Only requires requests.

bash

pip install vnrobo-agent

2. Connect from Python

Initialize the agent with your API key and robot ID. Heartbeats are sent automatically in the background.

python

from vnrobo_agent import VnRoboAgent

agent = VnRoboAgent(
    api_key="your-api-key",
    robot_id="your-robot-id",
    interval=60  # heartbeat every 60 seconds
)
agent.start()

3. Or use the CLI

For quick testing or non-Python environments, use the CLI directly.

bash

vnrobo-agent start \
  --api-key=vnr_prod_xxxx \
  --robot-id=AMR-01 \
  --interval=60

REST API Reference

All endpoints use JSON. Base URL: https://app.vnrobo.com

Authentication

Pass your organization ID in the X-Org-Id header. Get your org ID from the dashboard settings.

bash

curl -H "X-Org-Id: org_xxxxx" \
     https://app.vnrobo.com/api/robots

Register a new robot in your fleet.

POST/api/robots

bash

curl -X POST https://app.vnrobo.com/api/robots \
  -H "X-Org-Id: org_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "AMR-01", "serialNumber": "SN-001", "model": "Unitree Go2"}'

Get all robots in your organization.

GET/api/robots

bash

curl https://app.vnrobo.com/api/robots \
  -H "X-Org-Id: org_xxxxx"

Send a heartbeat from a robot. Include status, battery, and location.

POST/api/robots/{id}/heartbeat

bash

curl -X POST https://app.vnrobo.com/api/robots/1/heartbeat \
  -H "X-Org-Id: org_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "online", "batteryLevel": 85, "latitude": "21.028", "longitude": "105.854"}'

Python SDK (vnrobo-agent)

pip install vnrobo-agent — works with Python 3.8+, single dependency (requests).

Initialize the agent

python

from vnrobo_agent import VnRoboAgent

# Initialize
agent = VnRoboAgent(
    api_key="your-api-key",
    robot_id="robot-01",
    endpoint="https://app.vnrobo.com/api/heartbeat",
    interval=60,
)

# Start background heartbeat (sends every 60s)
agent.start()

# Send custom data
agent.send_heartbeat(
    status="busy",
    battery=72,
    location={"lat": 21.028, "lng": 105.854},
    metadata={"task": "pick-and-place", "cycle": 142}
)

# Stop when shutting down
agent.stop()

Environment Variables

bash

export VNROBO_API_KEY=your-api-key
export VNROBO_ROBOT_ID=robot-01

# Then in Python:
agent = VnRoboAgent()  # reads from env

ROS 2 Integration

Subscribe to ROS 2 topics and forward data to VnRobo. Works with any ROS 2 distribution (Humble, Iron, Jazzy).

Full ROS 2 node example

python

import rclpy
from rclpy.node import Node
from sensor_msgs.msg import BatteryState
from vnrobo_agent import VnRoboAgent

class VnRoboNode(Node):
    def __init__(self):
        super().__init__('vnrobo_heartbeat')
        self.agent = VnRoboAgent(
            api_key="your-key",
            robot_id="ros2-robot-01",
            interval=30,
        )
        self.agent.start()

        # Subscribe to battery topic
        self.create_subscription(
            BatteryState, '/battery_state',
            self.battery_cb, 10
        )

    def battery_cb(self, msg):
        self.agent.send_heartbeat(
            battery=int(msg.percentage * 100),
            status="online",
        )

    def destroy_node(self):
        self.agent.stop()
        super().destroy_node()

def main():
    rclpy.init()
    node = VnRoboNode()
    rclpy.spin(node)
    node.destroy_node()
    rclpy.shutdown()