mpython --- 掌控板板载相关功能函数

mpython 是基于掌控板封装的专有模块,内含掌控板板载资源相关功能函数。 详细代码实现可查阅 mpython.py源码 。

延时

mpython.sleep(s)

秒级延时

• s -单位秒。

mpython.sleep_ms(ms)

毫秒级延时

• ms -单位毫秒。

mpython.sleep_us(us)

级延时

• us -单位微秒。

映射

mpython.numberMap(inputNum, bMin, bMax, cMin, cMax)

映射函数，参数：

• inputNum 为需要映射的变量

• bMin 为需要映射的最小值

• bMax 为需要映射的最大值

• cMin 为映射的最小值

• cMax 为映射的最大值

板载传感器

声音、光线

light.read()

读取板载光线传感器值，范围0~4095。

sound.read()

读取板载麦克风，范围0~4095。

加速度计

通过accelerometer对象，您可以获取3轴加速度计值，单位g。 加速度范围±2g/±4g/±8g/±16g,默认为±2g。

accelerometer.get_x()

获取x轴上的加速度测量值，正整数或负整数，具体取决于方向。

accelerometer.get_y()

获取y轴上的加速度测量值，正整数或负整数，具体取决于方向。

accelerometer.get_z()

获取z轴上的加速度测量值，正整数或负整数，具体取决于方向。

accelerometer.set_range(range)

设置加速度范围,在默认,不修改为,范围在±2g。

加速度范围值为以下常量:

常量	值	定义
RANGE_2G	0	范围±2g
RANGE_4G	1	范围±4g
RANGE_8G	2	范围±8g
RANGE_16G	3	范围±16g

accelerometer.set_resolution(resolution)

设置加速度分辨率,默认,不修改为10bit分辨率。

分辨率值为以下常量:

常量	值	定义
RES_14_BIT	0	14 bit 分辨率
RES_12_BIT	1	12 bit 分辨率
RES_10_BIT	2	10 bit 分辨率

accelerometer.set_offset(x=None, y=None, z=None)

该函数用于校准加速度计的3个轴(x,y,z)的加速值偏差。一般情况下无需校准,只有当遇到加速度偏差较大时修正。 注意,校准数据断电后不会保存。x , y , z 为调整偏差值,可修正范围±1g。 掌控板v2.3版本以上，掉电会保存校准数据。

accelerometer.roll_pitch_angle()

返回通过加速度计计算得出的欧拉角(横滚角roll、俯仰角pitch)。注意，偏航角(yaw)需要角速度，故无法测得。返回2元组（roll,pitch），单位角度。

假定，掌控板为飞机：

• 横滚角指飞机两翼所在的平面与平行线之间的夹角，机体向右滚为正,范围为[-180,180].

• 俯仰角是指机头与水平面的夹角,当飞机平行时则为0,抬头时则为正,范围为[-180,180]

注意

只通过3轴加速度计算方式，只适用于静态下，只受重力下的测量。实际中，会受到其他加速度干扰，如震动。

运动侦测事件

提供多种平面倾斜、翻转、敲击（类似鼠标点击）、掉落的运动姿态事件。用户可预先设定回调函数，当事件发生后，触发事件回调。 回调函数定义如，function_callback(event)。event 参数为对应事件常量。

accelerometer.event_tilt_left

向左倾斜

accelerometer.event_tilt_right

向右倾斜

accelerometer.event_tilt_up

向前倾斜

accelerometer.event_tilt_down

向后倾斜

accelerometer.event_face_up

正面朝上

accelerometer.event_face_down

正面朝下

accelerometer.event_single_click

单次敲击，类似鼠标的单击操作。

accelerometer.event_double_click

连续敲击两次，类似鼠标的双击操作。

accelerometer.event_freefall

坠落

event事件定义如下:

事件	值
accelerometer.TILT_LEFT	0
accelerometer.TILT_RIGHT	1
accelerometer.TILT_UP	2
accelerometer.TILT_DOWN	3
accelerometer.FACE_UP	4
accelerometer.FACE_DOWN	5
accelerometer.SINGLE_CLICK	6
accelerometer.DOUBLE_CLICK	7
accelerometer.FREEFALL	8

