Script Example Analysis

Pour mieux comprendre les aspects généraux du système de scripts, ainsi que l’utilisation de Delphi et des modèles d’objet X2 dans les scripts, deux projets d’exemple sont examinés ici du point de vue fonctionnel : un copieur de contour de carte et un script de génération de netlist.

Les scripts Board Outline Copier et Netlister sont développés à l’aide des modèles d’objet X2 afin d’illustrer les capacités du système de scripts dans Altium Designer. Il s’agit de scripts existants disponibles dans la collection d’exemples de scripts, comme suit :

• Le script Board Outline Copier utilise le modèle d’objet PCB pour copier le contour existant de la carte PCB sous forme de pistes et d’arcs sur une couche spécifiée.
  Voir \Scripts\VB Scripts\CopyBoardOutlinePRJ.PRJSCR.
• Le script de génération de netlist utilise le modèle d’objet WorkSpace Manager pour générer une netlist au format Protel traditionnel (v1 et v2).
  Voir \Scripts\Delphiscript Scripts\WSM\Protel Netlister\ScripterProtelNetlist.PRJSCR.

Projet Board Outline Copier

L’objectif de Board Outline Copier est de copier un contour de carte existant depuis le document PCB vers une autre couche du même document.

Le projet utilise un formulaire de script afin que l’utilisateur puisse interagir avec une boîte de dialogue pour définir la largeur du contour de carte et sélectionner sa couche cible dans un menu déroulant. En utilisant le modèle d’objet PCB et ses interfaces PCB issues de l’API PCB, les objets du contour de carte sont extraits puis copiés sur la couche spécifiée.

► Exemple de fonctionnement du script

Les principales parties du script sont :

• Une variable globale PCB_Board (de type IPCB_Board).
• Une sous-routine CopyBoardOutline qui accepte les paramètres AWidth et ALayer.
• Le gestionnaire d’événement bOkClick, qui récupère les valeurs de largeur et de couche depuis le formulaire du script, puis exécute la sous-routine CopyBoardOutline.
• Le gestionnaire d’événement bCancelClick, qui ferme le formulaire (boîte de dialogue) du script Board Outline.

Fonctionnement du script

Le script utilise un formulaire qui nécessite des gestionnaires d’événements pour capturer les clics de souris sur les différents contrôles, tels que les boutons OK et Cancel.

Le gestionnaire d’événement du bouton OK est essentiellement le suivant :

Sub bOKClick(Sender)
  Dim Width
  Dim Layer

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

Ici, le gestionnaire d’événement OnClick de la souris du formulaire (bOKClick) utilise la fonction StringToCoordUnit pour obtenir la largeur saisie du contour (la chaîne eWidth de la zone TEdit) en valeurs de coordonnées internes. Cette fonction applique les unités actuelles de la carte (propriété PCB_Board.DisplayUnit) à la variable Width.

De même, la chaîne de couche sélectionnée (l’élément cbLayers de la TComboBox du formulaire) est transmise à la fonction String2Layer afin d’obtenir une valeur énumérée pour la variable Layer. Notez que, dans ce projet, la TComboBox du formulaire est préremplie avec une liste indexée de chaînes de couches (cbLayers.Items) – voir le fichier CopyBoardOutlineForm.dfm du formulaire pour la liste des couches.

L’étape finale du gestionnaire d’événement (bOKClick) appelle ensuite la sous-routine CopyBoardOutline avec les variables Width et Layer comme paramètres transmis. Le gestionnaire du bouton Cancel du formulaire (bCancelClick) ferme simplement le formulaire.

Interface IPCB_Board

Dans le gestionnaire du bouton OK (bOKClick), la carte courante est obtenue à partir de l’interface IPCB_Board via le IPCB_ServerInterface renvoyé par la fonction spéciale PCBServer. Ici, la fonction GetCurrentPCB affecte la référence de la carte courante à la variable PCB_Board.

Le contour de carte courant (IPC_BoardOutline) est ensuite obtenu tout au long du script à partir de la propriété BoardOutline de l’interface IPCB_Board, en utilisant la référence de carte PCB_Board ci-dessus.

Le contour de carte doit être initialisé avant de poursuivre la copie et la création d’un nouveau contour. Un contour – représenté par l’interface IPCB_BoardOutline – peut être initialisé à l’aide des méthodes de reconstruction/validation de cette interface.

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

Segments d’arc et de piste du contour

L’interface IPCB_BoardOutline, qui représente le contour de carte, hérite de l’interface IPCB_Group. Une interface IPCB_Group représente un objet de groupe pouvant stocker des objets enfants. Un exemple d’interface IPCB_Group est un polygone ou un contour de carte, puisqu’ils peuvent stocker des arcs et des pistes comme objets enfants.

Un objet contour de carte stocke deux types différents de segments – ePolySegmentLine et ePolySegmentArc – qui représentent respectivement un objet piste ou un objet arc. Le nombre de segments est déterminé par la propriété PointCount de l’interface IPCB_BoardOutline, qui extrait chaque sommet du contour dans la variable I pour la boucle For-To-Next.

