bcmio 0.1.0__tar.gz

bcmio-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: bcmio
+Version: 0.1.0
+Summary: Low-level GPIO library for Raspberry Pi 4 (BCM2711) using /dev/mem + mmap
+Author: bcmio contributors
+License: MIT
+Keywords: raspberrypi,gpio,bcm2711,mmap,embedded,linux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+
+# bcmio
+
+Biblioteca Python **low-level** para controle de GPIO do **Raspberry Pi 4 Model B (BCM2711)** usando
+**acesso direto a registradores via `mmap`** e **`/dev/mem`** (MMIO).
+
+> Aviso: acessar `/dev/mem` normalmente requer **root** (`sudo`). Use com cuidado: MMIO incorreto pode
+> travar o sistema.
+
+## Objetivos
+
+- Performance: escrita/leitura direto em registradores (`GPSET/GPCLR/GPLEV`)
+- Arquitetura modular: separar low-level (MMIO/registradores) e high-level (abstrações)
+- API familiar (inspirada em RPi.GPIO/pigpio/gpiozero), mas **sem dependências** dessas bibliotecas
+- Código tipado, com docstrings, pronto para evoluir para PWM/SPI/I2C/UART/interrupts/DMA
+
+## Arquitetura (módulos)
+
+- `bcmio/memory.py`: abertura de `/dev/mem`, `mmap`, leitura/escrita 32-bit
+- `bcmio/constants.py`: offsets e constantes (GPIO modes, pulls, endereços base)
+- `bcmio/gpio.py`: acesso aos registradores GPIO (FSEL, SET/CLR, LEV, PULL)
+- `bcmio/pin.py`: classe `Pin` (alto nível) para um pino individual
+- `bcmio/exceptions.py`: exceções customizadas
+- `bcmio/utils.py`: helpers (validação, bit operations)
+- `bcmio/pwm.py`, `bcmio/interrupts.py`: placeholders para evolução
+
+## Como `mmap` funciona (visão geral)
+
+1. Abrimos `/dev/mem` (arquivo especial que expõe memória física do SoC).
+2. Fazemos `mmap` de uma página (ou mais) a partir do **endereço físico** dos periféricos GPIO.
+3. A partir do ponteiro mapeado, fazemos leituras/escritas de 32 bits em offsets específicos.
+
+No Linux, isso é MMIO (Memory Mapped I/O): escrever em um registrador mapeado altera o hardware.
+
+## Endereços base (BCM2711)
+
+O datasheet usa endereços no **barramento** (bus) como `0x7E200000` para o bloco GPIO. No Raspberry Pi 4,
+o endereço **físico** tipicamente é `0xFE200000` (peripheral base `0xFE000000` + GPIO offset `0x200000`).
+
+Esta biblioteca:
+
+- expõe ambos em `bcmio.constants` (`GPIO_BASE_BUS`, `GPIO_BASE_PHYS_DEFAULT`)
+- por padrão usa o **físico** (`0xFE200000`)
+- permite sobrescrever o endereço base via `GPIO.open(base_phys=...)`
+
+## Registradores GPIO usados (BCM2711)
+
+Offsets relativos ao base do GPIO (bloco `GPIO`):
+
+- `GPFSEL0..5` (Function Select): 3 bits por pino para definir `IN`, `OUT`, ou função alternativa
+- `GPSET0..1` (Set): escrever `1` no bit seta o pino em nível alto (atômico)
+- `GPCLR0..1` (Clear): escrever `1` no bit seta o pino em nível baixo (atômico)
+- `GPLEV0..1` (Level): lê o nível atual do pino
+- `GPIO_PUP_PDN_CNTRL_REG0..3`: 2 bits por pino para pull-up/pull-down/no-pull (BCM2711)
+
+## Uso
+
+### API estilo “módulo” (`GPIO`)
+
+```python
+from bcmio import GPIO
+
+GPIO.open()                       # inicializa /dev/mem + mmap
+GPIO.setup(17, GPIO.OUT, pull=GPIO.PULL_NONE)
+GPIO.write(17, GPIO.HIGH)
+value = GPIO.read(17)
+GPIO.cleanup()
+```
+
+### API orientada a objeto (`Pin`)
+
+```python
+from bcmio import Pin
+
+led = Pin(17, mode=Pin.OUT)
+led.high()
+led.low()
+led.toggle()
+led.close()
+```
+
+## Exemplos
+
+Veja `exemplos/`:
+
+- `exemplos/blink.py`
+- `exemplos/button_read.py`
+- `exemplos/toggle.py`
+- `exemplos/read_digital.py`
+
+## Testes
+
+Os testes em `testes/` não acessam `/dev/mem`. Eles usam um backend fake de memória para validar:
+
+- cálculo de offsets e bitfields de `GPFSEL`
+- `GPSET/GPCLR` e leitura em `GPLEV`
+- configuração de pull em `GPIO_PUP_PDN_CNTRL_REGx`
+
+Rodar:
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+## Segurança e boas práticas
+
+- Use `sudo` apenas quando necessário.
+- Prefira isolar e revisar o endereço base antes de usar em produção.
+- Em produção, considere um modo “safe” ou `/dev/gpiomem` (não implementado aqui por requisito).
+

