Design de PCB (KiCad 8/9)
Crie arquivos de PCB KiCad fabricáveis, sintaticamente válidos e os produza como arquivos s-expression .kicad_pcb. O KiCad é a estrutura principal. Não confie na memória para o formato de arquivo — use a documentação do desenvolvedor do KiCad e os recursos limpos e validados como fonte de verdade.
Dialeto alvo: KiCad 9 ((version 20241229)). O KiCad 8 (20240108) é suportado com as diferenças listadas em references/pcb-file-format.md#version-dialect-matrix — notavelmente os ordinais das camadas, que mudaram novamente na versão 9. Nunca misture dialetos: gráficos da era v6/v7 com (tstamp ...) ou v6 com (width ...) dentro de um cabeçalho v8/v9 são a causa mais comum de arquivos que não carregam.
Inegociáveis
- Um dialeto por arquivo. Cabeçalho
version,generator_version, UUIDs de trilhas, sintaxe de stroke e campos de footprint devem corresponder à versão declarada. - Uma placa é um arquivo completo, não um trecho. Ela deve abrir no KiCad e passar no verificador estrutural abaixo.
- Conectividade é geométrica. Uma trilha com o número de net correto que não toca em um pad ou em outra trilha ainda está não roteada.
- Sem palpites elétricos silenciosos. O mapeamento pino-para-net, polaridade, escolha de footprint e espaçamento de segurança devem ser declarados como suposições ou questionados.
- Não afirme conformidade de fabricação sem limites de fábrica verificados. Os números de fabricação dependem da pilha e do fornecedor.
- Nenhuma declaração de liberação sem um relatório aprovado. Uma placa está pronta para liberação somente quando
report/design-report.jsondizprofessional_claim: true. Caso contrário, liste os portões falhos e as aprovações ausentes.
Pipeline de Design Automático (preferido para novas placas)
Não autorize manualmente uma placa de liberação quando este pipeline pode fazê-lo. O pipeline transforma uma especificação de design em uma placa com footprints reais da biblioteca do KiCad, roteia-a com Freerouting, executa KiCad DRC + DFM + paridade de netlist, exporta Gerbers/furação/posição/STEP/IPC-D-356 e escreve um relatório de portão. Cada saída listada em profile.fab_outputs é um portão rígido. Use a autorização manual apenas para revisar ou corrigir uma placa gerada.
# 1. Validar intenção (sem necessidade de KiCad)
python3 scripts/design_spec.py validate specs/led-blinky.json
# 2. Design automático completo. Seleciona automaticamente local quando pcbnew do KiCad 9, Java 25
# e Freerouting 2.5.0 estão presentes; caso contrário, despacha para GitHub Actions.
python3 scripts/design_pipeline.py all specs/led-blinky.json
# Fonte de verdade elétrica é um esquemático ou netlist; a especificação fornece mecânica/regras.
python3 scripts/design_pipeline.py all specs/led-blinky.json --schematic design.kicad_sch
python3 scripts/design_pipeline.py all specs/led-blinky.json --netlist design.net
# Placa existente: rotear/verificar/exportar sem reconstruir.
python3 scripts/design_pipeline.py all specs/led-blinky.json --board existing.kicad_pcb --skip-build
# Apenas etapas
python3 scripts/design_pipeline.py build specs/led-blinky.json -o build/led-blinky
python3 scripts/design_pipeline.py route build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json
python3 scripts/design_pipeline.py check build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/check
python3 scripts/design_pipeline.py fab build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/fab
Entradas canônicas. specs/<nome>.json é a fonte de verdade para o caminho automático. Use schemas/design-spec.schema.json e specs/led-blinky.json como modelo. Para uma solicitação em linguagem natural, escreva a especificação primeiro, declare suposições em assumptions[], depois execute o pipeline. Para um esquemático/netlist do KiCad, a netlist é autoritativa para componentes/pads de nets; a sobreposição da especificação fornece tamanho da placa, pilha, regras, posicionamento e roteamento.
Perfis de classe de placa. O perfil seleciona o envelope de regras e os portões de liberação:
| Perfil | Automação | Aprovação humana necessária |
|---|---|---|
2layer-low-speed | Completo: construir, posicionar, rotear, DRC, DFM, fab | nenhum |
4layer-impedance / 6layer-impedance | Com portão: pilha + impedância + verificações de casamento de comprimento | stackup, impedance |
rf-mixed-signal | Assistida; nets de RF devem ser reroteadas manualmente | rf, emc, thermal |
flex-rigid | Assistida | mechanical, flex_bend, assembly |
high-voltage | Com portão; verificações de afastamento/creepage | safety, creepage |
professional_claim é verdadeiro apenas quando cada portão rígido passa e cada aprovação necessária está listada em signoff.completed. RF, EMC, térmica, segurança e fadiga de flexível não podem ser certificadas pelo pipeline; diga isso em vez de reivindicar demais. Registre um revisor em signoff.reviewer.
Seleção de backend: local ou CI (automática). A automação completa precisa de pcbnew (KiCad 9 Python), kicad-cli, Java 25 e freerouting-2.5.0.jar (Freerouting 2.5.0 é construído para Java 25). --backend auto é o padrão: ele verifica o ambiente atual e executa localmente quando todas as etapas solicitadas têm suas ferramentas; caso contrário, ele despacha .github/workflows/design.yml. Esse fluxo de trabalho executa no contêiner oficial kicad/kicad:9.0, instala um JRE 25, baixa o Freerouting, executa o pipeline inteiro e envia design-output + design-report.
| Ambiente | Resultado da sonda | Backend selecionado |
|---|---|---|
| PC real com KiCad 9 + Java 25 + jar | todas as etapas prontas | local |
Termux / contêiner sem KiCad; gh autenticado; repositório enviado limpo | pcbnew/kicad-cli ausente | CI |
| Nenhuma ferramenta local e nenhuma CI utilizável | ausente | local, falha com a lista de ferramentas ausentes |
python3 scripts/env_probe.py # o que esta máquina pode executar?
python3 scripts/env_probe.py --json # sonda legível por máquina
python3 scripts/design_pipeline.py all specs/led-blinky.json # auto
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend local
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend ci --ci-download build/ci
O despacho de CI é conservador: ele recusa uma árvore suja ou um branch à frente de seu upstream, porque Actions verifica a revisão enviada e, caso contrário, projetaria a placa errada. Primeiro, faça commit e push da especificação, perfis, esquemas, scripts e fluxo de trabalho. gh deve estar instalado e autenticado (pkg install gh, então gh auth login). Use --ci-repo owner/name apenas ao despachar para um repositório diferente do atual. As execuções de CI são monitoradas por padrão para que o código de saída reflita professional_claim; adicione --no-ci-watch para retornar imediatamente após o despacho.
Comandos de etapa (build, route, check, fab) executam localmente porque o CI não pode ver arquivos de etapa não commitados; use all --backend ci para uma execução de CI de ponta a ponta. Dentro do GitHub Actions, o pipeline sempre permanece local, portanto, uma execução de CI nunca se redespacha.
Regra de iteração. Quando um portão falha, altere a especificação (posicionamento, largura, afastamento, pilha, atribuição de classe) e regenere. Não edite uma placa gerada e depois afirme que o relatório se aplica; o relatório registra a especificação resolvida exata (<nome>.spec.json).
Fontes de Recuperação (use antes de adivinhar)
| Recurso | URL | Usar para |
|---|---|---|
| Introdução a S-Expression (sintaxe comum) | https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html | Sintaxe, citação, coordenadas, camadas, footprints, pads, gráficos, zonas, grupos |
| Formato de arquivo de placa | https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/index.html | Seções de nível superior do .kicad_pcb, cabeçalho, camadas, configuração, nets, trilhas, zonas |
| Formato de biblioteca de footprints | https://dev-docs.kicad.org/en/file-formats/sexpr-footprint/index.html | Contexto e campos de footprint do .kicad_mod |
| Índice de formatos de arquivo do KiCad | https://dev-docs.kicad.org/en/file-formats/index.html | Formatos de esquemático/símbolo quando um esquemático correspondente é necessário |
| Documentação do KiCad DRC | https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#design-rule-checking | O que o DRC real verifica e quais regras são configuráveis |
| Regras de design personalizadas do KiCad | https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#custom-design-rules | Sintaxe de .kicad_dru e expressões de regras |
| Capacidades do JLCPCB | https://jlcpcb.com/capabilities/pcb-capabilities | Limites de fábrica atuais (verifique antes de usar) |
| IPC-2221 / IPC-2152 | https://www.ipc.org/ | Fundamentos de largura/corrente de trilha, afastamento e creepage |
Os documentos do desenvolvedor estão atrasados em relação ao aplicativo em alguns lugares (eles ainda descrevem gráficos (width ...) pré-v7 e trilhas (tstamp ...)). Quando os documentos e um arquivo real da versão alvo do KiCad discordarem, siga o arquivo real e observe a discrepância.
Referências e Recursos Locais
| Caminho | Conteúdo |
|---|---|
references/pcb-file-format.md | Matriz de versão, seções, ordinais de camada, configuração/pilha, footprints, pads, trilhas, zonas, lista de verificação |
references/sexpr-primitives.md | Sintaxe de token, citação, strokes, efeitos, UUIDs, primitivas de pad/gráfico/zonas, tokens sensíveis à versão |
references/practical-rules.md | Pilha, posicionamento, roteamento, corrente/largura, SI/PI/EMI, impedância, térmica, mecânica, DFM/DFA, padrões |
assets/minimal-2layer.kicad_pcb | Placa em branco de 2 camadas limpa e validada (copie isso como ponto de partida) |
assets/example-led.kicad_pcb | Exemplo roteado limpo e validado: conector THT, resistor SMD/LED, vias, courtyard, furo de montagem |
assets/example.kicad_dru | Exemplos de regras personalizadas (largura de netclass, afastamento de alta tensão) |
schemas/design-spec.schema.json | Especificação de design automático canônica (placa, regras, nets, posicionamento, pilha, portões) |
profiles/*.json | Envelopes de regras de classe de placa e portões de liberação |
specs/led-blinky.json | Especificação de referência para o pipeline automático |
scripts/design_spec.py | Validador de especificação sem dependências, importador de netlist, cálculos de impedância/corrente, relatório de portão |
scripts/pcb_build.py | Especificação → placa KiCad usando footprints reais de biblioteca (pcbnew) |
scripts/pcb_route.py | Exportação DSN → Freerouting → Importação SES → preenchimento de zona |
scripts/pcb_check.py | Portões estruturais, DRC, DFM, paridade de netlist e casamento de comprimento |
scripts/pcb_fab.py | Gerbers, furação, posição, STEP, IPC-D-356 e README de fabricação |
scripts/design_pipeline.py | Orquestra todo o design automático e escreve o relatório de liberação; --backend auto seleciona local ou CI |
scripts/env_probe.py | Detecta pcbnew, kicad-cli, Java 25, Freerouting, gh/git e recomenda local vs CI |
scripts/ci_dispatch.py | Despacha .github/workflows/design.yml, opcionalmente monitora e baixa artefatos |
scripts/check_pcb.py | Verificador estrutural/geométrico de pré-voo sem dependências |
.github/workflows/design.yml | CI: construir, rotear, DRC/DFM, exportação fab e relatório no contêiner KiCad 9 |
Use os termos de pesquisa nessas referências antes de buscar uma página de documento inteira: version, generator_version, layers, stackup, setup, net, footprint, property, attr, pad, stroke, segment, via, zone, keepout, filled_polygon, Edge.Cuts, embedded_fonts, remove_unused_layers, courtyard, impedance, differential, 3W, return path, DFM, trace width.
Fluxo de Trabalho Manual / Revisão
Use o pipeline automático primeiro. Este fluxo de trabalho é para revisar uma placa gerada, corrigir um design cuja especificação não pode expressar uma restrição ou trabalhar em um ambiente onde as ferramentas do pipeline não estão disponíveis.
-
Esclareça a intenção do design (não adivinhe silenciosamente sobre restrições críticas).
- Função da placa, componentes, conectores, nets de alimentação/terra, tamanho alvo e restrições mecânicas.
- Suposições de fabricação: número de camadas (padrão 2), unidades (mm), peso do cobre, pilha, acabamento superficial, processo de montagem.
- Versão alvo do KiCad. Padrão para KiCad 9, a menos que o usuário diga o contrário.
- Se os requisitos forem subespecificados, declare as suposições explicitamente na resposta e codifique padrões razoáveis no arquivo.
-
Modele a netlist elétrica primeiro.
- Defina
(net 0 "")mais cada net nomeada antes que os itens as referenciem. Mantenha os ordinais estáveis e únicos. - Garanta que cada ordinal
netde pad, trilha, via e zona exista; garanta que os nomes(net N "NOME")do pad correspondam exatamente à tabela de nets. - Se existir um esquemático correspondente, os footprints precisam de links
path/referência; um design apenas de placa deve ser marcadoboard_onlyquando apropriado.
- Defina
-
Defina mecânica, camadas e pilha.
- Comece de
assets/minimal-2layer.kicad_pcbe mantenha seu cabeçalho/camadas/configuração válidos. - Defina a seção
layerscom nomes canônicos e os ordinais corretos (veja a tabela emreferences/pcb-file-format.md;B.CrtYd/F.CrtYdnão são sequenciais). - Defina
(general (thickness 1.6) (legacy_teardrops no)),(paper "A4")e umastackuprealista se a pilha for importante. - Forneça um limite
Edge.Cutsfechado (linhas/arcos ou um retângulo/círculo/polígono). Mantenha o cobre longe da borda.
- Comece de
-
Posicione footprints.
- Use definições completas de footprint incorporadas:
layer,uuid,at, camposproperty(Reference/Value),attr smd|through_hole, pads, serigrafia, courtyardF.CrtYd/B.CrtYde, opcionalmente,F.Fabe um modelo 3D. - Posicione por função: conectores, entrada de alimentação e MCU primeiro; agrupe circuitos relacionados; separe domínios analógico/digital/ruidosos.
- Coloque capacitores de desacoplamento em cada pino de alimentação/terra do IC com área de loop mínima; valores/pacotes conforme folha de dados ou suposições declaradas.
- Respeite o espaçamento de courtyard e montagem; mantenha as referências legíveis e as peças polarizadas marcadas.
- Use definições completas de footprint incorporadas:
-
Roteie a conectividade.
segmentpara trilhas,viapara mudanças de camada,arcpara trilhas curvas. Trilhas KiCad 8/9 usam(uuid ...), não(tstamp ...)(v6/7 ainda usavamtstamp).- Defina
widthpor item a partir da intenção de corrente/pilha; alimentação mais larga que sinais. As classes de net residem no arquivo de projeto/regras de design, não no.kicad_pcb. - Mantenha as trilhas curtas/diretas, prefira curvas de 45°, minimize vias em caminhos de alta velocidade.
- Preserve caminhos de retorno: não roteie trilhas de alta velocidade/sensíveis através de divisões de plano. Aplique espaçamento ~3W para execuções paralelas propensas a diafonia.
- Impedância/diferencial: largura controlada e espaçamento da pilha; pares diferenciais devem ser simétricos e casados em comprimento.
-
Implemente zonas de cobre e planos.
- Zonas de alimentação/terra para planos sólidos. Use ilhas térmicas para pads conectados a planos (conexão térmica).
- Defina prioridade: zona de terra primeiro, depois zonas de alimentação sobrepostas.
- Mantenha o cobre longe das bordas da placa e das margens de non-plating se especificado.
-
Execute verificações estruturais e pré-voo.
python3 scripts/check_pcb.py build/your-board.kicad_pcbpara validação estrutural sem dependências.- Verifique se todos os UUIDs são únicos, todos os ordinais de net existem,
Edge.Cutsestá fechado. - Verifique o dialeto: a versão do cabeçalho corresponde à sintaxe dos itens? (veja
references/pcb-file-format.md#version-dialect-matrix). - Verifique os ordinais da camada:
F.CrtYd/B.CrtYdnão são sequenciais.Edge.Cutsé ordinal 4, etc.
-
Documente suposições e questões pendentes.
- Registre a largura de trilha, afastamento, peso do cobre, acabamento, número de camadas assumidos e qualquer escolha de componente não especificada.
- Se forem necessários componentes personalizados ou não da biblioteca, declare que um footprint de biblioteca real deve ser atribuído.
- Nunca invente um footprint para uma peça real da biblioteca; o pipeline usa
pcbnewpara carregar da biblioteca real.
Verificações de Validação (aplicar a cada placa)
- Estrutural — O arquivo pode ser analisado? Os cabeçalhos estão corretos? Todas as seções necessárias estão presentes? (use
scripts/check_pcb.py) - Integridade de net — Toda referência de net corresponde a uma entrada
(net ...)na tabela? Nenhum ordinal duplicado ou zero para nets não nomeadas? (usescripts/check_pcb.py) - Geometria de placa —
Edge.Cutsestá fechado e dentro da área da placa? O cobre está longe das bordas? (usescripts/check_pcb.py) - DRC (KiCad) — Execute
kicad-cli pcb drcpara executar o verificador de regras de design do KiCad. - DFM (KiCad) — Execute
kicad-cli pcb dfmsinalizará problemas de fabricação. - Paridade de netlist — Compare a netlist da placa com a netlist de origem (esquemático ou especificação). Netlist e placa devem concordar. (use
scripts/pcb_check.py) - Relatório de portão — O pipeline gera
report/design-report.json. A liberação profissional requer que todos os portões rígidos passem e as aprovações necessárias sejam concluídas.
Checklist de Items de Arquivo (antes de finalizar)
- Cabeçalho
versioncorresponde ao dialeto alvo. -
generator_versionestá presente. - A seção
layerstem nomes canônicos e ordinais para a versão alvo. - A seção
setupdefinestackupepaper. -
(general (thickness ...) (legacy_teardrops no))está presente. -
Edge.Cutsé um caminho fechado. - Todos os footprints têm
layer,uuid,at,propertyeattr. - Todos os pads têm
netse conectados. - Trilhas usam sintaxe
uuid(nãotstamp). - As zonas estão definidas e têm prioridade.
- Nenhum token da era v5/v6 permanece.
- O arquivo passa em
check_pcb.py. - O arquivo abre no KiCad.
Guia de Solução de Problemas
| Problema | Causa provável | Solução |
|---|---|---|
| "Falha ao analisar" ao abrir no KiCad | Dialeto misto; item tstamp em cabeçalho v8, ou gráfico width em vez de stroke | Verifique a consistência do dialeto; substitua tstamp por uuid, width por (stroke (width ...)) |
| A placa abre, mas faltam camadas | Ordinal de camada incorreto para a versão (F.CrtYd/B.CrtYd); ou seção layers ausente | Use ordinais corretos; reconstrua a seção layers de minimal-2layer.kicad_pcb |
| Nenhuma trilha é roteada apesar dos nets definidos | Trilha com o net correto que não toca um pad ou outra trilha | Use a rota de pipeta; verifique a extremidade da trilha sobrepõe um pad |
| O relatório de liberação reclama de portão ausente | Uma saída fab necessária não foi gerada ou está vazia | Execute a etapa fab com todas as saídas habilitadas |
| O pipeline não pode encontrar o Java 25 | PATH desatualizado; Java 21 instalado; ou nenhum JRE | Verifique java -version; use --backend ci ou corrija o Java |
| A placa gerada tem nets errados | A especificação não corresponde ao esquemático/netlist; ou os ordinais de net foram alterados | Reimporte a netlist; verifique a paridade; mantenha os ordinais estáveis |
Este fluxo de trabalho é projetado para o pipeline de design automático do KiCad. Use a automação sempre que possível; a autorização manual é apenas para revisão e patches que o pipeline não pode expressar.