Kawalan Versi untuk Perkakasan Sumber Terbuka: 10 Langkah

2024 Pengarang: John Day | [email protected]. Diubah suai terakhir: 2024-01-30 11:10

Pasukan di Brainbow mempunyai sejumlah projek elektronik di bawah tali pinggang kami, dan kami ingin berkongsi proses kami menggunakan kawalan versi untuk menguruskan aliran kerja reka bentuk elektronik kami. Alur kerja ini telah digunakan untuk projek besar dan kecil, dari papan 2 lapisan sederhana hingga raksasa 10 lapisan kompleks, dan berdasarkan pada alat sumber terbuka. Mudah-mudahan, orang lain dapat menggunakan aliran kerja kami untuk diri mereka sendiri, dan memperoleh kelebihan kawalan versi untuk projek mereka sendiri. Tetapi apa faedah yang dapat ditawarkan oleh kawalan versi untuk projek elektronik?

Langkah 1: Mengapa Versi Mengendalikan Elektronik Anda?

Version Control (aka sumber control atau revision control) adalah konsep yang difahami dan diterima pakai secara meluas dalam kejuruteraan perisian. Idea di sebalik kawalan sumber secara sistematik mengesan perubahan yang dibuat pada kod sumber program atau aplikasi. Sekiranya perubahan melanggar aplikasi, anda boleh mengembalikan fail kod sumber ke keadaan kerja yang diketahui dari masa lalu. Dalam praktiknya, sistem kawalan sumber membolehkan anda mengesan sejarah koleksi fail (biasanya fail kod sumber untuk program komputer, laman web, dll), dan memvisualisasikan dan menguruskan perubahan pada fail tersebut.

Menjejaki sejarah perubahan pada projek nampaknya berguna untuk projek elektronik; jika anda membuat kesalahan dalam skema litar, atau menggunakan jejak komponen yang salah dalam susun atur PCB, ada baiknya anda melacak kesalahan yang telah dibuat dan apa yang diperbaiki dalam pelbagai semakan projek. Ia juga berguna bagi pembuat lain untuk melihat sejarah itu, dan memahami konteks dan motivasi dari pelbagai perubahan.

Langkah 2: Alat: KiCad dan Git

Kami menggunakan dua alat utama dalam projek ini: sistem kawalan versi (VCS) dan program automasi reka bentuk elektronik (EDA atau ECAD).

Terdapat banyak sistem kawalan versi di luar sana, tetapi kami menggunakan VCS Git yang diedarkan. Kami menggunakannya untuk beberapa sebab, tetapi kuncinya adalah sumber terbuka (cek!), Mudah digunakan (semak!), Dan VCS standard de-facto untuk perisian sumber terbuka (semak!). Kami akan menggunakan Git sebagai VCS untuk mengesan perubahan pada fail yang digunakan oleh program ECAD kami. Instructable ini tidak memerlukan keakraban dengan Git, tetapi keselesaan umum menggunakan baris perintah diandaikan. Saya akan cuba memaut ke sumber yang bermanfaat untuk penggunaan Git dan baris perintah jika perlu.

Sebilangan besar sistem kawalan sumber berfungsi dengan sangat baik untuk fail berasaskan teks, jadi program ECAD yang menggunakan fail teks akan menjadi bagus. Masukkan KiCad, "Cross Platform dan Open Source Electronics Design Automation Suite" sumber terbuka yang disokong oleh penyelidik di CERN. KiCad juga sumber terbuka (cek!), Mudah digunakan (walaupun ada yang tidak setuju dengan saya mengenai hal itu), dan sangat berkebolehan untuk kerja reka bentuk elektronik canggih.

Langkah 3: Pemasangan

Untuk memasang program ini, ikuti arahan dari pelbagai laman web muat turunnya yang dipautkan di bawah.

