Script Example Analysis

W skrócie

Dowiedz się, jak dwa przykładowe skrypty wykorzystują system skryptowy Altium Designer i modele obiektowe X2 do kopiowania obrysu płytki PCB oraz generowania listy połączeń w formacie Protel. W artykule omówiono kontrolki formularza skryptu Board Outline Copier napisanego w VBScript, interfejsy PCB oraz proces tworzenia obiektów. Następnie przedstawiono skrypt Netlister napisany w DelphiScript oraz interfejsy WorkSpace Manager, których używa on do uzyskiwania dostępu do danych projektu. Czytaj dalej, aby lepiej zrozumieć działanie tych przykładowych skryptów.

- Dowiedz się, jak segmenty obrysu płytki są odtwarzane jako ścieżki i łuki o określonej szerokości na wybranej warstwie.
- Poznaj sposób obsługi tworzenia obiektów PCB, synchronizacji operacji cofania, widoczności warstw i odświeżania dokumentu.
- Odkryj, jak skrypt Netlister wykorzystuje interfejsy projektów, komponentów i sieci do generowania list połączeń w formacie Protel Version 1 lub Version 2.
Zagłęb się w temat dzięki AI:
 

Aby przybliżyć ogólne aspekty systemu skryptowego oraz wykorzystanie Delphi i modeli obiektowych X2 w skryptach, omówiono tutaj działanie dwóch przykładowych projektów — skryptu kopiującego obrys płytki i skryptu generującego listę połączeń.

Skrypty Board Outline Copier i Netlister opracowano z wykorzystaniem modeli obiektowych X2, aby zilustrować możliwości systemu skryptowego w Altium Designer. Są to gotowe skrypty dostępne w zbiorze przykładowych skryptów:

  • Skrypt Board Outline Copier wykorzystuje model obiektowy PCB do kopiowania istniejącego obrysu płytki PCB jako ścieżek i łuków na wskazaną warstwę.
    Zobacz \Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR.
  • Skrypt generatora listy połączeń wykorzystuje model obiektowy WorkSpace Manager do generowania listy połączeń w tradycyjnym formacie Protel (v1 i v2).
    Zobacz \Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCR.

W przedstawionych przykładach wykorzystano języki DelphiScript i VBScript. DelphiScript jest oparty na Embarcadero Delphi, a VBScript — na technologii Microsoft Scripting.

► Informacje o różnicach między DelphiScript a Object Pascal (używanym w Delphi) można znaleźć w dokumentacji referencyjnej DelphiScript.

► Więcej informacji o VBScript można znaleźć w dokumentacji Microsoft VBScript .

Projekt Board Outline Copier

Celem skryptu Board Outline Copier jest skopiowanie istniejącego obrysu płytki z dokumentu PCB na inną warstwę w tym samym dokumencie.

Projekt wykorzystuje formularz skryptu, dzięki któremu użytkownik może w oknie dialogowym określić szerokość linii obrysu płytki i wybrać warstwę docelową z menu rozwijanego. Za pomocą modelu obiektowego PCB i jego interfejsów z API PCB obiekty obrysu płytki są pobierane i kopiowane na wskazaną warstwę.

► Przykład działania skryptu

  • Należy pamiętać, że omawiany tutaj skrypt Board Outline Copier napisano w VBScript, a nie w DelphiScript.

  • Projekty VBScript są obecnie uznawane za przestarzałe. Aby umożliwić tworzenie nowych projektów VBScript, zaznacz opcję Legacy.Scripts.SupportOldLanguages w oknie dialogowym Advanced Settings.

  • Dokumentacja API skryptowego jest dostępna tutaj: Obiekty API skryptowego. Należy pamiętać, że tę dokumentację ostatnio zaktualizowano dla starszej wersji Altium Designer. Chociaż wiele zasad i sposobów postępowania pozostaje bez zmian, interfejsy, obiekty, metody, właściwości itp. uległy od tego czasu zmianom, a dokumentacja nie obejmuje wszystkich elementów dostępnych w nowszych wersjach oprogramowania.

Główne elementy skryptu to:

  • Zmienna globalna PCB_Board (typu IPCB_Board).
  • Podprogram CopyBoardOutline przyjmujący parametry AWidth i ALayer.
  • Procedura obsługi zdarzenia bOkClick, która pobiera wartości szerokości i warstwy z formularza skryptu, a następnie wykonuje podprogram CopyBoardOutline.
  • Procedura obsługi zdarzenia bCancelClick, która zamyka formularz skryptu Board Outline (okno dialogowe).

