Puya PY32F MCU support by burgrp · Pull Request #5106 · tinygo-org/tinygo

burgrp · 2025-12-02T15:35:12Z

Hi, this is a port of of Puya PY32F super-cheap micro-controllers.
There are two new boards and supported (available on Aliexpress) for PY32F030 and PY32002b.
PY32F030 and PY32002b are supported, PY32F002a and PY32F071 will follow.
It follows the STM32 SVD pattern - there's a small TinyGo SVD repository dependent on Rust py32-rs repo. The repository is here: https://github.com/burgrp/py32-svd . I think it would be worth to move it to tinygo-org.

deadprogram · 2025-12-12T08:24:26Z

Hello @burgrp thank you for working on this.

Have you seen this page?
https://tinygo.org/docs/guides/contributing

I think you will find it helpful. 😸

deadprogram · 2025-12-13T18:53:43Z

@burgrp I have switched the branch for this PR to dev branch as mentioned here:
https://tinygo.org/docs/guides/contributing/#how-to-use-our-github-repository

Can you please rebase it against the latest dev so it can run all of the latest tests?
Also I made a few comments.

Planning on ordering a few of these myself, thanks for working on it!

b0ch3nski · 2026-01-27T16:53:01Z

@burgrp You are updating bdwgc submodule which is probably not something you meant to do - this breaks a lot of stuff 🔥

burgrp · 2026-01-27T19:04:18Z

You are right... I will fix it and hopefully it will be possible to merge the PR.

burgrp · 2026-02-13T19:51:23Z

@b0ch3nski , the sub-module issue is fixed, all checks are passing

b0ch3nski · 2026-02-15T12:22:11Z

Thanks! I think now there is some unrelated change also in net submodule 😬

deadprogram · 2026-02-15T13:56:07Z

@b0ch3nski looks that way to me as well: https://github.com/tinygo-org/tinygo/pull/5106/changes#diff-d7ea94295bc068e99e5edeacb50734849fb40d5aa39cbc68be5e55c0d90bd60a

@burgrp one other thing that is needed is to add something to the smoketests to show that at least everything can build. Someplace appropriate in here, please: https://github.com/tinygo-org/tinygo/blob/dev/GNUmakefile#L567-L989

burgrp · 2026-02-21T20:20:00Z

@b0ch3nski , @deadprogram smoketests added, net module update reverted

deadprogram · 2026-02-24T10:45:59Z