注意

掌控板v2.3版本以上,去除加速度计运动侦测事件

accelerometer 事件的简单应用

# The MIT License (MIT)
# Copyright (c) 2020, Tangliufeng for labplus Industries

# accelerometer event simple example

from mpython import *

def motion_callback_function(event):
    """ 运动事件回调函数 """
    if event == accelerometer.TILT_LEFT:
        print("tilt left")
    elif event == accelerometer.TILT_RIGHT:
        print("tilt right")
    elif event == accelerometer.TILT_UP:
        print("tilt up")
    elif event == accelerometer.TILT_DOWN:
        print("tilt down")
    elif event == accelerometer.FACE_UP:
        print("face up")
    elif event == accelerometer.FACE_DOWN:
        print("face down")
    elif event == accelerometer.SINGLE_CLICK:
        print("single click")
    elif event == accelerometer.DOUBLE_CLICK:
        print("double click")
    elif event == accelerometer.FREEFALL:
        print("freefall")

# 事件回调注册
accelerometer.event_tilt_up = motion_callback_function
accelerometer.event_tilt_down = motion_callback_function
accelerometer.event_tilt_left = motion_callback_function
accelerometer.event_tilt_right = motion_callback_function
accelerometer.event_face_up = motion_callback_function
accelerometer.event_face_down = motion_callback_function
accelerometer.event_single_click = motion_callback_function
accelerometer.event_double_click = motion_callback_function
accelerometer.event_freefall = motion_callback_function

陀螺仪(gyroscope)

通过gyroscope对象，您可以获取陀螺仪角速度值，角速度的单位是dps(°/S)。 角速度范围±16dps/±32dps/±64dps/±128dps/±256dps/±512dps/±1024dps/±2048dps ,默认为±256 dps。

gyroscope.get_x()

获取x轴上的角速度测量值，具体取决于方向。

gyroscope.get_y()

获取y轴上的角速度测量值，具体取决于方向。

gyroscope.get_z()

获取z轴上的角速度测量值，具体取决于方向。

gyroscope.set_range(range)

设置角速度范围,默认不修改为,范围在±256 dps。

角速度范围值为以下常量:

常量	值	定义
RANGE_16_DPS	0	范围±16 dps
RANGE_32_DPS	16	范围±32 dps
RANGE_64_DPS	32	范围±64 dps
RANGE_128_DPS	48	范围±128 dps
RANGE_256_DPS	64	范围±256 dps
RANGE_512_DPS	80	范围±512 dps
RANGE_1024_DPS	96	范围±1024 dps
RANGE_2048_DPS	112	范围±2048 dps

gyroscope.set_offset(x=None, y=None, z=None)

该函数用于校准陀螺仪的3个轴(x,y,z)的角速值偏差。一般情况下无需校准,只有当遇到角速度偏差较大时修正。 x , y , z 为调整偏差值,可修正范围±1024dps。

注意

掌控板v2.3版本以上加入陀螺仪传感器

磁力计(magnetic)

MMC5983MA磁力计函数接口,可获取3轴地磁感应强度、地磁场强度、获取电子罗盘角度。

注意

掌控板v2.0版本以上,才有MMC5983MA磁力计！

magnetic.get_x()

获取x轴的磁感应值,正整数或负整数,范围±8191,单位mG(毫高斯)。

magnetic.get_y()

获取y轴的磁感应值,正整数或负整数,范围±8191,单位mG(毫高斯)。

magnetic.get_z()

获取z轴的磁感应值,正整数或负整数,范围±8191,单位mG(毫高斯)。

magnetic.get_field_strength()

返回计算后的磁感应值,即3轴磁力的和。计算公式,x^2+y^2+z^2的平方根。

magnetic.peeling()

磁力去皮。类似电子秤去皮功能, peeling() 后,下次 get_field_strength() 返回的值为减去当前磁力值后计算得出的结果。可用于去除地磁感应值的测量应用。

