Custom Instrument Reference - Altiumvalhalla.altium.com/Learning-Guides/TR0176 Custom Instrument Ref… · configuration file, simply click on the Load From Existing button and use

Custom Instrument Reference

Version (v1.1) Aug 19, 2008 1

The CUSTOM_INSTRUMENT component is a fully-customizable 'virtual' instrument with which to monitor and control signals within an FPGA design.

As part of the instrument's configuration you are able to create your own GUI – the interface that is seen once the design is programmed into the target device and the instrument is accessed. A palette of standard components and instrument controls enable you to quickly construct the instrument panel, while various properties associated with a control allow you to make fine-tuning adjustments.

Defined IO signals, wired to the instrument on the schematic, can be hooked up directly to the various controls in your custom GUI, or you can write your own DelphiScript code to

process IO as required. Scripts can be fired whenever the instrument polls, and in relation to specified events.

One of the key features of this particular virtual instrument is that its configuration can be downloaded with the FPGA design and stored within the target physical device (in Block RAM). This allows for interaction with the design, through use of the Custom Instrument, directly in the field – particularly attractive to Field Service Engineers!

For a tutorial that looks at using the Custom Instrument in an FPGA design, involving monitoring of input signals directly and control of output signals using scripting, refer to the document TU0135 Adding Custom Instrumentation to an FPGA Design.

Placing a Custom Instrument

As with all 'virtual' instruments, the Custom Instrument component resides in the FPGA Instruments integrated library (FPGA Instruments.IntLib). This library is located in the \Libraries\Fpga folder of your Altium Designer installation.

Placement can be made directly from the Libraries panel. With the library active, simply click on the entry for the component and then click on the Place CUSTOM_INSTRUMENT button. Alternatively, click and drag an instance of the instrument directly onto the sheet.

For more information on placing and editing components on a schematic sheet, refer to the Part section in the document TR0111 Schematic Editor and Object Reference.

Figure 1. Place a Custom Instrument directly from the Libraries panel.

Summary This document provides detailed reference information with respect to configuration and use of the Custom Instrument component.

TR0176 Custom Instrument Reference

Version (v1.1) Aug 19, 2008 2

Configuring a Custom Instrument

Configuration of a Custom Instrument component is performed using the Custom Instrument Configuration dialog (Figure 2). Access this dialog by right-clicking over the component and choosing the Configure command from the menu that appears.

Figure 2. Configuration dialog for the Custom Instrument component.

Configuration of the instrument is performed over three distinct tabs of the dialog: • Signals – used to define base instrument options, including specification of the configuration file and how it is retrieved by

Altium Designer. • Design – used to create the customized GUI with which to interact with the instrument at run-time.

• Code – used to write any underlying script code used, for example, in the processing of instrument IO.

The following sections take a closer look at what each of these three tabs has to offer.

Signals tab

This tab of the dialog is divided into the following five regions.

Instrument Options This region of the tab allows you to define some basic options for the Custom Instrument: • Title – this is the caption used at the bottom-right of the instrument's panel, when accessed at run-time. This allows you to

give the panel a meaningful name, which would typically reflect the role of the instrument.

Figure 3. Customize the title for the instrument as required.


Version (v1.1) Aug 19, 2008 3

Use of the Synchronize button is only logical if the Options button is also present and the Update value in the Custom Instrument – Options dialog is set to either 0ms, or some longer time interval (e.g. 2000ms or more). If the Options button is not present, the IO values are automatically (and by default) refreshed every 250ms – too quick to make use of the Synchronize button!

• Show Options Button – enable this option to include an button at the bottom-left of the instrument's panel. When present, it provides access to the Custom Instrument – Options dialog. Input values to, and output values from, the Custom Instrument, are refreshed (updated) in accordance with the value specified in the Update Display From Core Every field of this dialog. In other words, this is the defined polling interval. By default, the values will be refreshed every 250ms.

• Show Synchronize Button - enable this option to include a button at the bottom-left of the instrument's panel. When present, it provides the ability to manually refresh the IO values to/from the Custom Instrument – manual polling if you will.

• Use Custom Bitmap – use this option to determine the icon that will be used to represent the Custom Instrument, in the Soft Devices JTAG chain of the Devices view. With this option disabled, the Custom_Instrument.bmp image file will be used, which is located in the \Library\Device Images folder of the installation. To use your own, customized image, simply enable the option and click the Select Bitmap button. Use the subsequent dialog that appears to locate and open the required image file. When creating a customized bitmap it is important to keep in mind that the Devices view will only display an image that is 80x70 pixels in size. Larger than this and it will be cropped, smaller and it will be centered within these bounds accordingly.

Figure 4. Customize the presentation of the instrument in the Devices view.

Interface Use this region of the tab to define all IO for the instrument – the input signals to be monitored and output signals to be generated. Default signals are added in the form AIN[7..0], BIN[7..0], AOUT[7..0], BOUT[7..0], and so on. Click on, and edit, an entry as required. Give the signals meaningful names to reflect what is being monitored and/or controlled.

