Skip to main content

API手册

前言​

pyBalance 的 API 主要包括传感器校准、平衡控制、运动控制和状态读取等功能，这些功能均通过 BALANCE 对象进行调用。使用相关 API 前，需要先创建 BALANCE 对象。

BALANCE 对象​

构造函数​

b = pyBalance.BALANCE()

构建pyBalance对象。

使用方法​

read_cal_data()​

b.read_cal_data()

获取当前校准数据。函数连续采集 20 次传感器数据并计算平均值，返回以下两个数据：

  • 倾斜角度平均值：根据加速度计 X、Z 轴数据计算得到的 Pitch（俯仰角）平均值，范围为 -1800 ~ 1800，返回值放大 10 倍以保留 1 位小数。
  • 陀螺仪原始平均值：陀螺仪 Y 轴（GY）原始数据的平均值，理论范围为 -327680 ~ 327670，返回值同样放大 10 倍以保留 1 位小数。

confirm_cal()​

b.confirm_cal()

确认并保存当前校准数据。将 b.read_cal_data() 获取的倾斜角度平均值和角速度原始平均值写入 cal_data.txt 文件，作为小车的校准参数。下次开机时会自动读取该文件，并使用保存的参数进行校准

cal_states()​

b.cal_states()

获取当前校准状态，用于判断小车上电后是否成功加载校准数据。

  • 1: 已成功读取 cal_data.txt 中的校准数据，校准已生效。
  • 0 : 未找到 cal_data.txt，或文件中的校准数据不完整，校准未生效。

start()​

b.start()

启动平衡控制，使能电机输出。调用后，小车进入自平衡工作状态。

stop()​

b.stop()

停止平衡控制，关闭电机输出，用于突发情况停止或结束运行。

speed()​

b.speed(value=5)

设置小车运动控制的输出档位，范围为 [1, 5]，默认为 5。数值越大，控制前进、后退和转向时的电机输出越大，小车运动速度越快；数值越小，输出越小，运动速度越慢。该参数只影响小车的运动控制，不影响直立平衡控制本身。

control()​

b.control(pit=0, yaw=0)

控制平衡小车的前后运动和左右转向，其实际运动输出会受到 b.speed() 设置的运动控制档位影响。

  • pit：前后运动控制量，范围为 -100 ~ 100。正值控制小车前进，负值控制小车后退，绝对值越大，前后运动的目标输出越大。
  • yaw：左右转向控制量，范围为 -100 ~ 100。正值控制小车向右转动，负值控制小车向左转动，绝对值越大，转向的目标输出越大。

read_states()​

b.read_states()

读取平衡小车状态信息。返回8个数据的元组。

  1. 倾斜角：范围为 -1800 ~ 1800，实际角度放大 10 倍。

  2. 实时速度：小车当前运动速度，单位为 mm/s。

  3. 超声波距离：当前超声波测距值，单位为 mm，范围约为 20 ~ 4500 mm。

  4. 电池电压：当前电池电压，单位为 10 mV。

  5. 平衡状态：当前平衡控制状态，对应 b.start() 和 b.stop()。1 表示已启动并使能电机输出，0 表示已停止并关闭电机输出。

  6. 运动控制档位：当前运动控制输出档位，范围为 [1, 5]。

  7. PIT 控制量：当前前后运动控制量，对应 b.control() 的 pit 参数，范围为 -100 ~ 100。

  8. YAW 控制量：当前左右转向控制量，对应 b.control() 的 yaw 参数，范围为 -100 ~ 100。