RobotSDK API 参考

RobotSdkManager

RobotSdkManager 是 RobotSDK 核心入口类，采用单例模式管理机器人连接、状态与指令。

初始化

fun init(
    context: Context,
    lifecycleScope: LifecycleCoroutineScope,
    connection: IRobotConnection,
    robotIp: String = "10.21.33.103",
    robotPort: Int = 30000,
    heartbeatRate: Long = 200L,
    joystickRate: Long = 80L,
    connectTimeOut: Long = 3000L
)

参数	类型	说明
`context`	`Context`	Android Context
`lifecycleScope`	`LifecycleCoroutineScope`	Activity/Fragment 的生命周期协程域
`connection`	`IRobotConnection`	通信连接实例，如 `UdpConnection(JsonProtocolConverter())`
`robotIp`	`String`	机器人 IP，默认 `10.21.33.103`
`robotPort`	`Int`	机器人通信端口，默认 `30000`
`heartbeatRate`	`Long`	心跳发送间隔（毫秒），默认 `200`
`joystickRate`	`Long`	摇杆轴指令发送间隔（毫秒），默认 `80`
`connectTimeOut`	`Long`	连接超时（毫秒），默认 `3000`

示例：

val connection = UdpConnection(JsonProtocolConverter())
RobotSdkManager.init(
    context = this,
    lifecycleScope = lifecycleScope,
    connection = connection,
    robotIp = "10.21.33.103",
    robotPort = 30000
)

连接管理

// 检查连接状态，Socket 异常时自动重建
fun checkConnectStates()

// 主动断开连接
fun disconnect()

// 释放所有 SDK 资源（连接关闭、协程取消）
fun release()

init() 调用后会自动建立连接，无需手动调用 connect()。连接状态可通过 RobotStatesManager.robotConnectStatus LiveData 观察。

状态管理

RobotSDK 使用 Android Jetpack LiveData 暴露机器人状态，在 Activity 或 Fragment 中调用 .observe(this) { ... } 即可实时响应状态变化。

通过 RobotSdkManager.robotStatesManager 访问 16 维状态：

val states = RobotSdkManager.robotStatesManager

states.robotConnectStatus.observe(this) { }
states.motionStateLive.observe(this) { }
states.gaitStateLive.observe(this) { }
states.batteryStatusLive.observe(this) { }
states.motionStatusInfoLive.observe(this) { }
states.motorStatusInfoLive.observe(this) { }
// 更多状态见下方列表

完整状态列表：

LiveData	类型	说明
`robotConnectStatus`	`Boolean`	机器人网络连接状态（true=已连接）
`motionStateLive`	`Int?`	运动状态（1=站立, 2=关节阻尼（软急停）, 4=趴下, 17=RL控制）
`hardwareEmergencyStopStateLive`	`Int?`	硬急停状态（1=急停中，0=正常）
`jointDampingMotionStateLive`	`Boolean`	软急停状态（motionState == 2 的派生值）
`gaitStateLive`	`Int?`	步态类型（0x1001=基础平地, 0x1003=基础楼梯），仅在 RL 控制模式（motionState == 17）下可切换
`errorStatusInfoLive`	`String?`	机器人异常状态消息（JSON 字符串）
`batteryStatusLive`	`List<BatteryStatusInfo?>?`	电池电量信息列表（多电池场景）
`motionStatusInfoLive`	`MotionStatusInfo?`	运动详情（姿态角、速度、高度等）
`motorStatusInfoLive`	`MotorStatusInfo?`	电机/关节状态（各关节角度及轮毂位置）
`temperatureStateLive`	`DeviceTemperatureInfo?`	温度信息（各电机、驱动器温度）
`fillLightStatusLive`	`LedStatusInfo.FillBean?`	补光灯状态（前/后补光灯开关）
`powerManagementStatusLive`	`Int?`	电源管理模式（0=常规（双电池）, 1=单电池模式）
`cpuStatusLive`	`CpuStatusInfo?`	各主机 CPU 状态（AOS/NOS/GOS）
`autoChargeStateLive`	`Int?`	充电状态（0=空闲, 1=前往电桩, 2=充电中, 3=退出电桩, 4=异常, 5=在桩未充电）
`robotModeStateLive`	`Int?`	机器人使用模式（0=手动, 1=导航, 2=辅助）
`deviceEnableStatusLive`	`DeviceEnableStatusInfo?`	设备使能开关状态（雷达、摄像头、GPS 等）

