Script Example Analysis

스크립팅 시스템의 일반적인 측면과, 스크립트에서 Delphi 및 X2 Object Model을 사용하는 방법에 대한 이해를 더하기 위해, 여기서는 기능 관점에서 두 가지 예제 프로젝트—보드 외곽선 복사기와 넷리스트 생성 스크립트—를 살펴봅니다.

Board Outline Copier 및 Netlister 스크립트는 Altium Designer의 스크립팅 시스템 기능을 보여주기 위해 X2 Object Model을 사용하여 개발되었습니다. 이들은 example script collection에서 제공되는 기존 스크립트이며, 다음과 같습니다:

• Board Outline Copier 스크립트는 PCB Object Model을 사용하여 기존 PCB 보드 외곽선을 트랙과 아크 형태로 지정한 레이어에 복사합니다.
  \Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR를 참조하십시오.
• Netlist generator 스크립트는 WorkSpace Manager Object Model을 사용하여 전통적인 Protel(v1 및 v2) 형식의 넷리스트를 생성합니다.
  \Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCR를 참조하십시오.

Board Outline Copier 프로젝트

Board Outline Copier의 목적은 PCB 문서에 있는 기존 보드 외곽선을 동일 문서의 다른 레이어로 복사하는 것입니다.

이 프로젝트는 Script Form을 사용하여 사용자가 대화상자에서 보드 외곽선의 폭을 지정하고 드롭다운 메뉴에서 대상 레이어를 선택할 수 있도록 합니다. PCB API의 PCB Object Model 및 PCB 인터페이스를 사용해 보드 외곽선의 객체를 추출한 뒤 지정한 레이어로 복사합니다.

► 스크립트 동작 예

스크립트의 주요 구성 요소는 다음과 같습니다:

• 전역 PCB_Board ( IPCB_Board 타입) 변수.
• AWidth 및 ALayer 파라미터를 받는 CopyBoardOutline 서브루틴.
• 스크립트 폼에서 폭과 레이어 값을 가져온 뒤 CopyBoardOutline 서브루틴을 실행하는 bOkClick 이벤트 핸들러.
• Board Outline 스크립트 폼(대화상자)을 닫는 bCancelClick 이벤트 핸들러.

스크립트 기능

이 스크립트는 OK 및 Cancel 버튼과 같은 개별 컨트롤의 마우스 클릭을 캡처하기 위해 이벤트 핸들러가 필요한 Script Form을 사용합니다.

OK 버튼 이벤트 핸들러는 기본적으로 아래와 같습니다:

Sub bOKClick(Sender)
  Dim Width
  Dim Layer

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

여기서 폼의 마우스 OnClick 이벤트 핸들러(bOKClick)는 StringToCoordUnit 함수를 사용하여 외곽선 폭으로 입력된 값(TEdit 박스의 eWidth 문자열)을 내부 좌표 값으로 변환해 얻습니다. 이 함수는 현재 보드 단위(PCB_Board.DisplayUnit 속성)를 Width 변수에 적용합니다.

마찬가지로 선택된 레이어 문자열(폼 TComboBox의 cbLayers 항목)은 String2Layer 함수로 전달되어 Layer 변수에 대한 열거형 값을 얻습니다. 이 프로젝트에서는 폼의 TComboBox가 레이어 문자열(cbLayers.Items)의 인덱스 목록으로 미리 채워져 있다는 점에 유의하십시오. 레이어 목록은 폼의 CopyBoardOutlineForm.dfm 파일을 참조하십시오.

이벤트 핸들러(bOKClick)의 마지막 단계에서는 Width 및 Layer 변수를 전달 파라미터로 하여 CopyBoardOutline 서브루틴을 호출합니다. 폼의 Cancel 버튼(bCancelClick)에 대한 핸들러는 단순히 폼을 닫습니다.

IPCB_Board 인터페이스

OK 버튼 핸들러(bOKClick)에서 현재 보드는 특수 PCBServer 함수가 반환하는 IPCB_ServerInterface를 통해 IPCB_Board 인터페이스에서 가져옵니다. 여기서 GetCurrentPCB 함수는 현재 보드 참조를 PCB_Board 변수에 설정합니다.

