Diseño de PCB (KiCad 8/9)

¿Qué hace 9)?

Cree archivos de PCB de KiCad sintácticamente válidos y fabricables, y expórtelos como archivos s-expression .kicad_pcb. KiCad es el marco principal. No confíe en la memoria para el formato del archivo: utilice la documentación para desarrolladores de KiCad y los recursos limpios del validador como fuente de verdad.

Dialecto objetivo: KiCad 9 ((version 20241229)). KiCad 8 (20240108) es compatible con las diferencias enumeradas en references/pcb-file-format.md#version-dialect-matrix — destacando los ordinales de capa, que cambiaron nuevamente en la versión 9. Nunca mezcle dialectos: los (tstamp ...) de la era v6/v7 o los gráficos (width ...) de v6 dentro de un encabezado v8/v9 son la causa más común de archivos que no se cargan.

Innegociables

1. Un dialecto por archivo. El encabezado version, generator_version, los UUID de pistas, la sintaxis de trazo y los campos de las huellas deben coincidir con la versión declarada.
2. Una placa es un archivo completo, no un fragmento. Debe abrirse en KiCad y pasar el verificador estructural a continuación.
3. La conectividad es geométrica. Una pista con el número de red correcto que no toca una almohadilla o otra pista sigue sin estar enrutada.
4. Sin conjeturas eléctricas silenciosas. La asignación pin-red, la polaridad, la elección de la huella y el espaciado de seguridad deben indicarse como suposiciones o preguntarse.
5. No afirme cumplimiento de fabricación sin límites de fábrica verificados. Las cifras de fabricación dependen de la pila de capas y del proveedor.
6. Ninguna afirmación de lanzamiento sin un informe aprobado. Una placa está lista para su lanzamiento solo cuando report/design-report.json indica professional_claim: true. De lo contrario, enumere las compuertas fallidas y las aprobaciones faltantes.

Pipeline de Diseño Automático (preferido para placas nuevas)

No redacte manualmente una placa de lanzamiento cuando este pipeline pueda hacerlo. El pipeline convierte una especificación de diseño en una placa con huellas reales de la biblioteca de KiCad, la enruta con Freerouting, ejecuta DRC de KiCad + DFM + paridad de netlist, exporta Gerbers/perforaciones/posición/STEP/IPC-D-356 y escribe un informe de compuertas. Cada salida listada en profile.fab_outputs es una compuerta estricta. Use la redacción manual solo para revisar o parchear una placa generada.

# 1. Validar intención (no necesita KiCad)
python3 scripts/design_spec.py validate specs/led-blinky.json

# 2. Diseño automático completo. Selecciona automáticamente local cuando están presentes pcbnew de KiCad 9, Java 25
#    y Freerouting 2.5.0; de lo contrario, envía a GitHub Actions.
python3 scripts/design_pipeline.py all specs/led-blinky.json

# La fuente de verdad eléctrica es un esquemático o netlist; la especificación proporciona mecánica/reglas.
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: enrutar/comprobar/exportar sin reconstruir.
python3 scripts/design_pipeline.py all specs/led-blinky.json --board existing.kicad_pcb --skip-build

# Solo 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/<nombre>.json es la fuente de verdad para la ruta automática. Utilice schemas/design-spec.schema.json y specs/led-blinky.json como modelo. Para una solicitud en lenguaje natural, escriba primero la especificación, indique las suposiciones en assumptions[] y luego ejecute el pipeline. Para un esquemático/netlist de KiCad, el netlist es la autoridad para los componentes/redes de almohadillas; la superposición de especificaciones proporciona el tamaño de la placa, la pila de capas, las reglas, la colocación y el enrutamiento.

Perfiles de clase de placa. El perfil selecciona el conjunto de reglas y las compuertas de lanzamiento:

Perfil	Automatización	Aprobación humana requerida
2layer-low-speed	Completa: construir, colocar, enrutar, DRC, DFM, fab	ninguna
4layer-impedance / 6layer-impedance	Restringida: pila de capas + impedancia + comprobaciones de igualdad de longitud	stackup, impedance
rf-mixed-signal	Asistida; las redes de RF deben ser re-enrutadas a mano	rf, emc, thermal
flex-rigid	Asistida	mechanical, flex_bend, assembly
high-voltage	Restringida; comprobaciones de aislamiento/distancia de fuga	safety, creepage

professional_claim es verdadero solo cuando cada compuerta estricta pasa y cada aprobación requerida está listada en signoff.completed. RF, EMC, térmico, seguridad y fatiga de flexión no pueden ser certificados por el pipeline; dígalo en lugar de reclamar en exceso. Registre un revisor en signoff.reviewer.