magnetic.clear_peeling()

磁力去皮功能取消。使用 peeling() 后,可用该函数,恢复正常地磁测量。

magnetic.get_heading()

获取电子罗盘角度,即改方向与地磁北极的夹角,掌控板的正上方,即USB位置视为正北方。单位角度,范围0~360。

注意

由于在角度计算并没有做z轴的倾斜补偿,在使用 get_heading() 读取罗盘角度时,掌控板应保持水平放置！

注意

如需得到精准的罗盘角度,请确保周边无强磁场干扰或在使用前 calibrate() 校准。

magnetic.calibrate()

电子罗盘校准。当掌控板周边存在强磁干扰,可使用该函数清除强磁分量,才能计算准确的地磁北偏角。注意,断电后不保存校准偏移值。

校准方法,按照掌控板显示屏指示步骤操作:

1. 掌控板水平放置,在水平面旋转数圈,过程约15秒。

2. 掌控板垂直放置,沿着垂直于地面轴旋转数圈,过程约15秒。

磁力计应用--指北针

# The MIT License (MIT)
# Copyright (c) 2019, Tangliufeng for labplus Industries

# 掌控板磁力计Magnetic应用--指北针 

from mpython import *
import math

# 绘制罗盘中心坐标和半径
xc,yc,r= 64,32,30


def draw_heading(angle):
    """绘制磁北指针"""
    global xc,yc,r
    angle = 360 - angle
    am = math.pi * 2.0 * angle / 360
    xm = round(xc + r * math.sin(am))
    ym = round(yc - r * math.cos(am))
    oled.line(xc, yc, xm, ym, 1)

# 电子罗盘校准
magnetic.calibrate()
sleep(2)
oled.DispChar('指北针',0,0)
# 绘制罗盘轮廓
oled.circle(xc, yc, r+1, 1)
oled.show()
while True:
    # 获取磁力计电子罗盘角度
    angle = magnetic.get_heading()
    # 清除指针
    oled.fill_circle(xc, yc, r, 0)
    # 显示罗盘指针
    draw_heading(angle)
    oled.show()
    print("磁北极夹角: %d" %angle)

蜂鸣器(music)

由 music 模块驱动掌控板蜂鸣器,具体操作详见 music 模块。

button_[a,b]对象

掌控板上的a,b按键。button_a/button_b 是 Button 类的实例对象。使用 machine.Pin.irq 中断实现。定义了 event_pressed 和 event_released 按键按下、释放事件。 用户可轻易的实现事件回调。除此外，还实现当前或过去按键状态、按键次数等函数方法。

class mpython.Button(pin_num, reverse=False)

Button类，按键抽象类。

• pin_num - IO引脚号

• reverse - 默认为reverse为False。适用于触发为低电平按键。如是触发为高电平按键，将reverse设为True，翻转下。

掌控板上button_a、button_b的实例:

button_a = Button(Pin.P5)
button_b = Button(Pin.P11)

当按键事件发生，触发事件回调。回调函数定义如，function_callback(pin), pin 为该引脚的machine.Pin对象返回。

Button.event_pressed

按键按下事件。

Button.event_released

按键释放事件。

Button 事件回调的简单应用

# The MIT License (MIT)
# Copyright (c) 2020, Tangliufeng for labplus Industries

# 按键事件回调简单的示例

from mpython import *

def on_button_a_pressed(pin):
    """ a键按下事件回调函数 """
    print("按键A，按下了。")

def on_button_b_pressed(pin):
    """ b键按下事件回调函数 """
    print("按键B，按下了。")

# 按键事件注册
button_a.event_pressed = on_button_a_pressed
button_b.event_pressed = on_button_b_pressed

Button.value()

获取按键引脚电平状态。1为高电平，0位低电平。

>>> button_a.value()
>>> 1
>>> button_a.value()
>>> 0

Button.is_pressed()

返回当前是否按住。 True 表示按键按下，False 则未按下。

