Análisis de ejemplo de script

De un vistazo

Descubre cómo dos scripts de ejemplo utilizan el sistema de scripting de Altium Designer y los modelos de objetos X2 para copiar el contorno de una PCB y generar una lista de conexiones de Protel. Este artículo analiza los controles de formulario, las interfaces de PCB y el flujo de trabajo de creación de objetos del copiador de contornos de placa en VBScript. A continuación, presenta el generador de listas de conexiones en DelphiScript y las interfaces de WorkSpace Manager que utiliza para acceder a los datos del proyecto. Sigue leyendo para comprender mejor cómo funcionan estos ejemplos de scripting.

- Aprende cómo se recrean los segmentos del contorno de la placa como pistas y arcos en una capa seleccionada y con un ancho especificado.
- Comprende cómo se gestionan la creación de objetos de PCB, la sincronización de la función Deshacer, la visibilidad de las capas y la actualización del documento.
- Descubre cómo el generador de listas de conexiones utiliza las interfaces de proyectos, componentes y redes para generar listas de conexiones de Protel versión 1 o versión 2.
Profundiza con IA:
 

Para profundizar en los aspectos generales del sistema de scripting y en el uso de Delphi y los modelos de objetos X2 en los scripts, aquí se examinan dos proyectos de ejemplo desde una perspectiva funcional: un copiador del contorno de la placa y un script de generación de netlists.

Los scripts Board Outline Copier y Netlister se han desarrollado utilizando los modelos de objetos X2 para ilustrar las capacidades del sistema de scripting de Altium Designer. Estos scripts están disponibles en la colección de scripts de ejemplo, como se indica a continuación:

  • El script Board Outline Copier utiliza el modelo de objetos PCB para copiar el contorno existente de la placa PCB como pistas y arcos en una capa especificada.
    Consulte \Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR.
  • El script de generación 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.

En los ejemplos ilustrados se utilizan los lenguajes DelphiScript y VBScript. DelphiScript se basa en Embarcadero Delphi y VBScript se basa en la tecnología de scripting de Microsoft.

► Para obtener información sobre las diferencias entre DelphiScript y Object Pascal (utilizado en Delphi), consulte el documento de referencia de DelphiScript.

► Para obtener más información sobre VBScript, consulte la documentación de Microsoft VBScript .

Proyecto Board Outline Copier

El objetivo de Board Outline Copier es copiar un contorno de placa existente del documento PCB a otra capa del mismo documento.

El proyecto utiliza un formulario de script para que el usuario pueda interactuar con un cuadro de diálogo para especificar el ancho del contorno de la placa y seleccionar su capa de destino en un menú desplegable. Mediante el modelo de objetos PCB y sus interfaces de la API de PCB, se extraen los objetos del contorno de la placa y se copian en la capa especificada.

► Ejemplo de funcionamiento del script

  • Tenga en cuenta que el script Board Outline Copier que se describe aquí está escrito en VBScript, no en DelphiScript.

  • Los proyectos VBScript ahora se consideran heredados. Para habilitar la creación de nuevos proyectos VBScript, marque la opción Legacy.Scripts.SupportOldLanguages en el cuadro de diálogo Advanced Settings.

  • La documentación de la API de scripting se encuentra aquí: Objetos de la API de scripting. Tenga en cuenta que esta documentación se actualizó por última vez para una versión anterior de Altium Designer. Aunque muchos de los principios y enfoques seguirán siendo los mismos, tenga presente que las interfaces, los objetos, los métodos, las propiedades y otros elementos similares han cambiado desde entonces y que la documentación no refleja la totalidad de los que se encuentran en las versiones posteriores del software.

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 formulario de script y, a continuación, ejecuta la subrutina CopyBoardOutline.
  • El controlador de eventos bCancelClick, que cierra el formulario de script Board Outline (cuadro de diálogo).

Funcionalidad del script

El script utiliza un formulario de script que necesita controladores de eventos para capturar los clics del ratón en los distintos controles, como los botones OK y Cancel.

El controlador de eventos del botón OK es, básicamente, el siguiente:

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 de ratón OnClick del formulario (bOKClick) utiliza la función StringToCoordUnit para obtener el ancho introducido del contorno (la cadena eWidth del cuadro TEdit) en valores de coordenadas internas. 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 se rellena previamente con una lista indexada de cadenas de capas (cbLayers.Items); consulte el archivo CopyBoardOutlineForm.dfm del formulario para ver la lista de capas.

La versión DelphiScript del proyecto Board Outline Copier utiliza un procedimiento adicional para extraer la lista de capas disponibles de la placa actual.