그 다음 현재 보드 외곽선(IPC_BoardOutline)은 위의 PCB_Board 보드 참조를 사용하여, IPCB_Board 인터페이스의 BoardOutline 속성을 통해 스크립트 전반에서 얻습니다.

복사 및 새 외곽선 생성을 진행하기 전에 보드 외곽선을 초기화해야 합니다. IPCB_BoardOutline 인터페이스로 표현되는 외곽선은 해당 인터페이스의 재빌드/검증 메서드를 사용해 초기화할 수 있습니다.

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

외곽선 아크 및 트랙 세그먼트

보드 외곽선을 나타내는 IPCB_BoardOutline 인터페이스는 IPCB_Group 인터페이스에서 상속됩니다. IPCB_Group 인터페이스는 자식 객체를 저장할 수 있는 그룹 객체를 나타냅니다. IPCB_Group 인터페이스의 예로는 폴리곤이나 보드 외곽선이 있으며, 이들은 아크와 트랙을 자식 객체로 저장할 수 있습니다.

보드 외곽선 객체는 두 가지 서로 다른 유형의 세그먼트—ePolySegmentLine 및 ePolySegmentArc—를 저장하며, 이는 각각 트랙 또는 아크 객체를 나타냅니다. 세그먼트 수는 IPCB_BoardOutline 인터페이스의 PointCount 속성으로 결정되며, 이는 각 외곽선 정점을 For-To-Next 루프를 위한 I 변수로 추출합니다.

가져온 보드 외곽선의 각 세그먼트는 If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then 문으로 트랙과 아크인지 확인합니다. 트랙 세그먼트(ePolySegmentLine)가 아니라면, 문장의 Else 부분에서는 해당 세그먼트가 아크라고 가정합니다.

발견된 각 세그먼트에 대해, 세그먼트 유형에 따라 PCBObjectFactory 함수를 사용해 새 트랙 또는 아크 객체를 생성합니다.

PCBObjectFactory 함수

새 PCB 객체 생성은 IPCB_ServerInterface 인터페이스에서 PCBObjectFactory 함수를 직접 사용하여 수행합니다.

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

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

PCBObjectFactory 함수의 파라미터는 객체 유형(Track, Arc, Via 등), 치수 종류(Linear, Radial 등), 그리고 객체 생성 모드(로컬 기본값 또는 전역 환경설정)를 설정합니다.

PCBObjectFactory 프로시저로 각 트랙 또는 아크 객체가 생성된 후, 뒤따르는 트랙/아크 구문에 의해 해당 속성이 인스턴스화됩니다.

Track 및 Arc 속성은 각각의 인터페이스 IPCB_Track 및 IPCB_Arc로 표현되며, 스크립트에서 관련 속성을 구현합니다. 예를 들어 새 트랙 좌표는 소스 외곽선 세그먼트의 정점에서 가져오며, Track.X1 및 Track.Y1는 트랙의 시작 좌표를, X2 및 Y2 속성은 끝 좌표를 나타냅니다.

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

위 코드 조각에서 볼 수 있듯이, 트랙의 Layer 및 Width 속성은 사용자 인터페이스 대화상자에서 추출되어 전달된 값—폼의 cbLayers 및 eWidth 변수—로 간단히 정의됩니다.

완전히 정의되면, 새 객체는 PCB_Board.AddPCBObject(NewObject) 문을 통해 PCB 문서의 지정 레이어에 추가되며, 여기서 NewObject는 Track 또는 Arc입니다.

PreProcess 및 PostProcess

PCB 객체를 생성할 때는 PCB 서버를 준비하기 위해 먼저 IPCB_ServerInterface 객체 인터페이스의 PreProcess 메서드를 호출해야 합니다. 객체 생성 후에는(역시 IPCB_ServerInterface 인터페이스의) PostPocess 메서드를 적용하여 객체 추가가 완료되었음을 서버에 알립니다.

PreProcess 및 PostProcess 메서드는 Undo 시스템과 PCB 편집기의 다른 서브시스템을 최신 상태로 유지하고 동기화합니다. 아래는 PreProcess 및 PostProcess 문을 포함한 대표적인 코드 조각입니다.

PCBServer.PreProcess
'Create PCB objects
PCBServer.PostProcess

