bcmio 0.1.0

Low-level GPIO library for Raspberry Pi 4 (BCM2711) using /dev/mem + mmap

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)

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)

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:

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).