Improvement: prepare HAL for PY32F071 support #16

Goal

Prepare the Firestarter firmware HAL so a native PY32F071 board backend can be added while keeping the existing PROM programming algorithms unchanged.

Scope update: the active implementation target is PY32F071 only. RP2040/RP2350 support is not part of the current port.

The beta branch Leonardo implementation remains the best model for separating logical data/control buses from physical pins and for keeping native USB independent of the programmer bus.

Recommended design

Keep the actual HAL boundary as functions with separate Uno, Leonardo and PY32F071 implementations. Use compile-time capability macros only to exclude unsupported facilities such as DAC control from small AVR builds.

Board-specific functions

void rurp_board_setup();
void rurp_set_control_pin(uint8_t pin, uint8_t state);
void rurp_write_data_buffer(uint8_t data);
uint8_t rurp_read_data_buffer();
void rurp_set_data_output();
void rurp_set_data_input();
uint8_t rurp_user_button_pressed();
uint16_t rurp_read_vcc_mv();
uint16_t rurp_read_voltage_mv();
void rurp_serial_begin(uint32_t baud);
void rurp_serial_end();
int rurp_communication_available();
int rurp_communication_read();
int rurp_communication_peak();
size_t rurp_communication_read_bytes(char* buffer, size_t size);
int rurp_communication_read_data(char* buffer, size_t cap);
size_t rurp_communication_write(const char* buffer, size_t size);

Platform compatibility layer

Add include/rurp_platform.h with normalized identifiers for Uno/ATmega328PB, Leonardo, native tests and PY32F071. It must hide AVR-only PROGMEM details from common headers.

Pin mapping

Physical pins belong in board-specific headers. Logical identifiers such as LEAST_SIGNIFICANT_BYTE, MOST_SIGNIFICANT_BYTE, OUTPUT_ENABLE, CONTROL_REGISTER and CHIP_ENABLE remain platform independent.

PY32F071 GPIO

Prefer a contiguous 8-bit data bus on one GPIO port. Read all bits from one IDR snapshot, write atomically using BSRR, and switch direction through MODER while preserving unrelated pins.

USB transport

Use native USB CDC through the official Puya SDK/CherryUSB stack. Do not define SERIAL_ON_IO; do not port the Uno UART/data-bus switching or deferred-log mechanism. Keep the Firestarter framing protocol unchanged.

Timing

Introduce rurp_millis(), rurp_delay_ms() and rurp_delay_us(). Use SysTick for milliseconds and a hardware timer for microsecond timing and precise programming pulses.

ADC, DAC and VPP

Use the PY32F071 12-bit ADC with VREFINT compensation and the common two-point board calibration. Use the on-chip 12-bit DAC for closed-loop VPP control through the common VPP API. Keep an independent overvoltage shutdown path.

Configuration storage

Use validated dual-slot flash records with sequence numbers and CRC because PY32F071 has no EEPROM.

Build target

Use native CMake and arm-none-eabi-gcc, based on the official Puya CMSIS/HAL/LL package. Produce ELF, BIN and HEX artifacts in CI.

Acceptance criteria

• PROM algorithms compile without PY32-specific changes.
• Common headers no longer unconditionally include AVR-only headers.
• Physical pin mappings are board specific.
• PY32F071 data-bus reads use one GPIO snapshot and writes are atomic.
• Native USB CDC stays active during programmer operations.
• SERIAL_ON_IO is not used for PY32F071.
• Timing is independent of Arduino APIs.
• ADC measurement uses VREFINT plus common board calibration.
• DAC VPP regulation uses calibrated ADC feedback.
• Configuration persists in CRC-validated flash records.
• Uno, ATmega328PB, Leonardo and native tests remain unaffected.
• PY32F071 firmware builds and CI publishes BIN/HEX/ELF artifacts.

Implementation is tracked in henols/firestarter PR #46.