Use the controls available directly under a signal list to add ( ), remove ( ) or re-order ( and ) signals as required. The latter allows you to change the order of the signals with respect to the instrument's schematic symbol. For output signals, you can also set an initial value, using the associated Initial value (hex) field. By default this will be zero.


Version (v1.1) Aug 19, 2008 4

If saving to a directory on the same root drive, the Configuration File Name field will initially show the full path. The next time the dialog is accessed, this entry will be a relative path – in relation to the parent FPGA project.

If you intend to provide access to the Custom Instrument using the Viewer Edition of Altium Designer, the From FPGA method of retrieval must be used.

It is possible to have multiple Custom Instrument components in the same design, all sharing a single .Instrument file. The configuration would be defined for one and the resulting configuration file loaded by all others. Editing one will therefore affect all.

Figure 5. Example interface definition for a Custom Instrument.

Schematic Depending on the naming used for input and output signals, the default width of the symbol used for the instrument on the schematic sheet may be too small, resulting in overlapping text. Use the Schematic Component Width option in this region of the tab, to resize the symbol in the horizontal plane as required. The value is entered as DXP Default units, where 1 DXP Default unit is equal to 10mils.

Figure 6. Resize the width of the instrument's symbol on the schematic to enhance readability.

Configuration File This region of the tab is where the file, into which all configuration information will be stored, is specified. Storage of configuration information in a separate file (*.Instrument) allows for portability of customized instruments between projects and installations – why use someone else's instrument, when you can take your favorite with you!

If creating a new configuration for the instrument, simply click on the folder icon, at the far right of the Configuration File Name field, and use the subsequent Save Configuration File To dialog to nominate where, and under what name, the file is to be saved. Typically, you would save the file to the same location as the parent FPGA project.

If you wish to configure the instrument using information stored in an existing configuration file, simply click on the Load From Existing button and use the subsequent Choose Instrument File dialog to browse to, and open, the required file. The information stored in the file will be loaded, where applicable, into each of the three tabs of the Custom Instrument Configuration dialog.

Configuration Retrieval This region of the tab is used to specify the method by which Altium Designer can access the relevant configuration information, for a custom instrument that is detected in the Soft Devices JTAG chain: • From Project - the configuration information is retrieved from the corresponding .Instrument

file for the instrument, which resides in the location specified in the Configuration File Name field (described previously). The project must be open in order to show the instrument from the Devices view.

• From FPGA - the configuration information is downloaded with the design to the physical device, and stored in Block RAM. It is retrieved directly from here and the project need not be open.


Version (v1.1) Aug 19, 2008 5

Design tab

The Design tab of the Custom Instrument Configuration dialog is where you design the look and feel of the instrument's panel – the customized GUI that you access to interact with the instrument at run-time. Initially, you will be presented with a 'shell' instrument form with which to build the GUI (Figure 7).

Figure 7. Design tab – providing the canvas with which to create the customized GUI for the instrument.

The Design tab is analogous to the Form tab in a DelphiScript Form.

There are three tabbed panels associated to the form: • Palette – this panel (Figure 8) provides a range of standard scripting components and instrument-specific controls for use on

the form.

Figure 8. Palette panel.

The panel is analagous to the Tool Palette panel used in scripting, but only contains those components and controls supported for use with a Custom Instrument. For more information on the components and controls available, see the sections Available Standard Components and Available Instrument Controls, respectively.

• Properties – this panel (Figure 9) displays all attributes of the currently selected component or control on the form. Use these properties to fine-tune the presentation and/or functionality of each object, further enhancing the look and feel of your customized instrument GUI.


Version (v1.1) Aug 19, 2008 6

The Properties and Events tabs are analogous to the tabs found on the Object Inspector panel used in scripting.

Figure 9. Example of the Properties panel.

• Events – this panel (Figure 10) lists the applicable events for the currently selected component or control on the form. These are the events that the object can 'react' to. This panel is used to hook-up a script procedure or function to a control, which will be called when the specified event occurs.

Figure 10. Example of the Events panel.

The initially selected object in the blank form, named DesignedAreaPanel, represents the bounds of form design. Objects can only be placed within this area. While the width of the panel design area is fixed, you can freely adjust the height of the panel, making it larger or smaller in accordance with the number of controls being used and presentation requirements.

The height of the panel can be changed in two ways: • By entering a new value for the Height property, in the Properties panel

• Clicking and dragging the editing handle at the bottom-center of the design boundary. As you drag, the value for the Height property will change accordingly.

Placing Objects onto the Form To place a component or control on the form, simply click on the relevant icon on the Palette panel and then click at the desired location within the bounds of the form.

Alternatively, double-click on an icon to have the object placed centrally on the form, and then move the object to the desired location. To delete a component/control from the form, simply click to select it and then hit the Delete key.

Note: If you have clicked on an icon in the palette and decide you do not need that component/control, to avoid placement on

the form you can simply click on the button at the top-left of the panel, to de-select that component/control.

Figure 11. Build your custom GUI by placing objects from the Palette panel.


Version (v1.1) Aug 19, 2008 7

