Phân tích Ví dụ Script
Sơ lược
- Tìm hiểu cách các đoạn đường bao bo mạch được tái tạo thành các đoạn mạch và cung tròn trên lớp đã chọn với độ rộng được chỉ định.
- Hiểu cách xử lý việc tạo đối tượng PCB, đồng bộ hóa thao tác hoàn tác, hiển thị lớp và làm mới tài liệu.
- Khám phá cách Netlister sử dụng các giao diện dự án, linh kiện và net để tạo netlist Protel Phiên bản 1 hoặc Phiên bản 2.
Để làm rõ hơn các khía cạnh chung của Hệ thống tạo tập lệnh, cũng như việc sử dụng Delphi và các mô hình đối tượng X2 trong tập lệnh, phần này sẽ xem xét hai dự án ví dụ dưới góc độ chức năng – một công cụ sao chép đường bao bo mạch và một tập lệnh tạo netlist.
Các tập lệnh Board Outline Copier và Netlister được phát triển bằng các mô hình đối tượng X2 nhằm minh họa khả năng của hệ thống tạo tập lệnh trong Altium Designer. Đây là các tập lệnh có sẵn trong bộ sưu tập tập lệnh ví dụ, cụ thể như sau:
-
Tập lệnh Board Outline Copier sử dụng Mô hình đối tượng PCB để sao chép đường bao bo mạch PCB hiện có thành các đoạn mạch và cung tròn trên một lớp được chỉ định.
Xem\Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR. -
Tập lệnh tạo netlist sử dụng Mô hình đối tượng WorkSpace Manager để tạo netlist theo định dạng Protel truyền thống (v1 và v2).
Xem\Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCR.
Dự án Board Outline Copier
Mục đích của Board Outline Copier là sao chép đường bao bo mạch hiện có từ tài liệu PCB sang một lớp khác trong cùng tài liệu.
Dự án sử dụng một biểu mẫu tập lệnh để người dùng có thể tương tác với hộp thoại nhằm chỉ định độ rộng của đường bao bo mạch và chọn lớp đích từ menu thả xuống. Thông qua Mô hình đối tượng PCB và các giao diện PCB của mô hình này trong PCB API, các đối tượng của đường bao bo mạch được trích xuất và sao chép lên lớp được chỉ định.
► Ví dụ về hoạt động của tập lệnh
Các thành phần chính của tập lệnh gồm:
-
Một biến toàn cục
PCB_Board(thuộc kiểuIPCB_Board). -
Một chương trình con
CopyBoardOutlinenhận các tham sốAWidthvàALayer. -
Trình xử lý sự kiện
bOkClicklấy các giá trị độ rộng và lớp từ biểu mẫu tập lệnh, sau đó thực thi chương trình conCopyBoardOutline. -
Trình xử lý sự kiện
bCancelClickđóng biểu mẫu tập lệnh Board Outline (hộp thoại).
Chức năng của tập lệnh
Tập lệnh sử dụng một biểu mẫu tập lệnh cần có các trình xử lý sự kiện để ghi nhận thao tác nhấp chuột trên từng phần tử điều khiển, chẳng hạn như các nút OK và Cancel.
Về cơ bản, trình xử lý sự kiện của nút OK như sau:
Sub bOKClick(Sender)
Dim Width
Dim Layer
Call StringToCoordUnit(eWidth.Text,Width,PCB_Board.DisplayUnit)
Layer = String2Layer(cbLayers.Items(cbLayers.ItemIndex))
End Sub
Ở đây, trình xử lý sự kiện chuột OnClick của biểu mẫu (bOKClick) sử dụng hàm StringToCoordUnit để lấy độ rộng đường bao đã nhập (chuỗi eWidth từ ô TEdit) dưới dạng giá trị tọa độ nội bộ. Hàm này áp dụng đơn vị hiện tại của bo mạch (thuộc tính PCB_Board.DisplayUnit) cho biến Width.
Tương tự, chuỗi lớp được chọn (mục cbLayers từ TComboBox của biểu mẫu) được truyền vào hàm String2Layer để lấy một giá trị liệt kê cho biến Layer. Lưu ý rằng trong dự án này, TComboBox của biểu mẫu được điền sẵn một danh sách các chuỗi lớp có đánh chỉ mục (cbLayers.Items) – xem tệp CopyBoardOutlineForm.dfm của biểu mẫu để biết danh sách lớp.
Bước cuối cùng trong trình xử lý sự kiện (bOKClick) gọi chương trình con CopyBoardOutline với các biến Width và Layer được truyền làm tham số. Trình xử lý cho nút Cancel của biểu mẫu (bCancelClick) chỉ đơn giản là đóng biểu mẫu.
Giao diện IPCB_Board
Trong trình xử lý của nút OK (bOKClick), bo mạch hiện tại được lấy từ giao diện IPCB_Board thông qua IPCB_ServerInterface do hàm đặc biệt PCBServer trả về. Ở đây, hàm GetCurrentPCB gán tham chiếu bo mạch hiện tại cho biến PCB_Board.
Sau đó, trong suốt tập lệnh, đường bao bo mạch hiện tại (IPC_BoardOutline) được lấy từ thuộc tính BoardOutline của giao diện IPCB_Board, bằng cách sử dụng tham chiếu bo mạch PCB_Board ở trên.
Đường bao bo mạch cần được khởi tạo trước khi tiến hành sao chép và tạo đường bao mới. Một đường bao – được biểu diễn bằng giao diện IPCB_BoardOutline – có thể được khởi tạo bằng các phương thức tái tạo/xác thực của giao diện.
PCB_Board.BoardOutline.Invalidate
PCB_Board.BoardOutline.Rebuild
PCB_Board.BoardOutline.Validate
Các đoạn cung tròn và đoạn mạch của đường bao
Giao diện IPCB_BoardOutline, đại diện cho đường bao bo mạch, kế thừa từ giao diện IPCB_Group. Giao diện IPCB_Group đại diện cho một đối tượng nhóm có thể lưu trữ các đối tượng con. Ví dụ về giao diện IPCB_Group là một đa giác hoặc đường bao bo mạch, vì chúng có thể lưu trữ các cung tròn và đoạn mạch dưới dạng đối tượng con.
Một đối tượng đường bao bo mạch lưu trữ hai loại đoạn khác nhau – ePolySegmentLine và ePolySegmentArc, lần lượt đại diện cho đối tượng đoạn mạch hoặc cung tròn. Số lượng đoạn được xác định bằng thuộc tính PointCount từ giao diện IPCB_BoardOutline; từng đỉnh của đường bao được trích xuất vào biến I cho vòng lặp For-To-Next.
Mỗi đoạn của đường bao bo mạch thu được đều được kiểm tra xem là đoạn mạch hay cung tròn bằng câu lệnh If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then. Nếu không phải là đoạn mạch (ePolySegmentLine) thì phần Else của câu lệnh sẽ coi đoạn đó là một cung tròn.
Với mỗi đoạn tìm được, tùy theo loại đoạn, một đối tượng đoạn mạch hoặc cung tròn mới sẽ được tạo bằng hàm PCBObjectFactory.
Hàm PCBObjectFactory
Việc tạo các đối tượng PCB mới sử dụng hàm PCBObjectFactory trực tiếp từ giao diện IPCB_ServerInterface.
'Create new Track object
PCBServer.PCBObjectFactory(eTrackObject, eNoDimension, eCreate_Default)
'Create new Arc object
PCBServer.PCBObjectFactory(eArcObject, eNoDimension, eCreate_Default)
Các tham số của hàm PCBObjectFactory thiết lập loại đối tượng (đoạn mạch, cung tròn, via, v.v.), kiểu kích thước (tuyến tính, hướng kính, v.v.) và chế độ tạo đối tượng (theo mặc định cục bộ hoặc tùy chọn toàn cục).
Sau khi mỗi đối tượng đoạn mạch hoặc cung tròn được tạo bởi thủ tục PCBObjectFactory, các thuộc tính của đối tượng được khởi tạo bằng các câu lệnh dành cho đoạn mạch/cung tròn theo sau.
Các thuộc tính của đoạn mạch và cung tròn được biểu diễn bằng các giao diện tương ứng, IPCB_Track và IPCB_Arc, trong đó các thuộc tính liên quan được tập lệnh thiết lập. Ví dụ, tọa độ của đoạn mạch mới được lấy từ các đỉnh của đoạn đường bao nguồn, trong đó Track.X1 và Track.Y1 biểu thị tọa độ đầu của đoạn mạch, còn các thuộc tính X2 và Y2 là tọa độ cuối.
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
Như cũng có thể thấy trong đoạn mã ở trên, các thuộc tính Layer và Width của đường mạch được xác định đơn giản bằng các giá trị truyền vào lấy từ hộp thoại giao diện người dùng – các biến cbLayers và eWidth của Form.
Sau khi được xác định đầy đủ, các đối tượng mới được thêm vào một lớp chỉ định của tài liệu PCB bằng câu lệnh PCB_Board.AddPCBObject(NewObject), trong đó NewObject ở đây là Track hoặc Arc.
PreProcess và PostProcess
Khi tạo một đối tượng PCB, trước tiên cần gọi phương thức PreProcess từ giao diện đối tượng IPCB_ServerInterface để chuẩn bị cho máy chủ PCB. Sau khi tạo đối tượng, phương thức PostPocess (cũng thuộc giao diện IPCB_ServerInterface) được áp dụng để thông báo cho máy chủ rằng việc thêm đối tượng đã hoàn tất.
Các phương thức PreProcess và PostProcess giúp hệ thống Hoàn tác và các hệ thống con khác của trình chỉnh sửa PCB luôn được cập nhật và đồng bộ. Dưới đây là đoạn mã minh họa với các câu lệnh PreProcess và PostProcess.
PCBServer.PreProcess
'Create PCB objects
PCBServer.PostProcess
Khi các đối tượng được thêm vào một lớp chỉ định chưa được hiển thị trong tài liệu PCB, cần buộc lớp đó hiển thị. Việc này được xử lý bằng câu lệnh PCB_Board.LayerIsDisplayed(ALayer) = True, trong đó ALayer là lớp do người dùng chọn.
Làm mới tài liệu
Cuối cùng, tài liệu PCB với đường bao bo mạch mới được làm mới bằng lệnh PCB:Zoom cùng các tham số Action = Redraw liên quan. Các tham số của lệnh thu phóng được áp dụng bằng thủ tục AddStringParameter sau khi bộ đệm tham số được xóa bằng phương thức ResetParameters.
Dự án Netlister
Mục đích của dự án tập lệnh Netlister này là tạo một netlist Protel tiêu chuẩn (ở định dạng Phiên bản 1 hoặc Phiên bản 2) cho một dự án Altium Designer có chứa sơ đồ nguyên lý. Netlist phẳng của một dự án sơ đồ nguyên lý được chia thành hai phần:
- Ký hiệu định danh linh kiện và thông tin liên quan đến từng linh kiện,
- Tên net và thông tin liên quan đến từng tên net, cùng với các kết nối chân (các chân của linh kiện).
► Ví dụ về hoạt động của tập lệnh
Mô hình đối tượng WorkSpace Manager của API cung cấp các giao diện đại diện cho dự án và các thành phần cấu thành – tài liệu, linh kiện cùng các chân của chúng và các net. WorkSpace Manager là một máy chủ hệ thống được tích hợp chặt chẽ với mô-đun Client, đảm nhiệm việc xử lý các dự án và tài liệu liên quan. Nó cung cấp khả năng biên dịch, hỗ trợ thiết kế nhiều trang, các công cụ điều hướng kết nối, hỗ trợ đa kênh, nhiều tài liệu triển khai, v.v. Để lấy giao diện WorkSpace Manager, hãy gọi hàm GetWorkspace, hàm này trả về giao diện IWorkspace.
Đối với tập lệnh Netlister, các giao diện cần quan tâm là IWorkSpace, IProject, IDocument, IComponent và INet.
Lưu ý rằng một số giao diện, đặc biệt là các giao diện đối tượng thiết kế, tương ứng với các giao diện đối tượng sơ đồ nguyên lý tương đương. Điều này là do các tài liệu logic trong dự án là các tài liệu sơ đồ nguyên lý chứa thông tin kết nối. Trên thực tế, có thể sử dụng mô hình đối tượng sơ đồ nguyên lý thay cho WorkSpace Manager, nhưng WorkSpace Manager cung cấp chức năng biên dịch dự án và trích xuất tài liệu từ dự án, cũng như truy xuất dữ liệu từ các đối tượng sơ đồ nguyên lý.
Các phần chính của tập lệnh Netlister gồm:
-
Một biến chuỗi toàn cục
TargetFileName, chứa tên tệp netlist. -
Một đối tượng tập hợp Netlist
TStringListtoàn cục, được điền dữ liệu netlist. -
Các thủ tục
WriteComponent_Version1vàWriteComponent_Version2. -
Các thủ tục
WriteNet_Version1vàWriteNet_Version2. -
Một hàm
ConvertElectricToStringchuyển đổi thuộc tính điện của chân thành chuỗi. -
Thủ tục
GenerateNetlistquản lý việc tạo dữ liệu và các tác vụ quản lý tên tệp, đường dẫn và thư mục.
Chức năng của tập lệnh
Hai thủ tục không có tham số, GenerateProtelV1FormatNetlist và GenerateProtelV2FormatNetlist, sẽ xuất hiện trong hộp thoại Select Item to Run, cho phép chọn tạo netlist định dạng Protel V1 hoặc Protel V2. Các thủ tục này gọi thủ tục GenerateNetlist với lựa chọn định dạng netlist (0 hoặc 1) được truyền vào dưới dạng tham số.
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
Thủ tục GenerateNetList lấy giao diện không gian làm việc để sau đó có thể trích xuất giao diện dự án cho dự án hiện tại (IWorkspace.DM_FocusedProject).
Dự án cần được biên dịch trước khi có thể trích xuất các net, vì quá trình biên dịch xây dựng thông tin kết nối của dự án. Phương thức DM_Compile của giao diện dự án được áp dụng (IProject.DM_Compile) như minh họa trong đoạn mã bên dưới. Lưu ý rằng các phiên bản Altium Designer gần đây tự động biên dịch dự án, vì vậy bước này là tùy chọn.
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;
Thông tin linh kiện và net được lưu trong đối tượng Netlist thuộc kiểu TStringList, sau đó được dùng để tạo tệp văn bản netlist có định dạng. Đối tượng TStringList là một lớp Delphi có thể sử dụng trong các tập lệnh.
Sau đó, thủ tục Generate được gọi với các tham số truyền vào xác định đường dẫn và tên tệp của dự án hiện tại, cùng với phiên bản định dạng netlist.
Generate
Thủ tục Generate lấy đường dẫn dự án làm đường dẫn đầu ra đích cho tệp netlist được tạo (từ tham số DocumentPath truyền vào), xác định tên tệp netlist (TargetFileName) và kiểm tra trạng thái làm phẳng của dự án (IProject.DM_DocumentFlattened).
Đối với tất cả các tài liệu sơ đồ nguyên lý trong dự án, từng tài liệu sau đó được kiểm tra để tìm các net và linh kiện bằng các thủ tục WriteNets và WriteComponents, rồi cuối cùng dữ liệu được trích xuất vào đối tượng Netlist.
Ghi net và linh kiện
Một netlist gồm các phần linh kiện và net, vì vậy cần hai thủ tục để ghi riêng dữ liệu linh kiện và dữ liệu net.
Chỉ các net có hơn hai nút mới được ghi vào netlist; các net có ít nút hơn sẽ bị loại bỏ. Với mỗi net, tên net được xác định dựa trên phương thức DM_CalculatedNetName của Net, phương thức này trích xuất tên net từ thông tin kết nối của dự án đã biên dịch.
Hai đoạn mã cho các phần Linh kiện và Net của netlist được trình bày bên dưới cho định dạng netlist Phiên bản 1. Lưu ý rằng dữ liệu linh kiện và net được lưu trong đối tượng NetList, thuộc kiểu TStringList. Netlist được tạo gồm hai phần: phần thông tin linh kiện và phần thông tin net.
Phần linh kiện
Trong thủ tục WriteComponent, mỗi linh kiện được tìm thấy trong Dự án đều được kiểm tra xem có phải là linh kiện thực hay không, sau đó các giá trị ký hiệu định danh vật lý, footprint và loại linh kiện được trích xuất. Các giá trị này được thêm vào đối tượng chứa Netlist (NetList.Add) để xây dựng netlist.
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;
Phần net
Đối với thủ tục Nets, NetName và Designators được trích xuất nếu một net có từ hai chân trở lên (INet.DM_PinCount). Thông tin net và chân cùng với các ký tự định dạng được thêm vào đối tượng chứa Netlist để xây dựng netlist. Đoạn mã bên dưới là thủ tục ghi net cho netlist phiên bản 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;
Lưu ý rằng định dạng netlist chi tiết hơn, Protel v2, bao gồm các thuộc tính điện của các chân thuộc net (In, Out, Passive, HiZ, v.v.).
Do đó, quy trình ghi net cho định dạng phiên bản 2 (WriteNet_Version2) sẽ truy vấn thuộc tính điện của từng chân thuộc net (INet.DM_Electical), sau đó thuộc tính này được chuyển đổi bằng thủ tục ConvertElectricToString được gọi – về cơ bản là một bảng tra cứu chuyển đổi chuỗi. Các giá trị này sau đó được thêm vào một biến chuỗi cục bộ (ElectricalString), rồi biến này được thêm vào đối tượng chứa Netlist.
Tạo tệp Netlist
Cuối cùng, khi đối tượng chứa Netlist đã được điền đầy đủ thông tin về linh kiện và net của dự án theo định dạng đã chọn, thủ tục Generate sẽ ghi dữ liệu Netlist vào một tệp (TStringList.SaveToFile). Đường dẫn và tên tệp được xác định bởi biến chuỗi TargetFileName, theo thiết lập trong thủ tục Generate.


