Bala2 Module

Bala2 模块是 M5Stack 堆叠模块系列的一部分。该模块通过 I2C 接口与主机通信，内置的微控制器负责电机的 PWM 控制、读取编码器计数，和输出舵机控制信号。

支持以下产品：

UiFlow2 应用示例：

舵机控制

在 UiFlow2 上打开 servo_control_example.m5f2 项目。

控制舵机 0°~180° 来回转动。

UiFlow2 代码块：

示例输出：

无

电机控制

在 UiFlow2 上打开 motor_control_example.m5f2 项目。

运行程序，小车电机先正转，逐步加速至最大速度，然后逐步减速至停止。随后，电机反转，同样逐步加速到最大速度，再逐步减速至停止。最后，小车停止运动，电机速度归零。

UiFlow2 代码块：

示例输出：

无

读取编码器

在 UiFlow2 上打开 read_encoder_example.m5f2 项目。

运行程序，用手转动车轮观察屏幕显示。

UiFlow2 代码块：

示例输出：

无

小车控制

在 UiFlow2 上打开 car_control_example.m5f2 项目。

保存程序到控制器中，侧放小车并开机，等待陀螺仪校准完成后，小车会自动直立保持平衡。随后，它会依次执行左转、右转、前进、后退等动作，最后停止，回到平衡状态。

UiFlow2 代码块：

示例输出：

无

MicroPython 应用示例：

舵机控制

控制舵机 0°~180° 来回转动。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from module import Bala2Module
import time


title0 = None
label_servo1 = None
label_servo1_val = None
module_bala2_0 = None
t_dir = None
last_time = None
angle = None