Editing Placed Objects on the Form After an object has been placed on the form, there are a variety of ways in which its location, size, or appearance can be edited. These methods of editing generally fall into two categories – graphical editing, directly within the form, and editing performed using the associated attributes on the Properties panel.

Graphical Editing When you click to select an object on the form, a number of editing handles will appear. To relocate the object, simply click on it, away from any editing handles, and drag to the required new position (Figure 12).

If the object can be resized – such as a Graph or Progress Bar – the cursor will change to a double-headed arrow when hovered over an editing handle. Using the applicable editing handle, you can simply click and drag to resize the object as required, in the vertical or horizontal (or both) planes (Figure 13).

Figure 13. Resizing an object directly on the form.

In addition to these basic graphical editing features, there are also various commands available on the right-click context menu that apply to the currently selected object or objects (use Shift+Click to select multiple objects).

• Align To Grid – use this command to align the selected object(s) to the form's grid.

• Bring To Front – use this command to bring the selected object to the front in terms of drawing order for a group of collocated objects.

• Send To Back – use this command to send the selected object to the back in terms of drawing order for a group of collocated objects.

• Align – use this command to access the Alignment dialog. This dialog is most useful when you want to align multiple selected objects on the form. For a single object, you can quickly center it in the vertical and/or horizontal planes.

Figure 14. Alignment dialog.

• Size – use this command to access the Size dialog, from where you can quickly change the size of the selected object(s) in terms of width and/or height. Options are also provided to quickly resize all objects in a selection based on the width and/or height of either the smallest object in the selection, or the largest.

Figure 12. Moving an object directly on the form.


Version (v1.1) Aug 19, 2008 8

Figure 15. Size dialog.

• Scale – use this command to access the Scale dialog, which is used to enlarge or reduce the selected object(s) based on the positive scaling factor entered. The default value of 100 equates to no change. If you want to halve the size, enter a value of 50. To double, enter a value of 200, and so on. The result is similar to resizing an object by using the bottom-right editing handle.

Figure 16. An example of scaling (200) applied to a default Graph control.

• Tab Order – use this command to access the Tab Order dialog. This dialog lists all those components and controls currently exist on the form, which can be used by the user to make something happen – such as an edit box or a clickable button. Use the dialog to determine the order in which these objects will be accessed on the run-time instrument panel when using the Tab key.

Figure 17. All objects for use on a form that allow tabbed access – define tab order using the Tab Order dialog.

• Creation Order – use this command to access the Creation Order dialog. This dialog lists all non-visual components currently used on the form. Non-visual components are not seen by the user on the run-time instrument panel. The creation order becomes important where one non-visual component requires the existence of another non-visual component prior to executing its functionality. Use this dialog to determine that creation order as required.


Version (v1.1) Aug 19, 2008 9

If multiple objects are selected, only those properties that are common to all objects will be displayed for editing on the Properties panel.

Figure 18. All non-visual objects for use on a form – define creation order using the Creation Order dialog.

Editing of Associated Properties The main avenue used when defining the look and feel of a control on the form – especially when that control is being used to display the value of a monitored signal – is the Properties panel.

Simply select the object whose properties you wish to change in some way, and then edit the required attributes on the panel as required. The majority of properties are straight forward and intuitive (e.g. Font, Color, Width, etc). Bear in mind that the Properties panel will populate with only those properties applicable to the selected object type.

Figure 19 illustrates how changing properties can make a Gauge control appear differently on the form.

Figure 19. Change the appearance of an object using its associated properties.

Directly Hooking up Signal IO to a Control Later in this document, we will look at how IO signals wired to a Custom Instrument can be manipulated to a greater degree by use of scripting. However, use of a script is not a prerequisite for use of the instrument. Indeed, the controls you place for your customized instrument GUI can be hooked up directly to the instrument's inputs and outputs – wired to the component on the schematic – without ever having to touch code.


Version (v1.1) Aug 19, 2008 10

The key to this direct connection of IO signal to instrument control object, lies in the use of the control's SignalName property. Each control that is capable of being used to monitor input and/or control output, will have this property as part of its properties list. The value field for the SignalName property provides a drop-down list of the signal(s) that can be 'hooked up' to the control.

Figure 20. Use the SignalName property to directly link a signal to the instrument control.

Note: The signal(s) listed will depend on the type of control. If it is a display-type control, only input signals will be listed. If it can be used to control output only, then only output signals will be listed. If it can be used to either display or control IO, then all inputs and outputs will be listed. It is also possible to setup controls on the form to only monitor/control part of a signal. In the value field for the SignalName property, simply select the required signal, then modify the index accordingly. For example, consider an input signal, Data_In[7..0], which is wired to a Custom Instrument on the schematic. On the customized instrument panel, we might want to monitor the individual bits of this signal, using eight Progress Bar controls. Starting with the left-most Progress Bar control, you would simply select each control in turn and set the SignalName property to assign the corresponding signal line of the Data_In[7..0] input. So set Data_In[7] for the leftmost control, then Data_In[6] for the next control, through to Data_In[0] for the right-most control.

Figure 21. Example of 'splitting' a signal over multiple instrument control objects.


