Skip to content

M1 回调、数据类型与状态参考 ​

返回文档总览 | SDK 控制流程与任务机制 | M1 SDK 接口参考 | 示例程序与故障排查

回调模型 ​

M1 SDK 使用两类回调:

回调接口接收内容注册函数
IDataCallback传感器、机器人状态、故障、控制权事件、任务状态和充电桩上报SetDataCallback()
IControlCallback机器人对控制命令的应答SetControlCallback()

发送结果、命令应答和动作状态的关系见 M1 SDK 控制流程与任务机制。

回调线程规则 ​

回调函数运行在 SDK I/O 线程中。回调中只做快速的数据复制、校验、状态更新和消息入队:

  • 不要执行长时间计算。
  • 不要执行文件写入、数据库操作或网络请求。
  • 不要在回调中调用同步 SDK 接口。
  • 共享数据使用原子变量、互斥锁或线程安全队列保护。
  • 不要从回调中抛出异常。
  • 耗时工作交给应用程序自己的工作线程。

IDataCallback ​

cpp
class IDataCallback {
public:
    virtual void OnImuData(const ImuData& data) {}
    virtual void OnLuxData(const LuxData& data) {}
    virtual void OnMcData(const MotionData& data) {}
    virtual void OnSpeedData(const SpeedData& data) {}
    virtual void OnJointStateData(const JointStateData& data) {}
    virtual void OnRobotStateData(const RobotState& data) {}
    virtual void OnFaultData(const FaultDatas& data) {}
    virtual void OnControlLost(const ControlLostInfo& info) {}
    virtual void OnControlAvailable(const ControlAvailableInfo& info) {}
    virtual void OnTaskStateData(const TaskStateInfo& info) {}
    virtual void OnDockScanResult(const DockScanResult& result) {}
    virtual void OnDockConnectionResult(const DockConnectionResult& result) {}
    virtual ~IDataCallback() = default;
};
回调触发方式数据
OnImuData开启 IMU 上报后按配置频率触发ImuData
OnLuxData开启光强上报后固定 1 Hz 触发LuxData
OnMcData开启运动数据后固定 50 Hz 触发MotionData
OnSpeedData开启速度上报后按配置频率触发SpeedData
OnJointStateData开启关节状态上报后触发JointStateData
OnRobotStateData机器人主动上报,通常 1 HzRobotState
OnFaultData主动上报当前故障集合FaultDatas
OnTaskStateData任务状态变化时主动上报TaskStateInfo
OnDockScanResult扫描期间上报发现的充电桩DockScanResult
OnDockConnectionResult上报充电桩连接或断开的最终结果DockConnectionResult

控制权事件 ​

回调含义处理建议
OnControlLost当前 SDK 失去控制权立即停止发送普通控制命令
OnControlAvailable控制权重新可申请由应用工作线程调用 TakeControl()

OnControlAvailable() 只表示控制权可用,不表示 SDK 已经获得控制权。实际结果要看 OnTakeControlAck()。

IControlCallback ​

cpp
class IControlCallback {
public:
    virtual void OnSoftEmergencyStop(bool on) {}
    virtual void OnStandUp() {}
    virtual void OnBalanceStandUp() {}
    virtual void OnLieDown() {}
    virtual void OnStair() {}
    virtual void OnCrawl() {}
    virtual void OnCrawlWalk() {}
    virtual void OnClimb() {}
    virtual void OnSlim() {}
    virtual void OnGait() {}
    virtual void OnWalk() {}
    virtual void OnPosControl() {}
    virtual void OnSkWalk() {}
    virtual void OnSand() {}
    virtual void OnReverseHeadTail() {}
    virtual void OnSpeed(int speed_level) {}
    virtual void OnLocked() {}
    virtual void OnFrontLight(bool on) {}
    virtual void OnBackLight(bool on) {}
    virtual void OnAutoModeLight(bool on) {}
    virtual void OnObstacleAvoidance(bool on) {}
    virtual void OnLuxConfig(bool on) {}
    virtual void OnImuConfig(int freq) {}
    virtual void OnMcConfig(bool on) {}
    virtual void OnSpeedReportConfig(bool on, uint32_t frequency) {}
    virtual void OnJointStateConfig(bool on) {}
    virtual void OnDockScanConfig(bool on) {}
    virtual void OnTakeControlAck(const TakeControlAck& ack) {}
    virtual void OnReleaseControlAck(const ReleaseControlAck& ack) {}
    virtual void OnUpdateCameraBitrateAck(const CameraBitrateAck& ack) {}
    virtual void OnDockConnectionAck(const DockConnectionAck& ack) {}
    virtual void OnDockInfo(const DockInfo& info) {}
    virtual void OnSwitchRemote() {}
    virtual void OnSwitchIdle() {}
    virtual void OnStartRechargeTask() {}
    virtual void OnStopRechargeTask() {}
    virtual void OnStartUnDockTask() {}
    virtual void OnStopUnDockTask() {}
    virtual void OnSetPeriphPower(const PowerCtrlAck& ack) {}
    virtual void OnGetPeriphPower(const PowerCtrlAck& ack) {}
    virtual void OnSetLedAutoMode(const LedAutoModeAck& ack) {}
    virtual void OnGetLedAutoMode(const LedAutoModeAck& ack) {}
    virtual void OnSetLedCommand(const LedCommandAck& ack) {}
    virtual ~IControlCallback() = default;
};

