[Diao Ye Learns Programming] MicroPython Manual ESP32 Specific Port Library esp32.ULP.set_wakeup_period()

MicroPython is a lightweight version of the interpreter designed for running the Python 3 programming language in embedded systems. Compared with regular Python, the MicroPython interpreter is small (only about 100KB) and is compiled into a binary Executable file to run, resulting in higher execution efficiency. It uses a lightweight garbage collection mechanism and removes most of the Python standard library to accommodate resource-constrained microcontrollers.

The main features of MicroPython include:
1. The syntax and functions are compatible with standard Python, making it easy to learn and use. Supports most core syntax of Python.
2. Directly access and control hardware, control GPIO, I2C, SPI, etc. like Arduino.
3. Powerful module system, providing file system, network, graphical interface and other functions.
4. Support cross-compilation to generate efficient native code, which is 10-100 times faster than the interpreter.
5. The amount of code is small and the memory usage is small. It is suitable for running on MCU and development boards with small memory.
6. Open source license, free to use. The Shell interactive environment provides convenience for development and testing.
7. The built-in I/O driver supports a large number of microcontroller platforms, such as ESP8266, ESP32, STM32, micro:bit, control board and PyBoard, etc. There is an active community.

MicroPython application scenarios include:
1. Rapidly build prototypes and user interactions for embedded products.
2. Make some small programmable hardware projects.
3. As an educational tool, it helps beginners learn Python and IoT programming.
4. Build smart device firmware to achieve advanced control and cloud connectivity.
5. Various microcontroller applications such as Internet of Things, embedded intelligence, robots, etc.

Things to note when using MicroPython:
1. Memory and Flash space are limited.
2. The explanation and execution efficiency is not as good as C language.
3. Some library functions are different from the standard version.
4. Optimize the syntax for the platform and correct the differences with standard Python.
5. Use memory resources rationally and avoid frequently allocating large memory blocks.
6. Use native code to improve the performance of speed-critical parts.
7. Use abstraction appropriately to encapsulate underlying hardware operations.

Generally speaking, MicroPython brings Python into the field of microcontrollers, which is an important innovation that not only lowers the programming threshold but also provides good hardware control capabilities. It is very suitable for the development of various types of Internet of Things and intelligent hardware.

MicroPython's esp refers to the MicroPython firmware and related software libraries for ESP8266 and ESP32 chips. ESP8266 and ESP32 are a class of low-cost, low-power Wi-Fi and Bluetooth modules widely used in IoT and embedded systems. MicroPython's esp provides an advanced scripting environment for both chips, allowing developers to use the Python language for rapid prototyping and development.

ESP8266: It is a low-cost, low-power Wi-Fi module/chip developed by Espressif Systems. It has a built-in TCP/IP protocol stack, can be used to connect to the Internet, and has strong processing capabilities. MicroPython's esp provides firmware and related software libraries for ESP8266, allowing developers to use MicroPython language to develop ESP8266 applications.

ESP32: It is a highly integrated Wi-Fi and Bluetooth module/chip launched by Espressif Systems. Compared with ESP8266, it has more powerful processing power, more peripheral interfaces and more memory. MicroPython's esp also provides firmware and related software libraries for ESP32, allowing developers to use MicroPython language to develop ESP32 applications.

MicroPython's esp firmware: It is a MicroPython firmware version specifically for ESP8266 and ESP32 chips. These firmwares have been specifically optimized to run on ESP8266 and ESP32, and provide APIs for hardware interaction, network communication, and peripheral control.

Software libraries: MicroPython's esp also provides a series of software libraries related to ESP8266 and ESP32 hardware to simplify and accelerate the development process. These software libraries provide a rich set of functional interfaces, covering commonly used hardware and communication protocols such as Wi-Fi, Bluetooth, GPIO (General Purpose Input and Output), I2C, SPI, and PWM, allowing developers to easily access and control hardware resources.

MicroPython's esp32.ULP.set_wakeup_period() is a method used to set the period for the ULP (Ultra Low-Power) coprocessor to wake up the main CPU. It has the following main features, application scenarios and precautions:

main feature:

esp32.ULP.set_wakeup_period() is a method of the esp32.ULP class, which can act on any ULP coprocessor object.
The function of esp32.ULP.set_wakeup_period() is to set how long the ULP coprocessor waits after running a program before waking up the main CPU.
The return value of esp32.ULP.set_wakeup_period() is None, indicating that the setting is successful.
There are two parameters for esp32.ULP.set_wakeup_period(). The first one is an integer, indicating the index of the wakeup period, ranging from 0-412. The second is an integer representing the number of microseconds in the wake-up period, ranging from 0-4294967295.
The default parameters of esp32.ULP.set_wakeup_period() are 0 and 0, which means not to wake up the main CPU.