Version (v1.1) Aug 19, 2008 11

Available Standard Components Table 1 lists all of the standard components available for use when designing the GUI for a Custom Instrument. These are components that are used as standard in scripting and, as such, can all be found on the Tool Palette panel that is used when writing general scripts in Altium Designer.

Table 1. Standard components for use on the instrument form.

Palette Icon

Component Name Description Component Type

TActionList Used to create and maintain a list of actions (event handling code) that

can be subsequently 'called' by different components (e.g. pop-up menu entries and buttons) on the instrument panel.

Actions are added and maintained using a dedicated editing dialog (accessed by double-clicking on the placed component).

Non-Visual

TBevel Used to add a beveled outline to the instrument panel. The bevel can

appear raised or lowered, by setting its Style property to bsRaised or bsLowered, respectively.

Visual

TImage Used to display a graphical image on the instrument panel, such as a bitmap, icon, or metafile.

Visual

TImageList Used to provide a repository in which to store a collection of same-sized images (icons, bitmaps, or metafiles). All images in an image list are contained in a single, wide bitmap in screen device format. An image list may also include a monochrome bitmap that contains masks used to draw images transparently (icon style).

Images are added and maintained using a dedicated editing dialog (accessed by double-clicking on the placed component). Images are retrieved via their index (in the range 0 to n-1).

Non-Visual

TPanel Used to visually group components together on the instrument panel. To

maintain the same relative position when the instrument panel is resized, set the component's Align property to alTop.

Visual

TPaintBox Used to render an image on the instrument panel, which is drawn directly

under script control. Typically, you would link the underlying script code (event handler) to this component using the OnPaint event.

Visual

TPopupMenu Used to define a pop-up menu that appears when the user right-clicks over

a particular control on the instrument panel. To make the pop-up menu available for the target control, simply assign the TPopupMenu object to that control's PopupMenu property.

Non-Visual

TShape Used to draw a geometric shape on the instrument panel. Visual

TTimer Used to trigger an event periodically, based on a defined time interval. The code (event handler) in the underlying script is hooked up to the TTimer component's OnTimer event, which is triggered every time the value for the component's Interval property has elapsed.

Non-Visual

TOpenDialog Used to display a modal Windows dialog for selecting and opening files.

The dialog does not appear at runtime until it is activated by a call to the Execute method. When the Open button in the dialog is clicked, the dialog closes and the selected file(s) are stored in the component's FileName property.

Non-Visual


Version (v1.1) Aug 19, 2008 12

TSaveDialog Used to display a modal Windows dialog for selecting and saving files. The

dialog does not appear at runtime until it is activated by a call to the Execute method. When the Save button in the dialog is clicked, the dialog closes and the selected file(s) are stored in the component's FileName property.

Non-Visual

TFontDialog Used to display a modal Windows dialog for selecting fonts. The dialog

does not appear at runtime until it is activated by a call to the Execute method. When a font is selected and the OK button in the dialog is clicked, the dialog closes and the selected font is stored in the component's Font property.

Non-Visual

TColorDialog Used to display a modal Windows dialog for selecting colors. The dialog

does not appear at runtime until it is activated by a call to the Execute method. When a color is selected and the OK button in the dialog is clicked, the dialog closes and the selected color is stored in the component's Color property.

Non-Visual

TPrintDialog Used to display a modal Windows dialog for sending jobs to a printer. The

dialog does not appear at runtime until it is activated by a call to the Execute method. When print options have been defined and the OK button in the dialog is clicked, the dialog closes and the relevant print job information is stored in the component's corresponding properties.

Non-Visual

TPrinterSetupDialog Used to display a modal Windows dialog for configuring printers. The

dialog does not appear at runtime until it is activated by a call to the Execute method.

Non-Visual

TPageSetupDialog Used to display a modal Windows dialog for configuring the page. The

dialog does not appear at runtime until it is activated by a call to the Execute method. When page options have been defined (such as paper size, orientation and margins) and the OK button in the dialog is clicked, the dialog closes and the relevant information is stored in the component's corresponding properties.

Non-Visual

TFindDialog Used to display a modeless Windows dialog that prompts the user for a

search string. The dialog does not appear at runtime until it is activated by a call to the Execute method. When a string is entered and the OK button in the dialog is clicked, the dialog closes and the entered search text is stored in the component's FindText property.

Non-Visual

TReplaceDialog Used to display a modeless Windows dialog that prompts the user for a

search string and a replace string. The dialog does not appear at runtime until it is activated by a call to the Execute method. When both strings are entered and the OK button in the dialog is clicked, the dialog closes. The entered search text is stored in the component's FindText property. The entered replacement text is stored in the component's ReplaceText property.

Non-Visual

Properties, Events and Methods Properties and events associated to each component can be viewed on the Properties and Events panels respectively. For more information on the methods supported for each component, refer to the relevant section of the document TR0119 Component Reference.

Additionally, for more detailed information on each of these components, refer to external documentation for the Borland Delphi Visual Component Library.


Version (v1.1) Aug 19, 2008 13