Selección de backend: local o CI (automática). La automatización completa necesita pcbnew (Python de KiCad 9), kicad-cli, Java 25 y freerouting-2.5.0.jar (Freerouting 2.5.0 está construido para Java 25). --backend auto es el valor predeterminado: sondea el entorno actual y se ejecuta localmente cuando cada etapa solicitada tiene sus herramientas; de lo contrario, envía .github/workflows/design.yml. Ese flujo de trabajo se ejecuta en el contenedor oficial kicad/kicad:9.0, instala JRE 25, descarga Freerouting, ejecuta todo el pipeline y sube design-output + design-report.

Entorno	Resultado de la sonda	Backend seleccionado
PC real con KiCad 9 + Java 25 + jar	todas las etapas listas	local
Termux / contenedor sin KiCad; gh autenticado; repositorio limpio empujado	falta pcbnew/kicad-cli	CI
Sin herramientas locales y sin CI utilizable	faltante	local, falla con la lista de herramientas faltantes

python3 scripts/env_probe.py                        # ¿qué puede ejecutar esta máquina?
python3 scripts/env_probe.py --json                 # sonda legible 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

El envío de CI es conservador: rechaza un árbol sucio o una rama por delante de su upstream, porque Actions verifica la revisión enviada y, de lo contrario, diseñaría la placa incorrecta. Primero confirme y empuje la especificación, los perfiles, los esquemas, los scripts y el flujo de trabajo. gh debe estar instalado y autenticado (pkg install gh, luego gh auth login). Use --ci-repo propietario/nombre solo cuando envíe a un repositorio diferente al actual. Las ejecuciones de CI se observan de forma predeterminada para que el código de salida refleje professional_claim; agregue --no-ci-watch para regresar inmediatamente después del envío.

Los comandos de etapa (build, route, check, fab) se ejecutan localmente porque CI no puede ver archivos de etapa no confirmados; use all --backend ci para una ejecución de CI de extremo a extremo. Dentro de GitHub Actions, el pipeline siempre permanece local, por lo que una ejecución de CI nunca se reenvía a sí misma.

Regla de iteración. Cuando falla una compuerta, cambie la especificación (colocación, ancho, espacio libre, pila de capas, asignación de clase) y regenere. No edite una placa generada y luego afirme que el informe se aplica; el informe registra la especificación exacta resuelta (<nombre>.spec.json).

Fuentes de Recuperación (use antes de adivinar)

Recurso	URL	Uso para
Introducción a S-Expression (sintaxis común)	https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html	Sintaxis, comillas, coordenadas, capas, huellas, almohadillas, gráficos, zonas, grupos
Formato de archivo de placa	https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/index.html	Secciones de nivel superior de .kicad_pcb, encabezado, capas, configuración, redes, pistas, zonas
Formato de biblioteca de huellas	https://dev-docs.kicad.org/en/file-formats/sexpr-footprint/index.html	Contexto de .kicad_mod y campos de huella
Índice de formatos de archivo de KiCad	https://dev-docs.kicad.org/en/file-formats/index.html	Formatos de esquemático/símbolo cuando se necesita un esquemático coincidente
Documentación de DRC de KiCad	https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#design-rule-checking	Qué verifica el DRC real y qué reglas son configurables
Reglas de diseño personalizadas de KiCad	https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#custom-design-rules	Sintaxis de .kicad_dru y expresiones de reglas
Capacidades de JLCPCB	https://jlcpcb.com/capabilities/pcb-capabilities	Límites actuales de fábrica (verificar antes de usar)
IPC-2221 / IPC-2152	https://www.ipc.org/	Fundamentos de ancho de pista/corriente, espacio libre y distancia de fuga

Los documentos de desarrollo van a la zaga de la aplicación en algunos lugares (todavía describen gráficos (width ...) anteriores a v7 y pistas (tstamp ...)). Cuando los documentos y un archivo real de la versión objetivo de KiCad no estén de acuerdo, siga el archivo real y anote la discrepancia.

Referencias y Recursos Locales

