Control de versiones para hardware de código abierto: 10 pasos

2025 Autor: John Day | [email protected]. Última modificación: 2025-01-13 06:57

El equipo de Brainbow tiene varios proyectos de electrónica en nuestro haber, y queríamos compartir nuestro proceso para usar el control de versiones para administrar nuestro flujo de trabajo de diseño de electrónica. Este flujo de trabajo se ha utilizado para proyectos grandes y pequeños, desde tableros simples de 2 capas hasta gigantes complejos de 10 capas, y se basa en herramientas de código abierto. Con suerte, otros pueden adoptar nuestro flujo de trabajo por sí mismos y obtener los beneficios del control de versiones para sus propios proyectos. Pero, ¿qué beneficios puede ofrecer el control de versiones a un proyecto de electrónica?

Paso 1: ¿Por qué controlar la versión de sus dispositivos electrónicos?

El control de versiones (también conocido como control de fuentes o control de revisiones) es un concepto bien entendido y ampliamente adoptado en la ingeniería de software. La idea detrás del control de fuente es rastrear sistemáticamente los cambios realizados en el código fuente de un programa o aplicación. Si los cambios interrumpen la aplicación, puede revertir los archivos de código fuente a un estado de trabajo conocido del pasado. En la práctica, los sistemas de control de fuente le permiten rastrear el historial de una colección de archivos (generalmente los archivos de código fuente de un programa de computadora, sitio web, etc.) y visualizar y administrar los cambios en esos archivos.

El seguimiento del historial de cambios en un proyecto parece útil para los proyectos de electrónica; Si comete un error en el esquema del circuito o utiliza la huella de componente incorrecta en el diseño de la PCB, sería bueno hacer un seguimiento de los errores que se cometieron y las correcciones que se implementaron en varias revisiones de un proyecto. También sería útil para otros creadores ver esa historia y comprender el contexto y las motivaciones de varios cambios.

Paso 2: Las herramientas: KiCad y Git

Usamos dos herramientas principales en este proyecto: el sistema de control de versiones (VCS) y el programa de automatización del diseño de la electrónica (EDA o ECAD).

Hay MUCHOS sistemas de control de versiones, pero usamos el VCS Git distribuido. Lo usamos por varias razones, pero la clave es que es de código abierto (¡verifique!), Fácil de usar (¡verifique!) Y el VCS estándar de facto para software de código abierto (¡verifique!). Usaremos Git como VCS para rastrear los cambios en los archivos que usa nuestro programa ECAD. Este Instructable no requiere familiaridad con Git, pero se asume la comodidad general al usar la línea de comandos. Intentaré vincularme a recursos útiles tanto para Git como para el uso de la línea de comandos, según sea necesario.

La mayoría de los sistemas de control de fuentes funcionan particularmente bien para archivos basados en texto, por lo que un programa ECAD que utilice archivos de texto sería excelente. Ingrese a KiCad, la "Suite de automatización de diseño de electrónica de código abierto y multiplataforma" respaldada por investigadores del CERN. KiCad también es de código abierto (¡compruébalo!), Fácil de usar (aunque algunos no estarían de acuerdo conmigo en eso) y muy capaz para el trabajo de diseño de electrónica avanzada.

Paso 3: instalación

Para instalar estos programas, siga las instrucciones de sus diversos sitios de descarga vinculados a continuación.

• KiCad es multiplataforma (y vertiginosamente; su página de descarga enumera 13 sistemas operativos compatibles y ofrece una descarga de código fuente si ninguno de ellos le conviene). Utilice la instalación predeterminada unificada de kicad, no la compilación de desarrollo nocturno. Consulte el Paso 4 para obtener detalles opcionales avanzados sobre la instalación de la biblioteca.
• Git también es multiplataforma. Si usa Windows, recomendaría el impresionante proyecto Git para Windows para una experiencia más útil y con todas las funciones.

La documentación de instalación disponible en ambos sitios será más completa que cualquier descripción que pueda ofrecer aquí. Una vez que ambos programas se descargan e instalan, puede clonar la plantilla de proyecto de Brainbow desde nuestro repositorio de Github. El comando git clone toma la estructura `git clone {directorio src} {directorio de destino}`; para nuestro proyecto, use `git clone https://github.com/builtbybrainbow/kicad-starter.git {directorio de destino}`.