El último paso del controlador de eventos (bOKClick) llama a la subrutina CopyBoardOutline con las variables Width y Layer como parámetros. 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 de la interfaz IPCB_Board mediante el IPCB_ServerInterface devuelto por la función especial PCBServer. Aquí, la función GetCurrentPCB asigna la referencia de la placa actual a la variable PCB_Board.

A continuación, el contorno de la placa actual (IPC_BoardOutline) se obtiene a lo largo del script a partir de la propiedad BoardOutline de la interfaz IPCB_Board, utilizando la referencia de placa PCB_Board anterior.

El contorno de la placa debe inicializarse antes de proceder a copiarlo y crear uno nuevo. Un contorno, representado por la interfaz IPCB_BoardOutline, puede inicializarse mediante los métodos de reconstrucción y validación de la interfaz.

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

Tenga en cuenta que acceder a IPCB_ServerInterface, que representa el editor de PCB, mediante la función PCBServer permite acceder a todas las demás interfaces de objetos PCB, como la interfaz IPCB_Board, etc. En este script, se utiliza la variable asignada PCB_Board para obtenerlas.

Segmentos de arco y pista del contorno

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

Un objeto de contorno de placa almacena dos tipos diferentes de segmentos: ePolySegmentLine y ePolySegmentArc, que representan un objeto de pista o de arco, respectivamente. El número de segmentos viene determinado por 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.

Se comprueba si cada segmento del contorno de placa obtenido es una pista o un arco mediante la instrucción If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then. Si no es un segmento de pista (ePolySegmentLine), la parte Else de la instrucción asume que el segmento es un arco.

Para cada segmento encontrado y en función de su tipo, se crea un nuevo objeto de pista o de arco mediante la función PCBObjectFactory.

Función PCBObjectFactory

Para crear los nuevos objetos PCB se utiliza 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 (pista, arco, vía, etc.), el tipo de dimensión (lineal, radial, etc.) y el modo de creación del objeto (según un valor predeterminado local o las preferencias globales).

Después de que el procedimiento PCBObjectFactory cree cada objeto de pista o de arco, sus propiedades se inicializan mediante las instrucciones de pista o arco que aparecen a continuación.

Las propiedades de pista y arco están representadas por sus respectivas interfaces, IPCB_Track y IPCB_Arc, cuyas propiedades pertinentes se implementan en el script. Por ejemplo, las coordenadas de la nueva pista se obtienen a partir de los vértices del segmento del contorno de origen, donde Track.X1 y Track.Y1 representan las coordenadas iniciales de la pista 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 de capa y anchura de la pista se definen simplemente mediante los valores pasados que se extraen del cuadro de diálogo de la interfaz de usuario: las variables cbLayers y eWidth del formulario.

Una vez definidos por completo, los nuevos objetos se añaden a una capa específica del documento de PCB mediante la instrucción PCB_Board.AddPCBObject(NewObject), donde NewObject es, en este caso, Track o Arc.

PreProcess y PostProcess

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

Los métodos PreProcess y PostProcess mantienen actualizados y sincronizados el sistema Deshacer y otros subsistemas del editor de PCB. A continuación se muestra un fragmento de código representativo con las instrucciones PreProcess y PostProcess.

PCBServer.PreProcess
'Create PCB objects
PCBServer.PostProcess

Cuando se añaden objetos a una capa determinada que no se muestra en el documento de PCB, es necesario forzar la visibilidad de dicha capa. Esto se gestiona mediante la instrucción PCB_Board.LayerIsDisplayed(ALayer) = True, donde ALayer es la capa seleccionada por el usuario.

Actualización del documento

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

Proyecto Netlister

El objetivo de este proyecto de script Netlister es generar una lista de conexiones Protel estándar (en formato de la versión 1 o de la versión 2) para un proyecto de Altium Designer que contenga esquemas. Una lista de conexiones plana de un proyecto de esquemas se divide en dos secciones:

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

► Ejemplo de funcionamiento del script

El modelo de objetos de WorkSpace Manager de la API proporciona interfaces que representan el proyecto y sus elementos: los documentos, los componentes y sus pines, y las redes. WorkSpace Manager es un servidor del sistema estrechamente vinculado al módulo Client que gestiona los proyectos y sus documentos asociados. Ofrece compilación, compatibilidad con diseños de varias hojas, herramientas de navegación de conectividad, compatibilidad multicanal, múltiples documentos de implementación, etc. Para obtener 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 interfaces, especialmente las de objetos de diseño, se corresponden con interfaces equivalentes de objetos de esquema. Esto se debe a que los documentos lógicos de un proyecto son documentos de esquema con información de conectividad. De hecho, el modelo de objetos de esquema puede utilizarse en lugar de WorkSpace Manager, pero este último ofrece funciones para compilar un proyecto y extraer documentos de él, además de recuperar datos de los objetos de esquema.

