Análise do Exemplo de Script

Para fornecer uma perspetiva mais aprofundada sobre os aspetos gerais do Sistema de Scripting, e sobre a utilização dos Modelos de Objetos Delphi e X2 em scripts, são aqui analisados dois projetos de exemplo do ponto de vista funcional – um copiador do contorno da placa e um script de geração de netlist.

Os scripts Board Outline Copier e Netlister são desenvolvidos com recurso aos Modelos de Objetos X2 para ilustrar as capacidades do sistema de scripting no Altium Designer. Estes são scripts existentes disponíveis na coleção de scripts de exemplo, como segue:

• O script Board Outline Copier utiliza o Modelo de Objetos PCB para copiar o contorno existente da placa PCB como tracks e arcs para uma camada especificada.
  Consulte \Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR.
• O script de geração de netlist utiliza o Modelo de Objetos WorkSpace Manager para gerar uma netlist no formato tradicional Protel (v1 e v2).
  Consulte \Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCR.

Projeto Board Outline Copier

O objetivo do Board Outline Copier é copiar um contorno de placa existente do documento PCB para uma camada diferente no mesmo documento.

O projeto utiliza um Script Form para que o utilizador possa interagir com uma caixa de diálogo para indicar a largura do contorno da placa e selecionar a camada de destino a partir de um menu pendente. Utilizando o modelo de objetos PCB e as suas interfaces PCB a partir da PCB API, os objetos de um contorno de placa são extraídos e copiados para a camada especificada.

► Exemplo de funcionamento do script

As partes principais do script são:

• Uma variável global PCB_Board (do tipo IPCB_Board).
• Uma subrotina CopyBoardOutline que aceita os parâmetros AWidth e ALayer.
• O gestor de eventos bOkClick, que obtém os valores de largura e camada do script form e depois executa a subrotina CopyBoardOutline.
• O gestor de eventos bCancelClick, que fecha o script form (caixa de diálogo) do Board Outline.

Funcionalidade do script

O script utiliza um script Form que necessita de gestores de eventos para captar os cliques do rato nos controlos individuais, como os botões OK e Cancel.

O gestor de eventos do botão OK é essencialmente o seguinte:

Sub bOKClick(Sender)
  Dim Width
  Dim Layer

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

Aqui, o gestor de eventos OnClick do rato do formulário (bOKClick) utiliza a função StringToCoordUnit para obter a largura introduzida do contorno (a string eWidth da caixa TEdit) em valores internos de coordenadas. Esta função aplica as unidades atuais da placa (propriedade PCB_Board.DisplayUnit) à variável Width.

De forma semelhante, a string da camada selecionada (o item cbLayers da TComboBox do formulário) é passada à função String2Layer para obter um valor enumerado para a variável Layer. Note que, neste projeto, a TComboBox do formulário é pré-preenchida com uma lista indexada de strings de camadas (cbLayers.Items) – consulte o ficheiro CopyBoardOutlineForm.dfm do Form para a lista de camadas.

O passo final no gestor de eventos (bOKClick) chama a subrotina CopyBoardOutline com as variáveis Width e Layer como parâmetros passados. O gestor do botão Cancel do formulário (bCancelClick) limita-se a fechar o formulário.

Interface IPCB_Board

Dentro do gestor do botão OK (bOKClick), a placa atual é obtida a partir da interface IPCB_Board através do valor IPCB_ServerInterface devolvido pela função especial PCBServer. Aqui, a função GetCurrentPCB define a referência da placa atual para a variável PCB_Board.

O contorno atual da placa (IPC_BoardOutline) é então obtido ao longo de todo o script a partir da propriedade BoardOutline da interface IPCB_Board, utilizando a referência de placa PCB_Board acima.

O contorno da placa tem de ser inicializado antes de se avançar com a cópia e a criação de um novo contorno. Um contorno – representado pela interface IPCB_BoardOutline – pode ser inicializado utilizando os métodos de reconstrução/validação da interface.

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

Segmentos de arco e track do contorno

A interface IPCB_BoardOutline, que representa o contorno da placa, é herdada da interface IPCB_Group. Uma interface IPCB_Group representa um objeto de grupo que pode armazenar objetos filhos. Um exemplo de uma interface IPCB_Group é um polígono ou um contorno de placa, uma vez que estes podem armazenar arcs e tracks como objetos filhos.

Um objeto de contorno de placa armazena dois tipos diferentes de segmentos – ePolySegmentLine e ePolySegmentArc, que representam respetivamente um objeto track ou arc. O número de segmentos é determinado pela propriedade PointCount da interface IPCB_BoardOutline, que extrai cada vértice do contorno para a variável I para o ciclo For-To-Next.

Cada segmento do contorno da placa obtido é verificado quanto a tracks e arcs com a instrução If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then. Se não for um segmento track (ePolySegmentLine), a parte Else da instrução assume que o segmento é um arc.

