CircuitPython环境变量配置详解

CircuitPython环境变量配置详解

circuitpython 项目地址: https://gitcode.com/gh_mirrors/ci/circuitpython

环境变量概述

CircuitPython 8.0.0版本引入了环境变量支持功能，这是一个重要的功能更新。环境变量主要用于存储敏感信息，如Wi-Fi密码和API密钥等。需要注意的是，这种方式并不能真正保证这些信息的安全性，只是将它们从代码中分离出来，提高了代码的可维护性。

配置文件格式

CircuitPython使用根目录下的settings.toml文件来存储环境变量。这个文件采用TOML格式，但CircuitPython只支持TOML的一个子集，这个子集设计得非常"Python化"，便于开发者理解和使用。

基本语法示例

# 字符串类型
wifi_ssid="MyWiFiNetwork"
wifi_password="MySecretPassword"

# 整型
retry_count=5

# 支持Unicode字符
unicode_example="中文测试"

# 支持转义字符
escaped_text="支持\\n换行符"

# 注释会被忽略

技术细节

支持的TOML特性

1. 编码要求：文件必须使用UTF-8编码
2. 数据类型：仅支持字符串和整数
3. 字符串格式：只支持基本字符串(双引号)，不支持三引号字符串
4. 整数格式：只支持十进制格式，不支持0o(八进制)、0b(二进制)或下划线分隔(如1_000)
5. 键名规则：只支持简单键名，不支持复杂键名
6. 注释：支持单行注释
7. 作用域：只能从根表中获取值

性能建议

由于每次调用os.getenv()都会解析settings.toml文件，建议将频繁使用的值保存在变量中，以提高性能。

系统级环境变量

CircuitPython自身也使用环境变量来配置系统行为。以下是主要的系统环境变量：

核心配置变量

1. CIRCUITPY_BLE_NAME：设置BLE广播名称
2. CIRCUITPY_HEAP_START_SIZE：设置Python堆初始大小(默认为8192，必须是4的倍数)
3. CIRCUITPY_PYSTACK_SIZE：设置Python栈大小(默认为1536，必须是4的倍数)
4. CIRCUITPY_WEB_API_PASSWORD：Web工作流的修改密码
5. CIRCUITPY_WEB_API_PORT：Web API的TCP端口(默认80)
6. CIRCUITPY_WIFI_SSID/PASSWORD：自动连接的Wi-Fi信息

显示相关变量

1. CIRCUITPY_DISPLAY_WIDTH/HEIGHT：设置显示分辨率
2. CIRCUITPY_DISPLAY_ROTATION：设置屏幕旋转角度(0/90/180/270)
3. CIRCUITPY_DISPLAY_FREQUENCY：设置显示刷新频率(单位Hz)
4. CIRCUITPY_DISPLAY_COLOR_DEPTH：设置颜色深度(1/2/4/8/16/32位)

终端配置变量

1. CIRCUITPY_TERMINAL_SCALE：设置终端显示缩放比例
2. CIRCUITPY_TERMINAL_FONT：指定自定义终端字体文件路径

实际应用示例

Wi-Fi自动连接配置

CIRCUITPY_WIFI_SSID="MyNetwork"
CIRCUITPY_WIFI_PASSWORD="securepassword123"

显示设置示例

# 设置分辨率为640x480，1位色深(黑白)
CIRCUITPY_DISPLAY_WIDTH=640
CIRCUITPY_DISPLAY_COLOR_DEPTH=1

# 设置屏幕旋转180度
CIRCUITPY_DISPLAY_ROTATION=180

内存配置示例

# 增大Python堆初始大小
CIRCUITPY_HEAP_START_SIZE=16384

# 增大Python栈大小以避免"Pystack exhausted"错误
CIRCUITPY_PYSTACK_SIZE=2048

注意事项

1. 环境变量不是安全存储方案，敏感信息仍可能被读取
2. 某些板型可能不支持全部环境变量功能
3. 修改系统变量可能影响系统稳定性，建议在了解影响后再进行修改
4. 不是所有TOML特性都被支持，复杂的TOML文件可能导致解析错误

通过合理使用环境变量，可以大大提高CircuitPython项目的可维护性和配置灵活性。

circuitpython 项目地址: https://gitcode.com/gh_mirrors/ci/circuitpython