MicroPython documentation and references

程小奔的python接口

本章介绍了程小奔的python接口,一共包含以下几类模块:

  • 小程的python接口:主要是指小程板载驱动的一些API接口。
  • 小奔的python接口:小程用于控制小奔运动或者获取小奔传感器数据的一些API接口。
  • 第三方类库的python接口:程小奔内置的一些第三方类库的接口类,例如mqtt、urequest的类。
  • 神经元扩展模块的python接口:程小奔扩展神经元模块时的一些API接口。

小程的python接口

小程的python接口API如下:

小程的python接口列表

led --- 板载全彩LED灯

led 模块的主要功能与函数

功能相关函数
led.show(r, g, b)

设置并显示RGB LED灯的颜色, 参数:

  • r 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
  • g 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
  • b 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
led.set_red(val)

设置 RGB LED灯的红色色值,参数:

  • val 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
led.set_green(val)

设置 RGB LED灯的绿色色值,参数:

  • val 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
led.set_blue(val)

设置 RGB LED灯的蓝色色值,参数:

  • val 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
led.off()

熄灭LED灯。

程序示例:
import codey
import time

codey.led.show(255,255,255)
time.sleep(2)
codey.led.off()
time.sleep(2)
while True:
    codey.led.set_red(255)
    time.sleep(1)
    codey.led.set_green(255)
    time.sleep(1)
    codey.led.set_blue(255)
    time.sleep(1)
    codey.led.off()
    time.sleep(1)
display --- 表情面板

display 模块的主要功能与函数

表情面板显示说明
_images/1.png

如上图所示,表情面板以左上角为坐标 0 点, x ,y 的方向如箭头示意。显示图片参数时,以上图为例,其第一列数据,上面的三个是点亮的,在数据转换时,这个数据转换为 11100000, 即 16进制 0xe0,同样的,第二列数据转换为 00001101,即 16进制的 0x0d,上图的全部点阵转换为图片参数时,是 e00d0000000000000000000000000000

功能相关函数
display.show_image(image, pos_x = 0, pos_y = 0, time_s = None)

以图片参数的方式显示自定义的点阵图形,参数:

  • image 字符串数据,点阵的每一列有8个显示点,为1 byte的数据,转换为16进制的字符串, 因此16列点阵,需要用 32 个字符串数据来表示。
  • pos_x 显示图形在表情面板上x轴的偏移量,参数范围是 -15 ~ 15,如果不设置该参数,默认从 0位置开始。
  • pos_y 显示图形在表情面板上y轴的偏移量,参数范围是 -7 ~ 7,如果不设置该参数,默认从 0位置开始。
  • time_s 显示暂留的时间(以秒为单位),如果没有设置该参数,在有清屏或者重新设置表情面板操作之前,维持显示不变。
display.show(var, pos_x = 0, pos_y = 0, wait = True)

以全类型的数据参数方式显示数据,参数:

  • var 全类型, 其中数值型和时间类型的显示会做特殊处理,时间格式显示需满足: [x]x:[x]x 格式 (正则表达式 \d?\d:\d\d?)。
  • pos_x 显示数据在表情面板上x轴的偏移量,参数范围是 -15 ~ 15,如果不设置该参数,默认从 0位置开始。
  • pos_y 显示数据在表情面板上y轴的偏移量,参数范围是 -7 ~ 7,如果不设置该参数,默认从 0位置开始。
  • wait 设置是否阻塞显示,其中 True:表示阻塞直到显示完毕, False:表示显示但不阻塞。
display.set_pixel(pos_x, pos_y, status)

设置表情面板单个像素点的亮灭状态,参数:

  • pos_x 像素点在表情面板上x轴的坐标,参数范围是 0 ~ 15
  • pos_y 像素点在表情面板上y轴的坐标,参数范围是 0 ~ 7
  • status 布尔值,其中 True:表示像素点亮, False:表示像素熄灭。
display.get_pixel(pos_x, pos_y)

获得表情面板上单个像素点当前的亮灭状态,返回值是布尔值,其中 True:表示像素点亮, False:表示像素熄灭,参数:

  • pos_x 像素点在表情面板上x轴的坐标,参数范围是 0 ~ 15
  • pos_y 像素点在表情面板上y轴的坐标,参数范围是 0 ~ 7
display.toggle_pixel(pos_x, pos_y)

切换表情面板上单个像素点当前的亮灭状态,参数:

  • pos_x 像素点在表情面板上x轴的坐标,参数范围是 0 ~ 15
  • pos_y 像素点在表情面板上y轴的坐标,参数范围是 0 ~ 7
display.clear()

熄灭表情面板上全部的灯。

程序示例:
import codey
import time

codey.display.show("ffffff")
codey.display.show("123")
time.sleep(1)
codey.display.show("12345", 3, 1)
codey.display.set_pixel(1, 1, True)
image = "ffffffffff000000000000000000000000"
codey.display.show_image(image, pos_x = 3, pos_y = 4)
time.sleep(1)
codey.display.clear()
print("[1, 1]:", codey.display.get_pixel(1, 1))
codey.display.show("12:28")
while True:
    codey.display.toggle_pixel(7, 2)
    codey.display.toggle_pixel(7, 4)
    time.sleep(1)
speaker --- 板载扬声器

speaker 模块的主要功能与函数

功能相关函数
speaker.stop_sounds()

停止所有声音。

speaker.play_melody(file_name)

播放音频文件,该函数播放时,不会阻塞,但连续调用的话,后一次播放操作会停止前一次的播放,参数:

  • file_name 字符串类型,烧录在程小奔flash中的wav格式的音频文件名,输入时,也可省略格式的后缀 .wav
可选择的音效文件有
hello.wav       : hello(哈喽)
hi.wav          : hi(嗨)
bye.wav         : bye(拜)
yeah.wav        : yeah(耶)
wow.wav         : wow(哇哦)
laugh.wav       : laugh(笑声)
hum.wav         : hum(哼唱)
sad.wav         : sad(难过)
sigh.wav        : sigh(叹气)
annoyed.wav     : annoyed(哼)
angry.wav       : angry(生气)
surprised.wav   : scared(惊吓)
yummy.wav       : pettish(撒娇)
curious.wav     : curious(好奇)
embarrassed.wav : embarrassed(尴尬)
ready.wav       : ready(准备)
sprint.wav      : sprint(冲刺)
sleepy.wav      : snore(打呼)
meow.wav        : meow(喵)
start.wav       : start(启动)
switch.wav      : switch(开关)
beeps.wav       : beeps(哔哔)
buzzing.wav     : buzz(蜂鸣)
exhaust.wav     : air-out(排气)
explosion.wav   : explosion(爆炸)
gotcha.wav      : gotcha(获取)
hurt.wav        : painful(痛苦)
jump.wav        : jump(跳动)
laser.wav       : laser(激光)
level up.wav    : level-up(升级)
low energy.wav  : low-energy(低能量)
metal clash.wav : metal-clash(金属音)
prompt tone.wav : prompt-tone(提示)
right.wav       : right(正确)
wrong.wav       : wrong(错误)
ring.wav        : ringtone(铃声)
score.wav       : score(得分)
shot.wav        : shot(发射)
step_1.wav      : step_1(脚步声1)
step_2.wav      : step_2(脚步声2)
wake.wav        : activate(激活)
warning.wav     : warning(警告)
speaker.play_melody_until_done(file_name)

播放音频文件直到停止,该函数会阻塞播放,即在未播放完音效之前,后一条指令无法得到执行,参数:

  • file_name 字符串类型,烧录在程小奔flash中的wav格式的音频文件名,输入时,也可省略格式名 .wav,具体可选参数见 play_melody
speaker.play_note(note_num, beat = None)

播放音符, 数字音符定义请参考: scratch数字音符说明,参数:

  • note_num 数值型,数值范围 48 - 72,或者字符串类型,如 C4
  • beat 数值数据,表示节拍数,如果不填,则一直播放。

音符与频率的对应关系如下:

['C2','65'],   ['D2','73'],   ['E2','82'],   ['F2','87'],
['G2','98'],   ['A2','110'],  ['B2','123'],  ['C3','131'],
['D3','147'],  ['E3','165'],  ['F3','175'],  ['G3','196'],
['A3','220'],  ['B3','247'],  ['C4','262'],  ['D4','294'],
['E4','330'],  ['F4','349'],  ['G4','392'],  ['A4','440'],
['B4','494'],  ['C5','523'],  ['D5','587'],  ['E5','659'],
['F5','698'],  ['G5','784'],  ['A5','880'],  ['B5','988'],
['C6','1047'], ['D6','1175'], ['E6','1319'], ['F6','1397'],
['G6','1568'], ['A6','1760'], ['B6','1976'], ['C7','2093'],
['D7','2349'], ['E7','2637'], ['F7','2794'], ['G7','3136'],
['A7','3520'], ['B7','3951'], ['C8','4186'], ['D8','4699'],
speaker.play_tone(frequency, time = None)

播放设定频率的声音,参数:

  • frequency 数值数据,播放声音的频率,其数值范围是 0 ~ 5000
  • time 数值数据,表示播放时间(单位是 毫秒-ms ),其数值范围是 0 ~ 数值范围极限
speaker.rest(number)

停止节拍,参数:

  • number 数值数据,暂停的节拍数,其数值范围是 0 ~ 数值范围极限
常量
speaker.volume

数值数据,音量的大小的属性值,可以修改或者读取这个值。修改这个数值,可以控制音量的大小。其数值范围是 0 ~ 100

speaker.tempo

数值数据,表示播放速度的属性,单位是 bmp (beat per minute),即每一个节拍的长度。 其数值范围是 6 ~ 600。 默认数值是60,即一个节拍的维持时间是1秒。 restplay_note 函数的节拍会受该常量影响。

程序示例:
import codey
import time

codey.speaker.play_melody("hello", True)
codey.display.show("hello")
codey.display.clear()

codey.speaker.play_note(48, 1)
codey.speaker.rest(1)
codey.display.show("note")
codey.display.clear()
codey.speaker.play_note("C4", 1)
codey.speaker.rest(1)
codey.display.show("C4")
codey.display.clear()
codey.speaker.play_tone(1000, 2)
codey.speaker.rest(1)
codey.display.show("tone")
codey.display.clear()
print("tempo:", end = "")
print(codey.speaker.tempo)
codey.speaker.play_note("C4", 1)
codey.speaker.rest(1)
codey.speaker.tempo = 120
codey.speaker.volume = 20
codey.speaker.play_note("C4", 1)
codey.speaker.rest(1)
sound_sensor --- 板载音量传感器

sound_sensor 模块的主要功能与函数

功能相关函数
sound_sensor.get_loudness()

获得音量传感器检测的声音强度, 返回值是音量的大小。 数值范围 0 ~ 100

程序示例:
import codey

while True:
    codey.display.show(codey.sound_sensor.get_loudness())
light_sensor --- 板载光线传感器

light_sensor 模块的主要功能与函数

功能相关函数
light_sensor.get_value()

获得光线传感器检测的光线强度, 返回值是可见光的强度值。 数值范围 0 ~ 100

程序示例:
import codey

while True:
    codey.display.show(codey.light_sensor.get_value())
potentiometer --- 板载电位器旋钮

potentiometer 模块的主要功能与函数

功能相关函数
potentiometer.get_value()

获得电位器旋钮的当前数值。 数值范围 0 ~ 100

程序示例:
import codey

while True:
    codey.display.show(codey.potentiometer.get_value())
button_a --- 板载按键A

button_a 模块的主要功能与函数

功能相关函数
button_a.is_pressed()

获取按键A当前状态。 返回的结果是 True:按键被按下, 或者 False: 按键未被按下。

程序示例:
import codey

def loop():
    while True:
        if codey.button_a.is_pressed():
            print("button A is pressed")
loop()
button_b --- 板载按键B

button_b 模块的主要功能与函数

功能相关函数
button_b.is_pressed()

获取按键B当前状态。 返回的结果是 True:按键被按下, 或者 False: 按键未被按下。

程序示例:
import codey

def loop():
    while True:
        if codey.button_b.is_pressed():
            print("button B is pressed")
loop()
button_c --- 板载按键C

button_c 模块的主要功能与函数

功能相关函数
button_c.is_pressed()

获取按键C当前状态。 返回的结果是 True:按键被按下, 或者 False: 按键未被按下。

程序示例:
import codey

def loop():
    while True:
        if codey.button_c.is_pressed():
            print("button C is pressed")
loop()
motion_sensor --- 板载姿态传感器

motion_sensor 模块的主要功能与函数

姿态传感器说明
_images/2.png

如上图所示,roll,pitch(翻滚角,俯仰角)的方向以右手螺旋定则为标准。

小程水平放置时roll和pitch都为

roll的范围: -90° ~ 90°

pitch的范围: -180° ~ 180°

功能相关函数
motion_sensor.get_roll()

获取姿态角的翻滚角,返回的数据范围是 -90 ~ 90

motion_sensor.get_pitch()

获取姿态角的俯仰角,返回的数据范围是 -180 ~ 180

motion_sensor.get_yaw()

获取姿态角的偏航角,返回的数据范围是 0 ~ 360,由于小程板载的传感器是六轴传感器,没有电子罗盘。所以实际上偏航角只是使用了Z轴角速度的积分。它存在着积累误差。如果是想获得真实偏航角的,这个API不适合使用。

motion_sensor.get_rotation(axis)

获得小程在三个轴上转动的角度,以逆时针转动方向为正方向,参数:

  • axis 字符串类型,以 xyz 代表小程定义的坐标轴。
motion_sensor.reset_rotation(axis = "all")

初始化绕三个轴转动的当前角度为0,get_rotation() 函数将从 0 开始计算,参数:

  • axis 字符串类型,以 xyz 代表小程定义的坐标轴, all 代表全部的三个轴。也是这个函数的默认值。
motion_sensor.is_shaked()

检测小程是否有被摇晃,返回值是布尔值,其中 True 表示小程被晃动了,False 表示小程未被晃动。

motion_sensor.get_shake_strength()

如果小程被摇晃了,这个函数可以获得摇晃的强度,返回值的数值范围是 0 ~ 100, 数值越大,晃动的强度就越大。

motion_sensor.is_tilted_left()

检测小程是否向左倾斜,返回值是布尔值,其中 True 表示小程向左倾斜了,False 表示小程未向左倾斜。

motion_sensor.is_tilted_right()

检测小程是否向右倾斜,返回值是布尔值,其中 True 表示小程向右倾斜了,False 表示小程未向右倾斜。

motion_sensor.is_ears_up()

检测小程是否耳朵向上,返回值是布尔值,其中 True 表示小程耳朵朝上,False 表示小程耳朵没有朝上。

motion_sensor.is_ears_down()

检测小程是否耳朵向下,返回值是布尔值,其中 True 表示小程耳朵朝下,False 表示小程耳朵没有朝下。

motion_sensor.is_display_up()

检测小程是否表情面板朝上,返回值是布尔值,其中 True 表示小程表情面板朝上,False 表示小程表情面板没有朝上。

motion_sensor.is_display_down()

检测小程是否表情面板朝下,返回值是布尔值,其中 True 表示小程表情面板朝下,False 表示小程表情面板没有朝下。

motion_sensor.is_upright()

检测小程是否直立,返回值是布尔值,其中 True 表示小程直立,False 表示小程没有直立。

motion_sensor.get_acceleration(axis)

获取三个轴的加速度值,单位是 m/s^2,参数:

  • axis 字符串类型,以 xyz 代表小程定义的坐标轴。
motion_sensor.get_gyroscope(axis)

获取三个轴的角速度值,单位是 °/秒,参数:

  • axis 字符串类型,以 xyz 代表小程定义的坐标轴。
程序示例1:
import codey
import time

while True:
    roll = codey.motion_sensor.get_roll()
    pitch = codey.motion_sensor.get_pitch()
    yaw = codey.motion_sensor.get_yaw()
    print("roll:", end = "")
    print(roll, end = "")
    print("   ,pitch:", end = "")
    print(pitch, end = "")
    print("   ,yaw:", end = "")
    print(yaw)
    time.sleep(0.05)
程序示例2:
import codey

while True:
    if codey.motion_sensor.is_shaked():
        print("shake_strength:", end = "")
        print(codey.motion_sensor.get_shake_strength())
程序示例3:
import codey

while True:
    if codey.motion_sensor.is_tilted_left():
        print("tilted_left")
    if codey.motion_sensor.is_tilted_right():
        print("tilted_right")
    if codey.motion_sensor.is_ears_up():
        print("ears_up")
    if codey.motion_sensor.is_ears_down():
        print("ears_down")
    if codey.motion_sensor.is_display_up():
        print("display_up")
    if codey.motion_sensor.is_display_down():
        print("display_down")
    if codey.motion_sensor.is_upright():
        print("upright")
ir --- 板载红外收发

ir 模块的主要功能与函数

功能相关函数
ir.receive()

返回红外收到的字符串信息,所以发送端发送的数据必须以 \n 结束。 如果是接收 NEC编码协议的遥控器指令,请使用另外一个函数 receive_remote_code()

ir.receive_remote_code()

获取红外遥控器数据,红外遥控器数据包含地址和内容两部分,因此返回一个长度为2的list数据。 前面一个参数是地址码,后面一个参数是数据码。

ir.send(str)

发送红外字符串,参数:

  • str 要发射的字符串数据,send 函数会在字符串末尾自动加入 \n 结束符。
ir.start_learning()

开始红外学习,仅支持学习标准NEC协议的遥控器指令。

ir.stop_learning()

停止红外学习

ir.save_learned_result(index)

将学习的红外编码结果保存到相应区域,参数:

  • index 数值范围是 0 ~ 15,一共有16个存储区域。
ir.send_learned_result(index = 1)

发送红外学习保存下来的红外编码, 默认发送 index = 1的区域的学习结果,参数:

  • index 数值范围是 0 ~ 15,一共有16个存储区域。
ir.learn(time = 3)

红外学习 time 秒,在调用该API后会保存 time 秒内学到的红外信息。 默认会保留到index = 1的区域,参数:

  • time 学习时间,单位是
程序示例1:
import codey
import event

@event.start
def start_cb():
    print("start event succeeded")
    while True:
        codey.display.show(codey.ir.receive_remote_code()[1])
程序示例2:
import codey
import event

@event.button_a_pressed
def button_a_cb():
    print("button a event succeeded")
    codey.ir.learn()
    codey.led.show(0, 100, 0)

@event.button_b_pressed
def button_a_cb():
    print("button b event succeeded")
    while True:
        codey.ir.send_learned_result()

@event.button_c_pressed
def button_c_cb():
    print("button b event succeeded")
    while True:
        codey.display.show(codey.ir.receive())
wifi --- 板载wifi

wifi 模块的主要功能与函数

功能相关函数
wifi.start(ssid = "wifi_ssid", password = "password", mode = codey.wifi.STA)

启动wifi连接,该API不阻塞,API退出不代表wifi已连接上,需要调用 wifi.is_connected() 判断,参数:

  • ssid 字符串类型,wifi账号。
  • password 字符串类型,wifi密码。
  • mode 启动wifi的模式。
wifi.is_connected()

检测wifi是否已连接上,返回值是布尔值,其中 True 表示wifi已经建立连接,False 表示wifi尚未建立连接。

常量
wifi.STA

wifi的站点模式,即无线网卡模式,该模式下,wifi可以连接到路由器。

wifi.AP

wifi的无线接入点模式,一般的无线路由/网桥工作在该模式,该模式下,wifi可以允许其它无线设备接入。

wifi.APSTA

wifi的AP和STA模式共存。

程序示例:
import codey
codey.wifi.start('makeblock', 'password', codey.wifi.STA)
codey.led.show(0,0,0)
while True:
    if codey.wifi.is_connected():
        codey.led.show(0,0,255)

    else:
        codey.led.show(0,0,0)
battery --- 内置锂电池

battery 模块的主要功能与函数

功能相关函数
battery.get_voltage()

获取当前的电池电压,返回值是一个浮点数据。单位是 V

battery.get_percentage()

获取剩余电池电量的百分比,返回值是一个整数,数据范围是 0 ~ 100,其中 100 表示剩余电量还有 100%。

程序示例:
import codey

while True:
    print("vol" + str(codey.battery.get_voltage()))
    print("percentage" + str(codey.battery.get_percentage()))
codey_timer --- 计数器

codey_timer 模块的主要功能与函数(因为是系统函数,所以使用时不需要带模块名称)

功能相关函数
codey.get_timer()

获取计时器当前值(计时器从用户脚本启动时开始运行),返回值是一个浮点数据,单位是

codey.reset_timer()

初始化计时器的值

Sample Code:
import codey

codey.reset_timer()

while True:
    print("time:", end = "")
    print(codey.get_timer())
codey_broadcast --- 广播模块

codey_broadcast 模块的主要功能与函数(因为是系统函数,所以使用时不需要带模块名称)

功能相关函数
codey.broadcast(str)

可以向串口,蓝牙以及自身的事件监听单元发送一个广播,参数:

  • str 广播的内容。
程序示例:
import codey
import event

@event.button_a_pressed
def button_a_cb():
    print("button a event succeeded")
    codey.broadcast("hello")

@event.received("hello")
def received_cb():
    print("received message: hello")
codey_external_module_detect --- 模块接入检测

codey_external_module_detect 模块的主要功能与函数(因为是系统函数,所以使用时不需要带模块名称)

功能相关函数
codey.has_neuron_connected()

检测是否有任何神经元模块接入小程,返回值是布尔值,其中 True 表示有神经元模块接入了小程(包括小奔的接入),False 表示没有任何神经元模块的接入。

codey.is_rocky_connected()

检测小奔是否接入小程,返回值是布尔值,其中 True 表示有小奔接入了小程,False 表示小奔没有接入。

程序示例:
import codey
import time

while True:
    if codey.is_rocky_connected():
        print("rocky is in")
    else:
        print("rocky is out")
    time.sleep(1)
codey_script_control --- 脚本/线程控制

codey_script_control 模块的主要功能与函数(因为是系统函数,所以使用时不需要带模块名称)

功能相关函数
codey.stop_this_script()

停止当前脚本,和scratch停止脚本功能一致。

codey.stop_other_scripts()

停止其他脚本,和scratch停止其他脚本功能一致。

codey.stop_this_script()

停止所有脚本,和scratch停止所有脚本功能一致。

程序示例:
import codey
import time
import event

@event.start
def start_cb():
    while True:
        print("start cb executing...")
        time.sleep(1)
        print("stop this script")
        codey.stop_this_script()

@event.button_a_pressed
def button_a_cb():
    codey.stop_other_scripts()
    while True:
        print("button a event")

@event.button_b_pressed
def button_b_cb():
    codey.stop_other_scripts()
    while True:
        print("button b event")

@event.button_c_pressed
def button_c_cb():
    codey.stop_all_scripts()
event --- 事件处理单元

event 模块的主要功能与函数

事件处理单元使用说明

用户事件的使用方式目前支持两种写法,一种为注册方式:

import codey
import time
import event

def start_cb():
    while True:
        codey.led.show(255, 0, 0)
        time.sleep(1)
        codey.led.show(0, 0, 0)
        time.sleep(1)
event.start(start_cb)

另一种是使用修饰器的写法,如:

import codey
import time
import event

@event.start

def start_callback():
    while True:
        codey.led.show(255, 0, 0)
        time.sleep(1)
        codey.led.show(0, 0, 0)
        time.sleep(1)
功能相关函数
event.start(callback)

开机启动事件。

event.shaked(callback)

小程被摇晃事件。

event.received(callback, msgstr)

广播接收事件, 除了回调参数之外,参数:

  • msgstr 字符串类型,要匹配的字符串,当收到的字符串和匹配字符串一致时,会触发该事件。
event.button_a_pressed(callback)

按键A被按下事件。

event.button_b_pressed(callback)

按键B被按下事件。

event.button_c_pressed(callback)

按键C被按下事件。

event.tilted_left(callback)

小程左倾斜事件。

event.tilted_right(callback)

小程右倾斜事件。

event.ears_up(callback)

小程耳朵向上事件。

event.ears_down(callback)

小程耳朵向下事件。

event.ir_received(callback, ir_str)

红外字符串接收检测事件,除了回调参数之外,参数:

  • ir_str 字符串类型,要匹配的字符串,当收到的字符串和匹配字符串一致时,会触发该事件。
event.greater_than(callback, threshold, type_str)

阈值比较事件,超过阈值则触发,除了回调参数之外,参数:

  • threshold 数值数据,设置触发的阈值。
  • type_str 字符串数据,目前只支持 sound_sensor:音量传感器,timer:计时器。
event.less_than(callback, threshold, type_str)

阈值比较事件,低于阈值则触发,除了回调参数之外,参数:

  • threshold 数值数据,设置触发的阈值。
  • type_str 字符串数据,目前只支持 light_sensor:光线传感器。
程序示例:
import codey
import event

@event.button_a_pressed
def button_a_cb():
    print("button a event triggered")

@event.button_b_pressed
def button_b_cb():
    print("button b event triggered")

@event.button_c_pressed
def button_c_cb():
    print("button c event triggered")

@event.greater_than(20, "sound_sensor")
def sound_sensor_cb():
    print("sound sensor greater event triggered")

@event.greater_than(5, "timer")
def timer_cb():
    print("timer greater event triggered")

@event.less_than(30, "light_sensor")
def light_sensor_cb():
    print("light sensor event triggered")

小奔的python接口

小奔的python接口API如下:

小奔的python接口列表

motion --- 小奔底盘移动

motion 模块的主要功能与函数(因为是系统函数,所以使用时不需要带模块名称)

功能相关函数
rocky.stop()

小奔停止运动。

rocky.forward(speed, t = None, straight = False)

小奔向前运动,参数:

  • speed 运动速度的数值,参数范围 -100 ~ 100,负数代表后退,正数代表前进。
  • t 运动时间的数值,单位为 ,参数范围 0 ~ 数值范围极限,如果设置为 1,代表小车往前运动 1s就会停下来。 如果不设置该参数,在没有停止运动或者新的运动指令之前,维持前进状态。
  • straight 是否使能陀螺仪对行进方向的校正,如果不设置该参数,则默认不启用。
rocky.backward(speed, t = None, straigh = False)

小奔向后运动,参数:

  • speed 运动速度的数值,参数范围 -100 ~ 100,负数代表前进,正数代表后退。
  • t 运动时间的数值,单位为 ,参数范围 0 ~ 数值范围极限,如果设置为 1,代表小车往后运动 1s就会停下来。 如果不设置该参数,在没有停止运动或者新的运动指令之前,维持后退状态。
  • straight 是否使能陀螺仪对行进方向的校正,如果不设置该参数,则默认不启用。
rocky.turn_left(speed, t = None)

小奔向左转,参数:

  • speed 转向快慢程度的数值,参数范围 -100 ~ 100,负数代表右转,正数代表左转。
  • t 运动时间的数值,单位为 ,参数范围 0 ~ 数值范围极限,如果设置为 1,代表小车左转 1s就会停下来。 如果不设置该参数,在没有停止运动或者新的运动指令之前,维持左转状态。
rocky.turn_right(speed, t = None)

小奔向右转,参数:

  • speed 转向快慢程度的数值,参数范围 -100 ~ 100,负数代表左转,正数代表右转。
  • t 运动时间的数值,单位为 ,参数范围 0 ~ 数值范围极限,如果设置为 1,代表小车右转 1s就会停下来。 如果不设置该参数,在没有停止运动或者新的运动指令之前,维持右转状态。
rocky.drive(left_power, right_power)

小奔电机按照设定的数值转动,参数:

  • left_power 左轮电机的运动速度,参数范围 -100 ~ 100,负数代表左轮向后转动,正数代表左轮向前转动。
  • right_power 右轮电机的运动速度,参数范围 -100 ~ 100,负数代表右轮向后转动,正数代表右轮向前转动。
rocky.turn_right_by_degree(angle, speed = 40)

小奔按照设定的角度值右转,参数:

  • angle 代表转动的角度,负数代表左转,正数代表右转。
  • speed 在何种速度下进行转弯,参数范围 0 ~ 100; 如果不设置该参数,速度默认为40。(由于拐弯使用陀螺仪作为传感器,建议不要修改速度,避免转弯角度不准)
rocky.turn_left_by_degree(angle, speed = 40)

小奔按照设定的角度值左转,参数:

  • angle 代表转动的角度,负数代表右转,正数代表左转。
  • speed 在何种速度下进行转弯,参数范围 0 ~ 100; 如果不设置该参数,速度默认为40。(由于拐弯使用陀螺仪作为传感器,建议不要修改速度,避免转弯角度不准)
程序示例:
import codey
import rocky
import time

rocky.forward(50, 1)
rocky.stop()
rocky.backward(50, 1)
rocky.turn_left(50, 1)
rocky.turn_right(50, 1)
rocky.drive(50, 80)
time.sleep(2)
while True:
    rocky.turn_right_by_degree(80, 40)
    rocky.turn_right_by_degree(80, 20)
color_ir_sensor --- 颜色红外传感器

color_ir_sensor 模块的主要功能与函数

颜色红外传感器说明
_images/11.png

如图所示,小奔前方的传感器分别为

  • 白光 LED:发出白光,配合可见光传感器可以探测物体表面的可见光反射强度。
  • 可见光光线传感器:探测可见光的强度。
  • RGB LED:按照设定RGB数值发出光线,配合可见光传感器识别颜色。
  • 红外光光线传感器:探测红外光线的强度。
  • 红外发射器:发射红外光线,配合红外光光线传感器可以探测物体表面的红外光反射强度。
功能相关函数
color_ir_sensor.get_red()

获取颜色传感器的红色色值分量的大小,参数范围是 0 ~ 100

color_ir_sensor.get_green()

获取颜色传感器的绿色色值分量的大小,参数范围是 0 ~ 100

color_ir_sensor.get_blue()

获取颜色传感器的蓝色色值分量的大小,参数范围是 0 ~ 100

color_ir_sensor.is_color(color_str)

判断是否检测到匹配的颜色,参数:

  • color_str 颜色类型,包括 红、绿、蓝、黄、青、紫、白、黑,对应的参数是 redgreenblueyellowpurplecyanwhiteblack,返回数值为布尔值,Ture 为颜色匹配,False 为颜色不匹配。
color_ir_sensor.get_light_strength()

获取可见光传感器的检测到的环境光强度,数值范围 0 ~ 100

color_ir_sensor.get_greyness()

获取可见光传感器的检测到的灰度值(使用RGB和可见光传感器),数值范围 0 ~ 100

color_ir_sensor.get_reflected_light()

获取可见光传感器的检测到的可见光反射强度(使用白灯和可见光传感器),数值范围 0 ~ 100

color_ir_sensor.get_reflected_infrared()

获取红外光接收管检测到的红外光反射强度,数值范围 0 ~ 100

color_ir_sensor.is_obstacle_ahead()

检测前方是否有障碍物,返回值为布尔值,Ture 为有障碍物,False 为没有障碍物。

color_ir_sensor.set_led_color(color_name)

设置颜色传感器中 RGB LED灯的颜色: 参数:

  • color_name 包括 红、绿、蓝、黄、青、紫、白、黑,对应的参数是 redgreenblueyellowpurplecyanwhiteblack
程序示例:
import codey
import rocky

while True:
    if rocky.color_ir_sensor.is_obstacle_ahead():
        rocky.color_ir_sensor.set_led_color('white')
    else:
      rocky.color_ir_sensor.set_led_color('black')

第三方类库的python接口

第三方类库的python接口API如下:

第三方类库的python接口列表

urequests --- 网络请求模块

urequests 模块的主要功能与函数

功能相关函数
urequests.request(method, url, data=None, json=None, headers={})

发送网络请求, 它会阻塞返回网络的响应数据,参数:

  • method 建立网络请求的方法,例如 HEADGETPOSTPUTPATCH, DELETE
  • url 网络请求的URL(网址)。
  • *data*(可选)在请求正文中发送的字典或元组列表[(键,值)](将是表单编码的),字节或类文件对象。
  • *json*(可选)在请求正文中发送的json数据。
  • *headers*(可选)要与请求一起发送的HTTP标头字典。
urequests.head(url, **kw)

发送一个 HEAD 请求,返回类型是 request 的响应,参数:

  • url 网络请求的URL(网址)。
  • **kw request可选的参数
urequests.get(url, **kw)

发送一个 GET 请求,返回类型是 request 的响应,参数:

  • url 网络请求的URL(网址)。
  • **kw request可选的参数
urequests.post(url, **kw)

发送一个 POST 请求,返回类型是 request 的响应,参数:

  • url 网络请求的URL(网址)。
  • **kw request可选的参数
urequests.put(url, **kw)

发送一个 PUT 请求,返回类型是 request 的响应,参数:

  • url 网络请求的URL(网址)。
  • **kw request可选的参数
urequests.patch(url, **kw)

发送一个 PATCH 请求,返回类型是 request 的响应,参数:

  • url 网络请求的URL(网址)。
  • **kw request可选的参数
urequests.delete(url, **kw)

发送一个 DELETE 请求,返回类型是 request 的响应,参数:

  • url 网络请求的URL(网址)。
  • **kw request可选的参数
程序示例1:
import codey
import urequests as requests
import time

# 此处需填入自己路由器的 ssid 和 密码
codey.wifi.start('wifi_ssid', 'password')
codey.led.show(0,0,0)
while True:
    if codey.wifi.is_connected():
        codey.led.show(0,0,255)
        res = requests.get(url='http://www.baidu.com/')
        print(res.text)
        time.sleep(3)
    else:
        codey.led.show(0,0,0)
程序示例2:
import codey
import urequests as requests
import time

# 此处需填入自己路由器的 ssid 和 密码
codey.wifi.start('wifi_ssid', 'password')
codey.led.show(0,0,0)
hour = minite = second = "00"
while True:
    if codey.wifi.is_connected():
        try:
            res = requests.get(url = 'http://www.time.ac.cn/timeflash.asp?user=flash').text
            hour_begin = res.find('<hour>') + len('<hour>')
            hour_end = res.find('</hour>')
            minite_begin = res.find('<minite>') + len('<minite>')
            minite_end = res.find('</minite>')
            second_begin = res.find('<second>') + len('<second>')
            second_end = res.find('</second>')
            if hour_begin > len('<hour>') and hour_end > hour_begin and \
               minite_begin > len('<minite>') and minite_end > minite_begin and \
               second_begin > len('<second>') and second_end > second_begin:

                if hour_end - hour_begin == 1:
                    hour = '0' + res[hour_begin:hour_end]
                elif hour_end - hour_begin == 2:
                    hour = res[hour_begin:hour_end]

                if minite_end - minite_begin == 1:
                    minite = '0' + res[minite_begin:minite_end]
                elif minite_end - minite_begin == 2:
                    minite = res[minite_begin:minite_end]

                if second_end - second_begin == 1:
                    second = '0' + res[second_begin:second_end]
                elif second_end - second_begin == 2:
                    second = res[second_begin:second_end]

                print(hour + ":" + minite + ":" + second)
                cur_time = hour + ':' + minite;
                codey.display.show(cur_time)
        except:
            print("get error data")
    else:
        codey.led.show(0,0,0)
程序示例3:
import codey
import urequests as requests
import ujson

# user_account 和 password 的账户信息就是mblock的账户
def get_user_request_header():
    post_data = ujson.dumps({ 'account': 'user_account', 'password': 'password'})
    request_url = 'http://passport2.makeblock.com/v1/user/login'
    res = requests.post(request_url, headers = {'content-type': 'application/json'}, data = post_data).json()
    header_data = ''
    if res['code'] == 0:
        header_data = { "content-type": 'application/json; charset=utf-8', "devicetype": '1'}
        header_data["uid"] = str(res['data']['user']['uid'])
        header_data["deviceid"] = '30AEA427EC60'
    return header_data

# 获取天气信息
# cid: 检查站id
# arg: 需要查询的信息
#            aqi:  空气质量指数
#            pm25: PM2.5浓度
#            pm10: PM10浓度
#            co:   一氧化碳浓度
#            so2:  二氧化硫浓度
#            no2:  二氧化氮浓度
deget_air_quality_info(cid, arg):
  if not codey.wifi.is_connected():
        return ''
    post_data = ujson.dumps({ "cid": cid, "arg": arg})
    request_url = 'http://msapi.passport3.makeblock.com/' + 'air/getone'
    res = requests.post(request_url, headers = get_user_request_header(), data = post_data)
    text = res.text
    return float(text)

# 此处需填入自己路由器的 ssid 和 密码
codey.wifi.start('wifi_ssid', 'password')
codey.led.show(0,0,0)
while True:
    if codey.wifi.is_connected():
        codey.led.show(0,0,255)
        data = get_air_quality_info('1539','aqi')  #1539 表示深圳测试点
        codey.display.show(data)
    else:
        codey.led.show(0,0,0)
mqtt --- 消息队列遥测传输

mqtt 模块的主要功能与函数

功能相关函数
class mqtt.MQTTClient(client_id, server, port=0, user=None, password=None, keepalive=0, ssl=False, ssl_params={})

实例化MQTT客户端的接口对象,参数:

  • client_id 连接到代理时使用的唯一客户端ID字符串,如果client_id为零长度或无,则将随机生成一个。在这种情况下,connect 函数的clean_session参数必须为True。
  • server 远程服务器的主机名或IP地址。
  • *port*(可选)要连接的服务器主机的网络端口。 默认为1883,请注意,MQTT over SSL / TLS的默认端口是8883。
  • *user*(可选)在服务器上注册的用户名。
  • *password*(可选)在服务器上注册的密码。
  • *keepalive*(可选)客户端的keepalive超时值。 默认为60秒。
  • *ssl*(可选)是否使能 SSL/TLS 支持。
  • *ssl_params*(可选)SSL/TLS 参数。
connect(clean_session=True)

将客户端连接到服务器。 这是一个阻塞函数,参数:

  • clean_session 一个确定客户端类型的布尔值。 如果为 True,服务器将在断开连接时删除有关此客户端的所有信息。 如果为 False,则客户端是持久客户端,并且当客户端断开连接时,将保留订阅信息和排队消息。
reconnect()

使用先前提供的详细信息重新连接到服务器。 在调用此函数之前,您必须调用 connect

disconnect()

与服务器断开连接。

ping()

测试客户端与服务器的连通性。

set_last_will(topic, msg, retain=False, qos=0)

设置要发送给服务器的遗嘱。 如果客户端断开而没有调用 disconnect(),服务器将代表它发布消息。

  • topic 该遗嘱消息发布的主题。
  • msg 要发送的遗嘱消息。
  • retain 如果设置为 True,遗嘱消息将被设置为该主题的 最后已知良好 /保留消息。
  • qos 用于遗嘱的服务质量等级。
publish(topic, msg, retain=False, qos=0)

从客户端向代理发送消息,然后从代理发送到订阅匹配主题的任何客户端。 参数:

  • topic 应该发布消息的主题。
  • msg 要发送的实际消息。
  • retain 如果设置为 True,遗嘱消息将被设置为该主题的 最后已知良好 /保留消息。
  • qos 要使用的服务质量水平。
subscribe(topic, qos=0)

订阅服务的某个主题,该模块提供了一些辅助函数,可以直接订阅和处理消息。例如 set_callback

  • topic 要订阅消息的主题。
  • qos 要使用的服务质量水平。
set_callback(f)

设置主题订阅的回调函数,当服务器响应我们的订阅请求时调用。参数:

  • f 回调函数。
wait_msg()

等待服务器直到服务器无待处理消息。该函数是阻塞函数。

check_msg()

检查服务器是否有待处理消息。如果没有,直接返回,如果有的话,同 wait_msg 的处理。

程序示例一:
from mqtt import MQTTClient
import codey
import time

MQTTHOST = "mq.makeblock.com"
MQTTPORT = 1883

# 任意填写
client_id = "20180911203800"

# 示例
Topic = "/sensors/temperature/#"

mqttClient = MQTTClient(client_id, MQTTHOST, port=MQTTPORT, user='test', password='test', keepalive=0, ssl=False)

# 连接MQTT服务器
def on_mqtt_connect():
    mqttClient.connect()

# 发布消息
def on_publish(topic, payload, retain=False, qos = 0):
    mqttClient.publish(topic, payload, retain, qos)

# 消息处理函数
def on_message_come(topic, msg):
    print(topic + " " + ":" + str(msg))
    codey.display.show(msg)

# subscribe 消息
def on_subscribe():
    mqttClient.set_callback(on_message_come)
    mqttClient.subscribe(Topic, qos = 1)

# 此处填入自己家的wiif账户和密码
codey.wifi.start('wifi_ssid', 'password')
codey.led.show(0,0,0)
codey.display.show(0)
while True:
    if codey.wifi.is_connected():
        on_mqtt_connect()
        on_subscribe()
        codey.led.show(0,0,255)
        while True:
            # Blocking wait for message
            on_publish("/sensors/temperature/home", str(38), qos = 1)
            mqttClient.wait_msg()
            time.sleep(1)
    else:
        codey.led.show(0,0,0)
程序示例二:
# -*- coding: utf-8 -*-
import haloboard
from mqtt import MQTTClient
import time
import event

MQTTHOST = "mq.makeblock.com"
MQTTPORT = 1883
client_id = "another client"

# QoS Level 0:至多一次
# QoS Level 1:至少一次,有可能重复
# QoS Level 2:只有一次,确保消息只到达一次

mqttClient = MQTTClient(client_id, MQTTHOST, port=MQTTPORT, user='YanMinge', password='YanMinge', keepalive=60, ssl=False)

# 连接MQTT服务器
def on_mqtt_connect():
    mqttClient.connect()

# publish 消息
def on_publish(topic, payload, retain=False, qos = 0):
    mqttClient.publish(topic, payload, retain, qos)

# 消息处理函数
def on_message_come(topic, msg):
    print(topic + " " + ":" + str(msg))


# subscribe 消息
def on_subscribe(Topic):
    mqttClient.set_callback(on_message_come)
    mqttClient.subscribe(Topic, qos = 0)

def sub_cb(topic, msg):
    print((topic, msg))


@event.start
def use_code():
    haloboard.wifi.start('Maker-guest', 'makeblock')
    haloboard.led.show_all(0,0,0)
    while True:
        if haloboard.wifi.is_connected():
            print("wifi connected!!!")
            on_mqtt_connect()
            on_subscribe("/cloud_message")
            haloboard.led.show_all(0,0,255)
            while True:
                mqttClient.wait_msg()
                on_publish("/cloud_message", "Yan")
                on_publish("/test_message2", "Yan 2")
                time.sleep(3)

        else:
            haloboard.led.show_all(0,0,0)
random --- 获取随机数模块

random 模块的主要功能与函数

功能相关函数
random.random()

用于生成一个0到1的随机符点数: 0 <= n < 1.0

random.uniform(a, b)

用于生成一个指定范围内的随机符点数,两个参数其中一个是上限,一个是下限。如果a > b,则生成的随机数n: a <= n <= b。如果 a <b, 则 b <= n <= a。参数:

  • a 上限/下限
  • b 上限/下限

参考代码如下:

print random.uniform(10, 20)
print random.uniform(20, 10)
# 18.7356606526
# 12.5798298022
random.randint(a, b)

用于生成一个指定范围内的整数。其中参数a是下限,参数b是上限,生成的随机数n: a <= n <= b。

  • a 下限
  • b 上限

参考代码如下:

print random.randint(12, 20)  # 生成的随机数 n: 12 <= n <= 20
print random.randint(20, 20)  # 结果永远是20
# print random.randint(20, 10)  # 该语句是错误的。下限必须小于上限
random.randrange([start, ]stop[, step])

从指定范围内,按指定基数递增的集合中 获取一个随机数。如:random.randrange(10, 100, 2),结果相当于从[10, 12, 14, 16, ... 96, 98]序列中获取一个随机数。

  • start 指定的基数
  • stop 上限
  • step 递增单位
random.choice(sequence)

从序列中获取一个随机元素。 参数:

  • sequence 表示一个有序类型。

参考代码如下:

print random.choice("学习Python")
print random.choice(["JGood", "is", "a", "handsome", "boy"])
print random.choice(("Tuple", "List", "Dict"))
random.shuffle(x[, random])

用于将一个列表中的元素打乱。参数

  • x 需要被打乱的列表。

参考代码如下:

p = ["Python", "is", "powerful", "simple", "and so on..."]
random.shuffle(p)
print p
# ['powerful', 'simple', 'is', 'Python', 'and so on...']
random.sample(sequence, k)

从指定序列中随机获取指定长度的片断,同时sample函数不会修改原有序列。参数:

  • sequence 序列
  • k 片断长度

参考代码如下:

list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
slice = random.sample(list, 5)  # 从list中随机获取5个元素,作为一个片断返回
print slice
print list  # 原有序列并没有改变
程序示例:
import time
import random

while True:
    x = int(random.randint(200, 600))
    print("x is:", x)
    time.sleep(1)

神经元扩展模块的python接口

神经元扩展模块的python接口API如下:

神经元扩展模块的python接口列表

dc_motor_driver --- 双直流电机驱动模块

dc_motor_driver 模块的主要功能与函数

功能相关函数
dc_motor_driver.set_power(speed, ch = 0)

设置双路直流电机各路电机的动力,参数:

  • speed 控制目标电机的动力值,参数范围是 -100 ~ 100
  • ch 控制的电机通道,参数范围是 0 ~ 2,其中 0 表示两路电机通道,1 表示插槽1通道,2 表示插槽2通道。
程序示例:
import codey
import neurons
import event

@event.button_a_pressed
def on_button_a_pressed():
    print("button a event succeeded")
    neurons.dc_motor_driver.set_power(100, 1)

@event.button_b_pressed
def on_button_b_pressed():
    print("button b event succeeded")
    neurons.dc_motor_driver.set_power(100, 2)

@event.button_c_pressed
def on_button_c_pressed():
    print("button c event succeeded")
    neurons.dc_motor_driver.set_power(100, 0)
    neurons.dc_motor_driver.set_power(100, 1, 2)
servo_driver --- 双舵机驱动模块

servo_driver 模块的主要功能与函数

功能相关函数
servo_driver.set_angle(position, ch = 0)

设置双路舵机各路电机的动力,参数:

  • position 控制目标舵机的转动角度,参数范围是 0 ~ 180
  • ch 控制的舵机通道,参数范围是 0 ~ 2,其中 0 表示两路舵机通道,1 表示插槽1通道,2 表示插槽2通道。
程序示例:
import codey
import neurons
import event
import time

neurons.servo_driver.set_angle(0, 0)
time.sleep(1)

@event.button_a_pressed
def on_button_a_pressed():
    print("button a event succeeded")
    neurons.servo_driver.set_angle(100, 1)

@event.button_b_pressed
def on_button_b_pressed():
    print("button b event succeeded")
    neurons.servo_driver.set_angle(100, 2)

@event.button_c_pressed
def on_button_c_pressed():
    print("button c event succeeded")
    neurons.servo_driver.set_angle(100, 0)
led_strip --- 灯带驱动模块

led_strip 模块的主要功能与函数

功能相关函数
led_strip.set_single(index, red_value, green_value, blue_value)

设置灯带上单个灯的颜色, 参数:

  • index 设置第几个灯,参数范围是 1 ~ 灯带的最大灯珠数目
  • red_value 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
  • green_value 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
  • blue_value 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
led_strip.set_all(red_value, green_value, blue_value)

设置全部灯带的颜色, 参数:

  • red_value 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
  • green_value 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
  • blue_value 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
led_strip.set_effect(mode, speed, list)

设置灯条的灯效,参数:

  • mode 灯效的模式,参数范围是 0 ~ 5,其中

    0: 表示静态模式,按设定的颜色点亮前N个灯,未设置的灯珠处于熄灭状态。

    1: 表示滚动模式,按设定的颜色点亮前N个灯,按设定动态变化速度,N个灯图案,向后滚动,每次滚动一个灯,循环滚动。如下图:

    _images/23.png

    2: 表示重复模式,按设定的颜色点亮前N个灯,后面的灯重复前面N个灯的效果,直到最后一个灯。如下图:

    _images/31.png

    3: 表示跑马灯模式,重复的效果加上动态变化,按设定的动态变化速度,N个灯循环挪动。如下图:

    _images/41.png

    4: 表示呼吸灯模式,呼吸灯的变化速度按人的呼吸频率3秒1次。

    5: 表示渐变模式,整条灯带从原来的颜色渐变到新设定的颜色,变化间隔时间可设定。

  • speed 动态变化速度,参数范围是 0 ~ 8,0最慢,8最快。(只针对有动态变化的灯效的设置)。

  • list 可变参数列表,每个数值的参数范围是 0 ~ 8,第1个参数表示第一个灯的颜色,第2个参数表示第二个灯的颜色...,颜色的参数如下: 黑(0x00)红(0x01)橙(0x02)黄(0x03)绿(0x04)青(0x05)蓝(0x06)紫(0x07)白(0x08)

程序示例:
import codey
import neurons
import event
import time

neurons.led_strip.set_all(0, 0, 255)
time.sleep(1)

@event.button_a_pressed
def on_button_a_pressed():
    print("button a event successed")
    neurons.led_strip.set_all(0, 0, 0)
    neurons.led_strip.set_single(1, 255, 0, 0)
    time.sleep(1)
    neurons.led_strip.set_all(0, 0, 0)
    neurons.led_strip.set_single(2, 255, 0, 0)
    time.sleep(1)
    neurons.led_strip.set_all(0, 0, 0)
    neurons.led_strip.set_single(3, 255, 0, 0)
    time.sleep(1)

@event.button_b_pressed
def on_button_b_pressed():
    print("button b event successed")
    neurons.led_strip.set_effect(0, 8, (1,6,8,1,6,8,1,6,8))
    time.sleep(3)
    neurons.led_strip.set_effect(1, 8, (1,6,8,1,6,8,1,6,8))
    time.sleep(3)
    neurons.led_strip.set_effect(2, 8, (1,6,8,1,6,8,1,6,8))
    time.sleep(3)
    neurons.led_strip.set_effect(3, 8, (1,6,8,1,6,8,1,6,8))
    time.sleep(3)
    neurons.led_strip.set_effect(4, 8, (1,6,8,1,6,8,1,6,8))
    time.sleep(3)
    neurons.led_strip.set_effect(5, 8, (1,6,8,1,6,8,1,6,8))
    time.sleep(3)

@event.button_c_pressed
def on_button_c_pressed():
    print("button c event successed")
    neurons.led_strip.set_effect(0, 5, (1,1,1,1,1,1,1,1,1))
    time.sleep(3)
    neurons.led_strip.set_effect(1, 5, (1,1,1,1,1,1,1,1,1))
    time.sleep(3)
    neurons.led_strip.set_effect(2, 5, (1,1,1,1,1,1,1,1,1))
    time.sleep(3)
    neurons.led_strip.set_effect(3, 5, (1,1,1,1,1,1,1,1,1))
    time.sleep(3)
    neurons.led_strip.set_effect(4, 5, (1,1,1,1,1,1,1,1,1))
    time.sleep(3)
    neurons.led_strip.set_effect(5, 5, (1,1,1,1,1,1,1,1,1))
    time.sleep(3)
led_panel --- LED面板模块

led_panel 模块的主要功能与函数

功能相关函数
led_panel.set_all(red_value, green_value, blue_value)

设置并显示整个LED面板的颜色, 参数:

  • red_value 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
  • green_value 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
  • blue_value 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
led_panel.set_pixel(x, y, red_value, green_value, blue_value)

设置LED面板单个像素点的颜色,参数:

  • x 像素点在表情面板上x轴的坐标,参数范围是 0 ~ 7
  • y 像素点在表情面板上y轴的坐标,参数范围是 0 ~ 7
  • red_value 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
  • green_value 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
  • blue_value 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
led_panel.show_image(list, mode = 0)

以图片参数的方式设置显示的内容,参数:

  • list 可变参数列表,每个数值的参数范围是 0 ~ 8,第1个参数表示第一个灯的颜色,第2个参数表示第二个灯的颜色...,颜色的参数如下: 黑(0x00)红(0x01)橙(0x02)黄(0x03)绿(0x04)青(0x05)蓝(0x06)紫(0x07)白(0x08)
  • mode 显示内容的呈现方式,参数范围是 0 ~ 3,其中

0:表示显现模式,直接将设定的图案显示出来。

1:表示擦除模式,原图像按竖列逐渐消失,同时设定的图像按竖列逐渐显现出来。

2:表示左移模式,原图像向左移动消失,设定的图像向左移动显现出来

3:表示右移模式,原图像向右移动消失,设定的图像向右移动显现出来

led_panel.set_animation(frame_index, list)

设置LED面板的动画帧内容,参数:

  • frame_index 动画帧的帧序列,参数范围是 0 ~ 3,0表示第一帧。
  • list 可变参数列表,每个数值的参数范围是 0 ~ 8,第1个参数表示第一个灯的颜色,第2个参数表示第二个灯的颜色...,颜色的参数如下: 黑(0x00)红(0x01)橙(0x02)黄(0x03)绿(    04)青(0x05)蓝(0x06)紫(0x07)白(0x08)
led_panel.show_animation(frame_speed, mode)

显示 set_animation 设定的动画帧内容,参数:

  • frame_speed 动画帧的切换速度,参数范围是 0 ~ 2,其中

0:表示慢速,1秒的滚动间隔。

1:表示正常,0.5秒的滚动间隔。

2:表示快速,0.2秒的滚动间隔。

  • mode 帧变化的模式,参数范围是 0 ~ 3,其中

0:表示显现模式,直接将设定的图案显示出来。

1:表示擦除模式,原图像按竖列逐渐消失,同时设定的图像按竖列逐渐显现出来。

2:表示左移模式,原图像向左移动消失,设定的图像向左移动显现出来

3:表示右移模式,原图像向右移动消失,设定的图像向右移动显现出来

led_panel.show_string(red_value, green_value, blue_value, list)

按指定颜色显示字符串,参数:

  • red_value 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
  • green_value 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
  • blue_value 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
  • list 可变参数列表,第1个字符,第2个字符...
led_panel.clear()

清除面板的显示,即所有LED灯珠都熄灭。

程序示例:
import codey
import neurons
import event
import time

neurons.led_panel.clear()
neurons.led_panel.set_all(0, 0, 255)
time.sleep(1)
neurons.led_panel.clear()

@event.button_a_pressed
def on_button_a_pressed():
    print("button a event successed")
    neurons.led_panel.set_pixel(0, 0, 255, 0, 0)
    time.sleep(1)
    neurons.led_panel.set_pixel(4, 4, 255, 0, 0)
    time.sleep(1)
    neurons.led_panel.set_pixel(7, 7, 255, 0, 0)
    time.sleep(1)
    neurons.led_panel.set_pixel(0, 6, 255, 0, 0)
    time.sleep(1)

@event.button_b_pressed
def on_button_b_pressed():
    print("button b event successed")
    neurons.led_panel.show_image([1,6,8,0,0,0,1,6,8],0)
    time.sleep(1)
    neurons.led_panel.show_image([1,1,1,1,1,1,1,1,1],1)
    time.sleep(1)
    neurons.led_panel.show_image([6,6,6,6,6,6,6,6,6],2)
    time.sleep(1)
    neurons.led_panel.show_image([8,8,8,8,8,8,8,8,8],3)
    time.sleep(1)

@event.button_c_pressed
def on_button_c_pressed():
    print("button c event successed")
    neurons.led_panel.set_animation(0, (1,6,8,1,6,8,0,0,0))
    neurons.led_panel.set_animation(1, (6,6,6,6,6,6,6,6,6))
    neurons.led_panel.set_animation(2, [6,6,6,6,6,6,6,6,6])
    neurons.led_panel.set_animation(3, (8,8,8,8,8,8,8,8,8))
    neurons.led_panel.show_animation(1, 2)
    time.sleep(6)
    neurons.led_panel.show_string(255, 0, 0, "hello")
    time.sleep(4)
    neurons.led_panel.show_string(255, 0, 0, (100))
    time.sleep(4)
    neurons.led_panel.show_string(255, 0, 0, (1,2,3))
    time.sleep(4)
buzzer --- 蜂鸣器模块

buzzer 模块的主要功能与函数

功能相关函数
buzzer.play_note(note_num, beat = None)

播放音符, 数字音符定义请参考: scratch数字音符说明,参数:

  • note_num 数值型,数值范围 48 - 72,或者字符串类型,如 C4
  • beat 数值数据,表示节拍数,如果不填,则一直播放。

音符与频率的对应关系如下:

['C2','65'],   ['D2','73'],   ['E2','82'],   ['F2','87'],
['G2','98'],   ['A2','110'],  ['B2','123'],  ['C3','131'],
['D3','147'],  ['E3','165'],  ['F3','175'],  ['G3','196'],
['A3','220'],  ['B3','247'],  ['C4','262'],  ['D4','294'],
['E4','330'],  ['F4','349'],  ['G4','392'],  ['A4','440'],
['B4','494'],  ['C5','523'],  ['D5','587'],  ['E5','659'],
['F5','698'],  ['G5','784'],  ['A5','880'],  ['B5','988'],
['C6','1047'], ['D6','1175'], ['E6','1319'], ['F6','1397'],
['G6','1568'], ['A6','1760'], ['B6','1976'], ['C7','2093'],
['D7','2349'], ['E7','2637'], ['F7','2794'], ['G7','3136'],
['A7','3520'], ['B7','3951'], ['C8','4186'], ['D8','4699'],
buzzer.play_tone(frequency, time = None)

播放设定频率的声音,参数:

  • frequency 数值数据,播放声音的频率,其数值范围是 0 ~ 5000
  • time 数值数据,表示播放时间(单位是 毫秒-ms ),其数值范围是 0 ~ 数值范围极限
buzzer.rest(number)

停止节拍,参数:

  • number 数值数据,暂停的节拍数,其数值范围是 0 ~ 数值范围极限
常量
buzzer.tempo

数值数据,数值范围是 6 ~ 600,表示播放速度的属性,单位是 bmp(beat per minute),即每一个节拍的长度。 默认数值是60,即一个节拍的维持时间是1秒。 restplay_note 函数的节拍会受该常量影响。

程序示例:
import codey
import time
import neurons

codey.display.show("hello")

neurons.buzzer.play_note(48, 1)
neurons.buzzer.rest(1)
codey.display.show("note")
codey.display.clear()
neurons.buzzer.play_note("C4", 1)
neurons.buzzer.rest(1)
codey.display.show("C4")
codey.display.clear()
neurons.buzzer.play_tone(1000, 2)
neurons.buzzer.rest(1)
codey.display.show("tone")
codey.display.clear()

while True:
    neurons.buzzer.tempo = 60
    print("tempo:", end = "")
    print(neurons.buzzer.tempo)
    neurons.buzzer.play_note("C4", 1)
    neurons.buzzer.rest(2)
    neurons.buzzer.tempo = 240
    neurons.buzzer.play_note("C4", 1)
    neurons.buzzer.rest(2)
button --- 按钮模块

button 模块的主要功能与函数

功能相关函数
button.is_pressed()

获取按键的当前状态。 返回的结果是 True:按键被按下, 或者 False: 按键未被按下。

程序示例:
import codey
import neurons

while True:
    if neurons.button.is_pressed():
        print("pressed!")
funny_touch --- 触摸开关(四控)模块

funny_touch 模块的主要功能与函数

触摸开关(四控)使用说明
_images/16.png

触摸开关可以连接导电的物品(如香蕉、水),将它变成触摸开关。通过检测四色鳄鱼夹和地线的导通状态,实现简单有趣的交互效果。

如何使用:

  1. 将四色鳄鱼夹插到插槽 1,地线插到插槽 2。
  2. 用鳄鱼夹夹住一个导电物体。
  3. 抓住地线的金属夹子,同时用另一只手触摸导电物体,触摸开关相应指示灯亮起,模块将发出一个触发信号。

注:鳄鱼夹比较锋利,请不要用四色鳄鱼夹或地线夹子夹自己或他人,否则可能会造成伤害。

功能相关函数
funny_touch.is_red_touched()

四色鳄鱼夹的红色鳄鱼夹是否有被触摸(或者间接触摸),返回的结果是 True:被触摸了, 或者 False: 未被触摸。

funny_touch.is_green_touched()

四色鳄鱼夹的绿色鳄鱼夹是否有被触摸(或者间接触摸),返回的结果是 True:被触摸了, 或者 False: 未被触摸。

funny_touch.is_yellow_touched()

四色鳄鱼夹的黄色鳄鱼夹是否有被触摸(或者间接触摸),返回的结果是 True:被触摸了, 或者 False: 未被触摸。

funny_touch.is_blue_touched()

四色鳄鱼夹的蓝色鳄鱼夹是否有被触摸(或者间接触摸),返回的结果是 True:被触摸了, 或者 False: 未被触摸。

程序示例:
import codey
import time
import event
import neurons

@event.start
def start_cb():
    while True:
        if neurons.funny_touch.is_blue_touched():
            print("blue touched")
        if neurons.funny_touch.is_red_touched():
            print("red touched")
        if neurons.funny_touch.is_green_touched():
            print("green touched")
        if neurons.funny_touch.is_yellow_touched():
            print("yellow touched")

        time.sleep(0.1)
ultrasonic_sensor --- 超声波传感器模块

ultrasonic_sensor 模块的主要功能与函数

功能相关函数
ultrasonic_sensor.get_distance()

获取超声波传感器测量的前方障碍物的距离,单位是 厘米,返回的数据是浮点类型数值。 测量的范围是 3 ~ 300 厘米,3厘米以内的测量数据会不准确,数值的范围是 0 ~ 300 厘米。

程序示例:
import codey
import time
import event
import neurons

@event.start
def start_cb():
    while True:
        print(neurons.ultrasonic_sensor.get_distance())
        time.sleep(0.2)
gyro_sensor --- 陀螺仪传感器

gyro_sensor 模块的主要功能与函数

陀螺仪传感器说明

神经元模块的陀螺仪的坐标体系如下图所示:

_images/51.png
功能相关函数
gyro_sensor.get_roll()

获取姿态角的翻滚角,返回的数据范围是 -90 ~ 90

gyro_sensor.get_pitch()

获取姿态角的俯仰角,返回的数据范围是 -180 ~ 180

gyro_sensor.get_yaw()

获取姿态角的偏航角,返回的数据范围是 -32768 ~ 32767,由于板载的陀螺仪模块是六轴传感器,没有电子罗盘。 所以实际上偏航角只是使用了Z轴角速度的积分。它存在着积累误差。如果是想获得真实偏航角的,这个API不适合使用。

gyro_sensor.is_shaked()

检测神经元的陀螺仪模块是否有被摇晃,返回值是布尔值,其中 True 表示陀螺仪模块被晃动了,False 表示陀螺仪模块未被晃动。

gyro_sensor.get_acceleration(axis)

获取三个轴的加速度值,单位是 g,参数:

  • axis 字符串类型,以 xyz 代表陀螺仪模块定义的坐标轴。
gyro_sensor.get_gyroscope(axis)

获取三个轴的角速度值,单位是 °/秒,参数:

  • axis 字符串类型,以 xyz 代表陀螺仪模块定义的坐标轴。
程序示例1:
import rocky
import event
import neurons

@event.button_a_pressed
def on_button_a_callback():
    codey.stop_other_scripts()
    codey.display.show("pit")
    while True:
        print(neurons.gyro_sensor.get_pitch())
        time.sleep(0.05)

@event.button_b_pressed
def on_button_b_callback():
    codey.stop_other_scripts()
    codey.display.show("rol")
    while True:
        print(neurons.gyro_sensor.get_roll())
        time.sleep(0.05)

@event.button_c_pressed
def on_button_c_callback():
    codey.stop_other_scripts()
    codey.display.show("yaw")
    while True:
        print(neurons.gyro_sensor.get_yaw())
        time.sleep(0.05)
程序示例2:
import rocky
import event
import neurons

@event.start
def start_cb():
    codey.display.show("sha")
    while True:
        print(neurons.gyro_sensor.is_shaked())
        time.sleep(0.2)
程序示例3:
import rocky
import event
import neurons

@event.start
def start_cb():
    while True:
        print("gyro z:", end = "")
        print(neurons.gyro_sensor.get_gyroscope("z"))
        print("accel z:", end = "")
        print(neurons.gyro_sensor.get_acceleration("z"))
        time.sleep(0.2)
pir_sensor --- 人体红外传感器模块

pir_sensor 模块的主要功能与函数

功能相关函数
pir_sensor.is_activated()

获取传感器的检测结果。 返回的结果是 True:检测到附近有人, 或者 False: 未检测到活动的人。

程序示例:
import codey
import time
import event
import neurons

@event.start
def start_cb():
    while True:
        print(neurons.pir_sensor.is_activated())
        time.sleep(0.2)
soil_moisture --- 土壤湿度传感器模块

soil_moisture 模块的主要功能与函数

功能相关函数
soil_moisture.get_value()

获取传感器检测到的土壤湿度值,数值的范围是 0 ~ 100 数值越大,表示土壤湿度越高。

程序示例:
import codey
import time
import event
import neurons

@event.start
def start_cb():
    while True:
        print(neurons.soil_moisture.get_value())
        time.sleep(0.2)

程小奔的实例教程

本教程的目的是让您开始程小奔的使用。 我们需要你有一个小程或者一台程小奔,其次您还需要一根USB线(或者蓝牙dongle)可以连接到程小奔。 如果你是第一次使用程小奔的python编程,建议阅读一下这部分的内容。

程小奔 典型实例

程小奔的micropython使用说明

添加自定义类库或者代码文件

如何将自己编写的一些Python脚本,或者python的类库添加到固件中。

使用mblock5软件

可以下载和使用 mblock5 来进行python程序的编写以及程序的上传。

_images/42.png
  1. 如上图所示,打开mblock5软件后,连接好设备,并确定当前模式是 上传模式。
  2. 确定当前是 python 模式(默认是积木模式)
  3. 在代码编辑区编写自己的执行代码
  4. 点击 上传到设备 将代码烧录进小程。
使用firefly_upload脚本

可以下载和使用 firefly_upload 这个python脚本来进行python程序的上传。它除了可以上传 main.py, 也可以上传第三方或者自定义的类库以供 main.py调用。

下载地址: https://github.com/YanMinge/firefly_upload

_images/52.png
  1. 下载脚本,该脚本可以支持 python2 和 python3 环境下的使用。
  2. 因为上传会使用到串口,所以需要安装 pyserial 的库,最好是用 pip 安装 pip install pyserial
  3. 因为上传使用了一个进度条的工具,所以需要安装 progressbar2 的库,最好是用 pip 安装 pip install progressbar2
  4. 在 shell 或者 cmd 界面 输入 在shell 中输入 python firefly_upload.py -p [串口名称] -i [文件的路径] -o [文件烧入flash的路径] 如windows示例: python firefly_upload.py -p COM5 -i C:/Users/MBENBEN/Desktop/test/main.py -o /flash/main.py

使用mpy-cross工具生成mpy文件

版权声明:文本编辑整理属于Yanminge,转载时请以超链接形式标明文章原始出处和作者信息及本声明

接触过Python语言的人都知道,Python可以编译成.pyc文件,它是一种二进制文件,可以提高程序的加载速度,同时也是一种保护源代码的有效方法。 在micropython中,也提供了类似的功能,可以将.py文件编译成.mpy文件。接下来,介绍一下具体的实现步骤。(本文以 mingw32 工具链为例, 使用小程作为目标主板)

搭建micropython编译环境

注意: 在不同的系统环境以及不同的目标主板,micropython的开发环境安装是有差别的,这里仅以乐鑫esp32的mingw32工具链作为示意。我们需要用到它的 xtensa-esp32-elf

  1. 参考乐鑫 设置工具链,以 windows系统为例,可以从乐鑫的官网下载 Windows all-in-one工具链 & MSYS2 zip包,将zip文件解压缩到C盘的根目录(也可以是其他一些位置,但本文档假定为 C:\ ),它将创建一个带有预先准备好的环境的msys32目录。
  2. 下载micropython源码包到本地,我下载到了G盘的根目录下。
生成mpy文件
  1. 执行msys32目录中的 mingw32.exe 切换到 /g/micropython/mpy-cross 目录执行make,编译生成mpy-cross工具。
_images/17.png _images/24.png
  1. 在mpy-cross目录新建一下main.py文件,以小程为例,写一个测试程序用于验证。
import codey
import time

codey.led.show(2555,255,255)
time.sleep(2)
codey.led.off()
time.sleep(2)
while True:
    codey.led.set_red(255)
    time.sleep(1)
    codey.led.set_green(255)
    time.sleep(1)
    codey.led.set_blue(255)
    time.sleep(1)
    codey.led.off()
    time.sleep(1)
  1. 执行编译mpy文件的命令。

其他相关功能可查看同目录下的README.md文件。

  1. 命令执行成功后,你就能发现同目录下出现了一个main.mpy文件。
_images/32.png
  1. 将 main.mpy 文件拷贝放到小程的flash中,如果是 main文件名的话,小程会自动运行。
烧录 *.py 或者 *.mpy 文件的说明见

注意: 如果运行时出现“ValueError: invalid .mpy file”错误的话,需要更新一下主板的micropython固件(最新固件跟随mblock最新版本发布)。

光环板的python接口

本章介绍了光环板的python接口,一共包含以下几类模块:

  • 光环板的python接口:主要是指光环板板载驱动的一些API接口。
  • 第三方类库的python接口:光环板内置的一些第三方类库的接口类,例如mqtt、urequest的类。
  • 神经元扩展模块的python接口:光环板扩展神经元模块时的一些API接口。

光环板的python接口

光环板python接口的API如下:

光环板的python接口分类

broadcast 接口列表
broadcast --- 广播消息

broadcast 模块的主要功能与函数

功能相关函数
broadcast.broadcast(message_str)

广播消息,广播消息后,其他线程可以接收到消息,参数:

  • message_str 字符串类型,消息值
程序示例:
# -*- coding: utf-8 -*-
import haloboard
import time
import event

@event.button_pressed
def on_button_a_pressed():
    print("button is pressed")
    haloboard.broadcast("hello")

@event.received("hello")
def received_cb():
    print("received message: hello")
haloboard.mesh --- mesh广播消息

haloboard.mesh 模块的主要功能与函数

功能描述

该模块主要介绍基于mesh网络模块的函数API

功能相关函数
haloboard.mesh.start(type = "node")

启动mesh通讯,参数:

  • type 指mesh网络中的类型,可以为root或者node,默认为node。

# mesh boardcast

haloboard.mesh.get_number_of_nodes()

获取目前mesh网络中node的数量(仅限于root?)。

haloboard.mesh.on_mesh_message_come(msg)

处理mesh消息。

  • msg 当前需要处理的mesh消息。
haloboard.mesh.get_info(msg)

获取mesh消息的info信息。

  • msg 当前需要处理的mesh消息。
haloboard.mesh.get_info_status(msg)

获取mesh消息当前状态(status)

  • msg 当前需要处理的mesh消息。

# for online mode

haloboard.mesh.get_all_info_status()

获取所有mesh消息的当前状态

haloboard.mesh.get_info_once(msg)

单次获取mesh消息的info信息。

  • msg 当前需要处理的mesh消息。
程序示例一:
# -*- coding: utf-8 -*-
# as a node
import haloboard
import time
import event

count = 0

@event.start
def on_start():
    haloboard.mesh.start(type = "node")

@event.button_pressed
def on_button_a_pressed():
    global count
    print("button is pressed")
    haloboard.mesh.broadcast("hello", str(count))
    count += 1

@event.mesh_message("hello")
def received_cb():
    print("received message: hello")
    print("value:", haloboard.mesh.get_info("hello"))
程序示例二:
# -*- coding: utf-8 -*-
# as a root
import haloboard
import time
import event

@event.start
def on_start():
    haloboard.mesh.start(type = "root")

@event.button_pressed
def on_button_a_pressed():
    print("button is pressed")
    haloboard.mesh.broadcast("hello", '123')

@event.mesh_message("hello")
def received_cb():
    print("received message: hello")
    print("value:", haloboard.mesh.get_info("hello"))
driver 接口列表
button --- 板载按键

button 模块的主要功能与函数

功能相关函数
button.is_pressed()

获取按键A当前状态。 返回的结果是 True:按键被按下, 或者 False: 按键未被按下。

程序示例:
import haloboard

def loop():
    while True:
        if haloboard.button.is_pressed():
            haloboard.led.show_all(255, 255, 255)
        else:
            haloboard.led.show_all(0, 0, 0)
loop()
clock --- 板载底板时钟模块

clock 模块的主要功能与函数

功能相关函数
clock.get_date_and_time(clock_id)
获取时间的值。
  • clock_id 时间类型参数,可以为小时:clock.HOUR_INDEX,分钟:clock.MINUTE_INDEX,秒:clock.SECOND_INDEX。
程序示例:
from haloboard import *
import time

minute = 0
hour = 0
count = 0
while True:
    hour = clock.get_date_and_time(clock.HOUR_INDEX)
    minute = clock.get_date_and_time(clock.MINUTE_INDEX)
    second = clock.get_date_and_time(clock.SECOND_INDEX)

    print("hour:%d, minute:%d, second:%d" %(hour, minute, second))
    time.sleep(1)
led --- 板载全彩LED灯

led 模块的主要功能与函数

功能相关函数
led.show_single(led_id, r, g, b)

设置单颗RGB LED灯的颜色,参数:

  • led_id 单颗LED的编号,参数范围是1-12,对应位置如下图:
_images/12.png
  • r 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。

  • g 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。

  • b 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。

    常用颜色RGB对应表:
    _images/21.png
led.show_all(r, g, b)

设置所有RGB LED灯为相同的颜色。

  • r 全彩LED红色分量的数值,参数范围是 0 ~ 255, 0为无红色分量,255是红色分量最亮。
  • g 全彩LED绿色分量的数值,参数范围是 0 ~ 255, 0为无绿色分量,255是绿色分量最亮。
  • b 全彩LED蓝色分量的数值,参数范围是 0 ~ 255, 0为无蓝色分量,255是蓝色分量最亮。
led.off_all()

熄灭所有LED灯。

led.clear()

熄灭所有LED灯,并打开灭灯标志 。

led.off_single(led_id)

熄灭单颗RGB LED,参数:

  • led_id 单颗LED的编号,参数范围是1-12。
led.show_ring(color_str, offset=0)

同时设置12颗RGB LED为相应的颜色,参数:

  • color_str 字符串类型,字符串格式需满足“color1 color2 color3 color4”, 其中colorx为"red"/"green"/"blue"/"yellow"/"cyan"/"purple"/"white"/"orange"/"black/"gray"颜色字符以单个空格隔开, 当颜色个数大于12时将被截断成12个。
  • offset 数值型,数值范围0-12。
led.ring_graph(percentage)

用LED灯环的状态显示百分比,参数:

  • percentage 数值型,数值范围0-100。
led.meteor_effect()

显示meteor灯效 。

led.rainbow_effect()

显示rainbow灯效 。

led.spoondrift_effect()

显示spoondrift灯效 。

led.firefly_effect()

显示firefly灯效 。

led.show_animation(name)

显示默认灯效,阻塞型,参数:

  • name 默认灯效名,有四种:spoondrift, meteor, rainbow, firefly。
程序示例一:
import haloboard
import time

haloboard.led.show_single(1, 255, 255,255)
time.sleep(2)
haloboard.led.show_single(2, 255, 0, 0)
time.sleep(2)
haloboard.led.show_single(3, 0, 255, 0)
time.sleep(2)
haloboard.led.show_single(4, 0, 0, 255)
time.sleep(2)
haloboard.led.show_all(255, 255, 255)
time.sleep(2)
while True:
    haloboard.led.off_single(1)
    time.sleep(1)
    haloboard.led.show_single(1, 255, 0, 0)
    time.sleep(1)
程序示例二:
import haloboard
import time

haloboard.led.show_single(1, 255, 255,255)
time.sleep(2)
haloboard.led.show_single(2, 255, 0, 0)
time.sleep(2)
haloboard.led.show_single(3, 0, 255, 0)
time.sleep(2)
haloboard.led.show_single(4, 0, 0, 255)
time.sleep(2)
haloboard.led.show_all(255, 255, 255)
time.sleep(2)
while True:
    haloboard.led.off_single(1)
    time.sleep(1)
    haloboard.led.show_single(1, 255, 0, 0)
    time.sleep(1)
程序示例三:
import haloboard
import time
import random

while True:
    for i in range(101):
        haloboard.led.ring_graph(i)
        time.sleep(0.1)
        print(i)

    for i in range(101):
        haloboard.led.ring_graph(100 - i)
        time.sleep(0.1)
        print(i)

    for i in range(13):
        haloboard.led.show_ring("green blue yellow purple cyan white green blue yellow purple cyan white", i)
        time.sleep(0.5)
程序示例四:
import haloboard
import time
import event

@event.touchpad0_active
def on_touchpad0_active():
    haloboard.stop_other_scripts()
    while True:
        haloboard.led.show_animation('spoondrift')

@event.touchpad1_active
def on_touchpad1_active():
    haloboard.stop_other_scripts()
    while True:
        haloboard.led.show_animation('meteor')

@event.touchpad2_active
def on_touchpad2_active():
    haloboard.stop_other_scripts()
    while True:
        haloboard.led.show_animation('rainbow')

@event.touchpad3_active
def on_touchpad3_active():
    haloboard.stop_other_scripts()
    while True:
        haloboard.led.show_animation('firefly')
motion_sensor --- 板载姿态传感器模块

motion_sensor 模块的主要功能与函数

板载姿态传感器模块说明:
_images/13.png

如上图所示,roll,pitch(翻滚角,俯仰角)的方向以右手螺旋定则为标准。 光环板水平放置时roll和pitch都为0°

  • roll 的范围:-90° ~ 90°
  • pitch 的范围:-180° ~ 180°
功能相关函数
motion_sensor.get_roll()

获取姿态角的翻滚角,返回的数据范围是 -90 ~ 90

motion_sensor.get_pitch()

获取姿态角的俯仰角,返回的数据范围是 -180 ~ 180

motion_sensor.get_yaw()

获取姿态角的偏航角,返回的数据范围是0 ~ 360,由于没有电子罗盘,所以实际上偏航角只是使用了Z轴角速 度的积分。它存在着积累误差。如果是想获得真实偏航角的,这个API不适合使用。

motion_sensor.get_acceleration(axis)

获取三个轴的加速度值,单位是 m/s^2,参数:

  • axis 字符串类型,以 x,y,z 代表光环板定义的坐标轴。
motion_sensor.get_gyroscope(axis)

获取三个轴的角速度值,单位是 °/秒,参数

  • axis 字符串类型,以 x,y,z 代表光环板定义的坐标轴。
motion_sensor.get_rotation(axis)

获得光环板在三个轴上转动的角度,以逆时针转动方向为正方向,参数:

  • axis 字符串类型,以 x,y,z 代表光环板定义的坐标轴。
motion_sensor.reset_rotation(axis = "all")

初始化绕三个轴转动的当前角度为0,get_rotation() 函数将从 0 开始计算,参数:

  • axis 字符串类型,以 x,y,z 代表光环板定义的坐标轴, all 代表全部的三个轴。也是这个函数的默认 值。
motion_sensor.is_tilted_left()

检测光环板是否向左倾斜,阈值15°,返回值是布尔值,其中 True 表示光环板向左倾斜了,False 表示光环板 未向左倾斜。

motion_sensor.is_tilted_right()

检测光环板是否向右倾斜,阈值15°,返回值是布尔值,其中 True 表示光环板向右倾斜了,False 表示光环板 未向右倾斜。

motion_sensor.is_arrow_up()

获取是否箭头是否朝上状态,阈值15°,返回值是布尔值,其中 True 表示箭头朝上,False 表示箭头没有朝 上。

motion_sensor.is_arrow_down()

获取是否箭头是否朝上状态,阈值15°,返回值是布尔值,其中 True 表示箭头朝下,False 表示箭头没有朝下。

motion_sensor.is_shaked()

检测光环板是否有被摇晃,返回值是布尔值,其中 True 表示光环板被晃动了,False 表示光环板未被晃动。

motion_sensor.is_led_ring_up()

检测LED灯环是否朝上状态,返回布尔值,其中True表示灯环朝上,False表示灯环未朝上。

motion_sensor.is_led_ring_down()

检测LED灯环是否朝下状态,返回布尔值,其中True表示灯环朝下,False表示灯环未朝下。

motion_sensor.get_shake_strength()

如果光环板被摇晃了,这个函数可以获得摇晃的强度,返回值的数值范围是 0 ~ 100, 数值越大,晃动的强度 就越大。

程序示例一:
import haloboard
import time

while True:
    acceleration_x = haloboard.motion_sensor.get_acceleration("x")
    acceleration_y = haloboard.motion_sensor.get_acceleration("y")
    acceleration_z = haloboard.motion_sensor.get_acceleration("z")
    print("acceleration_x:", end = "")
    print(acceleration_x, end = "")
    print("   ,acceleration_y:", end = "")
    print(acceleration_y, end = "")
    print("   ,acceleration_z:", end = "")
    print(acceleration_z)
    time.sleep(0.05)
程序示例二:
import haloboard
import time

while True:
    roll = haloboard.motion_sensor.get_roll()
    pitch = haloboard.motion_sensor.get_pitch()
    yaw = haloboard.motion_sensor.get_yaw()
    print("roll:", end = "")
    print(roll, end = "")
    print("   ,pitch:", end = "")
    print(pitch, end = "")
    print("   ,yaw:", end = "")
    print(yaw)
    time.sleep(0.05)
程序示例三:
import haloboard
import time

while True:
    gyroscope_x = haloboard.motion_sensor.get_gyroscope("x")
    gyroscope_y = haloboard.motion_sensor.get_gyroscope("y")
    gyroscope_z = haloboard.motion_sensor.get_gyroscope("z")
    print("gyroscope_x:", end = "")
    print(gyroscope_x, end = "")
    print("   ,gyroscope_y:", end = "")
    print(gyroscope_y, end = "")
    print("   ,gyroscope_z:", end = "")
    print(gyroscope_z)
    time.sleep(0.05)
程序示例四:
import haloboard
import time

while True:
    if haloboard.motion_sensor.is_tilted_left():
        print("tilted_left")
    if haloboard.motion_sensor.is_tilted_right():
        print("tilted_right")
    if haloboard.motion_sensor.is_arrow_up():
        print("arrow_up")
    if haloboard.motion_sensor.is_arrow_down():
        print("arrow_down")
程序示例五:
import haloboard
import time

while True:
    rotation_x = haloboard.motion_sensor.get_rotation("x")
    rotation_y = haloboard.motion_sensor.get_rotation("y")
    rotation_z = haloboard.motion_sensor.get_rotation("z")
    print("rotation_x:", end = "")
    print(rotation_x, end = "")
    print("   ,rotation_y:", end = "")
    print(rotation_y, end = "")
    print("   ,rotation_z:", end = "")
    print(rotation_z)
    time.sleep(0.05)
程序示例六:
import haloboard
import time

while True:
    if haloboard.motion_sensor.is_shaked():
        print("shake_strength:", end = "")
        print(haloboard.motion_sensor.get_shake_strength())
程序示例七:
import haloboard
import time

while True:
    if haloboard.motion_sensor.is_led_ring_up():
        print("led ring up")
    if haloboard.motion_sensor.is_led_ring_down():
        print("led ring down")

    time.sleep(0.3)
touchpad0 --- 触摸按键0

touchpad0 模块的主要功能与函数

功能相关函数
touchpad0.is_touched()

获取触摸按键0当前状态。返回的结果是 True:触摸按键0被触摸, 或者 False: 触摸按键0未被触摸。

touchpad0.get_value()

获取触摸按键被触摸状态。数值范围为0-10000。

touchpad0.set_touch_threshold()

设定触摸按键的阈值,参数:

  • val 触摸变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值范围为0-1。
程序示例:
import haloboard
import time

haloboard.touchpad0.set_touch_threshold(0.01 * 2)
haloboard.touchpad1.set_touch_threshold(0.01 * 2)
haloboard.touchpad0.set_touch_threshold(0.005 * 2)
haloboard.touchpad0.set_touch_threshold(0.015 * 2)
while True:
    if haloboard.touchpad0.is_touched():
        print("TouchPad 0 is touched!")
    if haloboard.touchpad1.is_touched():
        print("TouchPad 1 is touched!")
    if haloboard.touchpad2.is_touched():
        print("TouchPad 2 is touched!")
    if haloboard.touchpad3.is_touched():
        print("TouchPad 3 is touched!")

    print("val:" + str(haloboard.touchpad0.get_value()) + " ," + str(haloboard.touchpad1.get_value()) + " ," + str(haloboard.touchpad2.get_value()) + " ," + str(haloboard.touchpad3.get_value()))
    time.sleep(0.01)
touchpad1 --- 触摸按键1

touchpad1 模块的主要功能与函数

功能相关函数
touchpad1.is_touched()

获取触摸按键1当前状态。返回的结果是 True:触摸按键1被触摸, 或者 False: 触摸按键1未被触摸。

touchpad1.get_value()

获取触摸按键被触摸状态。数值范围为0-10000。

touchpad1.set_touch_threshold()

设定触摸按键的阈值,参数:

  • val 触摸变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值范围为0-1。
程序示例:
import haloboard
import time

haloboard.touchpad0.set_touch_threshold(0.01 * 2)
haloboard.touchpad1.set_touch_threshold(0.01 * 2)
haloboard.touchpad0.set_touch_threshold(0.005 * 2)
haloboard.touchpad0.set_touch_threshold(0.015 * 2)
while True:
    if haloboard.touchpad0.is_touched():
        print("TouchPad 0 is touched!")
    if haloboard.touchpad1.is_touched():
        print("TouchPad 1 is touched!")
    if haloboard.touchpad2.is_touched():
        print("TouchPad 2 is touched!")
    if haloboard.touchpad3.is_touched():
        print("TouchPad 3 is touched!")

    print("val:" + str(haloboard.touchpad0.get_value()) + " ," + str(haloboard.touchpad1.get_value()) + " ," + str(haloboard.touchpad2.get_value()) + " ," + str(haloboard.touchpad3.get_value()))
    time.sleep(0.01)
touchpad2 --- 触摸按键2

touchpad2 模块的主要功能与函数

功能相关函数
touchpad2.is_touched()

获取触摸按键2当前状态。返回的结果是 True:触摸按键2被触摸, 或者 False: 触摸按键2未被触摸。

touchpad2.get_value()

获取触摸按键被触摸状态。数值范围为0-10000。

touchpad2.set_touch_threshold()

设定触摸按键的阈值,参数:

  • val 触摸变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值范围为0-1。
程序示例:
import haloboard
import time

haloboard.touchpad0.set_touch_threshold(0.01 * 2)
haloboard.touchpad1.set_touch_threshold(0.01 * 2)
haloboard.touchpad0.set_touch_threshold(0.005 * 2)
haloboard.touchpad0.set_touch_threshold(0.015 * 2)
while True:
    if haloboard.touchpad0.is_touched():
        print("TouchPad 0 is touched!")
    if haloboard.touchpad1.is_touched():
        print("TouchPad 1 is touched!")
    if haloboard.touchpad2.is_touched():
        print("TouchPad 2 is touched!")
    if haloboard.touchpad3.is_touched():
        print("TouchPad 3 is touched!")

    print("val:" + str(haloboard.touchpad0.get_value()) + " ," + str(haloboard.touchpad1.get_value()) + " ," + str(haloboard.touchpad2.get_value()) + " ," + str(haloboard.touchpad3.get_value()))
    time.sleep(0.01)
touchpad3 --- 触摸按键3

touchpad3 模块的主要功能与函数

功能相关函数
touchpad3.is_touched()

获取触摸按键3当前状态。返回的结果是 True:触摸按键3被触摸, 或者 False: 触摸按键3未被触摸。

touchpad3.get_value()

获取触摸按键被触摸状态。数值范围为0-10000。

touchpad3.set_touch_threshold()

设定触摸按键的阈值,参数:

  • val 触摸变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值范围为0-1。
程序示例:
import haloboard
import time

haloboard.touchpad0.set_touch_threshold(0.01 * 2)
haloboard.touchpad1.set_touch_threshold(0.01 * 2)
haloboard.touchpad0.set_touch_threshold(0.005 * 2)
haloboard.touchpad0.set_touch_threshold(0.015 * 2)
while True:
    if haloboard.touchpad0.is_touched():
        print("TouchPad 0 is touched!")
    if haloboard.touchpad1.is_touched():
        print("TouchPad 1 is touched!")
    if haloboard.touchpad2.is_touched():
        print("TouchPad 2 is touched!")
    if haloboard.touchpad3.is_touched():
        print("TouchPad 3 is touched!")

    print("val:" + str(haloboard.touchpad0.get_value()) + " ," + str(haloboard.touchpad1.get_value()) + " ," + str(haloboard.touchpad2.get_value()) + " ," + str(haloboard.touchpad3.get_value()))
    time.sleep(0.01)
vibration_motor --- 震动电机

vibration_motor 模块的主要功能与函数

功能相关函数
vibration_motor.set_strength(val)

设置震动电机动力值,设置但不执行,参数:

  • val 数值范围0-100。
vibration_motor.on(value=None)

震动电机开始执行,若未设置参数,默认值是100,参数:

  • value 数值范围为0-100。
程序示例:
import haloboard
import time

while True:
    print("set_strength 100")
    haloboard.vibration_motor.set_strength(100)
    haloboard.vibration_motor.on(100)
    time.sleep(3)
    haloboard.vibration_motor.on(0)
    time.sleep(2)
    print("set_strength 50")
    haloboard.vibration_motor.set_strength(50)
    haloboard.vibration_motor.on()
    time.sleep(3)
microphone --- 板载麦克风

microphone 模块的主要功能与函数

功能相关函数
microphone.get_loudness(type)

获取声音的响度,参数:

  • type 字符串参数,一共有两个:average,获得一段时间内的响度平均值;maximum,获得一段时间内 响度的最大值,为默认参数。返回值范围为0-100。
程序示例:
import haloboard
import time
import event

@event.start
def on_start():
    while True:
        average = haloboard.microphone.get_loudness("average")
        maximum = haloboard.microphone.get_loudness("maximum")
        print("average:" + str(average), " ,maximum" + str(maximum))
        time.sleep(0.2)

@event.greater_than(20, 'microphone')
def on_greater_than():
    haloboard.led.show_all(10, 0, 0)
    time.sleep(0.2)
    haloboard.led.show_all(0, 0, 0)
speaker --- 板载扬声器

speaker 模块的主要功能与函数

常量
  • speaker.volume 数值数据,音量的大小的属性值,可以修改或者读取这个值。修改这个数值,可以控制音量的大小。其数值范围是 0 ~ 100。
  • speaker.tempo 数值数据,表示播放速度的属性,单位是 bmp (beat per minute),即每一个节拍的长度。 其数 值范围是 6 ~ 600。 默认数值是60,即一个节拍的维持时间是1秒。 rest 和 play_note 函数的节拍会受该常量影响
功能相关函数
speaker.stop_sound()

停止音频播放。

speaker.play_melody_until_done(file_name)

播放音频文件,该函数播放时阻塞,参数:

  • file_name 字符串类型,烧录在光环板flash中的wav格式的音频文件 名,输入时,也可省略格式的后缀 .wav。
speaker.play_melody(file_name)

播放音频文件,该函数播放时不阻塞,参数:

  • file_name 字符串类型,烧录在光环板flash中的wav格式的音频文 件名,输入时,也可省略格式的后缀 .wav。
speaker.play_tone(frequency, time_ms=None)

按频率播放音调,参数:

  • frequency 数值数据,播放声音的频率,其数值范围是0-1000。
  • time_ms 数值数据,表示播放时间(单位是 毫秒-ms ),不填此参数,则一直播放,否则阻塞播放。
speaker.play_note(note, beat=None)

播放音符, 数字音符定义请参考: scratch数字音符说明,参数:

  • note_num 数值型,数值范围 48 - 72,或者字符串类型,如 C4,将自动识别。

  • beat 数值数据,表示节拍数,如果不填,则一直播放。

    音符与频率的对应关系如下:
    _images/14.png
speaker.rest(beat)

扬声器停止/休息的节拍时间。

  • beat 数值型,指节拍数。
程序示例:
import haloboard
import time

haloboard.speaker.tempo = 60
haloboard.speaker.volume = 100
haloboard.speaker.play_melody_until_done("hello")
haloboard.speaker.play_note(48, 1)
haloboard.speaker.rest(1)
haloboard.speaker.play_note("C4", 1)
haloboard.speaker.rest(1)
haloboard.speaker.play_tone(1000, 2)
haloboard.speaker.rest(1)
print("tempo:", end = "")
print(haloboard.speaker.tempo)
print("volume:", end = "")
print(haloboard.speaker.volume)

haloboard.speaker.play_note("C4", 3)
haloboard.speaker.rest(1)
haloboard.speaker.tempo = 120
haloboard.speaker.volume = 20
haloboard.speaker.play_note("C4", 3)
haloboard.speaker.rest(1)
event 接口列表
event --- 事件模块

event 模块的主要功能与函数

两种写法

方法一:注册方式,如以下示例:

event.start(test_callback)
event.received(callback, 'hello')

方法二:修饰器写法,如以下示例:

@event.start
def start_callback():
print(123)
@event.received('hello')
def received_callback():
print(123)

注意:当函数有callback之外的其他参数时,需加上参数。

功能相关函数
event.start(callback)

启动事件,参数:

  • callback 回调函数。
event.shaked(callback)

摇晃事件,参数:

  • callback 回调函数。
event.button_pressed(callback)

按键按下事件,参数:

  • callback 回调函数。
event.tilted_left(callback)

左倾事件,参数:

  • callback 回调函数。
event.tilted_right(callback)

右倾事件,参数:

  • callback 回调函数。
event.arrow_up(callback)

前倾事件,参数:

  • callback 回调函数。
event.arrow_down(callback)

后倾事件,参数:

  • callback 回调函数。
event.receieved(callback, message_str)

广播事件,参数:

  • callback 回调函数。
  • message_str 监听的广播名称。
event.cloud_message(message)

云广播事件,参数:

  • message 字符串数据,广播的信息名称。
event.mesh_message(message)

mesh广播事件,参数:

  • message 字符串数据,广播的信息名称。
event.greater_than(callback, threshold, type_str)

阈值比较事件, 超过阈值则触发,参数:

  • callback 回调函数。
  • threshold 数值型,触发阈值。
  • type_str microphone/timer,分别代表声音传感器和计时器,目前仅支持这两个。
event.touchpad0_active(callback)

被触摸按键,参数:

  • callback 回调函数。
event.touchpad1_active(callback)

被触摸按键,参数:

  • callback 回调函数。
event.touchpad2_active(callback)

被触摸按键,参数:

  • callback 回调函数。
event.touchpad3_active(callback)

被触摸按键,参数:

  • callback 回调函数。
程序示例:
import haloboard
import time
import event

@event.button_pressed
def on_button_pressed():
    print("button event successed")
    haloboard.broadcast('hello')
    haloboard.mesh.broadcast('hello')

@event.start
def on_start():
    print("start event successed")

@event.shaked
def on_shaked():
    print("shaked event activate")

@event.received("hello")
def received_cb():
    print("broadcast received event successed")

@event.tilted_left
def on_tilted_left():
    print("tilted left event successed")

@event.tilted_right
def on_tilted_right():
    print("tilted right event successed")

@event.arrow_up
def on_arrow_up():
    print("arrow up event successed")

@event.arrow_down
def on_arrow_up():
    print("arrow down event successed")

@event.greater_than(80, "microphone")
def on_greater_than():
    print("sound sensor greater event successed")

@event.greater_than(2, "timer")
def on_greater_than():
    print("timer greater event successed")

@event.touchpad0_active
def on_touchpad0_active():
    print("touchpad0 active")

@event.touchpad1_active
def on_touchpad1_active():
    print("touchpad1 active")

@event.touchpad2_active
def on_touchpad2_active():
    print("touchpad2 active")

@event.touchpad3_active
def on_touchpad3_active():
    print("touchpad3 active")

@event.cloud_message("hello")
def on_cloud_message():
    print("cloud message event successed")

@event.mesh_message("hello")
def on_mesh_message():
    print("mesh message event successed")
cloud_message 接口列表
cloud_message --- 云广播模块

cloud_message 模块的主要功能与函数

功能相关函数
cloud_message.start(topic_head, cliend_id=None, server="mq.makeblock.com", port=1883, user=None, password=None, keepalive=60, ssl=False)

开启云广播,需保证Wi-Fi连接,这个开启动作才生效,参数:

  • topic_head 云广播主题的前缀目录。
  • client_id 连接到代理时使用的唯一客户端ID字符串,如果client_id为零长度或无,则将随机生成一个。在这种情况下,connect 函数的clean_session参数必须为True。
  • server 远程服务器的主机名或IP地址。
  • port (可选)要连接的服务器主机的网络端口,默认为1883。请注意:MQTT over SSL/TLS的默认端口为8883。
  • user (可选)在服务器上注册的用户名。
  • password (可选)在服务器上注册的密码。
  • keepalive (可选)客户端的keepalive超时值,默认为60秒。
  • ssl (可选)是否能使SSL/TLS支持。
cloud_message.get_info(message)

获取广播信息的附带参数,返回字符串类型或者数值数据,参数:

  • message 字符串数据,广播的信息名称。
cloud_message.broadcast(message, value = "")

广播信息并附带参数,参数:

  • message 字符串数据,广播的信息名称。
  • value 广播信息附带的参数。
程序示例一:
import haloboard
import event
haloboard.cloud_message.start('/USER/1014148/MESSAGE')

@event.start
def on_start():
    haloboard.wifi.start(ssid = 'Maker-guest', password = 'makeblock', mode = haloboard.wifi.WLAN_MODE_STA)
    while not haloboard.wifi.is_connected():
        pass
    haloboard.led.show_all(126, 211, 33)
    time.sleep(2)
    haloboard.led.off_all()
    haloboard.cloud_message.broadcast('hello', '')
程序示例二:
# -*- coding: utf-8 -*-
# generated by mBlock5 for <product>
# codes make you happy
import time
import math
import random
import haloboard, event
# from micropython import mem_info

@event.start
def on_start():
    haloboard.led.show_all(50, 50, 50)
    haloboard.wifi.start(ssid = 'Maker-guest', password = 'makeblock', mode = haloboard.wifi.WLAN_MODE_STA)
    haloboard.cloud_message.start('/USER/11/MESSAGE')
    while not haloboard.wifi.is_connected():
        pass
    haloboard.led.show_all(0, 50, 0)

@event.cloud_message('b')
def on_cloud_message1():
    haloboard.led.show_all(50, 0, 0)
    print(haloboard.cloud_message.get_info("b"))

@event.cloud_message('a')
def on_cloud_message2():
    haloboard.led.show_all(0, 0, 50)
    print(haloboard.cloud_message.get_info("a"))
    # mem_info()

@event.button_pressed
def on_button_pressed():
    haloboard.cloud_message.broadcast('b', "test1")
    haloboard.cloud_message.broadcast('a', "test2")
pin 接口列表
pin0 --- pin口0

pin0 模块的主要功能与函数

功能相关函数
pin0.is_touched()

获取pin口当前状态。返回的结果是True:pin口被触摸,或者False:pin口未被触摸。

pin0.get_touchpad_value()

获取pin口被触摸的值。数值范围为0-10000。

pin0.set_touchpad_threshold(val)

设置pin口触摸触发阈值,参数:

  • val 变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值为0.0-1。
pin0.read_digital()

获取pin口数字输入,值为0或1。

pin0.write_digital(val)

设置pin口数字输出,参数:

  • val 数字输出值为0或1。
pin0.write_analog(val)

设置模拟输出(pwm),参数:

  • val 模拟输出值,数值范围为0-1023。
pin0.read_analog()

获取模拟输入值(pwm)。数值范围为0-3300,单位为mv。

pin0.servo_write(val)

设置舵机转动的角度,参数:

  • val 舵机转动的角度,或者舵机控制脉冲的高电平的维持时间,数值为0-19999。 当数值小于544 的时候,输入数据如果小于0,会转换为0,如果大于180会转化为180,代表设置 的是模拟舵机的转动角度; 当数值大于或等于544时,表示设置的是50Hz PWM波的高电平的时间宽度(单位是 us),所以最大 值是 19999, 将近20ms,如果大于19999的,则转化为19999。
pin0.analog_set_frequency(frequency)

设置pin模拟输出(pwm)频率,参数:

  • frequency PWM频率值,数值范围为0-5000
程序示例一:
import haloboard
import event

@event.start
def on_start():
    global results
    if haloboard.pin0.is_touched():
        haloboard.led.show_all(126, 211, 33)
程序示例二:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5
PIN_MODE_WRITE_SERVO      = 6

pin_mode = PIN_MODE_TOUCH
pin_index = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode, pin_index
    pin_index = (pin_index + 1) % 10

    if pin_index % 2 == 0:
        pin_mode = PIN_MODE_TOUCH
        print("*****", "in tp mode")
    elif pin_index == 1:
        pin_mode = PIN_MODE_WRITE_ANALOG
        print("*****", "in write analog mode")
    elif pin_index == 3:
        pin_mode = PIN_MODE_READ_DIGITAL
        print("*****", "in read digital mode")
    elif pin_index == 5:
        pin_mode = PIN_MODE_WRITE_DIGITAL
        print("*****", "in write digital mode")
    elif pin_index == 7:
        pin_mode = PIN_MODE_READ_ANALOG
        print("*****", "in read analog mode")

    elif pin_index == 9:
        pin_mode = PIN_MODE_WRITE_SERVO
        print("*****", "in servo mode")

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            time.sleep(0.1)
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)

        if pin_mode == PIN_MODE_WRITE_SERVO:
            print("write_servo 150")
            haloboard.pin2.servo_write(150)
            haloboard.pin3.servo_write(150)
            time.sleep(2)
            print("write_servo 10000")
            haloboard.pin2.servo_write(10000)
            haloboard.pin3.servo_write(10000)
            time.sleep(2)

        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
程序示例三:
import haloboard
import event

pin_mode = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        pin_mode %= 8
        if pin_mode < 4:
            if pin_mode == 0:
                print("pin write servo 0")
                haloboard.pin0.servo_write(0)
            elif pin_mode == 1:
                print("pin write servo 90")
                haloboard.pin0.servo_write(90)
            elif pin_mode == 2:
                print("pin write servo 120")
                haloboard.pin0.servo_write(120)
            elif pin_mode == 3:
                print("pin write servo 180")
                haloboard.pin0.servo_write(180)
程序示例四:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5

pin_mode = PIN_MODE_TOUCH

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    if pin_mode > PIN_MODE_READ_ANALOG:
        pin_mode = PIN_MODE_TOUCH

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)
        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
pin1 --- pin口1

pin1 模块的主要功能与函数

功能相关函数
pin1.is_touched()

获取pin口当前状态。返回的结果是True:pin口被触摸,或者False:pin口未被触摸。

pin1.get_touchpad_value()

获取pin口被触摸的值。数值范围为0-10000。

pin1.set_touchpad_threshold(val)

设置pin口触摸触发阈值,参数:

  • val 变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值为0.0-1。
pin1.read_digital()

获取pin口数字输入,值为0或1。

pin1.write_digital(val)

设置pin口数字输出,参数:

  • val 数字输出值为0或1。
pin1.write_analog(val)

设置模拟输出(pwm),参数:

  • val 模拟输出值,数值范围为0-1023。
pin1.read_analog()

获取模拟输入值(pwm)。数值范围为0-3300,单位为mv。

pin1.servo_write(val)

设置舵机转动的角度,参数:

  • val 舵机转动的角度,或者舵机控制脉冲的高电平的维持时间,数值为0-19999。 当数值小于544 的时候,输入数据如果小于0,会转换为0,如果大于180会转化为180,代表设置 的是模拟舵机的转动角度; 当数值大于或等于544时,表示设置的是50Hz PWM波的高电平的时间宽度(单位是 us),所以最大 值是 19999, 将近20ms,如果大于19999的,则转化为19999。
pin1.analog_set_frequency(frequency)

设置pin模拟输出(pwm)频率,参数:

  • frequency PWM频率值,数值范围为0-5000
程序示例一:
import haloboard
import event

@event.start
def on_start():
    global results
    if haloboard.pin1.is_touched():
        haloboard.led.show_all(126, 211, 33)
程序示例二:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5
PIN_MODE_WRITE_SERVO      = 6

pin_mode = PIN_MODE_TOUCH
pin_index = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode, pin_index
    pin_index = (pin_index + 1) % 10

    if pin_index % 2 == 0:
        pin_mode = PIN_MODE_TOUCH
        print("*****", "in tp mode")
    elif pin_index == 1:
        pin_mode = PIN_MODE_WRITE_ANALOG
        print("*****", "in write analog mode")
    elif pin_index == 3:
        pin_mode = PIN_MODE_READ_DIGITAL
        print("*****", "in read digital mode")
    elif pin_index == 5:
        pin_mode = PIN_MODE_WRITE_DIGITAL
        print("*****", "in write digital mode")
    elif pin_index == 7:
        pin_mode = PIN_MODE_READ_ANALOG
        print("*****", "in read analog mode")

    elif pin_index == 9:
        pin_mode = PIN_MODE_WRITE_SERVO
        print("*****", "in servo mode")

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            time.sleep(0.1)
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)

        if pin_mode == PIN_MODE_WRITE_SERVO:
            print("write_servo 150")
            haloboard.pin2.servo_write(150)
            haloboard.pin3.servo_write(150)
            time.sleep(2)
            print("write_servo 10000")
            haloboard.pin2.servo_write(10000)
            haloboard.pin3.servo_write(10000)
            time.sleep(2)

        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
程序示例三:
import haloboard
import event

pin_mode = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        pin_mode %= 8
        if pin_mode < 4:
            if pin_mode == 0:
                print("pin write servo 0")
                haloboard.pin0.servo_write(0)
            elif pin_mode == 1:
                print("pin write servo 90")
                haloboard.pin0.servo_write(90)
            elif pin_mode == 2:
                print("pin write servo 120")
                haloboard.pin0.servo_write(120)
            elif pin_mode == 3:
                print("pin write servo 180")
                haloboard.pin0.servo_write(180)
程序示例四:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5

pin_mode = PIN_MODE_TOUCH

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    if pin_mode > PIN_MODE_READ_ANALOG:
        pin_mode = PIN_MODE_TOUCH

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)
        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
pin2 --- pin口2

pin2 模块的主要功能与函数

功能相关函数
pin2.is_touched()

获取pin口当前状态。返回的结果是True:pin口被触摸,或者False:pin口未被触摸。

pin2.get_touchpad_value()

获取pin口被触摸的值。数值范围为0-10000。

pin2.set_touchpad_threshold(val)

设置pin口触摸触发阈值,参数:

  • val 变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值为0.0-1。
pin2.read_digital()

获取pin口数字输入,值为0或1。

pin2.write_digital(val)

设置pin口数字输出,参数:

  • val 数字输出值为0或1。
pin2.write_analog(val)

设置模拟输出(pwm),参数:

  • val 模拟输出值,数值范围为0-1023。
pin2.read_analog()

获取模拟输入值(pwm)。数值范围为0-3300,单位为mv。

pin2.servo_write(val)

设置舵机转动的角度,参数:

  • val 舵机转动的角度,或者舵机控制脉冲的高电平的维持时间,数值为0-19999。 当数值小于544 的时候,输入数据如果小于0,会转换为0,如果大于180会转化为180,代表设置 的是模拟舵机的转动角度; 当数值大于或等于544时,表示设置的是50Hz PWM波的高电平的时间宽度(单位是 us),所以最大 值是 19999, 将近20ms,如果大于19999的,则转化为19999。
pin2.analog_set_frequency(frequency)

设置pin模拟输出(pwm)频率,参数:

  • frequency PWM频率值,数值范围为0-5000
程序示例一:
import haloboard
import event

@event.start
def on_start():
    global results
    if haloboard.pin2.is_touched():
        haloboard.led.show_all(126, 211, 33)
程序示例二:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5
PIN_MODE_WRITE_SERVO      = 6

pin_mode = PIN_MODE_TOUCH
pin_index = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode, pin_index
    pin_index = (pin_index + 1) % 10

    if pin_index % 2 == 0:
        pin_mode = PIN_MODE_TOUCH
        print("*****", "in tp mode")
    elif pin_index == 1:
        pin_mode = PIN_MODE_WRITE_ANALOG
        print("*****", "in write analog mode")
    elif pin_index == 3:
        pin_mode = PIN_MODE_READ_DIGITAL
        print("*****", "in read digital mode")
    elif pin_index == 5:
        pin_mode = PIN_MODE_WRITE_DIGITAL
        print("*****", "in write digital mode")
    elif pin_index == 7:
        pin_mode = PIN_MODE_READ_ANALOG
        print("*****", "in read analog mode")

    elif pin_index == 9:
        pin_mode = PIN_MODE_WRITE_SERVO
        print("*****", "in servo mode")

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            time.sleep(0.1)
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)

        if pin_mode == PIN_MODE_WRITE_SERVO:
            print("write_servo 150")
            haloboard.pin2.servo_write(150)
            haloboard.pin3.servo_write(150)
            time.sleep(2)
            print("write_servo 10000")
            haloboard.pin2.servo_write(10000)
            haloboard.pin3.servo_write(10000)
            time.sleep(2)

        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
程序示例三:
import haloboard
import event

pin_mode = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        pin_mode %= 8
        if pin_mode < 4:
            if pin_mode == 0:
                print("pin write servo 0")
                haloboard.pin0.servo_write(0)
            elif pin_mode == 1:
                print("pin write servo 90")
                haloboard.pin0.servo_write(90)
            elif pin_mode == 2:
                print("pin write servo 120")
                haloboard.pin0.servo_write(120)
            elif pin_mode == 3:
                print("pin write servo 180")
                haloboard.pin0.servo_write(180)
程序示例四:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5

pin_mode = PIN_MODE_TOUCH

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    if pin_mode > PIN_MODE_READ_ANALOG:
        pin_mode = PIN_MODE_TOUCH

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)
        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
pin3 --- pin口3

pin3 模块的主要功能与函数

功能相关函数
pin3.is_touched()

获取pin口当前状态。返回的结果是True:pin口被触摸,或者False:pin口未被触摸。

pin3.get_touchpad_value()

获取pin口被触摸的值。数值范围为0-10000。

pin3.set_touchpad_threshold(val)

设置pin口触摸触发阈值,参数:

  • val 变化的百分比,检测到变化的幅值大于该百分比时认为被触摸,数值为0.0-1。
pin3.read_digital()

获取pin口数字输入,值为0或1。

pin3.write_digital(val)

设置pin口数字输出,参数:

  • val 数字输出值为0或1。
pin3.write_analog(val)

设置模拟输出(pwm),参数:

  • val 模拟输出值,数值范围为0-1023。
pin3.read_analog()

获取模拟输入值(pwm)。数值范围为0-3300,单位为mv。

pin3.servo_write(val)

设置舵机转动的角度,参数:

  • val 舵机转动的角度,或者舵机控制脉冲的高电平的维持时间,数值为0-19999。 当数值小于544 的时候,输入数据如果小于0,会转换为0,如果大于180会转化为180,代表设置 的是模拟舵机的转动角度; 当数值大于或等于544时,表示设置的是50Hz PWM波的高电平的时间宽度(单位是 us),所以最大 值是 19999, 将近20ms,如果大于19999的,则转化为19999。
pin3.analog_set_frequency(frequency)

设置pin模拟输出(pwm)频率,参数:

  • frequency PWM频率值,数值范围为0-5000
程序示例一:
import haloboard
import event

@event.start
def on_start():
    global results
    if haloboard.pin3.is_touched():
        haloboard.led.show_all(126, 211, 33)
程序示例二:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5
PIN_MODE_WRITE_SERVO      = 6

pin_mode = PIN_MODE_TOUCH
pin_index = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode, pin_index
    pin_index = (pin_index + 1) % 10

    if pin_index % 2 == 0:
        pin_mode = PIN_MODE_TOUCH
        print("*****", "in tp mode")
    elif pin_index == 1:
        pin_mode = PIN_MODE_WRITE_ANALOG
        print("*****", "in write analog mode")
    elif pin_index == 3:
        pin_mode = PIN_MODE_READ_DIGITAL
        print("*****", "in read digital mode")
    elif pin_index == 5:
        pin_mode = PIN_MODE_WRITE_DIGITAL
        print("*****", "in write digital mode")
    elif pin_index == 7:
        pin_mode = PIN_MODE_READ_ANALOG
        print("*****", "in read analog mode")

    elif pin_index == 9:
        pin_mode = PIN_MODE_WRITE_SERVO
        print("*****", "in servo mode")

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            time.sleep(0.1)
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)

        if pin_mode == PIN_MODE_WRITE_SERVO:
            print("write_servo 150")
            haloboard.pin2.servo_write(150)
            haloboard.pin3.servo_write(150)
            time.sleep(2)
            print("write_servo 10000")
            haloboard.pin2.servo_write(10000)
            haloboard.pin3.servo_write(10000)
            time.sleep(2)

        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
程序示例三:
import haloboard
import event

pin_mode = 0

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        pin_mode %= 8
        if pin_mode < 4:
            if pin_mode == 0:
                print("pin write servo 0")
                haloboard.pin0.servo_write(0)
            elif pin_mode == 1:
                print("pin write servo 90")
                haloboard.pin0.servo_write(90)
            elif pin_mode == 2:
                print("pin write servo 120")
                haloboard.pin0.servo_write(120)
            elif pin_mode == 3:
                print("pin write servo 180")
                haloboard.pin0.servo_write(180)
程序示例四:
import haloboard
import event

PIN_MODE_TOUCH            = 1
PIN_MODE_READ_DIGITAL     = 2
PIN_MODE_WRITE_DIGITAL    = 3
PIN_MODE_WRITE_ANALOG     = 4
PIN_MODE_READ_ANALOG      = 5

pin_mode = PIN_MODE_TOUCH

@event.button_pressed
def on_button_pressed():
    global pin_mode
    pin_mode = pin_mode + 1
    if pin_mode > PIN_MODE_READ_ANALOG:
        pin_mode = PIN_MODE_TOUCH

    print("pin mode is: " + str(pin_mode))

@event.start
def on_start():
    global pin_mode
    while True:
        if pin_mode == PIN_MODE_TOUCH:
            if haloboard.pin0.is_touched():
                print("pin0 is touched")
            if haloboard.pin1.is_touched():
                print("pin1 is touched")
            if haloboard.pin2.is_touched():
                print("pin2 is touched")
            if haloboard.pin3.is_touched():
                print("pin3 is touched")
        if pin_mode == PIN_MODE_READ_DIGITAL:
            print("pin0:", end = "")
            print(haloboard.pin0.read_digital(), end = "")
            print(" ,pin1:", end = "")
            print(haloboard.pin1.read_digital(), end = "")
            print(" ,pin2:", end = "")
            print(haloboard.pin2.read_digital(), end = "")
            print(" ,pin3:", end = "")
            print(haloboard.pin3.read_digital())
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_DIGITAL:
            print("write_digital HIGH")
            haloboard.pin0.write_digital(1)
            haloboard.pin1.write_digital(1)
            haloboard.pin2.write_digital(1)
            haloboard.pin3.write_digital(1)
            time.sleep(1)
            print("write_digital LOW")
            haloboard.pin0.write_digital(0)
            haloboard.pin1.write_digital(0)
            haloboard.pin2.write_digital(0)
            haloboard.pin3.write_digital(0)
            time.sleep(1)
        if pin_mode == PIN_MODE_WRITE_ANALOG:
            print("write_analog 512")
            haloboard.pin0.write_analog(512)
            haloboard.pin1.write_analog(512)
            haloboard.pin2.write_analog(512)
            haloboard.pin3.write_analog(512)
            time.sleep(1)
        if pin_mode == PIN_MODE_READ_ANALOG:
            print("pin2:", end = "")
            print(haloboard.pin2.read_analog(), end = "")
            print("pin3:", end = "")
            print(haloboard.pin3.read_analog())
            time.sleep(1)
speech_recognition 接口列表
speech_recognition --- 语音识别模块

speech_recognition 模块的主要功能与函数

功能相关函数
speech_recognition.start(server, language)

启动语音识别服务,参数:

  • server 服务器名称
  • language 识别的语言
speech_recognition.get_error_code()

获取结果数据的错误码。返回值对应结果如下:

  • 0 : 正确返回
  • 3300: 语音输入参数不正确
  • 3301:语音数据不清晰
  • 3302:鉴权失败
  • 3303:原始音频或者服务端问题
  • 3304:用户请求超限(QPS)
  • 3305:用户请求超限(pv-日请求量)
  • 3307: 服务端问题
  • 3308:音频数据过长
  • 3309:音频数据异常
  • 3310:音频文件过大
  • 3311:采样率错误
  • 3312:音频格式错误
  • 3333:未知错误
  • 3334:响应超时
speech_recognition.get_error_message()

获取错误的具体信息,字符串类型。

speech_recognition.get_result_code()

获取识别的结果,如果发生错误或者超时,返回空字符串。

speech_recognition.get_sn_code()

获取语音数据唯一标识,由服务器系统内部产生。

speech_recognition.get_all_respond()

获取语音识别结果,包含整个回复信息,如错误信息等

程序示例一:
# -*- coding: utf-8 -*-
import haloboard
import time
import event

@event.start
def use_code():
    haloboard.wifi.start(ssid = "Maker-guest", password = "makeblock", mode = haloboard.wifi.WLAN_MODE_STA)

    while(True):
        if haloboard.wifi.is_connected() == True:
            print("wifi is connected!")
            break;

    while True:
        if haloboard.button.is_pressed():
            haloboard.led.show_all(0, 0, 50)
            haloboard.speech_recognition.start(haloboard.speech_recognition.SERVER_MICROSOFT, haloboard.speech_recognition.LAN_DEFAULT, 2)
            if haloboard.speech_recognition.get_error_code() != 0:
                str = haloboard.speech_recognition.get_error_message()
                print("error_message:" + str)
            else:
                result = haloboard.speech_recognition.get_result_code()
                print("result:" + result)
                if '红色' in result:
                    haloboard.led.show_all(50, 0, 0)
                elif '黄色' in result:
                    haloboard.led.show_all(50, 50, 0)
                elif '白色' in result:
                    haloboard.led.show_all(50, 50, 50)
                elif '蓝色' in result:
                    haloboard.led.show_all(0, 0, 50)
                elif '绿色' in result:
                    haloboard.led.show_all(0, 50, 0)
                else:
                    haloboard.led.show_all(0, 0, 0)
        time.sleep(0.5)
程序示例二:
# -*- coding: utf-8 -*-
import haloboard
import time
import event

haloboard.speech_recognition.set_recognition_url(haloboard.speech_recognition.SERVER_MICROSOFT, "http://msapi.passport3.makeblock.com/ms/bing_speech/interactive")
haloboard.speech_recognition.set_token(haloboard.speech_recognition.SERVER_MICROSOFT, "ed8xubrmidv")
# haloboard.speech_recognition.set_account(haloboard.speech_recognition.SERVER_MICROSOFT, "embeded@makeblock.com", "123456")

@event.start
def use_code():
    haloboard.wifi.start(ssid = "Maker-guest", password = "makeblock", mode = haloboard.wifi.WLAN_MODE_STA)

    while(True):
        if haloboard.wifi.is_connected() == True:
            print("wifi is connected!")
            break;

    while True:
        if haloboard.button.is_pressed():
            haloboard.led.show_all(0, 0, 50)
            haloboard.speech_recognition.start(haloboard.speech_recognition.SERVER_MICROSOFT, haloboard.speech_recognition.LAN_DEFAULT, 2)
            if haloboard.speech_recognition.get_error_code() != 0:
                str = haloboard.speech_recognition.get_error_message()
                print("error_message:" + str)
            else:
                result = haloboard.speech_recognition.get_result_code()
                print("result:" + result)
                if '红色' in result:
                    haloboard.led.show_all(50, 0, 0)
                elif '黄色' in result:
                    haloboard.led.show_all(50, 50, 0)
                elif '白色' in result:
                    haloboard.led.show_all(50, 50, 50)
                elif '蓝色' in result:
                    haloboard.led.show_all(0, 0, 50)
                elif '绿色' in result:
                    haloboard.led.show_all(0, 50, 0)
                else:
                    haloboard.led.show_all(0, 0, 0)
        time.sleep(0.5)
timer 接口列表
timer --- 计时器模块

timer 模块的主要功能与函数

功能相关函数
timer.get_timer()

获取系统计时器时间,单位为秒。

timer.reset_timer()

复位系统计时器时间。

程序示例:
import haloboard
import time

haloboard.reset_timer()

while True:
    if haloboard.button.is_pressed():
        haloboard.reset_timer()
        print("reset_timer")
    print("time:", end = "")
    print(haloboard.get_timer())
wifi 接口列表
wifi --- 板载WiFi模块

wifi 模块的主要功能与函数

功能相关函数
wifi.start(ssid = "wifi_ssid", password = "password", mode = haloboard.wifi.STA)

启动wifi连接,该API不阻塞,API退出不代表Wi-Fi已连接上,需要调用 wifi.is_connected() 判断,参数:

  • ssid 字符串类型,Wi-Fi账号。
  • password 字符串类型,Wi-Fi密码。
  • mode 启动Wi-Fi的模式,目前只支持WLAN_MODE_STA
wifi.set_mode(mode)

设置Wi-Fi的模式,参数:

  • mode 指WiFi模式,目前只支持WLAN_MODE_STA。
wifi.connect()

连接WiFi

wifi.is_connected()

检测Wi-Fi连接状态,返回值是布尔值,其中 True 表示Wi-Fi已经建立连接,False 表示Wi-Fi尚未建立连接。

wifi.disconnect()

断开WiFi连接

程序示例一:
import haloboard
haloboard.wifi.start('Maker-guest', 'makeblock')
haloboard.led.show_all(0,0,0)
while True:
    if haloboard.wifi.is_connected():
        haloboard.led.show_all(0,0,255)

    else:
        haloboard.led.show_all(0,0,0)
程序示例二:
import haloboard
import event

@event.button_pressed
def on_button():
    haloboard.stop_other_scripts()
    print("start toconnect Maker-guest")
    haloboard.wifi.start('Maker-guest', 'makeblock')
    haloboard.led.show_all(0,0,0)
    while True:
        if haloboard.wifi.is_connected():
            haloboard.led.show_all(0,0,255)
            break
        else:
            haloboard.led.show_all(0,0,0)

@event.touchpad0_active
def on_touchpad0_active():
    haloboard.stop_other_scripts()
    print("start toconnect iPhone fftust")
    haloboard.wifi.start('iPhone fftust', '19920112')
    haloboard.led.show_all(0,0,0)
    while True:
        if haloboard.wifi.is_connected():
            haloboard.led.show_all(0,0,255)
            break
        else:
            haloboard.led.show_all(0,0,0)

第三方类库的python接口

第三方类库的python接口API如下:

神经元扩展模块的python接口

神经元扩展模块的python接口API如下:

光环板的实例教程

本教程的目的是让您开始光环板python的使用。 我们需要你有一块光环板,其次您还需要一根USB线(或者蓝牙dongle)可以连接到电脑。 如果你是第一次使用光环板的python编程,建议阅读一下这部分的内容。

光环板 典型实例

光环板的micropython使用说明

光环板上面的webrepl的开启与连接

webrepl是micropython提供无线链接的管理平台。

步骤一:烧写固件
确保好自己的固件已经烧好了即可。
步骤二:连接网络
打开串口助手(如putty,secureCRT等等),光环板与电脑之间使用USB连接好,按ctrl+e进入代码粘贴模式,将以下代码的ssid和password填写完整以后,粘贴在串口助手,然后ctrl+d运行代码。(注意:ssid为WiFi的名字、password为WiFi的密码)
import network
import time
ssid=''
password=''
wlan=network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect(ssid,password)
i=0

while(wlan.ifconfig()[0]=='0.0.0.0' and i < 100):
    i=i+1
    time.sleep(1)
    if(wlan.ifconfig()[0]=='0.0.0.0'):
        print('connect Wifi False!')
        #return False
    else:
        print('connect Wifi True!')
        print(wlan.ifconfig())
        #return True
_images/1.jpg

如上图所示,网络配置完成,输出模块IP地址。

步骤三:配置webrepl
1.向串口中输入
import webrepl_setup
_images/2.jpg

如上图所示,向串口中输入 import webrepl_setup。

2.输入 E 确定开启webrepl,连续输入两次密码即可完成配置
_images/3.jpg

如上图所示,输入两次密码。

3.手动依次输入 import webrepl 和 webrepl.start() ,开启webrepl
_images/4.jpg

如上图所示,开启webrepl。

步骤四:连接webrepl
1.打开webrepl的地址:http://micropython.org/webrepl/
_images/5.jpg

如上图所示,webrepl界面。

2.输入第三步中的ip地址,点击Connect,输入配置时候的密码(注:密码在输入的时候不显示!)
_images/6.jpg

如上图所示,连接完成界面。

3.可以输入help()尝试一下
_images/7.jpg
步骤五:配置开机连接WiFi和开启webrepl
1.新建boot.py,内容如下
import time

ssid=''
password=''

def connectWifi():
    wlan=network.WLAN(network.STA_IF)                     #create a wlan object
    wlan.active(True)                                     #Activate the network interface
    wlan.connect(ssid,password)
    i=0
    while(wlan.ifconfig()[0]=='0.0.0.0' and i < 10):
        i=i+1
        time.sleep(1)
        if(wlan.ifconfig()[0]=='0.0.0.0'):
            print('connect Wifi False!')
            return False
        else:
            print('connect Wifi True!')
            print(wlan.ifconfig())
            return True
if(connectWifi() == True):
    import webrepl
    webrepl.start()

注意:要将上代码的ssid和password填写完整。

2.回到webrepl的网站界面,在右侧栏Send a file 下方点击 浏览 选择刚才写好的boot.py,点击Send to device,等待上传完成
_images/8.jpg

如上图所示,发送一个文件。

3.输入ctrl+d或者断电重启光环板,重启完成后再次连接。
此时在打开webrepl的网站就能管理光环板,而不用串口线。

novapi主控python接口

本章介绍了novapi主控python接口,一共包含以下几类模块:

  • novapi主控python接口:主要是指novapi主控支持的模块API接口。
  • 第三方类库的python接口:novapi主控内置的一些第三方类库的接口类,例如mqtt、urequest的类。

novapi主控python接口

novapi主控python接口如下:

novapi的python接口列表

timer --- 计时器模块

timer 模块的主要功能与函数

功能相关函数
timer.timer()

获取系统计时器时间,单位为秒。

timer.reset_timer()

复位系统计时器时间。

程序示例:
import novapi

novapi.reset_timer()

while True:
    if novapi.timer() > 5:
        novapi.reset_timer()
    print("time:", novapi.timer())
gyro_sensor --- 板载陀螺仪传感器

gyro_sensor 模块的主要功能与函数

板载陀螺仪传感器说明

板载陀螺仪的坐标体系如下图所示:

_images/novapi.png
功能相关函数
gyro_sensor.get_pitch()

获取姿态角的俯仰角(X轴),单位:°,返回的数据范围是 -180 ~ 180

gyro_sensor.get_roll()

获取姿态角的翻滚角(Y轴),单位:°,返回的数据范围是 -180 ~ 180

gyro_sensor.get_yaw()

获取姿态角的偏航角(Z轴),单位:°,返回的数据范围是 -32768 ~ 32767,由于板载的陀螺仪模块是六轴传感器,没有电子罗盘。 所以实际上偏航角只是使用了Z轴角速度的积分。它存在着积累误差。如果是想获得真实偏航角的,这个API不适合使用。

gyro_sensor.is_shaked()

检测板载陀螺仪模块是否有被摇晃,返回值是布尔值,其中 True 表示陀螺仪模块被晃动了,False 表示陀螺仪模块未被晃动。

gyro_sensor.get_acceleration(axis)

获取三个轴的加速度值,单位是 g,参数:

  • axis 字符串类型,以 xyz 代表板载陀螺仪模块定义的坐标轴。
gyro_sensor.get_gyroscope(axis)

获取三个轴的角速度值,单位是 °/秒,返回的数据范围是 -500 ~ 500,参数:

  • axis 字符串类型,以 xyz 代表板载陀螺仪模块定义的坐标轴。
gyro_sensor.set_shake_threshold(threshold)

设置震动阈值,参数:

  • threshold 震动阈值,范围是``0~100``,系统默认震动阈值为50,0表示关闭震动检测。
gyro_sensor.reset_rotation(axis)

重置绕x、y、z轴转过的角度,参数:

  • axis 字符串类型,以 xyzall 代表板载陀螺仪模块定义的坐标轴,``all`代表所有轴。
程序示例1:
import novapi

while True:
    print("pitch:", novapi.get_pitch())
    print("roll:", novapi.get_roll())
    print("yaw:", novapi.get_yaw())
程序示例2:
import novapi

while True:
    print("x acc:", novapi.get_acceleration("x"))
    print("y acc:", novapi.get_acceleration("y"))
    print("z acc:", novapi.get_acceleration("z"))
程序示例3:
import novapi

while True:
    print("x gyro:", novapi.get_gyroscope("x"))
    print("y gyro:", novapi.get_gyroscope("y"))
    print("z gyro:", novapi.get_gyroscope("z"))
程序示例4:
import novapi

novapi.set_shake_threshold(60)

while True:
    if novapi.is_shaked():
        print("novapi is shaked")
gamepad --- 遥控手柄

gamepad 模块的主要功能与函数

遥控手柄说明

遥控手柄外观如下图所示:

_images/gamepad.png
功能相关函数
gamepad.get_joystick(joystick_pos)

获取摇杆值,返回值范围 100 ~ -100 ,左正右负,上正下负,参数:

  • joystick_pos 字符串类型,其中:

    “Lx”:左边x轴

    “Ly”:左边y轴

    “Rx”:右边x轴

    “Ry”:右边y轴

gamepad.s_key_pressed(button)

判断手柄按键是否被按下,返回值是布尔值,其中 True 表示按键被按下, False 按键未被按下

  • button 字符串类型,其中:

    “R1”:右边R1

    “R2”: 右边R2

    “L1”: 左边L1

    “L2”: 左边L2

    “N1”: 数字1

    “N2”: 数字2

    “N3”: 数字3

    “N4”: 数字4

    “Up”: 方向键上

    “Down“: 方向键下

    “Left“: 方向键左

    “Right”: 方向键右

    “Start”: 开始键

    “Select“: 菜单键

    “L_Thumb”: 左边摇杆按下

    “R_Thumb“: 右边摇杆按下

程序示例:
import novapi
from mbuild import gamepad

while True:
    time.sleep(0.1)
    if(gamepad.is_key_pressed("Up")):
        print("Up")
    elif(gamepad.is_key_pressed("Down")):
        print("Down")
    elif(gamepad.is_key_pressed("Left")):
        print("Left")
    elif(gamepad.is_key_pressed("Right")):
        print("Right")
    elif(gamepad.is_key_pressed("N1")):
        print("N1")
    elif(gamepad.is_key_pressed("N2")):
        print("N2")
    elif(gamepad.is_key_pressed("N3")):
        print("N3")
    elif(gamepad.is_key_pressed("N4")):
        print("N4")
    elif(gamepad.is_key_pressed("L1")):
        print("L1")
    elif(gamepad.is_key_pressed("L2")):
        print("L2")
    elif(gamepad.is_key_pressed("R1")):
        print("R1")
    elif(gamepad.is_key_pressed("R2")):
        print("R2")
    elif(gamepad.is_key_pressed("Start")):
        print("Start")
    elif(gamepad.is_key_pressed("Select")):
        print("Select")
    elif(gamepad.is_key_pressed("L_Thumb")):
        print("L_Thumb")
    elif(gamepad.is_key_pressed("R_Thumb")):
        print("R_Thumb")
    else:
        Lx = gamepad.get_joystick("Lx")
        Ly = gamepad.get_joystick("Ly")
        Rx = gamepad.get_joystick("Rx")
        Ry = gamepad.get_joystick("Ry")
        print("Lx=%d, Ly=%d, Rx=%d, Ry=%d, " % (Lx, Ly, Rx, Ry))
power_manage_module --- 电源管理模块

power_manage_module 模块的主要功能与函数

电源管理模块说明

电源管理模块外观如下图所示:

_images/power_manage_module.png
功能相关函数
power_manage_module.is_auto_mode()

判断比赛是否处于自动赛模式,返回值是布尔值,其中 True 表示比赛处于自动赛模式, False 表示比赛处于手动赛模式

程序示例:
import novapi
from mbuild import power_manage_module

while True:
    if power_manage_module.is_auto_mode():
        print("Competition is in auto mode")
    else:
        print("Competition is in manual mode")
dual_rgb_sensor --- 双路RGB传感器

dual_rgb_sensor 模块的主要功能与函数

双路RGB传感器说明

双路RGB传感器模块外观如下图所示:

_images/dual_rgb_sensor.png
功能相关函数
dual_rgb_sensor.get_intensity(ch)

获取探头光强值,返回的数据范围是 0 ~ 255

  • ch 通道号,字符串类型,通道范围:

    "RGB1" :通道1

    "RGB2" :通道2

dual_rgb_sensor.is_state(state)

巡线时,获取RGB1|RGB2的状态,如果获取到的状态等于state,则返回 True ,否则返回 False

  • state 字符串类型,参数范围:

    "00" :RGB1在线上,RGB2在线上

    "01" :RGB1在线上,RGB2在轨道上

    "10" :RGB1在轨道上,RGB2在线上

    "11" :RGB1在线轨道上,RGB2在轨道上

dual_rgb_sensor.get_offset_track_value()

在巡线时,获取传感器偏离轨道值,返回数据范围 -100 ~ 100

dual_rgb_sensor.is_color(ch,color)

获取颜色值的状态,如果获取到的颜色等于color,则返回 True ,否则返回 False

  • ch 通道号,字符串类型,通道范围:

    "RGB1" :通道1

    "RGB2" :通道2

  • color 颜色,字符串类型,可以选择的颜色有:

    "white": 白色

    "puple": 紫色

    "red": 红色

    "yellow": 黄色

    "green": 绿色

    "cyan": 青色

    "blue": 蓝色

    "black": 黑色

dual_rgb_sensor.set_led_color(color)

设置巡线时使用的颜色

  • color 颜色,字符串类型,可以选择的颜色有 redgreenblue
dual_rgb_sensor.is_on_track(ch)

巡线时,获取RGB探头状态,如果RGB探头在轨道上,则返回 True ,否则返回 False

  • ch 通道号,字符串类型,通道范围:

    "RGB1" :通道1

    "RGB2" :通道2

dual_rgb_sensor.is_on_background(ch)

巡线时,获取RGB探头状态,如果RGB探头在背景上,则返回 True ,否则返回 False

  • ch 通道号,字符串类型,通道范围:

    "RGB1" :通道1

    "RGB2" :通道2

dual_rgb_sensor.set_motor_diff_speed_kp(kp)

巡线时,设置传感器偏离轨道的电机差速系数,参数:

  • kp 系数,范围: 0 ~ 1
dual_rgb_sensor.get_motor_diff_speed()

在巡线时,获取传感器偏离轨道的电机差速,返回值等于传感器偏离轨道值get_offset_track_value()乘于设置的电机差速系数kp。

程序示例1-巡线:
import novapi
from mbuild.dual_rgb_sensor import dual_rgb_sensor_class
from mbuild.encoder_motor import encoder_motor_class

__dual_rgb_1 = dual_rgb_sensor_class("PORT1", "INDEX1")
__encoder_motor_1 = encoder_motor_class("M1", "INDEX1")
__encoder_motor_2 = encoder_motor_class("M2", "INDEX1")

speed = 50
__dual_rgb_1.set_motor_diff_speed_kp(0.5)

while True:
    __encoder_motor_1.set_power(speed + __dual_rgb_1.get_motor_diff_speed())
    __encoder_motor_2.set_power(speed - __dual_rgb_1.get_motor_diff_speed())
    time.sleep(0.01)
程序示例2-识别颜色:
import novapi
from mbuild.dual_rgb_sensor import dual_rgb_sensor_class

__dual_rgb_1 = dual_rgb_sensor_class("PORT1", "INDEX1")

while True:
    if __dual_rgb_1.is_color("RGB1", "red"):
        print("RGB1 color is red")
    if __dual_rgb_1.is_color("RGB2", "red"):
        print("RGB2 color is red")
    time.sleep(0.01)
程序示例3-检测"RGB1|RGB2"状态:
import novapi
from mbuild.dual_rgb_sensor import dual_rgb_sensor_class

__dual_rgb_1 = dual_rgb_sensor_class("PORT1", "INDEX1")

while True:
    if __dual_rgb_1.is_state("00"):
        print("RGB1|RGB2 is:00")
    elif __dual_rgb_1.is_state("01"):
        print("RGB1|RGB2 is:01")
    elif __dual_rgb_1.is_state("10"):
        print("RGB1|RGB2 is:10")
    elif __dual_rgb_1.is_state("11"):
        print("RGB1|RGB2 is:11")
    time.sleep(0.01)
encoder_motor --- 编码电机

encoder_motor 模块的主要功能与函数

编码电机说明

编码电机包括180编码电机和36堆叠无刷电机模块外观如下图所示:

_images/encoder_motor.png
功能相关函数
encoder_motor.move_to(position, speed)

按指定转速移动到绝对角度,参数:

  • position 目标角度,单位为度,范围 -2147483648~2147483647
  • speed 转速,单位为rpm/min,范围 不限定
encoder_motor.move(position, speed)

按指定转速移动到相对角度,参数:

  • position 目标角度,单位为度,范围 -2147483648~2147483647
  • speed 转速,单位为rpm/min,范围 不限定
encoder_motor.set_speed(speed)

设置目标速度,闭环控制,参数:

  • speed 转速,单位为rpm/min,范围:不限制,以电机最大能力转动。
encoder_motor.set_power(pwm)

设置电机以指定动力转动,开环控制,参数:

  • pwm 转速,单位为 ,范围 -100~100
encoder_motor.get_value(type)

获取电机数据,参数:

  • type 获取数据类型,字符串类型,参数可以选择为:

    “angle”:当前位置角度,返回值单位为读

    “speed”:当前速度,返回值单位为rpm/min

程序示例:
import novapi
from mbuild.encoder_motor import encoder_motor_class

#先初始化,定义电机接在M1口的第1个
__encoder_motor_1 = encoder_motor_class("M1", "INDEX1")

while True:
    __encoder_motor_1.set_power(50)
    __encoder_motor_1.set_power(-50)
    time.sleep(1)

    __encoder_motor_1.set_speed(100)
    __encoder_motor_1.set_speed(-100)
    time.sleep(1)

    __encoder_motor_1.move_to(360, 100)
    __encoder_motor_1.move_to(-360, 100)
    time.sleep(1)

    __encoder_motor_1.move(360, 100)
    __encoder_motor_1.move(-360, 100)
    time.sleep(1)

    __encoder_motor_1.set_power(50)
    time.sleep(1)
    speed = __encoder_motor_1.get_value("speed")
    print("speed: %d" %speed)
    position1 = __encoder_motor_1.get_value("angle")
    print("position1: %d" %position1)
ranging_sensor --- 激光测距模块

ranging_sensor 模块的主要功能与函数

激光测距模块说明

激光测距模块模块外观如下图所示:

_images/ranging_sensor.png
功能相关函数
ranging_sensor.get_distance()

获取超声波传感器测量的前方障碍物的距离,单位是 厘米,返回的数据是浮点类型数值。 测量的范围是 2 ~ 200 厘米,2厘米以内的测量数据会不准确,当实际距离小于2cm或者大于200cm时,获取到的数据都是200。

程序示例:
import novapi
from mbuild.ranging_sensor import ranging_sensor_class

#先初始化,定义激光测距模块接在PORT1口的第1个
__ranging_sensor_1 = ranging_sensor_class("PORT1", "INDEX1")

while True:
  centimeter = __ranging_sensor_1.get_distance()
  print("centimeter1: ", centimeter)
  time.sleep(1
smartservo --- 智能舵机

smartservo 模块的主要功能与函数

智能舵机说明

mbuild模块的智能舵机模块如下图所示:

_images/smartservo.png
功能相关函数
smartservo.set_zero()

设置当前位置为零点。

smartservo.move_to(position, speed)

按指定转速移动到绝对角度,参数:

  • position 目标角度,单位为度,范围 -2147483648~2147483647
  • speed 转速,单位为rpm/min,范围 1~50
smartservo.move(position, speed)

按指定转速移动到相对角度,参数:

  • position 目标角度,单位为度,范围 -2147483648~2147483647
  • speed 转速,单位为rpm/min,范围 1~50
smartservo.set_power(pwm)

设置电机以指定动力转动,开环控制,参数:

  • pwm 转速,单位为 ,范围 -100~100
smartservo.get_value(type)

获取电机数据,参数:

  • type 获取数据类型,字符串类型,参数可以选择为:

    "current":电流,单位A

    "voltage":电压,单位V

    "speed":速度,单位rpm/min

    "angle":角度,单位度

    "temperature":温度,单位摄氏度

程序示例1:
import novapi
from mbuild.smartservo import smartservo_class

#先初始化,定义智能舵机接在M1口的第1个
__smartservo_1 = smartservo_class("M1", "INDEX1")

while True:
    __smartservo_1.set_zero()
    time.sleep(0.1)

    __smartservo_1.move_to(360, 20)
    time.sleep(4)
    position = __smartservo_1.get_value("angle")
    print("position: " ,position)

    __smartservo_1.move(-360, 20)
    time.sleep(4)
    position = __smartservo_1.get_value("angle")
    print("position: ",position)

    __smartservo_1.set_power(50)
    time.sleep(1)

    param0 = __smartservo_1.get_value("current")
    print("current: " ,param0)

    param1 = __smartservo_1.get_value("voltage")
    print("voltage: " ,param1)

    param2 = __smartservo_1.get_value("speed")
    print("speed: " ,param2)

    param3 = __smartservo_1.get_value("angle")
    print("angle: " ,param3)

    param4 = __smartservo_1.get_value("temperature")
    print("temperature: ", param4)
power_expand_board --- 动力扩展板

power_expand_board 模块的主要功能与函数

动力扩展板说明

动力扩展板外观如下图所示:

_images/power_expand_board.png
功能相关函数
power_expand_board.set_power(ch, pwm)

设置直流电机以指定动力转动,开环控制,参数:

  • ch 通道,直流电机通道/电磁阀通道为 "CH1" ~ "CH8", 无刷电机通道为 "BL1" ~ "BL2"
  • pwm 转速,单位为 ,范围 -100~100, 当设置电磁阀断电时pwn为0,当设置电磁阀通电时pwm为100。
power_expand_board.stop(ch)

使直流电机/无刷电机停止运转,参数:

  • ch 通道,直流电机通道为 "CH1" ~ "CH8", 无刷电机通道为 "BL1" ~ "BL2", 所有通道为 "ALL"
程序示例:
import novapi
from mbuild import power_expand_board

while True:
  time.sleep(1)

  power_expand_board.set_power("DC1",100) #直流电机
  power_expand_board.set_power("DC2",100)
  power_expand_board.set_power("DC3",100)
  power_expand_board.set_power("DC4",100)
  power_expand_board.set_power("DC5",100)
  power_expand_board.set_power("DC6",100)
  power_expand_board.set_power("DC7",100)
  power_expand_board.set_power("DC8",100)
  power_expand_board.set_power("BL1",100) #无刷电机
  power_expand_board.set_power("BL2",100)
  time.sleep(2)

  power_expand_board.stop("DC1",100)
  power_expand_board.stop("DC2",100)
  power_expand_board.stop("DC3",100)
  power_expand_board.stop("DC4",100)
  power_expand_board.stop("DC5",100)
  power_expand_board.stop("DC6",100)
  power_expand_board.stop("DC7",100)
  power_expand_board.stop("DC8",100)
  power_expand_board.stop("BL1",100)
  power_expand_board.stop("BL2",100)

  #电磁阀1设置为断电
  power_expand_board.set_power("DC1",0)
  time.sleep(2)

  #电磁阀1设置为通电
  power_expand_board.set_power("DC1",100)
  time.sleep(2)

  #停止所有电机
  power_expand_board.stop("ALL")

第三方类库的python接口

第三方类库的python接口API如下:

novapi的实例教程

本教程的目的是让您开始novapi主控的python的使用。 我们需要你有一块novapi主控板,其次您还需要一根USB线(或者蓝牙dongle)可以连接到电脑。 如果你是第一次使用novapi主控板的python编程,建议阅读一下这部分的内容。

novapi主控 典型实例

novapi主控的micropython使用说明

添加自定义类库或者代码文件

如何将自己编写的一些Python脚本,或者python的类库添加到固件中。

使用mblock5软件

可以下载和使用 mblock5 来进行python程序的编写以及程序的上传。

_images/4.png
  1. 如上图所示,打开mblock5软件后,连接好设备,并确定当前模式是 上传模式。
  2. 确定当前是 python 模式(默认是积木模式)
  3. 在代码编辑区编写自己的执行代码
  4. 点击 上传到设备 将代码烧录进小程。
使用firefly_upload脚本

可以下载和使用 firefly_upload 这个python脚本来进行python程序的上传。它除了可以上传 main.py, 也可以上传第三方或者自定义的类库以供 main.py调用。

下载地址: https://github.com/YanMinge/firefly_upload

_images/5.png
  1. 下载脚本,该脚本可以支持 python2 和 python3 环境下的使用。
  2. 因为上传会使用到串口,所以需要安装 pyserial 的库,最好是用 pip 安装 pip install pyserial
  3. 因为上传使用了一个进度条的工具,所以需要安装 progressbar2 的库,最好是用 pip 安装 pip install progressbar2
  4. 在 shell 或者 cmd 界面 输入 在shell 中输入 python firefly_upload.py -p [串口名称] -i [文件的路径] -o [文件烧入flash的路径] 如windows示例: python firefly_upload.py -p COM5 -i C:/Users/MBENBEN/Desktop/test/main.py -o /flash/main.py

使用mpy-cross工具生成mpy文件

版权声明:文本编辑整理属于Yanminge,转载时请以超链接形式标明文章原始出处和作者信息及本声明

接触过Python语言的人都知道,Python可以编译成.pyc文件,它是一种二进制文件,可以提高程序的加载速度,同时也是一种保护源代码的有效方法。 在micropython中,也提供了类似的功能,可以将.py文件编译成.mpy文件。接下来,介绍一下具体的实现步骤。(本文以 mingw32 工具链为例, 使用小程作为目标主板)

搭建micropython编译环境

注意: 在不同的系统环境以及不同的目标主板,micropython的开发环境安装是有差别的,这里仅以乐鑫esp32的mingw32工具链作为示意。我们需要用到它的 xtensa-esp32-elf

  1. 参考乐鑫 设置工具链,以 windows系统为例,可以从乐鑫的官网下载 Windows all-in-one工具链 & MSYS2 zip包,将zip文件解压缩到C盘的根目录(也可以是其他一些位置,但本文档假定为 C:\ ),它将创建一个带有预先准备好的环境的msys32目录。
  2. 下载micropython源码包到本地,我下载到了G盘的根目录下。
生成mpy文件
  1. 执行msys32目录中的 mingw32.exe 切换到 /g/micropython/mpy-cross 目录执行make,编译生成mpy-cross工具。
_images/15.png _images/22.png
  1. 在mpy-cross目录新建一下main.py文件,以小程为例,写一个测试程序用于验证。
import codey
import time

codey.led.show(2555,255,255)
time.sleep(2)
codey.led.off()
time.sleep(2)
while True:
    codey.led.set_red(255)
    time.sleep(1)
    codey.led.set_green(255)
    time.sleep(1)
    codey.led.set_blue(255)
    time.sleep(1)
    codey.led.off()
    time.sleep(1)
  1. 执行编译mpy文件的命令。

其他相关功能可查看同目录下的README.md文件。

  1. 命令执行成功后,你就能发现同目录下出现了一个main.mpy文件。
_images/3.png
  1. 将 main.mpy 文件拷贝放到小程的flash中,如果是 main文件名的话,小程会自动运行。
烧录 *.py 或者 *.mpy 文件的说明见

注意: 如果运行时出现“ValueError: invalid .mpy file”错误的话,需要更新一下主板的micropython固件(最新固件跟随mblock最新版本发布)。

microPython 官方类库

警告

本章节的重要摘要

  • MicroPython为每个模块实现了Python功能的子集。
  • 为了简化可扩展性,MicroPython版本的标准Python模块通常有``u``(“micro”)前缀。
  • 任何特定的MicroPython主板分支都可能遗漏本通用文档中描述的部分功能/函数(由于资源限制或其他限制)。

本章介绍了构成micropython的模块(函数和类库)。有几类模块:

  • 内置模块:标准Python功能的子集,用户不能扩展。
  • 扩展模块:实现了Python功能的一个子集,并提供用户扩展(通过Python代码)。
  • 扩展模块:实现micropython的Python标准库。
  • 硬件驱动模块:特定端口或者硬件驱动的模块,因此不可移植。

请注意模块及其内容的可用性:本文档通常所描述所有模块和函数/类在MicroPython项目中都会尽量实现。 但是,MicroPython具有高度可配置性,所以在特定主板/嵌入式系统中可能会仅提供一个子集MicroPython库。 对于官方支持的端口,我们会尽量过滤掉不适用的项目,或标记个别模块的“可用性:” 即使用子句描述主板提供的功能。

考虑到这一点,请仍然警告一些函数/类在本文档中描述的模块(甚至整个模块)中 可能在特定系统上的特定MicroPython版本中不可用。 该查找可用性/不可用性的一般信息的最佳位置特定功能的“通用信息”部分包含有关特定`MicroPython主板`的信息。

在某些端口上,可用的内置库的查询,可以通过在REPL中输入以下内容来导入:: REPL:

help('modules')

除了本文档中描述的内置库之外,还有更多来自Python标准库的模块,它们可以提供更多的MicroPython 的扩展,可以github的 `micropython-lib`找到.

micropython 标准库

标准的Python库被 “微型化”后,就是micropython标准库。它们仅仅提供了该模块的核心功能。一些模块没有直接使用标准的Python的名字,而是冠以"u",例如 ujson 代替 json。也就是说micropython标准库(=微型库),只实现了一部分模块功能。通过他们的名字不同,用户有选择的去写一个Python级模块扩展功能,也是为实现更好的兼容性。

在嵌入式平台上,可添加Python级别封装库从而实现命名兼容CPython,微模块即可调用他们的u-name,也可以调用non-u-name。根据non-u-name包路径的文件可重写。

例如, import json 的话,首先搜索一个 json.py 文件或 json 目录进行加载。如果没有找到,它回退到加载内置 ujson 模块。

Builtin functions and exceptions

All builtin functions and exceptions are described here. They are also available via builtins module.

Functions and types
abs()
all()
any()
bin()
class bool
class bytearray
class bytes

See CPython documentation: python:bytes.

callable()
chr()
classmethod()
compile()
class complex
delattr(obj, name)

The argument name should be a string, and this function deletes the named attribute from the object given by obj.

class dict
dir()
divmod()
enumerate()
eval()
exec()
filter()
class float
class frozenset
getattr()
globals()
hasattr()
hash()
hex()
id()
input()
class int
classmethod from_bytes(bytes, byteorder)

In MicroPython, byteorder parameter must be positional (this is compatible with CPython).

to_bytes(size, byteorder)

In MicroPython, byteorder parameter must be positional (this is compatible with CPython).

isinstance()
issubclass()
iter()
len()
class list
locals()
map()
max()
class memoryview
min()
next()
class object
oct()
open()
ord()
pow()
print()
property()
range()
repr()
reversed()
round()
class set
setattr()
class slice

The slice builtin is the type that slice objects have.

sorted()
staticmethod()
class str
sum()
super()
class tuple
type()
zip()
Exceptions
exception AssertionError
exception AttributeError
exception Exception
exception ImportError
exception IndexError
exception KeyboardInterrupt
exception KeyError
exception MemoryError
exception NameError
exception NotImplementedError
exception OSError

See CPython documentation: python:OSError. MicroPython doesn't implement errno attribute, instead use the standard way to access exception arguments: exc.args[0].

exception RuntimeError
exception StopIteration
exception SyntaxError
exception SystemExit

See CPython documentation: python:SystemExit.

exception TypeError

See CPython documentation: python:TypeError.

exception ValueError
exception ZeroDivisionError

array -- arrays of numeric data

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:array.

Supported format codes: b, B, h, H, i, I, l, L, q, Q, f, d (the latter 2 depending on the floating-point support).

Classes
class array.array(typecode[, iterable])

Create array with elements of given type. Initial contents of the array are given by iterable. If it is not provided, an empty array is created.

append(val)

Append new element val to the end of array, growing it.

extend(iterable)

Append new elements as contained in iterable to the end of array, growing it.

cmath -- mathematical functions for complex numbers

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:cmath.

The cmath module provides some basic mathematical functions for working with complex numbers.

Availability: not available on WiPy and ESP8266. Floating point support required for this module.

Functions
cmath.cos(z)

Return the cosine of z.

cmath.exp(z)

Return the exponential of z.

cmath.log(z)

Return the natural logarithm of z. The branch cut is along the negative real axis.

cmath.log10(z)

Return the base-10 logarithm of z. The branch cut is along the negative real axis.

cmath.phase(z)

Returns the phase of the number z, in the range (-pi, +pi].

cmath.polar(z)

Returns, as a tuple, the polar form of z.

cmath.rect(r, phi)

Returns the complex number with modulus r and phase phi.

cmath.sin(z)

Return the sine of z.

cmath.sqrt(z)

Return the square-root of z.

Constants
cmath.e

base of the natural logarithm

cmath.pi

the ratio of a circle's circumference to its diameter

gc -- control the garbage collector

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:gc.

Functions
gc.enable()

Enable automatic garbage collection.

gc.disable()

Disable automatic garbage collection. Heap memory can still be allocated, and garbage collection can still be initiated manually using gc.collect().

gc.collect()

Run a garbage collection.

gc.mem_alloc()

Return the number of bytes of heap RAM that are allocated.

Difference to CPython

This function is MicroPython extension.

gc.mem_free()

Return the number of bytes of available heap RAM, or -1 if this amount is not known.

Difference to CPython

This function is MicroPython extension.

gc.threshold([amount])

Set or query the additional GC allocation threshold. Normally, a collection is triggered only when a new allocation cannot be satisfied, i.e. on an out-of-memory (OOM) condition. If this function is called, in addition to OOM, a collection will be triggered each time after amount bytes have been allocated (in total, since the previous time such an amount of bytes have been allocated). amount is usually specified as less than the full heap size, with the intention to trigger a collection earlier than when the heap becomes exhausted, and in the hope that an early collection will prevent excessive memory fragmentation. This is a heuristic measure, the effect of which will vary from application to application, as well as the optimal value of the amount parameter.

Calling the function without argument will return the current value of the threshold. A value of -1 means a disabled allocation threshold.

Difference to CPython

This function is a MicroPython extension. CPython has a similar function - set_threshold(), but due to different GC implementations, its signature and semantics are different.

math -- mathematical functions

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:math.

The math module provides some basic mathematical functions for working with floating-point numbers.

Note: On the pyboard, floating-point numbers have 32-bit precision.

Availability: not available on WiPy. Floating point support required for this module.

Functions
math.acos(x)

Return the inverse cosine of x.

math.acosh(x)

Return the inverse hyperbolic cosine of x.

math.asin(x)

Return the inverse sine of x.

math.asinh(x)

Return the inverse hyperbolic sine of x.

math.atan(x)

Return the inverse tangent of x.

math.atan2(y, x)

Return the principal value of the inverse tangent of y/x.

math.atanh(x)

Return the inverse hyperbolic tangent of x.

math.ceil(x)

Return an integer, being x rounded towards positive infinity.

math.copysign(x, y)

Return x with the sign of y.

math.cos(x)

Return the cosine of x.

math.cosh(x)

Return the hyperbolic cosine of x.

math.degrees(x)

Return radians x converted to degrees.

math.erf(x)

Return the error function of x.

math.erfc(x)

Return the complementary error function of x.

math.exp(x)

Return the exponential of x.

math.expm1(x)

Return exp(x) - 1.

math.fabs(x)

Return the absolute value of x.

math.floor(x)

Return an integer, being x rounded towards negative infinity.

math.fmod(x, y)

Return the remainder of x/y.

math.frexp(x)

Decomposes a floating-point number into its mantissa and exponent. The returned value is the tuple (m, e) such that x == m * 2**e exactly. If x == 0 then the function returns (0.0, 0), otherwise the relation 0.5 <= abs(m) < 1 holds.

math.gamma(x)

Return the gamma function of x.

math.isfinite(x)

Return True if x is finite.

math.isinf(x)

Return True if x is infinite.

math.isnan(x)

Return True if x is not-a-number

math.ldexp(x, exp)

Return x * (2**exp).

math.lgamma(x)

Return the natural logarithm of the gamma function of x.

math.log(x)

Return the natural logarithm of x.

math.log10(x)

Return the base-10 logarithm of x.

math.log2(x)

Return the base-2 logarithm of x.

math.modf(x)

Return a tuple of two floats, being the fractional and integral parts of x. Both return values have the same sign as x.

math.pow(x, y)

Returns x to the power of y.

math.radians(x)

Return degrees x converted to radians.

math.sin(x)

Return the sine of x.

math.sinh(x)

Return the hyperbolic sine of x.

math.sqrt(x)

Return the square root of x.

math.tan(x)

Return the tangent of x.

math.tanh(x)

Return the hyperbolic tangent of x.

math.trunc(x)

Return an integer, being x rounded towards 0.

Constants
math.e

base of the natural logarithm

math.pi

the ratio of a circle's circumference to its diameter

sys -- system specific functions

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:sys.

Functions
sys.exit(retval=0)

Terminate current program with a given exit code. Underlyingly, this function raise as SystemExit exception. If an argument is given, its value given as an argument to SystemExit.

sys.print_exception(exc, file=sys.stdout)

Print exception with a traceback to a file-like object file (or sys.stdout by default).

Difference to CPython

This is simplified version of a function which appears in the traceback module in CPython. Unlike traceback.print_exception(), this function takes just exception value instead of exception type, exception value, and traceback object; file argument should be positional; further arguments are not supported. CPython-compatible traceback module can be found in micropython-lib.

Constants
sys.argv

A mutable list of arguments the current program was started with.

sys.byteorder

The byte order of the system ("little" or "big").

sys.implementation

Object with information about the current Python implementation. For MicroPython, it has following attributes:

  • name - string "micropython"
  • version - tuple (major, minor, micro), e.g. (1, 7, 0)

This object is the recommended way to distinguish MicroPython from other Python implementations (note that it still may not exist in the very minimal ports).

Difference to CPython

CPython mandates more attributes for this object, but the actual useful bare minimum is implemented in MicroPython.

sys.maxsize

Maximum value which a native integer type can hold on the current platform, or maximum value representable by MicroPython integer type, if it's smaller than platform max value (that is the case for MicroPython ports without long int support).

This attribute is useful for detecting "bitness" of a platform (32-bit vs 64-bit, etc.). It's recommended to not compare this attribute to some value directly, but instead count number of bits in it:

bits = 0
v = sys.maxsize
while v:
    bits += 1
    v >>= 1
if bits > 32:
    # 64-bit (or more) platform
    ...
else:
    # 32-bit (or less) platform
    # Note that on 32-bit platform, value of bits may be less than 32
    # (e.g. 31) due to peculiarities described above, so use "> 16",
    # "> 32", "> 64" style of comparisons.
sys.modules

Dictionary of loaded modules. On some ports, it may not include builtin modules.

sys.path

A mutable list of directories to search for imported modules.

sys.platform

The platform that MicroPython is running on. For OS/RTOS ports, this is usually an identifier of the OS, e.g. "linux". For baremetal ports it is an identifier of a board, e.g. "pyboard" for the original MicroPython reference board. It thus can be used to distinguish one board from another. If you need to check whether your program runs on MicroPython (vs other Python implementation), use sys.implementation instead.

sys.stderr

Standard error stream.

sys.stdin

Standard input stream.

sys.stdout

Standard output stream.

sys.version

Python language version that this implementation conforms to, as a string.

sys.version_info

Python language version that this implementation conforms to, as a tuple of ints.

ubinascii -- binary/ASCII conversions

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:binascii.

This module implements conversions between binary data and various encodings of it in ASCII form (in both directions).

Functions
ubinascii.hexlify(data[, sep])

Convert binary data to hexadecimal representation. Returns bytes string.

Difference to CPython

If additional argument, sep is supplied, it is used as a separator between hexadecimal values.

ubinascii.unhexlify(data)

Convert hexadecimal data to binary representation. Returns bytes string. (i.e. inverse of hexlify)

ubinascii.a2b_base64(data)

Decode base64-encoded data, ignoring invalid characters in the input. Conforms to RFC 2045 s.6.8. Returns a bytes object.

ubinascii.b2a_base64(data)

Encode binary data in base64 format, as in RFC 3548. Returns the encoded data followed by a newline character, as a bytes object.

ucollections -- collection and container types

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:collections.

This module implements advanced collection and container types to hold/accumulate various objects.

Classes
ucollections.deque(iterable, maxlen[, flags])

Deques (double-ended queues) are a list-like container that support O(1) appends and pops from either side of the deque. New deques are created using the following arguments:

  • iterable must be the empty tuple, and the new deque is created empty.
  • maxlen must be specified and the deque will be bounded to this maximum length. Once the deque is full, any new items added will discard items from the opposite end.
  • The optional flags can be 1 to check for overflow when adding items.

As well as supporting bool and len, deque objects have the following methods:

deque.append(x)

Add x to the right side of the deque. Raises IndexError if overflow checking is enabled and there is no more room left.

deque.popleft()

Remove and return an item from the left side of the deque. Raises IndexError if no items are present.

ucollections.namedtuple(name, fields)

This is factory function to create a new namedtuple type with a specific name and set of fields. A namedtuple is a subclass of tuple which allows to access its fields not just by numeric index, but also with an attribute access syntax using symbolic field names. Fields is a sequence of strings specifying field names. For compatibility with CPython it can also be a a string with space-separated field named (but this is less efficient). Example of use:

from ucollections import namedtuple

MyTuple = namedtuple("MyTuple", ("id", "name"))
t1 = MyTuple(1, "foo")
t2 = MyTuple(2, "bar")
print(t1.name)
assert t2.name == t2[1]
ucollections.OrderedDict(...)

dict type subclass which remembers and preserves the order of keys added. When ordered dict is iterated over, keys/items are returned in the order they were added:

from ucollections import OrderedDict

# To make benefit of ordered keys, OrderedDict should be initialized
# from sequence of (key, value) pairs.
d = OrderedDict([("z", 1), ("a", 2)])
# More items can be added as usual
d["w"] = 5
d["b"] = 3
for k, v in d.items():
    print(k, v)

Output:

z 1
a 2
w 5
b 3

uerrno -- system error codes

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:errno.

This module provides access to symbolic error codes for OSError exception. A particular inventory of codes depends on MicroPython port.

Constants
EEXIST, EAGAIN, etc.

Error codes, based on ANSI C/POSIX standard. All error codes start with "E". As mentioned above, inventory of the codes depends on MicroPython port. Errors are usually accessible as exc.args[0] where exc is an instance of OSError. Usage example:

try:
    uos.mkdir("my_dir")
except OSError as exc:
    if exc.args[0] == uerrno.EEXIST:
        print("Directory already exists")
uerrno.errorcode

Dictionary mapping numeric error codes to strings with symbolic error code (see above):

>>> print(uerrno.errorcode[uerrno.EEXIST])
EEXIST

uhashlib -- hashing algorithms

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:hashlib.

This module implements binary data hashing algorithms. The exact inventory of available algorithms depends on a board. Among the algorithms which may be implemented:

  • SHA256 - The current generation, modern hashing algorithm (of SHA2 series). It is suitable for cryptographically-secure purposes. Included in the MicroPython core and any board is recommended to provide this, unless it has particular code size constraints.
  • SHA1 - A previous generation algorithm. Not recommended for new usages, but SHA1 is a part of number of Internet standards and existing applications, so boards targeting network connectivity and interoperatiability will try to provide this.
  • MD5 - A legacy algorithm, not considered cryptographically secure. Only selected boards, targeting interoperatibility with legacy applications, will offer this.
Constructors
class uhashlib.sha256([data])

Create an SHA256 hasher object and optionally feed data into it.

class uhashlib.sha1([data])

Create an SHA1 hasher object and optionally feed data into it.

class uhashlib.md5([data])

Create an MD5 hasher object and optionally feed data into it.

Methods
hash.update(data)

Feed more binary data into hash.

hash.digest()

Return hash for all data passed through hash, as a bytes object. After this method is called, more data cannot be fed into the hash any longer.

hash.hexdigest()

This method is NOT implemented. Use ubinascii.hexlify(hash.digest()) to achieve a similar effect.

uheapq -- heap queue algorithm

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:heapq.

This module implements the heap queue algorithm.

A heap queue is simply a list that has its elements stored in a certain way.

Functions
uheapq.heappush(heap, item)

Push the item onto the heap.

uheapq.heappop(heap)

Pop the first item from the heap, and return it. Raises IndexError if heap is empty.

uheapq.heapify(x)

Convert the list x into a heap. This is an in-place operation.

uio -- input/output streams

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:io.

This module contains additional types of stream (file-like) objects and helper functions.

Conceptual hierarchy

Difference to CPython

Conceptual hierarchy of stream base classes is simplified in MicroPython, as described in this section.

(Abstract) base stream classes, which serve as a foundation for behavior of all the concrete classes, adhere to few dichotomies (pair-wise classifications) in CPython. In MicroPython, they are somewhat simplified and made implicit to achieve higher efficiencies and save resources.

An important dichotomy in CPython is unbuffered vs buffered streams. In MicroPython, all streams are currently unbuffered. This is because all modern OSes, and even many RTOSes and filesystem drivers already perform buffering on their side. Adding another layer of buffering is counter- productive (an issue known as "bufferbloat") and takes precious memory. Note that there still cases where buffering may be useful, so we may introduce optional buffering support at a later time.

But in CPython, another important dichotomy is tied with "bufferedness" - it's whether a stream may incur short read/writes or not. A short read is when a user asks e.g. 10 bytes from a stream, but gets less, similarly for writes. In CPython, unbuffered streams are automatically short operation susceptible, while buffered are guarantee against them. The no short read/writes is an important trait, as it allows to develop more concise and efficient programs - something which is highly desirable for MicroPython. So, while MicroPython doesn't support buffered streams, it still provides for no-short-operations streams. Whether there will be short operations or not depends on each particular class' needs, but developers are strongly advised to favor no-short-operations behavior for the reasons stated above. For example, MicroPython sockets are guaranteed to avoid short read/writes. Actually, at this time, there is no example of a short-operations stream class in the core, and one would be a port-specific class, where such a need is governed by hardware peculiarities.

The no-short-operations behavior gets tricky in case of non-blocking streams, blocking vs non-blocking behavior being another CPython dichotomy, fully supported by MicroPython. Non-blocking streams never wait for data either to arrive or be written - they read/write whatever possible, or signal lack of data (or ability to write data). Clearly, this conflicts with "no-short-operations" policy, and indeed, a case of non-blocking buffered (and this no-short-ops) streams is convoluted in CPython - in some places, such combination is prohibited, in some it's undefined or just not documented, in some cases it raises verbose exceptions. The matter is much simpler in MicroPython: non-blocking stream are important for efficient asynchronous operations, so this property prevails on the "no-short-ops" one. So, while blocking streams will avoid short reads/writes whenever possible (the only case to get a short read is if end of file is reached, or in case of error (but errors don't return short data, but raise exceptions)), non-blocking streams may produce short data to avoid blocking the operation.

The final dichotomy is binary vs text streams. MicroPython of course supports these, but while in CPython text streams are inherently buffered, they aren't in MicroPython. (Indeed, that's one of the cases for which we may introduce buffering support.)

Note that for efficiency, MicroPython doesn't provide abstract base classes corresponding to the hierarchy above, and it's not possible to implement, or subclass, a stream class in pure Python.

Functions
uio.open(name, mode='r', **kwargs)

Open a file. Builtin open() function is aliased to this function. All ports (which provide access to file system) are required to support mode parameter, but support for other arguments vary by port.

Classes
class uio.FileIO(...)

This is type of a file open in binary mode, e.g. using open(name, "rb"). You should not instantiate this class directly.

class uio.TextIOWrapper(...)

This is type of a file open in text mode, e.g. using open(name, "rt"). You should not instantiate this class directly.

class uio.StringIO([string])
class uio.BytesIO([string])

In-memory file-like objects for input/output. StringIO is used for text-mode I/O (similar to a normal file opened with "t" modifier). BytesIO is used for binary-mode I/O (similar to a normal file opened with "b" modifier). Initial contents of file-like objects can be specified with string parameter (should be normal string for StringIO or bytes object for BytesIO). All the usual file methods like read(), write(), seek(), flush(), close() are available on these objects, and additionally, a following method:

getvalue()

Get the current contents of the underlying buffer which holds data.

ujson -- JSON encoding and decoding

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:json.

This modules allows to convert between Python objects and the JSON data format.

Functions
ujson.dump(obj, stream)

Serialise obj to a JSON string, writing it to the given stream.

ujson.dumps(obj)

Return obj represented as a JSON string.

ujson.load(stream)

Parse the given stream, interpreting it as a JSON string and deserialising the data to a Python object. The resulting object is returned.

Parsing continues until end-of-file is encountered. A ValueError is raised if the data in stream is not correctly formed.

ujson.loads(str)

Parse the JSON str and return an object. Raises ValueError if the string is not correctly formed.

uos -- basic "operating system" services

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:os.

The uos module contains functions for filesystem access and mounting, terminal redirection and duplication, and the uname and urandom functions.

General functions
uos.uname()

Return a tuple (possibly a named tuple) containing information about the underlying machine and/or its operating system. The tuple has five fields in the following order, each of them being a string:

  • sysname -- the name of the underlying system
  • nodename -- the network name (can be the same as sysname)
  • release -- the version of the underlying system
  • version -- the MicroPython version and build date
  • machine -- an identifier for the underlying hardware (eg board, CPU)
uos.urandom(n)

Return a bytes object with n random bytes. Whenever possible, it is generated by the hardware random number generator.

Filesystem access
uos.chdir(path)

Change current directory.

uos.getcwd()

Get the current directory.

uos.ilistdir([dir])

This function returns an iterator which then yields tuples corresponding to the entries in the directory that it is listing. With no argument it lists the current directory, otherwise it lists the directory given by dir.

The tuples have the form (name, type, inode[, size]):

  • name is a string (or bytes if dir is a bytes object) and is the name of the entry;
  • type is an integer that specifies the type of the entry, with 0x4000 for directories and 0x8000 for regular files;
  • inode is an integer corresponding to the inode of the file, and may be 0 for filesystems that don't have such a notion.
  • Some platforms may return a 4-tuple that includes the entry's size. For file entries, size is an integer representing the size of the file or -1 if unknown. Its meaning is currently undefined for directory entries.
uos.listdir([dir])

With no argument, list the current directory. Otherwise list the given directory.

uos.mkdir(path)

Create a new directory.

uos.remove(path)

Remove a file.

uos.rmdir(path)

Remove a directory.

uos.rename(old_path, new_path)

Rename a file.

uos.stat(path)

Get the status of a file or directory.

uos.statvfs(path)

Get the status of a fileystem.

Returns a tuple with the filesystem information in the following order:

  • f_bsize -- file system block size
  • f_frsize -- fragment size
  • f_blocks -- size of fs in f_frsize units
  • f_bfree -- number of free blocks
  • f_bavail -- number of free blocks for unpriviliged users
  • f_files -- number of inodes
  • f_ffree -- number of free inodes
  • f_favail -- number of free inodes for unpriviliged users
  • f_flag -- mount flags
  • f_namemax -- maximum filename length

Parameters related to inodes: f_files, f_ffree, f_avail and the f_flags parameter may return 0 as they can be unavailable in a port-specific implementation.

uos.sync()

Sync all filesystems.

Terminal redirection and duplication
uos.dupterm(stream_object, index=0)

Duplicate or switch the MicroPython terminal (the REPL) on the given stream-like object. The stream_object argument must implement the readinto() and write() methods. The stream should be in non-blocking mode and readinto() should return None if there is no data available for reading.

After calling this function all terminal output is repeated on this stream, and any input that is available on the stream is passed on to the terminal input.

The index parameter should be a non-negative integer and specifies which duplication slot is set. A given port may implement more than one slot (slot 0 will always be available) and in that case terminal input and output is duplicated on all the slots that are set.

If None is passed as the stream_object then duplication is cancelled on the slot given by index.

The function returns the previous stream-like object in the given slot.

Filesystem mounting

Some ports provide a Virtual Filesystem (VFS) and the ability to mount multiple "real" filesystems within this VFS. Filesystem objects can be mounted at either the root of the VFS, or at a subdirectory that lives in the root. This allows dynamic and flexible configuration of the filesystem that is seen by Python programs. Ports that have this functionality provide the mount() and umount() functions, and possibly various filesystem implementations represented by VFS classes.

uos.mount(fsobj, mount_point, *, readonly)

Mount the filesystem object fsobj at the location in the VFS given by the mount_point string. fsobj can be a a VFS object that has a mount() method, or a block device. If it's a block device then the filesystem type is automatically detected (an exception is raised if no filesystem was recognised). mount_point may be '/' to mount fsobj at the root, or '/<name>' to mount it at a subdirectory under the root.

If readonly is True then the filesystem is mounted read-only.

During the mount process the method mount() is called on the filesystem object.

Will raise OSError(EPERM) if mount_point is already mounted.

uos.umount(mount_point)

Unmount a filesystem. mount_point can be a string naming the mount location, or a previously-mounted filesystem object. During the unmount process the method umount() is called on the filesystem object.

Will raise OSError(EINVAL) if mount_point is not found.

class uos.VfsFat(block_dev)

Create a filesystem object that uses the FAT filesystem format. Storage of the FAT filesystem is provided by block_dev. Objects created by this constructor can be mounted using mount().

static mkfs(block_dev)

Build a FAT filesystem on block_dev.

Block devices

A block device is an object which implements the block protocol, which is a set of methods described below by the AbstractBlockDev class. A concrete implementation of this class will usually allow access to the memory-like functionality a piece of hardware (like flash memory). A block device can be used by a particular filesystem driver to store the data for its filesystem.

class uos.AbstractBlockDev(...)

Construct a block device object. The parameters to the constructor are dependent on the specific block device.

readblocks(block_num, buf)

Starting at the block given by the index block_num, read blocks from the device into buf (an array of bytes). The number of blocks to read is given by the length of buf, which will be a multiple of the block size.

writeblocks(block_num, buf)

Starting at the block given by the index block_num, write blocks from buf (an array of bytes) to the device. The number of blocks to write is given by the length of buf, which will be a multiple of the block size.

ioctl(op, arg)

Control the block device and query its parameters. The operation to perform is given by op which is one of the following integers:

  • 1 -- initialise the device (arg is unused)
  • 2 -- shutdown the device (arg is unused)
  • 3 -- sync the device (arg is unused)
  • 4 -- get a count of the number of blocks, should return an integer (arg is unused)
  • 5 -- get the number of bytes in a block, should return an integer, or None in which case the default value of 512 is used (arg is unused)

By way of example, the following class will implement a block device that stores its data in RAM using a bytearray:

class RAMBlockDev:
    def __init__(self, block_size, num_blocks):
        self.block_size = block_size
        self.data = bytearray(block_size * num_blocks)

    def readblocks(self, block_num, buf):
        for i in range(len(buf)):
            buf[i] = self.data[block_num * self.block_size + i]

    def writeblocks(self, block_num, buf):
        for i in range(len(buf)):
            self.data[block_num * self.block_size + i] = buf[i]

    def ioctl(self, op, arg):
        if op == 4: # get number of blocks
            return len(self.data) // self.block_size
        if op == 5: # get block size
            return self.block_size

It can be used as follows:

import uos

bdev = RAMBlockDev(512, 50)
uos.VfsFat.mkfs(bdev)
vfs = uos.VfsFat(bdev)
uos.mount(vfs, '/ramdisk')

ure -- simple regular expressions

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:re.

This module implements regular expression operations. Regular expression syntax supported is a subset of CPython re module (and actually is a subset of POSIX extended regular expressions).

Supported operators are:

'.'
Match any character.
'[...]'
Match set of characters. Individual characters and ranges are supported, including negated sets (e.g. [^a-c]).
'^'
Match the start of the string.
'$'
Match the end of the string.
'?'
Match zero or one of the previous entity.
'*'
Match zero or more of the previous entity.
'+'
Match one or more of the previous entity.

'??'

'*?'

'+?'

'|'
Match either the LHS or the RHS of this operator.
'(...)'
Grouping. Each group is capturing (a substring it captures can be accessed with match.group() method).

NOT SUPPORTED: Counted repetitions ({m,n}), more advanced assertions (\b, \B), named groups ((?P<name>...)), non-capturing groups ((?:...)), etc.

Functions
ure.compile(regex_str[, flags])

Compile regular expression, return regex object.

ure.match(regex_str, string)

Compile regex_str and match against string. Match always happens from starting position in a string.

ure.search(regex_str, string)

Compile regex_str and search it in a string. Unlike match, this will search string for first position which matches regex (which still may be 0 if regex is anchored).

ure.sub(regex_str, replace, string, count=0, flags=0)

Compile regex_str and search for it in string, replacing all matches with replace, and returning the new string.

replace can be a string or a function. If it is a string then escape sequences of the form \<number> and \g<number> can be used to expand to the corresponding group (or an empty string for unmatched groups). If replace is a function then it must take a single argument (the match) and should return a replacement string.

If count is specified and non-zero then substitution will stop after this many substitutions are made. The flags argument is ignored.

Note: availability of this function depends on MicroPython port.

ure.DEBUG

Flag value, display debug information about compiled expression. (Availability depends on MicroPython port.)

Regex objects

Compiled regular expression. Instances of this class are created using ure.compile().

regex.match(string)
regex.search(string)
regex.sub(replace, string, count=0, flags=0)

Similar to the module-level functions match(), search() and sub(). Using methods is (much) more efficient if the same regex is applied to multiple strings.

regex.split(string, max_split=-1)

Split a string using regex. If max_split is given, it specifies maximum number of splits to perform. Returns list of strings (there may be up to max_split+1 elements if it's specified).

Match objects

Match objects as returned by match() and search() methods, and passed to the replacement function in sub().

match.group([index])

Return matching (sub)string. index is 0 for entire match, 1 and above for each capturing group. Only numeric groups are supported.

match.groups()

Return a tuple containing all the substrings of the groups of the match.

Note: availability of this method depends on MicroPython port.

match.start([index])
match.end([index])

Return the index in the original string of the start or end of the substring group that was matched. index defaults to the entire group, otherwise it will select a group.

Note: availability of these methods depends on MicroPython port.

match.span([index])

Returns the 2-tuple (match.start(index), match.end(index)).

Note: availability of this method depends on MicroPython port.

uselect -- wait for events on a set of streams

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:select.

This module provides functions to efficiently wait for events on multiple streams (select streams which are ready for operations).

Functions
uselect.poll()

Create an instance of the Poll class.

uselect.select(rlist, wlist, xlist[, timeout])

Wait for activity on a set of objects.

This function is provided by some MicroPython ports for compatibility and is not efficient. Usage of Poll is recommended instead.

class Poll
Methods
poll.register(obj[, eventmask])

Register stream obj for polling. eventmask is logical OR of:

  • uselect.POLLIN - data available for reading
  • uselect.POLLOUT - more data can be written

Note that flags like uselect.POLLHUP and uselect.POLLERR are not valid as input eventmask (these are unsolicited events which will be returned from poll() regardless of whether they are asked for). This semantics is per POSIX.

eventmask defaults to uselect.POLLIN | uselect.POLLOUT.

poll.unregister(obj)

Unregister obj from polling.

poll.modify(obj, eventmask)

Modify the eventmask for obj.

poll.poll(timeout=-1)

Wait for at least one of the registered objects to become ready or have an exceptional condition, with optional timeout in milliseconds (if timeout arg is not specified or -1, there is no timeout).

Returns list of (obj, event, ...) tuples. There may be other elements in tuple, depending on a platform and version, so don't assume that its size is 2. The event element specifies which events happened with a stream and is a combination of uselect.POLL* constants described above. Note that flags uselect.POLLHUP and uselect.POLLERR can be returned at any time (even if were not asked for), and must be acted on accordingly (the corresponding stream unregistered from poll and likely closed), because otherwise all further invocations of poll() may return immediately with these flags set for this stream again.

In case of timeout, an empty list is returned.

Difference to CPython

Tuples returned may contain more than 2 elements as described above.

poll.ipoll(timeout=-1, flags=0)

Like poll.poll(), but instead returns an iterator which yields a callee-owned tuple. This function provides an efficient, allocation-free way to poll on streams.

If flags is 1, one-shot behavior for events is employed: streams for which events happened will have their event masks automatically reset (equivalent to poll.modify(obj, 0)), so new events for such a stream won't be processed until new mask is set with poll.modify(). This behavior is useful for asynchronous I/O schedulers.

Difference to CPython

This function is a MicroPython extension.

usocket -- socket module

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:socket.

This module provides access to the BSD socket interface.

Difference to CPython

For efficiency and consistency, socket objects in MicroPython implement a stream (file-like) interface directly. In CPython, you need to convert a socket to a file-like object using makefile() method. This method is still supported by MicroPython (but is a no-op), so where compatibility with CPython matters, be sure to use it.

Socket address format(s)

The native socket address format of the usocket module is an opaque data type returned by getaddrinfo function, which must be used to resolve textual address (including numeric addresses):

sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1]
# You must use getaddrinfo() even for numeric addresses
sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1]
# Now you can use that address
sock.connect(addr)

Using getaddrinfo is the most efficient (both in terms of memory and processing power) and portable way to work with addresses.

However, socket module (note the difference with native MicroPython usocket module described here) provides CPython-compatible way to specify addresses using tuples, as described below. Note that depending on a MicroPython port, socket module can be builtin or need to be installed from micropython-lib (as in the case of MicroPython Unix port), and some ports still accept only numeric addresses in the tuple format, and require to use getaddrinfo function to resolve domain names.

Summing up:

  • Always use getaddrinfo when writing portable applications.
  • Tuple addresses described below can be used as a shortcut for quick hacks and interactive use, if your port supports them.

Tuple address format for socket module:

  • IPv4: (ipv4_address, port), where ipv4_address is a string with dot-notation numeric IPv4 address, e.g. "8.8.8.8", and port is and integer port number in the range 1-65535. Note the domain names are not accepted as ipv4_address, they should be resolved first using usocket.getaddrinfo().
  • IPv6: (ipv6_address, port, flowinfo, scopeid), where ipv6_address is a string with colon-notation numeric IPv6 address, e.g. "2001:db8::1", and port is an integer port number in the range 1-65535. flowinfo must be 0. scopeid is the interface scope identifier for link-local addresses. Note the domain names are not accepted as ipv6_address, they should be resolved first using usocket.getaddrinfo(). Availability of IPv6 support depends on a MicroPython port.
Functions
usocket.socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP)

Create a new socket using the given address family, socket type and protocol number. Note that specifying proto in most cases is not required (and not recommended, as some MicroPython ports may omit IPPROTO_* constants). Instead, type argument will select needed protocol automatically:

# Create STREAM TCP socket
socket(AF_INET, SOCK_STREAM)
# Create DGRAM UDP socket
socket(AF_INET, SOCK_DGRAM)
usocket.getaddrinfo(host, port, af=0, type=0, proto=0, flags=0)

Translate the host/port argument into a sequence of 5-tuples that contain all the necessary arguments for creating a socket connected to that service. Arguments af, type, and proto (which have the same meaning as for the socket() function) can be used to filter which kind of addresses are returned. If a parameter is not specified or zero, all combinations of addresses can be returned (requiring filtering on the user side).

The resulting list of 5-tuples has the following structure:

(family, type, proto, canonname, sockaddr)

The following example shows how to connect to a given url:

s = usocket.socket()
# This assumes that if "type" is not specified, an address for
# SOCK_STREAM will be returned, which may be not true
s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1])

Recommended use of filtering params:

s = usocket.socket()
# Guaranteed to return an address which can be connect'ed to for
# stream operation.
s.connect(usocket.getaddrinfo('www.micropython.org', 80, 0, SOCK_STREAM)[0][-1])

Difference to CPython

CPython raises a socket.gaierror exception (OSError subclass) in case of error in this function. MicroPython doesn't have socket.gaierror and raises OSError directly. Note that error numbers of getaddrinfo() form a separate namespace and may not match error numbers from the uerrno module. To distinguish getaddrinfo() errors, they are represented by negative numbers, whereas standard system errors are positive numbers (error numbers are accessible using e.args[0] property from an exception object). The use of negative values is a provisional detail which may change in the future.

usocket.inet_ntop(af, bin_addr)

Convert a binary network address bin_addr of the given address family af to a textual representation:

>>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1")
'127.0.0.1'
usocket.inet_pton(af, txt_addr)

Convert a textual network address txt_addr of the given address family af to a binary representation:

>>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4")
b'\x01\x02\x03\x04'
Constants
usocket.AF_INET
usocket.AF_INET6

Address family types. Availability depends on a particular MicroPython port.

usocket.SOCK_STREAM
usocket.SOCK_DGRAM

Socket types.

usocket.IPPROTO_UDP
usocket.IPPROTO_TCP

IP protocol numbers. Availability depends on a particular MicroPython port. Note that you don't need to specify these in a call to usocket.socket(), because SOCK_STREAM socket type automatically selects IPPROTO_TCP, and SOCK_DGRAM - IPPROTO_UDP. Thus, the only real use of these constants is as an argument to setsockopt().

usocket.SOL_*

Socket option levels (an argument to setsockopt()). The exact inventory depends on a MicroPython port.

usocket.SO_*

Socket options (an argument to setsockopt()). The exact inventory depends on a MicroPython port.

Constants specific to WiPy:

usocket.IPPROTO_SEC

Special protocol value to create SSL-compatible socket.

class socket
Methods
socket.close()

Mark the socket closed and release all resources. Once that happens, all future operations on the socket object will fail. The remote end will receive EOF indication if supported by protocol.

Sockets are automatically closed when they are garbage-collected, but it is recommended to close() them explicitly as soon you finished working with them.

socket.bind(address)

Bind the socket to address. The socket must not already be bound.

socket.listen([backlog])

Enable a server to accept connections. If backlog is specified, it must be at least 0 (if it's lower, it will be set to 0); and specifies the number of unaccepted connections that the system will allow before refusing new connections. If not specified, a default reasonable value is chosen.

socket.accept()

Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair (conn, address) where conn is a new socket object usable to send and receive data on the connection, and address is the address bound to the socket on the other end of the connection.

socket.connect(address)

Connect to a remote socket at address.

socket.send(bytes)

Send data to the socket. The socket must be connected to a remote socket. Returns number of bytes sent, which may be smaller than the length of data ("short write").

socket.sendall(bytes)

Send all data to the socket. The socket must be connected to a remote socket. Unlike send(), this method will try to send all of data, by sending data chunk by chunk consecutively.

The behavior of this method on non-blocking sockets is undefined. Due to this, on MicroPython, it's recommended to use write() method instead, which has the same "no short writes" policy for blocking sockets, and will return number of bytes sent on non-blocking sockets.

socket.recv(bufsize)

Receive data from the socket. The return value is a bytes object representing the data received. The maximum amount of data to be received at once is specified by bufsize.

socket.sendto(bytes, address)

Send data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by address.

socket.recvfrom(bufsize)

Receive data from the socket. The return value is a pair (bytes, address) where bytes is a bytes object representing the data received and address is the address of the socket sending the data.

socket.setsockopt(level, optname, value)

Set the value of the given socket option. The needed symbolic constants are defined in the socket module (SO_* etc.). The value can be an integer or a bytes-like object representing a buffer.

socket.settimeout(value)

Note: Not every port supports this method, see below.

Set a timeout on blocking socket operations. The value argument can be a nonnegative floating point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations will raise an OSError exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode.

Not every MicroPython port supports this method. A more portable and generic solution is to use uselect.poll object. This allows to wait on multiple objects at the same time (and not just on sockets, but on generic stream objects which support polling). Example:

# Instead of:
s.settimeout(1.0)  # time in seconds
s.read(10)  # may timeout

# Use:
poller = uselect.poll()
poller.register(s, uselect.POLLIN)
res = poller.poll(1000)  # time in milliseconds
if not res:
    # s is still not ready for input, i.e. operation timed out

Difference to CPython

CPython raises a socket.timeout exception in case of timeout, which is an OSError subclass. MicroPython raises an OSError directly instead. If you use except OSError: to catch the exception, your code will work both in MicroPython and CPython.

socket.setblocking(flag)

Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking, else to blocking mode.

This method is a shorthand for certain settimeout() calls:

  • sock.setblocking(True) is equivalent to sock.settimeout(None)
  • sock.setblocking(False) is equivalent to sock.settimeout(0)
socket.makefile(mode='rb', buffering=0)

Return a file object associated with the socket. The exact returned type depends on the arguments given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb'). CPython's arguments: encoding, errors and newline are not supported.

Difference to CPython

As MicroPython doesn't support buffered streams, values of buffering parameter is ignored and treated as if it was 0 (unbuffered).

Difference to CPython

Closing the file object returned by makefile() WILL close the original socket as well.

socket.read([size])

Read up to size bytes from the socket. Return a bytes object. If size is not given, it reads all data available from the socket until EOF; as such the method will not return until the socket is closed. This function tries to read as much data as requested (no "short reads"). This may be not possible with non-blocking socket though, and then less data will be returned.

socket.readinto(buf[, nbytes])

Read bytes into the buf. If nbytes is specified then read at most that many bytes. Otherwise, read at most len(buf) bytes. Just as read(), this method follows "no short reads" policy.

Return value: number of bytes read and stored into buf.

socket.readline()

Read a line, ending in a newline character.

Return value: the line read.

socket.write(buf)

Write the buffer of bytes to the socket. This function will try to write all data to a socket (no "short writes"). This may be not possible with a non-blocking socket though, and returned value will be less than the length of buf.

Return value: number of bytes written.

exception usocket.error

MicroPython does NOT have this exception.

Difference to CPython

CPython used to have a socket.error exception which is now deprecated, and is an alias of OSError. In MicroPython, use OSError directly.

ussl -- SSL/TLS module

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:ssl.

This module provides access to Transport Layer Security (previously and widely known as “Secure Sockets Layer”) encryption and peer authentication facilities for network sockets, both client-side and server-side.

Functions
ussl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None)

Takes a stream sock (usually usocket.socket instance of SOCK_STREAM type), and returns an instance of ssl.SSLSocket, which wraps the underlying stream in an SSL context. Returned object has the usual stream interface methods like read(), write(), etc. In MicroPython, the returned object does not expose socket interface and methods like recv(), send(). In particular, a server-side SSL socket should be created from a normal socket returned from accept() on a non-SSL listening server socket.

Depending on the underlying module implementation in a particular MicroPython port, some or all keyword arguments above may be not supported.

警告

Some implementations of ussl module do NOT validate server certificates, which makes an SSL connection established prone to man-in-the-middle attacks.

Exceptions
ssl.SSLError

This exception does NOT exist. Instead its base class, OSError, is used.

Constants
ussl.CERT_NONE
ussl.CERT_OPTIONAL
ussl.CERT_REQUIRED

Supported values for cert_reqs parameter.

ustruct -- pack and unpack primitive data types

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:struct.

Supported size/byte order prefixes: @, <, >, !.

Supported format codes: b, B, h, H, i, I, l, L, q, Q, s, P, f, d (the latter 2 depending on the floating-point support).

Functions
ustruct.calcsize(fmt)

Return the number of bytes needed to store the given fmt.

ustruct.pack(fmt, v1, v2, ...)

Pack the values v1, v2, ... according to the format string fmt. The return value is a bytes object encoding the values.

ustruct.pack_into(fmt, buffer, offset, v1, v2, ...)

Pack the values v1, v2, ... according to the format string fmt into a buffer starting at offset. offset may be negative to count from the end of buffer.

ustruct.unpack(fmt, data)

Unpack from the data according to the format string fmt. The return value is a tuple of the unpacked values.

ustruct.unpack_from(fmt, data, offset=0)

Unpack from the data starting at offset according to the format string fmt. offset may be negative to count from the end of buffer. The return value is a tuple of the unpacked values.

utime -- time related functions

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:time.

The utime module provides functions for getting the current time and date, measuring time intervals, and for delays.

Time Epoch: Unix port uses standard for POSIX systems epoch of 1970-01-01 00:00:00 UTC. However, embedded ports use epoch of 2000-01-01 00:00:00 UTC.

Maintaining actual calendar date/time: This requires a Real Time Clock (RTC). On systems with underlying OS (including some RTOS), an RTC may be implicit. Setting and maintaining actual calendar time is responsibility of OS/RTOS and is done outside of MicroPython, it just uses OS API to query date/time. On baremetal ports however system time depends on machine.RTC() object. The current calendar time may be set using machine.RTC().datetime(tuple) function, and maintained by following means:

  • By a backup battery (which may be an additional, optional component for a particular board).
  • Using networked time protocol (requires setup by a port/user).
  • Set manually by a user on each power-up (many boards then maintain RTC time across hard resets, though some may require setting it again in such case).

If actual calendar time is not maintained with a system/MicroPython RTC, functions below which require reference to current absolute time may behave not as expected.

Functions
utime.localtime([secs])

Convert a time expressed in seconds since the Epoch (see above) into an 8-tuple which contains: (year, month, mday, hour, minute, second, weekday, yearday) If secs is not provided or None, then the current time from the RTC is used.

  • year includes the century (for example 2014).
  • month is 1-12
  • mday is 1-31
  • hour is 0-23
  • minute is 0-59
  • second is 0-59
  • weekday is 0-6 for Mon-Sun
  • yearday is 1-366
utime.mktime()

This is inverse function of localtime. It's argument is a full 8-tuple which expresses a time as per localtime. It returns an integer which is the number of seconds since Jan 1, 2000.

utime.sleep(seconds)

Sleep for the given number of seconds. Some boards may accept seconds as a floating-point number to sleep for a fractional number of seconds. Note that other boards may not accept a floating-point argument, for compatibility with them use sleep_ms() and sleep_us() functions.

utime.sleep_ms(ms)

Delay for given number of milliseconds, should be positive or 0.

utime.sleep_us(us)

Delay for given number of microseconds, should be positive or 0.

utime.ticks_ms()

Returns an increasing millisecond counter with an arbitrary reference point, that wraps around after some value.

The wrap-around value is not explicitly exposed, but we will refer to it as TICKS_MAX to simplify discussion. Period of the values is TICKS_PERIOD = TICKS_MAX + 1. TICKS_PERIOD is guaranteed to be a power of two, but otherwise may differ from port to port. The same period value is used for all of ticks_ms(), ticks_us(), ticks_cpu() functions (for simplicity). Thus, these functions will return a value in range [0 .. TICKS_MAX], inclusive, total TICKS_PERIOD values. Note that only non-negative values are used. For the most part, you should treat values returned by these functions as opaque. The only operations available for them are ticks_diff() and ticks_add() functions described below.

Note: Performing standard mathematical operations (+, -) or relational operators (<, <=, >, >=) directly on these value will lead to invalid result. Performing mathematical operations and then passing their results as arguments to ticks_diff() or ticks_add() will also lead to invalid results from the latter functions.

utime.ticks_us()

Just like ticks_ms() above, but in microseconds.

utime.ticks_cpu()

Similar to ticks_ms() and ticks_us(), but with the highest possible resolution in the system. This is usually CPU clocks, and that's why the function is named that way. But it doesn't have to be a CPU clock, some other timing source available in a system (e.g. high-resolution timer) can be used instead. The exact timing unit (resolution) of this function is not specified on utime module level, but documentation for a specific port may provide more specific information. This function is intended for very fine benchmarking or very tight real-time loops. Avoid using it in portable code.

Availability: Not every port implements this function.

utime.ticks_add(ticks, delta)

Offset ticks value by a given number, which can be either positive or negative. Given a ticks value, this function allows to calculate ticks value delta ticks before or after it, following modular-arithmetic definition of tick values (see ticks_ms() above). ticks parameter must be a direct result of call to ticks_ms(), ticks_us(), or ticks_cpu() functions (or from previous call to ticks_add()). However, delta can be an arbitrary integer number or numeric expression. ticks_add() is useful for calculating deadlines for events/tasks. (Note: you must use ticks_diff() function to work with deadlines.)

Examples:

# Find out what ticks value there was 100ms ago
print(ticks_add(time.ticks_ms(), -100))

# Calculate deadline for operation and test for it
deadline = ticks_add(time.ticks_ms(), 200)
while ticks_diff(deadline, time.ticks_ms()) > 0:
    do_a_little_of_something()

# Find out TICKS_MAX used by this port
print(ticks_add(0, -1))
utime.ticks_diff(ticks1, ticks2)

Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu() functions, as a signed value which may wrap around.

The argument order is the same as for subtraction operator, ticks_diff(ticks1, ticks2) has the same meaning as ticks1 - ticks2. However, values returned by ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will produce incorrect result. That is why ticks_diff() is needed, it implements modular (or more specifically, ring) arithmetics to produce correct result even for wrap-around values (as long as they not too distant inbetween, see below). The function returns signed value in the range [-TICKS_PERIOD/2 .. TICKS_PERIOD/2-1] (that's a typical range definition for two's-complement signed binary integers). If the result is negative, it means that ticks1 occurred earlier in time than ticks2. Otherwise, it means that ticks1 occurred after ticks2. This holds only if ticks1 and ticks2 are apart from each other for no more than TICKS_PERIOD/2-1 ticks. If that does not hold, incorrect result will be returned. Specifically, if two tick values are apart for TICKS_PERIOD/2-1 ticks, that value will be returned by the function. However, if TICKS_PERIOD/2 of real-time ticks has passed between them, the function will return -TICKS_PERIOD/2 instead, i.e. result value will wrap around to the negative range of possible values.

Informal rationale of the constraints above: Suppose you are locked in a room with no means to monitor passing of time except a standard 12-notch clock. Then if you look at dial-plate now, and don't look again for another 13 hours (e.g., if you fall for a long sleep), then once you finally look again, it may seem to you that only 1 hour has passed. To avoid this mistake, just look at the clock regularly. Your application should do the same. "Too long sleep" metaphor also maps directly to application behavior: don't let your application run any single task for too long. Run tasks in steps, and do time-keeping inbetween.

ticks_diff() is designed to accommodate various usage patterns, among them:

  • Polling with timeout. In this case, the order of events is known, and you will deal only with positive results of ticks_diff():

    # Wait for GPIO pin to be asserted, but at most 500us
    start = time.ticks_us()
    while pin.value() == 0:
        if time.ticks_diff(time.ticks_us(), start) > 500:
            raise TimeoutError
    
  • Scheduling events. In this case, ticks_diff() result may be negative if an event is overdue:

    # This code snippet is not optimized
    now = time.ticks_ms()
    scheduled_time = task.scheduled_time()
    if ticks_diff(scheduled_time, now) > 0:
        print("Too early, let's nap")
        sleep_ms(ticks_diff(scheduled_time, now))
        task.run()
    elif ticks_diff(scheduled_time, now) == 0:
        print("Right at time!")
        task.run()
    elif ticks_diff(scheduled_time, now) < 0:
        print("Oops, running late, tell task to run faster!")
        task.run(run_faster=true)
    

Note: Do not pass time() values to ticks_diff(), you should use normal mathematical operations on them. But note that time() may (and will) also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem .

utime.time()

Returns the number of seconds, as an integer, since the Epoch, assuming that underlying RTC is set and maintained as described above. If an RTC is not set, this function returns number of seconds since a port-specific reference point in time (for embedded boards without a battery-backed RTC, usually since power up or reset). If you want to develop portable MicroPython application, you should not rely on this function to provide higher than second precision. If you need higher precision, use ticks_ms() and ticks_us() functions, if you need calendar time, localtime() without an argument is a better choice.

Difference to CPython

In CPython, this function returns number of seconds since Unix epoch, 1970-01-01 00:00 UTC, as a floating-point, usually having microsecond precision. With MicroPython, only Unix port uses the same Epoch, and if floating-point precision allows, returns sub-second precision. Embedded hardware usually doesn't have floating-point precision to represent both long time ranges and subsecond precision, so they use integer value with second precision. Some embedded hardware also lacks battery-powered RTC, so returns number of seconds since last power-up or from other relative, hardware-specific point (e.g. reset).

uzlib -- zlib decompression

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:zlib.

This module allows to decompress binary data compressed with DEFLATE algorithm (commonly used in zlib library and gzip archiver). Compression is not yet implemented.

Functions
uzlib.decompress(data, wbits=0, bufsize=0)

Return decompressed data as bytes. wbits is DEFLATE dictionary window size used during compression (8-15, the dictionary size is power of 2 of that value). Additionally, if value is positive, data is assumed to be zlib stream (with zlib header). Otherwise, if it's negative, it's assumed to be raw DEFLATE stream. bufsize parameter is for compatibility with CPython and is ignored.

class uzlib.DecompIO(stream, wbits=0)

Create a stream wrapper which allows transparent decompression of compressed data in another stream. This allows to process compressed streams with data larger than available heap size. In addition to values described in decompress(), wbits may take values 24..31 (16 + 8..15), meaning that input stream has gzip header.

Difference to CPython

This class is MicroPython extension. It's included on provisional basis and may be changed considerably or removed in later versions.

_thread -- multithreading support

This module implements a subset of the corresponding CPython module, as described below. For more information, refer to the original CPython documentation: python:_thread.

This module implements multithreading support.

This module is highly experimental and its API is not yet fully settled and not yet described in this documentation.

microPython 特有类库

MicroPython的特有功能如下。

btree -- simple BTree database

The btree module implements a simple key-value database using external storage (disk files, or in general case, a random-access stream). Keys are stored sorted in the database, and besides efficient retrieval by a key value, a database also supports efficient ordered range scans (retrieval of values with the keys in a given range). On the application interface side, BTree database work as close a possible to a way standard dict type works, one notable difference is that both keys and values must be bytes objects (so, if you want to store objects of other types, you need to serialize them to bytes first).

The module is based on the well-known BerkelyDB library, version 1.xx.

Example:

import btree

# First, we need to open a stream which holds a database
# This is usually a file, but can be in-memory database
# using uio.BytesIO, a raw flash partition, etc.
# Oftentimes, you want to create a database file if it doesn't
# exist and open if it exists. Idiom below takes care of this.
# DO NOT open database with "a+b" access mode.
try:
    f = open("mydb", "r+b")
except OSError:
    f = open("mydb", "w+b")

# Now open a database itself
db = btree.open(f)

# The keys you add will be sorted internally in the database
db[b"3"] = b"three"
db[b"1"] = b"one"
db[b"2"] = b"two"

# Assume that any changes are cached in memory unless
# explicitly flushed (or database closed). Flush database
# at the end of each "transaction".
db.flush()

# Prints b'two'
print(db[b"2"])

# Iterate over sorted keys in the database, starting from b"2"
# until the end of the database, returning only values.
# Mind that arguments passed to values() method are *key* values.
# Prints:
#   b'two'
#   b'three'
for word in db.values(b"2"):
    print(word)

del db[b"2"]

# No longer true, prints False
print(b"2" in db)

# Prints:
#  b"1"
#  b"3"
for key in db:
    print(key)

db.close()

# Don't forget to close the underlying stream!
f.close()
Functions
btree.open(stream, *, flags=0, pagesize=0, cachesize=0, minkeypage=0)

Open a database from a random-access stream (like an open file). All other parameters are optional and keyword-only, and allow to tweak advanced parameters of the database operation (most users will not need them):

  • flags - Currently unused.
  • pagesize - Page size used for the nodes in BTree. Acceptable range is 512-65536. If 0, a port-specific default will be used, optimized for port's memory usage and/or performance.
  • cachesize - Suggested memory cache size in bytes. For a board with enough memory using larger values may improve performance. Cache policy is as follows: entire cache is not allocated at once; instead, accessing a new page in database will allocate a memory buffer for it, until value specified by cachesize is reached. Then, these buffers will be managed using LRU (least recently used) policy. More buffers may still be allocated if needed (e.g., if a database contains big keys and/or values). Allocated cache buffers aren't reclaimed.
  • minkeypage - Minimum number of keys to store per page. Default value of 0 equivalent to 2.

Returns a BTree object, which implements a dictionary protocol (set of methods), and some additional methods described below.

Methods
btree.close()

Close the database. It's mandatory to close the database at the end of processing, as some unwritten data may be still in the cache. Note that this does not close underlying stream with which the database was opened, it should be closed separately (which is also mandatory to make sure that data flushed from buffer to the underlying storage).

btree.flush()

Flush any data in cache to the underlying stream.

btree.__getitem__(key)
btree.get(key, default=None)
btree.__setitem__(key, val)
btree.__detitem__(key)
btree.__contains__(key)

Standard dictionary methods.

btree.__iter__()

A BTree object can be iterated over directly (similar to a dictionary) to get access to all keys in order.

btree.keys([start_key[, end_key[, flags]]])
btree.values([start_key[, end_key[, flags]]])
btree.items([start_key[, end_key[, flags]]])

These methods are similar to standard dictionary methods, but also can take optional parameters to iterate over a key sub-range, instead of the entire database. Note that for all 3 methods, start_key and end_key arguments represent key values. For example, values() method will iterate over values corresponding to they key range given. None values for start_key means "from the first key", no end_key or its value of None means "until the end of database". By default, range is inclusive of start_key and exclusive of end_key, you can include end_key in iteration by passing flags of btree.INCL. You can iterate in descending key direction by passing flags of btree.DESC. The flags values can be ORed together.

Constants
btree.INCL

A flag for keys(), values(), items() methods to specify that scanning should be inclusive of the end key.

btree.DESC

A flag for keys(), values(), items() methods to specify that scanning should be in descending direction of keys.

framebuf --- Frame buffer manipulation

This module provides a general frame buffer which can be used to create bitmap images, which can then be sent to a display.

class FrameBuffer

The FrameBuffer class provides a pixel buffer which can be drawn upon with pixels, lines, rectangles, text and even other FrameBuffer's. It is useful when generating output for displays.

For example:

import framebuf

# FrameBuffer needs 2 bytes for every RGB565 pixel
fbuf = FrameBuffer(bytearray(10 * 100 * 2), 10, 100, framebuf.RGB565)

fbuf.fill(0)
fbuf.text('MicroPython!', 0, 0, 0xffff)
fbuf.hline(0, 10, 96, 0xffff)
Constructors
class framebuf.FrameBuffer(buffer, width, height, format, stride=width)

Construct a FrameBuffer object. The parameters are:

  • buffer is an object with a buffer protocol which must be large enough to contain every pixel defined by the width, height and format of the FrameBuffer.
  • width is the width of the FrameBuffer in pixels
  • height is the height of the FrameBuffer in pixels
  • format specifies the type of pixel used in the FrameBuffer; permissible values are listed under Constants below. These set the number of bits used to encode a color value and the layout of these bits in buffer. Where a color value c is passed to a method, c is a small integer with an encoding that is dependent on the format of the FrameBuffer.
  • stride is the number of pixels between each horizontal line of pixels in the FrameBuffer. This defaults to width but may need adjustments when implementing a FrameBuffer within another larger FrameBuffer or screen. The buffer size must accommodate an increased step size.

One must specify valid buffer, width, height, format and optionally stride. Invalid buffer size or dimensions may lead to unexpected errors.

Drawing primitive shapes

The following methods draw shapes onto the FrameBuffer.

FrameBuffer.fill(c)

Fill the entire FrameBuffer with the specified color.

FrameBuffer.pixel(x, y[, c])

If c is not given, get the color value of the specified pixel. If c is given, set the specified pixel to the given color.

FrameBuffer.hline(x, y, w, c)
FrameBuffer.vline(x, y, h, c)
FrameBuffer.line(x1, y1, x2, y2, c)

Draw a line from a set of coordinates using the given color and a thickness of 1 pixel. The line method draws the line up to a second set of coordinates whereas the hline and vline methods draw horizontal and vertical lines respectively up to a given length.

FrameBuffer.rect(x, y, w, h, c)
FrameBuffer.fill_rect(x, y, w, h, c)

Draw a rectangle at the given location, size and color. The rect method draws only a 1 pixel outline whereas the fill_rect method draws both the outline and interior.

Drawing text
FrameBuffer.text(s, x, y[, c])

Write text to the FrameBuffer using the the coordinates as the upper-left corner of the text. The color of the text can be defined by the optional argument but is otherwise a default value of 1. All characters have dimensions of 8x8 pixels and there is currently no way to change the font.

Other methods
FrameBuffer.scroll(xstep, ystep)

Shift the contents of the FrameBuffer by the given vector. This may leave a footprint of the previous colors in the FrameBuffer.

FrameBuffer.blit(fbuf, x, y[, key])

Draw another FrameBuffer on top of the current one at the given coordinates. If key is specified then it should be a color integer and the corresponding color will be considered transparent: all pixels with that color value will not be drawn.

This method works between FrameBuffer instances utilising different formats, but the resulting colors may be unexpected due to the mismatch in color formats.

Constants
framebuf.MONO_VLSB

Monochrome (1-bit) color format This defines a mapping where the bits in a byte are vertically mapped with bit 0 being nearest the top of the screen. Consequently each byte occupies 8 vertical pixels. Subsequent bytes appear at successive horizontal locations until the rightmost edge is reached. Further bytes are rendered at locations starting at the leftmost edge, 8 pixels lower.

framebuf.MONO_HLSB

Monochrome (1-bit) color format This defines a mapping where the bits in a byte are horizontally mapped. Each byte occupies 8 horizontal pixels with bit 0 being the leftmost. Subsequent bytes appear at successive horizontal locations until the rightmost edge is reached. Further bytes are rendered on the next row, one pixel lower.

framebuf.MONO_HMSB

Monochrome (1-bit) color format This defines a mapping where the bits in a byte are horizontally mapped. Each byte occupies 8 horizontal pixels with bit 7 being the leftmost. Subsequent bytes appear at successive horizontal locations until the rightmost edge is reached. Further bytes are rendered on the next row, one pixel lower.

framebuf.RGB565

Red Green Blue (16-bit, 5+6+5) color format

framebuf.GS2_HMSB

Grayscale (2-bit) color format

framebuf.GS4_HMSB

Grayscale (4-bit) color format

framebuf.GS8

Grayscale (8-bit) color format

machine --- functions related to the hardware

The machine module contains specific functions related to the hardware on a particular board. Most functions in this module allow to achieve direct and unrestricted access to and control of hardware blocks on a system (like CPU, timers, buses, etc.). Used incorrectly, this can lead to malfunction, lockups, crashes of your board, and in extreme cases, hardware damage.

A note of callbacks used by functions and class methods of machine module: all these callbacks should be considered as executing in an interrupt context. This is true for both physical devices with IDs >= 0 and "virtual" devices with negative IDs like -1 (these "virtual" devices are still thin shims on top of real hardware and real hardware interrupts). See Writing interrupt handlers.

Miscellaneous functions
machine.unique_id()

Returns a byte string with a unique identifier of a board/SoC. It will vary from a board/SoC instance to another, if underlying hardware allows. Length varies by hardware (so use substring of a full value if you expect a short ID). In some MicroPython ports, ID corresponds to the network MAC address.

machine.time_pulse_us(pin, pulse_level, timeout_us=1000000)

Time a pulse on the given pin, and return the duration of the pulse in microseconds. The pulse_level argument should be 0 to time a low pulse or 1 to time a high pulse.

If the current input value of the pin is different to pulse_level, the function first (*) waits until the pin input becomes equal to pulse_level, then (**) times the duration that the pin is equal to pulse_level. If the pin is already equal to pulse_level then timing starts straight away.

The function will return -2 if there was timeout waiting for condition marked (*) above, and -1 if there was timeout during the main measurement, marked (**) above. The timeout is the same for both cases and given by timeout_us (which is in microseconds).

machine.rng()

Return a 24-bit software generated random number.

Availability: WiPy.

Constants
machine.IDLE
machine.SLEEP
machine.DEEPSLEEP

IRQ wake values.

machine.PWRON_RESET
machine.HARD_RESET
machine.WDT_RESET
machine.DEEPSLEEP_RESET
machine.SOFT_RESET

Reset causes.

machine.WLAN_WAKE
machine.PIN_WAKE
machine.RTC_WAKE

Wake-up reasons.

Classes
class Pin -- control I/O pins

A pin object is used to control I/O pins (also known as GPIO - general-purpose input/output). Pin objects are commonly associated with a physical pin that can drive an output voltage and read input voltages. The pin class has methods to set the mode of the pin (IN, OUT, etc) and methods to get and set the digital logic level. For analog control of a pin, see the ADC class.

A pin object is constructed by using an identifier which unambiguously specifies a certain I/O pin. The allowed forms of the identifier and the physical pin that the identifier maps to are port-specific. Possibilities for the identifier are an integer, a string or a tuple with port and pin number.

Usage Model:

from machine import Pin

# create an output pin on pin #0
p0 = Pin(0, Pin.OUT)

# set the value low then high
p0.value(0)
p0.value(1)

# create an input pin on pin #2, with a pull up resistor
p2 = Pin(2, Pin.IN, Pin.PULL_UP)

# read and print the pin value
print(p2.value())

# reconfigure pin #0 in input mode
p0.mode(p0.IN)

# configure an irq callback
p0.irq(lambda p:print(p))
Constructors
class machine.Pin(id, mode=-1, pull=-1, *, value, drive, alt)

Access the pin peripheral (GPIO pin) associated with the given id. If additional arguments are given in the constructor then they are used to initialise the pin. Any settings that are not specified will remain in their previous state.

The arguments are:

  • id is mandatory and can be an arbitrary object. Among possible value types are: int (an internal Pin identifier), str (a Pin name), and tuple (pair of [port, pin]).
  • mode specifies the pin mode, which can be one of:
    • Pin.IN - Pin is configured for input. If viewed as an output the pin is in high-impedance state.
    • Pin.OUT - Pin is configured for (normal) output.
    • Pin.OPEN_DRAIN - Pin is configured for open-drain output. Open-drain output works in the following way: if the output value is set to 0 the pin is active at a low level; if the output value is 1 the pin is in a high-impedance state. Not all ports implement this mode, or some might only on certain pins.
    • Pin.ALT - Pin is configured to perform an alternative function, which is port specific. For a pin configured in such a way any other Pin methods (except Pin.init()) are not applicable (calling them will lead to undefined, or a hardware-specific, result). Not all ports implement this mode.
    • Pin.ALT_OPEN_DRAIN - The Same as Pin.ALT, but the pin is configured as open-drain. Not all ports implement this mode.
  • pull specifies if the pin has a (weak) pull resistor attached, and can be one of:
    • None - No pull up or down resistor.
    • Pin.PULL_UP - Pull up resistor enabled.
    • Pin.PULL_DOWN - Pull down resistor enabled.
  • value is valid only for Pin.OUT and Pin.OPEN_DRAIN modes and specifies initial output pin value if given, otherwise the state of the pin peripheral remains unchanged.
  • drive specifies the output power of the pin and can be one of: Pin.LOW_POWER, Pin.MED_POWER or Pin.HIGH_POWER. The actual current driving capabilities are port dependent. Not all ports implement this argument.
  • alt specifies an alternate function for the pin and the values it can take are port dependent. This argument is valid only for Pin.ALT and Pin.ALT_OPEN_DRAIN modes. It may be used when a pin supports more than one alternate function. If only one pin alternate function is supported the this argument is not required. Not all ports implement this argument.

As specified above, the Pin class allows to set an alternate function for a particular pin, but it does not specify any further operations on such a pin. Pins configured in alternate-function mode are usually not used as GPIO but are instead driven by other hardware peripherals. The only operation supported on such a pin is re-initialising, by calling the constructor or Pin.init() method. If a pin that is configured in alternate-function mode is re-initialised with Pin.IN, Pin.OUT, or Pin.OPEN_DRAIN, the alternate function will be removed from the pin.

Methods
Pin.init(mode=-1, pull=-1, *, value, drive, alt)

Re-initialise the pin using the given parameters. Only those arguments that are specified will be set. The rest of the pin peripheral state will remain unchanged. See the constructor documentation for details of the arguments.

Returns None.

Pin.value([x])

This method allows to set and get the value of the pin, depending on whether the argument x is supplied or not.

If the argument is omitted then this method gets the digital logic level of the pin, returning 0 or 1 corresponding to low and high voltage signals respectively. The behaviour of this method depends on the mode of the pin:

  • Pin.IN - The method returns the actual input value currently present on the pin.
  • Pin.OUT - The behaviour and return value of the method is undefined.
  • Pin.OPEN_DRAIN - If the pin is in state '0' then the behaviour and return value of the method is undefined. Otherwise, if the pin is in state '1', the method returns the actual input value currently present on the pin.

If the argument is supplied then this method sets the digital logic level of the pin. The argument x can be anything that converts to a boolean. If it converts to True, the pin is set to state '1', otherwise it is set to state '0'. The behaviour of this method depends on the mode of the pin:

  • Pin.IN - The value is stored in the output buffer for the pin. The pin state does not change, it remains in the high-impedance state. The stored value will become active on the pin as soon as it is changed to Pin.OUT or Pin.OPEN_DRAIN mode.
  • Pin.OUT - The output buffer is set to the given value immediately.
  • Pin.OPEN_DRAIN - If the value is '0' the pin is set to a low voltage state. Otherwise the pin is set to high-impedance state.

When setting the value this method returns None.

Pin.__call__([x])

Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin. It is equivalent to Pin.value([x]). See Pin.value() for more details.

Pin.on()

Set pin to "1" output level.

Pin.off()

Set pin to "0" output level.

Pin.mode([mode])

Get or set the pin mode. See the constructor documentation for details of the mode argument.

Pin.pull([pull])

Get or set the pin pull state. See the constructor documentation for details of the pull argument.

Pin.drive([drive])

Get or set the pin drive strength. See the constructor documentation for details of the drive argument.

Not all ports implement this method.

Availability: WiPy.

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

Configure an interrupt handler to be called when the trigger source of the pin is active. If the pin mode is Pin.IN then the trigger source is the external value on the pin. If the pin mode is Pin.OUT then the trigger source is the output buffer of the pin. Otherwise, if the pin mode is Pin.OPEN_DRAIN then the trigger source is the output buffer for state '0' and the external pin value for state '1'.

The arguments are:

  • handler is an optional function to be called when the interrupt triggers.

  • trigger configures the event which can generate an interrupt. Possible values are:

    • Pin.IRQ_FALLING interrupt on falling edge.
    • Pin.IRQ_RISING interrupt on rising edge.
    • Pin.IRQ_LOW_LEVEL interrupt on low level.
    • Pin.IRQ_HIGH_LEVEL interrupt on high level.

    These values can be OR'ed together to trigger on multiple events.

  • priority sets the priority level of the interrupt. The values it can take are port-specific, but higher values always represent higher priorities.

  • wake selects the power mode in which this interrupt can wake up the system. It can be machine.IDLE, machine.SLEEP or machine.DEEPSLEEP. These values can also be OR'ed together to make a pin generate interrupts in more than one power mode.

This method returns a callback object.

Constants

The following constants are used to configure the pin objects. Note that not all constants are available on all ports.

Pin.IN
Pin.OUT
Pin.OPEN_DRAIN
Pin.ALT
Pin.ALT_OPEN_DRAIN

Selects the pin mode.

Pin.PULL_UP
Pin.PULL_DOWN

Selects whether there is a pull up/down resistor. Use the value None for no pull.

Pin.LOW_POWER
Pin.MED_POWER
Pin.HIGH_POWER

Selects the pin drive strength.

Pin.IRQ_FALLING
Pin.IRQ_RISING
Pin.IRQ_LOW_LEVEL
Pin.IRQ_HIGH_LEVEL

Selects the IRQ trigger type.

class Signal -- control and sense external I/O devices

The Signal class is a simple extension of the Pin class. Unlike Pin, which can be only in "absolute" 0 and 1 states, a Signal can be in "asserted" (on) or "deasserted" (off) states, while being inverted (active-low) or not. In other words, it adds logical inversion support to Pin functionality. While this may seem a simple addition, it is exactly what is needed to support wide array of simple digital devices in a way portable across different boards, which is one of the major MicroPython goals. Regardless of whether different users have an active-high or active-low LED, a normally open or normally closed relay - you can develop a single, nicely looking application which works with each of them, and capture hardware configuration differences in few lines in the config file of your app.

Example:

from machine import Pin, Signal

# Suppose you have an active-high LED on pin 0
led1_pin = Pin(0, Pin.OUT)
# ... and active-low LED on pin 1
led2_pin = Pin(1, Pin.OUT)

# Now to light up both of them using Pin class, you'll need to set
# them to different values
led1_pin.value(1)
led2_pin.value(0)

# Signal class allows to abstract away active-high/active-low
# difference
led1 = Signal(led1_pin, invert=False)
led2 = Signal(led2_pin, invert=True)

# Now lighting up them looks the same
led1.value(1)
led2.value(1)

# Even better:
led1.on()
led2.on()

Following is the guide when Signal vs Pin should be used:

  • Use Signal: If you want to control a simple on/off (including software PWM!) devices like LEDs, multi-segment indicators, relays, buzzers, or read simple binary sensors, like normally open or normally closed buttons, pulled high or low, Reed switches, moisture/flame detectors, etc. etc. Summing up, if you have a real physical device/sensor requiring GPIO access, you likely should use a Signal.
  • Use Pin: If you implement a higher-level protocol or bus to communicate with more complex devices.

The split between Pin and Signal come from the usecases above and the architecture of MicroPython: Pin offers the lowest overhead, which may be important when bit-banging protocols. But Signal adds additional flexibility on top of Pin, at the cost of minor overhead (much smaller than if you implemented active-high vs active-low device differences in Python manually!). Also, Pin is a low-level object which needs to be implemented for each support board, while Signal is a high-level object which comes for free once Pin is implemented.

If in doubt, give the Signal a try! Once again, it is offered to save developers from the need to handle unexciting differences like active-low vs active-high signals, and allow other users to share and enjoy your application, instead of being frustrated by the fact that it doesn't work for them simply because their LEDs or relays are wired in a slightly different way.

Constructors
class machine.Signal(pin_obj, invert=False)
class machine.Signal(pin_arguments..., *, invert=False)

Create a Signal object. There're two ways to create it:

  • By wrapping existing Pin object - universal method which works for any board.
  • By passing required Pin parameters directly to Signal constructor, skipping the need to create intermediate Pin object. Available on many, but not all boards.

The arguments are:

  • pin_obj is existing Pin object.
  • pin_arguments are the same arguments as can be passed to Pin constructor.
  • invert - if True, the signal will be inverted (active low).
Methods
Signal.value([x])

This method allows to set and get the value of the signal, depending on whether the argument x is supplied or not.

If the argument is omitted then this method gets the signal level, 1 meaning signal is asserted (active) and 0 - signal inactive.

If the argument is supplied then this method sets the signal level. The argument x can be anything that converts to a boolean. If it converts to True, the signal is active, otherwise it is inactive.

Correspondence between signal being active and actual logic level on the underlying pin depends on whether signal is inverted (active-low) or not. For non-inverted signal, active status corresponds to logical 1, inactive - to logical 0. For inverted/active-low signal, active status corresponds to logical 0, while inactive - to logical 1.

Signal.on()

Activate signal.

Signal.off()

Deactivate signal.

class ADC -- analog to digital conversion

Usage:

import machine

adc = machine.ADC()             # create an ADC object
apin = adc.channel(pin='GP3')   # create an analog pin on GP3
val = apin()                    # read an analog value
Constructors
class machine.ADC(id=0, *, bits=12)

Create an ADC object associated with the given pin. This allows you to then read analog values on that pin. For more info check the pinout and alternate functions table.

警告

ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it can withstand). When GP2, GP3, GP4 or GP5 are remapped to the ADC block, 1.8 V is the maximum. If these pins are used in digital mode, then the maximum allowed input is 3.6V.

Methods
ADC.channel(id, *, pin)

Create an analog pin. If only channel ID is given, the correct pin will be selected. Alternatively, only the pin can be passed and the correct channel will be selected. Examples:

# all of these are equivalent and enable ADC channel 1 on GP3
apin = adc.channel(1)
apin = adc.channel(pin='GP3')
apin = adc.channel(id=1, pin='GP3')
ADC.init()

Enable the ADC block.

ADC.deinit()

Disable the ADC block.

class ADCChannel --- read analog values from internal or external sources

ADC channels can be connected to internal points of the MCU or to GPIO pins. ADC channels are created using the ADC.channel method.

machine.adcchannel()

Fast method to read the channel value.

adcchannel.value()

Read the channel value.

adcchannel.init()

Re-init (and effectively enable) the ADC channel.

adcchannel.deinit()

Disable the ADC channel.

class UART -- duplex serial communication bus

UART implements the standard UART/USART duplex serial communications protocol. At the physical level it consists of 2 lines: RX and TX. The unit of communication is a character (not to be confused with a string character) which can be 8 or 9 bits wide.

UART objects can be created and initialised using:

from machine import UART

uart = UART(1, 9600)                         # init with given baudrate
uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters

Supported parameters differ on a board:

Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With parity=None, only 8 and 9 bits are supported. With parity enabled, only 7 and 8 bits are supported.

WiPy/CC3200: Bits can be 5, 6, 7, 8. Stop can be 1 or 2.

A UART object acts like a stream object and reading and writing is done using the standard stream methods:

uart.read(10)       # read 10 characters, returns a bytes object
uart.read()         # read all available characters
uart.readline()     # read a line
uart.readinto(buf)  # read and store into the given buffer
uart.write('abc')   # write the 3 characters
Constructors
class machine.UART(id, ...)

Construct a UART object of the given id.

Methods
UART.init(baudrate=9600, bits=8, parity=None, stop=1, *, ...)

Initialise the UART bus with the given parameters:

  • baudrate is the clock rate.
  • bits is the number of bits per character, 7, 8 or 9.
  • parity is the parity, None, 0 (even) or 1 (odd).
  • stop is the number of stop bits, 1 or 2.

Additional keyword-only parameters that may be supported by a port are:

  • tx specifies the TX pin to use.
  • rx specifies the RX pin to use.
  • txbuf specifies the length in characters of the TX buffer.
  • rxbuf specifies the length in characters of the RX buffer.

On the WiPy only the following keyword-only parameter is supported:

  • pins is a 4 or 2 item list indicating the TX, RX, RTS and CTS pins (in that order). Any of the pins can be None if one wants the UART to operate with limited functionality. If the RTS pin is given the the RX pin must be given as well. The same applies to CTS. When no pins are given, then the default set of TX and RX pins is taken, and hardware flow control will be disabled. If pins is None, no pin assignment will be made.
UART.deinit()

Turn off the UART bus.

UART.any()

Returns an integer counting the number of characters that can be read without blocking. It will return 0 if there are no characters available and a positive number if there are characters. The method may return 1 even if there is more than one character available for reading.

For more sophisticated querying of available characters use select.poll:

poll = select.poll()
poll.register(uart, select.POLLIN)
poll.poll(timeout)
UART.read([nbytes])

Read characters. If nbytes is specified then read at most that many bytes, otherwise read as much data as possible.

Return value: a bytes object containing the bytes read in. Returns None on timeout.

UART.readinto(buf[, nbytes])

Read bytes into the buf. If nbytes is specified then read at most that many bytes. Otherwise, read at most len(buf) bytes.

Return value: number of bytes read and stored into buf or None on timeout.

UART.readline()

Read a line, ending in a newline character.

Return value: the line read or None on timeout.

UART.write(buf)

Write the buffer of bytes to the bus.

Return value: number of bytes written or None on timeout.

UART.sendbreak()

Send a break condition on the bus. This drives the bus low for a duration longer than required for a normal transmission of a character.

UART.irq(trigger, priority=1, handler=None, wake=machine.IDLE)

Create a callback to be triggered when data is received on the UART.

  • trigger can only be UART.RX_ANY
  • priority level of the interrupt. Can take values in the range 1-7. Higher values represent higher priorities.
  • handler an optional function to be called when new characters arrive.
  • wake can only be machine.IDLE.

注解

The handler will be called whenever any of the following two conditions are met:

  • 8 new characters have been received.
  • At least 1 new character is waiting in the Rx buffer and the Rx line has been silent for the duration of 1 complete frame.

This means that when the handler function is called there will be between 1 to 8 characters waiting.

Returns an irq object.

Availability: WiPy.

Constants
UART.RX_ANY

IRQ trigger sources

Availability: WiPy.

class SPI -- a Serial Peripheral Interface bus protocol (master side)

SPI is a synchronous serial protocol that is driven by a master. At the physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices can share the same bus. Each device should have a separate, 4th signal, SS (Slave Select), to select a particular device on a bus with which communication takes place. Management of an SS signal should happen in user code (via machine.Pin class).

Constructors
class machine.SPI(id, ...)

Construct an SPI object on the given bus, id. Values of id depend on a particular port and its hardware. Values 0, 1, etc. are commonly used to select hardware SPI block #0, #1, etc. Value -1 can be used for bitbanging (software) implementation of SPI (if supported by a port).

With no additional parameters, the SPI object is created but not initialised (it has the settings from the last initialisation of the bus, if any). If extra arguments are given, the bus is initialised. See init for parameters of initialisation.

Methods
SPI.init(baudrate=1000000, *, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, sck=None, mosi=None, miso=None, pins=(SCK, MOSI, MISO))

Initialise the SPI bus with the given parameters:

  • baudrate is the SCK clock rate.
  • polarity can be 0 or 1, and is the level the idle clock line sits at.
  • phase can be 0 or 1 to sample data on the first or second clock edge respectively.
  • bits is the width in bits of each transfer. Only 8 is guaranteed to be supported by all hardware.
  • firstbit can be SPI.MSB or SPI.LSB.
  • sck, mosi, miso are pins (machine.Pin) objects to use for bus signals. For most hardware SPI blocks (as selected by id parameter to the constructor), pins are fixed and cannot be changed. In some cases, hardware blocks allow 2-3 alternative pin sets for a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver (id = -1).
  • pins - WiPy port doesn't sck, mosi, miso arguments, and instead allows to specify them as a tuple of pins parameter.
SPI.deinit()

Turn off the SPI bus.

SPI.read(nbytes, write=0x00)

Read a number of bytes specified by nbytes while continuously writing the single byte given by write. Returns a bytes object with the data that was read.

SPI.readinto(buf, write=0x00)

Read into the buffer specified by buf while continuously writing the single byte given by write. Returns None.

Note: on WiPy this function returns the number of bytes read.

SPI.write(buf)

Write the bytes contained in buf. Returns None.

Note: on WiPy this function returns the number of bytes written.

SPI.write_readinto(write_buf, read_buf)

Write the bytes from write_buf while reading into read_buf. The buffers can be the same or different, but both buffers must have the same length. Returns None.

Note: on WiPy this function returns the number of bytes written.

Constants
SPI.MASTER

for initialising the SPI bus to master; this is only used for the WiPy

SPI.MSB

set the first bit to be the most significant bit

SPI.LSB

set the first bit to be the least significant bit

class I2C -- a two-wire serial protocol

I2C is a two-wire protocol for communicating between devices. At the physical level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.

I2C objects are created attached to a specific bus. They can be initialised when created, or initialised later on.

Printing the I2C object gives you information about its configuration.

Example usage:

from machine import I2C

i2c = I2C(freq=400000)          # create I2C peripheral at frequency of 400kHz
                                # depending on the port, extra parameters may be required
                                # to select the peripheral and/or pins to use

i2c.scan()                      # scan for slaves, returning a list of 7-bit addresses

i2c.writeto(42, b'123')         # write 3 bytes to slave with 7-bit address 42
i2c.readfrom(42, 4)             # read 4 bytes from slave with 7-bit address 42

i2c.readfrom_mem(42, 8, 3)      # read 3 bytes from memory of slave 42,
                                #   starting at memory-address 8 in the slave
i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of slave 42
                                #   starting at address 2 in the slave
Constructors
class machine.I2C(id=-1, *, scl, sda, freq=400000)

Construct and return a new I2C object using the following parameters:

  • id identifies a particular I2C peripheral. The default value of -1 selects a software implementation of I2C which can work (in most cases) with arbitrary pins for SCL and SDA. If id is -1 then scl and sda must be specified. Other allowed values for id depend on the particular port/board, and specifying scl and sda may or may not be required or allowed in this case.
  • scl should be a pin object specifying the pin to use for SCL.
  • sda should be a pin object specifying the pin to use for SDA.
  • freq should be an integer which sets the maximum frequency for SCL.
General Methods
I2C.init(scl, sda, *, freq=400000)

Initialise the I2C bus with the given arguments:

  • scl is a pin object for the SCL line
  • sda is a pin object for the SDA line
  • freq is the SCL clock rate
I2C.deinit()

Turn off the I2C bus.

Availability: WiPy.

I2C.scan()

Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond. A device responds if it pulls the SDA line low after its address (including a write bit) is sent on the bus.

Primitive I2C operations

The following methods implement the primitive I2C master bus operations and can be combined to make any I2C transaction. They are provided if you need more control over the bus, otherwise the standard methods (see below) can be used.

These methods are available on software I2C only.

I2C.start()

Generate a START condition on the bus (SDA transitions to low while SCL is high).

I2C.stop()

Generate a STOP condition on the bus (SDA transitions to high while SCL is high).

I2C.readinto(buf, nack=True)

Reads bytes from the bus and stores them into buf. The number of bytes read is the length of buf. An ACK will be sent on the bus after receiving all but the last byte. After the last byte is received, if nack is true then a NACK will be sent, otherwise an ACK will be sent (and in this case the slave assumes more bytes are going to be read in a later call).

I2C.write(buf)

Write the bytes from buf to the bus. Checks that an ACK is received after each byte and stops transmitting the remaining bytes if a NACK is received. The function returns the number of ACKs that were received.

Standard bus operations

The following methods implement the standard I2C master read and write operations that target a given slave device.

I2C.readfrom(addr, nbytes, stop=True)

Read nbytes from the slave specified by addr. If stop is true then a STOP condition is generated at the end of the transfer. Returns a bytes object with the data read.

I2C.readfrom_into(addr, buf, stop=True)

Read into buf from the slave specified by addr. The number of bytes read will be the length of buf. If stop is true then a STOP condition is generated at the end of the transfer.

The method returns None.

I2C.writeto(addr, buf, stop=True)

Write the bytes from buf to the slave specified by addr. If a NACK is received following the write of a byte from buf then the remaining bytes are not sent. If stop is true then a STOP condition is generated at the end of the transfer, even if a NACK is received. The function returns the number of ACKs that were received.

Memory operations

Some I2C devices act as a memory device (or set of registers) that can be read from and written to. In this case there are two addresses associated with an I2C transaction: the slave address and the memory address. The following methods are convenience functions to communicate with such devices.

I2C.readfrom_mem(addr, memaddr, nbytes, *, addrsize=8)

Read nbytes from the slave specified by addr starting from the memory address specified by memaddr. The argument addrsize specifies the address size in bits. Returns a bytes object with the data read.

I2C.readfrom_mem_into(addr, memaddr, buf, *, addrsize=8)

Read into buf from the slave specified by addr starting from the memory address specified by memaddr. The number of bytes read is the length of buf. The argument addrsize specifies the address size in bits (on ESP8266 this argument is not recognised and the address size is always 8 bits).

The method returns None.

I2C.writeto_mem(addr, memaddr, buf, *, addrsize=8)

Write buf to the slave specified by addr starting from the memory address specified by memaddr. The argument addrsize specifies the address size in bits (on ESP8266 this argument is not recognised and the address size is always 8 bits).

The method returns None.

class RTC -- real time clock

The RTC is and independent clock that keeps track of the date and time.

Example usage:

rtc = machine.RTC()
rtc.init((2014, 5, 1, 4, 13, 0, 0, 0))
print(rtc.now())
Constructors
class machine.RTC(id=0, ...)

Create an RTC object. See init for parameters of initialization.

Methods
RTC.init(datetime)

Initialise the RTC. Datetime is a tuple of the form:

(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
RTC.now()

Get get the current datetime tuple.

RTC.deinit()

Resets the RTC to the time of January 1, 2015 and starts running it again.

RTC.alarm(id, time, *, repeat=False)

Set the RTC alarm. Time might be either a millisecond value to program the alarm to current time + time_in_ms in the future, or a datetimetuple. If the time passed is in milliseconds, repeat can be set to True to make the alarm periodic.

RTC.alarm_left(alarm_id=0)

Get the number of milliseconds left before the alarm expires.

RTC.cancel(alarm_id=0)

Cancel a running alarm.

RTC.irq(*, trigger, handler=None, wake=machine.IDLE)

Create an irq object triggered by a real time clock alarm.

  • trigger must be RTC.ALARM0
  • handler is the function to be called when the callback is triggered.
  • wake specifies the sleep mode from where this interrupt can wake up the system.
Constants
RTC.ALARM0

irq trigger source

class Timer -- control hardware timers

Hardware timers deal with timing of periods and events. Timers are perhaps the most flexible and heterogeneous kind of hardware in MCUs and SoCs, differently greatly from a model to a model. MicroPython's Timer class defines a baseline operation of executing a callback with a given period (or once after some delay), and allow specific boards to define more non-standard behavior (which thus won't be portable to other boards).

See discussion of important constraints on Timer callbacks.

注解

Memory can't be allocated inside irq handlers (an interrupt) and so exceptions raised within a handler don't give much information. See micropython.alloc_emergency_exception_buf() for how to get around this limitation.

If you are using a WiPy board please refer to machine.TimerWiPy instead of this class.

Constructors
class machine.Timer(id, ...)

Construct a new timer object of the given id. Id of -1 constructs a virtual timer (if supported by a board).

Methods
Timer.init(*, mode=Timer.PERIODIC, period=-1, callback=None)

Initialise the timer. Example:

tim.init(period=100)                         # periodic with 100ms period
tim.init(mode=Timer.ONE_SHOT, period=1000)   # one shot firing after 1000ms

Keyword arguments:

  • mode can be one of:
    • Timer.ONE_SHOT - The timer runs once until the configured period of the channel expires.
    • Timer.PERIODIC - The timer runs periodically at the configured frequency of the channel.
Timer.deinit()

Deinitialises the timer. Stops the timer, and disables the timer peripheral.

Constants
Timer.ONE_SHOT
Timer.PERIODIC

Timer operating mode.

class WDT -- watchdog timer

The WDT is used to restart the system when the application crashes and ends up into a non recoverable state. Once started it cannot be stopped or reconfigured in any way. After enabling, the application must "feed" the watchdog periodically to prevent it from expiring and resetting the system.

Example usage:

from machine import WDT
wdt = WDT(timeout=2000)  # enable it with a timeout of 2s
wdt.feed()

Availability of this class: pyboard, WiPy.

Constructors
class machine.WDT(id=0, timeout=5000)

Create a WDT object and start it. The timeout must be given in seconds and the minimum value that is accepted is 1 second. Once it is running the timeout cannot be changed and the WDT cannot be stopped either.

Methods
wdt.feed()

Feed the WDT to prevent it from resetting the system. The application should place this call in a sensible place ensuring that the WDT is only fed after verifying that everything is functioning correctly.

class SD -- secure digital memory card

警告

This is a non-standard class and is only available on the cc3200 port.

The SD card class allows to configure and enable the memory card module of the WiPy and automatically mount it as /sd as part of the file system. There are several pin combinations that can be used to wire the SD card socket to the WiPy and the pins used can be specified in the constructor. Please check the pinout and alternate functions table. for more info regarding the pins which can be remapped to be used with a SD card.

Example usage:

from machine import SD
import os
# clk cmd and dat0 pins must be passed along with
# their respective alternate functions
sd = machine.SD(pins=('GP10', 'GP11', 'GP15'))
os.mount(sd, '/sd')
# do normal file operations
Constructors
class machine.SD(id, ...)

Create a SD card object. See init() for parameters if initialization.

Methods
SD.init(id=0, pins=('GP10', 'GP11', 'GP15'))

Enable the SD card. In order to initialize the card, give it a 3-tuple: (clk_pin, cmd_pin, dat0_pin).

SD.deinit()

Disable the SD card.

micropython -- access and control MicroPython internals

Functions
micropython.const(expr)

Used to declare that the expression is a constant so that the compile can optimise it. The use of this function should be as follows:

from micropython import const

CONST_X = const(123)
CONST_Y = const(2 * CONST_X + 1)

Constants declared this way are still accessible as global variables from outside the module they are declared in. On the other hand, if a constant begins with an underscore then it is hidden, it is not available as a global variable, and does not take up any memory during execution.

This const function is recognised directly by the MicroPython parser and is provided as part of the micropython module mainly so that scripts can be written which run under both CPython and MicroPython, by following the above pattern.

micropython.opt_level([level])

If level is given then this function sets the optimisation level for subsequent compilation of scripts, and returns None. Otherwise it returns the current optimisation level.

The optimisation level controls the following compilation features:

  • Assertions: at level 0 assertion statements are enabled and compiled into the bytecode; at levels 1 and higher assertions are not compiled.
  • Built-in __debug__ variable: at level 0 this variable expands to True; at levels 1 and higher it expands to False.
  • Source-code line numbers: at levels 0, 1 and 2 source-code line number are stored along with the bytecode so that exceptions can report the line number they occurred at; at levels 3 and higher line numbers are not stored.

The default optimisation level is usually level 0.

micropython.alloc_emergency_exception_buf(size)

Allocate size bytes of RAM for the emergency exception buffer (a good size is around 100 bytes). The buffer is used to create exceptions in cases when normal RAM allocation would fail (eg within an interrupt handler) and therefore give useful traceback information in these situations.

A good way to use this function is to put it at the start of your main script (eg boot.py or main.py) and then the emergency exception buffer will be active for all the code following it.

micropython.mem_info([verbose])

Print information about currently used memory. If the verbose argument is given then extra information is printed.

The information that is printed is implementation dependent, but currently includes the amount of stack and heap used. In verbose mode it prints out the entire heap indicating which blocks are used and which are free.

micropython.qstr_info([verbose])

Print information about currently interned strings. If the verbose argument is given then extra information is printed.

The information that is printed is implementation dependent, but currently includes the number of interned strings and the amount of RAM they use. In verbose mode it prints out the names of all RAM-interned strings.

micropython.stack_use()

Return an integer representing the current amount of stack that is being used. The absolute value of this is not particularly useful, rather it should be used to compute differences in stack usage at different points.

micropython.heap_lock()
micropython.heap_unlock()

Lock or unlock the heap. When locked no memory allocation can occur and a MemoryError will be raised if any heap allocation is attempted.

These functions can be nested, ie heap_lock() can be called multiple times in a row and the lock-depth will increase, and then heap_unlock() must be called the same number of times to make the heap available again.

micropython.kbd_intr(chr)

Set the character that will raise a KeyboardInterrupt exception. By default this is set to 3 during script execution, corresponding to Ctrl-C. Passing -1 to this function will disable capture of Ctrl-C, and passing 3 will restore it.

This function can be used to prevent the capturing of Ctrl-C on the incoming stream of characters that is usually used for the REPL, in case that stream is used for other purposes.

micropython.schedule(func, arg)

Schedule the function func to be executed "very soon". The function is passed the value arg as its single argument. "Very soon" means that the MicroPython runtime will do its best to execute the function at the earliest possible time, given that it is also trying to be efficient, and that the following conditions hold:

  • A scheduled function will never preempt another scheduled function.
  • Scheduled functions are always executed "between opcodes" which means that all fundamental Python operations (such as appending to a list) are guaranteed to be atomic.
  • A given port may define "critical regions" within which scheduled functions will never be executed. Functions may be scheduled within a critical region but they will not be executed until that region is exited. An example of a critical region is a preempting interrupt handler (an IRQ).

A use for this function is to schedule a callback from a preempting IRQ. Such an IRQ puts restrictions on the code that runs in the IRQ (for example the heap may be locked) and scheduling a function to call later will lift those restrictions.

Note: If schedule() is called from a preempting IRQ, when memory allocation is not allowed and the callback to be passed to schedule() is a bound method, passing this directly will fail. This is because creating a reference to a bound method causes memory allocation. A solution is to create a reference to the method in the class constructor and to pass that reference to schedule(). This is discussed in detail here reference documentation under "Creation of Python objects".

There is a finite stack to hold the scheduled functions and schedule() will raise a RuntimeError if the stack is full.

ucryptolib -- cryptographic ciphers

Classes
class ucryptolib.aes
classmethod __init__(key, mode[, IV])

Initialize cipher object, suitable for encryption/decryption. Note: after initialization, cipher object can be use only either for encryption or decryption. Running decrypt() operation after encrypt() or vice versa is not supported.

Parameters are:

  • key is an encryption/decryption key (bytes-like).

  • mode is:

    • 1 (or ucryptolib.MODE_ECB if it exists) for Electronic Code Book (ECB).
    • 2 (or ucryptolib.MODE_CBC if it exists) for Cipher Block Chaining (CBC)
  • IV is an initialization vector for CBC mode.

encrypt(in_buf[, out_buf])

Encrypt in_buf. If no out_buf is given result is returned as a newly allocated bytes object. Otherwise, result is written into mutable buffer out_buf. in_buf and out_buf can also refer to the same mutable buffer, in which case data is encrypted in-place.

decrypt(in_buf[, out_buf])

Like encrypt(), but for decryption.

uctypes -- access binary data in a structured way

This module implements "foreign data interface" for MicroPython. The idea behind it is similar to CPython's ctypes modules, but the actual API is different, streamlined and optimized for small size. The basic idea of the module is to define data structure layout with about the same power as the C language allows, and then access it using familiar dot-syntax to reference sub-fields.

参见

Module ustruct
Standard Python way to access binary data structures (doesn't scale well to large and complex structures).
Defining structure layout

Structure layout is defined by a "descriptor" - a Python dictionary which encodes field names as keys and other properties required to access them as associated values. Currently, uctypes requires explicit specification of offsets for each field. Offset are given in bytes from a structure start.

Following are encoding examples for various field types:

  • Scalar types:

    "field_name": offset | uctypes.UINT32
    

    in other words, value is scalar type identifier ORed with field offset (in bytes) from the start of the structure.

  • Recursive structures:

    "sub": (offset, {
        "b0": 0 | uctypes.UINT8,
        "b1": 1 | uctypes.UINT8,
    })
    

    i.e. value is a 2-tuple, first element of which is offset, and second is a structure descriptor dictionary (note: offsets in recursive descriptors are relative to the structure it defines).

  • Arrays of primitive types:

    "arr": (offset | uctypes.ARRAY, size | uctypes.UINT8),
    

    i.e. value is a 2-tuple, first element of which is ARRAY flag ORed with offset, and second is scalar element type ORed number of elements in array.

  • Arrays of aggregate types:

    "arr2": (offset | uctypes.ARRAY, size, {"b": 0 | uctypes.UINT8}),
    

    i.e. value is a 3-tuple, first element of which is ARRAY flag ORed with offset, second is a number of elements in array, and third is descriptor of element type.

  • Pointer to a primitive type:

    "ptr": (offset | uctypes.PTR, uctypes.UINT8),
    

    i.e. value is a 2-tuple, first element of which is PTR flag ORed with offset, and second is scalar element type.

  • Pointer to an aggregate type:

    "ptr2": (offset | uctypes.PTR, {"b": 0 | uctypes.UINT8}),
    

    i.e. value is a 2-tuple, first element of which is PTR flag ORed with offset, second is descriptor of type pointed to.

  • Bitfields:

    "bitf0": offset | uctypes.BFUINT16 | lsbit << uctypes.BF_POS | bitsize << uctypes.BF_LEN,
    

    i.e. value is type of scalar value containing given bitfield (typenames are similar to scalar types, but prefixes with "BF"), ORed with offset for scalar value containing the bitfield, and further ORed with values for bit offset and bit length of the bitfield within scalar value, shifted by BF_POS and BF_LEN positions, respectively. Bitfield position is counted from the least significant bit, and is the number of right-most bit of a field (in other words, it's a number of bits a scalar needs to be shifted right to extract the bitfield).

    In the example above, first a UINT16 value will be extracted at offset 0 (this detail may be important when accessing hardware registers, where particular access size and alignment are required), and then bitfield whose rightmost bit is lsbit bit of this UINT16, and length is bitsize bits, will be extracted. For example, if lsbit is 0 and bitsize is 8, then effectively it will access least-significant byte of UINT16.

    Note that bitfield operations are independent of target byte endianness, in particular, example above will access least-significant byte of UINT16 in both little- and big-endian structures. But it depends on the least significant bit being numbered 0. Some targets may use different numbering in their native ABI, but uctypes always uses the normalized numbering described above.

Module contents
class uctypes.struct(addr, descriptor, layout_type=NATIVE)

Instantiate a "foreign data structure" object based on structure address in memory, descriptor (encoded as a dictionary), and layout type (see below).

uctypes.LITTLE_ENDIAN

Layout type for a little-endian packed structure. (Packed means that every field occupies exactly as many bytes as defined in the descriptor, i.e. the alignment is 1).

uctypes.BIG_ENDIAN

Layout type for a big-endian packed structure.

uctypes.NATIVE

Layout type for a native structure - with data endianness and alignment conforming to the ABI of the system on which MicroPython runs.

uctypes.sizeof(struct)

Return size of data structure in bytes. Argument can be either structure class or specific instantiated structure object (or its aggregate field).

uctypes.addressof(obj)

Return address of an object. Argument should be bytes, bytearray or other object supporting buffer protocol (and address of this buffer is what actually returned).

uctypes.bytes_at(addr, size)

Capture memory at the given address and size as bytes object. As bytes object is immutable, memory is actually duplicated and copied into bytes object, so if memory contents change later, created object retains original value.

uctypes.bytearray_at(addr, size)

Capture memory at the given address and size as bytearray object. Unlike bytes_at() function above, memory is captured by reference, so it can be both written too, and you will access current value at the given memory address.

Structure descriptors and instantiating structure objects

Given a structure descriptor dictionary and its layout type, you can instantiate a specific structure instance at a given memory address using uctypes.struct() constructor. Memory address usually comes from following sources:

  • Predefined address, when accessing hardware registers on a baremetal system. Lookup these addresses in datasheet for a particular MCU/SoC.
  • As a return value from a call to some FFI (Foreign Function Interface) function.
  • From uctypes.addressof(), when you want to pass arguments to an FFI function, or alternatively, to access some data for I/O (for example, data read from a file or network socket).
Structure objects

Structure objects allow accessing individual fields using standard dot notation: my_struct.substruct1.field1. If a field is of scalar type, getting it will produce a primitive value (Python integer or float) corresponding to the value contained in a field. A scalar field can also be assigned to.

If a field is an array, its individual elements can be accessed with the standard subscript operator [] - both read and assigned to.

If a field is a pointer, it can be dereferenced using [0] syntax (corresponding to C * operator, though [0] works in C too). Subscripting a pointer with other integer values but 0 are supported too, with the same semantics as in C.

Summing up, accessing structure fields generally follows C syntax, except for pointer dereference, when you need to use [0] operator instead of *.

Limitations

Accessing non-scalar fields leads to allocation of intermediate objects to represent them. This means that special care should be taken to layout a structure which needs to be accessed when memory allocation is disabled (e.g. from an interrupt). The recommendations are:

  • Avoid nested structures. For example, instead of mcu_registers.peripheral_a.register1, define separate layout descriptors for each peripheral, to be accessed as peripheral_a.register1.
  • Avoid other non-scalar data, like array. For example, instead of peripheral_a.register[0] use peripheral_a.register0.

Note that these recommendations will lead to decreased readability and conciseness of layouts, so they should be used only if the need to access structure fields without allocation is anticipated (it's even possible to define 2 parallel layouts - one for normal usage, and a restricted one to use when memory allocation is prohibited).

microPython 语言介绍

MicroPython旨在实现Python 3.4标准(选定了最新版本的部分功能) 的语言语法,大多数MicroPython的功能都可以在“语言参考”文档找到具体的描述。 文档链接: docs.python.org.

MicroPython 标准库的说明请从参考章节 micropython 标准库. 章节 micropython与cpython的差异 描述了MicroPython和CPython之间的区别(主要包括标准库和类型,也有一些语言级别特征的差异)。

本章介绍了MicroPython的功能和特性实现以及使用如何更好的使用micropython。

Glossary

baremetal
A system without a (full-fledged) OS, for example an MCU-based system. When running on a baremetal system, MicroPython effectively becomes its user-facing OS with a command interpreter (REPL).
board
A PCB board. Oftentimes, the term is used to denote a particular model of an MCU system. Sometimes, it is used to actually refer to MicroPython port to a particular board (and then may also refer to "boardless" ports like Unix port).
callee-owned tuple
A tuple returned by some builtin function/method, containing data which is valid for a limited time, usually until next call to the same function (or a group of related functions). After next call, data in the tuple may be changed. This leads to the following restriction on the usage of callee-owned tuples - references to them cannot be stored. The only valid operation is extracting values from them (including making a copy). Callee-owned tuples is a MicroPython-specific construct (not available in the general Python language), introduced for memory allocation optimization. The idea is that callee-owned tuple is allocated once and stored on the callee side. Subsequent calls don't require allocation, allowing to return multiple values when allocation is not possible (e.g. in interrupt context) or not desirable (because allocation inherently leads to memory fragmentation). Note that callee-owned tuples are effectively mutable tuples, making an exception to Python's rule that tuples are immutable. (It may be interesting why tuples were used for such a purpose then, instead of mutable lists - the reason for that is that lists are mutable from user application side too, so a user could do things to a callee-owned list which the callee doesn't expect and could lead to problems; a tuple is protected from this.)
CPython
CPython is the reference implementation of Python programming language, and the most well-known one, which most of the people run. It is however one of many implementations (among which Jython, IronPython, PyPy, and many more, including MicroPython). As there is no formal specification of the Python language, only CPython documentation, it is not always easy to draw a line between Python the language and CPython its particular implementation. This however leaves more freedom for other implementations. For example, MicroPython does a lot of things differently than CPython, while still aspiring to be a Python language implementation.
GPIO
General-purpose input/output. The simplest means to control electrical signals. With GPIO, user can configure hardware signal pin to be either input or output, and set or get its digital signal value (logical "0" or "1"). MicroPython abstracts GPIO access using machine.Pin and machine.Signal classes.
GPIO port
A group of GPIO pins, usually based on hardware properties of these pins (e.g. controllable by the same register).
interned string
A string referenced by its (unique) identity rather than its address. Interned strings are thus can be quickly compared just by their identifiers, instead of comparing by content. The drawbacks of interned strings are that interning operation takes time (proportional to the number of existing interned strings, i.e. becoming slower and slower over time) and that the space used for interned strings is not reclaimable. String interning is done automatically by MicroPython compiler and runtimer when it's either required by the implementation (e.g. function keyword arguments are represented by interned string id's) or deemed beneficial (e.g. for short enough strings, which have a chance to be repeated, and thus interning them would save memory on copies). Most of string and I/O operations don't produce interned strings due to drawbacks described above.
MCU
Microcontroller. Microcontrollers usually have much less resources than a full-fledged computing system, but smaller, cheaper and require much less power. MicroPython is designed to be small and optimized enough to run on an average modern microcontroller.
micropython-lib

MicroPython is (usually) distributed as a single executable/binary file with just few builtin modules. There is no extensive standard library comparable with CPython. Instead, there is a related, but separate project micropython-lib which provides implementations for many modules from CPython's standard library. However, large subset of these modules require POSIX-like environment (Linux, FreeBSD, MacOS, etc.; Windows may be partially supported), and thus would work or make sense only with MicroPython Unix port. Some subset of modules is however usable for baremetal ports too.

Unlike monolithic CPython stdlib, micropython-lib modules are intended to be installed individually - either using manual copying or using upip.

MicroPython port
MicroPython supports different boards, RTOSes, and OSes, and can be relatively easily adapted to new systems. MicroPython with support for a particular system is called a "port" to that system. Different ports may have widely different functionality. This documentation is intended to be a reference of the generic APIs available across different ports ("MicroPython core"). Note that some ports may still omit some APIs described here (e.g. due to resource constraints). Any such differences, and port-specific extensions beyond MicroPython core functionality, would be described in the separate port-specific documentation.
MicroPython Unix port
Unix port is one of the major MicroPython ports. It is intended to run on POSIX-compatible operating systems, like Linux, MacOS, FreeBSD, Solaris, etc. It also serves as the basis of Windows port. The importance of Unix port lies in the fact that while there are many different boards, so two random users unlikely have the same board, almost all modern OSes have some level of POSIX compatibility, so Unix port serves as a kind of "common ground" to which any user can have access. So, Unix port is used for initial prototyping, different kinds of testing, development of machine-independent features, etc. All users of MicroPython, even those which are interested only in running MicroPython on MCU systems, are recommended to be familiar with Unix (or Windows) port, as it is important productivity helper and a part of normal MicroPython workflow.
port
Either MicroPython port or GPIO port. If not clear from context, it's recommended to use full specification like one of the above.
stream
Also known as a "file-like object". An object which provides sequential read-write access to the underlying data. A stream object implements a corresponding interface, which consists of methods like read(), write(), readinto(), seek(), flush(), close(), etc. A stream is an important concept in MicroPython, many I/O objects implement the stream interface, and thus can be used consistently and interchangeably in different contexts. For more information on streams in MicroPython, see uio module.
upip
(Literally, "micro pip"). A package manage for MicroPython, inspired by CPython's pip, but much smaller and with reduced functionality. upip runs both on Unix port and on baremetal ports (those which offer filesystem and networking support).

The MicroPython Interactive Interpreter Mode (aka REPL)

This section covers some characteristics of the MicroPython Interactive Interpreter Mode. A commonly used term for this is REPL (read-eval-print-loop) which will be used to refer to this interactive prompt.

Auto-indent

When typing python statements which end in a colon (for example if, for, while) then the prompt will change to three dots (...) and the cursor will be indented by 4 spaces. When you press return, the next line will continue at the same level of indentation for regular statements or an additional level of indentation where appropriate. If you press the backspace key then it will undo one level of indentation.

If your cursor is all the way back at the beginning, pressing RETURN will then execute the code that you've entered. The following shows what you'd see after entering a for statement (the underscore shows where the cursor winds up):

>>> for i in range(30):
...     _

If you then enter an if statement, an additional level of indentation will be provided:

>>> for i in range(30):
...     if i > 3:
...         _

Now enter break followed by RETURN and press BACKSPACE:

>>> for i in range(30):
...     if i > 3:
...         break
...     _

Finally type print(i), press RETURN, press BACKSPACE and press RETURN again:

>>> for i in range(30):
...     if i > 3:
...         break
...     print(i)
...
0
1
2
3
>>>

Auto-indent won't be applied if the previous two lines were all spaces. This means that you can finish entering a compound statement by pressing RETURN twice, and then a third press will finish and execute.

Auto-completion

While typing a command at the REPL, if the line typed so far corresponds to the beginning of the name of something, then pressing TAB will show possible things that could be entered. For example, first import the machine module by entering import machine and pressing RETURN. Then type m and press TAB and it should expand to machine. Enter a dot . and press TAB again. You should see something like:

>>> machine.
__name__        info            unique_id       reset
bootloader      freq            rng             idle
sleep           deepsleep       disable_irq     enable_irq
Pin

The word will be expanded as much as possible until multiple possibilities exist. For example, type machine.Pin.AF3 and press TAB and it will expand to machine.Pin.AF3_TIM. Pressing TAB a second time will show the possible expansions:

>>> machine.Pin.AF3_TIM
AF3_TIM10       AF3_TIM11       AF3_TIM8        AF3_TIM9
>>> machine.Pin.AF3_TIM

Interrupting a running program

You can interrupt a running program by pressing Ctrl-C. This will raise a KeyboardInterrupt which will bring you back to the REPL, providing your program doesn't intercept the KeyboardInterrupt exception.

For example:

>>> for i in range(1000000):
...     print(i)
...
0
1
2
3
...
6466
6467
6468
Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
KeyboardInterrupt:
>>>

Paste Mode

If you want to paste some code into your terminal window, the auto-indent feature will mess things up. For example, if you had the following python code:

def foo():
    print('This is a test to show paste mode')
    print('Here is a second line')
foo()

and you try to paste this into the normal REPL, then you will see something like this:

>>> def foo():
...         print('This is a test to show paste mode')
...             print('Here is a second line')
...             foo()
...
  File "<stdin>", line 3
IndentationError: unexpected indent

If you press Ctrl-E, then you will enter paste mode, which essentially turns off the auto-indent feature, and changes the prompt from >>> to ===. For example:

>>>
paste mode; Ctrl-C to cancel, Ctrl-D to finish
=== def foo():
===     print('This is a test to show paste mode')
===     print('Here is a second line')
=== foo()
===
This is a test to show paste mode
Here is a second line
>>>

Paste Mode allows blank lines to be pasted. The pasted text is compiled as if it were a file. Pressing Ctrl-D exits paste mode and initiates the compilation.

Soft Reset

A soft reset will reset the python interpreter, but tries not to reset the method by which you're connected to the MicroPython board (USB-serial, or Wifi).

You can perform a soft reset from the REPL by pressing Ctrl-D, or from your python code by executing:

machine.soft_reset()

For example, if you reset your MicroPython board, and you execute a dir() command, you'd see something like this:

>>> dir()
['__name__', 'pyb']

Now create some variables and repeat the dir() command:

>>> i = 1
>>> j = 23
>>> x = 'abc'
>>> dir()
['j', 'x', '__name__', 'pyb', 'i']
>>>

Now if you enter Ctrl-D, and repeat the dir() command, you'll see that your variables no longer exist:

PYB: sync filesystems
PYB: soft reboot
MicroPython v1.5-51-g6f70283-dirty on 2015-10-30; PYBv1.0 with STM32F405RG
Type "help()" for more information.
>>> dir()
['__name__', 'pyb']
>>>

The special variable _ (underscore)

When you use the REPL, you may perform computations and see the results. MicroPython stores the results of the previous statement in the variable _ (underscore). So you can use the underscore to save the result in a variable. For example:

>>> 1 + 2 + 3 + 4 + 5
15
>>> x = _
>>> x
15
>>>

Raw Mode

Raw mode is not something that a person would normally use. It is intended for programmatic use. It essentially behaves like paste mode with echo turned off.

Raw mode is entered using Ctrl-A. You then send your python code, followed by a Ctrl-D. The Ctrl-D will be acknowledged by 'OK' and then the python code will be compiled and executed. Any output (or errors) will be sent back. Entering Ctrl-B will leave raw mode and return the the regular (aka friendly) REPL.

The tools/pyboard.py program uses the raw REPL to execute python files on the MicroPython board.

Writing interrupt handlers

On suitable hardware MicroPython offers the ability to write interrupt handlers in Python. Interrupt handlers - also known as interrupt service routines (ISR's) - are defined as callback functions. These are executed in response to an event such as a timer trigger or a voltage change on a pin. Such events can occur at any point in the execution of the program code. This carries significant consequences, some specific to the MicroPython language. Others are common to all systems capable of responding to real time events. This document covers the language specific issues first, followed by a brief introduction to real time programming for those new to it.

This introduction uses vague terms like "slow" or "as fast as possible". This is deliberate, as speeds are application dependent. Acceptable durations for an ISR are dependent on the rate at which interrupts occur, the nature of the main program, and the presence of other concurrent events.

MicroPython Issues

The emergency exception buffer

If an error occurs in an ISR, MicroPython is unable to produce an error report unless a special buffer is created for the purpose. Debugging is simplified if the following code is included in any program using interrupts.

import micropython
micropython.alloc_emergency_exception_buf(100)
Simplicity

For a variety of reasons it is important to keep ISR code as short and simple as possible. It should do only what has to be done immediately after the event which caused it: operations which can be deferred should be delegated to the main program loop. Typically an ISR will deal with the hardware device which caused the interrupt, making it ready for the next interrupt to occur. It will communicate with the main loop by updating shared data to indicate that the interrupt has occurred, and it will return. An ISR should return control to the main loop as quickly as possible. This is not a specific MicroPython issue so is covered in more detail below.

Communication between an ISR and the main program

Normally an ISR needs to communicate with the main program. The simplest means of doing this is via one or more shared data objects, either declared as global or shared via a class (see below). There are various restrictions and hazards around doing this, which are covered in more detail below. Integers, bytes and bytearray objects are commonly used for this purpose along with arrays (from the array module) which can store various data types.

The use of object methods as callbacks

MicroPython supports this powerful technique which enables an ISR to share instance variables with the underlying code. It also enables a class implementing a device driver to support multiple device instances. The following example causes two LED's to flash at different rates.

import pyb, micropython
micropython.alloc_emergency_exception_buf(100)
class Foo(object):
    def __init__(self, timer, led):
        self.led = led
        timer.callback(self.cb)
    def cb(self, tim):
        self.led.toggle()

red = Foo(pyb.Timer(4, freq=1), pyb.LED(1))
green = Foo(pyb.Timer(2, freq=0.8), pyb.LED(2))

In this example the red instance associates timer 4 with LED 1: when a timer 4 interrupt occurs red.cb() is called causing LED 1 to change state. The green instance operates similarly: a timer 2 interrupt results in the execution of green.cb() and toggles LED 2. The use of instance methods confers two benefits. Firstly a single class enables code to be shared between multiple hardware instances. Secondly, as a bound method the callback function's first argument is self. This enables the callback to access instance data and to save state between successive calls. For example, if the class above had a variable self.count set to zero in the constructor, cb() could increment the counter. The red and green instances would then maintain independent counts of the number of times each LED had changed state.

Creation of Python objects

ISR's cannot create instances of Python objects. This is because MicroPython needs to allocate memory for the object from a store of free memory block called the heap. This is not permitted in an interrupt handler because heap allocation is not re-entrant. In other words the interrupt might occur when the main program is part way through performing an allocation - to maintain the integrity of the heap the interpreter disallows memory allocations in ISR code.

A consequence of this is that ISR's can't use floating point arithmetic; this is because floats are Python objects. Similarly an ISR can't append an item to a list. In practice it can be hard to determine exactly which code constructs will attempt to perform memory allocation and provoke an error message: another reason for keeping ISR code short and simple.

One way to avoid this issue is for the ISR to use pre-allocated buffers. For example a class constructor creates a bytearray instance and a boolean flag. The ISR method assigns data to locations in the buffer and sets the flag. The memory allocation occurs in the main program code when the object is instantiated rather than in the ISR.

The MicroPython library I/O methods usually provide an option to use a pre-allocated buffer. For example pyb.i2c.recv() can accept a mutable buffer as its first argument: this enables its use in an ISR.

A means of creating an object without employing a class or globals is as follows:

def set_volume(t, buf=bytearray(3)):
    buf[0] = 0xa5
    buf[1] = t >> 4
    buf[2] = 0x5a
    return buf

The compiler instantiates the default buf argument when the function is loaded for the first time (usually when the module it's in is imported).

An instance of object creation occurs when a reference to a bound method is created. This means that an ISR cannot pass a bound method to a function. One solution is to create a reference to the bound method in the class constructor and to pass that reference in the ISR. For example:

class Foo():
    def __init__(self):
        self.bar_ref = self.bar  # Allocation occurs here
        self.x = 0.1
        tim = pyb.Timer(4)
        tim.init(freq=2)
        tim.callback(self.cb)

    def bar(self, _):
        self.x *= 1.2
        print(self.x)

    def cb(self, t):
        # Passing self.bar would cause allocation.
        micropython.schedule(self.bar_ref, 0)

Other techniques are to define and instantiate the method in the constructor or to pass Foo.bar() with the argument self.

Use of Python objects

A further restriction on objects arises because of the way Python works. When an import statement is executed the Python code is compiled to bytecode, with one line of code typically mapping to multiple bytecodes. When the code runs the interpreter reads each bytecode and executes it as a series of machine code instructions. Given that an interrupt can occur at any time between machine code instructions, the original line of Python code may be only partially executed. Consequently a Python object such as a set, list or dictionary modified in the main loop may lack internal consistency at the moment the interrupt occurs.

A typical outcome is as follows. On rare occasions the ISR will run at the precise moment in time when the object is partially updated. When the ISR tries to read the object, a crash results. Because such problems typically occur on rare, random occasions they can be hard to diagnose. There are ways to circumvent this issue, described in Critical Sections below.

It is important to be clear about what constitutes the modification of an object. An alteration to a built-in type such as a dictionary is problematic. Altering the contents of an array or bytearray is not. This is because bytes or words are written as a single machine code instruction which is not interruptible: in the parlance of real time programming the write is atomic. A user defined object might instantiate an integer, array or bytearray. It is valid for both the main loop and the ISR to alter the contents of these.

MicroPython supports integers of arbitrary precision. Values between 2**30 -1 and -2**30 will be stored in a single machine word. Larger values are stored as Python objects. Consequently changes to long integers cannot be considered atomic. The use of long integers in ISR's is unsafe because memory allocation may be attempted as the variable's value changes.

Overcoming the float limitation

In general it is best to avoid using floats in ISR code: hardware devices normally handle integers and conversion to floats is normally done in the main loop. However there are a few DSP algorithms which require floating point. On platforms with hardware floating point (such as the Pyboard) the inline ARM Thumb assembler can be used to work round this limitation. This is because the processor stores float values in a machine word; values can be shared between the ISR and main program code via an array of floats.

Using micropython.schedule

This function enables an ISR to schedule a callback for execution "very soon". The callback is queued for execution which will take place at a time when the heap is not locked. Hence it can create Python objects and use floats. The callback is also guaranteed to run at a time when the main program has completed any update of Python objects, so the callback will not encounter partially updated objects.

Typical usage is to handle sensor hardware. The ISR acquires data from the hardware and enables it to issue a further interrupt. It then schedules a callback to process the data.

Scheduled callbacks should comply with the principles of interrupt handler design outlined below. This is to avoid problems resulting from I/O activity and the modification of shared data which can arise in any code which pre-empts the main program loop.

Execution time needs to be considered in relation to the frequency with which interrupts can occur. If an interrupt occurs while the previous callback is executing, a further instance of the callback will be queued for execution; this will run after the current instance has completed. A sustained high interrupt repetition rate therefore carries a risk of unconstrained queue growth and eventual failure with a RuntimeError.

If the callback to be passed to schedule() is a bound method, consider the note in "Creation of Python objects".

Exceptions

If an ISR raises an exception it will not propagate to the main loop. The interrupt will be disabled unless the exception is handled by the ISR code.

General Issues

This is merely a brief introduction to the subject of real time programming. Beginners should note that design errors in real time programs can lead to faults which are particularly hard to diagnose. This is because they can occur rarely and at intervals which are essentially random. It is crucial to get the initial design right and to anticipate issues before they arise. Both interrupt handlers and the main program need to be designed with an appreciation of the following issues.

Interrupt Handler Design

As mentioned above, ISR's should be designed to be as simple as possible. They should always return in a short, predictable period of time. This is important because when the ISR is running, the main loop is not: inevitably the main loop experiences pauses in its execution at random points in the code. Such pauses can be a source of hard to diagnose bugs particularly if their duration is long or variable. In order to understand the implications of ISR run time, a basic grasp of interrupt priorities is required.

Interrupts are organised according to a priority scheme. ISR code may itself be interrupted by a higher priority interrupt. This has implications if the two interrupts share data (see Critical Sections below). If such an interrupt occurs it interposes a delay into the ISR code. If a lower priority interrupt occurs while the ISR is running, it will be delayed until the ISR is complete: if the delay is too long, the lower priority interrupt may fail. A further issue with slow ISR's is the case where a second interrupt of the same type occurs during its execution. The second interrupt will be handled on termination of the first. However if the rate of incoming interrupts consistently exceeds the capacity of the ISR to service them the outcome will not be a happy one.

Consequently looping constructs should be avoided or minimised. I/O to devices other than to the interrupting device should normally be avoided: I/O such as disk access, print statements and UART access is relatively slow, and its duration may vary. A further issue here is that filesystem functions are not reentrant: using filesystem I/O in an ISR and the main program would be hazardous. Crucially ISR code should not wait on an event. I/O is acceptable if the code can be guaranteed to return in a predictable period, for example toggling a pin or LED. Accessing the interrupting device via I2C or SPI may be necessary but the time taken for such accesses should be calculated or measured and its impact on the application assessed.

There is usually a need to share data between the ISR and the main loop. This may be done either through global variables or via class or instance variables. Variables are typically integer or boolean types, or integer or byte arrays (a pre-allocated integer array offers faster access than a list). Where multiple values are modified by the ISR it is necessary to consider the case where the interrupt occurs at a time when the main program has accessed some, but not all, of the values. This can lead to inconsistencies.

Consider the following design. An ISR stores incoming data in a bytearray, then adds the number of bytes received to an integer representing total bytes ready for processing. The main program reads the number of bytes, processes the bytes, then clears down the number of bytes ready. This will work until an interrupt occurs just after the main program has read the number of bytes. The ISR puts the added data into the buffer and updates the number received, but the main program has already read the number, so processes the data originally received. The newly arrived bytes are lost.

There are various ways of avoiding this hazard, the simplest being to use a circular buffer. If it is not possible to use a structure with inherent thread safety other ways are described below.

Reentrancy

A potential hazard may occur if a function or method is shared between the main program and one or more ISR's or between multiple ISR's. The issue here is that the function may itself be interrupted and a further instance of that function run. If this is to occur, the function must be designed to be reentrant. How this is done is an advanced topic beyond the scope of this tutorial.

Critical Sections

An example of a critical section of code is one which accesses more than one variable which can be affected by an ISR. If the interrupt happens to occur between accesses to the individual variables, their values will be inconsistent. This is an instance of a hazard known as a race condition: the ISR and the main program loop race to alter the variables. To avoid inconsistency a means must be employed to ensure that the ISR does not alter the values for the duration of the critical section. One way to achieve this is to issue pyb.disable_irq() before the start of the section, and pyb.enable_irq() at the end. Here is an example of this approach:

import pyb, micropython, array
micropython.alloc_emergency_exception_buf(100)

class BoundsException(Exception):
    pass

ARRAYSIZE = const(20)
index = 0
data = array.array('i', 0 for x in range(ARRAYSIZE))

def callback1(t):
    global data, index
    for x in range(5):
        data[index] = pyb.rng() # simulate input
        index += 1
        if index >= ARRAYSIZE:
            raise BoundsException('Array bounds exceeded')

tim4 = pyb.Timer(4, freq=100, callback=callback1)

for loop in range(1000):
    if index > 0:
        irq_state = pyb.disable_irq() # Start of critical section
        for x in range(index):
            print(data[x])
        index = 0
        pyb.enable_irq(irq_state) # End of critical section
        print('loop {}'.format(loop))
    pyb.delay(1)

tim4.callback(None)

A critical section can comprise a single line of code and a single variable. Consider the following code fragment.

count = 0
def cb(): # An interrupt callback
    count +=1
def main():
    # Code to set up the interrupt callback omitted
    while True:
        count += 1

This example illustrates a subtle source of bugs. The line count += 1 in the main loop carries a specific race condition hazard known as a read-modify-write. This is a classic cause of bugs in real time systems. In the main loop MicroPython reads the value of t.counter, adds 1 to it, and writes it back. On rare occasions the interrupt occurs after the read and before the write. The interrupt modifies t.counter but its change is overwritten by the main loop when the ISR returns. In a real system this could lead to rare, unpredictable failures.

As mentioned above, care should be taken if an instance of a Python built in type is modified in the main code and that instance is accessed in an ISR. The code performing the modification should be regarded as a critical section to ensure that the instance is in a valid state when the ISR runs.

Particular care needs to be taken if a dataset is shared between different ISR's. The hazard here is that the higher priority interrupt may occur when the lower priority one has partially updated the shared data. Dealing with this situation is an advanced topic beyond the scope of this introduction other than to note that mutex objects described below can sometimes be used.

Disabling interrupts for the duration of a critical section is the usual and simplest way to proceed, but it disables all interrupts rather than merely the one with the potential to cause problems. It is generally undesirable to disable an interrupt for long. In the case of timer interrupts it introduces variability to the time when a callback occurs. In the case of device interrupts, it can lead to the device being serviced too late with possible loss of data or overrun errors in the device hardware. Like ISR's, a critical section in the main code should have a short, predictable duration.

An approach to dealing with critical sections which radically reduces the time for which interrupts are disabled is to use an object termed a mutex (name derived from the notion of mutual exclusion). The main program locks the mutex before running the critical section and unlocks it at the end. The ISR tests whether the mutex is locked. If it is, it avoids the critical section and returns. The design challenge is defining what the ISR should do in the event that access to the critical variables is denied. A simple example of a mutex may be found here. Note that the mutex code does disable interrupts, but only for the duration of eight machine instructions: the benefit of this approach is that other interrupts are virtually unaffected.

Interrupts and the REPL

Interrupt handlers, such as those associated with timers, can continue to run after a program terminates. This may produce unexpected results where you might have expected the object raising the callback to have gone out of scope. For example on the Pyboard:

def bar():
    foo = pyb.Timer(2, freq=4, callback=lambda t: print('.', end=''))

bar()

This continues to run until the timer is explicitly disabled or the board is reset with ctrl D.

Maximising MicroPython Speed

This tutorial describes ways of improving the performance of MicroPython code. Optimisations involving other languages are covered elsewhere, namely the use of modules written in C and the MicroPython inline assembler.

The process of developing high performance code comprises the following stages which should be performed in the order listed.

  • Design for speed.
  • Code and debug.

Optimisation steps:

  • Identify the slowest section of code.
  • Improve the efficiency of the Python code.
  • Use the native code emitter.
  • Use the viper code emitter.
  • Use hardware-specific optimisations.

Designing for speed

Performance issues should be considered at the outset. This involves taking a view on the sections of code which are most performance critical and devoting particular attention to their design. The process of optimisation begins when the code has been tested: if the design is correct at the outset optimisation will be straightforward and may actually be unnecessary.

Algorithms

The most important aspect of designing any routine for performance is ensuring that the best algorithm is employed. This is a topic for textbooks rather than for a MicroPython guide but spectacular performance gains can sometimes be achieved by adopting algorithms known for their efficiency.

RAM Allocation

To design efficient MicroPython code it is necessary to have an understanding of the way the interpreter allocates RAM. When an object is created or grows in size (for example where an item is appended to a list) the necessary RAM is allocated from a block known as the heap. This takes a significant amount of time; further it will on occasion trigger a process known as garbage collection which can take several milliseconds.

Consequently the performance of a function or method can be improved if an object is created once only and not permitted to grow in size. This implies that the object persists for the duration of its use: typically it will be instantiated in a class constructor and used in various methods.

This is covered in further detail Controlling garbage collection below.

Buffers

An example of the above is the common case where a buffer is required, such as one used for communication with a device. A typical driver will create the buffer in the constructor and use it in its I/O methods which will be called repeatedly.

The MicroPython libraries typically provide support for pre-allocated buffers. For example, objects which support stream interface (e.g., file or UART) provide read() method which allocates new buffer for read data, but also a readinto() method to read data into an existing buffer.

Floating Point

Some MicroPython ports allocate floating point numbers on heap. Some other ports may lack dedicated floating-point coprocessor, and perform arithmetic operations on them in "software" at considerably lower speed than on integers. Where performance is important, use integer operations and restrict the use of floating point to sections of the code where performance is not paramount. For example, capture ADC readings as integers values to an array in one quick go, and only then convert them to floating-point numbers for signal processing.

Arrays

Consider the use of the various types of array classes as an alternative to lists. The array module supports various element types with 8-bit elements supported by Python's built in bytes and bytearray classes. These data structures all store elements in contiguous memory locations. Once again to avoid memory allocation in critical code these should be pre-allocated and passed as arguments or as bound objects.

When passing slices of objects such as bytearray instances, Python creates a copy which involves allocation of the size proportional to the size of slice. This can be alleviated using a memoryview object. memoryview itself is allocated on heap, but is a small, fixed-size object, regardless of the size of slice it points too.

ba = bytearray(10000)  # big array
func(ba[30:2000])      # a copy is passed, ~2K new allocation
mv = memoryview(ba)    # small object is allocated
func(mv[30:2000])      # a pointer to memory is passed

A memoryview can only be applied to objects supporting the buffer protocol - this includes arrays but not lists. Small caveat is that while memoryview object is live, it also keeps alive the original buffer object. So, a memoryview isn't a universal panacea. For instance, in the example above, if you are done with 10K buffer and just need those bytes 30:2000 from it, it may be better to make a slice, and let the 10K buffer go (be ready for garbage collection), instead of making a long-living memoryview and keeping 10K blocked for GC.

Nonetheless, memoryview is indispensable for advanced preallocated buffer management. readinto() method discussed above puts data at the beginning of buffer and fills in entire buffer. What if you need to put data in the middle of existing buffer? Just create a memoryview into the needed section of buffer and pass it to readinto().

Identifying the slowest section of code

This is a process known as profiling and is covered in textbooks and (for standard Python) supported by various software tools. For the type of smaller embedded application likely to be running on MicroPython platforms the slowest function or method can usually be established by judicious use of the timing ticks group of functions documented in utime. Code execution time can be measured in ms, us, or CPU cycles.

The following enables any function or method to be timed by adding an @timed_function decorator:

def timed_function(f, *args, **kwargs):
    myname = str(f).split(' ')[1]
    def new_func(*args, **kwargs):
        t = utime.ticks_us()
        result = f(*args, **kwargs)
        delta = utime.ticks_diff(utime.ticks_us(), t)
        print('Function {} Time = {:6.3f}ms'.format(myname, delta/1000))
        return result
    return new_func

MicroPython code improvements

The const() declaration

MicroPython provides a const() declaration. This works in a similar way to #define in C in that when the code is compiled to bytecode the compiler substitutes the numeric value for the identifier. This avoids a dictionary lookup at runtime. The argument to const() may be anything which, at compile time, evaluates to an integer e.g. 0x100 or 1 << 8.

Caching object references

Where a function or method repeatedly accesses objects performance is improved by caching the object in a local variable:

class foo(object):
    def __init__(self):
        ba = bytearray(100)
    def bar(self, obj_display):
        ba_ref = self.ba
        fb = obj_display.framebuffer
        # iterative code using these two objects

This avoids the need repeatedly to look up self.ba and obj_display.framebuffer in the body of the method bar().

Controlling garbage collection

When memory allocation is required, MicroPython attempts to locate an adequately sized block on the heap. This may fail, usually because the heap is cluttered with objects which are no longer referenced by code. If a failure occurs, the process known as garbage collection reclaims the memory used by these redundant objects and the allocation is then tried again - a process which can take several milliseconds.

There may be benefits in pre-empting this by periodically issuing gc.collect(). Firstly doing a collection before it is actually required is quicker - typically on the order of 1ms if done frequently. Secondly you can determine the point in code where this time is used rather than have a longer delay occur at random points, possibly in a speed critical section. Finally performing collections regularly can reduce fragmentation in the heap. Severe fragmentation can lead to non-recoverable allocation failures.

The Native code emitter

This causes the MicroPython compiler to emit native CPU opcodes rather than bytecode. It covers the bulk of the MicroPython functionality, so most functions will require no adaptation (but see below). It is invoked by means of a function decorator:

@micropython.native
def foo(self, arg):
    buf = self.linebuf # Cached object
    # code

There are certain limitations in the current implementation of the native code emitter.

  • Context managers are not supported (the with statement).
  • Generators are not supported.
  • If raise is used an argument must be supplied.

The trade-off for the improved performance (roughly twices as fast as bytecode) is an increase in compiled code size.

The Viper code emitter

The optimisations discussed above involve standards-compliant Python code. The Viper code emitter is not fully compliant. It supports special Viper native data types in pursuit of performance. Integer processing is non-compliant because it uses machine words: arithmetic on 32 bit hardware is performed modulo 2**32.

Like the Native emitter Viper produces machine instructions but further optimisations are performed, substantially increasing performance especially for integer arithmetic and bit manipulations. It is invoked using a decorator:

@micropython.viper
def foo(self, arg: int) -> int:
    # code

As the above fragment illustrates it is beneficial to use Python type hints to assist the Viper optimiser. Type hints provide information on the data types of arguments and of the return value; these are a standard Python language feature formally defined here PEP0484. Viper supports its own set of types namely int, uint (unsigned integer), ptr, ptr8, ptr16 and ptr32. The ptrX types are discussed below. Currently the uint type serves a single purpose: as a type hint for a function return value. If such a function returns 0xffffffff Python will interpret the result as 2**32 -1 rather than as -1.

In addition to the restrictions imposed by the native emitter the following constraints apply:

  • Functions may have up to four arguments.
  • Default argument values are not permitted.
  • Floating point may be used but is not optimised.

Viper provides pointer types to assist the optimiser. These comprise

  • ptr Pointer to an object.
  • ptr8 Points to a byte.
  • ptr16 Points to a 16 bit half-word.
  • ptr32 Points to a 32 bit machine word.

The concept of a pointer may be unfamiliar to Python programmers. It has similarities to a Python memoryview object in that it provides direct access to data stored in memory. Items are accessed using subscript notation, but slices are not supported: a pointer can return a single item only. Its purpose is to provide fast random access to data stored in contiguous memory locations - such as data stored in objects which support the buffer protocol, and memory-mapped peripheral registers in a microcontroller. It should be noted that programming using pointers is hazardous: bounds checking is not performed and the compiler does nothing to prevent buffer overrun errors.

Typical usage is to cache variables:

@micropython.viper
def foo(self, arg: int) -> int:
    buf = ptr8(self.linebuf) # self.linebuf is a bytearray or bytes object
    for x in range(20, 30):
        bar = buf[x] # Access a data item through the pointer
        # code omitted

In this instance the compiler "knows" that buf is the address of an array of bytes; it can emit code to rapidly compute the address of buf[x] at runtime. Where casts are used to convert objects to Viper native types these should be performed at the start of the function rather than in critical timing loops as the cast operation can take several microseconds. The rules for casting are as follows:

  • Casting operators are currently: int, bool, uint, ptr, ptr8, ptr16 and ptr32.
  • The result of a cast will be a native Viper variable.
  • Arguments to a cast can be a Python object or a native Viper variable.
  • If argument is a native Viper variable, then cast is a no-op (i.e. costs nothing at runtime) that just changes the type (e.g. from uint to ptr8) so that you can then store/load using this pointer.
  • If the argument is a Python object and the cast is int or uint, then the Python object must be of integral type and the value of that integral object is returned.
  • The argument to a bool cast must be integral type (boolean or integer); when used as a return type the viper function will return True or False objects.
  • If the argument is a Python object and the cast is ptr, ptr, ptr16 or ptr32, then the Python object must either have the buffer protocol with read-write capabilities (in which case a pointer to the start of the buffer is returned) or it must be of integral type (in which case the value of that integral object is returned).

The following example illustrates the use of a ptr16 cast to toggle pin X1 n times:

BIT0 = const(1)
@micropython.viper
def toggle_n(n: int):
    odr = ptr16(stm.GPIOA + stm.GPIO_ODR)
    for _ in range(n):
        odr[0] ^= BIT0

A detailed technical description of the three code emitters may be found on Kickstarter here Note 1 and here Note 2

Accessing hardware directly

注解

Code examples in this section are given for the Pyboard. The techniques described however may be applied to other MicroPython ports too.

This comes into the category of more advanced programming and involves some knowledge of the target MCU. Consider the example of toggling an output pin on the Pyboard. The standard approach would be to write

mypin.value(mypin.value() ^ 1) # mypin was instantiated as an output pin

This involves the overhead of two calls to the Pin instance's value() method. This overhead can be eliminated by performing a read/write to the relevant bit of the chip's GPIO port output data register (odr). To facilitate this the stm module provides a set of constants providing the addresses of the relevant registers. A fast toggle of pin P4 (CPU pin A14) - corresponding to the green LED - can be performed as follows:

import machine
import stm

BIT14 = const(1 << 14)
machine.mem16[stm.GPIOA + stm.GPIO_ODR] ^= BIT14

MicroPython on Microcontrollers

MicroPython is designed to be capable of running on microcontrollers. These have hardware limitations which may be unfamiliar to programmers more familiar with conventional computers. In particular the amount of RAM and nonvolatile "disk" (flash memory) storage is limited. This tutorial offers ways to make the most of the limited resources. Because MicroPython runs on controllers based on a variety of architectures, the methods presented are generic: in some cases it will be necessary to obtain detailed information from platform specific documentation.

Flash Memory

On the Pyboard the simple way to address the limited capacity is to fit a micro SD card. In some cases this is impractical, either because the device does not have an SD card slot or for reasons of cost or power consumption; hence the on-chip flash must be used. The firmware including the MicroPython subsystem is stored in the onboard flash. The remaining capacity is available for use. For reasons connected with the physical architecture of the flash memory part of this capacity may be inaccessible as a filesystem. In such cases this space may be employed by incorporating user modules into a firmware build which is then flashed to the device.

There are two ways to achieve this: frozen modules and frozen bytecode. Frozen modules store the Python source with the firmware. Frozen bytecode uses the cross compiler to convert the source to bytecode which is then stored with the firmware. In either case the module may be accessed with an import statement:

import mymodule

The procedure for producing frozen modules and bytecode is platform dependent; instructions for building the firmware can be found in the README files in the relevant part of the source tree.

In general terms the steps are as follows:

  • Clone the MicroPython repository.
  • Acquire the (platform specific) toolchain to build the firmware.
  • Build the cross compiler.
  • Place the modules to be frozen in a specified directory (dependent on whether the module is to be frozen as source or as bytecode).
  • Build the firmware. A specific command may be required to build frozen code of either type - see the platform documentation.
  • Flash the firmware to the device.

RAM

When reducing RAM usage there are two phases to consider: compilation and execution. In addition to memory consumption, there is also an issue known as heap fragmentation. In general terms it is best to minimise the repeated creation and destruction of objects. The reason for this is covered in the section covering the heap.

Compilation Phase

When a module is imported, MicroPython compiles the code to bytecode which is then executed by the MicroPython virtual machine (VM). The bytecode is stored in RAM. The compiler itself requires RAM, but this becomes available for use when the compilation has completed.

If a number of modules have already been imported the situation can arise where there is insufficient RAM to run the compiler. In this case the import statement will produce a memory exception.

If a module instantiates global objects on import it will consume RAM at the time of import, which is then unavailable for the compiler to use on subsequent imports. In general it is best to avoid code which runs on import; a better approach is to have initialisation code which is run by the application after all modules have been imported. This maximises the RAM available to the compiler.

If RAM is still insufficient to compile all modules one solution is to precompile modules. MicroPython has a cross compiler capable of compiling Python modules to bytecode (see the README in the mpy-cross directory). The resulting bytecode file has a .mpy extension; it may be copied to the filesystem and imported in the usual way. Alternatively some or all modules may be implemented as frozen bytecode: on most platforms this saves even more RAM as the bytecode is run directly from flash rather than being stored in RAM.

Execution Phase

There are a number of coding techniques for reducing RAM usage.

Constants

MicroPython provides a const keyword which may be used as follows:

from micropython import const
ROWS = const(33)
_COLS = const(0x10)
a = ROWS
b = _COLS

In both instances where the constant is assigned to a variable the compiler will avoid coding a lookup to the name of the constant by substituting its literal value. This saves bytecode and hence RAM. However the ROWS value will occupy at least two machine words, one each for the key and value in the globals dictionary. The presence in the dictionary is necessary because another module might import or use it. This RAM can be saved by prepending the name with an underscore as in _COLS: this symbol is not visible outside the module so will not occupy RAM.

The argument to const() may be anything which, at compile time, evaluates to an integer e.g. 0x100 or 1 << 8. It can even include other const symbols that have already been defined, e.g. 1 << BIT.

Constant data structures

Where there is a substantial volume of constant data and the platform supports execution from Flash, RAM may be saved as follows. The data should be located in Python modules and frozen as bytecode. The data must be defined as bytes objects. The compiler 'knows' that bytes objects are immutable and ensures that the objects remain in flash memory rather than being copied to RAM. The ustruct module can assist in converting between bytes types and other Python built-in types.

When considering the implications of frozen bytecode, note that in Python strings, floats, bytes, integers and complex numbers are immutable. Accordingly these will be frozen into flash. Thus, in the line

mystring = "The quick brown fox"

the actual string "The quick brown fox" will reside in flash. At runtime a reference to the string is assigned to the variable mystring. The reference occupies a single machine word. In principle a long integer could be used to store constant data:

bar = 0xDEADBEEF0000DEADBEEF

As in the string example, at runtime a reference to the arbitrarily large integer is assigned to the variable bar. That reference occupies a single machine word.

It might be expected that tuples of integers could be employed for the purpose of storing constant data with minimal RAM use. With the current compiler this is ineffective (the code works, but RAM is not saved).

foo = (1, 2, 3, 4, 5, 6, 100000)

At runtime the tuple will be located in RAM. This may be subject to future improvement.

Needless object creation

There are a number of situations where objects may unwittingly be created and destroyed. This can reduce the usability of RAM through fragmentation. The following sections discuss instances of this.

String concatenation

Consider the following code fragments which aim to produce constant strings:

var = "foo" + "bar"
var1 = "foo" "bar"
var2 = """\
foo\
bar"""

Each produces the same outcome, however the first needlessly creates two string objects at runtime, allocates more RAM for concatenation before producing the third. The others perform the concatenation at compile time which is more efficient, reducing fragmentation.

Where strings must be dynamically created before being fed to a stream such as a file it will save RAM if this is done in a piecemeal fashion. Rather than creating a large string object, create a substring and feed it to the stream before dealing with the next.

The best way to create dynamic strings is by means of the string format() method:

var = "Temperature {:5.2f} Pressure {:06d}\n".format(temp, press)

Buffers

When accessing devices such as instances of UART, I2C and SPI interfaces, using pre-allocated buffers avoids the creation of needless objects. Consider these two loops:

while True:
    var = spi.read(100)
    # process data

buf = bytearray(100)
while True:
    spi.readinto(buf)
    # process data in buf

The first creates a buffer on each pass whereas the second re-uses a pre-allocated buffer; this is both faster and more efficient in terms of memory fragmentation.

Bytes are smaller than ints

On most platforms an integer consumes four bytes. Consider the two calls to the function foo():

def foo(bar):
    for x in bar:
        print(x)
foo((1, 2, 0xff))
foo(b'\1\2\xff')

In the first call a tuple of integers is created in RAM. The second efficiently creates a bytes object consuming the minimum amount of RAM. If the module were frozen as bytecode, the bytes object would reside in flash.

Strings Versus Bytes

Python3 introduced Unicode support. This introduced a distinction between a string and an array of bytes. MicroPython ensures that Unicode strings take no additional space so long as all characters in the string are ASCII (i.e. have a value < 126). If values in the full 8-bit range are required bytes and bytearray objects can be used to ensure that no additional space will be required. Note that most string methods (e.g. str.strip()) apply also to bytes instances so the process of eliminating Unicode can be painless.

s = 'the quick brown fox'   # A string instance
b = b'the quick brown fox'  # A bytes instance

Where it is necessary to convert between strings and bytes the str.encode() and the bytes.decode() methods can be used. Note that both strings and bytes are immutable. Any operation which takes as input such an object and produces another implies at least one RAM allocation to produce the result. In the second line below a new bytes object is allocated. This would also occur if foo were a string.

foo = b'   empty whitespace'
foo = foo.lstrip()

Runtime compiler execution

The Python funcitons eval and exec invoke the compiler at runtime, which requires significant amounts of RAM. Note that the pickle library from micropython-lib employs exec. It may be more RAM efficient to use the ujson library for object serialisation.

Storing strings in flash

Python strings are immutable hence have the potential to be stored in read only memory. The compiler can place in flash strings defined in Python code. As with frozen modules it is necessary to have a copy of the source tree on the PC and the toolchain to build the firmware. The procedure will work even if the modules have not been fully debugged, so long as they can be imported and run.

After importing the modules, execute:

micropython.qstr_info(1)

Then copy and paste all the Q(xxx) lines into a text editor. Check for and remove lines which are obviously invalid. Open the file qstrdefsport.h which will be found in ports/stm32 (or the equivalent directory for the architecture in use). Copy and paste the corrected lines at the end of the file. Save the file, rebuild and flash the firmware. The outcome can be checked by importing the modules and again issuing:

micropython.qstr_info(1)

The Q(xxx) lines should be gone.

The Heap

When a running program instantiates an object the necessary RAM is allocated from a fixed size pool known as the heap. When the object goes out of scope (in other words becomes inaccessible to code) the redundant object is known as "garbage". A process known as "garbage collection" (GC) reclaims that memory, returning it to the free heap. This process runs automatically, however it can be invoked directly by issuing gc.collect().

The discourse on this is somewhat involved. For a 'quick fix' issue the following periodically:

gc.collect()
gc.threshold(gc.mem_free() // 4 + gc.mem_alloc())
Fragmentation

Say a program creates an object foo, then an object bar. Subsequently foo goes out of scope but bar remains. The RAM used by foo will be reclaimed by GC. However if bar was allocated to a higher address, the RAM reclaimed from foo will only be of use for objects no bigger than foo. In a complex or long running program the heap can become fragmented: despite there being a substantial amount of RAM available, there is insufficient contiguous space to allocate a particular object, and the program fails with a memory error.

The techniques outlined above aim to minimise this. Where large permanent buffers or other objects are required it is best to instantiate these early in the process of program execution before fragmentation can occur. Further improvements may be made by monitoring the state of the heap and by controlling GC; these are outlined below.

Reporting

A number of library functions are available to report on memory allocation and to control GC. These are to be found in the gc and micropython modules. The following example may be pasted at the REPL (ctrl e to enter paste mode, ctrl d to run it).

import gc
import micropython
gc.collect()
micropython.mem_info()
print('-----------------------------')
print('Initial free: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc()))
def func():
    a = bytearray(10000)
gc.collect()
print('Func definition: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc()))
func()
print('Func run free: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc()))
gc.collect()
print('Garbage collect free: {} allocated: {}'.format(gc.mem_free(), gc.mem_alloc()))
print('-----------------------------')
micropython.mem_info(1)

Methods employed above:

The numbers produced are dependent on the platform, but it can be seen that declaring the function uses a small amount of RAM in the form of bytecode emitted by the compiler (the RAM used by the compiler has been reclaimed). Running the function uses over 10KiB, but on return a is garbage because it is out of scope and cannot be referenced. The final gc.collect() recovers that memory.

The final output produced by micropython.mem_info(1) will vary in detail but may be interpreted as follows:

Symbol Meaning
. free block
h head block
= tail block
m marked head block
T tuple
L list
D dict
F float
B byte code
M module

Each letter represents a single block of memory, a block being 16 bytes. So each line of the heap dump represents 0x400 bytes or 1KiB of RAM.

Control of Garbage Collection

A GC can be demanded at any time by issuing gc.collect(). It is advantageous to do this at intervals, firstly to pre-empt fragmentation and secondly for performance. A GC can take several milliseconds but is quicker when there is little work to do (about 1ms on the Pyboard). An explicit call can minimise that delay while ensuring it occurs at points in the program when it is acceptable.

Automatic GC is provoked under the following circumstances. When an attempt at allocation fails, a GC is performed and the allocation re-tried. Only if this fails is an exception raised. Secondly an automatic GC will be triggered if the amount of free RAM falls below a threshold. This threshold can be adapted as execution progresses:

gc.collect()
gc.threshold(gc.mem_free() // 4 + gc.mem_alloc())

This will provoke a GC when more than 25% of the currently free heap becomes occupied.

In general modules should instantiate data objects at runtime using constructors or other initialisation functions. The reason is that if this occurs on initialisation the compiler may be starved of RAM when subsequent modules are imported. If modules do instantiate data on import then gc.collect() issued after the import will ameliorate the problem.

String Operations

MicroPython handles strings in an efficient manner and understanding this can help in designing applications to run on microcontrollers. When a module is compiled, strings which occur multiple times are stored once only, a process known as string interning. In MicroPython an interned string is known as a qstr. In a module imported normally that single instance will be located in RAM, but as described above, in modules frozen as bytecode it will be located in flash.

String comparisons are also performed efficiently using hashing rather than character by character. The penalty for using strings rather than integers may hence be small both in terms of performance and RAM usage - a fact which may come as a surprise to C programmers.

Postscript

MicroPython passes, returns and (by default) copies objects by reference. A reference occupies a single machine word so these processes are efficient in RAM usage and speed.

Where variables are required whose size is neither a byte nor a machine word there are standard libraries which can assist in storing these efficiently and in performing conversions. See the array, ustruct and uctypes modules.

Footnote: gc.collect() return value

On Unix and Windows platforms the gc.collect() method returns an integer which signifies the number of distinct memory regions that were reclaimed in the collection (more precisely, the number of heads that were turned into frees). For efficiency reasons bare metal ports do not return this value.

Distribution packages, package management, and deploying applications

Just as the "big" Python, MicroPython supports creation of "third party" packages, distributing them, and easily installing them in each user's environment. This chapter discusses how these actions are achieved. Some familiarity with Python packaging is recommended.

Overview

Steps below represent a high-level workflow when creating and consuming packages:

  1. Python modules and packages are turned into distribution package archives, and published at the Python Package Index (PyPI).
  2. upip package manager can be used to install a distribution package on a MicroPython port with networking capabilities (for example, on the Unix port).
  3. For ports without networking capabilities, an "installation image" can be prepared on the Unix port, and transferred to a device by suitable means.
  4. For low-memory ports, the installation image can be frozen as the bytecode into MicroPython executable, thus minimizing the memory storage overheads.

The sections below describe this process in details.

Distribution packages

Python modules and packages can be packaged into archives suitable for transfer between systems, storing at the well-known location (PyPI), and downloading on demand for deployment. These archives are known as distribution packages (to differentiate them from Python packages (means to organize Python source code)).

The MicroPython distribution package format is a well-known tar.gz format, with some adaptations however. The Gzip compressor, used as an external wrapper for TAR archives, by default uses 32KB dictionary size, which means that to uncompress a compressed stream, 32KB of contguous memory needs to be allocated. This requirement may be not satisfiable on low-memory devices, which may have total memory available less than that amount, and even if not, a contiguous block like that may be hard to allocate due to memory fragmentation. To accommodate these constraints, MicroPython distribution packages use Gzip compression with the dictionary size of 4K, which should be a suitable compromise with still achieving some compression while being able to uncompressed even by the smallest devices.

Besides the small compression dictionary size, MicroPython distribution packages also have other optimizations, like removing any files from the archive which aren't used by the installation process. In particular, upip package manager doesn't execute setup.py during installation (see below), and thus that file is not included in the archive.

At the same time, these optimizations make MicroPython distribution packages not compatible with CPython's package manager, pip. This isn't considered a big problem, because:

  1. Packages can be installed with upip, and then can be used with CPython (if they are compatible with it).
  2. In the other direction, majority of CPython packages would be incompatible with MicroPython by various reasons, first of all, the reliance on features not implemented by MicroPython.

Summing up, the MicroPython distribution package archives are highly optimized for MicroPython's target environments, which are highly resource constrained devices.

upip package manager

MicroPython distribution packages are intended to be installed using the upip package manager. upip is a Python application which is usually distributed (as frozen bytecode) with network-enabled MicroPython ports. At the very least, upip is available in the MicroPython Unix port.

On any MicroPython port providing upip, it can be accessed as following:

import upip
upip.help()
upip.install(package_or_package_list, [path])

Where package_or_package_list is the name of a distribution package to install, or a list of such names to install multiple packages. Optional path parameter specifies filesystem location to install under and defaults to the standard library location (see below).

An example of installing a specific package and then using it:

>>> import upip
>>> upip.install("micropython-pystone_lowmem")
[...]
>>> import pystone_lowmem
>>> pystone_lowmem.main()

Note that the name of Python package and the name of distribution package for it in general don't have to match, and oftentimes they don't. This is because PyPI provides a central package repository for all different Python implementations and versions, and thus distribution package names may need to be namespaced for a particular implementation. For example, all packages from micropython-lib follow this naming convention: for a Python module or package named foo, the distribution package name is micropython-foo.

For the ports which run MicroPython executable from the OS command prompts (like the Unix port), upip can be (and indeed, usually is) run from the command line instead of MicroPython's own REPL. The commands which corresponds to the example above are:

micropython -m upip -h
micropython -m upip install [-p <path>] <packages>...
micropython -m upip install micropython-pystone_lowmem

[TODO: Describe installation path.]

Cross-installing packages

For MicroPython ports without native networking capabilities, the recommend process is "cross-installing" them into a "directory image" using the MicroPython Unix port, and then transferring this image to a device by suitable means.

Installing to a directory image involves using -p switch to upip:

micropython -m upip install -p install_dir micropython-pystone_lowmem

After this command, the package content (and contents of every depenency packages) will be available in the install_dir/ subdirectory. You would need to transfer contents of this directory (without the install_dir/ prefix) to the device, at the suitable location, where it can be found by the Python import statement (see discussion of the upip installation path above).

Cross-installing packages with freezing

For the low-memory MicroPython ports, the process described in the previous section does not provide the most efficient resource usage,because the packages are installed in the source form, so need to be compiled to the bytecome on each import. This compilation requires RAM, and the resulting bytecode is also stored in RAM, reducing its amount available for storing application data. Moreover, the process above requires presence of the filesystem on a device, and the most resource-constrained devices may not even have it.

The bytecode freezing is a process which resolves all the issues mentioned above:

  • The source code is pre-compiled into bytecode and store as such.
  • The bytecode is stored in ROM, not RAM.
  • Filesystem is not required for frozen packages.

Using frozen bytecode requires building the executable (firmware) for a given MicroPython port from the C source code. Consequently, the process is:

  1. Follow the instructions for a particular port on setting up a toolchain and building the port. For example, for ESP8266 port, study instructions in ports/esp8266/README.md and follow them. Make sure you can build the port and deploy the resulting executable/firmware successfully before proceeding to the next steps.
  2. Build MicroPython Unix port and make sure it is in your PATH and you can execute micropython.
  3. Change to port's directory (e.g. ports/esp8266/ for ESP8266).
  4. Run make clean-frozen. This step cleans up any previous modules which were installed for freezing (consequently, you need to skip this step to add additional modules, instead of starting from scratch).
  5. Run micropython -m upip install -p modules <packages>... to install packages you want to freeze.
  6. Run make clean.
  7. Run make.

After this, you should have the executable/firmware with modules as the bytecode inside, which you can deploy the usual way.

Few notes:

  1. Step 5 in the sequence above assumes that the distribution package is available from PyPI. If that is not the case, you would need to copy Python source files manually to modules/ subdirectory of the port port directory. (Note that upip does not support installing from e.g. version control repositories).
  2. The firmware for baremetal devices usually has size restrictions, so adding too many frozen modules may overflow it. Usually, you would get a linking error if this happens. However, in some cases, an image may be produced, which is not runnable on a device. Such cases are in general bugs, and should be reported and further investigated. If you face such a situation, as an initial step, you may want to decrease the amount of frozen modules included.

Creating distribution packages

Distribution packages for MicroPython are created in the same manner as for CPython or any other Python implementation, see references at the end of chapter. Setuptools (instead of distutils) should be used, because distutils do not support dependencies and other features. "Source distribution" (sdist) format is used for packaging. The post-processing discussed above, (and pre-processing discussed in the following section) is achieved by using custom sdist command for setuptools. Thus, packaging steps remain the same as for the standard setuptools, the user just needs to override sdist command implementation by passing the appropriate argument to setup() call:

from setuptools import setup
import sdist_upip

setup(
    ...,
    cmdclass={'sdist': sdist_upip.sdist}
)

The sdist_upip.py module as referenced above can be found in micropython-lib: https://github.com/micropython/micropython-lib/blob/master/sdist_upip.py

Application resources

A complete application, besides the source code, oftentimes also consists of data files, e.g. web page templates, game images, etc. It's clear how to deal with those when application is installed manually - you just put those data files in the filesystem at some location and use the normal file access functions.

The situation is different when deploying applications from packages - this is more advanced, streamlined and flexible way, but also requires more advanced approach to accessing data files. This approach is treating the data files as "resources", and abstracting away access to them.

Python supports resource access using its "setuptools" library, using pkg_resources module. MicroPython, following its usual approach, implements subset of the functionality of that module, specifically pkg_resources.resource_stream(package, resource) function. The idea is that an application calls this function, passing a resource identifier, which is a relative path to data file within the specified package (usually top-level application package). It returns a stream object which can be used to access resource contents. Thus, the resource_stream() emulates interface of the standard open() function.

Implementation-wise, resource_stream() uses file operations underlyingly, if distribution package is install in the filesystem. However, it also supports functioning without the underlying filesystem, e.g. if the package is frozen as the bytecode. This however requires an extra intermediate step when packaging application - creation of "Python resource module".

The idea of this module is to convert binary data to a Python bytes object, and put it into the dictionary, indexed by the resource name. This conversion is done automatically using overridden sdist command described in the previous section.

Let's trace the complete process using the following example. Suppose your application has the following structure:

my_app/
    __main__.py
    utils.py
    data/
        page.html
        image.png

__main__.py and utils.py should access resources using the following calls:

import pkg_resources

pkg_resources.resource_stream(__name__, "data/page.html")
pkg_resources.resource_stream(__name__, "data/image.png")

You can develop and debug using the MicroPython Unix port as usual. When time comes to make a distribution package out of it, just use overridden "sdist" command from sdist_upip.py module as described in the previous section.

This will create a Python resource module named R.py, based on the files declared in MANIFEST or MANIFEST.in files (any non-.py file will be considered a resource and added to R.py) - before proceeding with the normal packaging steps.

Prepared like this, your application will work both when deployed to filesystem and as frozen bytecode.

If you would like to debug R.py creation, you can run:

python3 setup.py sdist --manifest-only

Alternatively, you can use tools/mpy_bin2res.py script from the MicroPython distribution, in which can you will need to pass paths to all resource files:

mpy_bin2res.py data/page.html data/image.png

References

Inline Assembler for Thumb2 architectures

This document assumes some familiarity with assembly language programming and should be read after studying the tutorial. For a detailed description of the instruction set consult the Architecture Reference Manual detailed below. The inline assembler supports a subset of the ARM Thumb-2 instruction set described here. The syntax tries to be as close as possible to that defined in the above ARM manual, converted to Python function calls.

Instructions operate on 32 bit signed integer data except where stated otherwise. Most supported instructions operate on registers R0-R7 only: where R8-R15 are supported this is stated. Registers R8-R12 must be restored to their initial value before return from a function. Registers R13-R15 constitute the Link Register, Stack Pointer and Program Counter respectively.

Document conventions

Where possible the behaviour of each instruction is described in Python, for example

  • add(Rd, Rn, Rm) Rd = Rn + Rm

This enables the effect of instructions to be demonstrated in Python. In certain case this is impossible because Python doesn't support concepts such as indirection. The pseudocode employed in such cases is described on the relevant page.

Instruction Categories

The following sections details the subset of the ARM Thumb-2 instruction set supported by MicroPython.

Register move instructions
Document conventions

Notation: Rd, Rn denote ARM registers R0-R15. immN denotes an immediate value having a width of N bits. These instructions affect the condition flags.

Register moves

Where immediate values are used, these are zero-extended to 32 bits. Thus mov(R0, 0xff) will set R0 to 255.

  • mov(Rd, imm8) Rd = imm8
  • mov(Rd, Rn) Rd = Rn
  • movw(Rd, imm16) Rd = imm16
  • movt(Rd, imm16) Rd = (Rd & 0xffff) | (imm16 << 16)

movt writes an immediate value to the top halfword of the destination register. It does not affect the contents of the bottom halfword.

  • movwt(Rd, imm32) Rd = imm32

movwt is a pseudo-instruction: the MicroPython assembler emits a movw followed by a movt to move a 32-bit value into Rd.

Load register from memory
Document conventions

Notation: Rt, Rn denote ARM registers R0-R7 except where stated. immN represents an immediate value having a width of N bits hence imm5 is constrained to the range 0-31. [Rn + immN] is the contents of the memory address obtained by adding Rn and the offset immN. Offsets are measured in bytes. These instructions affect the condition flags.

Register Load
  • ldr(Rt, [Rn, imm7]) Rt = [Rn + imm7] Load a 32 bit word
  • ldrb(Rt, [Rn, imm5]) Rt = [Rn + imm5] Load a byte
  • ldrh(Rt, [Rn, imm6]) Rt = [Rn + imm6] Load a 16 bit half word

Where a byte or half word is loaded, it is zero-extended to 32 bits.

The specified immediate offsets are measured in bytes. Hence in the case of ldr the 7 bit value enables 32 bit word aligned values to be accessed with a maximum offset of 31 words. In the case of ldrh the 6 bit value enables 16 bit half-word aligned values to be accessed with a maximum offset of 31 half-words.

Store register to memory
Document conventions

Notation: Rt, Rn denote ARM registers R0-R7 except where stated. immN represents an immediate value having a width of N bits hence imm5 is constrained to the range 0-31. [Rn + imm5] is the contents of the memory address obtained by adding Rn and the offset imm5. Offsets are measured in bytes. These instructions do not affect the condition flags.

Register Store
  • str(Rt, [Rn, imm7]) [Rn + imm7] = Rt Store a 32 bit word
  • strb(Rt, [Rn, imm5]) [Rn + imm5] = Rt Store a byte (b0-b7)
  • strh(Rt, [Rn, imm6]) [Rn + imm6] = Rt Store a 16 bit half word (b0-b15)

The specified immediate offsets are measured in bytes. Hence in the case of str the 7 bit value enables 32 bit word aligned values to be accessed with a maximum offset of 31 words. In the case of strh the 6 bit value enables 16 bit half-word aligned values to be accessed with a maximum offset of 31 half-words.

Logical & Bitwise instructions
Document conventions

Notation: Rd, Rn denote ARM registers R0-R7 except in the case of the special instructions where R0-R15 may be used. Rn<a-b> denotes an ARM register whose contents must lie in range a <= contents <= b. In the case of instructions with two register arguments, it is permissible for them to be identical. For example the following will zero R0 (Python R0 ^= R0) regardless of its initial contents.

  • eor(r0, r0)

These instructions affect the condition flags except where stated.

Logical instructions
  • and_(Rd, Rn) Rd &= Rn
  • orr(Rd, Rn) Rd |= Rn
  • eor(Rd, Rn) Rd ^= Rn
  • mvn(Rd, Rn) Rd = Rn ^ 0xffffffff i.e. Rd = 1's complement of Rn
  • bic(Rd, Rn) Rd &= ~Rn bit clear Rd using mask in Rn

Note the use of "and_" instead of "and", because "and" is a reserved keyword in Python.

Shift and rotation instructions
  • lsl(Rd, Rn<0-31>) Rd <<= Rn
  • lsr(Rd, Rn<1-32>) Rd = (Rd & 0xffffffff) >> Rn Logical shift right
  • asr(Rd, Rn<1-32>) Rd >>= Rn arithmetic shift right
  • ror(Rd, Rn<1-31>) Rd = rotate_right(Rd, Rn) Rd is rotated right Rn bits.

A rotation by (for example) three bits works as follows. If Rd initially contains bits b31 b30..b0 after rotation it will contain b2 b1 b0 b31 b30..b3

Special instructions

Condition codes are unaffected by these instructions.

  • clz(Rd, Rn) Rd = count_leading_zeros(Rn)

count_leading_zeros(Rn) returns the number of binary zero bits before the first binary one bit in Rn.

  • rbit(Rd, Rn) Rd = bit_reverse(Rn)

bit_reverse(Rn) returns the bit-reversed contents of Rn. If Rn contains bits b31 b30..b0 Rd will be set to b0 b1 b2..b31

Trailing zeros may be counted by performing a bit reverse prior to executing clz.

Arithmetic instructions
Document conventions

Notation: Rd, Rm, Rn denote ARM registers R0-R7. immN denotes an immediate value having a width of N bits e.g. imm8, imm3. carry denotes the carry condition flag, not(carry) denotes its complement. In the case of instructions with more than one register argument, it is permissible for some to be identical. For example the following will add the contents of R0 to itself, placing the result in R0:

  • add(r0, r0, r0)

Arithmetic instructions affect the condition flags except where stated.

Addition
  • add(Rdn, imm8) Rdn = Rdn + imm8
  • add(Rd, Rn, imm3) Rd = Rn + imm3
  • add(Rd, Rn, Rm) Rd = Rn +Rm
  • adc(Rd, Rn) Rd = Rd + Rn + carry
Subtraction
  • sub(Rdn, imm8) Rdn = Rdn - imm8
  • sub(Rd, Rn, imm3) Rd = Rn - imm3
  • sub(Rd, Rn, Rm) Rd = Rn - Rm
  • sbc(Rd, Rn) Rd = Rd - Rn - not(carry)
Negation
  • neg(Rd, Rn) Rd = -Rn
Multiplication and division
  • mul(Rd, Rn) Rd = Rd * Rn

This produces a 32 bit result with overflow lost. The result may be treated as signed or unsigned according to the definition of the operands.

  • sdiv(Rd, Rn, Rm) Rd = Rn / Rm
  • udiv(Rd, Rn, Rm) Rd = Rn / Rm

These functions perform signed and unsigned division respectively. Condition flags are not affected.

Comparison instructions

These perform an arithmetic or logical instruction on two arguments, discarding the result but setting the condition flags. Typically these are used to test data values without changing them prior to executing a conditional branch.

Document conventions

Notation: Rd, Rm, Rn denote ARM registers R0-R7. imm8 denotes an immediate value having a width of 8 bits.

The Application Program Status Register (APSR)

This contains four bits which are tested by the conditional branch instructions. Typically a conditional branch will test multiple bits, for example bge(LABEL). The meaning of condition codes can depend on whether the operands of an arithmetic instruction are viewed as signed or unsigned integers. Thus bhi(LABEL) assumes unsigned numbers were processed while bgt(LABEL) assumes signed operands.

APSR Bits
  • Z (zero)

This is set if the result of an operation is zero or the operands of a comparison are equal.

  • N (negative)

Set if the result is negative.

  • C (carry)

An addition sets the carry flag when the result overflows out of the MSB, for example adding 0x80000000 and 0x80000000. By the nature of two's complement arithmetic this behaviour is reversed on subtraction, with a borrow indicated by the carry bit being clear. Thus 0x10 - 0x01 is executed as 0x10 + 0xffffffff which will set the carry bit.

  • V (overflow)

The overflow flag is set if the result, viewed as a two's compliment number, has the "wrong" sign in relation to the operands. For example adding 1 to 0x7fffffff will set the overflow bit because the result (0x8000000), viewed as a two's complement integer, is negative. Note that in this instance the carry bit is not set.

Comparison instructions

These set the APSR (Application Program Status Register) N (negative), Z (zero), C (carry) and V (overflow) flags.

  • cmp(Rn, imm8) Rn - imm8
  • cmp(Rn, Rm) Rn - Rm
  • cmn(Rn, Rm) Rn + Rm
  • tst(Rn, Rm) Rn & Rm
Conditional execution

The it and ite instructions provide a means of conditionally executing from one to four subsequent instructions without the need for a label.

  • it(<condition>) If then

Execute the next instruction if <condition> is true:

cmp(r0, r1)
it(eq)
mov(r0, 100) # runs if r0 == r1
# execution continues here
  • ite(<condition>) If then else

If <condtion> is true, execute the next instruction, otherwise execute the subsequent one. Thus:

cmp(r0, r1)
ite(eq)
mov(r0, 100) # runs if r0 == r1
mov(r0, 200) # runs if r0 != r1
# execution continues here

This may be extended to control the execution of upto four subsequent instructions: it[x[y[z]]] where x,y,z=t/e; e.g. itt, itee, itete, ittte, itttt, iteee, etc.

Branch instructions

These cause execution to jump to a target location usually specified by a label (see the label assembler directive). Conditional branches and the it and ite instructions test the Application Program Status Register (APSR) N (negative), Z (zero), C (carry) and V (overflow) flags to determine whether the branch should be executed.

Most of the exposed assembler instructions (including move operations) set the flags but there are explicit comparison instructions to enable values to be tested.

Further detail on the meaning of the condition flags is provided in the section describing comparison functions.

Document conventions

Notation: Rm denotes ARM registers R0-R15. LABEL denotes a label defined with the label() assembler directive. <condition> indicates one of the following condition specifiers:

  • eq Equal to (result was zero)
  • ne Not equal
  • cs Carry set
  • cc Carry clear
  • mi Minus (negative)
  • pl Plus (positive)
  • vs Overflow set
  • vc Overflow clear
  • hi > (unsigned comparison)
  • ls <= (unsigned comparison)
  • ge >= (signed comparison)
  • lt < (signed comparison)
  • gt > (signed comparison)
  • le <= (signed comparison)
Branch to label
  • b(LABEL) Unconditional branch
  • beq(LABEL) branch if equal
  • bne(LABEL) branch if not equal
  • bge(LABEL) branch if greater than or equal
  • bgt(LABEL) branch if greater than
  • blt(LABEL) branch if less than (<) (signed)
  • ble(LABEL) branch if less than or equal to (<=) (signed)
  • bcs(LABEL) branch if carry flag is set
  • bcc(LABEL) branch if carry flag is clear
  • bmi(LABEL) branch if negative
  • bpl(LABEL) branch if positive
  • bvs(LABEL) branch if overflow flag set
  • bvc(LABEL) branch if overflow flag is clear
  • bhi(LABEL) branch if higher (unsigned)
  • bls(LABEL) branch if lower or equal (unsigned)
Long branches

The code produced by the branch instructions listed above uses a fixed bit width to specify the branch destination, which is PC relative. Consequently in long programs where the branch instruction is remote from its destination the assembler will produce a "branch not in range" error. This can be overcome with the "wide" variants such as

  • beq_w(LABEL) long branch if equal

Wide branches use 4 bytes to encode the instruction (compared with 2 bytes for standard branch instructions).

Subroutines (functions)

When entering a subroutine the processor stores the return address in register r14, also known as the link register (lr). Return to the instruction after the subroutine call is performed by updating the program counter (r15 or pc) from the link register, This process is handled by the following instructions.

  • bl(LABEL)

Transfer execution to the instruction after LABEL storing the return address in the link register (r14).

  • bx(Rm) Branch to address specified by Rm.

Typically bx(lr) is issued to return from a subroutine. For nested subroutines the link register of outer scopes must be saved (usually on the stack) before performing inner subroutine calls.

Stack push and pop
Document conventions

The push() and pop() instructions accept as their argument a register set containing a subset, or possibly all, of the general-purpose registers R0-R12 and the link register (lr or R14). As with any Python set the order in which the registers are specified is immaterial. Thus the in the following example the pop() instruction would restore R1, R7 and R8 to their contents prior to the push():

  • push({r1, r8, r7}) Save three registers on the stack.
  • pop({r7, r1, r8}) Restore them
Stack operations
  • push({regset}) Push a set of registers onto the stack
  • pop({regset}) Restore a set of registers from the stack
Miscellaneous instructions
  • nop() pass no operation.
  • wfi() Suspend execution in a low power state until an interrupt occurs.
  • cpsid(flags) set the Priority Mask Register - disable interrupts.
  • cpsie(flags) clear the Priority Mask Register - enable interrupts.
  • mrs(Rd, special_reg) Rd = special_reg copy a special register to a general register. The special register may be IPSR (Interrupt Status Register) or BASEPRI (Base Priority Register). The IPSR provides a means of determining the exception number of an interrupt being processed. It contains zero if no interrupt is being processed.

Currently the cpsie() and cpsid() functions are partially implemented. They require but ignore the flags argument and serve as a means of enabling and disabling interrupts.

Floating Point instructions

These instructions support the use of the ARM floating point coprocessor (on platforms such as the Pyboard which are equipped with one). The FPU has 32 registers known as s0-s31 each of which can hold a single precision float. Data can be passed between the FPU registers and the ARM core registers with the vmov instruction.

Note that MicroPython doesn't support passing floats to assembler functions, nor can you put a float into r0 and expect a reasonable result. There are two ways to overcome this. The first is to use arrays, and the second is to pass and/or return integers and convert to and from floats in code.

Document conventions

Notation: Sd, Sm, Sn denote FPU registers, Rd, Rm, Rn denote ARM core registers. The latter can be any ARM core register although registers R13-R15 are unlikely to be appropriate in this context.

Arithmetic
  • vadd(Sd, Sn, Sm) Sd = Sn + Sm
  • vsub(Sd, Sn, Sm) Sd = Sn - Sm
  • vneg(Sd, Sm) Sd = -Sm
  • vmul(Sd, Sn, Sm) Sd = Sn * Sm
  • vdiv(Sd, Sn, Sm) Sd = Sn / Sm
  • vsqrt(Sd, Sm) Sd = sqrt(Sm)

Registers may be identical: vmul(S0, S0, S0) will execute S0 = S0*S0

Move between ARM core and FPU registers
  • vmov(Sd, Rm) Sd = Rm
  • vmov(Rd, Sm) Rd = Sm

The FPU has a register known as FPSCR, similar to the ARM core's APSR, which stores condition codes plus other data. The following instructions provide access to this.

  • vmrs(APSR_nzcv, FPSCR)

Move the floating-point N, Z, C, and V flags to the APSR N, Z, C, and V flags.

This is done after an instruction such as an FPU comparison to enable the condition codes to be tested by the assembler code. The following is a more general form of the instruction.

  • vmrs(Rd, FPSCR) Rd = FPSCR
Move between FPU register and memory
  • vldr(Sd, [Rn, offset]) Sd = [Rn + offset]
  • vstr(Sd, [Rn, offset]) [Rn + offset] = Sd

Where [Rn + offset] denotes the memory address obtained by adding Rn to the offset. This is specified in bytes. Since each float value occupies a 32 bit word, when accessing arrays of floats the offset must always be a multiple of four bytes.

Data Comparison
  • vcmp(Sd, Sm)

Compare the values in Sd and Sm and set the FPU N, Z, C, and V flags. This would normally be followed by vmrs(APSR_nzcv, FPSCR) to enable the results to be tested.

Convert between integer and float
  • vcvt_f32_s32(Sd, Sm) Sd = float(Sm)
  • vcvt_s32_f32(Sd, Sm) Sd = int(Sm)
Assembler Directives
Labels
  • label(INNER1)

This defines a label for use in a branch instruction. Thus elsewhere in the code a b(INNER1) will cause execution to continue with the instruction after the label directive.

Defining inline data

The following assembler directives facilitate embedding data in an assembler code block.

  • data(size, d0, d1 .. dn)

The data directive creates n array of data values in memory. The first argument specifies the size in bytes of the subsequent arguments. Hence the first statement below will cause the assembler to put three bytes (with values 2, 3 and 4) into consecutive memory locations while the second will cause it to emit two four byte words.

data(1, 2, 3, 4)
data(4, 2, 100000)

Data values longer than a single byte are stored in memory in little-endian format.

  • align(nBytes)

Align the following instruction to an nBytes value. ARM Thumb-2 instructions must be two byte aligned, hence it's advisable to issue align(2) after data directives and prior to any subsequent code. This ensures that the code will run irrespective of the size of the data array.

Usage examples

These sections provide further code examples and hints on the use of the assembler.

Hints and tips

The following are some examples of the use of the inline assembler and some information on how to work around its limitations. In this document the term "assembler function" refers to a function declared in Python with the @micropython.asm_thumb decorator, whereas "subroutine" refers to assembler code called from within an assembler function.

Code branches and subroutines

It is important to appreciate that labels are local to an assembler function. There is currently no way for a subroutine defined in one function to be called from another.

To call a subroutine the instruction bl(LABEL) is issued. This transfers control to the instruction following the label(LABEL) directive and stores the return address in the link register (lr or r14). To return the instruction bx(lr) is issued which causes execution to continue with the instruction following the subroutine call. This mechanism implies that, if a subroutine is to call another, it must save the link register prior to the call and restore it before terminating.

The following rather contrived example illustrates a function call. Note that it's necessary at the start to branch around all subroutine calls: subroutines end execution with bx(lr) while the outer function simply "drops off the end" in the style of Python functions.

@micropython.asm_thumb
def quad(r0):
    b(START)
    label(DOUBLE)
    add(r0, r0, r0)
    bx(lr)
    label(START)
    bl(DOUBLE)
    bl(DOUBLE)

print(quad(10))

The following code example demonstrates a nested (recursive) call: the classic Fibonacci sequence. Here, prior to a recursive call, the link register is saved along with other registers which the program logic requires to be preserved.

@micropython.asm_thumb
def fib(r0):
    b(START)
    label(DOFIB)
    push({r1, r2, lr})
    cmp(r0, 1)
    ble(FIBDONE)
    sub(r0, 1)
    mov(r2, r0) # r2 = n -1
    bl(DOFIB)
    mov(r1, r0) # r1 = fib(n -1)
    sub(r0, r2, 1)
    bl(DOFIB)   # r0 = fib(n -2)
    add(r0, r0, r1)
    label(FIBDONE)
    pop({r1, r2, lr})
    bx(lr)
    label(START)
    bl(DOFIB)

for n in range(10):
    print(fib(n))
Argument passing and return

The tutorial details the fact that assembler functions can support from zero to three arguments, which must (if used) be named r0, r1 and r2. When the code executes the registers will be initialised to those values.

The data types which can be passed in this way are integers and memory addresses. With current firmware all possible 32 bit values may be passed and returned. If the return value may have the most significant bit set a Python type hint should be employed to enable MicroPython to determine whether the value should be interpreted as a signed or unsigned integer: types are int or uint.

@micropython.asm_thumb
def uadd(r0, r1) -> uint:
    add(r0, r0, r1)

hex(uadd(0x40000000,0x40000000)) will return 0x80000000, demonstrating the passing and return of integers where bits 30 and 31 differ.

The limitations on the number of arguments and return values can be overcome by means of the array module which enables any number of values of any type to be accessed.

Multiple arguments

If a Python array of integers is passed as an argument to an assembler function, the function will receive the address of a contiguous set of integers. Thus multiple arguments can be passed as elements of a single array. Similarly a function can return multiple values by assigning them to array elements. Assembler functions have no means of determining the length of an array: this will need to be passed to the function.

This use of arrays can be extended to enable more than three arrays to be used. This is done using indirection: the uctypes module supports addressof() which will return the address of an array passed as its argument. Thus you can populate an integer array with the addresses of other arrays:

from uctypes import addressof
@micropython.asm_thumb
def getindirect(r0):
    ldr(r0, [r0, 0]) # Address of array loaded from passed array
    ldr(r0, [r0, 4]) # Return element 1 of indirect array (24)

def testindirect():
    a = array.array('i',[23, 24])
    b = array.array('i',[0,0])
    b[0] = addressof(a)
    print(getindirect(b))
Non-integer data types

These may be handled by means of arrays of the appropriate data type. For example, single precision floating point data may be processed as follows. This code example takes an array of floats and replaces its contents with their squares.

from array import array

@micropython.asm_thumb
def square(r0, r1):
    label(LOOP)
    vldr(s0, [r0, 0])
    vmul(s0, s0, s0)
    vstr(s0, [r0, 0])
    add(r0, 4)
    sub(r1, 1)
    bgt(LOOP)

a = array('f', (x for x in range(10)))
square(a, len(a))
print(a)

The uctypes module supports the use of data structures beyond simple arrays. It enables a Python data structure to be mapped onto a bytearray instance which may then be passed to the assembler function.

Named constants

Assembler code may be made more readable and maintainable by using named constants rather than littering code with numbers. This may be achieved thus:

MYDATA = const(33)

@micropython.asm_thumb
def foo():
    mov(r0, MYDATA)

The const() construct causes MicroPython to replace the variable name with its value at compile time. If constants are declared in an outer Python scope they can be shared between multiple assembler functions and with Python code.

Assembler code as class methods

MicroPython passes the address of the object instance as the first argument to class methods. This is normally of little use to an assembler function. It can be avoided by declaring the function as a static method thus:

class foo:
  @staticmethod
  @micropython.asm_thumb
  def bar(r0):
    add(r0, r0, r0)
Use of unsupported instructions

These can be coded using the data statement as shown below. While push() and pop() are supported the example below illustrates the principle. The necessary machine code may be found in the ARM v7-M Architecture Reference Manual. Note that the first argument of data calls such as

data(2, 0xe92d, 0x0f00) # push r8,r9,r10,r11

indicates that each subsequent argument is a two byte quantity.

Overcoming MicroPython's integer restriction

The Pyboard chip includes a CRC generator. Its use presents a problem in MicroPython because the returned values cover the full gamut of 32 bit quantities whereas small integers in MicroPython cannot have differing values in bits 30 and 31. This limitation is overcome with the following code, which uses assembler to put the result into an array and Python code to coerce the result into an arbitrary precision unsigned integer.

from array import array
import stm

def enable_crc():
    stm.mem32[stm.RCC + stm.RCC_AHB1ENR] |= 0x1000

def reset_crc():
    stm.mem32[stm.CRC+stm.CRC_CR] = 1

@micropython.asm_thumb
def getval(r0, r1):
    movwt(r3, stm.CRC + stm.CRC_DR)
    str(r1, [r3, 0])
    ldr(r2, [r3, 0])
    str(r2, [r0, 0])

def getcrc(value):
    a = array('i', [0])
    getval(a, value)
    return a[0] & 0xffffffff # coerce to arbitrary precision

enable_crc()
reset_crc()
for x in range(20):
    print(hex(getcrc(0)))

References

microPython 和 python 的差异

microPython 与标准 python 相比不一致的地方

Syntax

Generated Sun 07 Oct 2018 06:47:55 UTC

Spaces

uPy requires spaces between literal numbers and keywords, CPy doesn't

Sample code:

try:
    print(eval('1and 0'))
except SyntaxError:
    print('Should have worked')
try:
    print(eval('1or 0'))
except SyntaxError:
    print('Should have worked')
try:
    print(eval('1if 1else 0'))
except SyntaxError:
    print('Should have worked')
CPy output: uPy output:
0
1
1
/bin/sh: ../ports/unix/micropython: No such file or directory

Unicode

Unicode name escapes are not implemented

Sample code:

print("\N{LATIN SMALL LETTER A}")
CPy output: uPy output:
a
/bin/sh: ../ports/unix/micropython: No such file or directory

Core Language

Generated Sun 07 Oct 2018 06:47:55 UTC

Classes

Special method __del__ not implemented for user-defined classes

Sample code:

import gc

class Foo():
    def __del__(self):
        print('__del__')

f = Foo()
del f

gc.collect()
CPy output: uPy output:
__del__
/bin/sh: ../ports/unix/micropython: No such file or directory
Method Resolution Order (MRO) is not compliant with CPython

Cause: Depth first non-exhaustive method resolution order

Workaround: Avoid complex class hierarchies with multiple inheritance and complex method overrides. Keep in mind that many languages don't support multiple inheritance at all.

Sample code:

class Foo:
    def __str__(self):
        return "Foo"

class C(tuple, Foo):
    pass

t = C((1, 2, 3))
print(t)
CPy output: uPy output:
Foo
/bin/sh: ../ports/unix/micropython: No such file or directory
When inheriting from multiple classes super() only calls one class

Cause: See Method Resolution Order (MRO) is not compliant with CPython

Workaround: See Method Resolution Order (MRO) is not compliant with CPython

Sample code:

class A:
    def __init__(self):
        print("A.__init__")

class B(A):
    def __init__(self):
        print("B.__init__")
        super().__init__()

class C(A):
    def __init__(self):
        print("C.__init__")
        super().__init__()


class D(B,C):
    def __init__(self):
        print("D.__init__")
        super().__init__()

D()
CPy output: uPy output:
D.__init__
B.__init__
C.__init__
A.__init__
/bin/sh: ../ports/unix/micropython: No such file or directory
Calling super() getter property in subclass will return a property object, not the value

Sample code:

class A:
    @property
    def p(self):
        return {"a":10}

class AA(A):
    @property
    def p(self):
        return super().p

a = AA()
print(a.p)
CPy output: uPy output:
{'a': 10}
/bin/sh: ../ports/unix/micropython: No such file or directory

Functions

Error messages for methods may display unexpected argument counts

Cause: MicroPython counts "self" as an argument.

Workaround: Interpret error messages with the information above in mind.

Sample code:

try:
    [].append()
except Exception as e:
    print(e)
CPy output: uPy output:
append() takes exactly one argument (0 given)
/bin/sh: ../ports/unix/micropython: No such file or directory
User-defined attributes for functions are not supported

Cause: MicroPython is highly optimized for memory usage.

Workaround: Use external dictionary, e.g. FUNC_X[f] = 0.

Sample code:

def f():
    pass

f.x = 0
print(f.x)
CPy output: uPy output:
0
/bin/sh: ../ports/unix/micropython: No such file or directory

Generator

Context manager __exit__() not called in a generator which does not run to completion

Sample code:

class foo(object):
    def __enter__(self):
        print('Enter')
    def __exit__(self, *args):
        print('Exit')

def bar(x):
    with foo():
        while True:
            x += 1
            yield x

def func():
    g = bar(0)
    for _ in range(3):
        print(next(g))

func()
CPy output: uPy output:
Enter
1
2
3
Exit
/bin/sh: ../ports/unix/micropython: No such file or directory

Runtime

Local variables aren't included in locals() result

Cause: MicroPython doesn't maintain symbolic local environment, it is optimized to an array of slots. Thus, local variables can't be accessed by a name.

Sample code:

def test():
    val = 2
    print(locals())

test()
CPy output: uPy output:
{'val': 2}
/bin/sh: ../ports/unix/micropython: No such file or directory
Code running in eval() function doesn't have access to local variables

Cause: MicroPython doesn't maintain symbolic local environment, it is optimized to an array of slots. Thus, local variables can't be accessed by a name. Effectively, eval(expr) in MicroPython is equivalent to eval(expr, globals(), globals()).

Sample code:

val = 1

def test():
    val = 2
    print(val)
    eval("print(val)")

test()
CPy output: uPy output:
2
2
/bin/sh: ../ports/unix/micropython: No such file or directory

import

__path__ attribute of a package has a different type (single string instead of list of strings) in MicroPython

Cause: MicroPython does't support namespace packages split across filesystem. Beyond that, MicroPython's import system is highly optimized for minimal memory usage.

Workaround: Details of import handling is inherently implementation dependent. Don't rely on such details in portable applications.

Sample code:

import modules

print(modules.__path__)
CPy output: uPy output:
['/Users/yanminge/project/micropython-api-doc/tests/cpydiff/modules']
/bin/sh: ../ports/unix/micropython: No such file or directory
Failed to load modules are still registered as loaded

Cause: To make module handling more efficient, it's not wrapped with exception handling.

Workaround: Test modules before production use; during development, use del sys.modules["name"], or just soft or hard reset the board.

Sample code:

import sys

try:
    from modules import foo
except NameError as e:
    print(e)
try:
    from modules import foo
    print('Should not get here')
except NameError as e:
    print(e)
CPy output: uPy output:
foo
name 'xxx' is not defined
foo
name 'xxx' is not defined
/bin/sh: ../ports/unix/micropython: No such file or directory
MicroPython does't support namespace packages split across filesystem.

Cause: MicroPython's import system is highly optimized for simplicity, minimal memory usage, and minimal filesystem search overhead.

Workaround: Don't install modules belonging to the same namespace package in different directories. For MicroPython, it's recommended to have at most 3-component module search paths: for your current application, per-user (writable), system-wide (non-writable).

Sample code:

import sys
sys.path.append(sys.path[1] + "/modules")
sys.path.append(sys.path[1] + "/modules2")

import subpkg.foo
import subpkg.bar

print("Two modules of a split namespace package imported")
CPy output: uPy output:
Two modules of a split namespace package imported
/bin/sh: ../ports/unix/micropython: No such file or directory

Builtin Types

Generated Sun 07 Oct 2018 06:47:55 UTC

Exception

Exception chaining not implemented

Sample code:

try:
    raise TypeError
except TypeError:
    raise ValueError
CPy output: uPy output:
Traceback (most recent call last):
  File "<stdin>", line 8, in <module>
TypeError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 10, in <module>
ValueError
/bin/sh: ../ports/unix/micropython: No such file or directory
User-defined attributes for builtin exceptions are not supported

Cause: MicroPython is highly optimized for memory usage.

Workaround: Use user-defined exception subclasses.

Sample code:

e = Exception()
e.x = 0
print(e.x)
CPy output: uPy output:
0
/bin/sh: ../ports/unix/micropython: No such file or directory
Exception in while loop condition may have unexpected line number

Cause: Condition checks are optimized to happen at the end of loop body, and that line number is reported.

Sample code:

l = ["-foo", "-bar"]

i = 0
while l[i][0] == "-":
    print("iter")
    i += 1
CPy output: uPy output:
iter
iter
Traceback (most recent call last):
  File "<stdin>", line 10, in <module>
IndexError: list index out of range
/bin/sh: ../ports/unix/micropython: No such file or directory
Exception.__init__ method does not exist.

Cause: Subclassing native classes is not fully supported in MicroPython.

Workaround: Call using super() instead:

class A(Exception):
    def __init__(self):
        super().__init__()

Sample code:

class A(Exception):
    def __init__(self):
        Exception.__init__(self)

a = A()
CPy output: uPy output:
 
/bin/sh: ../ports/unix/micropython: No such file or directory

bytearray

Array slice assignment with unsupported RHS

Sample code:

b = bytearray(4)
b[0:1] = [1, 2]
print(b)
CPy output: uPy output:
bytearray(b'\x01\x02\x00\x00\x00')
/bin/sh: ../ports/unix/micropython: No such file or directory

bytes

bytes objects support .format() method

Cause: MicroPython strives to be a more regular implementation, so if both str and bytes support __mod__() (the % operator), it makes sense to support format() for both too. Support for __mod__ can also be compiled out, which leaves only format() for bytes formatting.

Workaround: If you are interested in CPython compatibility, don't use .format() on bytes objects.

Sample code:

print(b'{}'.format(1))
CPy output: uPy output:
Traceback (most recent call last):
  File "<stdin>", line 7, in <module>
AttributeError: 'bytes' object has no attribute 'format'
/bin/sh: ../ports/unix/micropython: No such file or directory
bytes() with keywords not implemented

Workaround: Pass the encoding as a positional paramter, e.g. print(bytes('abc', 'utf-8'))

Sample code:

print(bytes('abc', encoding='utf8'))
CPy output: uPy output:
b'abc'
/bin/sh: ../ports/unix/micropython: No such file or directory
Bytes subscription with step != 1 not implemented

Cause: MicroPython is highly optimized for memory usage.

Workaround: Use explicit loop for this very rare operation.

Sample code:

print(b'123'[0:3:2])
CPy output: uPy output:
b'13'
/bin/sh: ../ports/unix/micropython: No such file or directory

float

uPy and CPython outputs formats may differ

Sample code:

print('%.1g' % -9.9)
CPy output: uPy output:
-1e+01
/bin/sh: ../ports/unix/micropython: No such file or directory

int

No int conversion for int-derived types available

Workaround: Avoid subclassing builtin types unless really needed. Prefer https://en.wikipedia.org/wiki/Composition_over_inheritance .

Sample code:

class A(int):
    __add__ = lambda self, other: A(int(self) + other)

a = A(42)
print(a+a)
CPy output: uPy output:
84
/bin/sh: ../ports/unix/micropython: No such file or directory

list

List delete with step != 1 not implemented

Workaround: Use explicit loop for this rare operation.

Sample code:

l = [1, 2, 3, 4]
del l[0:4:2]
print(l)
CPy output: uPy output:
[2, 4]
/bin/sh: ../ports/unix/micropython: No such file or directory
List slice-store with non-iterable on RHS is not implemented

Cause: RHS is restricted to be a tuple or list

Workaround: Use list(<iter>) on RHS to convert the iterable to a list

Sample code:

l = [10, 20]
l[0:1] = range(4)
print(l)
CPy output: uPy output:
[0, 1, 2, 3, 20]
/bin/sh: ../ports/unix/micropython: No such file or directory
List store with step != 1 not implemented

Workaround: Use explicit loop for this rare operation.

Sample code:

l = [1, 2, 3, 4]
l[0:4:2] = [5, 6]
print(l)
CPy output: uPy output:
[5, 2, 6, 4]
/bin/sh: ../ports/unix/micropython: No such file or directory

str

Start/end indices such as str.endswith(s, start) not implemented

Sample code:

print('abc'.endswith('c', 1))
CPy output: uPy output:
True
/bin/sh: ../ports/unix/micropython: No such file or directory
Attributes/subscr not implemented

Sample code:

print('{a[0]}'.format(a=[1, 2]))
CPy output: uPy output:
1
/bin/sh: ../ports/unix/micropython: No such file or directory
str(...) with keywords not implemented

Workaround: Input the encoding format directly. eg print(bytes('abc', 'utf-8'))

Sample code:

print(str(b'abc', encoding='utf8'))
CPy output: uPy output:
abc
/bin/sh: ../ports/unix/micropython: No such file or directory
str.ljust() and str.rjust() not implemented

Cause: MicroPython is highly optimized for memory usage. Easy workarounds available.

Workaround: Instead of s.ljust(10) use "%-10s" % s, instead of s.rjust(10) use "% 10s" % s. Alternatively, "{:<10}".format(s) or "{:>10}".format(s).

Sample code:

print('abc'.ljust(10))
CPy output: uPy output:
abc
/bin/sh: ../ports/unix/micropython: No such file or directory
None as first argument for rsplit such as str.rsplit(None, n) not implemented

Sample code:

print('a a a'.rsplit(None, 1))
CPy output: uPy output:
['a a', 'a']
/bin/sh: ../ports/unix/micropython: No such file or directory
Instance of a subclass of str cannot be compared for equality with an instance of a str

Sample code:

class S(str):
    pass

s = S('hello')
print(s == 'hello')
CPy output: uPy output:
True
/bin/sh: ../ports/unix/micropython: No such file or directory
Subscript with step != 1 is not yet implemented

Sample code:

print('abcdefghi'[0:9:2])
CPy output: uPy output:
acegi
/bin/sh: ../ports/unix/micropython: No such file or directory

tuple

Tuple load with step != 1 not implemented

Sample code:

print((1, 2, 3, 4)[0:4:2])
CPy output: uPy output:
(1, 3)
/bin/sh: ../ports/unix/micropython: No such file or directory

Modules

Generated Sun 07 Oct 2018 06:47:55 UTC

array

Looking for integer not implemented

Sample code:

import array
print(1 in array.array('B', b'12'))
CPy output: uPy output:
False
/bin/sh: ../ports/unix/micropython: No such file or directory
Array deletion not implemented

Sample code:

import array
a = array.array('b', (1, 2, 3))
del a[1]
print(a)
CPy output: uPy output:
array('b', [1, 3])
/bin/sh: ../ports/unix/micropython: No such file or directory
Subscript with step != 1 is not yet implemented

Sample code:

import array
a = array.array('b', (1, 2, 3))
print(a[3:2:2])
CPy output: uPy output:
array('b')
/bin/sh: ../ports/unix/micropython: No such file or directory

builtins

Second argument to next() is not implemented

Cause: MicroPython is optimised for code space.

Workaround: Instead of val = next(it, deflt) use:

try:
    val = next(it)
except StopIteration:
    val = deflt

Sample code:

print(next(iter(range(0)), 42))
CPy output: uPy output:
42
/bin/sh: ../ports/unix/micropython: No such file or directory

deque

Deque not implemented

Workaround: Use regular lists. micropython-lib has implementation of collections.deque.

Sample code:

import collections
D = collections.deque()
print(D)
CPy output: uPy output:
deque([])
/bin/sh: ../ports/unix/micropython: No such file or directory

json

JSON module does not throw exception when object is not serialisable

Sample code:

import json
a = bytes(x for x in range(256))
try:
    z = json.dumps(a)
    x = json.loads(z)
    print('Should not get here')
except TypeError:
    print('TypeError')
CPy output: uPy output:
TypeError
/bin/sh: ../ports/unix/micropython: No such file or directory

struct

Struct pack with too few args, not checked by uPy

Sample code:

import struct
try:
    print(struct.pack('bb', 1))
    print('Should not get here')
except:
    print('struct.error')
CPy output: uPy output:
struct.error
/bin/sh: ../ports/unix/micropython: No such file or directory
Struct pack with too many args, not checked by uPy

Sample code:

import struct
try:
    print(struct.pack('bb', 1, 2, 3))
    print('Should not get here')
except:
    print('struct.error')
CPy output: uPy output:
struct.error
/bin/sh: ../ports/unix/micropython: No such file or directory

sys

Overriding sys.stdin, sys.stdout and sys.stderr not possible

Cause: They are stored in read-only memory.

Sample code:

import sys
sys.stdin = None
print(sys.stdin)
CPy output: uPy output:
None
/bin/sh: ../ports/unix/micropython: No such file or directory

microPython 许可证信息

The MIT License (MIT)

Copyright (c) 2013-2017 Damien P. George, and others

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.