Rp2350a Weact

WeAct Studio RP2350A Core Board (RP2350A)

A Pico-2-shaped RP2350A core board that ships in two incompatible revisions under one name. V2.0 is a pin-for-pin Pico 2 replacement; V1.0 brings out every GPIO instead, and pays for it by moving the power pin, the ADC reference and three GPIO functions. Firmware built for the wrong one compiles cleanly and then drives the wrong pins — so establish the revision before writing any code, and read the reference files rather than assuming Pico 2 behaviour.

• reference/board-hardware.md — the complete board reference: how to tell the revisions apart, the 40-pin map for both, the off-header GPIO, power trees, clocks, memory map, vendor-material inventory plus a development guide (Part II: §8 toolchain, §10 peripheral cookbook, §11 RP2350 gotchas including erratum E9 and the PWM slice map, §12 flashing, §13 a symptom → cause → fix table).
• reference/recipes.md — copy-paste code: platformio.ini with all four envs, the revision guard, reading the real flash size out of the chip, LEDs, the KEY button, V2.0 power sensing, ADC, Wire1 remapping, PWM, EEPROM, LittleFS, core 1.
• template/ — a project that builds clean for both revisions and both flash sizes, in two variants, plus a scaffold script. See template/README.md.

Orientation

Rules that prevent the expensive mistakes

Each of these produces a failure that looks like something else.