bcmio-0.1.0/README.md

@@ -0,0 +1,110 @@
+# bcmio
+
+Biblioteca Python **low-level** para controle de GPIO do **Raspberry Pi 4 Model B (BCM2711)** usando
+**acesso direto a registradores via `mmap`** e **`/dev/mem`** (MMIO).
+
+> Aviso: acessar `/dev/mem` normalmente requer **root** (`sudo`). Use com cuidado: MMIO incorreto pode
+> travar o sistema.
+
+## Objetivos
+
+- Performance: escrita/leitura direto em registradores (`GPSET/GPCLR/GPLEV`)
+- Arquitetura modular: separar low-level (MMIO/registradores) e high-level (abstrações)
+- API familiar (inspirada em RPi.GPIO/pigpio/gpiozero), mas **sem dependências** dessas bibliotecas
+- Código tipado, com docstrings, pronto para evoluir para PWM/SPI/I2C/UART/interrupts/DMA
+
+## Arquitetura (módulos)
+
+- `bcmio/memory.py`: abertura de `/dev/mem`, `mmap`, leitura/escrita 32-bit
+- `bcmio/constants.py`: offsets e constantes (GPIO modes, pulls, endereços base)
+- `bcmio/gpio.py`: acesso aos registradores GPIO (FSEL, SET/CLR, LEV, PULL)
+- `bcmio/pin.py`: classe `Pin` (alto nível) para um pino individual
+- `bcmio/exceptions.py`: exceções customizadas
+- `bcmio/utils.py`: helpers (validação, bit operations)
+- `bcmio/pwm.py`, `bcmio/interrupts.py`: placeholders para evolução
+
+## Como `mmap` funciona (visão geral)
+
+1. Abrimos `/dev/mem` (arquivo especial que expõe memória física do SoC).
+2. Fazemos `mmap` de uma página (ou mais) a partir do **endereço físico** dos periféricos GPIO.
+3. A partir do ponteiro mapeado, fazemos leituras/escritas de 32 bits em offsets específicos.
+
+No Linux, isso é MMIO (Memory Mapped I/O): escrever em um registrador mapeado altera o hardware.
+
+## Endereços base (BCM2711)
+
+O datasheet usa endereços no **barramento** (bus) como `0x7E200000` para o bloco GPIO. No Raspberry Pi 4,
+o endereço **físico** tipicamente é `0xFE200000` (peripheral base `0xFE000000` + GPIO offset `0x200000`).
+
+Esta biblioteca:
+
+- expõe ambos em `bcmio.constants` (`GPIO_BASE_BUS`, `GPIO_BASE_PHYS_DEFAULT`)
+- por padrão usa o **físico** (`0xFE200000`)
+- permite sobrescrever o endereço base via `GPIO.open(base_phys=...)`
+
+## Registradores GPIO usados (BCM2711)
+
+Offsets relativos ao base do GPIO (bloco `GPIO`):
+
+- `GPFSEL0..5` (Function Select): 3 bits por pino para definir `IN`, `OUT`, ou função alternativa
+- `GPSET0..1` (Set): escrever `1` no bit seta o pino em nível alto (atômico)
+- `GPCLR0..1` (Clear): escrever `1` no bit seta o pino em nível baixo (atômico)
+- `GPLEV0..1` (Level): lê o nível atual do pino
+- `GPIO_PUP_PDN_CNTRL_REG0..3`: 2 bits por pino para pull-up/pull-down/no-pull (BCM2711)
+
+## Uso
+
+### API estilo “módulo” (`GPIO`)
+
+```python
+from bcmio import GPIO
+
+GPIO.open()                       # inicializa /dev/mem + mmap
+GPIO.setup(17, GPIO.OUT, pull=GPIO.PULL_NONE)
+GPIO.write(17, GPIO.HIGH)
+value = GPIO.read(17)
+GPIO.cleanup()
+```
+
+### API orientada a objeto (`Pin`)
+
+```python
+from bcmio import Pin
+
+led = Pin(17, mode=Pin.OUT)
+led.high()
+led.low()
+led.toggle()
+led.close()
+```
+
+## Exemplos
+
+Veja `exemplos/`:
+
+- `exemplos/blink.py`
+- `exemplos/button_read.py`
+- `exemplos/toggle.py`
+- `exemplos/read_digital.py`
+
+## Testes
+
+Os testes em `testes/` não acessam `/dev/mem`. Eles usam um backend fake de memória para validar:
+
+- cálculo de offsets e bitfields de `GPFSEL`
+- `GPSET/GPCLR` e leitura em `GPLEV`
+- configuração de pull em `GPIO_PUP_PDN_CNTRL_REGx`
+
+Rodar:
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+## Segurança e boas práticas
+
+- Use `sudo` apenas quando necessário.
+- Prefira isolar e revisar o endereço base antes de usar em produção.
+- Em produção, considere um modo “safe” ou `/dev/gpiomem` (não implementado aqui por requisito).
+

bcmio-0.1.0/bcmio/__init__.py