应答回调分类 ​

分类回调说明
姿态命令OnStandUp()、OnWalk()、OnLieDown() 等机器人已收到命令,动作完成看状态数据
速度和灯光OnSpeed()、OnFrontLight() 等返回机器人确认的设置值
数据配置OnImuConfig()、OnMcConfig() 等返回生效的配置
控制权OnTakeControlAck()、OnReleaseControlAck()根据 error_code 判断业务结果
相机OnUpdateCameraBitrateAck()返回相机实际码率
充电桩OnDockScanConfig()、OnDockConnectionAck()、OnDockInfo()分别返回扫描开关、连接或断开请求是否受理、充电桩信息
状态和任务OnSwitchRemote()、OnStartRechargeTask() 等命令确认,任务过程看 OnTaskStateData()
电源和 LEDOnSetPeriphPower()、OnSetLedCommand() 等返回设备确认的通道或灯效

Move()、MoveVelocity()、Turn()、ControlHead()、HighLowStance() 和 PosMove() 没有专用控制应答回调,发送结果通过 WriteHandler 获取。

基础类型 ​

TransportProtocol ​

枚举值整数值说明
WebSocket0WebSocket 传输,使用端口 8081
Udp1UDP 传输,使用端口 8082;SDKClient 默认值

DeviceInfo 和 DeviceType ​

cpp
struct DeviceInfo {
    DeviceType device_type = DeviceType::UNKNOWN;
    std::string sn;
};
DeviceType整数值产品类型
UNKNOWN0未识别或尚未取得设备信息
M11中狗轮足
M1F2中狗点足
M1_PRO3中狗轮足 Pro
M1F_PRO4中狗点足 Pro
M1_ULTRA5中狗轮足 Ultra
M1F_ULTRA6中狗点足 Ultra

device_type 来自连接握手,sn 为机器人序列号。连接成功前或断开后,类型可能为 UNKNOWN,序列号可能为空。

传感器数据结构 ​

ImuData ​

cpp
struct ImuData {
    float acc_x, acc_y, acc_z;
    float gyro_x, gyro_y, gyro_z;
    float quat_x, quat_y, quat_z, quat_w;
};

加速度单位为 m/s²,角速度单位为 rad/s。此结构体的四元数字段顺序为 x, y, z, w。

LuxData ​

cpp
struct LuxData {
    float lux;
};

lux 为照度,单位为 lux。

MotionData ​

cpp
struct MotionData {
    float quat[4];
    float v_world[3];
    float position[3];
    float omega_world[3];
    float v_body[3];
    float omega_body[3];
    uint64_t time_stamp;
};
字段内容单位
quat世界姿态四元数 [w, x, y, z]—
v_world世界坐标系速度 [x, y, z]m/s
position世界坐标系位置 [x, y, z]m
omega_world世界坐标系角速度rad/s
v_body机体坐标系速度m/s
omega_body机体坐标系角速度rad/s
time_stamp数据时间戳ns

SpeedData 和 JointStateData ​

cpp
struct SpeedData {
    float x;
    float y;
    float yaw;
};