Ruta	Contenidos
references/pcb-file-format.md	Matriz de versiones, secciones, ordinales de capa, configuración/pila de capas, huellas, almohadillas, pistas, zonas, lista de verificación
references/sexpr-primitives.md	Sintaxis de tokens, comillas, trazos, efectos, UUID, primitivas de almohadilla/gráfico/zona, tokens sensibles a la versión
references/practical-rules.md	Pila de capas, colocación, enrutamiento, corriente/ancho, SI/PI/EMI, impedancia, térmico, mecánico, DFM/DFA, valores predeterminados
assets/minimal-2layer.kicad_pcb	Placa en blanco de 2 capas limpia del validador (cópiela como punto de partida)
assets/example-led.kicad_pcb	Ejemplo enrutado limpio del validador: conector THT, resistencia/LED SMD, vías, patio, orificio de montaje
assets/example.kicad_dru	Ejemplos de reglas personalizadas (ancho de clase de red, espacio libre de alta tensión)
schemas/design-spec.schema.json	Especificación canónica de diseño automático (placa, reglas, redes, colocación, pila de capas, compuertas)
profiles/*.json	Conjuntos de reglas de clase de placa y compuertas de lanzamiento
specs/led-blinky.json	Especificación de referencia para el pipeline automático
scripts/design_spec.py	Validador de especificaciones sin dependencias, importador de netlist, cálculos de impedancia/corriente, informe de compuertas
scripts/pcb_build.py	Especificación → placa KiCad usando huellas reales de biblioteca (pcbnew)
scripts/pcb_route.py	Exportación DSN → Freerouting → Importación SES → relleno de zona
scripts/pcb_check.py	Compuertas estructurales, DRC, DFM, paridad de netlist y coincidencia de longitud
scripts/pcb_fab.py	Gerbers, perforación, posición, STEP, IPC-D-356 y README de fabricación
scripts/design_pipeline.py	Orquesta todo el diseño automático y escribe el informe de lanzamiento; --backend auto selecciona local o CI
scripts/env_probe.py	Detecta pcbnew, kicad-cli, Java 25, Freerouting, gh/git y recomienda local vs CI
scripts/ci_dispatch.py	Envía .github/workflows/design.yml, opcionalmente observa y descarga artefactos
scripts/check_pcb.py	Verificador estructural/geométrico preliminar sin dependencias
.github/workflows/design.yml	CI: construir, enrutar, DRC/DFM, exportación fab e informe en el contenedor de KiCad 9

Use los términos de búsqueda en estas referencias antes de obtener una página de documento completa: 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.

Flujo de Trabajo Manual / de Revisión

Utilice primero el pipeline automático. Este flujo de trabajo es para revisar una placa generada, parchear un diseño cuya especificación no puede expresar una restricción, o trabajar en un entorno donde las herramientas del pipeline no están disponibles.

1. Aclare la intención de diseño (no adivine en silencio sobre restricciones críticas).

   • Función de la placa, componentes, conectores, redes de alimentación/tierra, tamaño objetivo y restricciones mecánicas.
   • Suposiciones de fabricación: número de capas (predeterminado 2), unidades (mm), peso del cobre, pila de capas, acabado superficial, proceso de ensamblaje.
   • Versión objetivo de KiCad. Por defecto, KiCad 9 a menos que el usuario indique lo contrario.
   • Si los requisitos están poco especificados, indique las suposiciones explícitamente en la respuesta y codifique valores predeterminados razonables en el archivo.

2. Modele primero la lista de conexiones eléctrica (netlist).

   • Defina (net 0 "") más cada red nombrada antes de que los elementos las referencien. Mantenga los ordinales estables y únicos.
   • Asegúrese de que exista el ordinal net de cada almohadilla, pista, vía y zona; asegúrese de que los nombres de red (net N "NOMBRE") de las almohadillas coincidan exactamente con la tabla de redes.
   • Si existe un esquemático coincidente, las huellas necesitan enlaces path/referencia; un diseño solo de placa debe marcarse como board_only cuando corresponda.

3. Defina la mecánica, las capas y la pila de capas.

   • Comience desde assets/minimal-2layer.kicad_pcb y mantenga su encabezado/capas/configuración válidos.
   • Establezca la sección layers con nombres canónicos y los ordinales correctos (consulte la tabla en references/pcb-file-format.md; B.CrtYd/F.CrtYd no son secuenciales).
   • Establezca (general (thickness 1.6) (legacy_teardrops no)), (paper "A4") y una stackup realista si la pila de capas es importante.
   • Proporcione un límite Edge.Cuts cerrado (líneas/arcos o un rectángulo/círculo/polígono). Mantenga el cobre alejado del borde.

4. Coloque las huellas.

   • Use definiciones de huella incrustadas completas: layer, uuid, at, campos property (Reference/Value), attr smd|through_hole, almohadillas, serigrafía, patio F.CrtYd/B.CrtYd, y opcionalmente F.Fab y un modelo 3D.
   • Coloque por función: conectores, entrada de alimentación y MCU primero; agrupe circuitos relacionados; separe dominios analógicos/digitales/ruidosos.
   • Coloque condensadores de desacoplo en cada pin de alimentación/tierra del CI con un área de bucle mínima; valores/paquetes según la hoja de datos o suposiciones indicadas.
   • Respete el espacio del patio y de ensamblaje; mantenga las referencias legibles y las piezas polarizadas marcadas.

5. Enrute la conectividad.

   • segment para pistas, via para cambios de capa, arc para pistas curvas. Las pistas de KiCad 8/9 usan (uuid ...), no (tstamp ...) (v6/7 todavía usaban tstamp).
   • Establezca width por elemento según la intención de corriente/pila de capas; alimentación más ancha que señales. Las clases de red residen en el archivo de proyecto/reglas de diseño, no en .kicad_pcb.
   • Mantenga las pistas cortas/directas, prefiera curvas de 45°, minimice las vías en rutas de alta velocidad.
   • Preserve las rutas de retorno: no enrute trazas de alta velocidad/sensibles a través de divisiones de planos. Aplique espaciado ~3W para ejecuciones paralelas propensas a diafonía.
   • Impedancia/diferen...

[truncado para traducción]