Button.was_pressed()

返回 True 或 False 指示自设备启动以来或上次调用此方法以来是否按下按钮。调用此方法将清除按下状态，因此必须再次按下按钮，然后才能再次返回 True 。

Button.get_presses()

返回按键的按下总数，并在返回之前将该总数重置为零。注意，计数器超过100将不再计数。

Button.irq(handler=None, trigger=Pin.IRQ_FALLING | Pin.IRQ_RISING, priority=1, wake=None)

配置在引脚的触发源处于活动状态时调用的中断处理程序。用法与 machine.Pin.irq 一样。

参数:

• handler 是一个可选的函数，在中断触发时调用。

• trigger 配置可以触发中断的事件。可能的值是：

  • Pin.IRQ_FALLING 下降沿中断

  • Pin.IRQ_RISING 上升沿中断

  • Pin.IRQ_LOW_LEVEL 低电平中断

  • Pin.IRQ_HIGH_LEVEL 高电平中断

  这些值可以一起进行 OR 运算以触发多个事件。

• priority 设置中断的优先级。它可以采用的值是特定于端口的，但是更高的值总是代表更高的优先级。

• wake 选择此中断可唤醒系统的电源模式。它可以是 machine.IDLE ， machine.SLEEP 或 machine.DEEPSLEEP 。

这些值也可以进行 OR 运算，使引脚在多种功耗模式下产生中断。

此方法返回一个回调对象。

>>> from mpython import *
>>> button_a.irq(trigger=Pin.IRQ_FALLING, handler=lambda p:print("button-a press！"))

touch对象

掌控板上共有6个触摸引脚分别touchpad_p/y/t/h/o/n。是Touch类的实例对象，具体包含函数方法如下。

class mpython.Touch(pin)

Touch.event_pressed

触摸按键按下事件。当按键事件发生，触发事件回调。回调函数定义如，function_callback(value), value 为该触摸按键的状态值。

Touch.event_released

触摸按键释放事件。

Touch.read()

返回触摸值

Touch.config(threshold)

触摸阈值设置

Touch.is_pressed()

返回当前是否按住。 True 表示按键按下，False 则未按下。

Touch.was_pressed()

返回 True 或 False 指示自设备启动以来或上次调用此方法以来是否按下按钮。调用此方法将清除按下状态，因此必须再次按下按钮，然后才能再次返回 True 。

Touch.get_presses()

返回按键的按下总数，并在返回之前将该总数重置为零。注意，计数器超过100将不再计数。

rgb对象

用于控制掌控板的3颗RGB ws2812灯珠。rgb对象为neopixel的衍生类，继承neopixel的方法。更多的使用方法请查阅 neopixel 。

rgb.write()

把数据写入RGB灯珠中。

提示

通过给rgb[n]列表赋值来写入RGB颜色值。如，rgb[0]=(50,0,0)

from mpython import *

rgb[0] = (255, 0, 0)  # 设置为红色，全亮度
rgb[1] = (0, 128, 0)  # 设定为绿色，半亮度
rgb[2] = (0, 0, 64)   # 设置为蓝色，四分之一亮度

rgb.write()

rgb.fill(rgb_buf)

填充所有LED像素。

rgb.brightness(brightness)

亮度调节,范围0~1.0

i2c对象

mPython掌控板已实例 I2C 类，P19、P20 为I2C的SCL、SDA引脚。I2C设备可连接掌控板I2C总线进行操作。

详细有关I2C的读写操作，请查看 machine.I2C 模块或 I2C基础教程 章节。

MPythonPin类

class mpython.MPythonPin(pin, mode=PinMode.IN, pull=None)

构建Pin对象

• pin 掌控板定义引脚号，具体定义看查看 掌控板引脚定义 。

• mode 引脚模式。未设定时,默认 mode = PinMode.IN

  • PinMode.IN 等于1，数字输入模式

  • PinMode.OUT 等于2，数字输出模式

  • PinMode.PWM 等于3，模拟输出模式

  • PinMode.ANALOG