kicad-mcp/docs/pattern_guide.md

KiCad Circuit Pattern Recognition Guide

This guide explains how to use the circuit pattern recognition features in the KiCad MCP Server to identify common circuit blocks in your schematics.

Overview

The circuit pattern recognition functionality allows you to:

1. Automatically identify common circuit patterns in your KiCad schematics
2. Get detailed information about each identified circuit
3. Understand the structure and function of different parts of your design
4. Quickly locate specific circuit types (power supplies, amplifiers, etc.)

Quick Reference

Task	Example Prompt
Identify patterns in a schematic	Identify circuit patterns in my schematic at /path/to/schematic.kicad_sch
Identify patterns in a project	Analyze circuit patterns in my KiCad project at /path/to/project.kicad_pro
Get a report of identified patterns	Show me the circuit patterns in my KiCad project at /path/to/project.kicad_pro
Find specific patterns	Find all power supply circuits in my schematic at /path/to/schematic.kicad_sch

Using Pattern Recognition Features

Identifying Circuit Patterns

To identify circuit patterns in a schematic:

Identify circuit patterns in my schematic at /path/to/schematic.kicad_sch

This will:

• Parse your schematic to extract component and connection information
• Apply pattern recognition algorithms to identify common circuit blocks
• Generate a comprehensive report of all identified patterns
• Provide details about each pattern's components and characteristics

Project-Based Pattern Recognition

To analyze circuit patterns in a KiCad project:

Analyze circuit patterns in my KiCad project at /path/to/project.kicad_pro

This will find the schematic associated with your project and perform pattern recognition on it.

Viewing Pattern Reports

For a formatted report of identified patterns:

Show me the circuit patterns in my KiCad project at /path/to/project.kicad_pro

This will load the kicad://patterns/project/path/to/project.kicad_pro resource, showing:

• A summary of all identified patterns
• Detailed information for each pattern type
• Component references and values
• Additional characteristics specific to each pattern type

Searching for Specific Pattern Types

You can also ask about specific types of patterns:

Find all power supply circuits in my schematic at /path/to/schematic.kicad_sch

Show me the microcontroller circuits in my KiCad project at /path/to/project.kicad_pro

Supported Pattern Types

The pattern recognition system currently identifies the following types of circuits:

Power Supply Circuits

• Linear voltage regulators (78xx/79xx series, LDOs, etc.)
• Switching regulators (buck, boost, buck-boost)

Amplifier Circuits

• Operational amplifiers (general-purpose, audio, instrumentation)
• Transistor amplifiers (BJT, FET)
• Audio amplifier ICs

Filter Circuits

• Passive filters (RC low-pass/high-pass)
• Active filters (op-amp based)
• Crystal and ceramic filters

Oscillator Circuits

• Crystal oscillators
• Oscillator ICs
• RC oscillators (555 timer, etc.)

Digital Interface Circuits

• I2C interfaces
• SPI interfaces
• UART/Serial interfaces
• USB interfaces
• Ethernet interfaces

Microcontroller Circuits

• Various microcontroller families (AVR, STM32, PIC, ESP, etc.)
• Development boards (Arduino, ESP32, Raspberry Pi Pico, etc.)

Sensor Interface Circuits

• Temperature sensors
• Humidity sensors
• Pressure sensors
• Motion sensors (accelerometers, gyroscopes)
• Light sensors
• Many other sensor types

Extending the Pattern Recognition System

The pattern recognition system is designed to be extensible. If you find that certain components or circuit patterns you use frequently aren't being recognized, you can contribute to the system.

Adding New Component Patterns

The pattern recognition is primarily based on regular expression matching of component values and library IDs. The patterns are defined in the kicad_mcp/utils/pattern_recognition.py file.

For example, to add support for a new microcontroller family, you could update the mcu_patterns dictionary in the identify_microcontrollers() function:

mcu_patterns = {
    # Existing patterns...
    "AVR": r"ATMEGA\d+|ATTINY\d+|AT90\w+",
    "STM32": r"STM32\w+",
    
    # Add your new pattern here
    "Renesas": r"R[A-Z]\d+|RL78|RX\d+",
}

Similarly, you can add patterns for new sensors, power supply ICs, or other components in their respective functions.

Adding New Circuit Recognition Functions

For entirely new types of circuits, you can add new recognition functions in the kicad_mcp/utils/pattern_recognition.py file, following the pattern of existing functions.

For example, you might add:

def identify_motor_drivers(components: Dict[str, Any], nets: Dict[str, Any]) -> List[Dict[str, Any]]:
    """Identify motor driver circuits in the schematic."""
    # Your implementation here
    ...

Then, update the identify_circuit_patterns() function in kicad_mcp/tools/pattern_tools.py to call your new function and include its results.

Contributing Your Extensions

We strongly encourage you to contribute your pattern recognition extensions back to the project so that everyone can benefit from improved recognition capabilities!

To contribute:

1. Fork the repository on GitHub
2. Make your changes to add new patterns or recognition functions
3. Test your changes with your own schematics
4. Submit a pull request with:
   • A description of the new patterns you've added
   • Examples of components/circuits that can now be recognized
   • Any test cases you used to verify the recognition

Your contributions will help build a more comprehensive pattern recognition system that works for a wider variety of designs.

Troubleshooting

Patterns Not Being Recognized

If your circuits aren't being recognized:

1. Check component naming: The pattern recognition often relies on standard reference designators (R for resistors, C for capacitors, etc.)
2. Check component values: Make sure your component values are in standard formats
3. Check library IDs: The system also looks at library IDs, so using standard libraries can help
4. Look at existing patterns: Check the pattern_recognition.py file to see if your components match the existing patterns

Pattern Recognition Fails

If the pattern recognition process fails entirely:

1. Check file paths: Ensure the schematic file exists and has the correct extension
2. Verify schematic format: Make sure it's a valid KiCad 6+ .kicad_sch file
3. Check file permissions: Ensure you have read access to the file
4. Try a simpler schematic: Start with a small test case to verify functionality

Advanced Usage

Integration with Other Features

Combine pattern recognition with other KiCad MCP Server features:

1. DRC + Pattern Recognition: Find design issues in specific circuit blocks

   Find DRC issues affecting the power supply circuits in my schematic
   

2. BOM + Pattern Recognition: Analyze component usage by circuit type

   Show me the BOM breakdown for the digital interface circuits in my design
   

3. Netlist + Pattern Recognition: Understand connectivity in specific patterns

   Analyze the connections between the microcontroller and sensor interfaces in my design
   

Batch Pattern Recognition

For analyzing multiple projects:

Find all projects in my KiCad directory that contain switching regulator circuits

Compare the digital interfaces used across all my KiCad projects

Future Improvements

We plan to enhance the pattern recognition system with:

1. More pattern types: Support for additional circuit patterns
2. Better connection analysis: More accurate tracing of connections between components
3. Hierarchical pattern recognition: Identifying patterns across hierarchical sheets
4. Pattern verification: Validating that recognized patterns follow design best practices
5. Component suggestions: Recommending alternative components for recognized patterns

Contribute to Pattern Recognition

The pattern recognition system relies on a community-driven database of component patterns. The more patterns we have, the better the recognition works for everyone!

If you work with components that aren't being recognized:

1. Check the current patterns in kicad_mcp/utils/pattern_recognition.py
2. Add your own patterns for components you use
3. Submit a pull request to share with the community

Common areas where contributions are valuable:

• Modern microcontroller families and variants
• Specialized sensor types
• Power management ICs
• Interface and communication chips
• Industry-specific components

Your expertise in specific component types can help make the pattern recognition more useful for everyone!