Działanie skryptu

Skrypt wykorzystuje formularz, który wymaga procedur obsługi zdarzeń do przechwytywania kliknięć myszą poszczególnych kontrolek, takich jak przyciski OK i Cancel.

Procedura obsługi zdarzenia przycisku OK wygląda zasadniczo następująco:

Sub bOKClick(Sender)
  Dim Width
  Dim Layer

  Call StringToCoordUnit(eWidth.Text,Width,PCB_Board.DisplayUnit)
  Layer = String2Layer(cbLayers.Items(cbLayers.ItemIndex))
End Sub

W tym przypadku procedura obsługi zdarzenia myszy OnClick formularza (bOKClick) wykorzystuje funkcję StringToCoordUnit do przeliczenia wprowadzonej szerokości linii obrysu (ciągu znaków eWidth z pola TEdit) na wewnętrzne jednostki współrzędnych. Funkcja ta stosuje bieżące jednostki płytki (właściwość PCB_Board.DisplayUnit) do zmiennej Width.

Podobnie ciąg znaków wybranej warstwy (element cbLayers z kontrolki TComboBox formularza) jest przekazywany do funkcji String2Layer w celu uzyskania wartości wyliczeniowej dla zmiennej Layer. Należy pamiętać, że w tym projekcie kontrolka TComboBox formularza jest wstępnie wypełniona indeksowaną listą ciągów znaków warstw (cbLayers.Items) — listę warstw można znaleźć w pliku CopyBoardOutlineForm.dfm formularza.

Wersja projektu Board Outline Copier w DelphiScript wykorzystuje dodatkową procedurę do pobrania listy dostępnych warstw z bieżącej płytki.

W ostatnim kroku procedura obsługi zdarzenia (bOKClick) wywołuje podprogram CopyBoardOutline ze zmiennymi Width i Layer przekazanymi jako parametry. Procedura obsługi przycisku Cancel formularza (bCancelClick) po prostu zamyka formularz.

Interfejs IPCB_Board

W procedurze obsługi przycisku OK (bOKClick) bieżąca płytka jest pobierana z interfejsu IPCB_Board za pośrednictwem IPCB_ServerInterface zwracanego przez specjalną funkcję PCBServer. W tym przypadku funkcja GetCurrentPCB przypisuje odwołanie do bieżącej płytki do zmiennej PCB_Board.

Bieżący obrys płytki (IPC_BoardOutline) jest następnie pobierany w całym skrypcie z właściwości BoardOutline interfejsu IPCB_Board, z użyciem powyższego odwołania do płytki PCB_Board.

Przed przystąpieniem do kopiowania i tworzenia nowego obrysu należy zainicjalizować obrys płytki. Obrys — reprezentowany przez interfejs IPCB_BoardOutline — można zainicjalizować za pomocą metod przebudowy i walidacji tego interfejsu.

PCB_Board.BoardOutline.Invalidate
PCB_Board.BoardOutline.Rebuild
PCB_Board.BoardOutline.Validate

Należy pamiętać, że uzyskanie dostępu do IPCB_ServerInterface — reprezentującego edytor PCB — za pomocą funkcji PCBServer udostępnia wszystkie pozostałe interfejsy obiektów PCB, takie jak interfejs IPCB_Board itp. W tym skrypcie do ich pobierania służy przypisana zmienna PCB_Board.

Segmenty łuków i ścieżek obrysu

Interfejs IPCB_BoardOutline, reprezentujący obrys płytki, dziedziczy po interfejsie IPCB_Group. Interfejs IPCB_Group reprezentuje obiekt grupowy, który może przechowywać obiekty podrzędne. Przykładem zastosowania interfejsu IPCB_Group jest wielokąt lub obrys płytki, ponieważ mogą one przechowywać łuki i ścieżki jako obiekty podrzędne.

Obiekt obrysu płytki przechowuje dwa różne typy segmentów — ePolySegmentLine i ePolySegmentArc, reprezentujące odpowiednio obiekt ścieżki lub łuku. Liczbę segmentów określa właściwość PointCount interfejsu IPCB_BoardOutline, który pobiera każdy wierzchołek obrysu do zmiennej I na potrzeby pętli For-To-Next.

Każdy segment pobranego obrysu płytki jest sprawdzany za pomocą instrukcji If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then w celu ustalenia, czy jest ścieżką, czy łukiem. Jeśli nie jest segmentem ścieżki (ePolySegmentLine), część Else instrukcji zakłada, że segment jest łukiem.

