vcnl4010_driver/
├── code/
│   ├── vcnl4010.py      # 核心驱动文件
│   └── main.py          # 测试示例
├── README.md            # 说明文档
├── package.json         # 包描述文件
└── LICENSE              # 许可协议

# Python env   : MicroPython v1.23.0
# -*- coding: utf-8 -*-
# @Time    : 2026/07/31 12:00
# @Author  : Jose D. Montoya
# @File    : main.py
# @Description : 测试 VCNL4010 驱动类
# @License : MIT

# ======================================== 导入相关模块 =========================================
import time
from machine import Pin, I2C
from micropython import const
from vcnl4010 import (
    VCNL4010,
    SAMPLERATE_1_95,
    SAMPLERATE_250,
    AMBIENT_LIGHT_RATE1,
    AMBIENT_LIGHT_RATE10,
    AL_AVERAGE1,
    AL_AVERAGE128,
)

# ======================================== 全局变量 ============================================
# I2C 设备验证常量
_DEVICE_ID_REG = const(0x81)       # WHO_AM_I 寄存器地址
_EXPECTED_DEVICE_ID = const(0x21)  # VCNL4010 设备 ID 期望值
_DEVICE_I2C_ADDR = const(0x13)     # VCNL4010 默认 I2C 地址

# 定时打印控制
last_print_time = time.ticks_ms()
print_interval = 2000  # 打印间隔（ms）

# ======================================== 功能函数 ============================================

def test_proximity_rates(device):
    """
    测试所有接近采样率配置（模式切换，注释默认执行，可 REPL 手动触发）。
    遍历 SAMPLERATE_1_95 ~ SAMPLERATE_250，切换后读取一次数据验证功能正常。
    """
    rates = (
        ("SAMPLERATE_1_95", SAMPLERATE_1_95),
        ("SAMPLERATE_3_90625", 0b001),
        ("SAMPLERATE_7_8125", 0b010),
        ("SAMPLERATE_16_625", 0b011),
        ("SAMPLERATE_31_25", 0b100),
        ("SAMPLERATE_62_5", 0b101),
        ("SAMPLERATE_125", 0b110),
        ("SAMPLERATE_250", SAMPLERATE_250),
    )
    print("\n--- Proximity Rate Test ---")
    for name, rate in rates:
        # 切换采样率
        device.proximity_rate = rate
        # 验证读取一致性
        current = device.proximity_rate
        # 读取一次接近数据
        prox = device.proximity
        print("  %s: config=%s, proximity=%d" % (name, current, prox))
        time.sleep_ms(10)


def test_ambient_light_rates(device):
    """
    测试所有环境光采样率配置（模式切换，注释默认执行，可 REPL 手动触发）。
    遍历 AMBIENT_LIGHT_RATE1 ~ AMBIENT_LIGHT_RATE10。
    """
    rates = (
        ("AMBIENT_LIGHT_RATE1", AMBIENT_LIGHT_RATE1),
        ("AMBIENT_LIGHT_RATE2", 0b001),
        ("AMBIENT_LIGHT_RATE3", 0b010),
        ("AMBIENT_LIGHT_RATE4", 0b011),
        ("AMBIENT_LIGHT_RATE5", 0b100),
        ("AMBIENT_LIGHT_RATE6", 0b101),
        ("AMBIENT_LIGHT_RATE8", 0b110),
        ("AMBIENT_LIGHT_RATE10", AMBIENT_LIGHT_RATE10),
    )
    print("\n--- Ambient Light Rate Test ---")
    for name, rate in rates:
        device.ambient_light_rate = rate
        current = device.ambient_light_rate
        ambient = device.ambient
        print("  %s: config=%s, ambient=%.2f lux" % (name, current, ambient))
        time.sleep_ms(10)


def test_ambient_light_averages(device):
    """
    测试所有环境光平均次数配置（模式切换，注释默认执行，可 REPL 手动触发）。
    遍历 AL_AVERAGE1 ~ AL_AVERAGE128。
    """
    averages = (
        ("AL_AVERAGE1", AL_AVERAGE1),
        ("AL_AVERAGE2", 0b001),
        ("AL_AVERAGE4", 0b010),
        ("AL_AVERAGE8", 0b011),
        ("AL_AVERAGE16", 0b100),
        ("AL_AVERAGE32", 0b101),
        ("AL_AVERAGE64", 0b110),
        ("AL_AVERAGE128", AL_AVERAGE128),
    )
    print("\n--- Ambient Light Average Test ---")
    for name, avg in averages:
        device.ambient_light_average = avg
        current = device.ambient_light_average
        ambient = device.ambient
        print("  %s: config=%s, ambient=%.2f lux" % (name, current, ambient))
        time.sleep_ms(10)