struct JointStateData {
    std::vector<std::string> names;
    std::vector<double> positions;
    std::vector<double> velocities;
    std::vector<double> efforts;
};
字段含义单位
SpeedData::x前后速度m/s
SpeedData::y左右平移速度m/s
SpeedData::yaw旋转角速度rad/s
JointStateData::positions关节位置rad
JointStateData::velocities关节速度rad/s
JointStateData::efforts关节力矩N·m

JointStateData 的四个数组按照 names 的索引一一对应。

RobotState ​

cpp
struct RobotState {
    double head_angle;
    FillLightStatus front_fill_light;
    FillLightStatus back_fill_light;
    bool auto_mode_light;
    bool obstacle_avoidance;
    bool charging_pile_connected;
    SpeedLevel speed_level;
    EmergencyStatus software_emergency_status;
    EmergencyStatus hardware_emergency_status;
    HeadDirection head_direction;
    MotionStatus motion_status;
    MachineStatus machine_status;
    BatteryData battery;
    Speed speed;
    float mile_data;
    std::unordered_map<std::string, double> joint_temps;
    CtrlSource control_source;
};
字段含义
head_angle头部角度
front_fill_light / back_fill_light前后补光灯状态
auto_mode_light是否启用自动补光
obstacle_avoidance是否开启停障
charging_pile_connected是否连接充电桩
speed_level当前速度档位
software_emergency_status软件急停状态
hardware_emergency_status硬件急停状态
head_direction当前头尾方向
motion_status当前身体姿态或运动状态
machine_status当前机器任务状态
battery双电池数据
speed当前实际速度:前后和平移单位为 m/s,旋转单位为 rad/s
mile_data累计里程,单位 m
joint_temps关节名称到温度的映射,单位 ℃
control_source当前控制来源

motion_status 描述身体姿态;machine_status 描述机器人正在执行的业务,两者不要混用。

RobotState::speed 的结构如下:

cpp
struct Speed {
    double line;         // 前后速度,m/s
    double translation;  // 左右平移速度,m/s
    double angle;        // 旋转角速度,rad/s
};

电池数据 ​

通过 OnRobotStateData() 获取 RobotState::battery。

cpp
struct BatteryData {
    float power1, power2;
    bool present1, present2;
    float voltage1, voltage2;
    float temperature1, temperature2;
    float current1, current2;
    PowerSupplyStatus power_supply_status1;
    PowerSupplyStatus power_supply_status2;
};

字段末尾的 1 和 2 分别表示电池 1 和电池 2。电量为百分比,电压单位为 V,温度单位为 ℃,电流单位为 A。

PowerSupplyStatus ​

枚举值整数值含义
UNKNOWN0未知
CHARGING1充电中
DISCHARGING2放电中
FULL4已充满

故障数据 ​

通过 OnFaultData() 获取当前故障列表。

cpp
struct FaultData {
    FaultCode code;
    FaultLevel level;
    std::string message;
};

using FaultDatas = std::vector<FaultData>;

FaultCode 和 FaultLevel ​

从 SDK v0.2.3 起,FaultCode 的底层类型为 int,直接承载机器人上报的协议故障码。记录告警时可同时保存数字码、FaultData::level 和 message。例如,执行器过流的 message 为 Actuator/OverCurrent。OnFaultData() 可能一次返回多条故障,收到空列表表示当前上报的故障已清除。

FaultCode整数值含义
Unknown0未知故障
SystemClockSanityError1001系统时间跳变
SystemKeyNodeLifecycleError1002关键节点不可达或生命周期状态异常
SystemOptNodeLifecycleError1003可选节点不可达或生命周期状态异常
MotionStateFallError1004检测到机器人跌倒
IMUConnectError1101IMU 连接错误
IMUDataNotUpdated1102IMU 数据更新超时
IMUCrcError1103IMU 数据 CRC 校验失败
ActuatorOffline1201执行器离线
ActuatorDisabled1202执行器禁用
ActuatorTimeout1203执行器控制超时
ActuatorEncoderError1204执行器编码器错误
ActuatorOverVoltage1205执行器过压
ActuatorUndervolt1206执行器欠压
ActuatorOverCurrent1207执行器过流
ActuatorOverSpeed1208执行器超速
ActuatorOverheat1209执行器过热
ActuatorOverTempWarn1210驱动器检测到温度告警
ActuatorOverTempProtect1211驱动器触发过温保护
ActuatorDCOverVoltage1212高速运动引起直流母线过压
PowerControlOffline1301电源控制板离线
PowerControlPowerLow1302电池电量低于 20% 且不低于 10%,可由机器人配置关闭上报
PowerControlPowerEmpty1303电池电量低于 10%
CANBroken1401CAN 总线通信故障
SystemMcBoard…1501–1516运控板 I/O、内存、CPU 使用率、温度和频率诊断
SystemAlgBoard…1517–1532算力板 I/O、内存、CPU 使用率、温度和频率诊断