+	return uint8(p) & 0x0F
+}
+
+func (p Pin) getPort() (*py32.GPIO_Type, uint8) {


Better to use unsafe.Add() if you must. Probably even better to use a switch to avoid possible errors.

deadprogram · 2026-02-24T10:52:16Z

+	switch config.Mode {
+
+	case PinInputFloating:
+		port.MODER.ReplaceBits(gpioModeInput, gpioModeMask, pos)


I have not installed/run the gen-device-py32 yet, but I assume there are probably some functions like SetMODERInput() that are being generated. Using these are usually preferable, to avoid possible bugs from setting unexpected bits.

Unfortunately there is no SetMODERInput() generated. These helper functions are generated in form SetMODER_MODE0()...SetMODER_MODE15(), which are quite useless for parametric access.
I've fixed the machine constants to use the svd pin0 generated constants e.g.:
gpioModeOutput = py32.GPIO_MODER_MODE0_Output
so there is at least some binding to svd values.

deadprogram · 2026-02-24T10:52:21Z

+const PinInput PinMode = PinInputFloating
+
+const (
+	gpioModeInput     = 0


Are any of these being generated from the SVD file already? See comment below.

See my comment above.

deadprogram · 2026-02-24T10:53:23Z

+// peripheral clock frequency.
+func InitSerialWithClock(clockHz uint32) {
+	py32UARTClockHz = clockHz
+	//Serial.ConfigureWithClock(UARTConfig{}, clockHz)


Commented line?

deadprogram · 2026-02-24T10:55:39Z

+	py32.RCC.SetICSCR_HSI_FS(py32.RCC_ICSCR_HSI_FS_Freq24MHz)
+
+	ConfigureSystemTimer(24_000_000)
+	machine.InitSerial()


This perhaps needs to be moved into an init() function?

See #5200 (comment)

deadprogram · 2026-02-24T10:55:59Z

+  ],
+  "build-tags": [
+    "embedfire_py32f002b",
+		"default_uart_pins"


Formatting, please.

deadprogram · 2026-02-24T10:59:04Z

This is getting exciting @burgrp thank you so much for working on it! We were discussing during our TinyGo monthly meeting last night ❤️

I made some comments, hopefully @soypat and others can also take a look.

soypat · 2026-02-24T19:51:33Z

I've taken a look and have some reservations on exported API chosen. I'd like to better understand how we define APIs in machine package to understand if the exported functions implemented here match with what the rest of TinyGo does. Basically working on getting something like go doc -tags=rp2040 machine to work (which it does not currently)

soypat · 2026-02-25T15:38:04Z

I vibe coded a tool to help us understand the tinygo APIs better. I'll invite you all to check it out to understand what our APIs look like in TinyGo #5224

soypat

Running tgdoc I've found what look like discrepancies with usual TinyGo API.

You can browse our APIs by running go run ./cmd/tgdoc -http=:18080 ../tinygo/targets ../tinygo/src/machine given tinygodoc shares tinygo parent directory
https://github.com/tinygo-org/tinygodoc

soypat · 2026-03-02T13:07:02Z

+
+// ConfigureWithClock initializes the UART using the provided peripheral clock
+// frequency (in Hz). This avoids assuming a fixed MCU clock.
+func (uart *UART) ConfigureWithClock(config UARTConfig, clockHz uint32) error {


can we replace clockHz with CPUFrequency() internal call to Configure?

soypat · 2026-03-02T13:08:13Z

+
+// InitSerialWithClock configures the default Serial using the supplied
+// peripheral clock frequency.
+func InitSerialWithClock(clockHz uint32) {


Same as above, use CPUFrequency(). It is standard tinygo API, present on 160 targets.

soypat · 2026-03-02T13:08:45Z

+}
+
+// Configure pin for use by UART
+func ConfigureUARTPin(pin Pin, af uint8) {


Shouldn't this be Pin.Configure followed by an SetAltFunc? (is it really necessary to export this?)

Or unexport it if it is expected to only be called internally for UART configuration

You are right, cleaned up to just Pin.Configure+SetAltFunc.
This needs to be exported, because other boards may need explicit call for non-default UART pins.

Non default pins can be configured with the UARTConfig struct. Please unexport this.

Unfortunately it can't be configured using UARTConfig on PY32F. We need to pass the AF parameter somehow.

However, I will try to fix it somehow...

The function removed.

soypat · 2026-03-04T03:50:58Z

+func SetCPUFrequency(frequency uint32) {
+	CPUFrequencyHz = frequency
+}


This is a very confusing API- it does not actually change the frequency. Prefer unexporting it and either linking with //go:linkname compiler directive from runtime package or setting as constant at build time.

I agree - the function is removed. The variable CPUFrequencyHz still needs to be exported to allow clock change from user code.

Why do you want to allow changing CPU frequency from user code?

This API does not exist yet in TinyGo, we'd likely need to discuss the best design going forward if we are to add it

For two simple reasons (correct me if I'm not seeing something):

TinyGo comes with a finite set of supported dev boards. In practice, final product boards differ, so they may need other setting.

There may be application which need to set clock dynamically, e.g. to save energy.

https://github.com/orgs/tinygo-org/discussions/5239

Yes, I need that for one of my projects. Thanks for being open to discuss it!

I'd hate for this to stay in a stale state while we discuss the CPUFrequency API. Could you implement CPU frequency API on your side and test things and let us know how your experimentation goes?

This API is still very unintuitive because it does exactly none of what it says it does. Calling this function does not actually do anything yet documentation and the name state otherwise. Either remove the CPU setting frequency API or figure out how to include it in an intuitive way.

Consider we want new users of the PY32 with TinyGo to have a smooth experience and not be confused as to why the CPU frequency has not changed after calling the function that says it changes CPU frequency. If need be have this function do all the reinitialization of all peripherals to fulfill the objective.

The function was removed - no SetCPUFrequency anymore.

burgrp · 2026-04-28T22:15:55Z

@soypat I'm using this PY32F port already for few firmware projects. No change was needed for a month or two, so the code seems to be stable. What do you think about merging it?

soypat · 2026-05-03T13:28:33Z

+func SetCPUFrequency(frequency uint32) {
+	CPUFrequencyHz = frequency
+}


This API is still very unintuitive because it does exactly none of what it says it does. Calling this function does not actually do anything yet documentation and the name state otherwise. Either remove the CPU setting frequency API or figure out how to include it in an intuitive way.

Consider we want new users of the PY32 with TinyGo to have a smooth experience and not be confused as to why the CPU frequency has not changed after calling the function that says it changes CPU frequency. If need be have this function do all the reinitialization of all peripherals to fulfill the objective.

soypat · 2026-05-03T13:32:21Z

+}
+
+// Configure pin for use by UART
+func ConfigureUARTPin(pin Pin, af uint8) {


Non default pins can be configured with the UARTConfig struct. Please unexport this.

soypat · 2026-05-03T15:14:35Z

+	for uart.Bus.SR.Get()&py32.USART_SR_TXE == 0 {
+	}


I missed these hot loops. can we take measures to prevent runaway spinning?

https://tinygo.org/docs/guides/driver-design/#hot-loops

soypat · 2026-05-03T15:14:48Z

+	for uart.Bus.SR.Get()&py32.USART_SR_TC == 0 {
+	}


this hot loop too

soypat · 2026-05-03T15:16:53Z

+func (p Pin) SetAltFunc(af uint8) {
+	port, pin := p.getPort()
+	if pin >= 8 {
+		port.AFRH.ReplaceBits(uint32(af), 0xF, (pin%8)*4)
+	} else {
+		port.AFRL.ReplaceBits(uint32(af), 0xF, (pin%8)*4)
+	}
+}


I'm still very confused as to why these APIs are here. I am not familiar with the py32. Maybe documenting them here would clarify to me and future users how to use Altfuncs on the py32 and also maybe give me clarity to suggest alternative APIs?

This is how you configure a pin for an alternative function, such as UART RX or ADC IN.

Documentation added.

OK, I think we can approach the UART config of pins like RP2040 does it:

type pinFunc: https://github.com/tinygo-org/tinygo/blob/dev/src/machine/machine_rp2_gpio.go#L59

setPinFunc: https://github.com/tinygo-org/tinygo/blob/dev/src/machine/machine_rp2_gpio.go#L145-L152

pinfunc definitions for RP2040:

tinygo/src/machine/machine_rp2_2040.go

Lines 99 to 124 in 1a1506e

fnJTAG pinFunc = 0

fnSPI pinFunc = 1 // Connect one of the internal PL022 SPI peripherals to GPIO

fnUART pinFunc = 2

fnI2C pinFunc = 3

// Connect a PWM slice to GPIO. There are eight PWM slices,

// each with two outputchannels (A/B). The B pin can also be used as an input,

// for frequency and duty cyclemeasurement

fnPWM pinFunc = 4

// Software control of GPIO, from the single-cycle IO (SIO) block.

// The SIO function (F5)must be selected for the processors to drive a GPIO,

// but the input is always connected,so software can check the state of GPIOs at any time.

fnSIO pinFunc = 5

// Connect one of the programmable IO blocks (PIO) to GPIO. PIO can implement a widevariety of interfaces,

// and has its own internal pin mapping hardware, allowing flexibleplacement of digital interfaces on bank 0 GPIOs.

// The PIO function (F6, F7) must beselected for PIO to drive a GPIO, but the input is always connected,

// so the PIOs canalways see the state of all pins.

fnPIO0, fnPIO1 pinFunc = 6, 7

// General purpose clock inputs/outputs. Can be routed to a number of internal clock domains onRP2040,

// e.g. Input: to provide a 1 Hz clock for the RTC, or can be connected to an internalfrequency counter.

// e.g. Output: optional integer divide

fnGPCK pinFunc = 8

// USB power control signals to/from the internal USB controller

fnUSB pinFunc = 9

fnNULL pinFunc = 0x1f

fnXIP pinFunc = 0

uart config of pins: https://github.com/tinygo-org/tinygo/blob/dev/src/machine/machine_rp2_uart.go#L53-L57

what do you think?

FYI: The exported API is PinMode:

tinygo/src/machine/machine_rp2_2040.go

Lines 36 to 46 in 1a1506e

PinOutput PinMode = iota

PinInput

PinInputPulldown

PinInputPullup

PinAnalog

PinUART

PinPWM

PinI2C

PinSPI

PinPIO0

PinPIO1

Update submodule to fix duplicate SetIDCODE/GetIDCODE method declarations in the generated py32f002bxx.go device file. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…tion in UART setup

Add a per-instance setup func to the UART type so the driver is no longer hardwired to USART1. DefaultUART stays USART1; add UART2 (USART2) in a separately build-tagged file since py32f002x parts lack USART2. RX IRQ handlers reference runtime-assigned vars to break the init cycle, and setup is assigned in the var initializer so it runs before InitSerial. Add the py32f003_32k_4k target (32K flash / 4K RAM).

Use CMSIS/pyocd device names for target files and build tags. Add all F003 and F030 densities plus F002A/B, correct F002B to 24K flash and its own startup file, fix the F030x8 pyocd target, and update Embedfire inheritance.

soypat · 2026-08-21T05:03:07Z

+// must update this value after the new clock is stable, then reconfigure
+// SysTick and any peripherals derived from the system clock. Assigning this
+// variable does not configure the clock hardware.
+var CPUFrequencyHz uint32 = defaultCPUFrequencyHz


Please remove/unexport this. I invite you to implement your own HAL for setting the CPU frequency outside of TinyGo. We need to talk about adding/changing HALs before adding them in multi-thousand line CLs. Its too much for one place. Remove all other non-standard HAL as well please to make our life easier.

What do you mean by "outside of TinyGo", please? We have touched this few times already. There definitely need to be a possibility to configure clock low-level way (by direct register manipulation) and thus there needs to be a variable holding that clock speed to be read by other parties (UART, system timer etc...)

OK. The way I see it having an exported global variable is a hard no. The best way I can think of moving this along is unexporting this variable and having an unexported function that sets it that we expose via a compiler pragma like //go:linkname from your application. This is done often enough in TinyGo that you should be able to find several examples of how this works in our codebase. The most pertinent example is the net.useNetdev https://github.com/tinygo-org/net/blob/1638a8751255b9d3afe761b8633d94f90a79e91e/netdev.go#L36
which drivers repo links and so do external projects like lneto https://github.com/soypat/lneto/blob/main/x/netdev/gonet-tinygo.go#L11. This way we do not expose any API we have not "approved" but we do not outright just block the useful feature of dynamically setting CPU frequency.

That sounds kinda hacky, but I take it :) I will change it to unexported function.
Do you have any deadline for that 1.27 release we could merge this in?

Yes, as soon as possible please! We are trying to target the next release in the next 24 hours, hopefully.

So, it's there.

soypat · 2026-08-21T05:03:48Z

+
+const (
+	PinOutput PinMode = iota
+	PinInputFloating


I think PinInput is standard tinygo HAL for floating inputs unless I've missed something.

soypat · 2026-08-21T05:08:07Z

+// 4-bit field in the GPIO alternate-function registers. The register is split
+// in two: AFRL holds the 4-bit selectors for pins 0–7 and AFRH holds them for
+// pins 8–15, with each selector at bit offset (pin%8)*4 within its register.
+//
+// Alternate-function mappings vary by pin and PY32 variant; consult the
+// device datasheet for the AF0-AF15 mapping. The pin must also be configured
+// as PinAlternate via Pin.Configure before the alternate function takes effect.


The register is split ...

There are so many words and the only actual useful part for a user is "Pin must be configured as PinAlternate". Be considerate of user's time reading comments.

soypat · 2026-08-21T05:08:34Z

+// Each pin supports up to 16 alternate functions (AF0–AF15), encoded as a
+// 4-bit field in the GPIO alternate-function registers. The register is split
+// in two: AFRL holds the 4-bit selectors for pins 0–7 and AFRH holds them for
+// pins 8–15, with each selector at bit offset (pin%8)*4 within its register.
+//
+// Alternate-function mappings vary by pin and PY32 variant; consult the
+// device datasheet for the AF0-AF15 mapping. The pin must also be configured
+// as PinAlternate via Pin.Configure before the alternate function takes effect.


soypat · 2026-08-21T05:10:07Z

+
+// Configure SysTick to fire every 1ms on given system frequency.
+// This should be called after any change to the system clock frequency.
+func ConfigureSystemTimer() {


Same as CPUFrequencyHz. Lets talk about new HAL before adding.

deadprogram changed the base branch from release to dev December 13, 2025 18:43

deadprogram reviewed Dec 13, 2025

View reviewed changes

Comment thread targets/embedfire-py32f002b.json Outdated

deadprogram reviewed Dec 13, 2025

View reviewed changes

Comment thread targets/embedfire-py32f002b.json Outdated

deadprogram reviewed Dec 13, 2025

View reviewed changes

Comment thread targets/embedfire-py32f030.json Outdated

burgrp force-pushed the py32 branch from 8e14179 to fa6d383 Compare December 15, 2025 19:29

burgrp force-pushed the py32 branch from 84756c5 to 7fa20c4 Compare January 7, 2026 00:07

deadprogram reviewed Feb 24, 2026

View reviewed changes

soypat reviewed Mar 2, 2026

View reviewed changes

soypat reviewed Mar 4, 2026

View reviewed changes

soypat requested changes May 3, 2026

View reviewed changes

soypat reviewed May 3, 2026

View reviewed changes

burgrp and others added 27 commits August 21, 2026 01:32

WIP

5fe5ac6

WIP

25d696f

WIP

8931d1a

add build targets for embedfire on py32

e593e08

add support for embedfire target in GNUmakefile for py32

1709e94

lib/py32-svd: remove duplicate DBGMCU.IDCODE CODE field

6db8df0

Update submodule to fix duplicate SetIDCODE/GetIDCODE method declarations in the generated py32f002bxx.go device file. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

update subproject commit reference in py32-svd

499cfa2

PR fixes

a74db97

refactor: update CPU frequency handling in machine and runtime packages

3ed3393

refactor: replace ConfigureUARTPin function with direct pin configura…

39d1690

…tion in UART setup

SetAltFunc documentation for GPIO pin alternate functions

7bef7af

refactor: improve UART write and flush error handling with timeout

c49587d

Add canonical PY32F002, F003, and F030 density targets

af5100e

Use CMSIS/pyocd device names for target files and build tags. Add all F003 and F030 densities plus F002A/B, correct F002B to 24K flash and its own startup file, fix the F030x8 pyocd target, and update Embedfire inheritance.

Add targets for all PY32 CMSIS devices

075ef75

Support all PY32 register layout variants

762853d

machine/py32: use generated register definitions

3036791

machine/py32: fix alternate-function documentation

c91cc59

machine/py32: report the configured CPU frequency

3e331ac

machine/py32: use unsafe.Add for GPIO ports

352359d

machine/py32: bound and yield UART polling

414d408

machine/py32: configure UART pins from UARTConfig

97bf8e5

build: use the current PY32 SVD repository URL

3607c1a

test: cover PY32 UART register layouts

fad1072

machine/py32: restore dynamic CPU frequency tracking

c3e6ae3

machine/py32: share the USART TX-ready bit

26d62a1

targets/py32: scale system stacks with RAM

f8e1f46

burgrp force-pushed the py32 branch from 120053c to f8e1f46 Compare August 20, 2026 23:36

soypat requested changes Aug 21, 2026

View reviewed changes

machine/py32: keep clock state internal

6ef14f5

	fnJTAG pinFunc = 0
	fnSPI pinFunc = 1 // Connect one of the internal PL022 SPI peripherals to GPIO
	fnUART pinFunc = 2
	fnI2C pinFunc = 3
	// Connect a PWM slice to GPIO. There are eight PWM slices,
	// each with two outputchannels (A/B). The B pin can also be used as an input,
	// for frequency and duty cyclemeasurement
	fnPWM pinFunc = 4
	// Software control of GPIO, from the single-cycle IO (SIO) block.
	// The SIO function (F5)must be selected for the processors to drive a GPIO,
	// but the input is always connected,so software can check the state of GPIOs at any time.
	fnSIO pinFunc = 5
	// Connect one of the programmable IO blocks (PIO) to GPIO. PIO can implement a widevariety of interfaces,
	// and has its own internal pin mapping hardware, allowing flexibleplacement of digital interfaces on bank 0 GPIOs.
	// The PIO function (F6, F7) must beselected for PIO to drive a GPIO, but the input is always connected,
	// so the PIOs canalways see the state of all pins.
	fnPIO0, fnPIO1 pinFunc = 6, 7
	// General purpose clock inputs/outputs. Can be routed to a number of internal clock domains onRP2040,
	// e.g. Input: to provide a 1 Hz clock for the RTC, or can be connected to an internalfrequency counter.
	// e.g. Output: optional integer divide
	fnGPCK pinFunc = 8
	// USB power control signals to/from the internal USB controller
	fnUSB pinFunc = 9
	fnNULL pinFunc = 0x1f

	fnXIP pinFunc = 0

	PinOutput PinMode = iota
	PinInput
	PinInputPulldown
	PinInputPullup
	PinAnalog
	PinUART
	PinPWM
	PinI2C
	PinSPI
	PinPIO0
	PinPIO1

Uh oh!

Uh oh!

Conversation

burgrp commented Dec 2, 2025

Uh oh!

deadprogram commented Dec 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

deadprogram commented Dec 13, 2025

Uh oh!

b0ch3nski commented Jan 27, 2026

Uh oh!

burgrp commented Jan 27, 2026

Uh oh!

burgrp commented Feb 13, 2026

Uh oh!

b0ch3nski commented Feb 15, 2026

Uh oh!

deadprogram commented Feb 15, 2026

Uh oh!

burgrp commented Feb 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deadprogram commented Feb 24, 2026

Uh oh!

soypat commented Feb 24, 2026

Uh oh!

soypat commented Feb 25, 2026

Uh oh!

soypat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soypat Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

burgrp Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

soypat Mar 2, 2026 •

edited

Loading

burgrp Mar 3, 2026 •

edited

Loading