1. Establish the revision before writing code. V1.0 and V2.0 differ on GP23, GP24, GP29 and on what pin 39 accepts. Ask the user, or have them look at the top row of pins: VREF in the ADC-reference slot and one LED means V2.0; 29 in that slot, two LEDs and a third button marked 23@KEY means V1.0. Then build with -DBOARD_REV=10 or =20 — the template's board.h refuses to compile without it, on purpose.
2. board = rpipico2, never weact_rp2350b. There is no PlatformIO board definition for this board. weact_rp2350b exists in arduino-pico and is the RP2350B core board — QFN-80, 48 GPIO, 8 ADC channels, a different pinout. It builds and then everything above GP29 is fiction. rpipico2 is exactly right for V2.0 and the best available base for V1.0.
3. board_build.core = earlephilhower in platformio.ini. Plain framework = arduino selects the Arduino Mbed core, which does not support RP2350 at all. The failure reads as a broken toolchain, not a missing ini line.
4. The pin silkscreened VIN is USB VBUS, on both revisions. The supply input is the pin next to it, and the two boards do not accept the same voltage there: V1.0's 5V is an LDO input wanting 3.6–6.5 V, V2.0's VSYS is a buck-boost input wanting 1.8–5.5 V. 6.5 V into a V2.0 is over the absolute maximum; a 3.7 V Li-ion into a V1.0 browns out as the cell discharges. Only V2.0 runs a single cell properly.
5. Serial is USB CDC, not UART0. A USB-serial adapter on GP0/GP1 sees nothing from Serial.print — those pins are Serial1. The CDC port exists only once the host opens it: earlier bytes are dropped, and while (!Serial) blocks startup until a monitor connects. Never gate bring-up on the port being open.
6. analogRead returns 10-bit values (0–1023) by default on a 12-bit ADC. Symptom: "pinned at 1023 at full scale", or a calibration that is off by exactly 4×. analogReadResolution(12) before sampling.
7. GP29 is not the same pin on the two boards. On V1.0 it is ADC3 on header pin 35, a free analog input. On V2.0 it is the VSYS sense (test pad only) and header pin 35 is ADC_VREF instead. Code that reads "the fourth ADC channel" measures the supply on one board and your sensor on the other.
8. The V2.0 VSYS sense is nominally ÷3, but through a FET. R23/R24 100 kΩ into R25 100 kΩ works out to VSYS/3 — the same ×3 math as a Pico — except there is a pass FET with its gate at 3V3 in the path, whose resistance varies with VSYS. Use it for trends and thresholds; calibrate against a meter before quoting an absolute battery voltage.
9. INPUT_PULLDOWN is not usable on RP2350 (erratum RP2350-E9). An input whose pad sits between logic levels leaks up to ~120 µA, which overwhelms the internal pull-down: the pin latches at ~2 V and reads HIGH forever. Wire buttons to GND with INPUT_PULLUP, or fit an external pull-down of 8.2 kΩ or less. The same leakage costs ~120 µA per floating input — on a battery build that is the whole sleep budget. V1.0's 23@KEY is active-LOW with a 5.1 kΩ pull-up and is unaffected.
10. PWM aliasing is four-wide, not two. Slice = (gpio >> 1) & 7, so slices 0–7 each serve four pins (0/1/16/17, 2/3/18/19, …) and only GP14/GP15 are unaliased. Pins on one slice share the frequency; pins 16 apart share the channel, so analogWrite(2, x) and analogWrite(18, y) write the same duty register and the last one wins for both. A servo/stepper pair that glitches like a power problem is usually this.
11. Nothing on the board says whether it has 4 MB or 16 MB of flash. The build believes board_upload.maximum_size. Claiming 16 MB on a 4 MB board puts the EEPROM sector and any filesystem past the end of the chip. Read the JEDEC ID at boot (recipe 3 — the template prints both the real size and the one the build assumed), then pick the matching env. picotool info -d in BOOTSEL is a cross-check, but on a third-party board its flash-size field comes from unprogrammed OTP and may say nothing. board_build.f_flash is an ESP-ism and does nothing on this platform.
12. Wire1 defaults to GP26/GP27 — the same pins as A0/A1. I2C corruption that starts the moment analogRead is called is this, not noise. Wire1.setSDA()/setSCL() to another i2c1 pair (2/3, 6/7, 10/11, 14/15, 18/19) before begin().
13. The LEDs run through 5.1 kΩ. ~0.25 mA: they are visible in shade and almost invisible in daylight. Do not debug a blink sketch that is working.
14. EEPROM lives in flash and only persists on commit(), and flash writes stall both cores because code runs from the same QSPI chip via XIP. A sketch that never commits loses everything on reboot, silently; one that commits inside a timing-critical loop hiccups in a way that looks like a scheduler bug.
15. flash_do_cmd() must run during startup, interrupts off. It stops XIP to talk to the flash chip. Called from a running application — or with core 1 executing — it hangs the board. That is why the template reads the JEDEC ID on the first line of setup().
16. RP2350 UF2 files are not RP2040 UF2 files. Different family ID, and the BOOTSEL drive is named RP2350. An RP2040 image dropped on it is rejected rather than run, and a .uf2 from a Pico project will not boot here.
17. GP26–GP29 are not 5 V tolerant and carry a reverse diode to 3V3. Above ~3.6 V they damage the chip, and any voltage on them while the board is unpowered back-powers the whole board through the pin.

When the task is powering it from something other than USB

This is where the two revisions actually diverge, so answer the revision question first.

V2.0 behaves like a Pico 2: VSYS (pin 39) takes 1.8–5.5 V into a buck-boost, so a single Li-ion cell, 3 × AA, or any 2–5 V supply works directly and stays working as the cell sags. GP24 tells you whether USB is present and GP29 gives you approximately VSYS/3, so battery monitoring and USB/battery switchover need no extra parts. If USB is the only source you may short VBUS to VSYS to remove the Schottky drop. USB host mode needs 5 V fed to the VIN pin (pin 40), not to VSYS.

V1.0 has an LDO instead: pin 39 (5V) wants 3.6–6.5 V and drops out below ~3.6 V, so a 1S Li-ion works only down to ~3.6 V — most of the cell is unusable, and the brown-out looks like a firmware crash. There is no VSYS or VBUS sense on any GPIO, so battery monitoring means wiring a divider of your own into one of the four ADC inputs (GP29/ADC3 is free on this revision, which is convenient). And because it is linear, input current equals output current: 6.5 V in at 300 mA out dissipates about a watt in a SOT-23-5 package.

On both: 3V3 (pin 36) is an output — never back-feed it — and EN (pin 37) pulled low kills the rail and makes the board look bricked with USB attached.