板卡诊断的逐项码值、协议名称和默认级别见官方故障码参考。

FaultLevel整数值含义
Unknown0未知级别
FatalError1致命错误
Error2错误
Warn3警告

关键状态枚举 ​

MotionStatus ​

枚举值整数值含义
MOTION_STATUS_UNKNOWN0未知
MOTION_STATUS_STAND_UP1站立过程中
MOTION_STATUS_WALK2可移动的站立状态
MOTION_STATUS_BALANCE_STAND3平衡站立
MOTION_STATUS_LIE_DOWN4卧倒
MOTION_STATUS_CRAWL5匍匐
MOTION_STATUS_CRAWL_WALK6匍匐行走
MOTION_STATUS_LOCKED7锁定
MOTION_STATUS_CLIMB8爬高台
MOTION_STATUS_STAIR9登阶
MOTION_STATUS_SLIM10瘦身过窄道
MOTION_STATUS_GAIT11精细步态
MOTION_STATUS_POS_CONTROL13位控
MOTION_STATUS_SK_WALK14同膝行走
MOTION_STATUS_SAND15沙地姿态

MachineStatus ​

枚举值整数值含义
UNKNOWN0未知
IDLE1空闲
REMOTE2远程控制
OTA3OTA 升级
RECHARGE4回充
MAPPING5建图
NAVIGATION6导航
SAFETY7安全保护
SELFTEST8自检
SOFT_SHUTDOWN9软关机
SILENCE10静音待机
FOLLOW11跟随
TRACK12跟踪
UNDOCK13离桩
DOCK_CALIBRATION14充电桩标定
ESTOP15急停
FALL16摔倒
LOCAL_REMOTE17本地遥控
LOW_LEVEL18低层控制

其他状态枚举 ​

类型枚举值整数值含义
FillLightStatusFILL_LIGHT_STATUS_UNKNOWN0未知
FillLightStatusFILL_LIGHT_STATUS_ON1补光灯开启
FillLightStatusFILL_LIGHT_STATUS_OFF2补光灯关闭
SpeedLevelSPEED_LEVEL_UNKNOWN0未知档位
SpeedLevelSPEED_LEVEL_SLOW1低速
SpeedLevelSPEED_LEVEL_MEDIUM2中速
SpeedLevelSPEED_LEVEL_HIGH3高速
EmergencyStatusEMERGENCY_STATUS_UNKNOWN0未知
EmergencyStatusEMERGENCY_STATUS_RECOVER1急停解除
EmergencyStatusEMERGENCY_STATUS_STOP2急停触发
HeadDirectionHEAD_DIRECTION_UNKNOWN0未知方向
HeadDirectionHEAD_DIRECTION_HEAD1头部为前方
HeadDirectionHEAD_DIRECTION_TAIL2尾部为前方
CtrlSourceCTRL_SOURCE_UNKNOWN0未知控制来源
CtrlSourceCTRL_SOURCE_APP1App 控制
CtrlSourceCTRL_SOURCE_SDK2SDK 控制
CtrlSourceCTRL_SOURCE_OTHER3其他来源控制

任务状态 ​

cpp
struct TaskStateInfo {
    TaskType task_type;
    TaskStatus task_status;
    std::string phase;
    uint32_t error_code;
};
字段含义
task_type任务类型
task_status任务状态
phase可选的任务子阶段,可能为空
error_code0 表示成功,非 0 表示失败

回充阶段依次包括 recharge_preparing(准备)、recharge_docking(对准与入桩)、recharge_charging(充电)和 recharge_completed(充满后留桩)。离桩阶段包括 undock_preparing(准备)、undock_undocking(离桩中)和 undock_completed(离桩完成)。应用可用 phase 展示进度,并以 task_status 判断任务结果。