Chaque segment du contour de carte obtenu est vérifié pour détecter les pistes et les arcs à l’aide de l’instruction If PCB_Board.BoardOutline.Segments(I).Kind = ePolySegmentLine Then. S’il ne s’agit pas d’un segment de piste (ePolySegmentLine), la partie Else de l’instruction suppose que le segment est un arc.

Pour chaque segment trouvé et selon son type, un nouvel objet piste ou arc est créé à l’aide de la fonction PCBObjectFactory.

Fonction PCBObjectFactory

La création des nouveaux objets PCB utilise directement la fonction PCBObjectFactory depuis l’interface IPCB_ServerInterface.

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

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

Les paramètres de la fonction PCBObjectFactory définissent le type d’objet (Track, Arc, Via, etc.), le type de dimension (Linear, Radial, etc.) et le mode de création de l’objet (selon une valeur locale par défaut ou les préférences globales).

Après la création de chaque objet piste ou arc par la procédure PCBObjectFactory, ses propriétés sont instanciées par les instructions de piste/arc qui suivent.

Les propriétés Track et Arc sont représentées par leurs interfaces respectives, IPCB_Track et IPCB_Arc, où les propriétés pertinentes sont implémentées par le script. Par exemple, les coordonnées de la nouvelle piste sont obtenues à partir des sommets du segment du contour source, où Track.X1 et Track.Y1 représentent les coordonnées initiales de la piste, et les propriétés X2 et Y2 ses coordonnées 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

Comme on peut également le voir dans l’extrait de code ci-dessus, les propriétés Layer et Width de la piste sont simplement définies par les valeurs transmises extraites de la boîte de dialogue de l’interface utilisateur – les variables cbLayers et eWidth du formulaire.

Une fois entièrement définis, les nouveaux objets sont ajoutés à une couche spécifiée du document PCB avec l’instruction PCB_Board.AddPCBObject(NewObject), où NewObject correspond ici à Track ou Arc.

PreProcess et PostProcess

Lors de la création d’un objet PCB, la méthode PreProcess de l’interface objet IPCB_ServerInterface doit d’abord être invoquée pour préparer le serveur PCB. Après la création de l’objet, la méthode PostPocess (également issue de l’interface IPCB_ServerInterface) est appliquée pour informer le serveur que les ajouts d’objets sont terminés.

Les méthodes PreProcess et PostProcess maintiennent le système d’annulation et les autres sous-systèmes de l’éditeur PCB à jour et synchronisés. Voici ci-dessous un extrait de code représentatif avec les instructions PreProcess et PostProcess.

PCBServer.PreProcess
'Create PCB objects
PCBServer.PostProcess

Lorsque des objets sont ajoutés à une couche désignée qui n’était pas affichée dans le document PCB, il faut forcer la couche à devenir visible. Cela est géré par l’instruction PCB_Board.LayerIsDisplayed(ALayer) = True, où ALayer est la couche sélectionnée par l’utilisateur.

Actualisation du document

Enfin, le document PCB avec son nouveau contour de carte est actualisé par la commande PCB:Zoom et ses paramètres Action = Redraw associés. Les paramètres de la commande de zoom sont appliqués à l’aide de la procédure AddStringParameter après que le tampon de paramètres a d’abord été effacé avec la méthode ResetParameters.

Projet Netlister

L’objectif de ce projet de script Netlister est de générer une netlist Protel standard (au format Version 1 ou Version 2) pour un projet Altium Designer contenant des schémas. Une netlist à plat d’un projet schématique est divisée en deux sections :

• Les désignateurs de composants et les informations associées à chaque composant,
• Les noms de nets et les informations associées à chaque nom de net, ainsi que les connexions de broches (broches d’un composant).

► Exemple de fonctionnement du script

Le modèle objet API du gestionnaire WorkSpace fournit des interfaces qui représentent le projet et ses constituants : les documents, les composants et leurs broches, ainsi que les nets. Le gestionnaire WorkSpace est un serveur système étroitement couplé au module Client qui gère les projets et leurs documents associés. Il fournit la compilation, la prise en charge des conceptions multi-feuilles, les outils de navigation de connectivité, la prise en charge multi-canaux, plusieurs documents d’implémentation, etc. Pour récupérer l’interface du gestionnaire WorkSpace, appelez la fonction GetWorkspace, qui renvoie l’interface IWorkspace.

Pour le script Netlister, les interfaces qui nous intéressent sont les interfaces IWorkSpace, IProject, IDocument, IComponent et INet.

Notez que certaines interfaces, en particulier les interfaces d’objets de conception, correspondent à des interfaces d’objets schématiques équivalentes. Cela s’explique par le fait que les documents logiques d’un projet sont des documents schématiques contenant des informations de connectivité. En fait, le modèle d’objet schématique peut être utilisé à la place du gestionnaire WorkSpace, mais ce dernier fournit la fonctionnalité permettant de compiler un projet et d’en extraire des documents, ainsi que de récupérer des données à partir d’objets schématiques.

