P2 Knowledge Base - support for command-line AI agents as our P2 development coding partner
Stephen Moraco
Posts: 366
NEWS: Introducing the P2 Knowledge Base v2.0 - Structured P2 Documentation for AI-Assisted Development
I'd like to share a project I've been working on for P2 developers who use AI coding assistants like Claude Code, GitHub Copilot, and ChatGPT.
What is the P2 Knowledge Base?
The P2 Knowledge Base is a structured documentation system specifically designed for AI-assisted P2 development. It provides comprehensive P2 reference material in a format that AI assistants can navigate and understand systematically, enabling accurate code generation and technical guidance.
Repository: https://github.com/IronSheepProductionsLLC/P2-Knowledge-Base
Key Features
Complete P2 Coverage (80% complete):
- 357 PASM2 instructions with detailed specifications and examples
- 32 Smart Pin modes with configuration patterns and real-world usage
- Complete architecture documentation covering all 8 COGs, Hub memory, and timing
- Spin2 language constructs with method documentation
- Proven code patterns from real-world P2 projects
Structured Format:
- Hierarchical manifests that AI systems can navigate systematically
- Consistent YAML specifications for reliable parsing
- Cross-referenced documentation linking related concepts and instructions
- Detailed instruction encodings with constraints and usage notes
Code Patterns and Examples:
- Multi-COG communication patterns from real P2 projects
- Smart Pin configuration templates for common use cases
- Proven implementation techniques from working drivers
- Instruction usage examples with proper syntax
How It Works with AI Assistants
Instead of AI assistants guessing at P2 capabilities or generating potentially incorrect code, they can now:
- Navigate systematically through manifests to find exactly the right instruction or technique
- Generate accurate code based on verified P2 specifications and real examples
- Suggest optimal approaches using proven patterns from the community
- Validate generated code against official instruction encodings and constraints
Example interaction:
You: "Help me configure a Smart Pin for quadrature encoding"
Claude: *Checks smart-pins manifest → finds mode 11000*
"Use Smart Pin mode %11000 for quadrature. Here's the configuration..."
Getting Started with AI-Assisted Development
This first release is specifically designed for AI-assisted workflows:
- Quick Start Templates - Copy-paste prompts to get started immediately
- Complete Usage Guide - Comprehensive setup and best practices
- AI Prompt Patterns - Interaction patterns for all P2 development scenarios
Works with all major AI assistants: Claude Code, GitHub Copilot, ChatGPT, and other command-line AI agents.
Note: Traditional human-readable documentation support is planned for future releases - this v2.0 focuses on proven AI-assistant compatibility.
What Makes This Different
This documentation is structured specifically for AI assistant compatibility:
- Consistent format that AI systems can reliably parse
- Complete instruction coverage with encoding details for validation
- Real-world patterns that AI can reference and adapt
- Cross-platform compatibility - works with Claude, GPT, Copilot, and other AI assistants
Development Process
This has been a systematic effort involving:
- Comprehensive extraction from official P2 documentation and silicon references
- Pattern analysis of proven P2 implementations
- AI interaction testing to ensure optimal assistant performance
- Community validation using real-world development scenarios
We maintain comprehensive regression testing and continue expanding coverage based on community needs and new P2 capabilities.
Looking Ahead
Future development includes:
- Traditional documentation support for human developers (planned)
- Enhanced Spin2 method documentation (comprehensive coverage of current language specification)
- Advanced video generation patterns for complex display applications
- USB implementation details as the community develops more USB projects
- Community integration - something exciting coming soon! 😉
Community Engagement
I'd love to hear your experiences using this with AI assistants! If you encounter any issues or have suggestions for improvements:
- GitHub Issues: https://github.com/IronSheepProductionsLLC/P2-Knowledge-Base/issues
- Direct feedback in this thread
Have you tried AI-assisted P2 development? What challenges have you faced that a structured knowledge base might help solve?
Try it out and let me know what you think!
Best regards,
Stephen
Comments
Hi, we have asked for ages for proper propeller 2 documentation and now it's being done. For ai machines, not for humans. Weird World.
Christof
PS first link gives error 404
I'm on the link issue, thanks for reporting it.
You are so right! However, what you haven't seen evidence of yet is our ability to generate documentation from this highly accurate understanding of the P2. I am deeply auditing all of our available documentation, and I'm blending this with actual studies of the compiler (pnut_ts) itself to provide a highly accurate language description for all of Pasm2 and Spin2. In doing this, I'm able to thoroughly audit what we know of each region of the P2. From this, I have a pretty good idea of where detailed information is lacking. I'm working to expand our knowledge in these areas. From this, we can generate rich documentation. Of course, all of these documents that we develop will need a complete technical review. But this might be an amazing opportunity for our community. This is what I'm trying to prototype/prove out.
So, anticipating some success in what I'm doing ... If you had your druthers, what would be the first three documents you would wish to see? Which are most important to you and why? As P2 community members, we might not all have the same 3 in mind, so I'm asking.
Add examples to the existing two reference docs that Chip wrote: Silicon Manual and Spin2 Manual. Examples would hopefully clarify wording already present.
The evidence goes to another school, you wouldn't know it.
Who you replying to? And evidence of what?
Ah, this'll be it:
For humans, I don't know what is good for ai:
With P2 special hardware is very much interwoven with special instructions. So in my opinion for this mc hardware and asm software should be described together in one manual. For example LUT can only be used through special lut related instructions.
I am wondering. So now some guy will be able to ask a machine to write some Spin2 code say to print the first 1000 prime numbers. As he can skip to learn to do simple things, he will not learn the special language Spin2. So he cannot check or correct or alter that program. This is a dead end. If you want ai to write a complex program, then you have to describe the problem in such detail, that you could write the code instead.
In my opinion if you do want to use ai, then a standard language makes at least the same sense as for humans. Ai and humans can both use their already learned knowledge or take source code from some book or github. As C compilers exist now for P2, it makes a lot more sense to me to use them instead of Spin2. The basis of known and proven solutions is so much bigger and growing.
Good point:
Of course, AI tools are nowhere near that capable - but that's still how they are designed and anyone can get AI to produce programs that don't work ... then they're none the wiser as to how to make them work.
(If this needs to be said, please do not vandalize the existing google doc files)
It would be a good opportunity to ditch the word-processor altogether and convert those documents to proper publishing tools.
I think google docs can export straight-out Markdown, so maybe I could import them into a P2Docs subdirectory. The silicon doc, anyways, that one's not being changed anymore, I think. The official instruction table has been there from the start.
(edit: yeah that works, but the MD file is super weird, will need some cleanup to render nicely in SiteGen! and also the pictures are missing)
(edit 2: wait wtf the images are base64-encoded as footer refs WTF WTF)
(edit 3: URRGRGRGRGR this has all the comments from idiots just mixed in I hate this)
There we go: https://p2docs.github.io/mirror/p2silicon.html
Still some word-processor-isms that need to be reformatted, but I had enough trouble getting all the images to be in the right places (some might need to be scaled down a bit).
Ah, much better now.
The code sections were all a mess when I first had a look.
I have been working with Claude.ai for several days. I have started digging through boxes and finding things I bought years ago and using Claude to try to make them work with a P2. Yesterday I had success with a TMP102 temperature sensor I bought from Sparkfun years ago. Claude did not need any kind of driver. He just got the data sheet from Sparkfun and made it work. Together with all the other things he has been doing for me it was just amazing. Today, however, failure. I wanted to use an HIH4030 humidity sensor. It is an extremely simple thing. It puts out an analog voltage on one pin and you just apply some simple math and you have a reading. The problem was that you need to use ADC, a very basic and essential microcontroller function. I have to admit that I don't know how to do it with a P2. Claude made a mighty effort to use a smart pin. He tried everything and just could not do it. I gave him the information about how to access the documentation with the "yaml" and all that stuff and his attempts to access it failed which was strange because I clicked two of the same links and I got someplace, but not knowing what he wanted there I couldn't help him. This happened this afternoon. He tried to do it without a smart pin. No luck. I have found that Claude often takes a very involved approach to things and sometimes can't make them work. A couple of times I have offered him simpler ways that I know work and he has grabbed on to those like a drowning man. I encourage everyone to give ai a try. Flash some LEDs. Ask him to send a command via Xbee from one P2 to another. You will be amazed at what he can do and deeply frustrated by what he can't - not yet, but I'm sure he will get there. We just have to give him the information.
If you can't do the job yourself and using the LLM to guess for you then you're using LLMs incorrectly.
evanh, just a few minutes ago Claude listed your post from 2019 on the topic "How to use Smart Pin for ADC?" as one of the sources he consulted. Claude rummages through all the forums, and I guess, everything else at Parallax. This was after about 6 failed tries to figure out how to read the voltage on pin 3 to which I had applied the 3.3 volt supply voltage. If we can figure that out we will be able to get the humidity sensor working. He has used up all my free time and won't help me again for 5 hours, so I guess I am going to have to search around and figure this out for myself. It won't be the first time I had to figure out something he couldn't.
Frustrated with the P2, today I have turned to the P1. Now I know this forum topic deals with ai and the P2, but in a larger sense my comment is still relevant. With the P1 Claude.ai can flash an led, but after 6 tries (6 seems to be my limit) he still can't start a new cog to flash an led on the P1. And he claims to have full access to the Propeller Manual. I could show him how to do it, but is he here to help me or am I here to help him? I have gotten a couple of good P2 programs out of him this week, but not being able to measure a voltage on a P2 pin, can't start a new cog to flash an led in P1? I am done with this, for now.
I just uploaded my jm_adc.spin2 object to ObEx -- that will help you measure the voltage on a P2 pin.
-- https://obex.parallax.com/obex/p2-adc/
The A in AI is for "artificial" and we have to keep that in mind. I have had some successes with claude.ai, but usually with things that are not specific to the P2. In fact, I rarely ask AI to generate Propeller code; instead, I ask for generic code and then adapt it myself.
Thank you JonnyMac! What I told you at Parallax in Rocklin in May still holds true. Anything I know about the P2 I learned from you. I am going to have to study your jm_adc.spin2 program for a while before I understand it all. Claude, he understood it in about a nanosecond. He can now measure voltages, at least for my programs. With that he was able to get the HIH4030 humidity sensor working a few minutes later. I am finding that the best way to work with Claude.ai is to develop programs incrementally just like we have always done, build it up a little bit at a time, make sure everything is working and then extend it.
I had a discussion with Claude.ai today about his repeatedly making the same mistakes in Spin2 syntax.I asked him about the P2 Knowledge Base and he said he was aware of it because I had given him the following, as I do at the start of every session:
"I am using the Parallax P2 processor.
Please access the P2 Knowledge Base directly from GitHub:
https://github.com/ironsheep/P2-Knowledge-Base
Start by reading the root manifest for navigation:
https://raw.githubusercontent.com/ironsheep/P2-Knowledge-Base/main/manifests/p2-knowledge-root.yaml."
He asked me if I would like him to look at it now and I asked him to.
And then this appeared and it is similar to things I see every day:
"Failed to fetch https://raw.githubusercontent.com/ironsheep/P2-Knowledge-Base/main/manifests/spin2-manifest.yaml"
And at this point Claude said,
"I can't access the Spin2 manifest because I can only fetch URLs that are either provided directly by you or appear in search results. Since I fetched the root manifest earlier through your instructions, I could access that, but the system won't let me follow the nested links to the specific manifests without explicit permission."
Interesting. Am I making some sort of mistake that is preventing him from seeing what he needs?
You do know that LMMs are not aware, right? It doesn't understand anything it says, or anything you say for that matter. It's just a fancy parroting machine. Which is also why they can be used like a search engine.
I was bored so I actually looked at your repo Stephen, and I've never seen hotter garbage in my entire life, like, wow, a true accomplishment in snatching shit from the jaws of mediocrity.
Remember here that misinformation has negative value. Especially to a clanka with no grounding in empiric reality.
It's easy to create documentation with great coverage if the information doesn't need to be accurate, but you could use a 100% organic typewriter monkey for such a purpose and it'd be better for the environment and less easily confused with factual documentation.
Also I don't know what you're trying to accomplish by putting text in a YAML file, I Don't Think It Works Like That. Or rather, no better than otherwise (un)structured text. I've been seeing memes about the futility of this formal-language-as-LLM-prompt approach already, lol.
WOW, indeed.
In all the years I've been on this forum, I've never seen a comment so needlessly mean spirited.
You're entitled to your opinion, but this sort of personal attack adds nothing constructive and goes against the spirit of this community and the way Parallax has always conducted itself.
If you can't make your point respectfully, then it s probably best not to make it at all.
You owe Stephen an apology.
I've seen worse posts on here (though those usually escalate to some lunatic getting kicked).
I gave him the nice and constructive version in a private conversation some time ago already (you couldn't have known this, so it's fine to react like that). Then he rolls up with this slopfest (do take a gander yourself, it's baaaaad). So I would call that justifiably mean-spirited. As mentioned, misinformation has negative value. It's actively offensive in the way other types of bad endeavors aren't. This is the root of Cunningham's Law.
If you try build a house on a foundation of sand, the most constructive thing you can do is tear it down so it doesn't collapse on someone.
Haha, I immediately had the same thought. In fact, I'm very irritated that Parallax is spending money for this IMHO quite useless stuff. Yes, there is a hype, currently, about AI and you can't ignore that completely. So I don't argument against having discussions about it and doing some experiments.
But the priority should be on humans, I mean, documantation that is not only understandable by humans but is spreading excitement, motivation and fun. People want to learn. Yes, we already have rather formal documentation for the P2 chip that seems to be sufficient for most of us geeks and nerds here to produce some amazing hard and software. But it would be even better to have something like the P1 manuals. They were really excellent with lots of examples and hints.
The biggest problems, not only with AI but with engineering in general are:
If those problems are solved then the actual coding is a no-brainer. And a newcomer who struggles with those questions will not benefit at all from AI. The frustration about their own inability will onkly be replaced by frustration about something else not doing what was intended.
So please finish the P2 documentaions for humans. Put emphasis on purpose and intentions, not only on function and formalism. People need to understand how things work and why they work. Then and only then you can judge if the results AI gives you is useful or garbage. Then you can use AI to delegate boring and exhausting tasks you don't want to do by yourself.
^ 100% this
Item 2 there just gave me an idea. Do we need a glossary of Propeller-specific terminology?
EDIT: Yes we do https://forums.parallax.com/discussion/177863/p2-glossary-suggestion-and-brain-mind-explordination-thread
Also put emphasis on correctness first and foremost! As aforementioned, wrong information is worse than nothing/a placeholder. This is why LLMs mustn't be used in the creation of such documentation.
I am a non-believer in the idea that you'd need separate documentation optimized for LLM nonsense in the first place; An LLM is not a YAML parser, the whole point is that it's a Natural Language Processing magic black box.
If you wanted that to work, just putting a bunch of docs in the context buffer is probably not entirely it, anyways, you'd probably want to grab a weights file for some Open Source [sic] assistant and fine-tune it on known good Spin2 code. (probably, idk, not an expert) I have a hunch the main reason this doesn't really work out of the box is that when they go to pilfer e.g. GitHub for source code to steal for training purposes, they'll find:
Anyways, I have no idea how my half-ass, half-finished, plushie-adorned P2docs site is now becoming the supreme source for docs that Parallax should be providing (or at least I see people here use it quite often).
Hey @"Ken Gracey" , mind linking it ( https://p2docs.github.io ) on https://www.parallax.com/propeller-2/documentation/ ? There's some other community material there already. And now I have a copy of the Chip Silicon Google Doc that isn't a huge PITA to use.