控制使能判断：RobotStatesManager.controlEnable() 扩展函数综合判断当前是否允许发送控制指令（已连接、非急停、非充电中等），并提供了 controlEnableLive 的 LiveData 版本供 UI 绑定使用。

控制指令

// 发送起立指令
fun sendStandUpMsg()

// 发送趴下指令
fun sendSitDownMsg()

// 发送关节阻尼（软急停）指令
fun sendMotionJointsDumpingMsg()

// 发送进入/退出软急停指令
fun sendEnterDampingMode()
fun sendExitDampingMode()

// 发送步态切换指令（需在 RL 控制模式下，即 motionState == 17；gait 取值：0x1001=基础平地, 0x1003=基础楼梯）
fun sendGaitMsg(gait: Int)

// 发送使用模式切换指令（0=手动, 1=导航, 2=辅助）
fun sendChangeRobotUseModeMsg(mode: Int)

// 发送开始/停止/取消充电指令
fun sendStartChargeMsg()
fun sendStopChargeMsg()
fun sendCancelChargeMsg()
fun sendStopExitChargeMsg()
fun sendResetChargeMsg()

// 发送补光灯控制指令（true=开启, false=关闭, null=不控制/保持当前状态）
fun sendFillLightControlMsg(front: Boolean? = null, back: Boolean? = null)

摇杆控制示例：

// 设置轴指令数据提供函数，SDK 每 80ms 自动调用并发送
RobotSdkManager.axisDataProvider = {
    // 返回当前摇杆/虚拟摇杆的 AxisData（值域 -1.0 ~ 1.0）
    AxisData(x = 0.5f, y = 0f, z = 0f, yaw = 0.3f, roll = 0f, pitch = 0f)
}

注意：当前基础步态和楼梯步态下，仅 x、y、yaw 三个轴生效，z、roll、pitch 暂不支持。

自定义消息发送

// 发送自定义协议消息
fun sendCustomMessage(message: Message)

// 原始响应监听（用于接收自定义协议回包）
var onRawResponseListener: ((String) -> Unit)?

自定义消息示例：

val message = RobotProtocol.getMessage(
    type = 1101,
    command = 2,
    items = mapOf("Front" to 1, "Back" to 0)
)
RobotSdkManager.sendCustomMessage(message)

状态判断速查

// 是否已连接
if (RobotStatesManager.isConnect()) { }

// 是否允许控制
if (RobotStatesManager.controlEnable()) { }

// 当前运动姿态
val motionState = RobotStatesManager.motionStateLive.value

// 当前步态
val gait = RobotStatesManager.gaitStateLive.value

// 电量是否充足
val batteries = RobotStatesManager.batteryStatusLive.value
val level = batteries?.firstOrNull()?.BatteryLevel?.toIntOrNull()
if (level != null && level > 20) { }

// 是否存在机器人错误
val hasError = !RobotStatesManager.errorStatusInfoLive.value.isNullOrEmpty()

异常与错误处理

连接异常

连接异常可通过 RobotStatesManager.robotConnectStatus 观察断连，或通过 RobotErrorManager.hasDisConnectError() 判断：

RobotStatesManager.robotConnectStatus.observe(owner) { connected ->
    if (!connected) {
        // 连接断开，检查网络或机器人 IP
    }
}

机器人错误上报

RobotErrorManager.errorListLive.observe(owner) { errors ->
    if (errors.isEmpty()) return@observe
    val latest = errors.last()
    // 根据错误码提示用户或自动处理
    when (latest.code) {
        1001 -> { /* 电机过温 */ }
        1002 -> { /* 关节异常 */ }
        else -> { /* 通用错误提示 */ }
    }
}

控制使能检查

在发送控制指令前，建议检查是否允许控制：

