Kontrol Versi untuk Perangkat Keras Sumber Terbuka: 10 Langkah

2024 Pengarang: John Day | [email protected]. Terakhir diubah: 2024-01-30 09:57

Tim di Brainbow memiliki sejumlah proyek elektronik di bawah ikat pinggang kami, dan kami ingin membagikan proses kami menggunakan kontrol versi untuk mengelola alur kerja desain elektronik kami. Alur kerja ini telah digunakan untuk proyek besar dan kecil, dari papan 2 lapis sederhana hingga raksasa 10 lapis yang kompleks, dan didasarkan pada alat sumber terbuka. Mudah-mudahan, orang lain dapat mengadopsi alur kerja kami untuk diri mereka sendiri, dan mendapatkan manfaat dari kontrol versi untuk proyek mereka sendiri. Tetapi manfaat apa yang dapat ditawarkan kontrol versi pada proyek elektronik?

Langkah 1: Mengapa Versi Mengontrol Elektronik Anda?

Kontrol Versi (alias kontrol sumber atau kontrol revisi) adalah konsep yang dipahami dengan baik dan diadopsi secara luas dalam rekayasa perangkat lunak. Ide di balik kontrol sumber secara sistematis melacak perubahan yang dibuat pada kode sumber program atau aplikasi. Jika perubahan merusak aplikasi, Anda dapat mengembalikan file kode sumber ke status kerja yang diketahui dari masa lalu. Dalam praktiknya, sistem kontrol sumber memungkinkan Anda untuk melacak riwayat kumpulan file (biasanya file kode sumber untuk program komputer, situs web, dll), dan memvisualisasikan serta mengelola perubahan pada file tersebut.

Melacak sejarah perubahan proyek tampaknya berguna untuk proyek elektronik; jika Anda membuat kesalahan dalam skema rangkaian, atau menggunakan jejak komponen yang salah dalam tata letak PCB, alangkah baiknya untuk melacak kesalahan apa yang dibuat dan perbaikan apa yang diterapkan dalam berbagai revisi proyek. Ini juga akan berguna bagi pembuat lain untuk melihat sejarah itu, dan memahami konteks dan motivasi dari berbagai perubahan.

Langkah 2: Alat: KiCad dan Git

Kami menggunakan dua alat utama dalam proyek ini: sistem kontrol versi (VCS) dan program otomatisasi desain elektronik (EDA atau ECAD).

Ada BANYAK sistem kontrol versi di luar sana, tetapi kami menggunakan Git VCS terdistribusi. Kami menggunakannya untuk sejumlah alasan, tetapi kuncinya adalah bahwa itu open-source (periksa!), Mudah digunakan (periksa!), dan VCS standar de-facto untuk perangkat lunak open-source (periksa!). Kami akan menggunakan Git sebagai VCS untuk melacak perubahan pada file yang digunakan oleh program ECAD kami. Instruksi ini tidak memerlukan keakraban dengan Git, tetapi kenyamanan umum menggunakan baris perintah diasumsikan. Saya akan mencoba menautkan ke sumber daya yang bermanfaat untuk penggunaan Git dan baris perintah seperlunya.

Sebagian besar sistem kontrol sumber bekerja sangat baik untuk file berbasis teks, jadi program ECAD yang menggunakan file teks akan sangat bagus. Masuklah ke KiCad, "Suite Otomatisasi Desain Elektronik Lintas Platform dan Sumber Terbuka" open-source yang didukung oleh para peneliti di CERN. KiCad juga open-source (periksa!), mudah digunakan (walaupun beberapa orang tidak setuju dengan saya tentang itu), dan sangat mampu untuk pekerjaan desain elektronik tingkat lanjut.

Langkah 3: Instalasi

Untuk menginstal program ini, ikuti petunjuk dari berbagai situs unduhan mereka yang ditautkan di bawah ini.

