本篇主角长这样
适用于产品: 幻尔科技 uHandPi 树莓派5机械手掌
涉及模块: 树莓派5扩展板A款
一、Board 类初始化
引用扩展板SDK
import ros_robot_controller_sdk as rrc #引用扩展版通讯协议
创建串口通信对象，连接幻尔（Hiwonder）树莓派5扩展板（Servo Board），后续你就可以通过 board 对象发送指令：
board = rrc.Board(device=“/dev/ttyAMA0”, baudrate=1000000, timeout=5)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| device | str | /dev/ttyAMA0 | 串口设备路径 |
| baudrate | int | 1000000 | 波特率 |
| timeout | int | 5 | 串口超时时间（秒） |
-–
二、系统通用接口
2.1 enable_reception(enable=True) — 开启数据接收
调用 `get_imu()`、`get_button()` 等读取接口前，必须先调用此方法开启数据接收。
board.enable_reception() # 开启接收
board.enable_reception(False) # 关闭接收
| 参数 | 类型 | 说明 |
|---|---|---|
| enable | bool | True 开启，False 关闭，默认 True |
-–
2.2 get_battery() — 读取电池电压
返回电池电压值，单位毫伏（mV）；无数据时返回 `None`。需先调用 `enable_reception()`。
示例代码：
board.enable_reception() #开启接收
voltage = board.get_battery() #读取电压存入voltage变量
if voltage is not None: #判断是否有读出电压值，有则打印电压
print(f"电压: {voltage} mV")
| 返回值 | 类型 | 说明 |
|---|---|---|
| 电压值 | int | 单位 mV，例如 7400 表示 7.4V |
| 无数据 | None | 队列为空或未开启接收时返回 |
-–
三、RGB 灯控制
3.1 `set_rgb(pixels)` — 设置 RGB 灯颜色
同时设置一个或多个 RGB 灯的颜色。扩展板上共有 2 颗 RGB 灯，编号为 1、2。
# 1号灯红色，2号灯绿色
board.set_rgb([[1, 255, 0, 0], [2, 0, 255, 0]])
# 所有灯关闭
board.set_rgb([[1, 0, 0, 0], [2, 0, 0, 0]])
# 两灯同时设为黄色
board.set_rgb([[1, 255, 255, 0], [2, 255, 255, 0]])
| 参数 | 类型 | 说明 |
|---|---|---|
| pixels | list | 嵌套列表，每个子列表格式为 [index, R, G, B] |
| index | int | 灯编号，从 1 开始（最大 2） |
| R | int | 红色分量，范围 0~255 |
| G | int | 绿色分量，范围 0~255 |
| B | int | 蓝色分量，范围 0~255 |
-–
四、LED 控制
4.1 set_led(on_time, off_time, repeat=1, led_id=1) — 控制板载 LED 闪烁
board.set_led(0.1, 0.9, 3) # 亮0.1s，灭0.9s，重复3次
board.set_led(0.5, 0.5, 0) # 持续闪烁（repeat=0 表示无限循环）
board.set_led(1.0, 0.0, 1) # 常亮1秒
| 参数 | 类型 | 说明 |
|---|---|---|
| on_time | float | 亮灯时长（秒） |
| off_time | float | 灭灯时长（秒） |
| repeat | int | 重复次数，0 表示无限循环，默认 1 |
| led_id | int | LED 编号，默认 1 |
-–
五、蜂鸣器控制
5.1 set_buzzer(freq, on_time, off_time, repeat=1) — 控制蜂鸣器
board.set_buzzer(1900, 0.1, 0.9, 1) # 1900Hz，响0.1s，停0.9s，执行1次
board.set_buzzer(1000, 0.5, 0.5, 0) # 1000Hz，持续循环
board.set_buzzer(1000, 0.0, 0.0, 1) # 关闭蜂鸣器
| 参数 | 类型 | 说明 |
|---|---|---|
| freq | int | 蜂鸣频率（Hz），常用值 1000~3000 |
| on_time | float | 响声持续时长（秒），0.0 时关闭 |
| off_time | float | 停止时长（秒） |
| repeat | int | 重复次数，0 表示无限循环，默认 1 |
-–
六、直流电机控制
扩展板支持最多 4 路 直流电机，编号 `1~4`。
6.1 `set_motor_duty(dutys)` — 按占空比设置电机速度
board.set_motor_duty([[1, 35]]) # 1号电机35%占空比正转
board.set_motor_duty([[1, -50]]) # 1号电机50%占空比反转
board.set_motor_duty([[1, 35], [2, -35], [3, 35], [4, -35]]) # 同时控制4个电机
board.set_motor_duty([[1, 0], [2, 0], [3, 0], [4, 0]]) # 停止所有电机
| 参数 | 类型 | 说明 |
|---|---|---|
| dutys | list | 嵌套列表，每项格式 [motor_id, duty] |
| motor_id | int | 电机编号，1~4 |
| duty | float | 占空比，范围 -100~100，负值反转，0 停止 |
-–
6.2 `set_motor_speed(speeds)` — 按速度值设置电机
board.set_motor_speed([[1, 0.3], [2, -0.3]]) # 1号正转，2号反转
board.set_motor_speed([[1, 0], [2, 0]]) # 停止
| 参数 | 类型 | 说明 |
|---|---|---|
| speeds | list | 嵌套列表，每项格式 [motor_id, speed] |
| motor_id | int | 电机编号，1~4 |
| speed | float | 速度值，负值反转 |
-–
七、PWM 舵机控制
扩展板支持 4 路 PWM 舵机（从内到外编号 `1~4`），脉宽范围约 `500~2500` μs，中位为 `1500` μs。
7.1 `pwm_servo_set_position(duration, positions)` — 设置 PWM 舵机位置
board.pwm_servo_set_position(0.5, [[1, 1500]]) # 1号舵机到1500，用时0.5s
board.pwm_servo_set_position(1.0, [[1, 1000], [2, 2000]]) # 同时控制1、2号，用时1s
board.pwm_servo_set_position(1.0, [[1, 500]]) # 1号舵机转到最小角度
| 参数 | 类型 | 说明 |
|---|---|---|
| duration | float | 运动时长（秒），值越小速度越快 |
| positions | list | 嵌套列表，每项格式 [servo_id, pulse_width] |
| servo_id | int | 舵机编号，1~4 |
| pulse_width | int | 脉宽值（μs），范围约 500~2500，中位 1500 |
-–
7.2 `pwm_servo_set_offset(servo_id, offset)` — 设置 PWM 舵机偏移
微调舵机中位偏差，用于校准安装误差。
board.pwm_servo_set_offset(1, 10) # 1号舵机正偏移10
board.pwm_servo_set_offset(1, -5) # 1号舵机负偏移5
board.pwm_servo_set_offset(1, 0) # 清除偏移
| 参数 | 类型 | 说明 |
|---|---|---|
| servo_id | int | 舵机编号，1~4 |
| offset | int | 偏移量，有符号整数 |
-–
7.3 `pwm_servo_read_offset(servo_id)` — 读取 PWM 舵机偏移**
注意： 此接口为阻塞调用，会等待串口响应。
offset = board.pwm_servo_read_offset(1)
print("偏移:", offset)
| 参数 | 类型 | 说明 |
|---|---|---|
| servo_id | int | 舵机编号 |
返回值： `int` 当前偏移量
-–
7.4 `pwm_servo_read_position(servo_id)` — 读取 PWM 舵机当前位置
注意： 此接口为阻塞调用，会等待串口响应。
pos = board.pwm_servo_read_position(1)
print("当前脉宽:", pos, "μs")
| 参数 | 类型 | 说明 |
|---|---|---|
| servo_id | int | 舵机编号 |
返回值： `int` 当前脉宽值（μs）
八、总线舵机控制
总线舵机通过半双工串口总线通信，支持位置控制及状态读取。
角度值范围 `0~1000`（对应 0°~240°），舵机 ID 范围 `1~253`，`254` 为广播地址。
8.1 `bus_servo_set_position(duration, positions)` — 设置总线舵机位置
board.bus_servo_set_position(1.0, \[\[1, 500\], \[2, 500\]\]) # 1、2号到500，用时1s
board.bus_servo_set_position(0.5, \[\[1, 0\], \[2, 1000\]\]) # 快速运动到目标位置
board.bus_servo_set_position(2.0, \[\[1, 500\]\]) # 缓慢运动
| 参数 | 类型 | 说明 |
|---|---|---|
| duration | float | 运动时长（秒），值越大越慢 |
| positions | list | 嵌套列表，每项格式 [servo_id, angle] |
| servo_id | int | 舵机 ID，1~253 |
| angle | int | 目标角度值，范围 0~1000 |
-–
8.2 `bus_servo_stop(servo_id)` — 立即停止总线舵机
board.bus_servo_stop([1, 2]) # 同时停止1、2号舵机
board.bus_servo_stop([1]) # 仅停止1号
| 参数 | 类型 | 说明 |
|---|---|---|
| `servo_id` | list | 要停止的舵机 ID 列表 |
-–
8.3 `bus_servo_enable_torque(servo_id, enable)` — 开关舵机扭矩
board.bus_servo_enable_torque(1, True) # 开启扭矩（舵机锁定位置）
board.bus_servo_enable_torque(1, False) # 关闭扭矩（可手动转动舵机）
| 参数 | 类型 | 说明 |
|---|---|---|
| `servo_id` | int | 舵机 ID |
| `enable` | bool | `True` 启用扭矩，`False` 禁用扭矩 |
-–
8.4 `bus_servo_set_id(servo_id_now, servo_id_new)` — 修改舵机 ID
注意： 修改前总线上只能接一颗舵机，否则会造成 ID 冲突。
board.bus_servo_set_id(254, 1) # 将广播地址舵机的 ID 改为 1
board.bus_servo_set_id(1, 2) # 将 1 号改为 2 号
| 参数 | 类型 | 说明 |
|---|---|---|
| `servo_id_now` | int | 当前舵机 ID，`254` 为广播地址 |
| `servo_id_new` | int | 新 ID，范围 `1~253` |
-–
8.5 `bus_servo_set_offset(servo_id, offset)` — 设置舵机角度偏移
board.bus_servo_set_offset(1, -10) # 临时设置偏移为-10
8.6 `bus_servo_save_offset(servo_id)` — 保存偏移到舵机 EEPRO
board.bus_servo_set_offset(1, -10) # 先设置偏移
board.bus_servo_save_offset(1) # 再保存，掉电不丢失
| 参数 | 类型 | 说明 |
|---|---|---|
| `servo_id` | int | 舵机 ID |
| `offset` | int | 偏移量，有符号整数 |
-–
8.7 `bus_servo_set_angle_limit(servo_id, limit)` — 设置角度限制
board.bus_servo_set_angle_limit(1, [0, 1000]) # 全范围
board.bus_servo_set_angle_limit(1, [200, 800]) # 限制在200\~800之间
| 参数 | 类型 | 说明 |
|---|---|---|
| `servo_id` | int | 舵机 ID |
| `limit` | list | `[最小角度, 最大角度]`，范围 `0~1000` |
-–
8.8 `bus_servo_set_vin_limit(servo_id, limit)` — 设置输入电压保护限制
board.bus_servo_set_vin_limit(1, [4500, 14500]) # 限制 4.5V\~14.5V
| 参数 | 类型 | 说明 |
|---|---|---|
| `servo_id` | int | 舵机 ID |
| `limit` | list | `[最低电压(mV), 最高电压(mV)]` |
-–
8.9 `bus_servo_set_temp_limit(servo_id, limit)` — 设置温度保护限制
board.bus_servo_set_temp_limit(1, 85) # 超过 85℃ 触发保护
| 参数 | 类型 | 说明 |
|---|---|---|
| `servo_id` | int | 舵机 ID |
| `limit` | int | 最高温度限制（℃） |
-–
8.10 读取总线舵机状态接口汇总
所有读取接口均为阻塞调用，需确保舵机已连接并调用过 `enable_reception()`。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| `bus_servo_read_id(servo_id=254)` | 舵机 ID（默认广播） | `[id]` | 读取舵机 ID |
| `bus_servo_read_position(servo_id)` | 舵机 ID | `[angle]` (0~1000) | 读取当前角度 |
| `bus_servo_read_vin(servo_id)` | 舵机 ID | `[voltage_mV]` | 读取输入电压（mV） |
| `bus_servo_read_temp(servo_id)` | 舵机 ID | `[temp_℃]` | 读取当前温度（℃） |
| `bus_servo_read_offset(servo_id)` | 舵机 ID | `[offset]` | 读取角度偏移 |
| `bus_servo_read_angle_limit(servo_id)` | 舵机 ID | `[min, max]` | 读取角度限制 |
| `bus_servo_read_vin_limit(servo_id)` | 舵机 ID | `[min_mV, max_mV]` | 读取电压限制 |
| `bus_servo_read_temp_limit(servo_id)` | 舵机 ID | `[temp_℃]` | 读取温度保护值 |
| `bus_servo_read_torque_state(servo_id)` | 舵机 ID | `[state]` | 读取扭矩开关状态 |
示例代码
board.enable_reception()
servo_id = board.bus_servo_read_id()\[0\] # 先读取 ID
print("ID:", board.bus_servo_read_id(servo_id))
print("角度:", board.bus_servo_read_position(servo_id))
print("电压(mV):", board.bus_servo_read_vin(servo_id))
print("温度(℃):", board.bus_servo_read_temp(servo_id))
print("偏移:", board.bus_servo_read_offset(servo_id))
print("角度限制:", board.bus_servo_read_angle_limit(servo_id))
print("电压限制:", board.bus_servo_read_vin_limit(servo_id))
print("温度限制:", board.bus_servo_read_temp_limit(servo_id))
print("扭矩状态:", board.bus_servo_read_torque_state(servo_id))
九、 资源下载
可通过以下途径获取：
官方在线课程与资料库： 幻尔科技官网在线教程
客服领取： 联系你购买设备的店铺客服（淘宝/京东/天猫客服），提供订单号即可免费领取资料。