Automatisch erstellte Dokumentation unserer PCB-Designs in Altium

Ab sofort bietet #alpha-board unsere per Toolchain aufgesetzte Autodoku neben Hardware-Entwicklungsprojekten auch für PCB-Designs in Altium an. Für KiCAD haben wir das auch geplant, sind aber noch in der Umsetzung.



Autodoku? Wie? Wat? Was ist das?

alpha-board hat gemeinsam mit einigen unserer Kunden bereits in 2019 begonnen, Werkzeuge für die automatische Dokumentation von Hardwareentwicklungen zu aufzusetzen und zu implementieren. Aktuell noch begrenzt auf Altium-Projekte kann mit Hilfe von verschiedenen CI/CD- und Dokumenten-Werkzeugen tagesaktuell eine Dokumentation eines aktuellen Projekts erstellt werden. Nachdem beispielsweise Änderungen im Projekt zum jeweiligen Projekt-Git auf unserem Gitlab gepusht wurden, können automatisch mit Gitlab-CI/CD die aktuellen Daten aus dem Projekt gelesen werden. Diese werden dann mit Sphinx-Doc als Webseite im ReadTheDocs-Stil und als PDF formatiert und anschließend auf unserem Webserver veröffentlicht. In Gitlab wird dann im Projekt ein Link erzeugt, der zu unserem Webserver führt. Oauth2 sorgt dafür, dass nur Mitglieder der Projektgruppe in Gitlab Zugriff erhalten.


Überblick über unsere Autodoku für PCB-Designs in Altium


Und wozu das ganze?

Für die Firmwareentwicklung ist es beispielsweise eine große Hilfe, wenn die Schnittstellen während der Entwicklung schon feststehen und zuverlässig dokumentiert sind. So werden bei Entwicklungsprojekten beispielsweise Bus-Adressen von Peripherie, Pin-Belegungen und Jumper-Optionen direkt aus den Bauteilparametern in die Dokumentation übernommen. Das erspart Nachfragen, reduziert Fehlerquellen durch veraltete oder manuell gepflegte Listen oder doppelt vorhandene Informationen und beschleunigt die Inbetriebnahme erheblich. Firmware-Entwickler können sich darauf verlassen, dass die Dokumentation dem tatsächlichen Hardwarestand entspricht – tagesaktuell.

Am deutlichsten traten diese Probleme in Projekten auf, wo wir agil Hardware entwickelten. Dort arbeiten wir auch in Teams, die interdisziplinär zusammengesetzt sind. Und für alle Nicht-Hardware-Entwickler waren diese und ähnliche Informationen immer schwer tagesgenau zu beschaffen.

Auch für das Hardware-Team selbst ist Autodoku Gold wert

  • Zeitersparnis: Das mühsame manuelle Erstellen und Aktualisieren von Schnittstellendokumenten, Pinlisten oder Konfigurationsübersichten entfällt weitgehend. Entwickler können sich auf das Design konzentrieren.
  • Konsistenz & Genauigkeit: Die Informationen kommen direkt aus der "Single Source of Truth" – dem Altium-Projekt mit seinen Bibliotheken, Stromlaufplänen und Layout-Daten. Was im Design festgelegt ist, steht auch in der Doku. Keine Abweichungen mehr durch Copy-Paste-Fehler oder vergessene Updates.
  • Vereinfachte Reviews: Design Reviews werden effizienter, da alle relevanten Informationen (über die reinen Schaltpläne und Layouts hinaus) strukturiert und aktuell zur Verfügung stehen.
  • Verbesserte Zusammenarbeit: Alle Projektbeteiligten (Hardware, Firmware, Software, Mechanik, Test, Inbetriebnahme, Bestücker, Projektleitung) haben über den Webserver Zugriff auf die gleiche, tagesaktuelle Dokumentation.
  • Nachvollziehbarkeit: Durch die Anbindung an Gitlab ist die Historie unserer Dokumentation direkt mit der Historie des Designs verknüpft. Änderungen sind nachvollziehbar.
  • Selbst Informationen zur mechanischen Integration, wie Board-Abmessungen oder Positionen von Befestigungslöchern, können, sofern im Design entsprechend parametrisiert, automatisch in die Dokumentation einfließen.


Anzeige von Interfaces, Buttons, LEDs in unserer autodoku für Altium-PCB-Designs


Zusammenfassend ist uns folgendes klar geworden: Unsere Autodoku reduziert unseren Dokumentationsaufwand drastisch, erhöht die Genauigkeit sowie Aktualität der technischen Dokumentation und verbessert die Zusammenarbeit im gesamten Entwicklungsteam. Und weil wir in unseren (agilen) Hardware-Entwicklungsprojekten so gute Erfahrungen damit gemacht haben, rollen wir dieses Feature nun auch für unsere PCB-Designs (in Altium) aus.

Agilität und frühes Feedback inklusive

Ein weiterer entscheidender Vorteil liegt in agiler Zusammenarbeit: Da unsere Dokumentation tagesaktuell über Gitlab zugänglich ist, können auch Kunden frühzeitig Einblick nehmen. Werden anhand der Autodoku Unstimmigkeiten oder potenzielle Probleme im Design oder in der Spezifikation erkannt, können direkt Issues im Gitlab-Projekt erstellt werden. Dieses direkte Feedback fließt sofort in den Entwicklungsprozess zurück – Transparenz und Agilität pur!

Neu: Fokussierte Autodoku für reine PCB-Projekte

Neben der umfassenden Autodoku für komplette Entwicklungsprojekte bieten wir ab sofort auch eine fokussierte Variante speziell für Altium-PCB-Designs an. Diese abgespeckte Version konzentriert sich auf die wesentlichen Aspekte der Platine selbst und ist ideal, um schnell und effizient den Status Quo eines Designs zu dokumentieren.

Was beinhaltet diese PCB-Autodoku konkret?

  • Project Overview: Wer ist der Kunde, wer sind wir (alpha-board), Eckdaten zum Projekt (Datum, Webseite).
  • System Overview: Aussagekräftige 3D-Ansichten des Boards für einen schnellen Überblick.
  • PCB-Design / Layout: Die Kerninformationen wie Lagenaufbau, wesentliche Design Rules, Board-Abmessungen und Bestückungsinformationen.
  • BOM: die aktuelle Bill of Materials
  • Schaltpläne (SCH): Als eingebettete Bilder zur schnellen Ansicht und als komplette, herunterladbare PDFs.

Zukünftig planen wir auch hier, die in Gitlab erstellten Kunden-Issues direkt in der Dokumentation zu verlinken, um die Nachverfolgbarkeit von Feedback und Änderungen noch einfacher zu gestalten.

Egal ob komplexes Entwicklungsprojekt oder reines PCB-Design – mit unserer Autodoku von alpha-board bringen wir Effizienz, Transparenz und Agilität in eure Hardware-Dokumentation. Sprecht uns an, wenn ihr mehr wissen wollt!