Dla każdego znalezionego segmentu, zależnie od jego typu, tworzony jest nowy obiekt ścieżki lub łuku za pomocą funkcji PCBObjectFactory.

Funkcja PCBObjectFactory

Do tworzenia nowych obiektów PCB służy funkcja PCBObjectFactory bezpośrednio z interfejsu IPCB_ServerInterface.

'Create new Track object
PCBServer.PCBObjectFactory(eTrackObject, eNoDimension, eCreate_Default)

'Create new Arc object
PCBServer.PCBObjectFactory(eArcObject, eNoDimension, eCreate_Default)

Parametry funkcji PCBObjectFactory określają typ obiektu (ścieżka, łuk, przelotka itp.), rodzaj wymiaru (liniowy, promieniowy itp.) oraz tryb tworzenia obiektu (według lokalnych ustawień domyślnych lub preferencji globalnych).

Po utworzeniu każdego obiektu ścieżki lub łuku przez procedurę PCBObjectFactory jego właściwości są inicjalizowane przez następujące po niej instrukcje dotyczące ścieżki lub łuku.

Właściwości ścieżek i łuków są reprezentowane przez odpowiednie interfejsy, IPCB_Track i IPCB_Arc, a skrypt ustawia odpowiednie właściwości. Na przykład współrzędne nowej ścieżki są pobierane z wierzchołków segmentu obrysu źródłowego, przy czym Track.X1 i Track.Y1 reprezentują współrzędne początku ścieżki, a właściwości X2 i Y2 — współrzędne jej końca.

Track.X1     = PCB_Board.BoardOutline.Segments(I).vx
Track.Y1     = PCB_Board.BoardOutline.Segments(I).vy
Track.X2     = PCB_Board.BoardOutline.Segments(J).vx
Track.Y2     = PCB_Board.BoardOutline.Segments(J).vy
Track.Layer  = ALayer
Track.Width  = AWidth

Jak widać również w powyższym fragmencie kodu, właściwości Layer i Width ścieżki są definiowane po prostu przez przekazane wartości pobrane z okna dialogowego interfejsu użytkownika — zmienne cbLayers i eWidth formularza.

Po pełnym zdefiniowaniu nowe obiekty są dodawane do określonej warstwy dokumentu PCB za pomocą instrukcji PCB_Board.AddPCBObject(NewObject), gdzie NewObject oznacza tutaj Track lub Arc.

PreProcess i PostProcess

Podczas tworzenia obiektu PCB należy najpierw wywołać metodę PreProcess z interfejsu obiektu IPCB_ServerInterface, aby przygotować serwer PCB. Po utworzeniu obiektu stosuje się metodę PostPocess (również z interfejsu IPCB_ServerInterface), aby poinformować serwer, że dodawanie obiektów zostało zakończone.

Metody PreProcess i PostProcess zapewniają aktualność i synchronizację systemu cofania operacji oraz innych podsystemów edytora PCB. Poniżej przedstawiono przykładowy fragment kodu z instrukcjami PreProcess i PostProcess.

PCBServer.PreProcess
'Create PCB objects
PCBServer.PostProcess

Jeśli obiekty są dodawane do wskazanej warstwy, która nie jest wyświetlana w dokumencie PCB, należy wymusić jej widoczność. Służy do tego instrukcja PCB_Board.LayerIsDisplayed(ALayer) = True, gdzie ALayer oznacza warstwę wybraną przez użytkownika.

Odświeżanie dokumentu

Na koniec dokument PCB z nowym obrysem płytki jest odświeżany za pomocą polecenia PCB:Zoom i powiązanych z nim parametrów Action = Redraw. Parametry polecenia powiększenia są stosowane przy użyciu procedury AddStringParameter, po uprzednim wyczyszczeniu bufora parametrów metodą ResetParameters.

Projekt Netlister

Celem projektu skryptowego Netlister jest wygenerowanie standardowej listy połączeń Protel (w formacie wersji 1 lub wersji 2) dla projektu Altium Designer zawierającego schematy. Płaska lista połączeń projektu schematowego jest podzielona na dwie sekcje:

  • Oznaczenia komponentów i informacje związane z poszczególnymi komponentami,
  • Nazwy sieci i informacje związane z poszczególnymi nazwami sieci wraz z połączeniami wyprowadzeń (wyprowadzeń komponentu).

► Przykład działania skryptu