def setup():
    global title0, label_servo1, label_servo1_val, module_bala2_0, t_dir, last_time, angle
    M5.begin()
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title("Bala2 Servo Control", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)
    label_servo1 = Widgets.Label("Angle:", 54, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
    label_servo1_val = Widgets.Label("0", 125, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
    module_bala2_0 = Bala2Module(0)
    t_dir = True
    angle = 0
    last_time = time.ticks_ms()


def loop():
    global title0, label_servo1, label_servo1_val, module_bala2_0, t_dir, last_time, angle
    M5.update()
    if (time.ticks_diff((time.ticks_ms()), last_time)) > 10:
        last_time = time.ticks_ms()
        angle = angle + 1
        if angle > 180:
            angle = 0
            t_dir = not t_dir
        if t_dir:
            module_bala2_0.set_servo_angle(1, angle)
        else:
            module_bala2_0.set_servo_angle(1, 180 - angle)
        label_servo1_val.setText(str(angle))


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

无

电机控制

运行程序，小车电机先正转，逐步加速至最大速度，然后逐步减速至停止。随后，电机反转，同样逐步加速到最大速度，再逐步减速至停止。最后，小车停止运动，电机速度归零。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from module import Bala2Module
import time


title0 = None
module_bala2_0 = None
i = None


def setup():
    global title0, module_bala2_0, i
    M5.begin()
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title("Bala2 Motor Control", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)

    module_bala2_0 = Bala2Module(0)
    for i in range(1, 1001):
        module_bala2_0.set_motor_speed(i, i)
        time.sleep_ms(10)
    for i in range(1, 1001):
        module_bala2_0.set_motor_speed(1000 - i, 1000 - i)
        time.sleep_ms(10)
    for i in range(1, 1001):
        module_bala2_0.set_motor_speed(0 - i, 0 - i)
        time.sleep_ms(10)
    for i in range(-1000, 1):
        module_bala2_0.set_motor_speed(i, i)
        time.sleep_ms(10)
    module_bala2_0.set_motor_speed(0, 0)


def loop():
    global title0, module_bala2_0, i
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

无

读取编码器

运行程序，用手转动车轮观察屏幕显示。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from module import Bala2Module
import time


title0 = None
label_enc1 = None
label_enc2 = None
label_enc1_val = None
label_enc2_val = None
module_bala2_0 = None
last_time = None
enc_value = None
enc1 = None
enc2 = None


def setup():
    global \
        title0, \
        label_enc1, \
        label_enc2, \
        label_enc1_val, \
        label_enc2_val, \
        module_bala2_0, \
        last_time, \
        enc_value, \
        enc1, \
        enc2
    M5.begin()
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title("Bala2 Encoder Read", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)
    label_enc1 = Widgets.Label("Enc1", 54, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
    label_enc2 = Widgets.Label("Enc2", 208, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
    label_enc1_val = Widgets.Label("0", 50, 125, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
    label_enc2_val = Widgets.Label("0", 202, 125, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
    module_bala2_0 = Bala2Module(0)
    module_bala2_0.set_encoder_value(0, 0)
    last_time = time.ticks_ms()


def loop():
    global \
        title0, \
        label_enc1, \
        label_enc2, \
        label_enc1_val, \
        label_enc2_val, \
        module_bala2_0, \
        last_time, \
        enc_value, \
        enc1, \
        enc2
    M5.update()
    if (time.ticks_diff((time.ticks_ms()), last_time)) > 100:
        last_time = time.ticks_ms()
        enc_value = module_bala2_0.get_encoder_value()
        enc1 = enc_value[0]
        enc2 = enc_value[1]
        label_enc1_val.setText(str(enc1))
        label_enc2_val.setText(str(enc2))


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

无

小车控制

保存程序到控制器中，侧放小车并开机，等待陀螺仪校准完成后，小车会自动直立保持平衡。随后，它会依次执行左转、右转、前进、后退等动作，最后停止，回到平衡状态。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from module import Bala2Module
import time


title0 = None
module_bala2_0 = None
i = None


def setup():
    global title0, module_bala2_0, i
    M5.begin()
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title("Self-Balancing Robot", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)
    module_bala2_0 = Bala2Module(0)
    module_bala2_0.calibrate()
    module_bala2_0.start()
    time.sleep_ms(2000)
    module_bala2_0.set_turn_speed(-100)
    time.sleep_ms(1000)
    module_bala2_0.set_turn_speed(100)
    time.sleep_ms(1000)
    module_bala2_0.set_turn_speed(0)
    time.sleep_ms(2000)
    for i in range(20):
        module_bala2_0.set_angle_pid_target(0 - i)
        time.sleep_ms(100)
    time.sleep_ms(2000)
    for i in range(20):
        module_bala2_0.set_angle_pid_target(i - 20)
        time.sleep_ms(100)
    for i in range(20):
        module_bala2_0.set_angle_pid_target(i)
        time.sleep_ms(100)
    time.sleep_ms(2000)
    for i in range(20):
        module_bala2_0.set_angle_pid_target(20 - i)
        time.sleep_ms(100)
    module_bala2_0.set_angle_pid_target(0)


def loop():
    global title0, module_bala2_0, i
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

无

API应用

Bala2Module

class module.bala2.Bala2Module(timer_id=0)

创建一个 Bala2Module 对象

参数:: timer_id (int) – 定时器 ID 从 0 到 3（使用定时器周期性地调用平衡控制程序）。

UiFlow2 代码块：

MicroPython 代码块：

from module import Bala2Module

module_bala2_0 = Bala2Module(timer_id = 0)

calibrate()

校准传感器

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.calibrate()

set_motor_speed(left, right)

设置电机转速

参数:

left (int) – 左边电机转速，范围：-1023 ~ 1023。
right (int) – 右边电机转速，范围：-1023 ~ 1023。

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_motor_speed(left, right)

set_encoder_value(left, right)

设置编码器数值

参数:

left (int) – 左边电机编码器数值，范围：-2^31 ~ 2^31。
right (int) – 右边电机编码器数值，范围：-2^31 ~ 2^31。

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_encoder_value(left, right)

get_encoder_value()

左、右编码器值以二元组的形式返回。

返回:: 左，右编码器数值
返回类型:: tuple[int, int]

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.get_encoder_value()

set_servo_angle(pos, angle)

设置舵机角度

参数:

pos (int) – 输出通道，范围：1~4。
angle (int) – 舵机角度，范围：0~180。

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_servo_angle(pos, angle)

start()

开始直立平衡控制

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.start()

stop()

停止平衡控制

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.stop()

get_angle()

获取小车倾角

返回:: 小车倾角
返回类型:: int

小车运行 start() 时数据才有效

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.get_angle()

set_angle_pid(kp, ki, kd)

设置角度环 PID 参数

参数:

kp (float) – 比例增
ki (float) – 积分增益
kd (float) – 微分增益

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_angle_pid(kp, ki, kd)

get_angle_pid()

角度环 PID 参数以三元组的形式返回。

返回:: kp, ki, kd parameters
返回类型:: tuple[float, float, float]

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.get_angle_pid()

set_angle_pid_target(angle=0)

设置角度环 PID 控制目标

参数:: angle (float) – 角度环控制目标角度，默认为0。

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_angle_pid_target(angle)

get_angle_pid_target()

获取角度环 PID 控制目标。

返回:: 角度环 PID 控制目标。
返回类型:: float

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.get_angle_pid_target()

set_speed_pid(kp, ki, kd)

设置速度环 PID 控制参数。

参数:

kp (float) – 比例增
ki (float) – 积分增益
kd (float) – 微分增益

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_speed_pid(kp, ki, kd)

get_speed_pid()

速度环 PID 参数以三元组的形式返回。

返回:: kp, ki, kd parameters
返回类型:: tuple[float, float, float]

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.get_speed_pid()

set_speed_pid_target(speed=0)

设置速度环 PID 控制目标。

参数:: speed (float) – 速度环 PID 控制目标，默认为0。

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_speed_pid_target(speed)

get_speed_pid_target()

获取速度环 PID 控制目标。

返回:: 速度环 PID 控制目标。
返回类型:: float

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.get_speed_pid_target()

set_turn_speed(speed)

设置转向速度。

参数:: speed (float) – 左右电机速度偏差。

UiFlow2 代码块：

MicroPython 代码块：

module_bala2_0.set_turn_speed(speed)