Análisis de ejemplo de script

Para ofrecer una visión más profunda de los aspectos generales del sistema de scripts, y del uso de los modelos de objetos Delphi y X2 en scripts, aquí se analizan dos proyectos de ejemplo desde una perspectiva funcional: un copiador del contorno de la placa y un script generador de netlists.

Los scripts Board Outline Copier y Netlister se desarrollaron utilizando los modelos de objetos X2 para ilustrar las capacidades del sistema de scripts en Altium Designer. Estos son scripts existentes disponibles en la colección de scripts de ejemplo, como sigue:

• El script Board Outline Copier utiliza el modelo de objetos PCB para copiar el contorno existente de la placa PCB como tracks y arcs en una capa especificada.
  Consulte \Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR.
• El script generador de netlists utiliza el modelo de objetos WorkSpace Manager para generar una netlist en el formato tradicional de Protel (v1 y v2).
  Consulte \Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCR.

Proyecto Board Outline Copier

El objetivo de Board Outline Copier es copiar un contorno de placa existente desde el documento PCB a una capa diferente dentro del mismo documento.

El proyecto usa un Script Form para que el usuario pueda interactuar con un cuadro de diálogo y especificar el ancho del contorno de la placa, además de seleccionar su capa de destino desde un menú desplegable. Usando el modelo de objetos PCB y sus interfaces PCB desde la PCB API, los objetos del contorno de la placa se extraen y se copian a la capa especificada.

► Ejemplo de funcionamiento del script

Las partes principales del script son:

• Una variable global PCB_Board (de tipo IPCB_Board).
• Una subrutina CopyBoardOutline que acepta los parámetros AWidth y ALayer.
• El controlador de eventos bOkClick, que obtiene los valores de ancho y capa del script form y luego ejecuta la subrutina CopyBoardOutline.
• El controlador de eventos bCancelClick, que cierra el script form (cuadro de diálogo) de Board Outline.

Funcionalidad del script

El script utiliza un script Form que necesita controladores de eventos para capturar los clics del mouse en controles individuales, como los botones OK y Cancel.

El controlador de eventos del botón OK es esencialmente como se muestra a continuación:

Sub bOKClick(Sender)
  Dim Width
  Dim Layer

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

Aquí, el controlador del evento OnClick del mouse del formulario (bOKClick) utiliza la función StringToCoordUnit para obtener el ancho introducido del contorno (la cadena eWidth del cuadro TEdit) en valores internos de coordenadas. Esta función aplica las unidades actuales de la placa (propiedad PCB_Board.DisplayUnit) a la variable Width.

De forma similar, la cadena de la capa seleccionada (el elemento cbLayers del TComboBox del formulario) se pasa a la función String2Layer para obtener un valor enumerado para la variable Layer. Tenga en cuenta que en este proyecto el TComboBox del formulario está rellenado previamente con una lista indexada de cadenas de capas (cbLayers.Items); consulte el archivo CopyBoardOutlineForm.dfm del formulario para ver la lista de capas.

El paso final en el controlador de eventos (bOKClick) llama a la subrutina CopyBoardOutline con las variables Width y Layer como parámetros pasados. El controlador del botón Cancel del formulario (bCancelClick) simplemente cierra el formulario.

Interfaz IPCB_Board

Dentro del controlador del botón OK (bOKClick), la placa actual se obtiene desde la interfaz IPCB_Board a través de IPCB_ServerInterface, devuelto por la función especial PCBServer. Aquí, la función GetCurrentPCB establece la referencia de la placa actual en la variable PCB_Board.

El contorno actual de la placa (IPC_BoardOutline) se obtiene luego a lo largo del script desde la propiedad BoardOutline de la interfaz IPCB_Board, usando la referencia de placa PCB_Board indicada arriba.

El contorno de la placa debe inicializarse antes de continuar con la copia y la creación de un nuevo contorno. Un contorno, representado por la interfaz IPCB_BoardOutline, puede inicializarse usando los métodos de reconstrucción/validación de la interfaz.

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

Segmentos de arco y track del contorno

La interfaz IPCB_BoardOutline, que representa el contorno de la placa, se hereda de la interfaz IPCB_Group. Una interfaz IPCB_Group representa un objeto de grupo que puede almacenar objetos hijos. Un ejemplo de una interfaz IPCB_Group es un polígono o un contorno de placa, ya que estos pueden almacenar arcs y tracks como objetos hijos.

Un objeto de contorno de placa almacena dos tipos diferentes de segmentos: ePolySegmentLine y ePolySegmentArc, que representan respectivamente un objeto track o arc. El número de segmentos se determina mediante la propiedad PointCount de la interfaz IPCB_BoardOutline, que extrae cada vértice del contorno a la variable I para el bucle For-To-Next.