Application scenarios:

The function of esp32.ULP.set_wakeup_period() can be used to regularly wake up the main CPU in the low-power mode of ESP32 and perform some tasks that need to be performed regularly or periodically, such as monitoring sensors, controlling peripherals, updating data, etc.
The function of esp32.ULP.set_wakeup_period() can be used in the normal working mode of ESP32 to allow the main CPU to be awakened by the ULP coprocessor after a certain period of time to perform some tasks that need to be delayed or scheduled, such as sending network requests and displaying results, save data, etc.
The function of esp32.ULP.set_wakeup_period() can also be used in the deep sleep mode of ESP32 to allow the main CPU to be awakened by the ULP coprocessor after a certain period of time to perform some tasks that require low frequency or low power consumption, such as checking Battery level, sync time, update firmware and more.

Precautions:

The function of esp32.ULP.set_wakeup_period() needs to pay attention to conflicts with other functions that occupy ULP coprocessors or pins, such as SPI, I2C, UART, etc.
The function of esp32.ULP.set_wakeup_period() needs to pay attention to the impact of other functions that occupy shared memory or interrupt signals, such as network communication, file system, garbage collection, etc.
The function of esp32.ULP.set_wakeup_period() needs to be coordinated with other functions that require interrupt services or timer services, such as machine timers, machine interrupts, etc.

The following are several practical application examples using MicroPython's esp32.ULP.set_wakeup_period() method:

Case 1: Use esp32.ULP.set_wakeup_period() to set the ULP coprocessor to wake up the main CPU every 10 seconds and print out the current time.

# 导入必要的模块
import esp32
import machine
import time

# 定义一个空程序的源代码，使用esp32_ulp提供的汇编语法
empty_src = """
entry: halt # 停止执行
"""

# 使用esp32_ulp.assemble()函数来编译源代码，并返回一个字节对象
empty_bin = esp32_ulp.assemble(empty_src)

# 使用esp32.ULP.set_wakeup_period()函数来设置ULP协处理器唤醒周期为10秒
esp32.ULP.set_wakeup_period(0, 10000000)

# 使用esp32.ULP.load_binary()函数来加载二进制文件到ULP协处理器内存中，起始地址为0
esp32.ULP.load_binary(0, empty_bin)

# 使用esp32.ULP.run()函数来运行二进制文件，起始地址为0
esp32.ULP.run(0)

# 定义一个循环，每次被唤醒后打印出当前时间，并让主CPU重新进入睡眠模式
while True:
    # 使用time.localtime()函数来获取当前时间，返回一个元组
    t = time.localtime()
    # 使用print()函数来打印出当前时间，格式为年-月-日 时:分:秒
    print('%d-%02d-%02d %02d:%02d:%02d' % t[:6])
    # 使用machine.lightsleep()函数来让主CPU进入轻度睡眠模式，等待下一次唤醒
    machine.lightsleep()

Case 2: Use esp32.ULP.set_wakeup_period() to set the ULP coprocessor to delay 5 seconds before waking up the main CPU after running a program, and control the flashing of an LED light.

# 导入必要的模块
import esp32
import machine

# 定义一个控制LED灯的程序的源代码，使用py-esp32-ulp提供的汇编语法
led_src = """
data: .long 0
entry: move r3, data # 将数据地址存入r3寄存器
       load r0, r3, 0 # 将数据值加载到r0寄存器
       move r1, 18 # 将引脚号18存入r1寄存器
       i2c_rd r2, r1, 28, 1 # 读取GPIO_OUT寄存器的值，存入r2寄存器
       xor r2, r2, r0 # 将r2和r0做异或运算，得到反转后的值，存入r2寄存器
       i2c_wr r2, r1, 28, 1 # 将r2的值写入GPIO_OUT寄存器，控制LED灯的状态
       store r2, r3, 0 # 将r2的值存回数据地址，更新数据值
       halt # 停止执行
"""

# 使用py_esp32_ulp.assemble()函数来编译源代码，并返回一个字节对象
led_bin = py_esp32_ulp.assemble(led_src)

# 使用esp32.ULP.set_wakeup_period()函数来设置ULP协处理器唤醒周期为5秒
esp32.ULP.set_wakeup_period(0, 5000000)

# 使用esp32.ULP.load_binary()函数来加载二进制文件到ULP协处理器内存中，起始地址为0
esp32.ULP.load_binary(0, led_bin)

# 使用esp32.ULP.run()函数来运行二进制文件，起始地址为0
esp32.ULP.run(0)

# 创建一个Pin对象，绑定到第18号引脚，设置为输出模式，并初始化为低电平（关闭LED灯）
led = machine.Pin(18, machine.Pin.OUT)
led.value(0)

# 此时，ESP32的第18号引脚会每隔5秒反转一次电平，从而控制LED灯的闪烁