• KiCad adalah lintas platform (dan sangat memusingkan; halaman unduhan mereka mencantumkan 13 OS yang didukung, dan menawarkan unduhan kode sumber jika tidak ada yang cocok untuk Anda). Gunakan instal default kicad-unified, bukan build pengembangan malam. Lihat Langkah 4 untuk detail opsional lanjutan tentang penginstalan pustaka.
• Git juga lintas platform. Jika menggunakan Windows, saya akan merekomendasikan proyek Git untuk Windows yang mengesankan untuk pengalaman yang lebih berguna dan berfitur lengkap.

Dokumentasi pemasangan yang tersedia di kedua situs ini akan lebih lengkap daripada deskripsi apa pun yang dapat saya tawarkan di sini. Setelah kedua program diunduh dan diinstal, Anda dapat mengkloning templat proyek Brainbow dari repositori Github kami. Perintah git clone mengambil struktur `git clone {src directory} {target directory}`; untuk proyek kami, gunakan `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Mengkloning git repo adalah bentuk penyalinan khusus; ketika Anda mengkloning sebuah proyek, Anda mendapatkan salinan semua file yang termasuk dalam repo serta seluruh riwayat proyek yang dilacak Git. Dengan mengkloning repo kami, Anda mendapatkan direktori proyek yang sudah terstruktur dengan rekomendasi kami untuk menggunakan Git dengan KiCad. Kami akan membahas lebih lanjut tentang struktur proyek di Langkah 6, atau Anda dapat melompat ke Langkah 7 jika Anda ingin segera bekerja.

Beberapa tugas pembersihan cepat - jalankan `git remote rm origin` untuk menghapus tautan ke proyek Github tempat Anda mengkloning. Juga, jalankan `git commit --amend --author="John Doe "`, ganti parameter author dengan nama dan email Anda. Ini mengubah komit terakhir (yang dalam hal ini juga komit pertama) dan mengubah penulis menjadi Anda, bukan Brainbow.

Langkah 4: Catatan Instalasi: Perpustakaan KiCad

Satu catatan singkat tentang struktur perpustakaan KiCad. KiCad menyediakan satu set perpustakaan yang dikelola oleh tim pengembang untuk berbagai macam komponen listrik. Ada tiga perpustakaan utama:

• Simbol Skema: Simbol yang digunakan untuk mewakili komponen elektronik dalam gambar skema rangkaian.
• Jejak Kaki PCB: Gambar 2D yang mewakili jejak sebenarnya (bantalan tembaga, teks silkscreen, dll) yang akan digunakan saat meletakkan sirkuit pada PCB.
• Model 3D: Model 3D komponen elektronik.

Pustaka ini diunduh bersama dengan rangkaian program KiCad yang baru saja Anda instal. Anda dapat menggunakan KiCad tanpa susah payah. Namun, untuk "pengguna kuat", file sumber untuk perpustakaan disimpan dalam repositori git di Github, memungkinkan pengguna yang ingin tetap mengetahui perubahan terbaru untuk mengkloning repo perpustakaan ke mesin mereka sendiri. Melacak perpustakaan dengan git memiliki sejumlah keuntungan - Anda dapat memilih kapan Anda ingin memperbarui perpustakaan Anda, dan pembaruan hanya perlu memasukkan perubahan pada file, daripada mengunduh seluruh kumpulan file perpustakaan lagi. Namun, Anda bertanggung jawab untuk memperbarui perpustakaan, yang dapat dengan mudah dilupakan.

Jika Anda ingin mengkloning perpustakaan, situs ini merinci berbagai repo Github yang ditawarkan KiCad. Git mengkloning perpustakaan ke komputer Anda (mis: `git clone https://github.com/KiCad/kicad-symbols.git`), kemudian buka KiCad, pilih item "Preferences" pada bilah menu, dan klik "Configure Paths… ". Ini memungkinkan Anda memberi tahu KiCad jalur direktori untuk mencari setiap pustaka. Variabel lingkungan ini default ke jalur ke pustaka yang diinstal dengan instalasi KiCad; Saya mencatat nilai-nilai ini sehingga saya dapat beralih kembali ke pustaka default jika perlu. Jalur KICAD_SYMBOL_DIR harus mengarah ke perpustakaan simbol kicad Anda, KISYSMOD ke perpustakaan kicad-footprints yang dikloning, dan KISYS3DMOD ke perpustakaan kicad-packages3d yang dikloning.