类型枚举值整数值
TaskTypeUNKNOWN0
TaskTypeSCAN_QR1
TaskTypeMAPPING2
TaskTypeNAV3
TaskTypeRECHARGING4
TaskTypeUNDOCK5
TaskTypeUWB_FOLLOW6
TaskTypeVISUAL_TRACK7
TaskStatusUNKNOWN0
TaskStatusSTARTING1
TaskStatusRUNNING2
TaskStatusSUCCESS3
TaskStatusFAILURE4
TaskStatusSTOPPED5

任务状态变化时通过 OnTaskStateData() 上报。充电与离桩任务的状态判断流程见 M1 SDK 控制流程与任务机制。

回充与离桩业务错误码 ​

收到 task_status == TaskStatus::FAILURE 时,按 task_type 查找 TaskStateInfo::error_code。回充(RECHARGING)的码值范围为 0x11000~0x11FFF,离桩(UNDOCK)为 0x16000~0x16FFF。排查时保留原始码值,并记录失败阶段 phase(如有)。接口调用返回的 std::error_code 见 SDK 接口参考。

回充错误码枚举含义
0x11000ARC_UNKNOWN未知回充异常
0x11001ARC_CALIBRATION_FILE_INVALID相机标定文件无效
0x11002ARC_LOCALIZATION_CHECK_FAILED感知模块未通过检查
0x11003ARC_NAV_ALIGNMENT_CHECK_FAILED对准模块未通过检查
0x11004ARC_DOCK_START_TASK_FAILED保留码,当前流程不上报
0x11005ARC_STAND_UP_FAILED机器人未能站起
0x11006ARC_LOCALIZATION_START_FAILED无法启动感知模块
0x11007ARC_NAV_ALIGNMENT_START_FAILED无法启动对准任务
0x11008ARC_NAV_ALIGNMENT_FAILED入桩过程中对准失败
0x11009ARC_DOCK_CONTACT_FAILED未能确认与充电桩接触
0x1100AARC_DOCK_CHARGING_START_FAILED充电桩未能开始充电
0x1100BARC_CHARGING_STATE_LOST未能继续接收充电状态
0x1100CARC_CHARGING_DOCK_FAULT充电期间桩端报故障
0x1100DARC_CHARGING_STATE_INVALID收到异常的充电状态
0x1100EARC_CHARGING_BATTERY_STATE_LOST未能继续接收电池状态
0x1100FARC_DOCK_COMMAND_ACK_FAILED充电桩命令应答失败
0x11010ARC_LOCALIZATION_RUNTIME_IMAGE_INVALID感知期间收到无效图像
0x11011ARC_LOCALIZATION_RUNTIME_TARGET_TAG_TIMEOUT等待目标 AprilTag 超时
0x11012ARC_LOCALIZATION_RUNTIME_TAG_POSE_FAILED无法计算 AprilTag 位姿
0x11013ARC_LOCALIZATION_RUNTIME_DOCK_POSE_FAILED无法计算充电桩位姿
0x11014ARC_LOCALIZATION_RUNTIME_UNKNOWN感知期间发生未知错误
0x11015ARC_LOCALIZATION_RUNTIME_DUPLICATE_TARGET_TAG检测到重复的目标 AprilTag
0x11016ARC_NAV_ALIGNMENT_STOP_FAILED重试接触时未能停止对准
离桩错误码枚举含义
0x16000UNDOCK_UNKNOWN未知离桩异常
0x16001UNDOCK_STAND_UP_FAILED离桩前未能站起
0x16002UNDOCK_STOP_CHARGING_FAILED无法停止充电
0x16003UNDOCK_LOCALIZATION_START_FAILED无法启动离桩感知
0x16004UNDOCK_NAV_ALIGNMENT_START_FAILED无法启动离桩对准任务
0x16005UNDOCK_NAV_ALIGNMENT_FAILED离桩过程中对准失败
0x16006UNDOCK_CALIBRATION_FILE_INVALID相机标定文件无效
0x16007UNDOCK_FILL_LIGHT_FAILED无法操作补光灯
0x16008UNDOCK_LOCALIZATION_QR_NOT_DETECT未检测到二维码
0x16009UNDOCK_LOCALIZATION_CHECK_FAILED感知模块未通过通信检查
0x1600AUNDOCK_NAV_ALIGNMENT_CHECK_FAILED对准模块未通过通信检查
0x1600BUNDOCK_LOCALIZATION_RUNTIME_IMAGE_INVALID离桩感知期间收到无效图像
0x1600CUNDOCK_LOCALIZATION_RUNTIME_TAG_POSE_FAILED无法计算 AprilTag 位姿
0x1600DUNDOCK_LOCALIZATION_RUNTIME_DOCK_POSE_FAILED无法计算充电桩位姿
0x1600EUNDOCK_LOCALIZATION_RUNTIME_UNKNOWN离桩感知期间发生未知错误
0x1600FUNDOCK_LOCALIZATION_RUNTIME_DUPLICATE_TARGET_TAG检测到重复的目标 AprilTag
0x16010UNDOCK_DETECT_OBSTACLE_FAILED检测到障碍物,离桩失败