Clonar un repositorio de git es una forma especial de copia; cuando clona un proyecto, obtiene una copia de todos los archivos incluidos en el repositorio, así como el historial completo del proyecto con seguimiento de Git. Al clonar nuestro repositorio, obtiene un directorio de proyectos ya estructurado con nuestras recomendaciones para usar Git con KiCad. Cubriremos más sobre la estructura del proyecto en el Paso 6, o puede saltar al Paso 7 si está ansioso por comenzar a trabajar.

Algunas tareas de limpieza rápidas: ejecute `git remote rm origin` para eliminar el enlace al proyecto de Github desde el que clonó. Además, ejecute `git commit --amend --author =" John Doe "`, reemplazando el parámetro de autor con su nombre y correo electrónico. Esto enmienda la última confirmación (que en este caso también es la primera confirmación) y le cambia el autor a usted, en lugar de Brainbow.

Paso 4: Nota de instalación: Bibliotecas KiCad

Una nota rápida sobre la estructura de la biblioteca de KiCad. KiCad proporciona un conjunto de bibliotecas mantenidas por el equipo de desarrolladores para una amplia gama de componentes eléctricos. Hay tres bibliotecas principales:

• Símbolos esquemáticos: Símbolos utilizados para representar componentes electrónicos en un dibujo esquemático de circuito.
• Huellas de PCB: dibujos en 2D que representan la huella real (almohadillas de cobre, texto de serigrafía, etc.) que se utilizarán al diseñar el circuito en una PCB.
• Modelos 3D: modelos 3D de componentes electrónicos.

Estas bibliotecas se descargan junto con el paquete de programas KiCad que acaba de instalar. Puede utilizar KiCad sin más esfuerzo. Sin embargo, para los "usuarios avanzados", los archivos de origen de las bibliotecas se almacenan en un repositorio git en Github, lo que permite a los usuarios que desean mantenerse actualizados con los últimos cambios clonar los repositorios de la biblioteca en su propia máquina. El seguimiento de las bibliotecas con git tiene una serie de ventajas: puede elegir cuándo desea actualizar sus bibliotecas, y las actualizaciones solo necesitan incorporar cambios en los archivos, en lugar de descargar todo el conjunto de archivos de la biblioteca nuevamente. Sin embargo, usted es responsable de actualizar las bibliotecas, que puede ser fácil de olvidar.

Si desea clonar las bibliotecas, este sitio detalla los diversos repositorios de Github que ofrece KiCad. Git clone las bibliotecas en su computadora (por ejemplo: `git clone https:// github.com / KiCad / kicad-symbols.git`), luego abra KiCad, seleccione el elemento" Preferencias "de la barra de menú y haga clic en" Configurar rutas … ". Esto le permite decirle a KiCad la ruta del directorio en el que buscar cada biblioteca. Estas variables de entorno toman de forma predeterminada la ruta a las bibliotecas instaladas con la instalación de KiCad; Tomé nota de estos valores para poder volver a las bibliotecas predeterminadas si fuera necesario. La ruta KICAD_SYMBOL_DIR debe apuntar a su biblioteca de símbolos kicad clonada, KISYSMOD a la biblioteca kicad-footprints clonada y KISYS3DMOD a la biblioteca kicad-packages3d clonada.

Cuando desee actualizar las bibliotecas, puede ejecutar un comando simple `git pull` en el repositorio de la biblioteca que le dirá a Git que verifique las diferencias entre su copia local del repositorio de la biblioteca y el repositorio" remoto "de Github, y que actualice automáticamente su copia local para incorporar cambios.

Paso 5: Fundamentos de Git

Git es un programa complejo y multifacético, con libros completos dedicados a dominarlo. Sin embargo, hay algunos conceptos simples que lo ayudarán a comprender cómo usamos Git en nuestro flujo de trabajo.

