pio2o

Overview

pio2o is a Python program that generates an Oberon module to get the binary code for PIO assembly programs.

There are two steps:

1. run the PIO assembler pioasm to create the corresponding binaries;
2. generate an Oberon module to read this binary code, to then load it into the PIO instruction registers.

The former restriction on one PIO program per module only has been lifted, and .wrap and .wrap_target are supported.

The Python version used to develop the program is 3.12.

Description

The PIO assembly code can either be

• placed inside comments and two keywords directly in an Oberon module, or
• read from a separate file.

Inside an Oberon module, from the example program:

(*
  PIOBEGIN
    .program square_wave
      set pindirs 1
    loop:
      set pins 1 [1]
      set pins 0
      jmp loop

    .program square_wave_asym
      set pindirs 1
      .wrap_target
      set pins 1 [1]
      set pins 0
      .wrap
  PIOEND
*)

Everything within the PIOBEGIN and PIOEND¹ markers must comply with the PIO assembly language specifications, including comment styles (/* .. */, //, ;).

In a separate pure PIO assembly code .pio file, the PIOBEGIN and PIOEND markers are omitted, of course.

The PIO programs’ binary code and the .wrap and .wrap_target parameters are extracted from pioasm’s output by scanning the corresponding C header file. Since this a pretty simplistic algorithm as implemented,² it’s best not to use PIOBEGIN and PIOEND elsewhere in the same module, including other comments, at least not at the beginning of a line.

Example Program

Please refer to example program PIOsquare.

Installation for Command Line Usage

This is how I install pio2o, which may not the “right” way to do it, but it works:

• put pio2o.py into any directory, which must be on $PYTHONPATH, though;
• one possibility is to leave the file in its directory in the repo structure, so you get and “install” any updates automatically. Just put the directory on $PYTHONPATH;
• run the program with the -m option for Python (without the .py extension).

Hence, to generate the Oberon module for the example PIOsquare, I run in the Windows PowerShell, inside the example code directory (with pioasm installed as described below):

PS python -m pio2o PIOsquare.mod

Or

PS python -m pio2o PIOsquare.pio

Which both generate PIOsquarePio.mod, that is, Pio gets added to the source module name. You can optionally specify a different output module name using -o module_name.

Running

PS python -m pio2o -h

prints

usage: pio2o [-h] [-v] [-o MODULE] ifn

Create an Oberon module for PIO assembly code. 'pioasm' is used to assemble
the PIO code, which then can be accessed from the Oberon module.

positional arguments:
  ifn            input file (.mod or .pio)

options:
  -h, --help     show this help message and exit
  -v, --verbose  print feedback
  -o MODULE      output module name (Oberon)

PIO source code can be extracted from an Oberon module (.mod), or read from a
separate file (.pio). In the Oberon module, place the code inside a comment and
keywords PIOBEGIN and PIOEND.

Installation for Astrobe’s Tools Menu

Install as outlined above, then add this snippet – mutatis mutandis – to your Tools.ini file in the Astrobe configs folder:³

[Command3]
MenuItem=Create PIO Module
Path=C:\Users\gray\AppData\Local\Programs\Python\Python312\python.exe
Parameters=-m pio2o %FileDir%\%FileName%
WorkingFolder=%FileDir%
ConsoleApp=TRUE
Prompt=FALSE

PIO Code Assembler pioasm

pio2o relies on the PIO assembler pioasm in the Raspberry Pi Pico C SDK. Just the binary! No need to touch the SDK otherwise. :)

There’s now a simple installer for Windows. Make sure the corresponding directory is in Window’s Path environment variable.

Caveat: this is for SDK version 1.5.1.

The default installation puts piasm here:

C:\Program Files\Raspberry Pi\Pico SDK v1.5.1\pico-sdk-tools

Repository

• pio2o.py