Las partes principales del script Netlister son:

  • Una variable de cadena global TargetFileName, que contiene el nombre de archivo de la lista de conexiones.
  • Un objeto de colección global Netlist TStringList que se rellena con los datos de la lista de conexiones.
  • 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 administración del nombre de archivo, la ruta y el directorio.
El script Netlister está escrito en DelphiScript.

Funcionalidad del script

Los dos procedimientos sin parámetros, GenerateProtelV1FormatNetlist y GenerateProtelV2FormatNetlist, aparecerán en el cuadro de diálogo Seleccionar elemento para ejecutar, donde se podrá elegir entre generar una lista de conexiones en formato Protel V1 o Protel V2. Estos procedimientos llaman al procedimiento GenerateNetlist y le pasan como parámetro la opción de formato de la lista de conexiones (0 o 1).

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 obtiene la interfaz del espacio de trabajo para poder extraer después la interfaz del proyecto actual (IWorkspace.DM_FocusedProject).

El proyecto debe compilarse antes de poder extraer las redes, ya que el proceso de compilación genera 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 los componentes y las redes se almacena en el objeto Netlist de tipo TStringList, que se utiliza posteriormente para generar un archivo de texto de lista de conexiones con formato. El objeto TStringList es una clase de Delphi que puede utilizarse en los scripts.

A continuación se llama al procedimiento Generate con parámetros que definen la ruta y el nombre de archivo del proyecto actual, así como la versión del formato de la lista de conexiones.

Generate

El procedimiento Generate obtiene la ruta del proyecto como ruta de salida de destino para el archivo de lista de conexiones generado (a partir del parámetro DocumentPath recibido), determina el nombre de archivo de la lista de conexiones (TargetFileName) y comprueba si el proyecto se ha aplanado (IProject.DM_DocumentFlattened).

A continuación, se comprueban las redes y los componentes de cada documento de esquema del proyecto mediante los procedimientos WriteNets y WriteComponents, y finalmente se extraen al objeto Netlist.

Escritura de redes y componentes

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

Solo se escribirán en la lista de conexiones las redes con más de dos nodos; las que tengan menos se descartarán. Para cada red, el nombre se basa en el método DM_CalculatedNetName de la red, que extrae los nombres de las redes 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 lista de conexiones en formato de la versión 1. Tenga en cuenta que los datos de los componentes y las redes se almacenan en el objeto NetList, que es de tipo TStringList. La lista de conexiones generada se compone de dos secciones: la de información de componentes y la 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 pieza. Estos se añaden al objeto contenedor Netlist (NetList.Add) para construir la propia lista de conexiones.

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

En el procedimiento de redes, se extraen NetName y los designadores si una red tiene dos o más pines (INet.DM_PinCount). La información de las redes y los pines, junto con los caracteres de formato, se añade al contenedor Netlist para construir la lista de conexiones. El siguiente fragmento corresponde al procedimiento de escritura de redes para la lista de conexiones de la 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 lista de conexiones más detallado, Protel v2, incluye las propiedades eléctricas de los pines de las redes (In, Out, Passive, HiZ, etc.).

Por tanto, el procedimiento de escritura de redes para el formato de la versión 2 (WriteNet_Version2) consulta la propiedad eléctrica de cada pin de la red (INet.DM_Electical), que luego se convierte mediante el procedimiento ConvertElectricToString invocado, que es básicamente una tabla de consulta para la conversión de cadenas. Los valores resultantes se añaden a una variable de cadena local (ElectricalString), que a su vez se añade al objeto contenedor de la lista de conexiones.

Crear el archivo de lista de conexiones

Por último, una vez que el objeto contenedor Netlist contiene toda la información de los componentes y las 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 se definen mediante la variable de cadena TargetFileName, según lo determinado en el procedimiento Generate.

AI-LocalizedLocalizado por IA
Si encuentra un problema, seleccione el texto/imagen y presioneCtrl + Enterpara enviarnos sus comentarios.
Nav
Contents
Disponibilidad de funciones

Las funciones disponibles para usted dependen de qué solución de Altium tenga: Altium Develop, Altium Agile Teams, Altium Agile Enterprise o Altium Designer (con suscripción activa).

Si no ve una función documentada en su software actual, contacte con Ventas de Altium para obtener más información.

Documentación heredada

La documentación de Altium Designer ya no está versionada. Si necesita acceder a la documentación de versiones anteriores de Altium Designer, visite la sección Documentación heredada de la página de Otros instaladores.

Contents