__init__.py

# This file is part of espzero, automatically synced from
# https://github.com/roboticsware/espzero at revision 24cae2bc1c028458052675181e95f2a08fdf7481.
# Do not edit this file directly — run update_user_libs.py espzero instead.

"""
espzero/__init__.py
Public entry point for the espzero library — an ESP32 port of picozero.

Quick start::

    import espzero
    espzero.begin()               # initialise board (auto-detect)

    from espzero import esp_led   # built-in LED, ready after begin()
    from time import sleep

    while True:
        esp_led.on()
        sleep(1)
        esp_led.off()
        sleep(1)

Specify a board explicitly::

    espzero.begin("esp32_devkit_v1")  # override auto-detection

Import other components after begin()::

    from espzero import LED, Button, Servo, WiFi

The board profile system abstracts hardware differences (pin aliases,
ADC attenuation, strapping pins, NeoPixel vs GPIO LEDs, etc.) so that
user code remains identical across supported boards.
"""

from . import _hal

# ── Board → profile class mapping ─────────────────────────────
# Key   : user-facing board name (passed to begin())
# Value : (module_name, class_name) for lazy import
_PROFILE_MAP = {
    "esp32_devkit_v1":    ("profiles.esp32_boards", "ESP32DevKitV1"),
    "esp32_s3_devkit":    ("profiles.esp32_boards", "ESP32S3DevKit"),
    "esp32_c3_mini":      ("profiles.esp32_boards", "ESP32C3Mini"),
    "m5stack_atom":       ("profiles.esp32_boards", "M5StackAtom"),
    "wemos_d1_mini32":    ("profiles.esp32_boards", "WemosD1Mini32"),
    "esp8266_lolin_v3":   ("profiles.esp32_boards", "ESP8266LolinV3"),
    "esp32_38pin_nodemcu":("profiles.esp32_boards", "ESP32_38Pin_NodeMCU"),
}

# ── Internal state for convenience objects ─────────────────────
_esp_led         = None   # Built-in LED (DigitalLED or NeoPixelLED)
_esp_temp_sensor = None   # Built-in temperature sensor

# Module-level __getattr__ (MicroPython 1.18+) for lazy loading.
# This prevents NoneType errors if user imports before calling begin().
def __getattr__(name):
    if name == "esp_led":
        if _esp_led is None:
            raise RuntimeError(
                "[espzero] ERROR: 'esp_led' is not initialized. "
                "You must call espzero.begin() first."
            )
        return _esp_led
    if name == "esp_temp_sensor":
        return _esp_temp_sensor
    raise AttributeError("module 'espzero' has no attribute '{}'".format(name))


def begin(board="auto"):
    """
    Initialise the board profile.  Must be called before any espzero class.

    :param board:
        - ``"auto"``          – detect from ``sys.implementation._machine``
        - A board name string – e.g. ``"esp32_devkit_v1"``
        - A ``BoardProfile`` instance – for custom boards

    Raises ``ValueError`` for unknown board name strings.
    """
    global _esp_led, _esp_temp_sensor

    from .profiles._base import BoardProfile

    if isinstance(board, BoardProfile):
        _hal._profile = board

    elif board == "auto":
        from .profiles.auto import detect
        begin(detect())
        return

    else:
        if board not in _PROFILE_MAP:
            raise ValueError(
                "[espzero] Unknown board: '{}'. "
                "Available boards: {}".format(board, list(_PROFILE_MAP.keys()))
            )
        mod_name, cls_name = _PROFILE_MAP[board]
        # Dynamically import the profile module within the package
        full_mod_name = __name__ + "." + mod_name
        mod = __import__(full_mod_name, None, None, [cls_name])
        _hal._profile = getattr(mod, cls_name)()

    print("[espzero] Board: {} ({})".format(
        _hal._profile.NAME, _hal._profile.CHIP))

    # Initialise built-in LED — branch on LED type declared in the profile
    from ._core import NeoPixelLED, LED as _LED
    try:
        p = _hal._profile
        if p.INTERNAL_LED_TYPE == "neopixel":
            _esp_led = NeoPixelLED(p.resolve_pin("internal"))
        else:
            _esp_led = _LED("internal",
                            pwm=False,
                            active_high=p.INTERNAL_LED_ACTIVE_HIGH)
    except Exception as e:
        print("[espzero] LED Init Error:", e)
        _esp_led = None

    # Initialise built-in temperature sensor
    try:
        from ._core import ESPTemperatureSensor
        _esp_temp_sensor = ESPTemperatureSensor()
    except Exception as e:
        print("[espzero] TempSensor Init Error:", e)
        _esp_temp_sensor = None


# ── Re-export public API ───────────────────────────────────────
from ._core import (
    LED, DigitalLED, PWMLED, NeoPixelLED,
    Buzzer, PWMBuzzer, Speaker,
    RGBLED,
    Servo,
    Motor, Robot, Rover, Stepper,
    Button, Switch, MotionSensor, TouchSensor,
    Potentiometer, Pot,
    TemperatureSensor, TempSensor, Thermistor,
    DistanceSensor,
    ESPTemperatureSensor,
    DigitalOutputDevice, PWMOutputDevice,
    DigitalInputDevice, AnalogInputDevice,
    I2cLcd, GpioLcd,
)
from ._wifi  import WiFi
from ._touch import CapTouch