Les principales parties du script Netlister sont :

• Une variable chaîne globale TargetFileName, qui correspond au nom de fichier de la netlist.
• Un objet de collection global Netlist TStringList, qui est rempli avec les données de la netlist.
• Les procédures WriteComponent_Version1 et WriteComponent_Version2.
• Les procédures WriteNet_Version1 et WriteNet_Version2.
• Une fonction ConvertElectricToString qui convertit la propriété électrique d’une broche en chaîne
• La procédure GenerateNetlist qui gère la génération des données ainsi que les tâches de gestion du nom de fichier, du chemin et du répertoire.

Fonctionnalité du script

Les deux procédures sans paramètre, GenerateProtelV1FormatNetlist et GenerateProtelV2FormatNetlist, apparaîtront dans la boîte de dialogue Select Item to Run dialog, offrant le choix de générer une netlist au format Protel V1 ou au format Protel V2. Ces procédures appellent la procédure GenerateNetlist avec le choix du format de netlist (0 ou 1) passé en paramètre.

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

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

GenerateNetList

La procédure GenerateNetList récupère l’interface workspace afin que l’interface du projet puisse ensuite être extraite pour le projet courant (IWorkspace.DM_FocusedProject).

Le projet doit être compilé avant que les nets puissent être extraits, car le processus de compilation construit les informations de connectivité du projet. La méthode DM_Compile de l’interface du projet est appliquée (IProject.DM_Compile), comme indiqué dans l’extrait de code ci-dessous. Notez que les versions récentes d’Altium Designer compilent automatiquement les projets ; cette étape est donc facultative.

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

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

// Compiler le projet pour récupérer les informations de connectivité de la conception.
 Prj.DM_Compile;

Les informations sur les composants et les nets sont stockées dans l’objet Netlist de type TStringList, qui est utilisé ultérieurement pour générer un fichier texte de netlist formaté. L’objet TStringList est une classe Delphi disponible pour une utilisation dans les scripts.

La procédure Generate est ensuite appelée avec des paramètres transmis qui définissent le chemin et le nom de fichier du projet courant, ainsi que la version du format de netlist.

Generate

La procédure Generate obtient le chemin du projet comme chemin de sortie cible pour le fichier de netlist généré (à partir du paramètre DocumentPath transmis), détermine le nom du fichier de netlist (TargetFileName) et vérifie l’état aplati du projet (IProject.DM_DocumentFlattened).

Pour tous les documents schématiques d’un projet, chaque document est ensuite vérifié pour les nets et les composants à l’aide des procédures WriteNets et WriteComponents, puis finalement extrait vers l’objet Netlist.

Écriture des nets et des composants

Une netlist est composée de sections composants et nets ; deux procédures sont donc nécessaires pour écrire séparément les données des composants et celles des nets.

Seuls les nets comportant plus de deux nœuds seront écrits dans une netlist ; ceux qui en comportent moins sont ignorés. Pour chaque net, le nom du net est basé sur la méthode DM_CalculatedNetName du Net, qui extrait les noms de nets à partir des informations de connectivité du projet compilé.

Deux extraits de code pour les sections Components et Nets d’une netlist sont présentés ci-dessous pour le format de netlist Version 1. Notez que les données des composants et des nets sont stockées dans l’objet NetList, qui est de type TStringList. La netlist générée est composée de deux sections : la section d’informations sur les composants et la section d’informations sur les nets.

Section Components

Dans la procédure WriteComponent, chaque composant trouvé dans le projet est vérifié pour déterminer s’il s’agit d’un composant réel, puis les valeurs du désignateur physique, de l’empreinte et du type de pièce sont extraites. Elles sont ajoutées au conteneur d’objet Netlist (NetList.Add) pour construire la netlist elle-même.

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;

Section Nets

Pour la procédure Nets, le NetName et les Designators sont extraits si un net possède deux broches ou plus (INet.DM_PinCount). Les informations sur le net et les broches, ainsi que les caractères de formatage, sont ajoutés au conteneur Netlist pour construire la netlist. L’extrait ci-dessous montre la procédure d’écriture des nets pour la 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;

Notez que le format de netlist plus détaillé, Protel v2, inclut les propriétés électriques des broches de net (In, Out, Passive, HiZ, etc.).

La procédure d’écriture des nets pour le format version 2 (WriteNet_Version2) interroge donc la propriété électrique de chaque broche de net (INet.DM_Electical), qui est ensuite convertie par la procédure appelée ConvertElectricToString — essentiellement une table de correspondance de conversion en chaîne. Celles-ci sont ensuite ajoutées à une variable chaîne locale (ElectricalString), qui est à son tour ajoutée à l’objet conteneur Netlist.

Création du fichier de netlist

Enfin, lorsque l’objet conteneur Netlist est entièrement rempli avec les informations sur les composants et les nets du projet, dans le format choisi, la procédure Generate écrit les données Netlist dans un fichier (TStringList.SaveToFile). Le chemin et le nom du fichier sont définis par la variable chaîne TargetFileName, comme déterminé dans la procédure Generate.