Tài liệu Developer

Mọi thứ bạn cần để kết nối robot với VnRobo Fleet Monitor.

Bắt đầu trong 2 phút

Cài agent, kết nối robot, xem trên dashboard.

1. Cài đặt agent

vnrobo-agent là package Python nhẹ. Chỉ cần requests.

bash

pip install vnrobo-agent

2. Kết nối từ Python

Khởi tạo agent với API key và robot ID. Heartbeat được gửi tự động trong 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. Hoặc dùng CLI

Để test nhanh hoặc môi trường không Python, dùng CLI trực tiếp.

bash

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

REST API Reference

Tất cả endpoint dùng JSON. Base URL: https://app.vnrobo.com

Xác thực

Truyền organization ID qua header X-Org-Id. Lấy org ID từ dashboard settings.

bash

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

Đăng ký robot mới vào 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"}'

Lấy tất cả robot trong organization.

GET/api/robots

bash

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

Gửi heartbeat từ robot. Bao gồm status, pin, và vị trí.

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 — hỗ trợ Python 3.8+, 1 dependency duy nhất (requests).

Khởi tạo 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()

Biến môi trường

bash

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

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

Tích hợp ROS 2

Subscribe ROS 2 topics và chuyển tiếp dữ liệu về VnRobo. Hỗ trợ mọi ROS 2 distro (Humble, Iron, Jazzy).

Ví dụ ROS 2 node đầy đủ

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()