if (!RobotStatesManager.controlEnable()) {
    Toast.makeText(context, "当前状态不可控，请检查机器人模式", Toast.LENGTH_SHORT).show()
    return
}

// 执行控制指令（示例：进入软急停）
RobotSdkManager.sendEnterDampingMode()

状态类型定义

以下是与 RobotStatesManager 各 LiveData 对应的自定义数据类型字段说明。

MotionStatusInfo

运动详情状态，包含姿态角、速度、加速度、高度等信息。

data class MotionStatusInfo(
    var Roll: String? = null,        // 横滚角（Roll），单位度；前视图逆时针为正
    var Pitch: String? = null,       // 俯仰角（Pitch），单位度；左侧视图逆时针为正
    var Yaw: String? = null,         // 偏航角（Yaw），单位度；俯视图逆时针为正
    var OmegaX: String? = null,      // X 轴角速度，单位 rad/s
    var OmegaY: String? = null,      // Y 轴角速度，单位 rad/s
    var OmegaZ: String? = null,      // Z 轴角速度，单位 rad/s
    var AngularZ: String? = null,    // Z 轴角速度（与 OmegaZ 含义相同，旧协议兼容字段）
    var LinearX: String? = null,     // X 方向线速度，单位 m/s
    var LinearY: String? = null,     // Y 方向线速度，单位 m/s
    var AccX: String? = null,        // X 轴加速度，单位 m/s²
    var AccY: String? = null,        // Y 轴加速度，单位 m/s²
    var AccZ: String? = null,        // Z 轴加速度，单位 m/s²
    var Height: String? = null,      // 机身离地高度，单位 m
    var Payload: String? = null,     // 无效值
    var RemainMile: String? = null,  // 预估剩余续航里程，单位 km
    var Gait: String? = null,        // 当前步态
    var MotionState: String? = null  // 当前运动状态
)

所有字段均为 String? 类型，由后端 JSON 直接解析而来，使用时建议按需转换为数值类型。

BatteryStatusInfo

单块电池的状态信息。batteryStatusLive 返回的是列表，支持多电池场景。

data class BatteryStatusInfo(
    var Voltage: String? = null,              // 电池电压，单位 V（如 "48.0"）
    var BatteryLevel: String? = null,         // 电池电量百分比（如 "85"）
    var battery_temperature: String? = null,  // 电池温度，单位 °C
    var charge: Boolean = false,              // 是否正在充电
)

MotorStatusInfo

侧摆、髋、膝关节的实时角度位置（rad）和轮的实时转速（rad/s）。Joint 列表按机器人关节编号顺序存储。

data class MotorStatusInfo(
    var Joint: List<String>? = null,
    var LeftFrontHipX: String? = null,
    var LeftFrontHipY: String? = null,
    var LeftFrontKnee: String? = null,
    var LeftFrontWheel: String? = null,
    var RightFrontHipX: String? = null,
    var RightFrontHipY: String? = null,
    var RightFrontKnee: String? = null,
    var RightFrontWheel: String? = null,
    var LeftBackHipX: String? = null,
    var LeftBackHipY: String? = null,
    var LeftBackKnee: String? = null,
    var LeftBackWheel: String? = null,
    var RightBackHipX: String? = null,
    var RightBackHipY: String? = null,
    var RightBackKnee: String? = null,
    var RightBackWheel: String? = null
)

本文中提及的16个关节顺序，默认为：

[0]LeftFrontHipX, [1]LeftFrontHipY, [2]LeftFrontKnee, [3]LeftFrontWheel,  
[4]RightFrontHipX, [5]RightFrontHipY, [6]RightFrontKnee, [7]RightFrontWheel,  
[8]LeftBackHipX, [9]LeftBackHipY, [10]LeftBackKnee, [11]LeftBackWheel,  
[12]RightBackHipX, [13]RightBackHipY, [14]RightBackKnee, [15]RightBackWheel

DeviceTemperatureInfo

设备温度信息，包含各关节电机及驱动器的实时温度。

data class DeviceTemperatureInfo(
    var Motor: List<String>? = null,   // 各关节电机温度列表（°C）
    var Driver: List<String>? = null   // 各关节驱动器温度列表（°C）
)

