Shop OBEX P1 Docs P2 Docs Learn Events
P2 Knowledge Base - support for command-line AI agents as our P2 development coding partner — Parallax Forums

P2 Knowledge Base - support for command-line AI agents as our P2 development coding partner

Stephen MoracoStephen Moraco Posts: 366
in AI Tools and Techniques

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:

  1. Navigate systematically through manifests to find exactly the right instruction or technique
  2. Generate accurate code based on verified P2 specifications and real examples
  3. Suggest optimal approaches using proven patterns from the community
  4. 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:

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:

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

  • Christof Eb.Christof Eb. Posts: 1,417
    edited 2025-09-13 18:29

    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.
    :D Christof

    PS first link gives error 404

  • Stephen MoracoStephen Moraco Posts: 366

    @"Christof Eb." said:
    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.
    :D 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.

  • evanhevanh Posts: 16,701

    Add examples to the existing two reference docs that Chip wrote: Silicon Manual and Spin2 Manual. Examples would hopefully clarify wording already present.

  • Wuerfel_21Wuerfel_21 Posts: 5,536

    The evidence goes to another school, you wouldn't know it.

  • evanhevanh Posts: 16,701
    edited 2025-09-14 01:38

    @Wuerfel_21 said:
    The evidence goes to another school, you wouldn't know it.

    Who you replying to? And evidence of what?

    Ah, this'll be it:

    @"Stephen Moraco" said:
    ... what you haven't seen evidence of yet is our ability to generate documentation from this highly accurate understanding of the P2.

  • Christof Eb.Christof Eb. Posts: 1,417

    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.

  • evanhevanh Posts: 16,701
    edited 2025-09-14 07:12

    Good point:

    • Spin language is designed to make learning programming, for the human, easier.
    • The objective of using AI for coding is to not need to learn programming at all. The output may as well be assembly.

    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.

  • Wuerfel_21Wuerfel_21 Posts: 5,536

    (If this needs to be said, please do not vandalize the existing google doc files)

Sign In or Register to comment.