Para cada segmento encontrado e consoante o tipo de segmento, é criado um novo objeto track ou arc utilizando a função PCBObjectFactory.

Função PCBObjectFactory

A criação dos novos objetos PCB emprega diretamente a função PCBObjectFactory a partir da interface IPCB_ServerInterface.

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

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

Os parâmetros da função PCBObjectFactory definem o tipo de objeto (Track, Arc, Via, etc.), o tipo de dimensão (Linear, Radial, etc.) e o modo de criação do objeto (para uma predefinição local ou preferências globais).

Depois de cada objeto track ou arc ser criado pelo procedimento PCBObjectFactory, as suas propriedades são instanciadas pelas instruções de track/arc que se seguem.

As propriedades de Track e Arc são representadas pelas respetivas interfaces, IPCB_Track e IPCB_Arc, nas quais as propriedades relevantes são implementadas pelo script. Por exemplo, as novas coordenadas do track são obtidas a partir dos vértices do segmento do contorno de origem, em que Track.X1 e Track.Y1 representam as coordenadas iniciais do track e as propriedades X2 e Y2 são as suas coordenadas finais.

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

Como também se pode ver no excerto de código acima, as propriedades Layer e Width do track são simplesmente definidas pelos valores passados extraídos da caixa de diálogo da interface do utilizador – as variáveis cbLayers e eWidth do Form.

Depois de totalmente definidos, os novos objetos são adicionados a uma camada especificada do documento PCB com a instrução PCB_Board.AddPCBObject(NewObject), em que NewObject aqui é Track ou Arc.

PreProcess e PostProcess

Ao criar um objeto PCB, o método PreProcess da interface de objeto IPCB_ServerInterface tem primeiro de ser invocado para preparar o servidor PCB. Após a criação do objeto, o método PostPocess (também da interface IPCB_ServerInterface) é aplicado para informar o servidor de que a adição dos objetos está concluída.

Os métodos PreProcess e PostProcess mantêm o sistema Undo e outros subsistemas do editor PCB atualizados e sincronizados. Abaixo encontra-se um excerto de código representativo com as instruções PreProcess e PostProcess.

PCBServer.PreProcess
'Create PCB objects
PCBServer.PostProcess

Quando os objetos são adicionados a uma camada indicada que não tenha sido apresentada no documento PCB, é necessário forçar a visibilidade da camada. Isto é tratado pela instrução PCB_Board.LayerIsDisplayed(ALayer) = True, em que ALayer é a camada selecionada pelo utilizador.

Atualização do documento

Por fim, o documento PCB com o seu novo contorno de placa é atualizado pelo comando PCB:Zoom e pelos respetivos parâmetros Action = Redraw. Os parâmetros do comando de zoom são aplicados utilizando o procedimento AddStringParameter depois de o buffer de parâmetros ser primeiro limpo com o método ResetParameters.

Projeto Netlister

O objetivo deste projeto de script Netlister é gerar uma netlist Protel padrão (em formatos Version 1 ou Version 2) para um projeto do Altium Designer que contenha esquemas. Uma netlist plana de um projeto esquemático é separada em duas secções:

• Designadores dos componentes e a informação associada a cada componente,
• Nomes das nets e a informação associada a cada nome de net, juntamente com as ligações dos pinos (pinos de um componente).

► Exemplo de funcionamento do script

O Modelo de Objetos do WorkSpace Manager da API fornece interfaces que representam o projeto e os seus constituintes – os documentos, os componentes e os seus pinos, e as nets. O WorkSpace Manager é um servidor de sistema fortemente acoplado ao módulo Client que trata dos projetos e dos seus documentos associados. Fornece compilação, suporte a designs multi-folha, ferramentas de navegação de conectividade, suporte multi-canal, múltiplos documentos de implementação, entre outras funcionalidades. Para obter a interface do WorkSpace Manager, invoque a função GetWorkspace, que devolve a interface IWorkspace.

Para o script Netlister, as interfaces de interesse são as interfaces IWorkSpace, IProject, IDocument, IComponent e INet.

Note que algumas das interfaces, especialmente as interfaces de objetos de design, correspondem a interfaces equivalentes de Objetos Esquemáticos. Isto acontece porque os documentos lógicos de um projeto são documentos esquemáticos com informação de conectividade. Na verdade, o modelo de Objetos Esquemáticos pode ser usado em vez do WorkSpace Manager, mas este último fornece a funcionalidade para compilar um projeto e extrair documentos de um projeto, bem como para obter dados a partir de objetos esquemáticos.

As partes principais do script Netlister são:

• Uma variável global de string TargetFileName, que é o nome do ficheiro da netlist.
• Um objeto global de coleção Netlist TStringList, que é preenchido com os dados da netlist.
• Os procedimentos WriteComponent_Version1 e WriteComponent_Version2.
• Os procedimentos WriteNet_Version1 e WriteNet_Version2.
• Uma função ConvertElectricToString que converte a propriedade elétrica de um pino numa string
• O procedimento GenerateNetlist, que gere a geração dos dados e as tarefas de manutenção do nome do ficheiro, caminho e diretório.