温度数据以字符串列表形式上报，顺序对应机器人关节编号。

LedStatusInfo.FillBean

补光灯前后开关状态。fillLightStatusLive 直接暴露 FillBean。

data class FillBean(
    var Front: Int = 0,   // 前补光灯：1=开启，0=关闭
    var Back: Int = 0     // 后补光灯：1=开启，0=关闭
)

CpuStatusInfo

各主机 CPU 状态。
山猫M20内部包含两套计算主机：AOS（运动主机）、NOS（导航主机）。
山猫M20 Pro内部包含三套计算主机：AOS（运动主机）、NOS（导航主机）、GOS（通用主机）。

data class CpuStatusInfo(
    var AOS: CPUBean? = null,   // 运动主机是否处于有效运行状态
    var NOS: CPUBean? = null,   // 导航主机是否处于有效运行状态
    var GOS: CPUBean? = null    // 通用主机是否处于有效运行状态
) {
    data class CPUBean(
        var Temperature: Double = 0.0,   // CPU 最高温度（°C）
        var FrequencyInt: Double = 0.0,  // 小核 CPU 占用率（%）
        var FrequencyApp: Double = 0.0   // 大核 CPU 占用率（%）
    )
}

DeviceEnableStatusInfo

设备使能开关状态，封装雷达、摄像头、GPS、指示灯、负载电源等模块的开关状态。

data class DeviceEnableStatusInfo(
    var FanSpeed: Int = 0,              // 风扇转速
    var LoadPower: Int = 0,             // 外部负载电源：1=开启，0=关闭
    var LedHost: Int = 0,               // 本机电源指示灯（非补光灯）：1=开启，0=关闭
    var LedExt: Int = 0,                // 外部电源指示灯（非补光灯）：1=开启，0=关闭
    var FP: Int = 0,                    // 图传/对频模块：1=开启，0=关闭
    var Lidar: LidarBean? = null,       // 前后雷达电源开关
    var GPS: Int = 0,                   // GPS 模块：1=开启，0=关闭
    var GPSMode: Long = 0L,             // GPS 工作模式位掩码
    var Video: VideoBean? = null        // 前后摄像头电源开关
) {
    data class LidarBean(
        var Front: Int = 0,   // 前雷达：1=开启，0=关闭
        var Back: Int = 0     // 后雷达：1=开启，0=关闭
    )

    data class VideoBean(
        var Front: Int = 0,   // 前摄像头：1=开启，0=关闭
        var Back: Int = 0     // 后摄像头：1=开启，0=关闭
    )
}

补光灯状态不在本类中，由 LedStatusInfo.FillBean 单独管理，通过 fillLightStatusLive 获取。

RobotProtocol

协议层工具类，用于构造自定义协议消息，详见RobotSDK 协议自定义扩展。

// 构造消息
fun getMessage(
    type: Int,
    command: Int,
    items: Map<String, Any>? = null
): Message

示例：

val message = RobotProtocol.getMessage(
    type = 1101,
    command = 2,
    items = mapOf("Front" to 1, "Back" to 0)
)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

RobotSDK API 参考

RobotSdkManager

初始化

连接管理

状态管理

控制指令

自定义消息发送

状态判断速查

异常与错误处理

连接异常

机器人错误上报

控制使能检查

状态类型定义

MotionStatusInfo

BatteryStatusInfo

MotorStatusInfo

DeviceTemperatureInfo

LedStatusInfo.FillBean

CpuStatusInfo

DeviceEnableStatusInfo

RobotProtocol

Uh oh!

FilesExpand file tree

robot-sdk-api-reference.md

Latest commit

History

robot-sdk-api-reference.md

File metadata and controls

RobotSDK API 参考

RobotSdkManager

初始化

连接管理

状态管理

控制指令

自定义消息发送

状态判断速查

异常与错误处理

连接异常

机器人错误上报

控制使能检查

状态类型定义

MotionStatusInfo

BatteryStatusInfo

MotorStatusInfo

DeviceTemperatureInfo

LedStatusInfo.FillBean

CpuStatusInfo

DeviceEnableStatusInfo

RobotProtocol