pioasm_platformio.md

Using pioasm in platformio projects

Here is somethig you might find useful: automatic pio assembly -> h file generation for platformio.
I have tested it on Linux only.

This is the state as of Nov 2022. The arduino core for RP2040 will most likely change in the future and make this method obsolete.

May 2025 Update.

The pioasm tool by earlephilhower has been removed from the official Platformio repository, thus installing it requires choosing the correct version (OS) from the releases and providing a direct link to the package.

Step 1:

Visit the tool release page:
https://github.com/earlephilhower/pico-quick-toolchain/releases/
and copy the link to the correct version. In my cese (x86 Linux) the current tar.gz is available at
https://github.com/earlephilhower/pico-quick-toolchain/releases/download/4.0.1/x86_64-linux-gnu.pioasm-efe2103.240929.tar.gz

Either install the tool globally

pio pkg install -g --tool https://github.com/earlephilhower/pico-quick-toolchain/releases/download/4.0.1/x86_64-linux-gnu.pioasm-efe2103.240929.tar.gz

or add it to the platfom packages in the platformio.ini file
platform_packages = tool-pioasm-rp2040-earlephilhower @ https://github.com/earlephilhower/pico-quick-toolchain/releases/download/4.0.1/x86_64-linux-gnu.pioasm-efe2103.240929.tar.gz

changing the link address to your correct version. Saving the platformio.ini file should install the required pioasm tool.

Step2:

We are going to create a python script searching for any .pio files in the project src directory and converting them to compiled header files.
Add the following to the platformio.ini file:

extra_scripts = pre:scripts/pioasm.py

This tells the platformio to execute that script before building the firmware.

Step 3:

Create a new dir called "scripts" in your project's root dir and copy the following pioasm.py file into it:

"""
Custom pioasm compiler script for platformio.
(c) 2025 by P.Z.

"""
from os.path import join
import glob
import sys
Import("env")

install_msg = """tool-pioasm-rp2040-earlephilhower not found!

Visit https://github.com/earlephilhower/pico-quick-toolchain/releases/
and copy the link to your OS correspoding version.

The tool is no longer in the Platformio repository and has to be installed
manually using a direct link.

Either install the tool globally (change the address to your version):
pio pkg install -g --tool https://github.com/earlephilhower/pico-quick-toolchain/releases/download/4.0.1/x86_64-linux-gnu.pioasm-efe2103.240929.tar.gz

of add in the platfromio.ini

platform_packages = tool-pioasm-rp2040-earlephilhower @ https://github.com/earlephilhower/pico-quick-toolchain/releases/download/4.0.1/x86_64-linux-gnu.pioasm-efe2103.240929.tar.gz"""

platform = env.PioPlatform()
PROJ_SRC = env["PROJECT_SRC_DIR"]
PIO_FILES = glob.glob(join(PROJ_SRC, '*.pio'), recursive=True)

if PIO_FILES:
    print("==============================================")
    print('PIO ASSEMBLY COMPILER')
    try:
        PIOASM_DIR = platform.get_package_dir("tool-pioasm-rp2040-earlephilhower")
    except:
        print(install_msg)
        sys.exit()

    if PIOASM_DIR is not None:
        PIOASM_EXE = join(PIOASM_DIR, "pioasm")
        print(f"pio files found:")
        for filename in PIO_FILES:
            env.Execute(PIOASM_EXE + f' -o c-sdk {filename} {filename}.h')
        print("==============================================")
    else:
        print(install_msg)
        sys.exit()

The project folder structure after succesful build looks like this (using the apa102.pio driver as example):

├── include
│   └── README
├── lib
│   └── README
├── platformio.ini
├── scripts
│   └── pioasm.py
├── src
│   ├── apa102.pio
│   ├── apa102.pio.h
│   └── main.cpp
└── test
    └── README

My full platformio.ini file looks like this :

[env:pico]
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
board = pico
framework = arduino
board_build.core = earlephilhower
build_flags = -DUSE_TINYUSB
monitor_speed = 115200
platform_packages = tool-pioasm-rp2040-earlephilhower @ https://github.com/earlephilhower/pico-quick-toolchain/releases/download/4.0.1/x86_64-linux-gnu.pioasm-efe2103.240929.tar.gz
extra_scripts = pre:scripts/pioasm.py

Building a project automatically converts the .pio files into compiled .pio.h ones, which can be included in the rest of the firmware.

Processing pico (platform: https://github.com/maxgerhardt/platform-raspberrypi.git; board: pico; framework: arduino)
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
==============================================
PIO ASSEMBLY COMPILER
pio files found:
/home/user/.platformio/packages/tool-pioasm-rp2040-earlephilhower/pioasm -o c-sdk /home/user/Projects/Software/arm/RPi_Pico/MIDI2EXP/src/apa102.pio /home/user/Projects/Software/arm/RPi_Pico/MIDI2EXP/src/apa102.pio.h
==============================================
CONFIGURATION: https://docs.platformio.org/page/boards/raspberrypi/pico.html
PLATFORM: Raspberry Pi RP2040 (1.7.0+sha.bd485fe) > Raspberry Pi Pico
...

Unfortunately, the procedure seems not to work anymore, the plugin cannot be located

The pioasm tool has been removed from the Platformio repository and has to be installed using a direct link to the package.
Just tested the updated procedure - success.

Much appreciated, I'll test it ASAP