P2 Manuals — Out for Community Review
Stephen Moraco
Posts: 479
We've got four new manuals for our P2 ready for your eyes, and I'd like to ask the
community to help us check them.
These are AI-assisted drafts, guided by human direction, and grounded deeply in the Parallax Published Documentation and the PNut compiler source — and, where it counts, checked on real P2 silicon — even still, this means they can miss in their own particular ways, the kind of thing automated checks can't catch but a practitioner spots in a heartbeat. That's why they're review editions, not finished books, and why your eyes matter. (Two short companion reads go deeper on how they're built and what to watch for — Why You Can Trust What's in These Manuals and How These Manuals Are Made — and How They Stack Up.)
Here's what's on the table and why you'd reach for each one:
P2 Assembly Language Reference Manual — v3.0.0
The look-it-up book for PASM2. Every instruction with its real syntax, encoding,
behavior, flag effects, and a practical example — laid out alphabetically so you
can land on the one you need without hunting. The front of the book sets the
foundation (execution models, instruction formats, flags, timing, hardware
integration) so the per-instruction pages can stay tight. This is the one you keep
open on the second monitor while you're writing assembly.
P2 Assembly Programming (deSilva Style) — v3.0.0
If the Reference is the book you look things up in, this is the book you learn
from. It follows in the footsteps of deSilva's legendary P1 tutorial, carrying that
same warm, hands-on, "learn-by-doing" spirit over to the P2 — start with a blinking
LED and work up through COG architecture, hub memory, CORDIC, Smart Pins, and
getting multiple COGs to cooperate. Reach for this one when you want PASM2 to
actually be fun to pick up, not a wall of mnemonics.
P2 Streamer Programming Guide — v1.0.1
The streamer is the DMA-like engine that shovels data between hub RAM, the pins,
and the DACs — and it's one of the parts of the P2 that's genuinely hard to get
going from the silicon docs alone. This guide walks every mode (immediate,
RDFAST/WRFAST, RGB video, ADC sampling, DDS/Goertzel), the NCO timing and frequency
math, DAC routing and pin control, and the application patterns that put it to work
(video out, high-speed serial, signal processing). Reach for this when you want
video, fast I/O, or signal work and need the streamer to make sense.
P2 Debug Window Manual — v1.0.0
See what your program is actually doing. This is the complete guide to the P2's nine
DEBUG display windows — TERM, BITMAP, PLOT, LOGIC, SCOPE, SCOPE_XY, FFT, SPECTRO,
and MIDI — with every window's directives, parameters, ranges, and defaults, and a
worked example in each chapter that runs on a bare P2 with no wiring (thermal
heatmap, PID strip-chart, glitch capture, motor run-up, and more). There's a
downloadable library of 32 compile-clean Spin2 programs to go with it. Reach for
this when you'd rather watch your data on screen than squint at raw numbers.
The kind of feedback that helps us most — and how to send it our way — is
described right on the review page. That's the whole point of a review edition, and
your expertise is what makes each release of these manuals better.
👉 Read the four manuals and report what you find here:
Documents in Community Review
I look forward to seeing what you find — please let me know when you do!
-Stephen
Comments
Why You Can Trust These P2 Manuals — the Honest Version
Alongside the four manuals we just put out for review, I wanted to answer the question
I'd ask first if I were standing in your shoes: these are AI-assisted — so why should I
trust a word of them?
That's a fair question, and it deserves a real answer instead of a reassuring noise. So
we wrote one down. It walks the whole chain — where every fact comes from, how it's
checked against the Parallax documentation and against real silicon, how we audit our
own drafts (and how the community caught us early on, which is the reason those audits
exist at all), what we flatly refuse to claim, and what happens when you report a problem
(short version: it ships fast).
There's no marketing in it. Where we've been wrong, it says so. Where the chip overruled
us — including our own already-released work — it says that too.
👉 Read it here: Why You Can Trust What's in These Manuals
Then read the manuals with a sharp eye and tell us what you find — that's the part that
makes every release that follows sharper. I look forward to seeing what you turn up.
-Stephen
How These P2 Manuals Are Made — and How They Stack Up
The other companion piece to the community review is about craft: how these manuals are
built, and how that holds up against the way the best technical reference manuals in the
world are actually produced.
We didn't want to grade our own homework, so we went and looked at what the top
publishing houses and the documentation standards really do — single-source authoring,
code that's actually compiled and run, multi-pass editing, professional indexing, errata
discipline, accessibility — and then laid our own process down next to it. Honestly.
Where we meet the bar, where we get past it (the two things a printed book structurally
can't do — check itself against real silicon, and serve an AI as well as a human), and
where a traditional house still has us and we know it.
It also says plainly why we use AI at all, and lands on the one line that matters: the AI
is why a small team could write manuals this complete; the verification — the
sources, the compiler, the silicon, the audits — is why you can trust what's in them. Two
different things, and we keep them apart on purpose.
👉 Read it here: How These Manuals Are Made — and How They Stack Up
-Stephen
(On the ASM manual)
Hey at least it's no longer all turbo-wrong....
But a significant chunk of the examples are what I'd call "not entirely wrong but would be very confusing if I was confronted with them".
e.g.
This is not a "common pattern", no one in their right mind writes this over using FLE. I know it's supposed to be a condition sample, but find a better one.
Or tell claudeTM to find a better one. He can do anything I hear.
(warning: incoherent ramble upcoming)
All a symptom of the times. We live in the Downward Spiral, the Omnicrisis. No one can do things anymore. Things that people used to make in a few days, weekends, months now seem like impossible monoliths and we tell ourselves that we need things like AI slop to achieve what used to be the baseline. Humans couldn't have possibly written the P1 manual and sample objects and appnotes with the primitive technology available in *checks notes* 2006 A.D. ; It must've been written by space aliens from space that Chip Gracey was in communicating with, his propeller hat acting as an antenna to receive their foreign mind waves. Other explanations defy all logic. It's not a phenomenon contained to Parallax or semiconductors or anything. Look how every new house is just a prefab box with haphazardly placed windows and doors. Sometimes I go to the old town just to remember there was a time when each building got unique Stucco decorations applied to it by hand. No longer possible, too much work. Maybe they can AI-generate them in the future...
Thank you for doing this. Some comments about the look of the manuals: