Controle de versão para hardware de código aberto: 10 etapas

2024 Autor: John Day | [email protected]. Última modificação: 2024-01-30 11:38

A equipe da Brainbow tem uma série de projetos eletrônicos sob nossos cintos e queríamos compartilhar nosso processo de uso do controle de versão para gerenciar nosso fluxo de trabalho de design eletrônico. Este fluxo de trabalho tem sido usado para projetos grandes e pequenos, de simples placas de 2 camadas a complexos gigantes de 10 camadas, e é baseado em ferramentas de código aberto. Esperançosamente, outras pessoas podem adotar nosso fluxo de trabalho para si mesmas e obter os benefícios do controle de versão para seus próprios projetos. Mas quais benefícios o controle de versão pode oferecer a um projeto eletrônico?

Etapa 1: Por que controlar a versão de seus eletrônicos?

Controle de versão (também conhecido como controle de origem ou controle de revisão) é um conceito bem compreendido e amplamente adotado na engenharia de software. A ideia por trás do controle de origem é rastrear sistematicamente as alterações feitas no código-fonte de um programa ou aplicativo. Se as alterações interromperem o aplicativo, você pode reverter os arquivos de código-fonte para um estado de funcionamento conhecido do passado. Na prática, os sistemas de controle de origem permitem que você acompanhe o histórico de uma coleção de arquivos (geralmente os arquivos de código-fonte de um programa de computador, site da Web, etc.) e visualize e gerencie as alterações nesses arquivos.

Rastrear o histórico de alterações em um projeto parece útil para projetos eletrônicos; se você cometer um erro no esquema do circuito ou usar a pegada de componente incorreta no layout do PCB, seria bom manter o controle de quais erros foram cometidos e quais correções foram implementadas em várias revisões de um projeto. Também seria útil para outros fabricantes ver essa história e entender o contexto e as motivações de várias mudanças.

Etapa 2: as ferramentas: KiCad e Git

Utilizamos duas ferramentas principais neste projeto: o sistema de controle de versão (VCS) e o programa de automação de projetos eletrônicos (EDA ou ECAD).

Existem MUITOS sistemas de controle de versão por aí, mas usamos o VCS Git distribuído. Nós o usamos por vários motivos, mas o principal é que ele é de código aberto (verifique!), Fácil de usar (verifique!) E o VCS padrão de fato para software de código aberto (verifique!). Estaremos usando o Git como o VCS para rastrear as mudanças nos arquivos que nosso programa ECAD usa. Este Instructable não requer familiaridade com Git, mas o conforto geral usando a linha de comando é assumido. Tentarei criar um link para recursos úteis para o uso do Git e da linha de comando, conforme necessário.

A maioria dos sistemas de controle de origem funciona particularmente bem para arquivos baseados em texto, então um programa ECAD que usa arquivos de texto seria ótimo. Entra em cena o KiCad, o "Cross Platform e Open Source Electronics Design Automation Suite" apoiado por pesquisadores do CERN. KiCad também é de código aberto (confira!), Fácil de usar (embora alguns discordem de mim quanto a isso) e altamente capaz para trabalhos avançados de design eletrônico.

Etapa 3: Instalação

Para instalar esses programas, siga as instruções de seus vários sites de download com links abaixo.

• KiCad é multiplataforma (e estonteante; sua página de download lista 13 sistemas operacionais suportados e oferece um download do código-fonte se nenhum deles for adequado para você). Use a instalação padrão unificada por kicad, não a compilação de desenvolvimento noturna. Consulte a Etapa 4 para obter detalhes opcionais avançados sobre a instalação da biblioteca.
• Git também é multiplataforma. Se estiver usando o Windows, eu recomendaria o impressionante projeto Git para Windows para uma experiência mais útil e completa.

A documentação de instalação disponível em ambos os sites será mais completa do que qualquer descrição que posso oferecer aqui. Depois que os dois programas forem baixados e instalados, você pode clonar o modelo de projeto do Brainbow de nosso repositório Github. O comando git clone assume a estrutura `git clone {diretório src} {diretório de destino}`; para nosso projeto, use `git clone https://github.com/builtbybrainbow/kicad-starter.git {diretório de destino}`.

A clonagem de um repositório git é uma forma especial de cópia; ao clonar um projeto, você obtém uma cópia de todos os arquivos incluídos no repo, bem como todo o histórico do projeto rastreado pelo Git. Ao clonar nosso repo, você obtém um diretório de projeto já estruturado com nossas recomendações para usar Git com KiCad. Cobriremos mais sobre a estrutura do projeto na Etapa 6 ou você pode pular para a Etapa 7 se estiver ansioso para começar a trabalhar.

Algumas tarefas de manutenção rápidas - execute `git remote rm origin` para remover o link para o projeto Github do qual você clonou. Além disso, execute `git commit --amend --author =" John Doe "`, substituindo o parâmetro author por seu nome e e-mail. Isso corrige o último commit (que neste caso também é o primeiro commit) e muda o autor para você, em vez de Brainbow.

Etapa 4: Nota de instalação: Bibliotecas KiCad

Uma nota rápida sobre a estrutura da biblioteca do KiCad. KiCad fornece um conjunto de bibliotecas mantidas pela equipe de desenvolvedores para uma ampla gama de componentes elétricos. Existem três bibliotecas principais:

• Símbolos esquemáticos: Símbolos usados para representar componentes eletrônicos em um desenho esquemático de circuito.
• Pegadas de PCB: desenhos 2D que representam a pegada real (almofadas de cobre, texto serigrafado, etc.) a serem usados no layout do circuito em um PCB.
• Modelos 3D: modelos 3D de componentes eletrônicos.

Essas bibliotecas são baixadas junto com o pacote de programas KiCad que você acabou de instalar. Você pode usar o KiCad sem mais esforço. No entanto, para "usuários avançados", os arquivos de origem das bibliotecas são armazenados em um repositório git no Github, permitindo que os usuários que desejam se manter atualizados com as últimas mudanças clonem o repositório da biblioteca em sua própria máquina. Rastrear as bibliotecas com git tem uma série de vantagens - você pode escolher quando deseja atualizar suas bibliotecas, e as atualizações só precisam incorporar alterações aos arquivos, ao invés de baixar todo o conjunto de arquivos de biblioteca novamente. No entanto, você é responsável por atualizar as bibliotecas, o que pode ser fácil de esquecer.

Se você gostaria de clonar as bibliotecas, este site detalha as várias ofertas de repositórios do Github KiCad. Git clone as bibliotecas para o seu computador (ex: `git clone https:// github.com / KiCad / kicad-symbols.git`), abra o KiCad, selecione o item" Preferências "da barra de menu e clique em" Configurar caminhos … " Isso permite que você diga ao KiCad o caminho do diretório para procurar cada biblioteca. Essas variáveis de ambiente são padronizadas para o caminho para as bibliotecas instaladas com a instalação do KiCad; Anotei esses valores para que pudesse voltar para as bibliotecas padrão, se necessário. O caminho KICAD_SYMBOL_DIR deve apontar para sua biblioteca clonada de símbolos kicad, KISYSMOD para a biblioteca clonada de pegadas kicad e KISYS3DMOD para a biblioteca clonada kicad-packages3d.

Quando você quiser atualizar as bibliotecas, você pode executar um comando `git pull` simples no repositório da biblioteca que dirá ao Git para verificar as diferenças entre a sua cópia local do repositório da biblioteca e o repositório" remoto "do Github, e atualizar automaticamente o seu cópia local para incorporar mudanças.

Etapa 5: fundamentos do Git

Git é um programa complexo e multifacetado, com livros inteiros dedicados a dominá-lo. No entanto, existem alguns conceitos simples que o ajudarão a entender como estamos usando o Git em nosso fluxo de trabalho.

Git rastreia alterações em arquivos usando uma série de estágios. As mudanças normais ocorrem no diretório de trabalho. Quando estiver satisfeito com as alterações feitas em uma série de arquivos, você adiciona os arquivos alterados à área de teste. Uma vez que você fez todas as mudanças que você planeja e testou todos os arquivos que você gostaria de rastrear no Git, você envia essas mudanças para o repositório. Os commits são essencialmente instantâneos do estado dos arquivos em um repo em um momento específico. Como o Git rastreia as mudanças em arquivos e armazena essas mudanças em commits, a qualquer momento você pode reverter um projeto ao estado em que estava em qualquer commit anterior.

Existem tópicos mais complexos, como ramificação e controles remotos, mas não precisamos usá-los para obter os benefícios do controle de origem. Tudo o que precisamos é rastrear as alterações em nossos arquivos de design KiCad com uma série de commits.

Etapa 6: Estrutura do Projeto KiCad

Vamos dar uma olhada mais de perto na estrutura do projeto KiCad-Starter que você clonou anteriormente. É dividido em vários subdiretórios para facilitar a organização:

• Circuito: Esta pasta contém os arquivos de projeto KiCad reais (esquemático, PCB, etc). Não renomeio esta pasta, mas renomeio todos os arquivos dentro com o nome do projeto (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: o arquivo de projeto KiCad
  • Circuit.sch: o arquivo esquemático KiCad.
  • Circuit.kicad_pcb: o arquivo de layout KiCad PCB.
• Documentação: Esta pasta é para armazenar a documentação referente ao projeto. Temos planos para melhorar este espaço no futuro, mas por enquanto ele contém um arquivo README simples. Use-o para armazenar notas sobre o projeto para revisão futura.
• Fabricação: Esta pasta é onde você armazenará os arquivos gerber que a maioria das fab houses usará para fabricar sua placa de circuito. Também o usamos para armazenar arquivos de BOM e outros documentos que podem ser necessários para fabricação e montagem.
• Bibliotecas: esta pasta é para armazenar arquivos de biblioteca específicos do projeto (abordaremos mais isso em algumas etapas).

Você também deve ter notado alguns outros arquivos (particularmente se você `ls -a` o diretório). O diretório.git é onde o Git faz sua mágica, armazenando o histórico do repositório. O arquivo.gitignore é usado para informar ao Git quais arquivos ele deve ignorar e não armazenar no controle de origem. Estes são principalmente arquivos de backup que o KiCad gera, ou alguns arquivos "gerados" diferentes, como netlists, que não devem ser armazenados no controle de origem porque são gerados a partir da origem que é o arquivo esquemático.

Esta estrutura de projeto é apenas um ponto de partida. Você deve adaptá-lo para atender às suas necessidades e adicionar seções conforme necessário. Em alguns projetos, incluímos uma pasta de software ou pasta de gabinete, onde armazenamos modelos de gabinetes de impressão 3D para o projeto.

Etapa 7: Usando Git para projetos KiCad

Finalmente estamos prontos para ver como usar o Git para monitorar seus projetos. Este Instructable não pretende ensiná-lo a usar o KiCad (embora eu possa fazer um no futuro se houver demanda para ele), portanto, examinaremos alguns exemplos triviais para mostrar como o fluxo de trabalho funciona. Deve ser fácil entender como adaptar essas idéias a um projeto real.

Abra o diretório kicad-starter e execute `git log` para exibir o histórico de commits. Deve haver um commit aqui, a inicialização do repo pelo Brainbow. A execução de `git status` informará o status dos arquivos em seu repo (não rastreado, modificado, excluído, testado).

No momento, você não deve ter alterações em seu repo. Vamos fazer uma mudança. Abra o projeto KiCad e adicione um resistor ao esquema e salve. Agora, rodar `git status` deve mostrar que você modificou o arquivo esquemático, mas ainda não testou essas mudanças para o commit. Se você está curioso sobre o que exatamente o KiCad fez quando você adicionou o resistor, você pode executar o comando diff no arquivo modificado `git diff Circuit / Circuit.sch`. Isso irá destacar as mudanças entre a versão atual do arquivo no diretório de trabalho e o estado do arquivo no último commit.

Agora que fizemos uma mudança, vamos tentar enviar essa mudança para o histórico do nosso projeto. Precisamos mover as alterações de nosso diretório de trabalho para a área de teste. Na verdade, isso não move os arquivos no sistema de arquivos, mas é conceitualmente uma maneira de informar ao Git que você fez todas as alterações planejadas para um arquivo específico e está pronto para enviar essas alterações. Felizmente, o Git fornece algumas dicas quando você executa `git status` para a próxima ação. Observe a mensagem `(use" git add… "para atualizar o que será confirmado)` em `Alterações não preparadas para confirmação:`. O Git está dizendo a você como mover as mudanças para a área de teste. Execute `git add Circuit / Circuit.sch` para preparar as mudanças, então` git status` para ver o que aconteceu. Agora vemos o arquivo esquemático sob as alterações a serem confirmadas. Se você não deseja submeter essas mudanças ainda, Git oferece outra dica: `(use" git reset HEAD… "para descompactar)`. Queremos confirmar essas mudanças, então rodamos `git commit -m" Added resistor to schematic "`. Isso confirma as alterações com a mensagem fornecida. Executar git log mostrará este commit no histórico de commits do projeto.

Mais algumas dicas sobre commits.

1. Não se comprometa com cada salvamento. Comprometa-se quando sentir que atingiu um ponto em que suas mudanças se solidificaram. Eu me comprometo depois de terminar um esquema, não depois de cada adição de componente. Você também não quer se comprometer com pouca frequência, porque pode ser difícil lembrar o contexto do motivo pelo qual você fez as alterações 3 semanas depois. Descobrir quando comprometer é um pouco complicado, mas você ficará mais confortável à medida que usar mais o Git.
2. Armazenar apenas a fonte (principalmente). Isso inclui o projeto, o esquema e os arquivos de layout, bem como as bibliotecas específicas do projeto. Isso também pode incluir arquivos de documentação. Tenha cuidado ao armazenar objetos derivados porque eles podem ficar fora de sincronia com a fonte original facilmente e isso causa dores de cabeça mais tarde. Os arquivos BOM e gerber são dessincronizados com facilidade, portanto, é melhor evitá-los (embora orientações mais detalhadas sejam abordadas na Etapa 9).
3. Mensagens de confirmação são muito úteis, mas mensagens de confirmação bem estruturadas são inestimáveis. Este excelente artigo fornece algumas diretrizes para escrever mensagens de commit claras, concisas e úteis. Isso pode exigir o uso de um editor de texto de linha de comando, o que pode ser complicado para iniciantes (`git commit` sem a opção -m mensagem abrirá um editor de texto). Para a maioria das pessoas, eu recomendo o editor Nano. StackOverflow tem uma boa explicação sobre como mudar seu editor

Etapa 8: avançado: controle de versão semântica para eletrônicos

Para as almas aventureiras, as dicas a seguir são ideias avançadas, colhidas em muitas horas de desenvolvimento do KiCad. Eles não são particularmente úteis em projetos menores, mas podem realmente poupar seu coração à medida que seus projetos crescem em complexidade.

Em software, existe um conceito de Versão Semântica (semver). Semver define uma metodologia de nomenclatura comum para identificar lançamentos de software por "número de versão", seguindo um padrão de "Major. Minor. Patch". Para citar as especificações de semver, você avança o número da versão de acordo com as seguintes categorias de mudança.

1. Versão PRINCIPAL quando você faz alterações de API incompatíveis,
2. Versão MINOR quando você adiciona funcionalidade de maneira compatível com versões anteriores,
3. Versão PATCH quando você faz correções de bugs compatíveis com versões anteriores.

Nós da Brainbow usamos nossa própria versão do semver adaptada para atender às necessidades de projetos de hardware. Nossa especificação segue o mesmo padrão "Principal. Minor. Patch", embora nossas definições de quais mudanças se enquadram em quais categorias obviamente diferem.

1. Versão MAJOR: usada para mudanças significativas na funcionalidade central do circuito (ex: troca de processador de ATmegaa para ESP8266).
2. Versão MINOR: usado para trocas de componentes que podem afetar a operação do circuito (ex: troca de flash SPI com peça compatível com o pino que pode ter um conjunto de comandos diferente) ou adição de algum recurso adicional menor (ex: sensor de temperatura adicional adicionado).
3. Versão PATCH: usado para pequenas correções de bugs que não mudam a operação do circuito (ex: ajuste de silkscreen, ajuste de layout de rastreamento menor, trocas de componentes simples como capacitor 0603 para 0805).

No hardware semver, o número da versão só é atualizado na fabricação (assim como no software, os números da versão só mudam com os lançamentos, nem todo indivíduo se compromete com um projeto). Como resultado, muitos projetos têm números de versão baixos. Ainda não temos um projeto que use mais de 4 versões principais.

Além dos benefícios em consistência e compreensibilidade que você obtém ao mudar para um sistema de nomenclatura bem definido, você também obtém benefícios em compatibilidade de firmware e satisfação do cliente. O firmware pode ser escrito levando-se em consideração a versão da placa a que se destina, e pode ser mais fácil depurar por que um programa específico não está funcionando em uma placa específica ("certo, o firmware 2.4.1 não funciona no 1.2 placas porque não temos … "). Os clientes também se beneficiaram com nosso hardware semver porque o atendimento ao cliente e a solução de problemas são muito mais fáceis com um padrão definido.

Etapa 9: avançado: usando o controle de versão semântica de hardware

Para usar o hardware semver em seus próprios projetos, utilizamos um recurso do Git chamado tagging. Quando você fabrica uma placa pela primeira vez, essa é a versão 1.0.0 dessa placa. Certifique-se de ter confirmado todas as alterações em seu projeto e, em seguida, execute `git tag -a v1.0.0`. Isso abrirá um editor para que você possa escrever uma mensagem de anotação para esta tag (muito semelhante a uma mensagem de confirmação). Incluo detalhes sobre a fabricação (quem fez o PCB, quem montou a placa), que podem ser informações úteis mais tarde.

A tag de liberação é adicionada ao histórico de commits e indica o estado dos arquivos na fabricação 1.0.0. Isso pode ser particularmente útil várias revisões posteriores, quando você precisar consultar este ponto para solucionar problemas. Sem uma tag de liberação especificada, pode ser difícil descobrir qual commit era o mais recente no momento da fabricação. Uma tag 1.0.0 (e 1.1, 1.1.1, etc) permite que você especifique se esses arquivos de origem específicos são aqueles usados em uma determinada execução de manufatura.

Uma nota sobre Gerbers. Algumas fab houses requerem arquivos gerber para fazer sua placa, e você pode gerá-los com o KiCad. Esses são objetos derivados, gerados a partir do arquivo de origem.kicad_pcb, e normalmente não temos arquivos derivados de controle de versão. Nós da Brainbow não armazenamos gerbers no controle de versão, EXCETO quando marcamos um lançamento. Quando estamos prontos para construir, geramos os arquivos gerber, os armazenamos na pasta Fabrication, e submetemos e marcamos. Em seguida, removemos os gerbers e confirmamos a exclusão. Isso pode parecer um pouco confuso no início, mas garante que os commits normais armazenem apenas os arquivos-fonte, e os lançamentos marcados também armazenam os arquivos exatos usados para fabricar as placas. Isso tem se mostrado extremamente útil para rastrear erros de fabricação semanas depois.

Etapa 10: Próximas etapas

Esperançosamente, esta introdução o ensinou o suficiente para começar a usar o controle de versão em seus próprios projetos eletrônicos. Não chegamos a alguns dos tópicos mais avançados, como controle de versão para bibliotecas compartilhadas entre projetos ou ramos de recursos. Ainda assim, o controle de versão é como comer vegetais: você pode não obter o que acha que deveria, mas cada pedaço obtém contagens.

Brainbow está trabalhando em um guia mais detalhado para alguns dos recursos mais avançados de nosso fluxo de trabalho. Esperamos publicá-lo nos próximos meses. Siga-nos aqui no Instructables e avisaremos quando você puder lê-lo.

Obrigado por ler e mal podemos esperar para ver o que você ganha!