3.1 底盘控制模块(AGV SDK)
头文件:include/CubeBraidSDK/AGV_SDK/AGV_SDK.h
AGVController 通过 TCP 连接 AGV 控制器,内部维护接收线程和心跳线程。接口支持 C++ 对象方式,也导出以 AGV_Handle 为核心的 C ABI。
3.1.1 AGV 结构与状态通信协议
AGVPose 包含 x、y、z、roll、pitch、yaw 六个 double 字段。仓库 demo 将 roll 和 pitch 输出为 AGV 前方/左侧距离;实际坐标含义应以 AGV 控制器协议和现场坐标系为准。
字段 |
类型 |
含义 |
单位 |
|---|---|---|---|
|
|
空间笛卡尔坐标位置。 |
m / mm |
|
|
横滚角;部分导航协议也将该字段用于前方距离。 |
rad / m |
|
|
俯仰角;部分导航协议也将该字段用于左侧距离。 |
rad / m |
|
|
偏航角或航向角。 |
rad |
目标导航使用 GoalPose,包含 double x、double y 和 double yaw;C ABI 对应 C_GoalPose,字段顺序相同。目标坐标以 AGV 地图坐标系及控制器协议为准,不能直接套用相对位移接口的毫米单位。
通信线程
连接后,AGV 模块通过后台接收线程 receiveLoop 接收 TCP 数据,并由 parseDataStream 完成数据流的拆包与粘包解析;heartbeatLoop 定时调用 sendHeartBeatsMsg 维持系统心跳。断开或销毁对象时应确保这些线程已经停止。
3.1.2 控制模式与运动指令接口
ControlMode 枚举值:
枚举 |
值 |
说明 |
|---|---|---|
|
2 |
手动速度控制。 |
|
3 |
自动位移控制。 |
连接与状态
#include "CubeBraidSDK/AGV_SDK/AGV_SDK.h"
agv_sdk::AGVController agv;
if (!agv.connectAGV("192.168.1.91", 5005)) {
// 处理连接失败
}
if (agv.login("admin", password_hash)) {
agv.switchControlMode(agv_sdk::ControlMode::Auto);
const bool ok = agv.goForward(500.0, 30000);
const auto pose = agv.getPose();
agv.logout();
}
agv.disconnectAGV();
生产环境不要直接使用 demo 中的 IP、用户名或密码哈希。登录接口的第二个参数是已经计算好的 password_hash 字符串,哈希算法和凭据管理不由此接口定义。
运动与状态接口
接口 |
返回值 |
说明 |
|---|---|---|
|
|
建立 TCP 连接并启动后台线程。 |
|
|
停止后台线程并释放连接。 |
|
|
登录 AGV 系统。 |
|
|
注销当前会话。 |
|
|
切换手动或自动模式。 |
|
|
自动模式下阻塞等待前进动作完成,默认超时 30000 ms。 |
|
|
自动模式下阻塞等待位移完成,默认超时 30000 ms。 |
|
|
导航到 |
|
|
导航到已配置的站点编号,任务完成返回 true,超时或中断返回 false。 |
|
|
手动模式发送一次速度指令; |
|
|
持续重发手动速度,结束时发送速度归零;仅 C++ 类接口提供。 |
|
|
主动请求 AGV 系统状态。 |
|
|
手动发送一次心跳;类内部已有心跳线程。 |
|
|
线程安全读取本地缓存位姿。 |
goBack 的正负方向由 AGV 控制器协议定义;仓库 C++/Python demo 使用 +500 表示单步前进、-500 表示单步后退,集成前应在现场确认。
3.1.3 C-API 跨语言封装接口
typedef void* AGV_Handle;
typedef struct {
double x;
double y;
double yaw;
} C_GoalPose;
AGV_Handle AGV_Create();
void AGV_Destroy(AGV_Handle handle);
bool AGV_Connect(AGV_Handle handle, const char* ip, int port);
void AGV_Disconnect(AGV_Handle handle);
bool AGV_Login(AGV_Handle handle, const char* username,
const char* password_hash);
bool AGV_Logout(AGV_Handle handle);
bool AGV_SwitchControlMode(AGV_Handle handle, C_ControlMode mode);
bool AGV_GoForward(AGV_Handle handle, double dist_mm, int timeout_ms);
bool AGV_GoBack(AGV_Handle handle, double dist_mm, int timeout_ms);
bool AGV_NavToPose(AGV_Handle handle, C_GoalPose pose, int timeout_ms);
bool AGV_ToStation(AGV_Handle handle, int stations_num, int timeout_ms);
bool AGV_ManualCtlVelSet(AGV_Handle handle, float vx, float vy, float w);
bool AGV_QuerySystemState(AGV_Handle handle);
bool AGV_SendHeartBeatsMsg(AGV_Handle handle);
C_AGVPose AGV_GetPose(AGV_Handle handle);
3.1.4 C++ 调用例程(agv_sdk_demo.cpp)
下例展示自动前进、位姿读取和手动速度控制的完整调用顺序。示例地址和凭据仅用于说明格式,必须替换为现场安全配置:
agv_sdk::AGVController agv;
if (!agv.connectAGV("192.168.1.91", 5005)) return -1;
if (!agv.login("<username>", "<password_hash>")) return -1;
agv.switchControlMode(agv_sdk::ControlMode::Auto);
agv.querySystemState();
const auto pose = agv.getPose();
agv.goForward(1800.0, 100000);
agv.switchControlMode(agv_sdk::ControlMode::Manual);
agv.moveManualForDuration(100.0f, 0.0f, 0.0f, 2000, 50);
agv.logout();
agv.disconnectAGV();
3.1.5 Python 调用例程(agv_sdk_demo.py)
下面的示例只展示调用顺序。设备地址、用户名和密码哈希必须替换为现场安全配置,不能直接复制到生产程序:
from agv_sdk import AGVClient, ControlMode
def main():
with AGVClient() as agv:
if not agv.connect("192.168.1.91", 5005):
return
if not agv.login("<username>", "<password_hash>"):
return
agv.switch_control_mode(ControlMode.AUTO)
if agv.go_forward(1800.0, timeout_ms=100000):
print("前进到达指定位置")
print(agv.get_pose())
agv.switch_control_mode(ControlMode.MANUAL)
agv.move_manual_for_duration(
vx=100.0, vy=0.0, w=0.0,
duration_s=2, interval_s=0.1)
if __name__ == "__main__":
main()
目标点与站点导航
在连接、登录并进入自动模式后,C++ 可调用 navToPose(GoalPose{x, y, yaw}, timeout_ms) 或 navToStation(stations_num, timeout_ms)。Python 封装提供 C_GoalPose、navToPose 和 toStation,名称大小写与仓库保持一致:
from agv_sdk import C_GoalPose
def navigate_to_target(agv, x, y, yaw, timeout_ms=30000):
goal = C_GoalPose(x=x, y=y, yaw=yaw)
return agv.navToPose(goal, timeout_ms=timeout_ms)
def navigate_to_station(agv, station_number, timeout_ms=30000):
return agv.toStation(station_number, timeout_ms=timeout_ms)
这两个函数接收已连接、登录且处于自动模式的 AGVClient。站点编号须与 AGV 已配置的地图一致。