Script Example Analysis
W skrócie
- 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.
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.
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ę.
Główne elementy skryptu to:
-
Zmienna globalna
PCB_Board(typuIPCB_Board). -
Podprogram
CopyBoardOutlineprzyjmujący parametryAWidthiALayer. -
Procedura obsługi zdarzenia
bOkClick, która pobiera wartości szerokości i warstwy z formularza skryptu, a następnie wykonuje podprogramCopyBoardOutline. -
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.
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
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).
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_Version1iWriteComponent_Version2. -
Procedury
WriteNet_Version1iWriteNet_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.
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.