PCB 문서에서 아직 표시되지 않은 레이어에 객체가 추가되는 경우, 해당 레이어를 강제로 보이도록 해야 합니다. 이는 PCB_Board.LayerIsDisplayed(ALayer) = True 문으로 처리되며, 여기서 ALayer는 사용자가 선택한 레이어입니다.

문서 새로 고침

마지막으로 새 보드 외곽선이 포함된 PCB 문서는 PCB:Zoom 명령과 관련 Action = Redraw 파라미터로 새로 고침됩니다. 줌 명령 파라미터는, 먼저 ResetParameters 메서드로 파라미터 버퍼를 지운 뒤 AddStringParameter 프로시저를 사용해 적용합니다.

Netlister 프로젝트

이 Netlister 스크립트 프로젝트의 목적은 회로도(schematics)를 포함한 Altium Designer 프로젝트에 대해 표준 Protel 넷리스트(Version 1 또는 Version 2 형식)를 생성하는 것입니다. 회로도 프로젝트의 플랫(flat) 넷리스트는 두 개의 섹션으로 나뉩니다:

• 컴포넌트 설계자(Designator)와 각 컴포넌트에 연관된 정보,
• 넷 이름과 각 넷 이름에 연관된 정보, 그리고 핀 연결(컴포넌트의 핀).

► 스크립트 동작 예

API의 WorkSpace Manager Object Model은 프로젝트와 그 구성 요소(문서, 컴포넌트 및 그 핀, 넷)를 표현하는 인터페이스를 제공합니다. WorkSpace Manager는 프로젝트와 관련 문서를 다루는 Client 모듈과 긴밀하게 결합된 시스템 서버입니다. 이는 컴파일, 멀티 시트 설계 지원, 연결성 탐색 도구, 멀티 채널 지원, 다중 구현 문서 등과 같은 기능을 제공합니다. WorkSpace Manager 인터페이스를 가져오려면 GetWorkspace 함수를 호출하며, 이 함수는 IWorkspace 인터페이스를 반환합니다.

Netlister 스크립트에서 관심 있는 인터페이스는 IWorkSpace, IProject, IDocument, IComponent, INet 인터페이스입니다.

일부 인터페이스, 특히 설계 객체 인터페이스는 동등한 Schematic Object 인터페이스에 대응한다는 점에 유의하십시오. 이는 프로젝트의 논리 문서가 연결성 정보를 포함한 회로도 문서이기 때문입니다. 실제로 WorkSpace Manager 대신 Schematic Object 모델을 사용할 수도 있지만, WorkSpace Manager는 프로젝트를 컴파일하고 프로젝트에서 문서를 추출하는 기능뿐 아니라 회로도 객체에서 데이터를 가져오는 기능도 제공합니다.

Netlister 스크립트의 주요 구성 요소는 다음과 같습니다:

• 전역 TargetFileName 문자열 변수. 넷리스트의 파일 이름입니다.
• 넷리스트 데이터로 채워지는 전역 Netlist TStringList 컬렉션 객체.
• WriteComponent_Version1 및 WriteComponent_Version2 프로시저.
• WriteNet_Version1 및 WriteNet_Version2 프로시저.
• 핀의 전기적 속성을 문자열로 변환하는 ConvertElectricToString 함수
• 데이터 생성과 파일명, 경로 및 디렉터리 정리 작업을 관리하는 GenerateNetlist 프로시저.

스크립트 기능

매개변수가 없는 두 프로시저 GenerateProtelV1FormatNetlist 및 GenerateProtelV2FormatNetlist는 Select Item to Run dialog에 표시되며, Protel V1 형식 넷리스트 또는 Protel V2 형식 넷리스트 생성 중 하나를 선택할 수 있게 합니다. 이 프로시저들은 넷리스트 형식 선택(0 또는 1)을 매개변수로 전달하여 GenerateNetlist 프로시저를 호출합니다.

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

GenerateNetList 프로시저는 워크스페이스 인터페이스를 가져와서, 현재 프로젝트(IWorkspace.DM_FocusedProject)에 대한 프로젝트 인터페이스를 추출할 수 있도록 합니다.

