附录1 — Yanshee Robot SDK API 使用说明
本文档是开发优必选机器人(Yanshee)应用程序的用户使用指南。第三方开发者可以通过接入SDK控制机器人的各舵机转动和读传感器值，还集成人脸识别和手势识别等。本文主要描述SDK的使用方法，用于指导开发人员快速进行基于Python/JAVA/JS等语言的应用开发。
def ubtGetSWVersion( Type, Version, VersionLen)
获取机器的硬件版本信息
整型数值型: 0 为STM32 app版本；1~20为舵机版本；30：为SDK版本；31：为Raspberry APP版本
字符串类型: 对应的版本信息字符串，最长为20Byte
整型数值型: 版本字符串长度，最大为20Byte
整型数值型: 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 108--语音识别失败 109--语音识别语法错误 110--解码AIUI信息失败；
同步
def ubtGetRobotStatus(Type, Status)
获取机器的状态信息
整型数值型 1 为播放状态（Status：2 暂停， 1 播放，0空闲）；2 为音量（Status：0—ff）；3 为电量（Status：[0]是否充电（0否，1是），[1-2]电压值(mv，十六进制，高位在前)，[3]电量百分比（取值范围0~100，十六进制）
字符串类型: 返回含义见上面type说明
整型数值型: 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtSetRobotServo(UBTEDU_ROBOTSERVO_T servoAngle, iTime);
控制 单个、多个、所有 舵机的运动
UBTEDU_ROBOTSERVO_T类型: 包含了1到17号舵机的0 – 180度对应角度。
整型； 舵机运行时间，单位为20ms（最小大于10）
整型数值型; 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
此接口举例向前请参考第四节例3部分。 另外，Yanshee机器人正面舵机分布说明图如下：
def ubtGetRobotServo(UBTEDU_ROBOTSERVO_T servoAngle)
回读 单个、多个、所有舵机的角度，直接返回全部舵机角度值，通过类似下面结构来读取：
servoinfo = RobotApi.UBTEDU_ROBOTSERVO_T()
servoinfo.SERVO1_ANGLE
servoinfo.SERVO2_ANGLE
...........................
servoinfo.SERVO17_ANGLE
【servoAngle】 UBTEDU_ROBOTSERVO_T 类型。 0 - 180 对应舵机角度，值为255表示舵机无应答
整型数值型； 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
详情请参考第四部分第4个例子：读取舵机举例。
def ubtSetRobotVolume( Volume )
设置机器人音量
【Volume】整型，音量取值范围0~255
整型数值型; 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtSetRobotMotion(Type, direct, speed, repeat)
控制机器人做局部动作，例如：蹲下、举手、
字符串类型： crouch蹲下、raise 举手、 stretch 伸手、come on招手、wave挥手、bend 弯曲、walk 走路、turn around 转身、head 转动头部、bow鞠躬；
字符串类型： left 左、right右、both双手、front前、back后;
整型： 1/2/3/4/5（五个速度等级，依次更快），默认为3；
整型： 重复次数
整型数值型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtReadSensorValue( Type, Value, ValueLen)
读传感器值（默认读取一个低位地址）
字符串类型： gryo 陀螺仪、environment环境、board板上、infrared红外、 ultrasonic超声波、touch触摸、color颜色、pressure压力、gas气体
根据不同的类型传入不同的值。 返回传感器的值
整型类型： 返回值的长度，其中Type = gryo时Valuelen 值为 96 , environment 时为12，infrared时为4，ultrasonic时为4，touch时为4、pressure为4.
整型数值型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtReadSensorValueByAddr (Type, Addr, SensorValue, ValueLen )
读对应地址的传感器值
字符串类型： gryo 陀螺仪、environment环境、infrared红外、 ultrasonic超声波、touch触摸、pressure压力
整型数值型 需要读取模块的传感器IIC地址
不同传感器不同类型（例如：gyro_sensor = api.UBTEDU_ROBOTGYRO_SENSOR_T()） 返回传感器的值
整型数值型： 返回值的长度，其中Type = gryo时Valuelen 值为 96 , environment 时为12，infrared时为4，ultrasonic为4，touch为4、pressure为4.
整型数值型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtSetRobotLED( Type, Color, Mode)
设置 机器人LED灯
字符串类型：可选如下三种："button" "camera" "mic"
字符串类型： 灯颜色 white-白 red-红 green-绿 blue-蓝 yellow-黄 purple-紫 cyan-青绿；
字符串类型： off-关on-常亮 flicker-频闪 breath-呼吸 alternation 轮流
整型数值型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtEventDetect( pcEventType, pcValue, iTimeout)
执行动作文件
字符类型： 要检测事件类型，目前默认只支持button类型；
字符类型： 事件重复次数，0：没有发生 其它是实际发生次数；
整型数值型： 设置事件超时时间，最小10s,最大10min。
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
异步
def ubtStartRobotAction ( Name, repeat)
执行动作文件
字符类型： 动作文件名，例如：push up（俯卧撑）、Victory（胜利）等。另外我们如果自己手机回读编辑了动作文件可以发送到Yanshee机器人来，默认动作文件存储目录为：/usr/local/recv 需要手动拷贝到这个目录下调用：/mnt/1xrobot/res/hts，然后我们就能调用我们自己编辑的动作了，当然也可以通过查看这个目录下所有文件来查看我们都默认内置了哪些动作文件。
整型： 重复次数 0：连续执行 其它是实际次数
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
异步
def ubtStopRobotAction ( )
停止执行动作文件
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtPlayMusic( Type, Name)
执行声音文件,目前接口只支持wav格式。如果想播放MP3文件，可以直接命令行执行：mpg123 aaa.mp3
字符串类型： 动作文件操作类型：play、pause、stop分别表示播放音乐、暂停音乐和停止音乐；
字符串类型： 声音文件名:例如：alarm.wav； 默认wav文件存储目录为：/mnt/1xrobot/res/audio/blockly 举例： RobotApi.ubtPlayMusic(“play” , “alarm.wav”)
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
异步
def ubtVoiceTTS ( isInterrputed, tts)
将文字转成声音播放
整型： 0 不打断前面的语句 1 打断前面的语句
字符串类型： 需要播报的文字信息
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
异步
def ubtDetectVoiceMsg( buf, timeout)
检测是否听到
字符串类型： 文字内容（utf-8编码）
整型： 检测超时时间，最小10s,最大10min;
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtTakeAPhoto( Name， NameLen)
拍一张图片，拍完照图片会被保存到机器人/mnt/1xrobot/tmp目录下。
字符类型： 图标名字，不带后缀（.jpg），如果为空则按照：img_yyyymmdd_hhmmss.jpg
整型数值型： 图片名称长度
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
def ubtVisionDetect ( Type, Value, Timeout)
检测是否看到人脸或者人手并返回人脸或人手个数。
字符串类型： 检测类型，取值：face 人脸，hand 手;
字符串类型： 返回检测到的人脸个数或者人手个数
整型： 检测超时时间，最小10s,最大10min;
整型： 0 -- 操作成功 1-- 操作失败 2--资源缺失 3--发现失败 4--参数错误 5--忽略该返回值 100--网络socket错误 101--发消息为空 102--接收消息超时 103--编码消息失败 104--解码消息失败 105--编码消息错误 106--解码消息错误 107--发送消息超时 ；
同步
我们开发时候只需要修改虚线部分以内的代码即可。（如下图中红色方框部分）
这句话的意思是让机器人举左手，速度为3，重复1次。请参考上一节局部动作控制API接口说明。 这里我们的Type填写的是raise，direct填的是left，speed写的3，Repeat写的1。 这样就实现了一个简单的机器人举左手一次的动作。
#!/usr/bin/python
# _*_ coding: utf-8 -*-
import RobotApi
import time
#------------------------------Connect--------------------
RobotApi.ubtRobotInitialize()
ret=RobotApi.ubtRobotConnect("sdk","1", "127.0.0.1")
if (0 != ret):
print ("Error --> ubtRobotConnect return value: %d" % ret)
exit(1)
#----------------------- block program start ----------------------
infrared_sensor = RobotApi.UBTEDU_ROBOTINFRARED_SENSOR_T()
ret = RobotApi.ubtReadSensorValue("infrared",infrared_sensor,4)
if ret != 0:
print("Can not read Sensor value. Error code: %d" % (ret))
else:
print("Read Sensor Value: %d" % (infrared_sensor.iValue))
#----------------------- block program end ----------------------
RobotApi.ubtRobotDisconnect("SDK","1","127.0.0.1")
RobotApi.ubtRobotDeinitialize()
#!/usr/bin/python
# -*- coding: utf-8 -*-
import RobotApi
RobotApi.ubtRobotInitialize()
ret=RobotApi.ubtRobotConnect("sdk","1", "127.0.0.1")
if (0 != ret):
print ("Error --> ubtRobotConnect return value: %d" % ret)
exit(1)
#----------------------- block program start ----------------------
servoinfo = RobotApi.UBTEDU_ROBOTSERVO_T()
#set servo2 = 60°,servo3 = 40°
servoinfo.SERVO2_ANGLE = 60
servoinfo.SERVO3_ANGLE = 40
ret = RobotApi.ubtSetRobotServo(servoinfo, 20)
#----------------------- block program end ----------------------
RobotApi.ubtRobotDisconnect("sdk", "1", "127.0.0.1")
RobotApi.ubtRobotDeinitialize()
#!/usr/bin/python
# -*- coding: utf-8 -*-
import RobotApi
RobotApi.ubtRobotInitialize()
ret=RobotApi.ubtRobotConnect("sdk","1", "127.0.0.1")
if (0 != ret):
print ("Error --> ubtRobotConnect return value: %d" % ret)
exit(1)
#----------------------- block program start ----------------------
servoinfo = RobotApi.UBTEDU_ROBOTSERVO_T()
ret = RobotApi.ubtGetRobotServo(servoinfo)
print "servoinfo.SERVO1_ANGLE = %d" %(servoinfo.SERVO1_ANGLE)
print "servoinfo.SERVO2_ANGLE = %d" %(servoinfo.SERVO2_ANGLE)
print "servoinfo.SERVO3_ANGLE = %d" %(servoinfo.SERVO3_ANGLE)
print "servoinfo.SERVO17_ANGLE = %d" %(servoinfo.SERVO17_ANGLE)
#----------------------- block program end ----------------------
RobotApi.ubtRobotDisconnect("sdk", "1", "127.0.0.1")
RobotApi.ubtRobotDeinitialize()
将这个例1的python文件保存为SDKSampleAction1.py（当然这个文件名可以按照您的喜好任意命名）放到机器人的树莓派目录/home/pi下面，然后执行此文件。
在命令行敲入以下命令 sudo python SDKSampleAction1.py
然后就会看到Yanshee机器人做的相应的动作。如果您想让机器人做其它动作、说话、或者读取传感器数据等，只要您能想到的场景都可以试试调用相应的python接口，完成相应的功能。
注意如果您在执行过程中遇到这个问题：
请先执行下面命令：
export LD_LIBRARY_PATH=$LB_LIBRARY_PATH:/mnt/1xrobot/lib 然后再执行 python SDKSampleAction1.py
#!/usr/bin/python
# -*- coding: utf-8 -*-
import RobotApi
RobotApi.ubtRobotInitialize()
ret=RobotApi.ubtRobotConnect("sdk","1", "127.0.0.1")
if (0 != ret):
print ("Error --> ubtRobotConnect return value: %d" % ret)
exit(1)
#----------------------- block program start ----------------------
#raise_hand
RobotApi.ubtSetRobotMotion("raise", "left", 3, 1)
#----------------------- block program end ----------------------
RobotApi.ubtRobotDisconnect("sdk", "1", "127.0.0.1")
RobotApi.ubtRobotDeinitialize()
非常感谢您的阅读！