Available Instrument Controls Table 2 lists all of the instrument controls available for use when designing the GUI for a Custom Instrument. These controls are specifically for use with the Custom Instrument.

Table 2. Instrument controls available for use on the instrument form.

Palette Icon

Control Name Description Default Appearance on Form

TInstrumentBackground Used to add a colored background area to the

instrument panel.

TInstrumentButton Used to add a push button to the instrument

panel. This control would typically be used to initiate some action when it is clicked, by having event handling code linked to its OnClick event.

TInstrumentCaption Used to add a caption to the instrument panel.

Captions are typically used to distinguish between distinct regions of functionality within the panel (e.g. INPUTS and OUTPUTS).

TInstrumentCheckBox Used to add a check box to the instrument panel.

When clicked, the component's Checked property is automatically toggled between enabled (True) and disabled (False).

The check box can be used to control an output signal. The direct link to the signal is made using the SignalName property.

This control might also be used to initiate some action when it is clicked, by having event handling code linked to its OnClick event.

TInstrumentEdit Used to add an edit box to the instrument panel.

This control is typically used to retrieve text that is entered by the user. It can be used to control an output signal. The direct link to the signal is made using the SignalName property.

Although this control can also be used solely for displaying text, in such a case it would be easier to use a simple TInstrumentLabel control.

TInstrumentGauge Used to add an analog-style gauge to the

instrument panel. It can be used to monitor an input signal. The direct link to the signal is made using the SignalName property.

Use the Position property to define the initial displayed value (typically, set this to be the same value as that of the MinValue property).

TInstrumentGraph Used to add a graph to the instrument panel. It

can be used to monitor an input signal. The direct link to the signal is made using the SignalName property.

TInstrumentKnob Used to add a control knob to the instrument

panel. It can be used to control an output signal. The direct link to the signal is made using the


Version (v1.1) Aug 19, 2008 14

SignalName property.

The initial setting for the knob – specified by its Value property – is determined by the entry for the signal's Initial value, on the Signals tab of the Custom Instrument Configuration dialog.

The default behavior when turning the control knob is to have its value changed smoothly. Use the Discrete and ValueIncrement properties to enable and allow the value to be changed discretely, in steps according to the value defined for the ValueIncrement property.

TInstrumentLabel Used to add a simple text label to the instrument

panel. Use labels to 'annotate' the panel – tagging controls or explaining functionality.

TInstrumentLEDButton Used to add an LED button to the instrument

panel. When clicked, the component's IsOn property is automatically toggled between enabled (True) and disabled (False).

The LED button can be used to control an output signal. The direct link to the signal is made using the SignalName property.

This control might also be used to initiate some action when it is clicked, by having event handling code linked to its OnClick event.

TInstrumentLEDDigits Used to add a digital LED display to the

instrument panel. It can be used to either monitor an input signal, or control an output signal. The direct link to the signal is made using the SignalName property.

If linked to an output signal, the display will only be editable provided the UseDefaultDigitClick property is enabled. If linked to an input signal, use the Value property to define the initial displayed value (typically, set this to be the same value as that of the MinValue property). For an output signal, this value is determined by the entry for the signal's Initial value, on the Signals tab of the Custom Instrument Configuration dialog.

Values can be displayed/entered in either binary, decimal, hexadecimal, or octal, depending on the setting of the component's Radix property.

TInstrumentLEDsPanel Used to add a grouped 'panel' of LEDs to the

instrument panel. It can be used to either monitor an input signal, or control an output signal. The direct link to the signal is made using the SignalName property.

If linked to an output signal, the LEDs will only be editable provided the UseDefaultDigitClick property is enabled. If linked to an input signal, use the Value property to define the initial displayed value (typically, set this to be the same value as that of


Version (v1.1) Aug 19, 2008 15

the MinValue property). For an output signal, this value is determined by the entry for the signal's Initial value, on the Signals tab of the Custom Instrument Configuration dialog.

TInstrumentNumericPanel Used to add a numeric display to the instrument

panel. It can be used to either monitor an input signal, or control an output signal. The direct link to the signal is made using the SignalName property.

If linked to an output signal, the display will only be editable provided the UseDefaultDigitClick property is enabled. If linked to an input signal, use the Value property to define the initial displayed value (typically, set this to be the same value as that of the MinValue property). For an output signal, this value is determined by the entry for the signal's Initial value, on the Signals tab of the Custom Instrument Configuration dialog.

Values can be displayed/entered in either binary, decimal, hexadecimal, or octal, depending on the setting of the component's Radix property.

TInstrumentPanel Used to add panel area to the instrument panel.

This control is used for panel aesthetics, for example to highlight the numeric display of monitored information.

TInstrumentProgressBar Used to add a progress bar to the instrument

panel. It can be used to monitor an input signal. The direct link to the signal is made using the SignalName property.

Determine the bar's orientation on the panel using its Orientation property.

Use the Position property to define the initial displayed value (typically, set this to be the same value as that of the MinValue property).

TInstrumentScrollBar Used to add a scroll bar to the instrument panel. This control would typically be used in combination with some other control or form, to allow scrolling of the content therein.