Model obiektowy WorkSpace Manager interfejsu API udostępnia interfejsy reprezentujące projekt i jego elementy składowe — dokumenty, komponenty i ich wyprowadzenia oraz sieci. WorkSpace Manager to serwer systemowy ściśle powiązany z modułem Client, który obsługuje projekty i związane z nimi dokumenty. Zapewnia kompilację, obsługę projektów wieloarkuszowych, narzędzia do nawigacji po połączeniach, obsługę projektów wielokanałowych, wielu dokumentów implementacyjnych itd. Aby uzyskać interfejs WorkSpace Manager, należy wywołać funkcję GetWorkspace, która zwraca interfejs IWorkspace.

W skrypcie Netlister istotne są interfejsy IWorkSpace, IProject, IDocument, IComponent i INet.

Należy pamiętać, że niektóre interfejsy, zwłaszcza interfejsy obiektów projektowych, mają swoje odpowiedniki wśród interfejsów obiektów schematu. Wynika to z faktu, że dokumenty logiczne w projekcie są dokumentami schematów zawierającymi informacje o połączeniach. W rzeczywistości zamiast WorkSpace Manager można użyć modelu obiektowego schematu, jednak ten pierwszy zapewnia funkcje kompilowania projektu i pobierania z niego dokumentów, a także odczytywania danych z obiektów schematu.

Główne elementy skryptu Netlister to:

  • Globalna zmienna tekstowa TargetFileName, która przechowuje nazwę pliku listy połączeń.
  • Globalny obiekt kolekcji Netlist TStringList, który jest wypełniany danymi listy połączeń.
  • Procedury WriteComponent_Version1 i WriteComponent_Version2.
  • Procedury WriteNet_Version1 i WriteNet_Version2.
  • Funkcja ConvertElectricToString, która przekształca właściwość elektryczną wyprowadzenia w ciąg znaków.
  • Procedura GenerateNetlist, która zarządza generowaniem danych oraz zadaniami związanymi z nazwą pliku, ścieżką i katalogiem.
Skrypt Netlister jest napisany w języku DelphiScript.

Działanie skryptu

Dwie procedury bezparametrowe, GenerateProtelV1FormatNetlist i GenerateProtelV2FormatNetlist, pojawią się w oknie dialogowym Select Item to Run, umożliwiając wybór generowania listy połączeń w formacie Protel V1 lub Protel V2. Procedury te wywołują procedurę GenerateNetlist, przekazując wybrany format listy połączeń (0 lub 1) jako parametr.

Procedure GenerateProtelV1FormatNetlist;
Var
 Version : Integer;
Begin
 // Protel 1 Netlist format, pass 0
 GenerateNetlist(0);
End;

Procedure GenerateProtelV2FormatNetlist;
Var
 Version : Integer;
Begin
 // Protel 2 Netlist format, pass 1
 GenerateNetlist(1);
End;

GenerateNetList

Procedura GenerateNetList pobiera interfejs obszaru roboczego, aby następnie można było uzyskać interfejs bieżącego projektu (IWorkspace.DM_FocusedProject).

Przed pobraniem sieci należy skompilować projekt, ponieważ proces kompilacji tworzy informacje o jego połączeniach. W tym celu stosowana jest metoda DM_Compile interfejsu projektu (IProject.DM_Compile), jak pokazano w poniższym fragmencie kodu. Należy pamiętać, że najnowsze wersje Altium Designer kompilują projekty automatycznie, więc ten krok jest opcjonalny.

WS := GetWorkspace;
 If WS = Nil Then Exit;

Prj := WS.DM_FocusedProject;
 If Prj = Nil Then Exit;

// Compile the project to fetch the connectivity info for design.
 Prj.DM_Compile;

Informacje o komponentach i sieciach są przechowywane w obiekcie Netlist typu TStringList, który jest później używany do generowania sformatowanego pliku tekstowego listy połączeń. Obiekt TStringList jest klasą języka Delphi, z której można korzystać w skryptach.

Następnie wywoływana jest procedura Generate z parametrami określającymi ścieżkę i nazwę pliku bieżącego projektu oraz wersję formatu listy połączeń.

Generate

Procedura Generate pobiera ścieżkę projektu jako docelową ścieżkę wyjściową dla generowanego pliku listy połączeń (z przekazanego parametru DocumentPath), ustala nazwę pliku listy połączeń (TargetFileName) i sprawdza stan spłaszczenia projektu (IProject.DM_DocumentFlattened).

Następnie każdy dokument schematu w projekcie jest sprawdzany pod kątem sieci i komponentów za pomocą procedur WriteNets i WriteComponents, a uzyskane dane trafiają ostatecznie do obiektu Netlist.

Zapisywanie sieci i komponentów

