espzero 0.0.1__py3-none-any.whl

espzero-0.0.1.dist-info/METADATA

@@ -0,0 +1,409 @@
+Metadata-Version: 2.4
+Name: espzero
+Version: 0.0.1
+Summary: Educational tool for physical computing and ESP32/ESP8266 development.
+Author-email: Neo Neopia-uz <neopia.uz@gmail.com>
+Project-URL: Homepage, https://github.com/roboticsware/espzero
+Project-URL: Bug Tracker, https://github.com/roboticsware/espzero/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# espzero
+
+> A single MicroPython library that ports [picozero](https://github.com/raspberrypilearning/picozero) to the ESP32 family (WROOM, S3, C3, and more).  
+> **"One codebase, many boards"** — hardware differences are absorbed by the Board Profile system.
+
+---
+
+## Installation
+
+Copy the `espzero/` directory to the root of your ESP32 filesystem using Mu Editor, Thonny, or `mpremote`:
+
+```
+mpremote cp -r espzero/ :espzero/
+```
+
+---
+
+## Quick Start
+
+```python
+import espzero
+espzero.begin()                # initialise: auto-detect board
+
+# Built-in LED — available after begin()
+from espzero import esp_led
+from time import sleep
+
+while True:
+    esp_led.on()
+    sleep(1)
+    esp_led.off()
+    sleep(1)
+```
+
+Specify a board explicitly instead of auto-detection:
+
+```python
+import espzero
+espzero.begin("esp32_38pin_nodemcu")   # or "esp32_devkit_v1", "esp8266_lolin_v3", ...
+```
+
+Use other components after `begin()`:
+
+```python
+from espzero import LED, Button, Servo, WiFi
+
+led = LED("internal")              # built-in LED — profile maps alias to real GPIO
+btn = Button(0)                    # GPIO 0 (BOOT button)
+led.blink(on_time=0.5, n=5)       # identical API to picozero
+
+# WiFi (ESP32-specific)
+wifi = WiFi()
+ip = wifi.connect("MySSID", "password")
+print("IP:", ip)
+
+# Capacitive touch (WROOM/WROVER only)
+from espzero import CapTouch
+touch = CapTouch(pin=4)            # GPIO 4 = T0
+if touch.is_touched:
+    esp_led.on()
+
+# Servo
+servo = Servo(13)
+servo.mid()
+servo.value = 0.75                 # 0–1 range, same as picozero
+```
+
+---
+
+## 1. File Structure
+
+```
+espzero/
+├── __init__.py          # Public API entry point + begin()
+├── _hal.py              # Hardware Abstraction Layer (HAL)
+├── _core.py             # Ported picozero core logic
+├── _wifi.py             # ESP32-specific: WiFi class
+├── _touch.py            # ESP32-specific: capacitive touch class
+└── profiles/
+    ├── _base.py         # Abstract BoardProfile base class
+    ├── auto.py          # Runtime board auto-detection
+    └── esp32_boards.py  # Profile definitions for all supported boards
+```
+
+---
+
+## 2. Board Profile System
+
+### 2-A. Base Class (`profiles/_base.py`)
+
+```python
+class BoardProfile:
+    NAME = "unknown"            # Human-readable board name
+    CHIP = "esp32"              # esp32 / esp32s3 / esp32c3 / esp8266
+
+    # Pin aliases — lets users write LED("internal") instead of LED(2)
+    PIN_ALIASES = {}
+
+    # ADC settings
+    ADC_MAX_RAW  = 4095         # 12-bit resolution (0–4095)
+    ADC_SCALE    = 65535        # Scale target for picozero read_u16() compatibility
+    ADC_ATTEN    = None         # e.g. machine.ADC.ATTN_11DB; None = firmware default
+    ADC_VREF     = 3.3          # Maximum input voltage (tied to attenuation)
+
+    # PWM settings
+    PWM_DEFAULT_FREQ  = 1000    # Hz — Pico default was 100 Hz; 1 kHz recommended for ESP32
+    PWM_DUTY_MAX      = 65535   # Internal scale is always 16-bit
+
+    # Servo
+    SERVO_FREQ        = 50      # 50 Hz (20 ms frame) — same as picozero
+
+    # Built-in LED type
+    # "digital"  — standard GPIO LED
+    # "neopixel" — WS2812 RGB (e.g. ESP32-S3 DevKit, M5Stack ATOM)
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = True
+
+    # Boot strapping pins — connecting a button here may cause boot failures
+    STRAPPING_PINS = []         # e.g. [0, 2, 5, 12, 15]
+
+    # ADC2 pins — cannot be used while WiFi is active
+    ADC2_PINS = []              # e.g. [0, 2, 4, 12, 13, 14, 15, 25, 26, 27]
+```
+
+### 2-B. Board Profile Examples (`profiles/esp32_boards.py`)
+
+```python
+class ESP32DevKitV1(BoardProfile):
+    NAME = "esp32_devkit_v1"
+    CHIP = "esp32"
+    PIN_ALIASES = {"internal": 2, "led": 2}
+    ADC_ATTEN            = ADC.ATTN_11DB   # 0–3.6 V
+    ADC_VREF             = 3.6
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = False       # active-low
+    STRAPPING_PINS       = [0, 2, 5, 12, 15]
+    ADC2_PINS            = [0, 2, 4, 12, 13, 14, 15, 25, 26, 27]
+
+
+class ESP32S3DevKit(BoardProfile):
+    NAME = "esp32_s3_devkit"
+    CHIP = "esp32s3"
+    PIN_ALIASES = {"internal": 48, "led": 48}
+    INTERNAL_LED_TYPE = "neopixel"         # WS2812 RGB on GPIO 48
+    STRAPPING_PINS    = [0, 3, 45, 46]
+    ADC2_PINS         = [11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
+
+
+class ESP32C3Mini(BoardProfile):
+    NAME = "esp32_c3_mini"
+    CHIP = "esp32c3"
+    PIN_ALIASES = {"internal": 8, "led": 8}
+    INTERNAL_LED_ACTIVE_HIGH = False
+    STRAPPING_PINS = [2, 8, 9]
+    ADC2_PINS      = []                    # C3 has no ADC2
+```
+
+### 2-C. Auto-detection (`profiles/auto.py`)
+
+```python
+import sys
+
+def detect() -> str:
+    """
+    Identify the chip from sys.implementation._machine.
+    Returns a board key that matches an entry in espzero._PROFILE_MAP.
+    """
+    try:
+        machine_str = sys.implementation._machine.lower()
+    except AttributeError:
+        return "esp32_devkit_v1"   # fallback
+
+    if "esp32s3" in machine_str or "esp32-s3" in machine_str:
+        return "esp32_s3_devkit"
+    elif "esp32c3" in machine_str or "esp32-c3" in machine_str:
+        return "esp32_c3_mini"
+    else:
+        return "esp32_devkit_v1"   # default: WROOM
+```
+
+---
+
+## 3. Hardware Abstraction Layer (`_hal.py`)
+
+All `machine.Pin / machine.PWM / machine.ADC` calls are routed through this layer.  
+Swapping the board profile is enough to support a new board — `_core.py` requires no changes.
+
+```python
+_profile     = None    # Set by begin() to a BoardProfile instance
+_wifi_active = False   # True while WiFi is connected
+
+def make_digital_in(pin, pull_up=False):
+    """Create input Pin. Warns if GPIO is a strapping pin."""
+    gpio = resolve_pin(pin)
+    if gpio in get_profile().STRAPPING_PINS:
+        print("[espzero] WARNING: GPIO {} is a strapping pin. "
+              "Attaching a button may cause boot issues.".format(gpio))
+    ...
+
+def set_duty_u16(pwm_obj, value):
+    """Set duty cycle. Falls back to duty(0–1023) on firmware < 1.19."""
+    try:
+        pwm_obj.duty_u16(value)
+    except AttributeError:
+        pwm_obj.duty(value >> 6)    # 16-bit → 10-bit
+
+def make_adc(pin):
+    """Create ADC. Warns if WiFi is active and pin is in ADC2 group."""
+    if _wifi_active and gpio in get_profile().ADC2_PINS:
+        print("[espzero] WARNING: WiFi is active. ADC2 (GPIO {}) "
+              "cannot be used. Switch to an ADC1 pin.".format(gpio))
+    ...
+```
+
+---
+
+## 4. picozero → espzero Change Table
+
+| Topic | picozero (Pico) | espzero (ESP32) | How |
+|-------|----------------|-----------------|-----|
+| **Pin creation** | `Pin(num, ...)` directly | `_hal.make_digital_out(pin)` | HAL wrapper |
+| **PWM channel conflict** | `PIN_TO_PWM_CHANNEL[]` table | **Removed** (ESP32 LEDC: any pin, any channel) | Deleted |
+| **PWM duty write** | `duty_u16(val)` | Same, with fallback for firmware < 1.19 | `_hal.set_duty_u16()` |
+| **ADC read** | `adc.read_u16()` | `adc_read_u16()` → scales `read()×16` internally | HAL |
+| **ADC attenuation** | None | `ATTN_11DB` (set in profile) | Profile |
+| **Built-in LED** | `LED("LED")` or `LED(25)` | `LED("internal")` → profile maps to real pin | Alias system |
+| **Built-in temp** | `pico_temp_sensor` (ADC ch.4) | `esp_temp_sensor` (ESP32 `esp32` module) | Separate class |
+| **PWM default freq** | 100 Hz | 1000 Hz (`PWM_DEFAULT_FREQ` in profile) | Profile value |
+| **Servo freq** | 50 Hz | 50 Hz (unchanged) | — |
+| **WiFi** | None | `WiFi` class | New |
+| **Touch** | `TouchSensor` (external TTP223) | + `CapTouch` (ESP32 built-in touch peripheral) | New |
+
+---
+
+## 5. Key `_core.py` Changes
+
+### 5-A. `PWMOutputDevice` — Channel restriction removed
+
+```python
+# picozero: PIN_TO_PWM_CHANNEL table + _check_pwm_channel() → removed
+# espzero:  ESP32 LEDC assigns each pin an independent channel — no conflicts
+
+class PWMOutputDevice(OutputDevice, PinMixin):
+    def __init__(self, pin, freq=None, duty_factor=65535, ...):
+        self._pwm = _hal.make_pwm(pin, freq)   # routed through HAL
+
+    def _write(self, value):
+        _hal.set_duty_u16(self._pwm, self._value_to_state(value))  # with fallback
+```
+
+### 5-B. `AnalogInputDevice` — ADC scale correction
+
+```python
+class AnalogInputDevice(InputDevice, PinMixin):
+    def __init__(self, pin, ...):
+        self._adc = _hal.make_adc(pin)         # attenuation applied in profile
+
+    def _read(self):
+        raw_u16 = _hal.adc_read_u16(self._adc) # scaled to 0–65535
+        return self._state_to_value(raw_u16)   # upper logic unchanged
+
+    @property
+    def voltage(self):
+        return self.value * _hal.get_profile().ADC_VREF
+```
+
+### 5-C. Built-in objects renamed
+
+```python
+# picozero:  pico_led, pico_temp_sensor
+# espzero:
+esp_led         = LED("internal")          # profile resolves "internal" alias
+esp_temp_sensor = ESPTemperatureSensor()   # uses esp32.raw_temperature()
+```
+
+---
+
+## 6. ESP32-Specific Classes
+
+### 6-A. `WiFi` (`_wifi.py`)
+
+```python
+from espzero import WiFi
+
+wifi = WiFi()
+ip = wifi.connect("MySSID", "password", timeout=10)
+print("Connected:", ip)         # blocks until connected or raises OSError
+
+wifi.scan()                     # returns list of nearby APs
+wifi.is_connected               # True / False
+wifi.ip                         # current IP string
+wifi.disconnect()
+```
+
+> **Note:** After `connect()`, the HAL sets `_wifi_active = True` automatically.  
+> Any attempt to use an ADC2 pin after this will print a warning.
+
+### 6-B. `CapTouch` — Capacitive touch (`_touch.py`)
+
+```python
+from espzero import CapTouch
+
+touch = CapTouch(pin=4, threshold=300)  # GPIO 4 = T0 on WROOM
+if touch.is_touched:
+    print("Touched! Raw:", touch.value)
+```
+
+Unlike `TouchSensor` (which wraps an external TTP223 IC), `CapTouch` uses the ESP32's built-in capacitive touch peripheral directly. Available on pins T0–T9 of WROOM/WROVER modules.
+
+### 6-C. `NeoPixelLED` — Built-in RGB LED wrapper (`_core.py`)
+
+```python
+class NeoPixelLED:
+    """
+    Treats a single WS2812 pixel as a simple on/off LED.
+    Automatically used as esp_led on boards where INTERNAL_LED_TYPE == 'neopixel'
+    (e.g. ESP32-S3 DevKit GPIO 48, M5Stack ATOM GPIO 27).
+    """
+```
+
+---
+
+## 7. Safety Nets for Beginners
+
+espzero includes three runtime warnings designed to save beginners from common hardware pitfalls:
+
+| # | Trigger | Warning |
+|---|---------|---------|
+| 1 | Using an **ADC2 pin while WiFi is active** | `[espzero] WARNING: WiFi is active. ADC2 (GPIO N) cannot be used...` |
+| 2 | Attaching a **button to a strapping pin** | `[espzero] WARNING: GPIO N is a strapping pin. Boot issues may occur.` |
+| 3 | Running on **firmware < 1.19** (no `duty_u16`) | Silently falls back to `duty()` — no crash |
+
+---
+
+## 8. Supported Boards
+
+| Board | Built-in LED | ADC1 Pins | ADC2 Pins* | Touch Pins |
+|-------|-------------|-----------|------------|------------|
+| ESP32 DevKit V1 (WROOM) | GPIO 2 (active-low) | 32–39 | 0,2,4,12–15,25–27 | T0(4)–T9(32) |
+| ESP32-S3 DevKit | GPIO 48 (RGB) | 1–10 | 11–20 | T1–T14 |
+| ESP32-C3 Mini | GPIO 8 (active-low) | 0–4 | None | None |
+| M5Stack ATOM Lite | GPIO 27 (RGB) | 33,35,36 | 0,2,4,12–15,25–27 | T0(4),T3(15) |
+| Wemos D1 Mini32 | GPIO 2 (active-low) | 32–39 | 0,2,4,12–15,25–27 | T0(4)–T9(32) |
+| NodeMCU V3 Lolin (ESP8266) | GPIO 2 (active-low) | A0 only (10-bit, 0–1.0 V) | None | None |
+
+> \* ADC2 pins cannot be used while WiFi is active. For educational use, stick to ADC1 pins only.
+>
+> **ESP8266 ADC note:** A0 accepts 0–1.0 V only. Use a voltage divider (e.g. 220 kΩ + 100 kΩ) to measure 3.3 V signals safely.
+
+---
+
+## 9. Implementation Roadmap
+
+```
+Phase 1 — Core port (complete)
+  [x] profiles/_base.py         — BoardProfile abstract base class
+  [x] profiles/esp32_boards.py  — WROOM, S3, C3, M5Stack, Wemos profiles
+  [x] profiles/auto.py          — Runtime auto-detection
+  [x] _hal.py                   — HAL wrappers
+  [x] _core.py                  — Ported picozero core logic
+        · PWMOutputDevice: removed channel-collision check
+        · AnalogInputDevice: ADC read routed through HAL
+        · pico_led / pico_temp_sensor → esp_led / esp_temp_sensor
+  [x] __init__.py               — begin() + public API
+
+Phase 2 — ESP32-specific features (complete)
+  [x] _wifi.py                  — WiFi class
+  [x] _touch.py                 — CapTouch class
+  [x] Additional board profiles — S3, C3, M5Stack, Wemos
+
+Phase 3 — Mu Editor integration (complete)
+  [x] mu/resources/esp32/       — Library bundled with Mu Editor
+  [x] mu/logic.py               — esp32_lib auto-provisioned to mu_code/
+  [x] mu/interface/editor.py    — Jedi search path includes esp32_lib
+                                  (dynamic autocomplete via source analysis)
+```
+
+---
+
+## 10. Design Decisions
+
+| # | Topic | Decision |
+|---|-------|----------|
+| 1 | **ADC2 + WiFi warning** | `_hal.make_adc()` checks `_wifi_active` flag and prints a warning |
+| 2 | **`duty_u16()` fallback** | `_hal.set_duty_u16()` wrapper silently falls back to `duty(val>>6)` on firmware < 1.19 |
+| 3 | **Strapping pin warning** | `make_digital_in()` checks `STRAPPING_PINS` and prints a warning |
+| 4 | **NeoPixel built-in LED** | `INTERNAL_LED_TYPE = "neopixel"` profile field selects `NeoPixelLED` wrapper automatically |
+| 5 | **Lazy profile loading** | `_PROFILE_MAP` dict + `importlib` — only the selected board's module is imported |
+| 6 | **Autocomplete** | Jedi analyses live source in `mu/resources/esp32/` — no separate static API file needed |
+
+---
+
+## License
+
+MIT License — contributions welcome.  
+This library is part of the [Mu Editor](https://github.com/roboticsware/mu) project for educational IoT programming.

espzero-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+profiles/__init__.py,sha256=mDXtgRSz1isBGjbGM38SCNDtDIium3KoXxEkO3LQzd8,260
+profiles/_base.py,sha256=Qpt_GZyuUWxfbQ-SaCpV2tICVuRtqcnCwUdDdsSsP-Q,4345
+profiles/auto.py,sha256=r5k6XtuWuJ4NwnGNqTmnWF60Liow_quupyuZLVIApLY,2131
+profiles/esp32_boards.py,sha256=rrtHsULIH0TnTOjMXgCIyEehS94QitfcBEmJDRky1_o,8215
+espzero-0.0.1.dist-info/METADATA,sha256=7a9lJHtNibaYiXWXySKdZj2vqNbeqjGqd1GD70dy_hE,14298
+espzero-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+espzero-0.0.1.dist-info/top_level.txt,sha256=7AbhkLEJOzoiSyeUoPAwBlWoZ1vvIiBehEFDT3dsxpQ,9
+espzero-0.0.1.dist-info/RECORD,,

espzero-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

espzero-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+profiles

profiles/__init__.py

@@ -0,0 +1,5 @@
+# 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 profiles package

profiles/_base.py

@@ -0,0 +1,83 @@
+# 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/profiles/_base.py
+Abstract base class for all board profiles.
+
+Every board-specific profile inherits from BoardProfile and declares
+its hardware constants (pin aliases, ADC settings, strapping pins, etc.).
+The HAL and core logic read these constants at runtime so that no
+board-specific code ever leaks into _core.py.
+"""
+
+
+class BoardProfile:
+    """Abstract base class for all board profiles."""
+
+    NAME = "unknown"        # Human-readable board name
+    CHIP = "esp32"          # Chip family: esp32 / esp32s3 / esp32c3 / esp8266
+
+    # ── Pin aliases ───────────────────────────────────────────────
+    # Allows users to refer to pins by name (e.g. "internal", "led")
+    # instead of raw GPIO numbers.
+    PIN_ALIASES = {}
+
+    # ── ADC settings ──────────────────────────────────────────────
+    ADC_MAX_RAW = 4095      # 12-bit resolution (0–4095)
+    ADC_SCALE   = 65535     # Target scale for picozero compatibility (read_u16)
+    ADC_ATTEN   = None      # e.g. machine.ADC.ATTN_11DB; None = use firmware default
+    ADC_VREF    = 3.3       # Maximum input voltage (matches attenuation setting)
+
+    # ── PWM settings ──────────────────────────────────────────────
+    PWM_DEFAULT_FREQ = 1000     # Default PWM frequency in Hz (Pico used 100 Hz)
+    PWM_DUTY_MAX     = 65535    # Internal duty scale is always 16-bit
+    SERVO_FREQ       = 50       # Standard servo frequency: 50 Hz (20 ms frame)
+
+    # ── Built-in temperature sensor ───────────────────────────────
+    INTERNAL_TEMP_AVAILABLE = False
+
+    # ── Built-in LED type ─────────────────────────────────────────
+    # "digital"  – standard GPIO LED (on/off)
+    # "neopixel" – WS2812 RGB LED (e.g. ESP32-S3 DevKit, M5Stack ATOM)
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = True
+
+    # ── Boot strapping pins ───────────────────────────────────────
+    # Connecting a button or switch to these pins may cause boot failures
+    # or force the chip into download mode.
+    STRAPPING_PINS = []     # Example: [0, 2, 5, 12, 15]
+
+    # ── ADC2 pins (unavailable while WiFi is active) ──────────────
+    ADC2_PINS = []          # Example: [0, 2, 4, 12, 13, 14, 15, 25, 26, 27]
+
+    # ── Restricted pins (wired to internal flash — never use as GPIO) ──
+    # Driving these pins will corrupt flash memory and hang the system.
+    RESTRICTED_PINS = []    # Example: [6, 7, 8, 9, 10, 11]
+
+    # ─────────────────────────────────────────────────────────────
+
+    def resolve_pin(self, pin):
+        """Resolve a string alias or integer to a GPIO number."""
+        if isinstance(pin, str):
+            if pin in self.PIN_ALIASES:
+                return self.PIN_ALIASES[pin]
+            raise ValueError(
+                "Unknown pin alias '{}' for board '{}'. "
+                "Available aliases: {}".format(pin, self.NAME, list(self.PIN_ALIASES.keys()))
+            )
+        return int(pin)
+
+    def make_adc(self, gpio_num):
+        """Create an ADC object for the given GPIO, applying attenuation if configured."""
+        from machine import ADC, Pin
+        adc = ADC(Pin(gpio_num))
+        if self.ADC_ATTEN is not None:
+            adc.atten(self.ADC_ATTEN)
+        return adc
+
+    def adc_read_u16(self, adc_obj):
+        """Read raw 12-bit ADC value and scale it to 0–65535 for picozero compatibility."""
+        raw = adc_obj.read()   # 0–4095
+        return (raw * self.ADC_SCALE) // self.ADC_MAX_RAW

profiles/auto.py

@@ -0,0 +1,50 @@
+# 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/profiles/auto.py
+Runtime board auto-detection.
+
+Inspects sys.implementation._machine to identify the chip and returns
+the matching board profile key used in espzero._PROFILE_MAP.
+"""
+import sys
+
+
+def detect():
+    """
+    Detect the current board at runtime by inspecting sys.implementation._machine.
+
+    Returns a board key string that corresponds to an entry in
+    espzero._PROFILE_MAP (e.g. 'esp32_38pin_nodemcu').
+    Falls back to 'esp32_38pin_nodemcu' (38-pin NodeMCU) if detection fails.
+
+    Note: ESP32 DevKit V1 (30-pin) and ESP32 38-Pin NodeMCU share the same
+    WROOM-32 chip and firmware, so they cannot be distinguished at runtime.
+    The 38-pin NodeMCU is used as the generic ESP32 fallback because:
+      1. It is the more widely available board in the target region.
+      2. Its profile includes RESTRICTED_PINS [6-11] safety protection.
+    If your board is a 30-pin DevKit V1, call espzero.begin('esp32_devkit_v1')
+    explicitly to use its profile (active-low LED, no RESTRICTED_PINS).
+    """
+    try:
+        machine_str = sys.implementation._machine.lower()
+    except AttributeError:
+        machine_str = ""
+
+    if "esp32s3" in machine_str or "esp32-s3" in machine_str:
+        return "esp32_s3_devkit"
+    elif "esp32c3" in machine_str or "esp32-c3" in machine_str:
+        return "esp32_c3_mini"
+    elif "esp8266" in machine_str:
+        return "esp8266_lolin_v3"
+    elif "esp32" in machine_str:
+        # Cannot distinguish 38-pin NodeMCU from DevKit V1 — same WROOM-32 chip.
+        # Default to 38-pin NodeMCU (more common; includes flash-pin safety guard).
+        return "esp32_38pin_nodemcu"
+    else:
+        print("[espzero] WARNING: Could not auto-detect board. "
+              "Falling back to 'esp32_38pin_nodemcu' profile. "
+              "Call espzero.begin('<board_name>') to specify your board.")
+        return "esp32_38pin_nodemcu"

profiles/esp32_boards.py

@@ -0,0 +1,254 @@
+"""
+espzero/profiles/esp32_boards.py
+Board profile definitions for common ESP32-family boards.
+
+Each class declares the hardware constants for one board variant.
+Add new boards here by subclassing BoardProfile and overriding the
+relevant fields.
+"""
+from ._base import BoardProfile
+
+
+# --- ADC attenuation helper -------------------------------------
+# Imported lazily so the profiles module can be parsed on the host
+# (e.g. for IDE support) without requiring machine to be available.
+def _atten():
+    try:
+        from machine import ADC
+        return ADC.ATTN_11DB
+    except Exception:
+        return None
+
+
+# --------------------------------------------------------------
+# ESP32 DevKit V1 / WROOM-32
+# --------------------------------------------------------------
+class ESP32DevKitV1(BoardProfile):
+    """
+    Espressif ESP32 DevKit V1 (WROOM-32).
+    Built-in LED: GPIO 2 (active-low, blue).
+    ADC1: GPIO 32-39   ADC2: GPIO 0, 2, 4, 12-15, 25-27 (unusable with WiFi)
+    Strapping pins: GPIO 0, 2, 5, 12, 15
+    """
+    NAME = "esp32_devkit_v1"
+    CHIP = "esp32"
+
+    PIN_ALIASES = {
+        "internal": 2,
+        "led":      2,
+    }
+
+    ADC_ATTEN            = _atten()
+    ADC_VREF             = 3.6
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = False   # active-low
+    STRAPPING_PINS       = [0, 2, 5, 12, 15]
+    ADC2_PINS            = [0, 2, 4, 12, 13, 14, 15, 25, 26, 27]
+
+
+# --------------------------------------------------------------
+# ESP32-S3 DevKit-C
+# --------------------------------------------------------------
+class ESP32S3DevKit(BoardProfile):
+    """
+    Espressif ESP32-S3 DevKitC-1.
+    Built-in LED: GPIO 48 (WS2812 NeoPixel RGB).
+    ADC1: GPIO 1-10    ADC2: GPIO 11-20 (unusable with WiFi)
+    Strapping pins: GPIO 0, 3, 45, 46
+    """
+    NAME = "esp32_s3_devkit"
+    CHIP = "esp32s3"
+
+    PIN_ALIASES = {
+        "internal": 48,
+        "led":      48,
+    }
+
+    ADC_ATTEN            = _atten()
+    ADC_VREF             = 3.6
+    INTERNAL_LED_TYPE        = "neopixel"
+    INTERNAL_LED_ACTIVE_HIGH = True
+    STRAPPING_PINS       = [0, 3, 45, 46]
+    ADC2_PINS            = [11, 12, 13, 14, 15, 16, 17, 18, 19, 20]
+
+
+# --------------------------------------------------------------
+# ESP32-C3 Mini / SuperMini
+# --------------------------------------------------------------
+class ESP32C3Mini(BoardProfile):
+    """
+    ESP32-C3 Mini / SuperMini.
+    Built-in LED: GPIO 8 (active-low).
+    ADC1 only: GPIO 0-4. No ADC2 channel.
+    Strapping pins: GPIO 2, 8, 9
+    """
+    NAME = "esp32_c3_mini"
+    CHIP = "esp32c3"
+
+    PIN_ALIASES = {
+        "internal": 8,
+        "led":      8,
+    }
+
+    ADC_ATTEN            = _atten()
+    ADC_VREF             = 3.6
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = False   # active-low
+    STRAPPING_PINS       = [2, 8, 9]
+    ADC2_PINS            = []          # C3 has no ADC2
+
+
+# --------------------------------------------------------------
+# M5Stack ATOM Lite / Matrix
+# --------------------------------------------------------------
+class M5StackAtom(BoardProfile):
+    """
+    M5Stack ATOM Lite / Matrix.
+    Built-in LED: GPIO 27 (WS2812 NeoPixel).
+    Built-in button: GPIO 39 (G39).
+    """
+    NAME = "m5stack_atom"
+    CHIP = "esp32"
+
+    PIN_ALIASES = {
+        "internal": 27,
+        "led":      27,
+        "btn":      39,    # Built-in button (G39)
+    }
+
+    ADC_ATTEN            = _atten()
+    ADC_VREF             = 3.6
+    INTERNAL_LED_TYPE        = "neopixel"
+    INTERNAL_LED_ACTIVE_HIGH = True
+    STRAPPING_PINS       = [0, 2, 5, 12, 15]
+    ADC2_PINS            = [0, 2, 4, 12, 13, 14, 15, 25, 26, 27]
+
+
+# --------------------------------------------------------------
+# Wemos D1 Mini32 (ESP32)
+# --------------------------------------------------------------
+class WemosD1Mini32(BoardProfile):
+    """Wemos / LOLIN D1 Mini32."""
+    NAME = "wemos_d1_mini32"
+    CHIP = "esp32"
+
+    PIN_ALIASES = {
+        "internal": 2,
+        "led":      2,
+    }
+
+    ADC_ATTEN            = _atten()
+    ADC_VREF             = 3.6
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = False
+    STRAPPING_PINS       = [0, 2, 5, 12, 15]
+    ADC2_PINS            = [0, 2, 4, 12, 13, 14, 15, 25, 26, 27]
+
+
+# --------------------------------------------------------------
+# NodeMCU V3 Lolin (ESP8266)
+# --------------------------------------------------------------
+class ESP8266LolinV3(BoardProfile):
+    """
+    NodeMCU V3 Lolin (ESP8266).
+    Built-in LED: GPIO 2 (active-low, blue).
+    Single ADC: A0 only — 10-bit (0-1023).
+      The Lolin V3 board includes an on-board voltage divider (220 kΩ / 100 kΩ)
+      that extends the A0 input range from the bare ESP8266's 0-1.0 V to 0-3.3 V.
+      ADC_VREF is therefore 3.3 V for this board.
+    D-pin labels on the silkscreen differ from GPIO numbers;
+    use the D0-D8 aliases so user code matches the board labels.
+    Standard I2C: SDA=D2 (GPIO 4), SCL=D1 (GPIO 5).
+    No ADC2 group, no TouchPad, no ATTN setting.
+    """
+    NAME = "esp8266_lolin_v3"
+    CHIP = "esp8266"
+
+    PIN_ALIASES = {
+        # Silkscreen label → GPIO number
+        "D0": 16, "D1": 5,  "D2": 4,  "D3": 0,
+        "D4": 2,  "D5": 14, "D6": 12, "D7": 13,
+        "D8": 15, "RX": 3,  "TX": 1,
+        # Analog pin (the only ADC input)
+        "A0": 0,
+        # Built-in LED aliases
+        "internal": 2,
+        "led":      2,
+        # Standard I2C bus (matches Arduino/MicroPython convention for Lolin V3)
+        "sda": 4,   # D2
+        "scl": 5,   # D1
+    }
+
+    # 10-bit ADC (0-1023). Lolin V3 on-board divider extends range to 3.3 V.
+    ADC_MAX_RAW = 1023
+    ADC_ATTEN   = None      # ESP8266 has no attenuation register
+    ADC_VREF    = 3.3       # 0–3.3 V thanks to the Lolin V3 voltage divider
+
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = False    # active-low
+
+    # ESP8266 boots from GPIO 0/2/15 — warn users who attach buttons there
+    STRAPPING_PINS = [0, 2, 15]
+
+    # ESP8266 has only one ADC channel; WiFi/ADC conflict exists but is
+    # different from ESP32 (cannot read ADC during WiFi TX bursts).
+    ADC2_PINS = []
+
+    def make_adc(self, gpio_num):
+        """
+        ESP8266 ADC: only one channel exists, always accessed as ADC(0).
+        The gpio_num argument is accepted for API compatibility but ignored.
+        """
+        from machine import ADC
+        return ADC(0)   # channel 0 = A0 pin, the sole ADC input on ESP8266
+
+
+# --------------------------------------------------------------
+# ESP32 38-Pin NodeMCU (Type-C / Micro-USB combo)
+# --------------------------------------------------------------
+class ESP32_38Pin_NodeMCU(BoardProfile):
+    """
+    ESP32 38-Pin NodeMCU development board (Type-C & Micro-USB combo).
+
+    Built-in LED: GPIO 1 (TX pin — lit during communication, but works as GPIO).
+    I2C defaults: SDA=GPIO 21, SCL=GPIO 22.
+    BOOT button: GPIO 0.
+
+    GPIO 6-11 are internally wired to the SPI flash memory.
+    Driving them as GPIO will corrupt flash and hang the system.
+    Safe user GPIOs: 1-5, 12-23, 25-27, 32-39
+      (34, 35, 36, 39 are input-only — no internal pull-up/down).
+
+    ADC1: GPIO 32-39   ADC2: GPIO 0, 2, 4, 12-15, 25-27 (unusable with WiFi)
+    Strapping pins: GPIO 0, 2, 5, 12, 15
+    """
+    NAME = "esp32_38pin_nodemcu"
+    CHIP = "esp32"
+
+    PIN_ALIASES = {
+        # Built-in LED (Mapped to GPIO 1 TX pin as per user test)
+        "internal":    1,
+        "led":         1,
+        "builtin_led": 1,
+        # Built-in BOOT button
+        "button": 0,
+        # Standard I2C bus
+        "sda": 21,
+        "scl": 22,
+    }
+
+    ADC_ATTEN = _atten()    # ATTN_11DB → 0–3.6 V range
+    ADC_VREF  = 3.6
+
+    # This board's built-in LED is active-LOW (0 = on)
+    INTERNAL_LED_TYPE        = "digital"
+    INTERNAL_LED_ACTIVE_HIGH = False
+
+    # Boot strapping pins — attaching buttons here may cause boot failures
+    STRAPPING_PINS = [0, 2, 5, 12, 15]
+
+    # ADC2 pins — cannot be read while WiFi is active
+    ADC2_PINS = [0, 2, 4, 12, 13, 14, 15, 25, 26, 27]
+
+    # Flash-memory pins — NEVER use as GPIO; doing so corrupts flash
+    RESTRICTED_PINS = [6, 7, 8, 9, 10, 11]