Saat Anda ingin memperbarui perpustakaan, Anda dapat menjalankan perintah `git pull` sederhana di repo perpustakaan yang akan memberi tahu Git untuk memeriksa perbedaan antara salinan lokal repo perpustakaan dan repo "jarak jauh" Github, dan secara otomatis memperbarui salinan lokal untuk memasukkan perubahan.

Langkah 5: Dasar-dasar Git

Git adalah program yang kompleks dan memiliki banyak segi, dengan seluruh buku yang ditujukan untuk menguasainya. Namun, ada beberapa konsep sederhana yang akan membantu Anda memahami bagaimana kami menggunakan Git dalam alur kerja kami.

Git melacak perubahan pada file menggunakan serangkaian tahapan. Perubahan normal terjadi di direktori kerja. Saat Anda puas dengan perubahan yang Anda buat pada serangkaian file, Anda menambahkan file yang telah Anda ubah ke area staging. Setelah Anda membuat semua perubahan yang Anda rencanakan dan mementaskan semua file yang ingin Anda lacak di Git, Anda mengkomit perubahan tersebut ke repositori. Komit pada dasarnya adalah snapshot dari status file dalam repo pada waktu tertentu. Karena Git melacak perubahan pada file dan menyimpan perubahan ini dalam komit, kapan pun Anda dapat mengembalikan proyek ke keadaan semula pada komit sebelumnya.

Ada topik yang lebih kompleks, seperti percabangan dan remote, tetapi kita tidak perlu menggunakannya untuk mendapatkan manfaat dari kontrol sumber. Yang kita butuhkan hanyalah melacak perubahan pada file desain KiCad kita dengan serangkaian commit.

Langkah 6: Struktur Proyek KiCad

Mari kita lihat lebih dekat struktur proyek KiCad-Starter yang Anda kloning sebelumnya. Ini dibagi menjadi beberapa subdirektori untuk organisasi yang mudah:

• Sirkuit: Folder ini berisi file proyek KiCad yang sebenarnya (skema, PCB, dll). Saya tidak mengganti nama folder ini, tetapi saya mengganti nama semua file di dalamnya dengan nama proyek (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: file proyek KiCad
  • Circuit.sch: file skema KiCad.
  • Circuit.kicad_pcb: file layout PCB KiCad.
• Dokumentasi: Folder ini untuk menyimpan dokumentasi mengenai proyek. Kami memiliki rencana untuk meningkatkan ruang ini di masa mendatang, tetapi untuk saat ini berisi file README sederhana. Gunakan untuk menyimpan catatan pada proyek untuk Anda tinjau di masa mendatang.
• Fabrikasi: Folder ini adalah tempat Anda akan menyimpan file gerber yang akan digunakan sebagian besar rumah hebat untuk membuat papan sirkuit Anda. Kami juga menggunakannya untuk menyimpan file BOM dan dokumen lain yang mungkin diperlukan untuk pembuatan dan perakitan.
• Perpustakaan: Folder ini untuk menyimpan file perpustakaan khusus proyek (kami akan membahasnya lebih lanjut dalam beberapa langkah).

Anda mungkin juga memperhatikan beberapa file lain (terutama jika Anda `ls -a` direktori). Direktori.git adalah tempat Git melakukan keajaibannya, menyimpan riwayat repositori. File.gitignore digunakan untuk memberi tahu Git file mana yang harus diabaikan dan tidak disimpan di kontrol sumber. Ini sebagian besar adalah file cadangan yang dibuat oleh KiCad, atau beberapa file "dihasilkan" yang berbeda, seperti netlist, yang tidak boleh disimpan di kontrol sumber karena dibuat dari sumber yang merupakan file skema.

Struktur proyek ini hanyalah titik awal. Anda harus menyesuaikannya agar sesuai dengan kebutuhan Anda, dan menambahkan bagian seperlunya. Dalam beberapa proyek kami telah menyertakan folder perangkat lunak atau folder enklosur, tempat kami menyimpan model untuk enklosur pencetakan 3d untuk proyek tersebut.

Langkah 7: Menggunakan Git untuk Proyek KiCad

Kami akhirnya siap untuk melihat bagaimana menggunakan Git untuk melacak proyek Anda. Instruksi ini tidak dimaksudkan untuk mengajari Anda cara menggunakan KiCad (walaupun saya mungkin akan melakukannya di masa mendatang jika ada permintaan), jadi kami akan membahas beberapa contoh sepele untuk menunjukkan kepada Anda bagaimana alur kerja berjalan. Seharusnya mudah untuk memahami bagaimana mengadaptasi ide-ide ini ke proyek nyata.

Buka direktori kicad-starter, lalu jalankan `git log` untuk menampilkan riwayat komit. Harus ada satu komit di sini, inisialisasi repo oleh Brainbow. Menjalankan `git status` akan memberi tahu Anda status file di repo Anda (tidak terlacak, dimodifikasi, dihapus, dipentaskan).

Saat ini, Anda seharusnya tidak memiliki perubahan dalam repo Anda. Mari lakukan perubahan. Buka proyek KiCad dan tambahkan resistor ke skema, lalu simpan. Sekarang menjalankan `git status` akan menunjukkan bahwa Anda telah memodifikasi file skema, tetapi belum melakukan perubahan tersebut untuk komit. Jika Anda penasaran dengan apa yang sebenarnya dilakukan KiCad saat Anda menambahkan resistor, Anda dapat menjalankan perintah diff pada file yang dimodifikasi `git diff Circuit/Circuit.sch`. Ini akan menyoroti perubahan antara versi file saat ini di direktori kerja dan status file pada komit terakhir.

Sekarang setelah kita membuat perubahan, mari kita coba melakukan perubahan itu ke riwayat proyek kita. Kita perlu memindahkan perubahan dari direktori kerja kita ke staging area. Ini tidak benar-benar memindahkan file dalam sistem file, tetapi secara konseptual merupakan cara untuk memberi tahu Git bahwa Anda telah membuat semua perubahan yang direncanakan untuk file tertentu dan siap untuk melakukan perubahan tersebut. Bermanfaat, Git memberikan beberapa petunjuk saat Anda menjalankan `git status` untuk tindakan selanjutnya. Perhatikan pesan `(gunakan "git add …" untuk memperbarui apa yang akan di-commit)` di bawah `Changes not staged for commit:`. Git memberi tahu Anda cara memindahkan perubahan ke staging area. Jalankan `git add Circuit/Circuit.sch` untuk menampilkan perubahan, lalu `git status` untuk melihat apa yang terjadi. Sekarang kita melihat file skema di bawah perubahan yang harus dilakukan. Jika Anda belum ingin melakukan perubahan ini, Git menawarkan tip lain: `(gunakan "git reset HEAD …" untuk unstage)`. Kami ingin melakukan perubahan ini, jadi kami menjalankan `git commit -m "Added resistor to schematic"`. Ini melakukan perubahan dengan pesan yang disediakan. Menjalankan git log akan menampilkan komit ini dalam riwayat komit proyek.

Beberapa tips lagi tentang komit.

1. Jangan berkomitmen dengan setiap penyimpanan. Berkomitmenlah ketika Anda merasa telah mencapai titik di mana perubahan Anda agak memadat. Saya komit setelah saya menyelesaikan skema, bukan setelah setiap penambahan komponen. Anda juga tidak ingin melakukan terlalu sering, karena mengingat konteks mengapa Anda membuat perubahan yang Anda lakukan 3 minggu kemudian bisa jadi sulit. Mencari tahu kapan harus melakukan adalah sedikit seni, tetapi Anda akan menjadi lebih nyaman saat Anda lebih sering menggunakan Git.
2. Hanya sumber toko (kebanyakan). Ini termasuk file proyek, skema, dan tata letak, serta perpustakaan khusus proyek. Ini juga dapat mencakup file dokumentasi. Berhati-hatilah saat menyimpan objek turunan karena objek tersebut dapat dengan mudah tidak sinkron dengan sumber aslinya, dan itu menyebabkan sakit kepala di kemudian hari. File BOM dan gerber disinkronkan dengan sangat mudah, jadi sebaiknya dihindari (walaupun panduan yang lebih detail dibahas di Langkah 9).
3. Pesan komit sangat berguna, tetapi pesan komit yang terstruktur dengan baik sangat berharga. Artikel luar biasa ini memberikan beberapa panduan untuk menulis pesan komit yang jelas, ringkas, dan bermanfaat. Melakukannya mungkin memerlukan penggunaan editor teks baris perintah, yang dapat saya rumitkan untuk pemula (`git commit` tanpa opsi pesan -m akan membuka editor teks). Bagi kebanyakan orang, saya merekomendasikan editor Nano. StackOverflow memiliki penjelasan yang bagus tentang mengubah editor Anda

Langkah 8: Lanjutan: Versi Semantik untuk Elektronik

Untuk jiwa petualang, tips berikut adalah ide-ide lanjutan, yang diperoleh dari berjam-jam pengembangan KiCad. Mereka tidak terlalu berguna pada proyek yang lebih kecil, tetapi mereka benar-benar dapat menyelamatkan Anda dari sakit hati saat proyek Anda tumbuh dalam kompleksitas.

Dalam software terdapat konsep Semantic Versioning (semver). Semver mendefinisikan metodologi penamaan umum untuk mengidentifikasi rilis perangkat lunak dengan "nomor versi", mengikuti pola "Major. Minor. Patch". Untuk mengutip spesifikasi semver, Anda memajukan nomor versi sesuai dengan kategori perubahan berikut.

1. Versi UTAMA saat Anda membuat perubahan API yang tidak kompatibel,
2. Versi MINOR saat Anda menambahkan fungsionalitas dengan cara yang kompatibel ke belakang,
3. Versi PATCH saat Anda melakukan perbaikan bug yang kompatibel dengan versi sebelumnya.

Kami di Brainbow menggunakan semver versi kami sendiri yang disesuaikan dengan kebutuhan proyek perangkat keras. Spesifikasi kami mengikuti pola "Mayor. Minor. Patch" yang sama, meskipun definisi kami tentang perubahan apa yang termasuk dalam kategori yang jelas berbeda.

1. Versi UTAMA: digunakan untuk perubahan signifikan pada fungsionalitas inti sirkuit (mis: mengalihkan prosesor dari ATmegaa ke ESP8266).
2. Versi MINOR: digunakan untuk pertukaran komponen yang dapat mempengaruhi operasi sirkuit (mis: swap flash SPI dengan bagian yang kompatibel dengan pin yang mungkin memiliki set perintah yang berbeda) atau penambahan beberapa fitur tambahan kecil (mis: menambahkan sensor suhu tambahan).
3. Versi PATCH: digunakan untuk perbaikan bug kecil yang tidak akan mengubah operasi sirkuit (mis: penyesuaian silkscreen, penyesuaian tata letak jejak kecil, pertukaran komponen sederhana seperti kapasitor 0603 ke 0805).

Dalam semver perangkat keras, nomor versi hanya diperbarui pada pembuatan (seperti dalam perangkat lunak, nomor versi hanya berubah dengan rilis, tidak setiap individu berkomitmen untuk sebuah proyek). Akibatnya, banyak proyek memiliki nomor versi rendah. Kami belum memiliki proyek yang menggunakan lebih dari 4 versi utama.

Selain manfaat dalam konsistensi dan pemahaman yang Anda dapatkan dari beralih ke sistem penamaan yang terdefinisi dengan baik, Anda juga mendapatkan manfaat dalam kompatibilitas firmware dan kepuasan pelanggan. Firmware dapat ditulis dengan mempertimbangkan versi papan yang ditargetkan, dan dapat lebih mudah untuk men-debug mengapa program tertentu tidak bekerja pada papan tertentu ("benar, firmware 2.4.1 tidak berjalan pada 1.2 papan karena kita tidak punya …."). Pelanggan juga mendapat manfaat dari server perangkat keras kami karena layanan pelanggan dan pemecahan masalah jauh lebih mudah dengan standar yang ditentukan.

Langkah 9: Tingkat Lanjut: Menggunakan Versi Semantik Perangkat Keras

Untuk menggunakan perangkat keras semver dalam proyek Anda sendiri, kami menggunakan fitur Git yang disebut penandaan. Saat Anda pertama kali membuat papan, itu adalah versi 1.0.0 dari papan itu. Pastikan Anda telah melakukan semua perubahan dalam proyek Anda, lalu jalankan `git tag -a v1.0.0`. Ini akan membuka editor sehingga Anda dapat menulis pesan anotasi untuk tag ini (sangat mirip dengan pesan komit). Saya sertakan detail tentang pembuatannya (siapa yang membuat PCB, siapa yang merakit papan), yang dapat menjadi informasi yang berguna nanti.

Tag rilis ditambahkan ke riwayat komit dan menunjukkan status file pada pembuatan 1.0.0. Ini bisa sangat berguna beberapa revisi nanti ketika Anda perlu merujuk kembali ke titik ini untuk pemecahan masalah. Tanpa tag rilis yang ditentukan, mungkin sulit untuk mengetahui komit mana yang paling baru pada saat pembuatan. Tag 1.0.0 (dan 1.1, 1.1.1, dll) memungkinkan Anda menentukan bahwa file sumber khusus ini adalah yang digunakan dalam proses manufaktur tertentu.

Catatan tentang Gerbers. Beberapa rumah hebat memerlukan file gerber untuk membuat papan Anda, dan Anda dapat membuatnya dengan KiCad. Ini adalah objek turunan, yang dihasilkan dari file sumber.kicad_pcb, dan kami biasanya tidak mengontrol versi file turunan. Kami di Brainbow tidak menyimpan gerber di kontrol versi KECUALI ketika kami menandai rilis. Saat kami siap untuk membangun, kami membuat file gerber, menyimpannya di folder Fabrikasi, dan melakukan komit dan tag. Kemudian kami menghapus gerber dan melakukan penghapusan. Ini mungkin tampak sedikit membingungkan pada awalnya, tetapi memastikan bahwa komit normal hanya menyimpan file sumber, dan rilis yang diberi tag juga menyimpan file persis yang digunakan untuk membuat papan. Ini terbukti sangat berguna dalam melacak kesalahan manufaktur beberapa minggu kemudian.

Langkah 10: Langkah Selanjutnya

Semoga pengantar ini cukup mengajari Anda untuk mulai menggunakan kontrol versi pada proyek elektronik Anda sendiri. Kami tidak membahas beberapa topik yang lebih maju, seperti kontrol versi untuk pustaka yang dibagikan di antara proyek atau cabang fitur. Namun, kontrol versi seperti memakan sayuran Anda: Anda mungkin tidak mendapatkan apa yang Anda pikir seharusnya Anda dapatkan, tetapi setiap bit yang Anda dapatkan berharga.

Brainbow sedang mengerjakan panduan yang lebih mendetail untuk beberapa fitur yang lebih canggih dari alur kerja kami. Kami berharap dapat menerbitkannya dalam beberapa bulan ke depan. Ikuti kami di sini di Instructables, dan kami pasti akan memberi tahu Anda kapan Anda bisa membacanya.

Terima kasih telah membaca, dan kami tidak sabar untuk melihat apa yang Anda buat!