• KiCad adalah pelbagai platform (dan sangat memusingkan; halaman muat turun mereka menyenaraikan 13 OS yang disokong, dan menawarkan muat turun kod sumber jika tidak ada yang sesuai dengan anda). Gunakan pemasangan lalai bersatu kicad, bukan pembangunan pembangunan setiap malam. Lihat Langkah 4 untuk perincian pilihan lanjutan mengenai pemasangan perpustakaan.
• Git juga merentas platform. Sekiranya menggunakan Windows, saya akan mengesyorkan projek Git for Windows yang mengagumkan untuk pengalaman yang lebih berguna dan mempunyai ciri yang lengkap.

Dokumentasi pemasangan yang terdapat di kedua-dua laman web ini akan lebih lengkap daripada keterangan yang boleh saya tawarkan di sini. Setelah kedua-dua program dimuat turun dan dipasang, anda boleh mengklon templat projek Brainbow dari repositori Github kami. Perintah git clone mengambil struktur `git clone {src directory} {target directory}`; untuk projek kami, gunakan `git clone https://github.com/builtbybrainbow/kicad-starter.git {direktori sasaran}`.

Kloning git repo adalah bentuk penyalinan khas; apabila anda mengklon projek, anda akan mendapat salinan semua fail yang disertakan dalam repo dan juga keseluruhan sejarah projek yang dilacak oleh Git. Dengan mengklon repo kami, anda mendapatkan direktori projek yang sudah tersusun dengan cadangan kami untuk menggunakan Git dengan KiCad. Kami akan membahas lebih lanjut mengenai struktur projek di Langkah 6, atau anda boleh melangkah ke Langkah 7 jika anda ingin bekerja.

Beberapa tugas pengemasan yang cepat - jalankan `git remote rm origin` untuk membuang pautan ke projek Github yang anda kloning. Juga, jalankan `git commit --amend --author =" John Doe "", ganti parameter pengarang dengan nama dan e-mel anda. Ini mengubah komitmen terakhir (yang dalam hal ini juga merupakan komitmen pertama) dan mengubah pengarang kepada anda, dan bukannya Brainbow.

Langkah 4: Nota Pemasangan: Perpustakaan KiCad

Satu catatan ringkas mengenai struktur perpustakaan KiCad. KiCad menyediakan sekumpulan perpustakaan yang dikendalikan oleh pasukan pemaju untuk pelbagai komponen elektrik. Terdapat tiga perpustakaan utama:

• Simbol Skematik: Simbol yang digunakan untuk mewakili komponen elektronik dalam lukisan skematik litar.
• Jejak Kaki PCB: Lukisan 2D yang mewakili jejak kaki yang sebenarnya (pad tembaga, teks layar sutera, dll) yang akan digunakan ketika meletakkan litar pada PCB.
• Model 3D: Model komponen elektronik 3D.

Perpustakaan ini dimuat turun bersama dengan suite program KiCad yang baru anda pasang. Anda boleh menggunakan KiCad tanpa usaha lagi. Namun, untuk "pengguna kuasa", fail sumber untuk perpustakaan disimpan di git repositori di Github, yang membolehkan pengguna yang ingin mengikuti perkembangan terbaru untuk mengklon repo perpustakaan ke mesin mereka sendiri. Menjejaki perpustakaan dengan git mempunyai sejumlah kelebihan - anda boleh memilih bila anda ingin mengemas kini perpustakaan anda, dan kemas kini hanya perlu memasukkan perubahan pada fail, dan bukannya memuat turun keseluruhan rangkaian fail perpustakaan lagi. Walau bagaimanapun, anda bertanggungjawab untuk mengemas kini perpustakaan, yang mudah dilupakan.

Sekiranya anda ingin mengklon perpustakaan, laman web ini memperincikan pelbagai tawaran Github repositori KiCad. Git klon perpustakaan ke komputer anda (cth: `git clone https:// github.com / KiCad / kicad-simbols.git`), kemudian buka KiCad, pilih bar menu" Preferences "item, dan klik" Configure Paths … ". Ini membolehkan anda memberitahu KiCad jalan direktori untuk mencari setiap perpustakaan. Pemboleh ubah persekitaran ini lalai ke jalan ke perpustakaan yang dipasang dengan pemasangan KiCad; Saya memperhatikan nilai-nilai ini sehingga saya dapat beralih ke perpustakaan lalai jika perlu. Laluan KICAD_SYMBOL_DIR harus menunjuk ke perpustakaan simbol kicad klon anda, KISYSMOD ke perpustakaan jejak kaki kicad yang diklon, dan KISYS3DMOD ke perpustakaan kicad-package3d yang diklon.