Lista połączeń składa się z sekcji komponentów i sekcji sieci, dlatego do oddzielnego zapisywania danych komponentów i danych sieci potrzebne są dwie procedury.

Do listy połączeń zapisywane są tylko sieci zawierające więcej niż dwa węzły, a sieci z mniejszą ich liczbą są pomijane. Dla każdej sieci jej nazwa jest określana na podstawie metody DM_CalculatedNetName obiektu sieci, która pobiera nazwy sieci z informacji o połączeniach skompilowanego projektu.

Poniżej przedstawiono dwa fragmenty kodu dotyczące sekcji komponentów i sieci listy połączeń w formacie wersji 1. Należy pamiętać, że dane komponentów i sieci są przechowywane w obiekcie NetList typu TStringList. Wygenerowana lista połączeń składa się z dwóch sekcji: sekcji informacji o komponentach i sekcji informacji o sieciach.

Sekcja komponentów

W procedurze WriteComponent dla każdego komponentu znalezionego w projekcie sprawdzane jest, czy jest on rzeczywistym komponentem, a następnie pobierane są wartości oznaczenia fizycznego, obudowy montażowej i typu części. Są one dodawane do kontenera obiektu Netlist (NetList.Add) w celu utworzenia właściwej listy połączeń.

If Component <> Nil Then
Begin
 NetList.Add('[');
 NetList.Add(Component.DM_PhysicalDesignator);
 NetList.Add(Component.DM_FootPrint);
 NetList.Add(Component.DM_PartType);
 NetList.Add('');
 NetList.Add('');
 NetList.Add('');
 NetList.Add(']');
End;

Sekcja sieci

W procedurze Nets nazwa sieci i oznaczenia są pobierane, jeśli sieć ma co najmniej dwa wyprowadzenia (INet.DM_PinCount). Informacje o sieci i wyprowadzeniach wraz ze znakami formatującymi są dodawane do kontenera Netlist w celu utworzenia listy połączeń. Poniższy fragment przedstawia procedurę zapisu sieci dla listy połączeń w wersji 1.

If Net.DM_PinCount >= 2 Then
Begin
 NetList.Add('(');
 NetList.Add(Net.DM_CalculatedNetName);
 For i := 0 To Net.DM_PinCount – 1 Do
 Begin
   Pin := Net.DM_Pins(i);
   PinDsgn := Pin.DM_PhysicalPartDesignator;
   PinNo := Pin.DM_PinNumber;
   NetList.Add(PinDsgn + '-' + PinNo);
 End;
 NetList.Add(')');
End;

Należy pamiętać, że bardziej rozbudowany format listy połączeń, Protel v2, zawiera właściwości elektryczne wyprowadzeń sieci (In, Out, Passive, HiZ itd.).

Procedura zapisu sieci w formacie w wersji 2 (WriteNet_Version2) odczytuje zatem właściwość elektryczną każdego wyprowadzenia w sieci (INet.DM_Electical), która jest następnie konwertowana przez wywołaną procedurę ConvertElectricToString — będącą w istocie tabelą konwersji ciągów znaków. Wyniki są następnie dodawane do lokalnej zmiennej tekstowej (ElectricalString), która z kolei jest dodawana do obiektu kontenera listy sieci.

Tworzenie pliku listy sieci

Na koniec, gdy obiekt kontenera Netlist jest już w pełni wypełniony informacjami o komponentach i sieciach projektu w wybranym formacie, procedura Generate zapisuje dane Netlist do pliku (TStringList.SaveToFile). Ścieżkę i nazwę pliku określa zmienna tekstowa TargetFileName, której wartość jest ustalana w procedurze Generate.

AI-LocalizedTłumaczenie SI
Jeśli znajdziesz błąd, zaznacz tekst/obraz i naciśnij Ctrl + Enter aby wysłać nam wiadomość.
Nav
Contents
Dostępność funkcji

Dostępne funkcje zależą od tego, z którego rozwiązania Altium korzystasz – Altium Develop, Altium Agile Teams, Altium Agile Enterprise lub Altium Designer (w ramach aktywnej subskrypcji terminowej).

Jeśli opisana funkcja nie jest widoczna w Twoim oprogramowaniu, skontaktuj się z działem sprzedaży Altium, aby dowiedzieć się więcej.

Starsza dokumentacja

Dokumentacja Altium Designer nie jest już wersjonowana. Jeśli potrzebujesz dostępu do dokumentacji dla starszych wersji Altium Designer, odwiedź sekcję Starsza dokumentacja na stronie Inne instalatory.

Contents