Starting a new project

Do not hand-assemble one. template/ builds clean for both revisions; scaffold from it:

~/.claude/skills/rp2350a-weact/template/variants/new-project.sh <dir> \
    [--full|--minimal] [--v20|--v10] [--16mb]
cd <dir> && pio run -t upload -t monitor

• --minimal — blink on GP25, which is a user LED on both revisions. 32,916 B flash / 8,504 B RAM. Flash this first on an unfamiliar board: if it does not blink after upload, the problem is the cable, the BOOT dance or the env choice, not the code. (The floor is TinyUSB CDC; a bare blink costs ~33 KB here.)
• --full (default) — non-blocking heartbeat, USB-CDC report, the real flash size read from the JEDEC ID, A0 at 12 bits, die temperature, EEPROM boot counter, plus the per-revision extras: VSYS + VBUS sense and the SMPS mode pin on V2.0, the second LED and the KEY button on V1.0. 37,676 B flash (V2.0) / 9,824 B RAM.

All four envs — weact_rp2350a_v20, _v20_16mb, _v10, _v10_16mb — build as-is with platform-raspberrypi 1.20.0 + arduino-pico 6.0.0 (verified). Nothing is generated and no paths are embedded, so copying the tree by hand works identically; template/README.md maps files to subsystems.

When the user already has a project, prefer fixing their platformio.ini (board = rpipico2, board_build.core = earlephilhower, the right board_upload.maximum_size) and adding the BOARD_REV guard over rewriting their code — that is usually the whole fix.

Flashing

Over the USB-C cable, nothing pressed:

pio run -t upload -t monitor

PlatformIO opens the CDC port at 1200 baud, the running sketch reboots itself into BOOTSEL, picotool flashes and reboots the board; the LED is blinking again within a second of SUCCESS. The board enumerates as a CDC port (/dev/cu.usbmodem*, COMx) at VID:PID 2E8A:000F; the monitor's baud rate is ignored.

When the firmware cannot respond — crashed, USB disabled, power-only cable, or a blank board — the sequence is: hold BOOT (the button beside the USB connector) → plug or replug USB → release → a drive named RP2350 appears → either re-run pio run -t upload (picotool picks up the BOOTSEL device) or drag .pio/build/<env>/firmware.uf2 onto the drive. Without unplugging: hold BOOT, tap RESET, release BOOT. BOOT is sampled at power-up only — pressing it on a running board does nothing.

That BOOT route always works — the boot ROM is mask ROM and nothing you flash can disable it, so the board cannot be bricked. Note that pio run -t erase copies PlatformIO's bundled flash_nuke.uf2, which carries the RP2040 and absolute UF2 family IDs and no RP2350 family: do not count on it here (untested on this board), and the picotool 2.0.0 that ships with the platform has no erase subcommand. For a genuine clean slate, flash a flash_nuke built for RP2350 from pico-examples; for the ordinary case, flashing a known-good sketch over the top is enough. SWD on the four end pads (3V3/DIO/CLK/GND, with a Debug Probe or upload_protocol = cmsis-dap) is for live debugging, not for recovery.

Reporting

State honestly what was verified on hardware and what came from the schematic. In this skill: only RP2350A_V20 was run on hardware — the --minimal blink on GP25 and the USB-C upload path. All four template envs and every recipe marked as such build clean against platform-raspberrypi 1.20.0 + arduino-pico 6.0.0. Everything specific to V1.0 — the GP24/GP25 LEDs, the GP23 KEY, the free ADC3 on GP29, the LDO's 3.6–6.5 V range — is transcribed from V10_SCH.pdf and has not been run. No voltage, current, ADC or timing figure anywhere in this skill was measured: the ADC reference network, the VSYS ÷3 factor, the LED currents and the regulator ratings are schematic- and datasheet-derived. Core-behaviour claims (read-resolution default, Wire1 pins, the PWM slice formula, the 1200-baud touch) come from the arduino-pico 6.0.0 and pico-sdk sources. Anything above 150 MHz that a user asks for is overclocking — label it as outside spec.