Funcionalidade do script

Os dois procedimentos sem parâmetros, GenerateProtelV1FormatNetlist e GenerateProtelV2FormatNetlist, aparecerão na caixa de diálogo Select Item to Run dialog, oferecendo a escolha entre gerar uma netlist em formato Protel V1 ou em formato Protel V2. Estes procedimentos chamam o procedimento GenerateNetlist com a escolha do formato da netlist (0 ou 1) como parâmetro passado.

Procedure GenerateProtelV1FormatNetlist;
Var
 Version : Integer;
Begin
 // Formato de netlist Protel 1, passar 0
 GenerateNetlist(0);
End;

Procedure GenerateProtelV2FormatNetlist;
Var
 Version : Integer;
Begin
 // Formato de netlist Protel 2, passar 1
 GenerateNetlist(1);
End;

GenerateNetList

O procedimento GenerateNetList obtém a interface do workspace para que a interface do projeto possa depois ser extraída para o projeto atual (IWorkspace.DM_FocusedProject).

O projeto precisa de ser compilado antes de as nets poderem ser extraídas, uma vez que o processo de compilação constrói a informação de conectividade do projeto. É aplicado o método DM_Compile da interface do projeto (IProject.DM_Compile), como mostrado no excerto de código abaixo. Note que as versões recentes do Altium Designer compilam os projetos automaticamente, pelo que este passo é opcional.

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

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

// Compilar o projeto para obter a informação de conectividade para o design.
 Prj.DM_Compile;

A informação dos componentes e das nets é armazenada no objeto Netlist do tipo TStringList, que é depois usado para gerar um ficheiro de texto de netlist formatado. O objeto TStringList é uma classe Delphi disponível para utilização em scripts.

O procedimento Generate é então chamado com parâmetros passados que definem o caminho e o nome do ficheiro do projeto atual, além da versão do formato da netlist.

Generate

O procedimento Generate obtém o caminho do projeto como caminho de saída de destino para o ficheiro de netlist gerado (a partir do parâmetro passado DocumentPath), determina o nome do ficheiro da netlist (TargetFileName) e verifica o estado flattened do projeto (IProject.DM_DocumentFlattened).

Para todos os documentos esquemáticos de um projeto, cada documento é depois verificado quanto a nets e componentes com os procedimentos WriteNets e WriteComponents, e por fim extraído para o objeto Netlist.

Escrever Nets e Componentes

Uma netlist é composta por secções de componentes e de nets, pelo que são necessários dois procedimentos para escrever separadamente os dados dos componentes e os dados das nets.

Apenas as nets com mais de dois nós serão escritas numa netlist, e as que tiverem menos são descartadas. Para cada net, o nome da net baseia-se no método DM_CalculatedNetName da Net, que extrai os nomes das nets da informação de conectividade do projeto compilado.

Dois excertos de código para as secções Componentes e Nets de uma netlist são mostrados abaixo para o formato de netlist Version 1. Note que os dados de componentes e nets são armazenados no objeto NetList, que é do tipo TStringList. A netlist gerada é composta por duas secções: a secção de informação dos componentes e a secção de informação das nets.

Secção de componentes

No procedimento WriteComponent, cada componente encontrado no Projeto é verificado para confirmar se é um componente real e, em seguida, são extraídos os valores do designador físico, footprint e tipo de peça. Estes são adicionados ao contentor do objeto Netlist (NetList.Add) para construir a própria 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;

Secção de nets

Para o procedimento Nets, o NetName e os Designators são extraídos se uma net tiver dois ou mais Pins (INet.DM_PinCount). A informação da net e dos pinos, juntamente com caracteres de formatação, é adicionada ao contentor Netlist para construir a netlist. O excerto abaixo é o procedimento de escrita de nets para a netlist da versão 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;

Note que o formato de netlist mais detalhado, Protel v2, inclui as propriedades elétricas dos pinos das nets (In, Out, Passive, HiZ etc.).

O procedimento de escrita de nets para o formato da versão 2 (WriteNet_Version2) interroga, por isso, a propriedade elétrica de cada pino da net (INet.DM_Electical), que é depois convertida pelo procedimento chamado ConvertElectricToString – essencialmente uma tabela de pesquisa de conversão para string. Estas são depois adicionadas a uma variável local de string (ElectricalString), que por sua vez é adicionada ao objeto contentor Netlist.

Criar ficheiro de netlist

Por fim, com o objeto contentor Netlist totalmente preenchido com a informação de componentes e nets do projeto, no formato escolhido, o procedimento Generate escreve os dados de Netlist para um ficheiro (TStringList.SaveToFile). O caminho e o nome do ficheiro são definidos pela variável de string TargetFileName, conforme determinado no procedimento Generate.