Change the orientation of this control using the Kind property.

TInstrumentTerminal Used to add a terminal window to the instrument

panel that can be used to enter and/or display characters or strings of characters as multi-line text. Such a terminal window could be used as a simple memo control, for example.

TInstrumentTrackBar Used to add a slider bar to the instrument panel.

It can be used to control an output signal. The direct link to the signal is made using the SignalName property.

Change the orientation of this control using the


Version (v1.1) Aug 19, 2008 16

Horizontal property.

The initial setting for the slider bar – specified by its Value property – is determined by the entry for the signal's Initial value, on the Signals tab of the Custom Instrument Configuration dialog.

The default behavior when sliding the bar is to have its value changed smoothly. Use the Discrete and ValueIncrement properties to enable and allow the value to be changed discretely, in steps according to the value defined for the ValueIncrement property.

Properties, Events and Methods Properties and events associated to each control can be viewed on the Properties and Events panels respectively. Table 3 lists information with respect to the supported (and Public) methods for each control. Where methods are indicated as being inherited, the source of that inheritance (and its default set of methods) can be found in external documentation for the Borland Delphi Visual Component Library.

Table 3. Supported methods for the instrument controls.

Control Methods

TInstrumentBackground TInstrumentCaption TInstrumentCheckBox TInstrumentGauge TInstrumentGraph TInstrumentLabel TInstrumentLEDDigits TInstrumentLEDsPanel TInstrumentNumericPanel TInstrumentProgressBar

All methods inherited from TGraphicControl

TInstrumentButton

TInstrumentLEDButton

The following dedicated new method for this control: • Procedure UpdateBitmaps;

All other methods inherited from TCustomControl

TInstrumentEdit All methods as per the TXPEdit component

TInstrumentKnob

TInstrumentTrackBar

All methods inherited from TCustomControl

TInstrumentPanel The following dedicated new method for this control: • Procedure PaintOnBitmap(ABitmap : TBitmap);


TInstrumentScrollBar The following method is inherited from TCustomXPScrollBar: • Procedure SetParams(APosition, AMin, AMax : Integer);


TInstrumentTerminal The following dedicated new methods for this control: • Procedure PutChar(AChar : Char; ATransmit : Boolean);

• Procedure PutString(Const AString : String; ATransmit : Boolean);

• Procedure Clear;

• Procedure GetLines(ALines : TStrings); Overload;

• Function GetLines : String; Overload;

• Function GetLines(AFromPt, AToPt : TPoint) : String; Overload;


Version (v1.1) Aug 19, 2008 17

The following method is inherited from TCustomInstrumentPanel: • Procedure PaintOnBitmap(ABitmap : TBitmap);


Code tab

The Code tab of the Custom Instrument Configuration dialog is where you write the underlying event handling code – procedures and/or functions that are called into action when corresponding trigger events, relating to the components and controls on the instrument panel itself, are encountered. Initially, you will be presented with a blank page on which to write the content of your script (Figure 22).

Only DelphiScript is supported when writing event handling script for a Custom Instrument. For more information on working with DelphiScript, refer to the document TR0120 DelphiScript Reference.

Figure 22. Code tab – providing an area in which to develop your event handling code.

Hooking the Script up to the Instrument Writing script event handling procedures and functions is literally 'half the battle'. You could have the most elegant and functionally smart code there is, and it will still remain dormant unless it is correctly linked, or hooked-up, to the relevant components and controls defined for the instrument's customized GUI.

Having read through the previous sections of this document, you will be aware that each component/control has a number of events associated with it. These are the events which the component/control can 'react' to. The script code that gets used when an event is 'fired' is that event's handling code. The parent procedure or function written in the script is therefore the 'event handler'. The logical place then, to link event to event handler, is the value of the event – defined on the Events panel, when the Design tab of the dialog is active.

Standard Component/Instrument Control

ObjectNameClick

ObjectNameChange

ObjectNameMouseDown

DelphiScript Code

OnClick

OnChange

OnMouseDown

ObjectNameMouseUpOnMouseUp

Event Value

Figure 23. Use the value field of an object's Event to link to a procedure in the script.


Version (v1.1) Aug 19, 2008 18

There are two ways by which the event handling code can be linked to an event of a component/control, depending on your preferred method of working:

• Write the event handling procedure or function first then, for the component/control in question, assign it to the desired event by clicking in the value field for that event and choosing the name of the procedure or function from the drop-down list of all currently written procedures and functions.

Figure 24. Assigning existing event handling code to an event.

• For the component/control in question, identify the event on which you wish something to happen, then simply double-click inside the value field for that event. The Code tab of the dialog will be made active, and a shell event handling procedure added, ready for you to define the required functionality. The name of the procedure is automatically entered as the value for the event.

Figure 25. Generating new event handling code from an event.


Version (v1.1) Aug 19, 2008 19

Manipulating Signal IO through a Script As discussed earlier in the document, input and output signals can be linked directly to the controls placed on the customized GUI for the instrument. For many cases, this direct use of the signals will be sufficient. However, to fully harness the power of the Custom Instrument and give you full control over the processing of signal IO, scripting is required.