Git realiza un seguimiento de los cambios en los archivos mediante una serie de etapas. Los cambios normales tienen lugar en el directorio de trabajo. Cuando esté satisfecho con los cambios que ha realizado en una serie de archivos, agregue los archivos que ha cambiado al área de preparación. Una vez que haya realizado todos los cambios que planea y haya preparado todos los archivos que le gustaría rastrear en Git, confirma esos cambios en el repositorio. Las confirmaciones son esencialmente instantáneas del estado de los archivos en un repositorio en un momento específico. Dado que Git rastrea los cambios en los archivos y almacena estos cambios en las confirmaciones, en cualquier momento puede revertir un proyecto al estado en el que estaba en cualquier confirmación anterior.

Hay temas más complejos, como ramificaciones y controles remotos, pero no necesitamos usarlos para obtener los beneficios del control de fuente. Todo lo que necesitamos es realizar un seguimiento de los cambios en nuestros archivos de diseño de KiCad con una serie de confirmaciones.

Paso 6: Estructura del proyecto KiCad

Echemos un vistazo más de cerca a la estructura del proyecto KiCad-Starter que clonó anteriormente. Está dividido en varios subdirectorios para facilitar la organización:

• Circuito: esta carpeta contiene los archivos reales del proyecto KiCad (esquema, PCB, etc.). No cambio el nombre de esta carpeta, pero sí cambio el nombre de todos los archivos dentro con el nombre del proyecto (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: el archivo de proyecto KiCad
  • Circuit.sch: el archivo de esquema de KiCad.
  • Circuit.kicad_pcb: el archivo de diseño de PCB KiCad.
• Documentación: esta carpeta es para almacenar documentación relacionada con el proyecto. Tenemos planes para mejorar este espacio en el futuro, pero por ahora contiene un simple archivo README. Úselo para almacenar notas sobre el proyecto para que las revise en el futuro.
• Fabricación: esta carpeta es donde almacenará los archivos gerber que la mayoría de las casas fabulosas usarán para fabricar su placa de circuito. También lo usamos para almacenar archivos BOM y otros documentos que pueden ser necesarios para la fabricación y el ensamblaje.
• Bibliotecas: esta carpeta es para almacenar archivos de biblioteca específicos del proyecto (cubriremos esto más en unos pocos pasos).

Es posible que también haya notado algunos otros archivos (particularmente si `ls -a` el directorio). El directorio.git es donde Git hace su magia, almacenando el historial del repositorio. El archivo.gitignore se usa para decirle a Git qué archivos debe ignorar y no almacenar en el control de código fuente. Estos son en su mayoría archivos de respaldo que genera KiCad, o algunos archivos "generados" diferentes, como listas de red, que no deben almacenarse en el control de fuente porque se generan a partir de la fuente que es el archivo esquemático.

Esta estructura de proyecto es solo un punto de partida. Debe adaptarlo para que se ajuste a sus necesidades y agregar secciones según sea necesario. En algunos proyectos, hemos incluido una carpeta de software o una carpeta de gabinete, donde almacenamos modelos para gabinetes de impresión 3D para el proyecto.

Paso 7: uso de Git para proyectos KiCad

Finalmente estamos listos para ver cómo usar Git para rastrear sus proyectos. Este Instructable no está destinado a enseñarle cómo usar KiCad (aunque puedo hacer uno en el futuro si hay demanda), por lo que repasaremos algunos ejemplos triviales para mostrarle cómo se ejecuta el flujo de trabajo. Debería ser fácil de entender cómo adaptar estas ideas a un proyecto real.

Abra el directorio kicad-starter, luego ejecute `git log` para mostrar el historial de confirmaciones. Debería haber una confirmación aquí, la inicialización del repositorio por Brainbow. Ejecutar `git status` le dirá el estado de los archivos en su repositorio (sin seguimiento, modificado, eliminado, almacenado).

Por el momento, no debería haber cambios en su repositorio. Hagamos un cambio. Abra el proyecto KiCad y agregue una resistencia al esquema, luego guarde. Ahora la ejecución de `git status` debería mostrar que ha modificado el archivo esquemático, pero aún no ha preparado esos cambios para su confirmación. Si tiene curiosidad acerca de qué hizo exactamente KiCad cuando agregó la resistencia, puede ejecutar el comando diff en el archivo modificado `git diff Circuit / Circuit.sch`. Esto resaltará los cambios entre la versión actual del archivo en el directorio de trabajo y el estado del archivo en la última confirmación.

Ahora que hemos realizado un cambio, intentemos incluir ese cambio en el historial de nuestro proyecto. Necesitamos mover los cambios de nuestro directorio de trabajo al área de preparación. En realidad, esto no mueve los archivos en el sistema de archivos, pero es conceptualmente una forma de hacerle saber a Git que ha realizado todos los cambios planificados para un archivo en particular y que está listo para realizar esos cambios. Afortunadamente, Git proporciona algunas pistas cuando ejecuta `git status` para la siguiente acción. Observe el mensaje `(use" git add … "para actualizar lo que se confirmará)` en `Cambios no preparados para la confirmación:`. Git te está diciendo cómo mover los cambios al área de preparación. Ejecute `git add Circuit / Circuit.sch` para organizar los cambios, luego` git status` para ver qué sucedió. Ahora vemos el archivo de esquema debajo de los cambios que se van a confirmar. Si aún no desea realizar estos cambios, Git le ofrece otro consejo: `(use" git reset HEAD … "para quitar el escenario)`. Queremos confirmar estos cambios, así que ejecutamos `git commit -m" Resistencia agregada al esquema "`. Esto confirma los cambios con el mensaje proporcionado. La ejecución de git log mostrará esta confirmación en el historial de confirmaciones del proyecto.

Algunos consejos más sobre confirmaciones.

1. No se comprometa con cada salvamento. Comprométase cuando sienta que ha llegado a un punto en el que sus cambios se han solidificado un poco. Me comprometo después de terminar un esquema, no después de cada adición de componentes. Tampoco querrá comprometerse con poca frecuencia, porque recordar el contexto de por qué hizo los cambios que hizo 3 semanas después puede ser difícil. Averiguar cuándo comprometerse es un arte, pero te sentirás más cómodo a medida que uses más Git.
2. Solo la fuente de la tienda (en su mayoría). Esto incluye los archivos del proyecto, el esquema y el diseño, así como las bibliotecas específicas del proyecto. Esto también puede incluir archivos de documentación. Tenga cuidado al almacenar objetos derivados porque pueden desincronizarse fácilmente con la fuente original y eso causa dolores de cabeza más adelante. Los archivos BOM y gerber se desincronizan con especial facilidad, por lo que es mejor evitarlos (aunque en el paso 9 se tratan instrucciones más detalladas).
3. Los mensajes de confirmación son muy útiles, pero los mensajes de confirmación bien estructurados son invaluables. Este excelente artículo proporciona algunas pautas para escribir mensajes de confirmación claros, concisos y útiles. Hacerlo puede requerir el uso de un editor de texto de línea de comandos, lo que puede resultar complicado para los principiantes (`git commit` sin la opción -m message abrirá un editor de texto). Para la mayoría de la gente, recomiendo el editor Nano. StackOverflow tiene una buena explicación sobre cómo cambiar su editor

Paso 8: Avanzado: control de versiones semántico para electrónica

Para las almas aventureras, los siguientes consejos son ideas avanzadas, extraídas de muchas horas de desarrollo de KiCad. No son particularmente útiles en proyectos más pequeños, pero realmente pueden ahorrarle dolores de cabeza a medida que sus proyectos crecen en complejidad.

En software, existe un concepto de control de versiones semántico (semver). Semver define una metodología de nomenclatura común para identificar las versiones de software por "número de versión", siguiendo un patrón de "Major. Minor. Patch". Para citar la especificación de semver, avance el número de versión de acuerdo con las siguientes categorías de cambio.

1. Versión PRINCIPAL cuando realiza cambios de API incompatibles,
2. Versión MINOR cuando agrega funcionalidad de una manera compatible con versiones anteriores,
3. PARCHE la versión cuando realiza correcciones de errores compatibles con versiones anteriores.

En Brainbow utilizamos nuestra propia versión de semver adaptada a las necesidades de los proyectos de hardware. Nuestra especificación sigue el mismo patrón "Major. Minor. Patch", aunque nuestras definiciones de qué cambios caen bajo qué categoría obviamente difieren.

1. Versión PRINCIPAL: se utiliza para cambios significativos en la funcionalidad principal del circuito (por ejemplo: procesador de conmutación de ATmegaa a ESP8266).
2. Versión MINOR: se utiliza para cambios de componentes que podrían afectar el funcionamiento del circuito (p. Ej., Cambio de flash SPI con una pieza compatible con pines que puede tener un conjunto de comandos diferente) o la adición de alguna característica adicional menor (p. Ej., Sensor de temperatura adicional agregado).
3. Versión PATCH: se utiliza para correcciones de errores menores que no cambiarán el funcionamiento del circuito (por ejemplo: ajuste de serigrafía, ajuste de trazado de seguimiento menor, cambios de componentes simples como el condensador 0603 a 0805).

En hardware semver, el número de versión solo se actualiza en la fabricación (al igual que en el software, los números de versión solo cambian con las versiones, no todos los individuos se comprometen con un proyecto). Como resultado, muchos proyectos tienen números de versión bajos. Todavía tenemos que tener un proyecto que utilice más de 4 versiones principales.

Además de los beneficios en coherencia y comprensibilidad que obtiene al cambiar a un sistema de nombres bien definido, también obtiene beneficios en compatibilidad de firmware y satisfacción del cliente. El firmware se puede escribir teniendo en cuenta la versión de la placa a la que se dirige, y puede ser más fácil depurar por qué un programa en particular no funciona en una placa en particular ("correcto, el firmware 2.4.1 no se ejecuta en 1.2 tableros porque no tenemos…. "). Los clientes también se han beneficiado de nuestro semver de hardware porque el servicio al cliente y la resolución de problemas es mucho más fácil con un estándar definido.

Paso 9: Avanzado: uso del control de versiones semántico de hardware

Para usar semver de hardware en sus propios proyectos, utilizamos una función de Git llamada etiquetado. Cuando fabrica por primera vez una placa, esa es la versión 1.0.0 de esa placa. Asegúrese de haber confirmado todos los cambios en su proyecto, luego ejecute `git tag -a v1.0.0`. Esto abrirá un editor para que pueda escribir un mensaje de anotación para esta etiqueta (muy similar a un mensaje de confirmación). Incluyo detalles sobre la fabricación (quién hizo la PCB, quién ensambló la placa), que pueden ser información útil más adelante.

La etiqueta de lanzamiento se agrega al historial de confirmaciones e indica el estado de los archivos en la fabricación 1.0.0. Esto puede ser particularmente útil varias revisiones posteriores cuando necesite consultar este punto para solucionar problemas. Sin una etiqueta de lanzamiento específica, podría ser difícil determinar qué compromiso fue el más reciente en el momento de la fabricación. Una etiqueta 1.0.0 (y 1.1, 1.1.1, etc.) le permite especificar que estos archivos fuente específicos fueron los que se usaron en una ejecución de fabricación en particular.

Una nota sobre Gerbers. Algunas casas fabulosas requieren archivos gerber para hacer su tablero, y puede generarlos con KiCad. Estos son objetos derivados, generados a partir del archivo.kicad_pcb de origen, y normalmente no usamos archivos derivados de control de versiones. En Brainbow no almacenamos gerbers en el control de versiones EXCEPTO cuando etiquetamos un lanzamiento. Cuando estamos listos para construir, generamos los archivos gerber, los almacenamos en la carpeta Fabrication y los confirmamos y etiquetamos. Luego eliminamos los gerbers y cometemos la eliminación. Esto puede parecer un poco confuso al principio, pero asegura que las confirmaciones normales solo almacenen archivos fuente, y que las versiones etiquetadas también almacenen los archivos exactos utilizados para fabricar las placas. Esto ha demostrado ser muy útil para rastrear errores de fabricación semanas después.

Paso 10: Pasos siguientes

Con suerte, esta introducción le ha enseñado lo suficiente para comenzar a usar el control de versiones en sus propios proyectos de electrónica. No llegamos a algunos de los temas más avanzados, como el control de versiones para bibliotecas compartidas entre proyectos o ramas de funciones. Aún así, el control de versiones es como comerse las verduras: es posible que no obtenga lo que cree que debería, pero todo lo que obtiene cuenta.

Brainbow está trabajando en una guía más detallada de algunas de las funciones más avanzadas de nuestro flujo de trabajo. Esperamos publicarlo en los próximos meses. Síganos aquí en Instructables y nos aseguraremos de avisarle cuando pueda leerlo.

¡Gracias por leer, y estamos ansiosos por ver lo que haces!