Propeller 2 Assembly Language beginner guide v0.1

proppy

Hello!

I’ve been working on a practical Propeller 2 assembly language manual that walks through real-world examples using smartpins, UART, line editing/input parsing, and SPI flash access. It’s written in P2ASM/Spin2 and meant to be a hands-on reference for embedded development with the P2.

It covers topics like:

UART communication (high-speed async, echo, line input)

Interactive command input with backspace handling

Token parsing and command dispatch

State machines with optimized jump tables

SPI setup and full-duplex communication

Reading JEDEC ID from SPI flash

Streaming flash reads over UART

String handling routines (length, compare, copy, concatenate)

Number ↔ string conversions

And more

The manual is organized with explanations for each example, and every program has commentary describing how it works.

📌 Version: v0.1
📌 Repository: https://github.com/propeller-mcu/propeller2_asm

This is an early release, and I’d really appreciate feedback from the community — especially on:

Example enhancements

Clarity of explanation

Anything that’s confusing or could be improved

I intentionally waited to polish formatting until the content was solid first, so this is about substance over style. If you find it useful, great — and if not, constructive feedback is more than welcome.

Thanks!

JonnyMac

Neat. Downloaded and will get it over to the print show (I like to hold books in my hands [showing my age]).

Though it's old, too, I tried a couple of examples using Propeller Tool. I figured out that I have to download to flash (F11), open the terminal (PST), and then reset the P2. Still I was getting odd behavior from time to time.

I noticed that some of your examples jump to an end label...

  jmp     #endprog 

In the print JEDEC example that label is right above the variable definitions

  endprog

  spi_command         res 1
  spi_reception       res 1
  uart_transmission   res 1
  hexadecimal_copy    res 1

I was seeing funny things in the PST window. When I add a line at endprog, everything settled down.

  endprog
    jmp  #$

Is it possible that the P2 is interpreting the variables as instructions? Or that the cog just runs out? In all of my Spin code, especially code that prints to a terminal, I go into a repeat loop so that the TX pin doesn't shutdown and send garbage to the terminal. Am I missing something?

proppy

@JonnyMac said:

Is it possible that the P2 is interpreting the variables as instructions? Or that the cog just runs out? In all of my Spin code, especially code that prints to a terminal, I go into a repeat loop so that the TX pin doesn't shutdown and send garbage to the terminal. Am I missing something?

Thank you for the feedback! Most likely yes! That's because the jmp literally jumps to endprog. The only thing is, on FlexProp, I don't seem to run into that issue. But possible it may be an issue if using PNut or other software, since it might see those variables and just execute them, basically executing garbage. I do not have PNut but this helps the manual since jmp #$ should work in FlexProp.

Wuerfel_21

Letting the program counter just run off is definitely an error. You need to either enter an infinite loop or issue a cogstop. What happens afterwards will (in the case of very short programs) largely depend on stale RAM contents, which might differ based on a number of things. (If you have the debugger enabled, it should set unused memory to zero on startup...)

JonnyMac

...on FlexProp, I don't seem to run into that issue...

It's work, I know, but I suggest you ensure your code works with PNut, FlexProp, and Spin Tools. I try to do this with anything I release to the public.

proppy

@JonnyMac said:

...on FlexProp, I don't seem to run into that issue...

It's work, I know, but I suggest you ensure your code works with PNut, FlexProp, and Spin Tools. I try to do this with anything I release to the public.

Oh I don't disagree. I just updated the repository with the fix. Also, you may want to get the pdf again before printing. I refreshed the examples in that as well. For PNut, I may need to dig up a machine and put windows on it, so that part may take a bit but will do this before official v1.0 though. Thank you!

JonnyMac

PNut is not a big program, it will probably run in a VM.

ersmith

PNut works reasonably well under Wine. Getting the serial communication to work is a bit fiddly, but you can always compile the binary and then download it with loadp2.

proppy

@JonnyMac said:
PNut is not a big program, it will probably run in a VM.

@ersmith said:
PNut works reasonably well under Wine. Getting the serial communication to work is a bit fiddly, but you can always compile the binary and then download it with loadp2.

Oh really? Perfect! Thanks for that. I do have a FreeBSD machine with Wine so i can try it out there.