Synchronous Read/Write of Signals An event handler in the script is entered when the event to which it is linked is encountered, or 'fires'. When monitoring inputs or controlling outputs – wired to the Custom Instrument – we are dealing with not just a single control object on the instrument's panel, but rather the entire panel itself. The event we are interested in, and to which we will link code to read input signal values and write values onto output signal lines, is the OnReadWrite event. Figure 26 shows this event, along with shell procedure, for a panel possessing the default name DesignedAreaPanel.

Figure 26. Event handler for the OnReadWrite event, associated to the instrument panel.

The panel's OnReadWrite event is hard coded to 'fire' each time the instrument polls. Remember that the polling interval is 250ms by default, and can be changed in the Custom Instrument – Options dialog (provided the Options button has been enabled for inclusion on the panel).

Each time the instrument polls, the current value for each input signal is read into an internal storage structure. Similarly, the current value internally stored for each output signal is made available at the corresponding output pin of the instrument. The internal storage structure is transparent to the user and, as such, cannot be accessed in any way. The event handling code linked to the OnReadWrite event is essentially used to process the IO as required.

Custom Instrument

AIN_Val

BIN_Val

CIN_Val

AOUT_Val

BOUT_Val

COUT_Val

Event Handling Code:

Procedure TDesignedAreaPanel.DesignedAreaPanelReadWrite(Sender : Tobject);

AIN

BIN

CIN

AOUT

BOUT

COUT

Figure 27. Use event handling code linked to the panel's OnReadWrite event to process signal IO each time the instrument polls.


Version (v1.1) Aug 19, 2008 20

Of course, the full script may well contain more than just this one event handling procedure, for example to react to buttons being clicked or check boxes being toggled. It may well be that your instrument does not even need to use this event – relying rather on 'asynchronous' events of other controls to process the signals – remember, the IO values are updated by nature of the polling, not by the OnReadWrite event. The latter is simply a method to synchronously call code which can process the signal values at each poll point.

If polling is turned off (by setting the Update value in the Custom Instrument – Options dialog to 0ms), the OnReadWrite event will not fire. It will, however, fire if the Synchronize button is available on the instrument's panel, and is pressed. This would essentially be a 'manual poll'.

Getting and Setting Signal Values Access to the IO signals from within the code is made possible through use of the following global function:

Function SignalManager : TSignalManager;

This function returns an instance of the TSignalManager class – a global object which provides access to signals within a given Custom Instrument.

Table 4 lists the methods available for the SignalManager object.

Table 4. Supported methods for the SignalManager global function.

Method Description

Function GetInputSignalCount : Integer; Returns the number of input signals defined for the instrument.

Function GetInputSignal(Index : Integer) : TSignal; Returns a given input signal, based on the index value supplied. The index used depends on where the signal appears in the list of input signals, defined on the Signals tab of the Custom Instrument Configuration dialog. Index 0 corresponds to the signal at the top of the list.

Function GetOutputSignalCount : Integer; Returns the number of output signals defined for the instrument.

Function GetOutputSignal(Index : Integer) : TSignal; Returns a given output signal, based on the index value supplied. The index used depends on where the signal appears in the list of output signals, defined on the Signals tab of the Custom Instrument Configuration dialog. Index 0 corresponds to the signal at the top of the list.

Function GetSignalByName(Const ASignalName : TDynamicString) : TSignal;

Returns the signal that matches the supplied signal name string.

The main difference between these functions is when each is used:

• GetSignalByName – use this function when you know the name of the signal that you want to process.

• GetInputSignal, GetOutputSignal – use these functions, together with GetInputSignalCount and GetOutputSignalCount, when there is a need to iterate all input/output signals, irrespective of how many there are or what their names may be.

The TSignal class object has the following three properties: • Name – this read-only property allows you to obtain the name of the signal

• Value – this read-write property allows you to get the current value for a signal, or to set the value for that signal • Width – this read-only property allows you to obtain the width of the signal (e.g. for a signal named Data_Out[7..0], the

Width will be 8).

The following example code snippet shows use of this SignalManager function and the GetSignalByName method, to set the value for an output signal, Data_Out[7..0], based on the current value entered into a numeric panel control named LED_Control.


Version (v1.1) Aug 19, 2008 21

begin

SignalManager.GetSignalByName('Data_Out[7..0]').Value := LED_Control.Value;

end;

When working with bussed input and output signals in a script, the full signal range must be declared when entering the signal name parameter for the GetSignalByName method, otherwise the script will fail. So for a 32-bit signal VOLTAGE_OUT[31..0], the following line of script will work:

SignalManager.GetSignalByName('VOLTAGE_OUT[31..0]').Value := $00003500;

but this line of script will not:

SignalManager.GetSignalByName('VOLTAGE_OUT[15..8]').Value := $35;

Of course, with scripting you can simply add a few extra lines of code to achieve the required result!