Apabila anda ingin mengemas kini perpustakaan, anda boleh menjalankan perintah `git pull` sederhana di repo perpustakaan yang akan memberitahu Git untuk memeriksa perbezaan antara salinan repo perpustakaan tempatan anda dan repo" remote "Github, dan secara automatik mengemas kini salinan tempatan untuk memasukkan perubahan.

Langkah 5: Asas Git

Git adalah program yang kompleks dan pelbagai aspek, dengan keseluruhan buku yang dikhaskan untuk menguasainya. Walau bagaimanapun, terdapat beberapa konsep mudah yang akan membantu anda memahami bagaimana kami menggunakan Git dalam aliran kerja kami.

Git mengesan perubahan pada fail menggunakan satu rangkaian peringkat. Perubahan normal berlaku di direktori yang berfungsi. Apabila anda berpuas hati dengan perubahan yang anda buat pada serangkaian fail, anda menambahkan fail yang telah anda ubah ke kawasan pementasan. Setelah anda membuat semua perubahan yang anda rancangkan dan mengumpulkan semua fail yang ingin anda lacak di Git, anda melakukan perubahan tersebut ke repositori. Komitmen pada dasarnya adalah gambar keadaan fail dalam repo pada waktu tertentu. Oleh kerana Git melacak perubahan pada fail dan menyimpan perubahan ini dalam komit, kapan pun Anda dapat mengembalikan projek ke keadaan yang sebelumnya dilakukan.

Terdapat topik yang lebih kompleks, seperti bercabang dan terpencil, tetapi kita tidak perlu menggunakannya untuk mendapatkan faedah kawalan sumber. Yang kami perlukan hanyalah mengesan perubahan pada fail reka bentuk KiCad kami dengan serangkaian komitmen.

Langkah 6: Struktur Projek KiCad

Mari kita perhatikan lebih dekat struktur projek KiCad-Starter yang anda kloning sebelumnya. Ia dibahagikan kepada sebilangan subdirektori untuk memudahkan organisasi:

• Litar: Folder ini mengandungi fail projek KiCad sebenar (skema, PCB, dll). Saya tidak menamakan semula folder ini, tetapi saya menamakan semula semua fail di dalamnya dengan nama projek (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: fail projek KiCad
  • Circuit.sch: fail skematik KiCad.
  • Circuit.kicad_pcb: fail susun atur PCB KiCad.
• Dokumentasi: Folder ini adalah untuk menyimpan dokumentasi mengenai projek. Kami mempunyai rancangan untuk memperbaiki ruang ini di masa depan, tetapi buat masa ini ia mengandungi fail README sederhana. Gunakannya untuk menyimpan nota pada projek yang akan anda ulas di masa hadapan.
• Fabrikasi: Folder ini adalah tempat anda menyimpan fail gerber yang akan digunakan oleh kebanyakan rumah fab untuk pembuatan papan litar anda. Kami juga menggunakannya untuk menyimpan fail BOM dan dokumen lain yang mungkin diperlukan untuk pembuatan dan pemasangan.
• Perpustakaan: Folder ini adalah untuk menyimpan fail perpustakaan khusus projek (kami akan membahasnya lebih banyak lagi dalam beberapa langkah).

Anda mungkin juga melihat beberapa fail lain (terutamanya jika anda `ls -a` direktori). Direktori.git adalah tempat Git melakukan sihir, menyimpan sejarah repositori. Fail.gitignore digunakan untuk memberitahu Git fail mana yang harus diabaikan dan tidak disimpan dalam kawalan sumber. Ini adalah kebanyakan fail sandaran yang dihasilkan oleh KiCad, atau beberapa fail "dihasilkan" yang berbeza, seperti senarai net, yang seharusnya tidak disimpan dalam kawalan sumber kerana dihasilkan dari sumber yang merupakan fail skematik.

Struktur projek ini hanyalah titik permulaan. Anda harus menyesuaikannya agar sesuai dengan keperluan anda, dan menambahkan bahagian yang diperlukan. Dalam beberapa projek, kami memasukkan folder perisian atau folder lampiran, di mana kami menyimpan model untuk lampiran percetakan 3d untuk projek tersebut.

Langkah 7: Menggunakan Git untuk Projek KiCad

Kami akhirnya bersedia untuk melihat bagaimana menggunakan Git untuk mengesan projek anda. Instructable ini tidak bertujuan untuk mengajar anda cara menggunakan KiCad (walaupun saya mungkin akan melakukannya pada masa akan datang jika ada permintaan), jadi kami akan melalui beberapa contoh sepele untuk menunjukkan kepada anda bagaimana aliran kerja berjalan. Seharusnya mudah difahami bagaimana menyesuaikan idea-idea ini dengan projek sebenar.

Buka direktori kicad-starter, kemudian jalankan `git log` untuk memaparkan sejarah komitmen. Harus ada satu komit di sini, inisialisasi repo oleh Brainbow. Menjalankan `status git` akan memberitahu anda status fail di repo anda (tidak dilacak, diubah, dihapus, dipentaskan).

Pada masa ini, anda seharusnya tidak mempunyai perubahan dalam repo anda. Mari buat perubahan. Buka projek KiCad dan tambahkan perintang ke skema, kemudian simpan. Sekarang menjalankan `status git` harus menunjukkan bahawa anda telah mengubahsuai fail skematik, tetapi belum melakukan perubahan tersebut untuk melakukan. Sekiranya anda ingin tahu apa sebenarnya yang dilakukan KiCad semasa anda menambahkan perintang, anda boleh menjalankan perintah diff pada fail `git diff Circuit / Circuit.sch` yang diubah suai. Ini akan menyoroti perubahan antara versi semasa fail dalam direktori berfungsi dan keadaan fail pada komit terakhir.

Sekarang setelah kita membuat perubahan, mari cuba lakukan perubahan tersebut pada sejarah projek kami. Kita perlu memindahkan perubahan dari direktori kerja kita ke kawasan pementasan. Ini sebenarnya tidak memindahkan fail dalam sistem fail, tetapi secara konseptual adalah cara untuk memberi tahu Git bahawa anda telah membuat semua perubahan yang dirancang untuk fail tertentu dan bersedia untuk melakukan perubahan tersebut. Dengan senang hati, Git memberikan beberapa petunjuk ketika anda menjalankan `status git` untuk tindakan seterusnya. Perhatikan pesan `(gunakan" git add … "untuk mengemas kini apa yang akan dilakukan)" di bawah "Perubahan yang tidak dilakukan untuk melakukan:". Git memberitahu anda cara memindahkan perubahan ke kawasan pementasan. Jalankan `git add Circuit / Circuit.sch` untuk membuat perubahan, kemudian` git status` untuk melihat apa yang berlaku. Sekarang kita melihat fail skematik di bawah perubahan yang akan dilakukan. Sekiranya anda belum mahu melakukan perubahan ini, Git dengan senang hati menawarkan tip lain: `(gunakan" git reset HEAD … "untuk berhenti dari pentas)". Kami mahu melakukan perubahan ini, jadi kami menjalankan `git commit-m" Menambah perintang ke skema "". Ini melakukan perubahan dengan mesej yang diberikan. Menjalankan log git akan menunjukkan komitmen ini dalam sejarah komitmen projek.

Beberapa lagi petua mengenai melakukan.

1. Jangan komited dengan setiap penjimatan. Komited apabila anda merasakan bahawa anda telah mencapai titik di mana perubahan anda agak kukuh. Saya komited setelah saya menyelesaikan skema, bukan selepas setiap penambahan komponen. Anda juga tidak terlalu sering berkomitmen, kerana mengingat konteks mengapa anda membuat perubahan yang anda lakukan 3 minggu kemudian sukar. Memikirkan masa untuk membuat komitmen adalah sedikit seni, tetapi anda akan menjadi lebih selesa kerana anda menggunakan Git lebih banyak.
2. Hanya sumber kedai (kebanyakannya). Ini termasuk fail projek, skema, dan susun atur, serta perpustakaan khusus projek. Ini juga boleh merangkumi fail dokumentasi. Berhati-hatilah semasa menyimpan objek yang diturunkan kerana objek tersebut tidak dapat diselaraskan dengan sumber asalnya dengan mudah, dan itu menyebabkan sakit kepala di kemudian hari. Fail BOM dan gerber diselaraskan dengan sangat mudah, jadi lebih baik dielakkan (walaupun panduan yang lebih terperinci dibahas dalam Langkah 9).
3. Mesej komit sangat berguna, tetapi mesej komit yang tersusun tidak ternilai. Artikel yang sangat baik ini memberikan beberapa panduan untuk menulis mesej komit yang jelas, ringkas dan berguna. Melakukannya mungkin memerlukan penggunaan editor teks baris perintah, yang boleh membuat saya rumit untuk pemula (`git komit` tanpa pilihan -m mesej akan membuka penyunting teks). Bagi kebanyakan orang, saya mengesyorkan penyunting Nano. StackOverflow mempunyai penjelasan yang baik untuk menukar editor anda

Langkah 8: Lanjutan: Semantik Versi untuk Elektronik

Untuk jiwa petualang, petua berikut adalah idea lanjutan, yang diperoleh dari pengembangan KiCad selama berjam-jam. Mereka tidak begitu berguna pada projek yang lebih kecil, tetapi ia benar-benar dapat menjimatkan sakit hati anda kerana projek anda bertambah rumit.

Dalam perisian, terdapat konsep Semantic Versioning (semver). Semver mendefinisikan metodologi penamaan umum untuk mengenal pasti pelepasan perisian dengan "nombor versi", mengikuti corak "Major. Minor. Patch". Untuk memetik spesifikasi semver, anda memajukan nombor versi mengikut kategori perubahan berikut.

1. Versi UTAMA apabila anda membuat perubahan API yang tidak serasi,
2. Versi MINOR apabila anda menambahkan fungsi dengan cara yang serasi ke belakang,
3. Versi PATCH apabila anda membuat pembetulan pepijat yang serasi ke belakang.

Kami di Brainbow menggunakan versi semver kami sendiri yang disesuaikan untuk memenuhi keperluan projek perkakasan. Spesifikasi kami mengikuti corak "Major. Minor. Patch" yang sama, walaupun definisi kami mengenai perubahan apa yang berada di bawah kategori mana yang jelas berbeza.

1. Versi UTAMA: digunakan untuk perubahan ketara pada fungsi teras litar (mis. Menukar pemproses dari ATmegaa ke ESP8266).
2. Versi MINOR: digunakan untuk pertukaran komponen yang dapat mempengaruhi operasi litar (mis.: Tukar kilat SPI dengan bahagian yang sesuai dengan pin yang mungkin mempunyai set perintah yang berbeza) atau penambahan beberapa ciri tambahan kecil (mis: tambahan suhu tambahan sensor).
3. Versi PATCH: digunakan untuk perbaikan bug kecil yang tidak akan mengubah operasi litar (cth: penyesuaian layar silks, penyesuaian susun atur jejak kecil, pertukaran komponen sederhana seperti kapasitor 0603 hingga 0805).

Dalam semver perkakasan, nombor versi hanya dikemas kini semasa pembuatan (seperti dalam perisian, nombor versi hanya berubah dengan pelepasan, tidak setiap individu berkomitmen untuk projek). Hasilnya, banyak projek mempunyai bilangan versi rendah. Kami belum mempunyai projek yang menggunakan lebih daripada 4 versi utama.

Selain daripada manfaat konsistensi dan pemahaman yang anda dapat dari beralih ke sistem penamaan yang ditentukan dengan baik, anda juga mendapat faedah dalam keserasian firmware dan kepuasan pelanggan. Firmware boleh ditulis sambil mengambil kira versi papan yang disasarkannya, dan lebih mudah untuk debug mengapa program tertentu tidak berfungsi pada papan tertentu ("betul, firmware 2.4.1 tidak berjalan pada 1.2 papan kerana kita tidak mempunyai…. "). Pelanggan juga mendapat manfaat dari perisian perkakasan kami kerana perkhidmatan pelanggan dan penyelesaian masalah jauh lebih mudah dengan standard yang ditentukan.

Langkah 9: Lanjutan: Menggunakan Perkakasan Semantik Versi

Untuk menggunakan semver perkakasan dalam projek anda sendiri, kami menggunakan fitur Git yang disebut penandaan. Semasa pertama kali membuat papan, itu adalah versi 1.0.0 papan itu. Pastikan bahawa anda telah melakukan semua perubahan dalam projek anda, kemudian jalankan `git tag -a v1.0.0`. Ini akan membuka editor supaya anda dapat menulis mesej anotasi untuk tag ini (sangat mirip dengan pesan komit). Saya sertakan perincian mengenai pembuatan (siapa yang membuat PCB, siapa yang memasang papan), yang boleh menjadi maklumat berguna kemudian.

Tag pelepasan ditambahkan ke sejarah komit dan menunjukkan keadaan fail pada pembuatan 1.0.0. Ini mungkin berguna untuk beberapa semakan kemudian apabila anda perlu merujuk ke titik ini untuk menyelesaikan masalah. Tanpa label pelepasan yang ditentukan, sukar untuk mengetahui komitmen mana yang paling baru pada saat pembuatan. Tag 1.0.0 (dan 1.1, 1.1.1, dll) memungkinkan anda menentukan bahawa fail sumber khusus ini adalah fail yang digunakan dalam proses pembuatan tertentu.

Nota mengenai Gerbers. Beberapa rumah fab memerlukan fail gerber untuk membuat papan anda, dan anda boleh membuatnya dengan KiCad. Ini adalah objek yang diturunkan, dihasilkan dari file.kicad_pcb sumber, dan biasanya kami tidak mengawal versi fail yang diturunkan. Kami di Brainbow tidak menyimpan gerbers dalam kawalan versi KECUALI ketika kami menandai pelepasan. Apabila kita siap untuk membuat, kita menghasilkan fail gerber, menyimpannya di folder Fabrikasi, dan komit dan tag. Kemudian kami membuang gerbers dan melakukan penghapusan. Ini mungkin kelihatan agak membingungkan pada awalnya, tetapi memastikan bahawa perkara biasa hanya menyimpan fail sumber, dan pelepasan yang ditandai juga menyimpan fail yang tepat digunakan untuk pembuatan papan. Ini terbukti berguna dalam mengesan kesalahan pembuatan beberapa minggu kemudian.

Langkah 10: Langkah Seterusnya

Semoga pengenalan ini cukup mengajar anda untuk mula menggunakan kawalan versi pada projek elektronik anda sendiri. Kami tidak menemui beberapa topik yang lebih maju, seperti kawalan versi untuk perpustakaan yang dikongsi antara projek atau cabang ciri. Namun, kawalan versi adalah seperti memakan sayur-sayuran anda: anda mungkin tidak mendapat apa yang anda fikirkan sepatutnya, tetapi setiap yang anda lakukan dapat mengira.

Brainbow sedang mengusahakan panduan yang lebih terperinci untuk beberapa ciri alur kerja kami yang lebih maju. Kami berharap dapat menerbitkannya dalam beberapa bulan akan datang. Ikuti kami di Instructables, dan kami pasti akan memberitahu anda bila anda boleh membacanya.

Terima kasih kerana membaca, dan kami tidak sabar untuk melihat apa yang anda buat!