넷을 추출하기 전에 프로젝트를 컴파일해야 하는데, 컴파일 과정에서 프로젝트의 연결성 정보가 구축되기 때문입니다. 아래 코드 스니펫에 보인 것처럼 프로젝트 인터페이스의 DM_Compile 메서드를 적용합니다(IProject.DM_Compile). 참고로 최신 버전의 Altium Designer는 프로젝트를 자동으로 컴파일하므로 이 단계는 선택 사항입니다.

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;

컴포넌트 및 넷 정보는 TStringList 타입의 Netlist 객체에 저장되며, 이는 이후 포맷된 넷리스트 텍스트 파일을 생성하는 데 사용됩니다. TStringList 객체는 스크립트에서 사용할 수 있는 Delphi 클래스입니다.

그 다음 Generate 프로시저가 호출되며, 현재 프로젝트 경로와 파일명, 그리고 넷리스트 형식 버전을 정의하는 매개변수들이 전달됩니다.

Generate

Generate 프로시저는 전달된 DocumentPath 매개변수로부터 프로젝트 경로를 생성될 넷리스트 파일의 대상 출력 경로로 가져오고, 넷리스트 파일명(TargetFileName)을 결정하며, 프로젝트의 플래튼(flattened) 상태(IProject.DM_DocumentFlattened)를 확인합니다.

프로젝트 내 모든 회로도 문서에 대해, 각 문서는 WriteNets 및 WriteComponents 프로시저로 넷과 컴포넌트를 검사한 뒤, 최종적으로 Netlist 객체로 추출됩니다.

넷과 컴포넌트 쓰기

넷리스트는 컴포넌트 섹션과 넷 섹션으로 구성되므로, 컴포넌트 데이터와 넷 데이터를 각각 별도로 기록하는 두 개의 프로시저가 필요합니다.

노드가 2개를 초과하는 넷만 넷리스트에 기록되며, 그보다 적은 넷은 폐기됩니다. 각 넷에 대해 넷 이름은 Net의 DM_CalculatedNetName 메서드를 기반으로 하며, 이 메서드는 컴파일된 프로젝트의 연결성 정보에서 넷 이름을 추출합니다.

아래에는 Version 1 넷리스트 형식에 대한 넷리스트의 Components 섹션과 Nets 섹션 코드 스니펫 두 개가 나와 있습니다. 컴포넌트 및 넷 데이터는 NetList 객체( TStringList 타입)에 저장됩니다. 생성된 넷리스트는 두 섹션, 즉 컴포넌트 정보 섹션과 넷 정보 섹션으로 구성됩니다.

Components 섹션

WriteComponent 프로시저에서는 프로젝트에서 발견된 각 컴포넌트가 실제 컴포넌트인지 확인한 다음, 물리 설계자(physical designator), 풋프린트(footprint), 파트 타입(part type) 값을 추출합니다. 이 값들은 넷리스트 자체를 구성하기 위해 Netlist 객체 컨테이너(NetList.Add)에 추가됩니다.

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;

Nets 섹션

Nets 프로시저에서는 넷에 핀이 2개 이상(INet.DM_PinCount)인 경우 NetName과 Designator를 추출합니다. 넷 및 핀 정보와 포맷팅 문자를 Netlist 컨테이너에 추가하여 넷리스트를 구성합니다. 아래 스니펫은 Version 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;

더 상세한 넷리스트 형식인 Protel v2에는 넷 핀의 전기적 속성(In, Out, Passive, HiZ 등)이 포함된다는 점에 유의하십시오.

따라서 Version 2 형식(WriteNet_Version2)의 넷 기록 프로시저는 각 넷 핀의 전기적 속성(INet.DM_Electical)을 조회하며, 이는 호출된 ConvertElectricToString 프로시저에 의해 변환됩니다(본질적으로 문자열 변환 룩업 테이블). 그런 다음 이 값들은 로컬 문자열 변수(ElectricalString)에 추가되고, 이어서 Netlist 컨테이너 객체에 추가됩니다.

넷리스트 파일 생성

마지막으로 Netlist 컨테이너 객체가 선택한 형식으로 프로젝트의 컴포넌트 및 넷 정보로 완전히 채워지면, Generate 프로시저가 Netlist 데이터를 파일(TStringList.SaveToFile)로 기록합니다. 파일 경로와 이름은 Generate 프로시저에서 결정된 TargetFileName 문자열 변수로 정의됩니다.