Case 3: Use esp32.ULP.set_wakeup_period() to set the ULP coprocessor to wait for an external interrupt before waking up the main CPU after running a program, and read the status of a button.

# 导入必要的模块
import esp32
import machine

# 定义一个读取按钮的程序的源代码，使用binutils-esp32ulp编译生成，保存在ESP32的文件系统中，文件名为button.bin

# 使用open()函数来打开二进制文件，并读取其内容，返回一个字节对象
with open('button.bin', 'rb') as f:
    button_bin = f.read()

# 使用esp32.ULP.set_wakeup_period()函数来设置ULP协处理器唤醒周期为-1，表示等待一个外部中断再唤醒主CPU
esp32.ULP.set_wakeup_period(-1)

# 使用esp32.ULP.load_binary()函数来加载二进制文件到ULP协处理器内存中，起始地址为0
esp32.ULP.load_binary(0, button_bin)

# 使用esp32.ULP.run()函数来运行二进制文件，起始地址为0
esp32.ULP.run(0)

# 创建一个Pin对象，绑定到第19号引脚，设置为输入模式，并启用内部上拉电阻
button = machine.Pin(19, machine.Pin.IN, machine.Pin.PULL_UP)

# 定义一个中断处理函数，用于唤醒ULP协处理器
def wake_ulp(pin):
    # 使用esp32.ULP.set_wakeup_period()函数来设置ULP协处理器唤醒周期为0，表示立即唤醒
    esp32.ULP.set_wakeup_period(0)

# 使用Pin对象的irq()方法来设置中断触发模式为下降沿，并绑定中断处理函数
button.irq(trigger=machine.Pin.IRQ_FALLING, handler=wake_ulp)

# 定义一个循环，每次被唤醒后读取共享内存中的数据，并打印出按钮的状态
while True:
    # 使用esp32.ULP.mem_read()函数来读取共享内存中的数据，地址为0，返回一个整数
    button_state = esp32.ULP.mem_read(0)
    # 判断按钮的状态是按下还是松开，并打印出结果
    if button_state == 0:
        print('Button is pressed')
    else:
        print('Button is released')
    # 使用machine.lightsleep()函数来让主CPU进入轻度睡眠模式，等待下一次唤醒
    machine.lightsleep()

Case 4: Set low-power wake-up period:

import esp32
esp32.ULP.set_wakeup_period(5000) # every 5 seconds

Case 5: Set different cycles to wake up repeatedly:

import esp32, math
for i in range(5):
esp32.ULP.set_wakeup_period(int(2000*math.sin(i)+3000))

Case 6: Clear wake-up cycle settings:

import esp32
esp32.ULP.set_wakeup_period(0)

The first example sets a fixed wake-up period of 5 seconds. The second example sets up different random cycles to wake up. The third example clears the previous wake-up cycle setting. This function is used to set the regular wake-up cycle of the ULP coprocessor, which plays a role in low power consumption management. The wake-up strategy can be flexibly configured through parameters such as steward and frequency.

Case 7: Set the wake-up period of the ULP coprocessor to 1 second:

import esp32

# 定义 ULP 程序
ulp_program = esp32.ULP()

# 设置 ULP 协处理器的唤醒周期为 1 秒
ulp_program.set_wakeup_period(1)

This sample program shows how to use the set_wakeup_period() method to set the ULP coprocessor's wakeup period to 1 second.

Case 8: Set the wake-up period of the ULP coprocessor to 500 milliseconds:

import esp32

# 定义 ULP 程序
ulp_program = esp32.ULP()

# 设置 ULP 协处理器的唤醒周期为 500 毫秒
ulp_program.set_wakeup_period(0.5)

This sample program shows how to use the set_wakeup_period() method to set the ULP coprocessor's wakeup period to 500 milliseconds.

Case 9: Dynamically set the wake-up cycle of the ULP coprocessor:

import esp32
import time

# 定义 ULP 程序
ulp_program = esp32.ULP()

# 设置 ULP 协处理器的初始唤醒周期为 1 秒
ulp_program.set_wakeup_period(1)

# 等待一段时间
time.sleep(5)

# 动态调整 ULP 协处理器的唤醒周期为 500 毫秒
ulp_program.set_wakeup_period(0.5)

This sample program shows how to dynamically adjust the ULP coprocessor's wake-up period during runtime. Start by setting the wake period to 1 second, then wait 5 seconds before adjusting it to 500 milliseconds.

These sample programs show how to set the wakeup period of the ESP32's ULP coprocessor using the esp32.ULP.set_wakeup_period() method. By adjusting the wake period, you can control the ULP coprocessor's run time and power consumption to meet specific needs and application scenarios. Please note that the unit of wake-up period is seconds, and you can use decimals to express milliseconds.