Bala2 Module

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

支持以下产品：

Bala2

Bala2-Fire

UiFlow2 应用示例：

舵机控制

在 UiFlow2 上打开 servo_control_example.m5f2 项目。

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

UiFlow2 代码块：

servo_control_example.png

示例输出：

无

电机控制

在 UiFlow2 上打开 motor_control_example.m5f2 项目。

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

UiFlow2 代码块：

motor_control_example.png

示例输出：

无

读取编码器

在 UiFlow2 上打开 read_encoder_example.m5f2 项目。

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

UiFlow2 代码块：

read_encoder_example.png

示例输出：

无

小车控制

在 UiFlow2 上打开 car_control_example.m5f2 项目。

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

UiFlow2 代码块：

car_control_example.png

示例输出：

无

MicroPython 应用示例：

舵机控制

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

MicroPython 代码块：

 1# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 2#
 3# SPDX-License-Identifier: MIT
 4
 5import os, sys, io
 6import M5
 7from M5 import *
 8from module import Bala2Module
 9import time
10
11
12title0 = None
13label_servo1 = None
14label_servo1_val = None
15module_bala2_0 = None
16t_dir = None
17last_time = None
18angle = None
19
20
21def setup():
22    global title0, label_servo1, label_servo1_val, module_bala2_0, t_dir, last_time, angle
23    M5.begin()
24    Widgets.fillScreen(0x222222)
25    title0 = Widgets.Title("Bala2 Servo Control", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)
26    label_servo1 = Widgets.Label("Angle:", 54, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
27    label_servo1_val = Widgets.Label("0", 125, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
28    module_bala2_0 = Bala2Module(0)
29    t_dir = True
30    angle = 0
31    last_time = time.ticks_ms()
32
33
34def loop():
35    global title0, label_servo1, label_servo1_val, module_bala2_0, t_dir, last_time, angle
36    M5.update()
37    if (time.ticks_diff((time.ticks_ms()), last_time)) > 10:
38        last_time = time.ticks_ms()
39        angle = angle + 1
40        if angle > 180:
41            angle = 0
42            t_dir = not t_dir
43        if t_dir:
44            module_bala2_0.set_servo_angle(1, angle)
45        else:
46            module_bala2_0.set_servo_angle(1, 180 - angle)
47        label_servo1_val.setText(str(angle))
48
49
50if __name__ == "__main__":
51    try:
52        setup()
53        while True:
54            loop()
55    except (Exception, KeyboardInterrupt) as e:
56        try:
57            from utility import print_error_msg
58
59            print_error_msg(e)
60        except ImportError:
61            print("please update to latest firmware")

示例输出：

无

电机控制

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

MicroPython 代码块：

 1# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 2#
 3# SPDX-License-Identifier: MIT
 4
 5import os, sys, io
 6import M5
 7from M5 import *
 8from module import Bala2Module
 9import time
10
11
12title0 = None
13module_bala2_0 = None
14i = None
15
16
17def setup():
18    global title0, module_bala2_0, i
19    M5.begin()
20    Widgets.fillScreen(0x222222)
21    title0 = Widgets.Title("Bala2 Motor Control", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)
22
23    module_bala2_0 = Bala2Module(0)
24    for i in range(1, 1001):
25        module_bala2_0.set_motor_speed(i, i)
26        time.sleep_ms(10)
27    for i in range(1, 1001):
28        module_bala2_0.set_motor_speed(1000 - i, 1000 - i)
29        time.sleep_ms(10)
30    for i in range(1, 1001):
31        module_bala2_0.set_motor_speed(0 - i, 0 - i)
32        time.sleep_ms(10)
33    for i in range(-1000, 1):
34        module_bala2_0.set_motor_speed(i, i)
35        time.sleep_ms(10)
36    module_bala2_0.set_motor_speed(0, 0)
37
38
39def loop():
40    global title0, module_bala2_0, i
41    M5.update()
42
43
44if __name__ == "__main__":
45    try:
46        setup()
47        while True:
48            loop()
49    except (Exception, KeyboardInterrupt) as e:
50        try:
51            from utility import print_error_msg
52
53            print_error_msg(e)
54        except ImportError:
55            print("please update to latest firmware")

示例输出：

无

读取编码器

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

MicroPython 代码块：

 1# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 2#
 3# SPDX-License-Identifier: MIT
 4
 5import os, sys, io
 6import M5
 7from M5 import *
 8from module import Bala2Module
 9import time
10
11
12title0 = None
13label_enc1 = None
14label_enc2 = None
15label_enc1_val = None
16label_enc2_val = None
17module_bala2_0 = None
18last_time = None
19enc_value = None
20enc1 = None
21enc2 = None
22
23
24def setup():
25    global \
26        title0, \
27        label_enc1, \
28        label_enc2, \
29        label_enc1_val, \
30        label_enc2_val, \
31        module_bala2_0, \
32        last_time, \
33        enc_value, \
34        enc1, \
35        enc2
36    M5.begin()
37    Widgets.fillScreen(0x222222)
38    title0 = Widgets.Title("Bala2 Encoder Read", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)
39    label_enc1 = Widgets.Label("Enc1", 54, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
40    label_enc2 = Widgets.Label("Enc2", 208, 85, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
41    label_enc1_val = Widgets.Label("0", 50, 125, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
42    label_enc2_val = Widgets.Label("0", 202, 125, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)
43    module_bala2_0 = Bala2Module(0)
44    module_bala2_0.set_encoder_value(0, 0)
45    last_time = time.ticks_ms()
46
47
48def loop():
49    global \
50        title0, \
51        label_enc1, \
52        label_enc2, \
53        label_enc1_val, \
54        label_enc2_val, \
55        module_bala2_0, \
56        last_time, \
57        enc_value, \
58        enc1, \
59        enc2
60    M5.update()
61    if (time.ticks_diff((time.ticks_ms()), last_time)) > 100:
62        last_time = time.ticks_ms()
63        enc_value = module_bala2_0.get_encoder_value()
64        enc1 = enc_value[0]
65        enc2 = enc_value[1]
66        label_enc1_val.setText(str(enc1))
67        label_enc2_val.setText(str(enc2))
68
69
70if __name__ == "__main__":
71    try:
72        setup()
73        while True:
74            loop()
75    except (Exception, KeyboardInterrupt) as e:
76        try:
77            from utility import print_error_msg
78
79            print_error_msg(e)
80        except ImportError:
81            print("please update to latest firmware")

示例输出：

无

小车控制

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

MicroPython 代码块：

 1# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
 2#
 3# SPDX-License-Identifier: MIT
 4
 5import os, sys, io
 6import M5
 7from M5 import *
 8from module import Bala2Module
 9import time
10
11
12title0 = None
13module_bala2_0 = None
14i = None
15
16
17def setup():
18    global title0, module_bala2_0, i
19    M5.begin()
20    Widgets.fillScreen(0x222222)
21    title0 = Widgets.Title("Self-Balancing Robot", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu24)
22    module_bala2_0 = Bala2Module(0)
23    module_bala2_0.calibrate()
24    module_bala2_0.start()
25    time.sleep_ms(2000)
26    module_bala2_0.set_turn_speed(-100)
27    time.sleep_ms(1000)
28    module_bala2_0.set_turn_speed(100)
29    time.sleep_ms(1000)
30    module_bala2_0.set_turn_speed(0)
31    time.sleep_ms(2000)
32    for i in range(20):
33        module_bala2_0.set_angle_pid_target(0 - i)
34        time.sleep_ms(100)
35    time.sleep_ms(2000)
36    for i in range(20):
37        module_bala2_0.set_angle_pid_target(i - 20)
38        time.sleep_ms(100)
39    for i in range(20):
40        module_bala2_0.set_angle_pid_target(i)
41        time.sleep_ms(100)
42    time.sleep_ms(2000)
43    for i in range(20):
44        module_bala2_0.set_angle_pid_target(20 - i)
45        time.sleep_ms(100)
46    module_bala2_0.set_angle_pid_target(0)
47
48
49def loop():
50    global title0, module_bala2_0, i
51    M5.update()
52
53
54if __name__ == "__main__":
55    try:
56        setup()
57        while True:
58            loop()
59    except (Exception, KeyboardInterrupt) as e:
60        try:
61            from utility import print_error_msg
62
63            print_error_msg(e)
64        except ImportError:
65            print("please update to latest firmware")

示例输出：

无

API应用

Bala2Module

class module.bala2.Bala2Module(timer_id=0)

创建一个 Bala2Module 对象

参数:

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

UiFlow2 代码块：

init.png

MicroPython 代码块：

from module import Bala2Module

module_bala2_0 = Bala2Module(timer_id = 0)
calibrate()

校准传感器

UiFlow2 代码块：

calibrate.png

MicroPython 代码块：

module_bala2_0.calibrate()
set_motor_speed(left, right)

设置电机转速

参数:

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

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

UiFlow2 代码块：

set_motor_speed.png

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 代码块：

set_encoder_value.png

MicroPython 代码块：

module_bala2_0.set_encoder_value(left, right)
get_encoder_value()

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

返回:

左，右编码器数值

返回类型:

tuple[int, int]

UiFlow2 代码块：

get_encoder_value.png

MicroPython 代码块：

module_bala2_0.get_encoder_value()
set_servo_angle(pos, angle)

设置舵机角度

参数:

  • pos (int) – 输出通道，范围：1~4。

  • angle (int) – 舵机角度，范围：0~180。

UiFlow2 代码块：

set_servo_angle.png

MicroPython 代码块：

module_bala2_0.set_servo_angle(pos, angle)
start()

开始直立平衡控制

UiFlow2 代码块：

start.png

MicroPython 代码块：

module_bala2_0.start()
stop()

停止平衡控制

UiFlow2 代码块：

stop.png

MicroPython 代码块：

module_bala2_0.stop()
get_angle()

获取小车倾角

返回:

小车倾角

返回类型:

int

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

UiFlow2 代码块：

get_angle.png

MicroPython 代码块：

module_bala2_0.get_angle()
set_angle_pid(kp, ki, kd)

设置角度环 PID 参数

参数:

  • kp (float) – 比例增

  • ki (float) – 积分增益

  • kd (float) – 微分增益

UiFlow2 代码块：

set_angle_pid.png

MicroPython 代码块：

module_bala2_0.set_angle_pid(kp, ki, kd)
get_angle_pid()

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

返回:

kp, ki, kd parameters

返回类型:

tuple[float, float, float]

UiFlow2 代码块：

get_angle_pid.png

MicroPython 代码块：

module_bala2_0.get_angle_pid()
set_angle_pid_target(angle=0)

设置角度环 PID 控制目标

参数:

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

UiFlow2 代码块：

set_angle_pid_target.png

MicroPython 代码块：

module_bala2_0.set_angle_pid_target(angle)
get_angle_pid_target()

获取角度环 PID 控制目标。

返回:

角度环 PID 控制目标。

返回类型:

float

UiFlow2 代码块：

get_angle_pid_target.png

MicroPython 代码块：

module_bala2_0.get_angle_pid_target()
set_speed_pid(kp, ki, kd)

设置速度环 PID 控制参数。

参数:

  • kp (float) – 比例增

  • ki (float) – 积分增益

  • kd (float) – 微分增益

UiFlow2 代码块：

set_speed_pid.png

MicroPython 代码块：

module_bala2_0.set_speed_pid(kp, ki, kd)
get_speed_pid()

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

返回:

kp, ki, kd parameters

返回类型:

tuple[float, float, float]

UiFlow2 代码块：

get_speed_pid.png

MicroPython 代码块：

module_bala2_0.get_speed_pid()
set_speed_pid_target(speed=0)

设置速度环 PID 控制目标。

参数:

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

UiFlow2 代码块：

set_speed_pid_target.png

MicroPython 代码块：

module_bala2_0.set_speed_pid_target(speed)
get_speed_pid_target()

获取速度环 PID 控制目标。

返回:

速度环 PID 控制目标。

返回类型:

float

UiFlow2 代码块：

get_speed_pid_target.png

MicroPython 代码块：

module_bala2_0.get_speed_pid_target()
set_turn_speed(speed)

设置转向速度。

参数:

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

UiFlow2 代码块：

set_turn_speed.png

MicroPython 代码块：

module_bala2_0.set_turn_speed(speed)