kicad-ipc-rs

Control KiCad programmatically from Rust. The most complete, production-ready client for KiCad's IPC API — async-first with full sync support.

• 100% API coverage (57/57 KiCad v10.0.0 commands)
• Type-safe PCB item manipulation with ergonomic Rust models
• Both async and blocking APIs for any application architecture
• Zero protobuf dependencies for consumers — everything is typed Rust

Status

Beta. All KiCad v10.0.0 API commands are implemented and tested.

• Async API (default): production-ready with full feature parity
• Sync/blocking wrapper API (feature = "blocking"): production-ready, uses dedicated Tokio runtime thread

Prerequisites

• Rust 1.70+ (edition 2021)
• KiCad 10.0.0+ running with the IPC API enabled
• The nng transport library is bundled automatically via nng-rs

Enabling the KiCad IPC API

1. Open KiCad → Preferences → Plugins
2. Check Enable IPC API
3. Restart KiCad

The API socket path is auto-detected. Override with KICAD_API_SOCKET if needed.

Usage

Async API (Default)

Add to Cargo.toml:

[dependencies]
kicad-ipc-rs = "0.4.1"
tokio = { version = "1", features = ["macros", "rt"] }

Connect and query KiCad:

use kicad_ipc_rs::KiCadClient;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
    let client = KiCadClient::connect().await?;
    
    // Get KiCad version info
    let version = client.get_version().await?;
    println!("Connected to KiCad {}", version.full_version);
    
    // Check if a board is open
    if client.has_open_board().await? {
        // Get all nets in the current board
        let nets = client.get_nets().await?;
        println!("Found {} nets", nets.len());
        
        // Get all tracks on the board
        let tracks = client.get_items_by_type_codes(vec![
            kicad_ipc_rs::PcbObjectTypeCode::new_trace()
        ]).await?;
        println!("Found {} tracks", tracks.len());
    }
    
    Ok(())
}

Sync API (Blocking)

Enable the blocking feature for synchronous applications:

[dependencies]
kicad-ipc-rs = { version = "0.4.1", features = ["blocking"] }

use kicad_ipc_rs::KiCadClientBlocking;

fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
    let client = KiCadClientBlocking::connect()?;
    
    // Get all nets and find unconnected ones
    let nets = client.get_nets()?;
    let unconnected: Vec<_> = nets
        .iter()
        .filter(|n| n.name == "unconnected")
        .collect();
    
    println!("Found {} unconnected nets", unconnected.len());
    Ok(())
}

Making Changes to PCBs

All board modifications use commit sessions for safety:

use kicad_ipc_rs::{KiCadClient, CommitAction};

async fn add_track(client: &KiCadClient) -> Result<(), kicad_ipc_rs::KiCadError> {
    // Start a commit session
    let commit = client.begin_commit().await?;
    
    // Create items (tracks, vias, footprints, etc.)
    let items = vec![/* your PcbItem instances */];
    let created_ids = client.create_items(items).await?;
    
    // Commit the changes
    client.end_commit(
        commit.id,
        CommitAction::Commit,
        "Added new track"
    ).await?;
    
    Ok(())
}

For in-place editing flows, fetch editable items, mutate them, then write them back:

use kicad_ipc_rs::EditablePcbItem;

let mut items = client.get_editable_items_by_id(ids).await?;
let back_cu = client.get_active_layer().await?.id;

for item in &mut items {
    match item {
        EditablePcbItem::Track(track) => track.set_layer_id(back_cu),
        EditablePcbItem::BoardText(text) => text.set_layer_id(back_cu),
        EditablePcbItem::Zone(zone) => zone.set_layer_ids(vec![back_cu]),
        _ => {}
    }
}

client.update_editable_items(items).await?;

PCB Item Model Layers

• Raw IPC layer: prost_types::Any payloads from KiCad commands (*_raw APIs).
• Read model layer: PcbItem for inspection/analysis when you do not need mutation.
• Editable model layer: EditablePcbItem for ergonomic mutate/update workflows.

EditablePcbItem wrappers also expose proto() / proto_mut() / into_proto() as advanced
escape hatches when you need direct protobuf access.

Examples

Run the included examples against a running KiCad instance:

# Minimal connection + version check
cargo run --example hello_kicad --features blocking

# Inspect board nets, layers, and origin
cargo run --example board_inspector --features blocking

# Deep-dive into current PCB selection
cargo run --example selection_deep_dump --features blocking

See the examples/ directory for full source.

KiCad Version Compatibility

This crate tracks KiCad releases. When KiCad updates their API, we update within a week. Currently supports KiCad 10.0.0.

KiCad v10.0.0 API Reference

All 57 KiCad v10.0.0 API commands are implemented:

Section Coverage

Command Reference

Common (base)

Common editor/document

Project manager

Board editor (PCB)

Documentation

• Guide: https://milind220.github.io/kicad-ipc-rs/
• API Reference: docs.rs/kicad-ipc-rs

Protobuf Source

This crate ships checked-in Rust protobuf output under src/proto/generated/.

• Consumers do not need KiCad source checkout or git submodules
• Maintainers regenerate bindings from KiCad upstream via the kicad git submodule
• Current proto pin: KiCad 10.0.0 (KICAD_API_VERSION = 10.0.0-0-g0feeca2a)

Maintainer refresh flow:

git submodule update --init --recursive
./scripts/regenerate-protos.sh

Contributing

See CONTRIBUTING.md for development workflow and commit conventions.

Issues and PRs welcome!

License

MIT