Writing the Code in a Syntax-Aware Text Editor The Code tab supports basic syntax highlighting. Should you wish to write your script within the comfort of a code-aware editor within Altium Designer, simply click the Open in Code Editor button at the bottom of the Custom Instrument Configuration dialog. This allows you to take advantage of the extended syntax highlighting and related code-based features available in the editor, that are not available in the Code tab of the dialog.

If you use the Code Editor to write your script, simply save the file when done and the code will be available in the dialog when next accessed.

Figure 28. Switch to writing your code in the luxury of a syntax-aware coding editor at the click of a button!


Version (v1.1) Aug 19, 2008 22

Accessing the Run-time Instrument Panel

The host computer is connected to a target Custom Instrument using the IEEE 1149.1 (JTAG) standard interface. This is the physical interface, providing connection to physical pins of the FPGA device in which the instrument has been embedded.

The Nexus 5001 standard is used as the protocol for communications between the host and all devices that are debug-enabled with respect to this protocol. This includes the custom instruments, as well as other Nexus-compliant devices such as debug-enabled processors, frequency generators, logic analyzers, counters, digital IO modules and cross-point switches.

All such devices are connected in a chain – the Soft Devices chain – which is determined when the design has been implemented within the target FPGA device and presents within the Devices view (Figure 29). It is not a physical chain, in the sense that you can see no external wiring – the connections required between the Nexus-enabled devices are made internal to the FPGA itself.

Figure 29. Nexus-enabled Custom Instrument device appearing in the Soft Devices chain.

The GUI for a Custom Instrument used in a design can be accessed from the Devices view. Simply double-click on the icon representing the CUSTOM_INSTRUMENT device whose controls you wish to access, in the Soft Devices region of the view. The Instrument Rack – Soft Devices panel will appear, with the chosen instrument added to the rack (Figure 30).

Figure 30. Accessing the customized instrument GUI.


Version (v1.1) Aug 19, 2008 23

Custom instrumentation, as well as various other virtual instruments can be accessed without Altium Designer or the Viewer Edition of Altium Designer, using the standalone Altium Instrument Dashboard.

Note: Each CUSTOM_INSTRUMENT device that you have included in the design will appear, when double-clicked, as an instrument in the rack (along with any other Nexus-enabled devices).

Field Servicing using the Viewer Edition of Altium Designer

For a Field Application Engineer, or Service Engineer out in the field, access to the GUI of a Custom Instrument, embedded within an FPGA design, could not be simpler. A trusty laptop computer loaded with the Viewer Edition of Altium Designer is all that is needed.

Simply connect your laptop to the target in which the design is currently running – which could be one of Altium's off-the-shelf Deployment NanoBoard solutions – start the Viewer, and access the Devices view. While the Viewer does allow access to the Devices view, the only functionality that can be accessed in terms of NanoBoards, Hard and Soft devices, is that of the Custom Instrument component. The type of NanoBoard you are connected to will appear in the NanoBoard chain of the view, but all other devices and components will appear as generic entities. You can not access the Process Flow for a physical device and therefore cannot program any devices from the view.

Only the instrument panel associated with the Custom Instrument can be accessed, by double-clicking on the icon for the instrument in the Soft Devices chain of the view.

It is important to note that in order to access and use the Custom Instrument at run-time from the Viewer, the instrument must have been configured (in Altium Designer during the design phase) such that the Configuration Retrieval option is set to From FPGA. This ensures that the configuration information for the instrument is downloaded with the design to the physical device (and stored in Block RAM).

Figure 31. Accessing the associated panel for the Custom Instrument from within the Devices view (within the Viewer Edition of Altium Designer).

http://wiki.altium.com/display/ADOH/Altium+Instrument+Dashboard�

http://wiki.altium.com/display/ADOH/Altium+Instrument+Dashboard�


Version (v1.1) Aug 19, 2008 24

Revision History

Date Version No. Revision

30-Jun-2008 1.0 Initial release

19-Aug-2008 1.1 Updated images relating to the Custom Instrument Configuration dialog.

30-Aug-2011 - Updated template.

Software, hardware, documentation and related materials:

Copyright © 2011 Altium Limited.

All rights reserved. You are permitted to print this document provided that (1) the use of such is for personal use only and will not be copied or posted on any network computer or broadcast in any media, and (2) no modifications of the document is made. Unauthorized duplication, in whole or part, of this document by any means, mechanical or electronic, including translation into another language, except for brief excerpts in published reviews, is prohibited without the express written permission of Altium Limited. Unauthorized duplication of this work may also be prohibited by local statute. Violators may be subject to both criminal and civil penalties, including fines and/or imprisonment.

Altium, Altium Designer, Board Insight, DXP, Innovation Station, LiveDesign, NanoBoard, NanoTalk, OpenBus, P-CAD, SimCode, Situs, TASKING, and Topological Autorouting and their respective logos are trademarks or registered trademarks of Altium Limited or its subsidiaries. All other registered or unregistered trademarks referenced herein are the property of their respective owners and no trademark rights to the same are claimed.

Documents

Custom Instrument Reference - Altiumvalhalla.altium.com/Learning-Guides/TR0176 Custom Instrument Ref… · configuration file, simply click on the Load From Existing button and use