@@ -0,0 +1,16 @@
+"""
+`bcmio` - GPIO low-level for Raspberry Pi 4 (BCM2711) using /dev/mem + mmap.
+
+Public API:
+  - GPIO: module-style API (class with classmethods)
+  - Pin: high-level per-pin abstraction
+"""
+
+from __future__ import annotations
+
+from .gpio import GPIO
+from .pin import Pin
+
+__version__ = "0.1.0"
+
+__all__ = ["GPIO", "Pin", "__version__"]

bcmio-0.1.0/bcmio/constants.py

@@ -0,0 +1,93 @@
+"""
+Constants and register offsets for BCM2711 GPIO.
+
+Notes about addresses:
+  - Datasheets often describe GPIO bus address as 0x7E200000.
+  - On Raspberry Pi 4 (BCM2711), physical peripheral base is typically 0xFE000000.
+    So GPIO physical base is typically 0xFE200000.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# --- Base addresses ---
+
+# GPIO base address as shown in the peripherals documentation (bus address)
+GPIO_BASE_BUS: int = 0x7E200000
+
+# Default physical base address for Raspberry Pi 4 (BCM2711).
+# This is the typical address used with /dev/mem mappings.
+GPIO_BASE_PHYS_DEFAULT: int = 0xFE200000
+
+# --- Register offsets (relative to GPIO base) ---
+
+GPFSEL0: int = 0x00
+GPFSEL1: int = 0x04
+GPFSEL2: int = 0x08
+GPFSEL3: int = 0x0C
+GPFSEL4: int = 0x10
+GPFSEL5: int = 0x14
+
+GPSET0: int = 0x1C
+GPSET1: int = 0x20
+
+GPCLR0: int = 0x28
+GPCLR1: int = 0x2C
+
+GPLEV0: int = 0x34
+GPLEV1: int = 0x38
+
+# BCM2711 pull-up/down control registers (2 bits per GPIO)
+GPIO_PUP_PDN_CNTRL_REG0: int = 0xE4
+GPIO_PUP_PDN_CNTRL_REG1: int = 0xE8
+GPIO_PUP_PDN_CNTRL_REG2: int = 0xEC
+GPIO_PUP_PDN_CNTRL_REG3: int = 0xF0
+
+
+@dataclass(frozen=True, slots=True)
+class PinMode:
+    """GPIO function select values (3-bit fields in GPFSEL registers)."""
+
+    IN: int = 0b000
+    OUT: int = 0b001
+
+    # Alternate function values (kept for extensibility)
+    ALT0: int = 0b100
+    ALT1: int = 0b101
+    ALT2: int = 0b110
+    ALT3: int = 0b111
+    ALT4: int = 0b011
+    ALT5: int = 0b010
+
+
+@dataclass(frozen=True, slots=True)
+class LogicLevel:
+    """Logical levels."""
+
+    LOW: int = 0
+    HIGH: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class Pull:
+    """
+    Pull configuration values (2-bit fields in GPIO_PUP_PDN_CNTRL_REGx).
+
+    BCM2711 encoding (per pin):
+      00 = No resistor
+      01 = Pull-up
+      10 = Pull-down
+      11 = Reserved
+    """
+
+    NONE: int = 0b00
+    UP: int = 0b01
+    DOWN: int = 0b10
+
+
+GPIO_MIN: int = 0
+GPIO_MAX: int = 53  # BCM2711 exposes GPIO0..GPIO53 (some are not on header).
+
+REGISTER_SIZE_BYTES: int = 4
+

bcmio-0.1.0/bcmio/exceptions.py

@@ -0,0 +1,28 @@
+"""Custom exceptions for bcmio."""
+
+from __future__ import annotations
+
+
+class BCMIOError(RuntimeError):
+    """Base error for bcmio."""
+
+
+class PermissionDeniedError(BCMIOError):
+    """Raised when /dev/mem cannot be opened due to insufficient permissions."""
+
+
+class DeviceNotFoundError(BCMIOError):
+    """Raised when expected device file is missing (e.g. /dev/mem)."""
+
+
+class NotInitializedError(BCMIOError):
+    """Raised when GPIO is used before initialization/open()."""
+
+
+class InvalidPinError(ValueError, BCMIOError):
+    """Raised when a GPIO pin number is invalid."""
+
+
+class MMIOMapError(BCMIOError):
+    """Raised when mmap fails or MMIO access cannot be established."""
+

bcmio-0.1.0/bcmio/gpio.py

@@ -0,0 +1,231 @@
+"""
+GPIO register access for BCM2711.
+
+Implements:
+  - function select (input/output)
+  - atomic set/clear
+  - level read
+  - pull-up/pull-down configuration via GPIO_PUP_PDN_CNTRL_REG0..3 (BCM2711)
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from threading import RLock
+from typing import Optional
+
+from .constants import (
+    GPIO_BASE_PHYS_DEFAULT,
+    GPIO_MAX,
+    GPFSEL0,
+    GPCLR0,
+    GPLEV0,
+    GPSET0,
+    GPIO_PUP_PDN_CNTRL_REG0,
+    LogicLevel,
+    PinMode,
+    Pull,
+)
+from .exceptions import NotInitializedError
+from .memory import FakeMMIORegion, MemoryBackend, open_gpio_region
+from .utils import bit_mask, replace_field, validate_gpio_pin
+
+logger = logging.getLogger(__name__)
+
+
+GPIO_BLOCK_SIZE: int = 0x1000  # enough to cover up to 0xF0 registers
+
+
+def _fsel_reg_and_shift(pin: int) -> tuple[int, int]:
+    # Each GPFSEL register controls 10 pins, 3 bits per pin.
+    reg_index = pin // 10  # 0..5
+    shift = (pin % 10) * 3
+    offset = GPFSEL0 + (reg_index * 4)
+    return offset, shift
+
+
+def _setclr_reg_and_bit(pin: int, base_offset: int) -> tuple[int, int]:
+    # GPSET0/GPCLR0 cover pins 0..31, GPSET1/GPCLR1 cover 32..53.
+    reg_index = pin // 32  # 0 or 1
+    bit = pin % 32
+    offset = base_offset + (reg_index * 4)
+    return offset, bit
+
+
+def _lev_reg_and_bit(pin: int) -> tuple[int, int]:
+    reg_index = pin // 32
+    bit = pin % 32
+    offset = GPLEV0 + (reg_index * 4)
+    return offset, bit
+
+
+def _pull_reg_and_shift(pin: int) -> tuple[int, int]:
+    # BCM2711: 2 bits per pin, 16 pins per 32-bit register.
+    reg_index = pin // 16  # 0..3
+    shift = (pin % 16) * 2
+    offset = GPIO_PUP_PDN_CNTRL_REG0 + (reg_index * 4)
+    return offset, shift
+
+
+@dataclass(slots=True)
+class GPIOConfig:
+    base_phys: int = GPIO_BASE_PHYS_DEFAULT
+    devmem_path: str = "/dev/mem"
+
+
+class GPIO:
+    """
+    Module-style API for GPIO access.
+
+    This class manages a single global MMIO mapping (per-process) for simplicity.
+    """
+
+    IN: int = PinMode().IN
+    OUT: int = PinMode().OUT
+
+    LOW: int = LogicLevel().LOW
+    HIGH: int = LogicLevel().HIGH
+
+    PULL_NONE: int = Pull().NONE
+    PULL_UP: int = Pull().UP
+    PULL_DOWN: int = Pull().DOWN
+
+    _lock = RLock()
+    _region: Optional[MemoryBackend] = None
+    _config: GPIOConfig = GPIOConfig()
+
+    @classmethod
+    def open(
+        cls,
+        *,
+        base_phys: int = GPIO_BASE_PHYS_DEFAULT,
+        devmem_path: str = "/dev/mem",
+        backend: Optional[MemoryBackend] = None,
+    ) -> None:
+        """
+        Initialize MMIO mapping for GPIO.
+
+        Pass `backend` only for tests (e.g. FakeMMIORegion).
+        """
+        with cls._lock:
+            if cls._region is not None:
+                return
+            cls._config = GPIOConfig(base_phys=base_phys, devmem_path=devmem_path)
+            if backend is None:
+                cls._region = open_gpio_region(base_phys=base_phys, size=GPIO_BLOCK_SIZE, devmem_path=devmem_path)
+            else:
+                cls._region = open_gpio_region(base_phys=base_phys, size=GPIO_BLOCK_SIZE, backend=backend)
+            logger.info("GPIO MMIO opened at phys=0x%X (%s)", base_phys, devmem_path)
+
+    @classmethod
+    def is_open(cls) -> bool:
+        return cls._region is not None
+
+    @classmethod
+    def _require_open(cls) -> MemoryBackend:
+        if cls._region is None:
+            raise NotInitializedError("GPIO not initialized. Call GPIO.open() first.")
+        return cls._region
+
+    @classmethod
+    def close(cls) -> None:
+        """Unmap and close the MMIO region."""
+        with cls._lock:
+            if cls._region is None:
+                return
+            try:
+                cls._region.close()
+            finally:
+                cls._region = None
+            logger.info("GPIO MMIO closed")
+
+    @classmethod
+    def cleanup(cls) -> None:
+        """Alias for close()."""
+        cls.close()
+
+    @classmethod
+    def setup(cls, pin: int, mode: int, *, pull: int = Pull().NONE) -> None:
+        """Configure pin function (IN/OUT) and pull resistor."""
+        validate_gpio_pin(pin)
+        if mode not in (cls.IN, cls.OUT):
+            raise ValueError(f"Invalid mode: {mode}")
+        if pull not in (cls.PULL_NONE, cls.PULL_UP, cls.PULL_DOWN):
+            raise ValueError(f"Invalid pull: {pull}")
+
+        with cls._lock:
+            region = cls._require_open()
+            fsel_off, shift = _fsel_reg_and_shift(pin)
+            cur = region.read32(fsel_off)
+            cur = replace_field(cur, field_mask=0b111, field_value=mode, shift=shift)
+            region.write32(fsel_off, cur)
+
+            # Pull is independent of mode on BCM2711
+            cls._set_pull_locked(region, pin, pull)
+
+    @classmethod
+    def _set_pull_locked(cls, region: MemoryBackend, pin: int, pull: int) -> None:
+        off, shift = _pull_reg_and_shift(pin)
+        cur = region.read32(off)
+        cur = replace_field(cur, field_mask=0b11, field_value=pull, shift=shift)
+        region.write32(off, cur)
+
+    @classmethod
+    def set_pull(cls, pin: int, pull: int) -> None:
+        """Configure pull resistor for a pin (PULL_NONE, PULL_UP, PULL_DOWN)."""
+        validate_gpio_pin(pin)
+        if pull not in (cls.PULL_NONE, cls.PULL_UP, cls.PULL_DOWN):
+            raise ValueError(f"Invalid pull: {pull}")
+        with cls._lock:
+            region = cls._require_open()
+            cls._set_pull_locked(region, pin, pull)
+
+    @classmethod
+    def write(cls, pin: int, value: int) -> None:
+        """Write a logical level using atomic GPSET/GPCLR registers."""
+        validate_gpio_pin(pin)
+        if value not in (cls.LOW, cls.HIGH):
+            raise ValueError(f"Invalid value: {value}")
+
+        with cls._lock:
+            region = cls._require_open()
+            if value == cls.HIGH:
+                off, bit = _setclr_reg_and_bit(pin, GPSET0)
+            else:
+                off, bit = _setclr_reg_and_bit(pin, GPCLR0)
+            region.write32(off, bit_mask(bit))
+
+    @classmethod
+    def high(cls, pin: int) -> None:
+        cls.write(pin, cls.HIGH)
+
+    @classmethod
+    def low(cls, pin: int) -> None:
+        cls.write(pin, cls.LOW)
+
+    @classmethod
+    def read(cls, pin: int) -> int:
+        """Read the pin level from GPLEV registers."""
+        validate_gpio_pin(pin)
+        with cls._lock:
+            region = cls._require_open()
+            off, bit = _lev_reg_and_bit(pin)
+            level = region.read32(off)
+            return cls.HIGH if (level & bit_mask(bit)) else cls.LOW
+
+    @classmethod
+    def toggle(cls, pin: int) -> int:
+        """Toggle pin output based on current level. Returns new level."""
+        current = cls.read(pin)
+        new = cls.LOW if current == cls.HIGH else cls.HIGH
+        cls.write(pin, new)
+        return new
+
+    # --- Convenience for tests ---
+    @classmethod
+    def _open_fake(cls) -> FakeMMIORegion:
+        fake = FakeMMIORegion(GPIO_BLOCK_SIZE)
+        cls.open(backend=fake)
+        return fake
+