Cada segmento del contorno de placa obtenido se comprueba para tracks y arcs con la sentencia If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then. Si no es un segmento de track (ePolySegmentLine), la parte Else de la sentencia asume que el segmento es un arco.

Para cada segmento encontrado y según el tipo de segmento, se crea un nuevo objeto track o arc usando la función PCBObjectFactory.

Función PCBObjectFactory

La creación de los nuevos objetos PCB emplea la función PCBObjectFactory directamente desde la interfaz IPCB_ServerInterface.

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

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

Los parámetros de la función PCBObjectFactory establecen el tipo de objeto (Track, Arc, Via, etc.), el tipo de dimensión (Linear, Radial, etc.) y el modo de creación del objeto (a un valor predeterminado local o a preferencias globales).

Después de que cada objeto track o arc es creado por el procedimiento PCBObjectFactory, sus propiedades se instancian mediante las sentencias track/arc que siguen.

Las propiedades de Track y Arc están representadas por sus respectivas interfaces, IPCB_Track y IPCB_Arc, donde las propiedades relevantes son implementadas por el script. Por ejemplo, las nuevas coordenadas del track se obtienen de los vértices del segmento del contorno de origen, donde Track.X1 y Track.Y1 representan las coordenadas iniciales del track, y las propiedades X2 y Y2 son sus coordenadas finales.

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 también puede verse en el fragmento de código anterior, las propiedades Layer y Width del track simplemente se definen mediante los valores pasados extraídos del cuadro de diálogo de la interfaz de usuario: las variables cbLayers y eWidth del Form.

Una vez definidos por completo, los nuevos objetos se agregan a una capa especificada del documento PCB con la sentencia PCB_Board.AddPCBObject(NewObject), donde aquí NewObject es Track o Arc.

PreProcess y PostProcess

Al crear un objeto PCB, primero debe invocarse el método PreProcess de la interfaz de objeto IPCB_ServerInterface para preparar el servidor PCB. Después de la creación del objeto, se aplica el método PostPocess (también de la interfaz IPCB_ServerInterface) para informar al servidor de que las adiciones de objetos se han completado.

Los métodos PreProcess y PostProcess mantienen actualizado y sincronizado el sistema Undo y otros subsistemas del editor PCB. A continuación se muestra un fragmento representativo de código con las sentencias PreProcess y PostProcess.

PCBServer.PreProcess
'Create PCB objects
PCBServer.PostProcess

Cuando se agregan objetos a una capa designada que no se ha mostrado en el documento PCB, es necesario forzar la visibilidad de la capa. Esto se maneja mediante la sentencia PCB_Board.LayerIsDisplayed(ALayer) = True, donde ALayer es la capa seleccionada por el usuario.

Actualización del documento

Por último, el documento PCB con su nuevo contorno de placa se actualiza mediante el comando PCB:Zoom y sus parámetros asociados Action = Redraw. Los parámetros del comando de zoom se aplican usando el procedimiento AddStringParameter después de que el búfer de parámetros se haya limpiado primero con el método ResetParameters.

Proyecto Netlister

El objetivo de este proyecto de script Netlister es generar una netlist Protel estándar (en formato Versión 1 o Versión 2) para un proyecto de Altium Designer que contenga esquemáticos. Una netlist plana de un proyecto esquemático se divide en dos secciones:

• Los designadores de componentes y la información asociada con cada componente,
• Los nombres de red y la información asociada con cada nombre de red, junto con las conexiones de pines (pines de un componente).

► Ejemplo de funcionamiento del script

El modelo de objetos WorkSpace Manager de la API proporciona interfaces que representan el proyecto y sus elementos constituyentes: los documentos, los componentes y sus pines, y las redes. El WorkSpace Manager es un servidor del sistema estrechamente acoplado con el módulo Client que gestiona los proyectos y sus documentos asociados. Proporciona compilación, soporte de diseño multihoja, herramientas de navegación de conectividad, soporte multicanal, múltiples documentos de implementación, entre otras funciones. Para recuperar la interfaz de WorkSpace Manager, invoque la función GetWorkspace, que devuelve la interfaz IWorkspace.

Para el script Netlister, las interfaces de interés son IWorkSpace, IProject, IDocument, IComponent y INet.

Tenga en cuenta que algunas de las interfaces, especialmente las interfaces de objetos de diseño, corresponden a interfaces equivalentes de objetos esquemáticos. Esto se debe a que los documentos lógicos de un proyecto son documentos esquemáticos con información de conectividad. De hecho, el modelo de objetos esquemáticos puede utilizarse en lugar de WorkSpace Manager, pero este último proporciona la funcionalidad para compilar un proyecto y extraer documentos de un proyecto, así como recuperar datos de objetos esquemáticos.

Las partes principales del script Netlister son:

• Una variable global de tipo cadena TargetFileName, que es el nombre de archivo de la netlist.
• Un objeto de colección global Netlist TStringList, que se rellena con los datos de la netlist.
• Los procedimientos WriteComponent_Version1 y WriteComponent_Version2.
• Los procedimientos WriteNet_Version1 y WriteNet_Version2.
• Una función ConvertElectricToString que convierte la propiedad eléctrica de un pin en una cadena
• El procedimiento GenerateNetlist, que gestiona la generación de datos y las tareas de mantenimiento del nombre de archivo, la ruta y el directorio.

Funcionalidad del script

Los dos procedimientos sin parámetros, GenerateProtelV1FormatNetlist y GenerateProtelV2FormatNetlist, aparecerán en el cuadro de diálogo Select Item to Run dialog, ofreciendo la opción de generar una netlist en formato Protel V1 o en formato Protel V2. Estos procedimientos llaman al procedimiento GenerateNetlist con la selección del formato de netlist (0 o 1) como parámetro pasado.

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

El procedimiento GenerateNetList recupera la interfaz del espacio de trabajo para que luego pueda extraerse la interfaz del proyecto para el proyecto actual (IWorkspace.DM_FocusedProject).

El proyecto debe compilarse antes de que puedan extraerse las redes, ya que el proceso de compilación construye la información de conectividad del proyecto. Se aplica el método DM_Compile de la interfaz del proyecto (IProject.DM_Compile), como se muestra en el siguiente fragmento de código. Tenga en cuenta que las versiones recientes de Altium Designer compilan los proyectos automáticamente, por lo que este paso es opcional.

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;

La información de componentes y redes se almacena en el objeto Netlist del tipo TStringList, que se utiliza más adelante para generar un archivo de texto de netlist con formato. El objeto TStringList es una clase Delphi que está disponible para usarse en scripts.

A continuación, se llama al procedimiento Generate con parámetros pasados que definen la ruta y el nombre de archivo del proyecto actual, además de la versión del formato de netlist.

Generate

El procedimiento Generate obtiene la ruta del proyecto como la ruta de salida de destino para el archivo de netlist generado (a partir del parámetro pasado DocumentPath), determina el nombre del archivo de netlist (TargetFileName) y verifica el estado aplanado del proyecto (IProject.DM_DocumentFlattened).

Para todos los documentos esquemáticos de un proyecto, cada documento se comprueba luego en busca de redes y componentes mediante los procedimientos WriteNets y WriteComponents, y finalmente se extrae al objeto Netlist.

Escribir redes y componentes

Una netlist se compone de secciones de componentes y de redes, por lo que se requieren dos procedimientos para escribir por separado los datos de los componentes y los datos de las redes.

Solo se escribirán en una netlist las redes con más de dos nodos, y aquellas con menos se descartan. Para cada red, el nombre de la red se basa en el método DM_CalculatedNetName de Net, que extrae los nombres de red a partir de la información de conectividad del proyecto compilado.

A continuación se muestran dos fragmentos de código para las secciones de Componentes y Redes de una netlist en formato de netlist Versión 1. Tenga en cuenta que los datos de componentes y redes se almacenan en el objeto NetList, que es de tipo TStringList. La netlist generada se compone de dos secciones: la sección de información de componentes y la sección de información de redes.

Sección de componentes

En el procedimiento WriteComponent, se comprueba si cada componente encontrado en el proyecto es un componente real y, a continuación, se extraen los valores del designador físico, la huella y el tipo de parte. Estos se agregan al contenedor del objeto Netlist (NetList.Add) para construir la netlist propiamente dicha.

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;

Sección de redes

Para el procedimiento Nets, se extraen NetName y los designadores si una red tiene dos o más pines (INet.DM_PinCount). La información de la red y de los pines, junto con los caracteres de formato, se agrega al contenedor Netlist para construir la netlist. El siguiente fragmento es el procedimiento de escritura de redes para la netlist de versió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;

Tenga en cuenta que el formato de netlist más detallado, Protel v2, incluye las propiedades eléctricas de los pines de red (In, Out, Passive, HiZ, etc.).

El procedimiento de escritura de redes para el formato de versión 2 (WriteNet_Version2) interroga, por lo tanto, la propiedad eléctrica de cada pin de red (INet.DM_Electical), que luego es convertida por el procedimiento llamado ConvertElectricToString; esencialmente una tabla de búsqueda de conversión a cadena. Luego, estos valores se agregan a una variable local de cadena (ElectricalString), que a su vez se agrega al objeto contenedor Netlist.

Crear archivo de netlist

Por último, con el objeto contenedor Netlist completamente rellenado con la información de componentes y redes del proyecto, en el formato elegido, el procedimiento Generate escribe los datos de Netlist en un archivo (TStringList.SaveToFile). La ruta y el nombre del archivo están definidos por la variable de cadena TargetFileName, tal como se determina en el procedimiento Generate.