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

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 is a module for controlling and programming the ESP32's ULP (Ultra Low-Power) coprocessor. It has the following main features, application scenarios and precautions:

main feature:

The esp32.ULP module provides functions and constants for loading, running, stopping, and monitoring programs on the ULP coprocessor.
The esp32.ULP module also provides functions and constants for accessing and modifying the shared memory between the ULP coprocessor and the main CPU.
The esp32.ULP module can be used with third-party modules such as py-esp32-ulp or micropython-esp32-ulp to write and compile ULP assembly programs in the MicroPython environment.
Application scenarios:

The function of the esp32.ULP module can be used to perform some simple tasks in the low power mode of the ESP32, such as monitoring sensors, controlling peripherals, waking up the main CPU, etc.
The function of the esp32.ULP module can be used to assist in completing some tasks that require high speed or precise timing when the main CPU is in normal working mode, such as PWM (Pulse Width Modulation), PPM (Pulse Position Modulation), PCM (Pulse Code Modulation) wait.
The functions of the esp32.ULP module can also be used to exchange and synchronize data between the main CPU and the ULP coprocessor, such as through shared memory or interrupt signals.

Precautions:

The functions of the esp32.ULP module need to pay attention to conflicts with other functions that occupy ULP coprocessors or pins, such as SPI, I2C, UART, etc.
The functions of the esp32.ULP module need to pay attention to the impact of other functions that occupy shared memory or interrupt signals, such as network communication, file systems, garbage collection, etc.
The functions of the esp32.ULP module need 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 module:

Case 1: Use the esp32.ULP module to load and run a binary file compiled by py-esp32-ulp. This file implements a simple counter function and stores the result in shared memory.

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

# 定义一个计数器程序的源代码，使用py_esp32_ulp提供的汇编语法
counter_src = """
data: .long 0
entry: move r3, data
loop:  add r3, r3, 1
       move r0, r3
       store r0, r3, 0
       wait 1000
       jump loop
"""

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

# 使用esp32.ULP.set_wakeup_period()函数来设置ULP协处理器唤醒周期为0，表示不唤醒主CPU
esp32.ULP.set_wakeup_period(0)

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

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

# 使用machine.deepsleep()函数来让主CPU进入深度睡眠模式，ULP协处理器继续运行
machine.deepsleep()

# 使用esp32.ULP.mem_read()函数来读取共享内存中的数据，地址为0，返回一个整数
counter = esp32.ULP.mem_read(0)

# 打印出计数器的值
print(counter)

Case 2: Use the esp32.ULP module to load and run a binary file compiled by micropython-esp32-ulp. This file implements a simple temperature sensor function and stores the results in shared memory.

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

# 定义一个温度传感器程序的源代码，使用esp32_ulp提供的汇编语法
temp_src = """
data: .long 0
entry: tsens r0, 850 # 读取温度传感器的值，延迟850个周期
       move r3, data # 将数据地址存入r3寄存器
       store r0, r3, 0 # 将温度值存入数据地址
       halt # 停止执行
"""

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

# 使用esp32.ULP.set_wakeup_period()函数来设置ULP协处理器唤醒周期为1000000，表示每隔1秒唤醒一次主CPU
esp32.ULP.set_wakeup_period(1000000)

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

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

# 定义一个循环，每隔1秒打印出温度值，并让主CPU重新进入睡眠模式
while True:
    # 使用esp32.ULP.mem_read()函数来读取共享内存中的数据，地址为0，返回一个整数
    temp = esp32.ULP.mem_read(0)
    # 打印出温度值，单位为摄氏度
    print(temp / 2 - 40)
    # 使用machine.lightsleep()函数来让主CPU进入轻度睡眠模式，等待下一次唤醒
    machine.lightsleep()

Case 3: Use the esp32.ULP module to load and run a binary file compiled by binutils-esp32ulp. This file implements a simple PWM (pulse width modulation) function and outputs the result to the pin.

# 导入必要的模块
import esp32

# 定义一个PWM程序的二进制文件，使用binutils-esp32ulp编译生成，保存在ESP32的文件系统中，文件名为pwm.bin

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

# 使用esp32.ULP.set_wakeup_period()函数来设置ULP协处理器唤醒周期为0，表示不唤醒主CPU
esp32.ULP.set_wakeup_period(0)

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

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

# 此时，ESP32的第18号引脚会输出一个PWM信号，可以用示波器或LED灯观察效果

Case 4: Load the ULP program and run:

import esp32

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

# 将 ULP 程序加载到 ULP 协处理器中
ulp_program.begin()

# 运行 ULP 程序
ulp_program.run()

This sample program shows how to load a ULP program into the ULP coprocessor and start running the program.

Case 5: Set ULP GPIO pin mode and level:

import esp32

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

# 设置 ULP GPIO 引脚模式
ulp_program.gpio_pin_mode(0, esp32.ULP.GPIO_MODE_INPUT)

# 设置 ULP GPIO 引脚电平
ulp_program.gpio_pin_write(0, esp32.ULP.GPIO_LEVEL_LOW)

This sample program shows how to use the gpio_pin_mode() method to set the mode of the ULP GPIO pin, and the gpio_pin_write() method to set the level of the ULP GPIO pin.

Case 6: Reading data from ULP coprocessor:

import esp32

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

# 从 ULP 协处理器读取数据
data = ulp_program.read_memory(0x20000000, 4)

This sample program shows how to use the read_memory() method to read data from the ULP coprocessor's memory. In the example, it reads 4 bytes of data starting at address 0x20000000.

Case 7: Please note that using ULP requires additional configuration and programming of the ESP32, and is slightly different from MicroPython's main execution environment. ULP programs need to be written in ULP assembly language and compiled and loaded through a specific tool chain. Below is a code snippet of a sample ULP program that demonstrates how to use ULP in MicroPython to periodically wake up the ESP32:

import machine
import esp32

# 加载ULP程序
ulp_code = """
.macro delay_cycles, count
    sub r3, r3, \count
    bge r3, zero, \delay_cycles
.endm

    .section .ulp_main
    .global ulp_main
ulp_main:
    mov r3, 1000000  // 延时1秒
    delay_cycles 1
    sleep
"""

# 配置ULP唤醒定时器
ulp_timer = machine.ULPTimer()
ulp_timer.init(period=5000, mode=machine.ULP_TIMER_ONE_SHOT)

# 配置ULP程序
ulp = machine.ULP()
ulp.load_binary(0, ulp_code)

# 启动ULP
ulp.run()

# 进入深度睡眠模式
machine.deepsleep()

# 唤醒后执行的代码
print("Wake up!")

# 其他操作...

In this sample program, we first define the assembly code of a ULP program. The ULP program uses the delay_cycles macro to delay for 1 second and then enters sleep state. Next, we use machine.ULPTimer() to configure the ULP wake-up timer and set it to wake up every 5 seconds. Then, we use machine.ULP() to configure ULP and load the ULP program. Finally, we call machine.deepsleep() to enter deep sleep mode. When the ULP timer fires, ULP will wake up the ESP32 and execute the ULP program. After waking up, the program will print "Wake up!" and then perform other operations.

These sample programs demonstrate how to use the esp32.ULP module to interact with the ESP32's ULP coprocessor. By loading the ULP program, setting the GPIO pin mode and level, and reading data from the ULP coprocessor, you can use the ULP coprocessor to perform some low-power tasks and interact with the main CPU. Please note that the ULP function has limited support in MicroPython. Please refer to official documentation and related materials for specific capabilities and limitations.