bcmio-0.1.0/bcmio/interrupts.py

@@ -0,0 +1,9 @@
+"""Interrupts placeholder (future work)."""
+
+from __future__ import annotations
+
+
+class Interrupts:  # pragma: no cover
+    def __init__(self, *args: object, **kwargs: object) -> None:
+        raise NotImplementedError("Interrupts not implemented yet. Planned module placeholder.")
+

bcmio-0.1.0/bcmio/memory.py

@@ -0,0 +1,208 @@
+"""
+Memory-mapped I/O helpers for BCM2711 peripherals via /dev/mem.
+
+This module intentionally focuses on:
+  - opening /dev/mem
+  - mapping a physical address range with mmap
+  - reading/writing 32-bit little-endian registers
+
+It is kept separate from GPIO logic to enable future modules (PWM/SPI/I2C/UART/DMA).
+"""
+
+from __future__ import annotations
+
+import logging
+import mmap
+import os
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+from .exceptions import DeviceNotFoundError, MMIOMapError, PermissionDeniedError
+
+logger = logging.getLogger(__name__)
+
+
+def _page_align(addr: int, page_size: int) -> tuple[int, int]:
+    base = addr - (addr % page_size)
+    offset = addr - base
+    return base, offset
+
+
+@dataclass(slots=True)
+class MMIORegion:
+    """
+    Represents a mapped MMIO region.
+
+    `base_phys` is the physical base address requested (not page-aligned).
+    """
+
+    base_phys: int
+    size: int
+    _fd: int
+    _mmap: mmap.mmap
+    _offset: int
+
+    def close(self) -> None:
+        """Unmap and close the underlying /dev/mem file descriptor."""
+        try:
+            self._mmap.close()
+        finally:
+            os.close(self._fd)
+
+    def read32(self, offset: int) -> int:
+        """Read a 32-bit little-endian value at `offset` within the region."""
+        if offset < 0 or offset + 4 > self.size:
+            raise MMIOMapError(f"read32 offset out of range: 0x{offset:X}")
+        pos = self._offset + offset
+        data = self._mmap[pos : pos + 4]
+        return struct.unpack_from("<I", data)[0]
+
+    def write32(self, offset: int, value: int) -> None:
+        """Write a 32-bit little-endian value at `offset` within the region."""
+        if offset < 0 or offset + 4 > self.size:
+            raise MMIOMapError(f"write32 offset out of range: 0x{offset:X}")
+        pos = self._offset + offset
+        self._mmap[pos : pos + 4] = struct.pack("<I", value & 0xFFFFFFFF)
+
+
+class MemoryMapper:
+    """
+    Maps physical peripheral registers through /dev/mem.
+
+    Typical usage:
+      mapper = MemoryMapper()
+      region = mapper.map_region(0xFE200000, 0x1000)  # GPIO block
+    """
+
+    def __init__(self, devmem_path: str = "/dev/mem") -> None:
+        self._devmem_path = devmem_path
+
+    def map_region(self, base_phys: int, size: int) -> MMIORegion:
+        """
+        Map a physical address range.
+
+        `size` should include all needed registers; it will be rounded up to page size.
+        """
+        if size <= 0:
+            raise ValueError("size must be > 0")
+
+        page_size = mmap.PAGESIZE
+        aligned_base, page_offset = _page_align(base_phys, page_size)
+        mapped_size = ((page_offset + size + page_size - 1) // page_size) * page_size
+
+        try:
+            fd = os.open(self._devmem_path, os.O_RDWR | os.O_SYNC)
+        except FileNotFoundError as e:
+            raise DeviceNotFoundError(f"Device not found: {self._devmem_path}") from e
+        except PermissionError as e:
+            raise PermissionDeniedError(
+                f"Permission denied opening {self._devmem_path}. Try running as root (sudo)."
+            ) from e
+        except OSError as e:
+            raise MMIOMapError(f"Failed opening {self._devmem_path}: {e}") from e
+
+        try:
+            mm = mmap.mmap(
+                fd,
+                mapped_size,
+                flags=mmap.MAP_SHARED,
+                prot=mmap.PROT_READ | mmap.PROT_WRITE,
+                offset=aligned_base,
+            )
+        except OSError as e:
+            os.close(fd)
+            raise MMIOMapError(
+                f"mmap failed for phys=0x{base_phys:X} aligned=0x{aligned_base:X} size=0x{mapped_size:X}: {e}"
+            ) from e
+
+        logger.debug(
+            "Mapped %s: phys=0x%X aligned=0x%X size=0x%X offset=0x%X",
+            self._devmem_path,
+            base_phys,
+            aligned_base,
+            mapped_size,
+            page_offset,
+        )
+        return MMIORegion(base_phys=base_phys, size=size, _fd=fd, _mmap=mm, _offset=page_offset)
+
+
+class FakeMMIORegion:
+    """
+    Test helper: in-memory fake MMIO region implementing read32/write32.
+
+    This is intentionally simple and NOT thread-safe.
+    """
+
+    def __init__(self, size: int) -> None:
+        self.size = size
+        self._buf = bytearray(size)
+
+    def close(self) -> None:  # pragma: no cover
+        return
+
+    def read32(self, offset: int) -> int:
+        if offset < 0 or offset + 4 > self.size:
+            raise MMIOMapError(f"read32 offset out of range: 0x{offset:X}")
+        return struct.unpack_from("<I", self._buf, offset)[0]
+
+    def write32(self, offset: int, value: int) -> None:
+        if offset < 0 or offset + 4 > self.size:
+            raise MMIOMapError(f"write32 offset out of range: 0x{offset:X}")
+        struct.pack_into("<I", self._buf, offset, value & 0xFFFFFFFF)
+
+
+class MemoryBackend:
+    """
+    Protocol-like base for memory backends.
+
+    Any backend must implement:
+      - read32(offset) -> int
+      - write32(offset, value) -> None
+      - close() -> None
+    """
+
+    def read32(self, offset: int) -> int:  # pragma: no cover
+        raise NotImplementedError
+
+    def write32(self, offset: int, value: int) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+    def close(self) -> None:  # pragma: no cover
+        raise NotImplementedError
+
+
+class GPIORegion(MemoryBackend):
+    """
+    A small wrapper to hold the actual MMIORegion (or FakeMMIORegion).
+    """
+
+    def __init__(self, region: MemoryBackend) -> None:
+        self._region = region
+
+    def read32(self, offset: int) -> int:
+        return self._region.read32(offset)
+
+    def write32(self, offset: int, value: int) -> None:
+        self._region.write32(offset, value)
+
+    def close(self) -> None:
+        self._region.close()
+
+
+def open_gpio_region(
+    *,
+    base_phys: int,
+    size: int,
+    devmem_path: str = "/dev/mem",
+    backend: Optional[MemoryBackend] = None,
+) -> GPIORegion:
+    """
+    Factory to open the GPIO MMIO region.
+
+    If `backend` is provided, it will be used (useful for tests).
+    """
+    if backend is not None:
+        return GPIORegion(backend)
+    mapper = MemoryMapper(devmem_path=devmem_path)
+    return GPIORegion(mapper.map_region(base_phys=base_phys, size=size))

bcmio-0.1.0/bcmio/pin.py

@@ -0,0 +1,71 @@
+"""High-level Pin abstraction built on top of bcmio.gpio.GPIO."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from .gpio import GPIO
+from .utils import validate_gpio_pin
+
+logger = logging.getLogger(__name__)
+
+
+class Pin:
+    """
+    High-level representation of a single GPIO pin.
+
+    This class uses the global `GPIO` mapping under the hood for performance.
+    """
+
+    IN: int = GPIO.IN
+    OUT: int = GPIO.OUT
+    LOW: int = GPIO.LOW
+    HIGH: int = GPIO.HIGH
+    PULL_NONE: int = GPIO.PULL_NONE
+    PULL_UP: int = GPIO.PULL_UP
+    PULL_DOWN: int = GPIO.PULL_DOWN
+
+    def __init__(
+        self,
+        pin: int,
+        *,
+        mode: int = OUT,
+        pull: int = PULL_NONE,
+        initial: Optional[int] = None,
+        auto_open: bool = True,
+    ) -> None:
+        validate_gpio_pin(pin)
+        self.pin = pin
+        self.mode = mode
+        self.pull = pull
+        self.initial = initial
+        self.auto_open = auto_open
+
+        if self.auto_open and not GPIO.is_open():
+            GPIO.open()
+        GPIO.setup(self.pin, self.mode, pull=self.pull)
+        if self.initial is not None:
+            GPIO.write(self.pin, self.initial)
+
+    def read(self) -> int:
+        return GPIO.read(self.pin)
+
+    def write(self, value: int) -> None:
+        GPIO.write(self.pin, value)
+
+    def high(self) -> None:
+        GPIO.high(self.pin)
+
+    def low(self) -> None:
+        GPIO.low(self.pin)
+
+    def toggle(self) -> int:
+        return GPIO.toggle(self.pin)
+
+    def set_pull(self, pull: int) -> None:
+        GPIO.set_pull(self.pin, pull)
+
+    def close(self) -> None:
+        """Close is intentionally a no-op for now (shared GPIO mapping)."""
+        logger.debug("Pin.close() called for GPIO%d (shared mapping left open)", self.pin)

bcmio-0.1.0/bcmio/pwm.py

@@ -0,0 +1,9 @@
+"""PWM placeholder (future work)."""
+
+from __future__ import annotations
+
+
+class PWM:  # pragma: no cover
+    def __init__(self, *args: object, **kwargs: object) -> None:
+        raise NotImplementedError("PWM not implemented yet. Planned module placeholder.")
+

bcmio-0.1.0/bcmio/utils.py

@@ -0,0 +1,35 @@
+"""Utility helpers (validation, bit operations)."""
+
+from __future__ import annotations
+
+from .constants import GPIO_MAX, GPIO_MIN
+from .exceptions import InvalidPinError
+
+
+def validate_gpio_pin(pin: int) -> None:
+    """Validate that `pin` is within the BCM2711 GPIO range."""
+    if not isinstance(pin, int):
+        raise InvalidPinError(f"GPIO pin must be int, got {type(pin).__name__}")
+    if pin < GPIO_MIN or pin > GPIO_MAX:
+        raise InvalidPinError(f"Invalid GPIO pin: {pin} (valid range {GPIO_MIN}..{GPIO_MAX})")
+
+
+def bit_mask(bit: int) -> int:
+    """Return a 32-bit mask with a single bit set."""
+    return 1 << bit
+
+
+def set_bits(value: int, mask: int) -> int:
+    return value | mask
+
+
+def clear_bits(value: int, mask: int) -> int:
+    return value & ~mask
+
+
+def replace_field(value: int, field_mask: int, field_value: int, shift: int) -> int:
+    """Replace a bitfield defined by mask+shift with a new value."""
+    value &= ~(field_mask << shift)
+    value |= (field_value & field_mask) << shift
+    return value
+

bcmio-0.1.0/bcmio/utils_logging.py

@@ -0,0 +1,14 @@
+"""Basic logging setup helpers."""
+
+from __future__ import annotations
+
+import logging
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Configure a basic root logger formatting."""
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+

bcmio-0.1.0/bcmio.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: bcmio
+Version: 0.1.0
+Summary: Low-level GPIO library for Raspberry Pi 4 (BCM2711) using /dev/mem + mmap
+Author: bcmio contributors
+License: MIT
+Keywords: raspberrypi,gpio,bcm2711,mmap,embedded,linux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+
+# bcmio
+
+Biblioteca Python **low-level** para controle de GPIO do **Raspberry Pi 4 Model B (BCM2711)** usando
+**acesso direto a registradores via `mmap`** e **`/dev/mem`** (MMIO).
+
+> Aviso: acessar `/dev/mem` normalmente requer **root** (`sudo`). Use com cuidado: MMIO incorreto pode
+> travar o sistema.
+
+## Objetivos
+
+- Performance: escrita/leitura direto em registradores (`GPSET/GPCLR/GPLEV`)
+- Arquitetura modular: separar low-level (MMIO/registradores) e high-level (abstrações)
+- API familiar (inspirada em RPi.GPIO/pigpio/gpiozero), mas **sem dependências** dessas bibliotecas
+- Código tipado, com docstrings, pronto para evoluir para PWM/SPI/I2C/UART/interrupts/DMA
+
+## Arquitetura (módulos)
+
+- `bcmio/memory.py`: abertura de `/dev/mem`, `mmap`, leitura/escrita 32-bit
+- `bcmio/constants.py`: offsets e constantes (GPIO modes, pulls, endereços base)
+- `bcmio/gpio.py`: acesso aos registradores GPIO (FSEL, SET/CLR, LEV, PULL)
+- `bcmio/pin.py`: classe `Pin` (alto nível) para um pino individual
+- `bcmio/exceptions.py`: exceções customizadas
+- `bcmio/utils.py`: helpers (validação, bit operations)
+- `bcmio/pwm.py`, `bcmio/interrupts.py`: placeholders para evolução
+
+## Como `mmap` funciona (visão geral)
+
+1. Abrimos `/dev/mem` (arquivo especial que expõe memória física do SoC).
+2. Fazemos `mmap` de uma página (ou mais) a partir do **endereço físico** dos periféricos GPIO.
+3. A partir do ponteiro mapeado, fazemos leituras/escritas de 32 bits em offsets específicos.
+
+No Linux, isso é MMIO (Memory Mapped I/O): escrever em um registrador mapeado altera o hardware.
+
+## Endereços base (BCM2711)
+
+O datasheet usa endereços no **barramento** (bus) como `0x7E200000` para o bloco GPIO. No Raspberry Pi 4,
+o endereço **físico** tipicamente é `0xFE200000` (peripheral base `0xFE000000` + GPIO offset `0x200000`).
+
+Esta biblioteca:
+
+- expõe ambos em `bcmio.constants` (`GPIO_BASE_BUS`, `GPIO_BASE_PHYS_DEFAULT`)
+- por padrão usa o **físico** (`0xFE200000`)
+- permite sobrescrever o endereço base via `GPIO.open(base_phys=...)`
+
+## Registradores GPIO usados (BCM2711)
+
+Offsets relativos ao base do GPIO (bloco `GPIO`):
+
+- `GPFSEL0..5` (Function Select): 3 bits por pino para definir `IN`, `OUT`, ou função alternativa
+- `GPSET0..1` (Set): escrever `1` no bit seta o pino em nível alto (atômico)
+- `GPCLR0..1` (Clear): escrever `1` no bit seta o pino em nível baixo (atômico)
+- `GPLEV0..1` (Level): lê o nível atual do pino
+- `GPIO_PUP_PDN_CNTRL_REG0..3`: 2 bits por pino para pull-up/pull-down/no-pull (BCM2711)
+
+## Uso
+
+### API estilo “módulo” (`GPIO`)
+
+```python
+from bcmio import GPIO
+
+GPIO.open()                       # inicializa /dev/mem + mmap
+GPIO.setup(17, GPIO.OUT, pull=GPIO.PULL_NONE)
+GPIO.write(17, GPIO.HIGH)
+value = GPIO.read(17)
+GPIO.cleanup()
+```
+
+### API orientada a objeto (`Pin`)
+
+```python
+from bcmio import Pin
+
+led = Pin(17, mode=Pin.OUT)
+led.high()
+led.low()
+led.toggle()
+led.close()
+```
+
+## Exemplos
+
+Veja `exemplos/`:
+
+- `exemplos/blink.py`
+- `exemplos/button_read.py`
+- `exemplos/toggle.py`
+- `exemplos/read_digital.py`
+
+## Testes
+
+Os testes em `testes/` não acessam `/dev/mem`. Eles usam um backend fake de memória para validar:
+
+- cálculo de offsets e bitfields de `GPFSEL`
+- `GPSET/GPCLR` e leitura em `GPLEV`
+- configuração de pull em `GPIO_PUP_PDN_CNTRL_REGx`
+
+Rodar:
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+## Segurança e boas práticas
+
+- Use `sudo` apenas quando necessário.
+- Prefira isolar e revisar o endereço base antes de usar em produção.
+- Em produção, considere um modo “safe” ou `/dev/gpiomem` (não implementado aqui por requisito).
+

bcmio-0.1.0/bcmio.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+setup.py
+bcmio/__init__.py
+bcmio/constants.py
+bcmio/exceptions.py
+bcmio/gpio.py
+bcmio/interrupts.py
+bcmio/memory.py
+bcmio/pin.py
+bcmio/pwm.py
+bcmio/utils.py
+bcmio/utils_logging.py
+bcmio.egg-info/PKG-INFO
+bcmio.egg-info/SOURCES.txt
+bcmio.egg-info/dependency_links.txt
+bcmio.egg-info/requires.txt
+bcmio.egg-info/top_level.txt

bcmio-0.1.0/bcmio.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bcmio-0.1.0/bcmio.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[dev]
+pytest>=8
+ruff>=0.5
+mypy>=1.10

bcmio-0.1.0/bcmio.egg-info/top_level.txt

@@ -0,0 +1 @@
+bcmio

bcmio-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bcmio"
+version = "0.1.0"
+description = "Low-level GPIO library for Raspberry Pi 4 (BCM2711) using /dev/mem + mmap"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "bcmio contributors" }]
+keywords = ["raspberrypi", "gpio", "bcm2711", "mmap", "embedded", "linux"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: System :: Hardware",
+  "Topic :: Software Development :: Embedded Systems",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5", "mypy>=1.10"]
+
+[tool.setuptools]
+packages = ["bcmio"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+

bcmio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bcmio-0.1.0/setup.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from setuptools import setup
+
+setup()
+