def test_irl_led_current_boundary(device):
    """
    测试 IR LED 电流边界值（边界参数场景，注释默认执行，可 REPL 手动触发）。
    测试最小值 1（10mA）和最大值 20（200mA）。
    """
    print("\n--- IR LED Current Boundary Test ---")
    # 测试最小电流
    device.irl_led_current = 1
    print("  min current: %d (10mA)" % device.irl_led_current)
    # 测试最大电流
    device.irl_led_current = 20
    print("  max current: %d (200mA)" % device.irl_led_current)
    # 恢复默认值
    device.irl_led_current = 2
    print("  restored default: %d (20mA)" % device.irl_led_current)


def test_invalid_params(device):
    """
    测试异常参数处理（异常参数场景，注释默认执行，可 REPL 手动触发）。
    验证非法参数是否正确抛出 ValueError。
    """
    print("\n--- Invalid Parameter Test ---")
    # 测试非法接近采样率
    try:
        device.proximity_rate = 0xFF
        print("  FAIL: no exception for invalid proximity_rate")
    except ValueError as e:
        print("  PASS: proximity_rate -> %s" % e)
    # 测试非法 IR LED 电流（超出范围）
    try:
        device.irl_led_current = 30
        print("  FAIL: no exception for invalid irl_led_current")
    except ValueError as e:
        print("  PASS: irl_led_current(30) -> %s" % e)
    # 测试非法 IR LED 电流（0）
    try:
        device.irl_led_current = 0
        print("  FAIL: no exception for irl_led_current=0")
    except ValueError as e:
        print("  PASS: irl_led_current(0) -> %s" % e)
    print("  All invalid param tests passed")

# ======================================== 初始化配置 ==========================================
# 等待设备稳定
time.sleep(3)
print("FreakStudio: VCNL4010 驱动类测试")

# 初始化 I2C 总线（根据平台修改引脚号）
# ESP32 常用: sda=Pin(21), scl=Pin(22)
# RP2040 常用: sda=Pin(4), scl=Pin(5)
i2c = I2C(0, sda=Pin(21), scl=Pin(22), freq=100000)
print("I2C initialized: sda=21, scl=22")

# I2C 设备扫描（确认传感器在线）
devices = i2c.scan()
if not devices:
    raise RuntimeError("No I2C device found on bus")
print("I2C scan result: %s" % [hex(d) for d in devices])

# 验证目标地址是否存在
if _DEVICE_I2C_ADDR not in devices:
    raise RuntimeError(
        "Device not found at expected address 0x%02X" % _DEVICE_I2C_ADDR
    )
print("Device found at 0x%02X" % _DEVICE_I2C_ADDR)

# 创建传感器实例（内部自动验证设备 ID）
try:
    sensor = VCNL4010(i2c)
    print("VCNL4010 initialized successfully")
    # 读取并验证设备 ID
    device_id = i2c.readfrom_mem(_DEVICE_I2C_ADDR, _DEVICE_ID_REG, 1)[0]
    if device_id == _EXPECTED_DEVICE_ID:
        print("Device ID verified: 0x%02X (expected 0x%02X)" % (device_id, _EXPECTED_DEVICE_ID))
    else:
        print("Device ID mismatch: got 0x%02X, expected 0x%02X" % (device_id, _EXPECTED_DEVICE_ID))
except RuntimeError as e:
    print("Device initialization failed: %s" % e)
    raise

# 打印初始配置状态
print("Default config:")
print("  proximity_rate: %s" % sensor.proximity_rate)
print("  irl_led_current: %d" % sensor.irl_led_current)
print("  ambient_light_rate: %s" % sensor.ambient_light_rate)
print("  ambient_light_average: %s" % sensor.ambient_light_average)

# ========================================  主程序  ===========================================
try:
    while True:
        current_time = time.ticks_ms()
        if time.ticks_diff(current_time, last_print_time) >= print_interval:
            # 低频查询：自动执行传感器数据读取
            prox = sensor.proximity
            ambient = sensor.ambient
            print("Proximity: %d, Ambient: %.2f lux" % (prox, ambient))
            last_print_time = current_time

        # test_proximity_rates(sensor)        # 接近采样率全量测试，注释自动执行，可 REPL 手动调用
        # test_ambient_light_rates(sensor)    # 环境光采样率全量测试，注释自动执行，可 REPL 手动调用
        # test_ambient_light_averages(sensor) # 环境光平均次数全量测试，注释自动执行，可 REPL 手动调用
        # test_irl_led_current_boundary(sensor) # IR LED 电流边界测试，注释自动执行，可 REPL 手动调用
        # test_invalid_params(sensor)          # 异常参数测试，注释自动执行，可 REPL 手动调用

        time.sleep_ms(10)

except KeyboardInterrupt:
    print("Program interrupted by user")
except OSError as e:
    print("Hardware communication error: %s" % str(e))
except Exception as e:
    print("Unknown error: %s" % str(e))
finally:
    print("Cleaning up resources...")
    sensor.deinit()
    del sensor
    print("Program exited")