见 GitHub 业务错误码表。

充电桩数据 ​

类型字段用途
DockScanDevicename、address、rssi、connectable、service_uuids扫描到的设备名称、BLE 地址、信号强度、可连接标记和服务列表
DockScanResultcode、accepted、scan_active、devices、updated_at_ms扫描状态和设备列表,由 OnDockScanResult() 上报
DockConnectConfigaddress目标充电桩的 BLE MAC 地址
DockConnectionAckcode、accepted、error_code、error_message连接或断开请求的受理结果,由 OnDockConnectionAck() 返回
DockConnectionResultcode、success、error_code连接或断开的最终结果,由 OnDockConnectionResult() 上报
DockInfocode、ble_address、name、dock_sn、dock_version、error_code、error_message查询结果、充电桩标识和错误信息
DockInfodock_connected、has_contact、charging_activeBLE 连接、机械接触和正在充电的状态
DockInfolight_switch_status、fill_light_brightness、auto_fill_light_enabled补光灯开关、亮度和自动补光状态

OnDockInfo() 可在主动查询后返回,也可能在充电桩状态变化时触发。字段类型见官方头文件,调用顺序见充电桩配对流程。

外设与 LED 枚举 ​

类型枚举值整数值含义
PeripheralPowerUNKNOWN0未知电源通道
PeripheralPowerM1_48V148 V 电源通道
PeripheralPowerM1_24V224 V 电源通道
PeripheralPowerM1_12V312 V 电源通道
LedIdUNKNOWN0未知灯分组
LedIdALL1全部状态 LED
LedIdFRONT2前部状态 LED
LedIdBACK3后部状态 LED
LedEffectUNKNOWN0未知灯效
LedEffectOFF1关闭
LedEffectON2常亮
LedEffectBREATH3呼吸
LedEffectBLINK4闪烁
LedEffectBLINK_TRANSIENT5瞬态闪烁

LedColor 的 r/g/b/a 通道范围均为 0 至 255。LedCommand 和 LedCommandAck 包含 id、effect、color、duration_ms;其中 duration_ms 的单位为 ms,表示灯效周期或闪烁间隔。

命令与应答结构 ​

类型主要字段说明
CameraBitrateCmd / CameraBitrateAckcamera_name、camera_bps相机名称和码率,码率单位 bit/s
PowerCtrlCfg / PowerCtrlAckpower、enable电源通道和开关状态
PosControlCmdx/y/z、roll/pitch/yaw位置单位 m,姿态角单位 rad
LedAutoModeAckauto_modetrue 为自动模式,false 为手动模式

控制权应答结构 ​

cpp
struct ControlLostInfo {};
struct ControlAvailableInfo {};

struct TakeControlAck {
    uint32_t error_code;
    std::string reason;
};

struct ReleaseControlAck {
    uint32_t error_code;
    std::string reason;
};

TakeControlAck::error_code == 0 表示控制权申请成功。完整的控制权切换流程见 M1 SDK 控制流程与任务机制。

注册回调示例 ​

cpp
SDKClient client;

auto data_cb = std::make_shared<MyDataCallback>();
auto control_cb = std::make_shared<MyControlCallback>();

client.SetDataCallback(data_cb);
client.SetControlCallback(control_cb);