Bladed Hardware Test User Manual

Bladed Hardware Test Module

Version 1.2

User Manual

Document No 282/BR/13 Issue A Status Approved Date Jan 2013

Author: T P Jacob

DISCLAIMER

Acceptance of this document by the client is on the basis that GL Garrad Hassan and Partners Limited are not in any way to be held responsible for the application or use made of the findings of the results from the analysis and that such responsibility remains with the client.

Key To Document Classification

Strictly Confidential : Recipients only

Private and Confidential : For disclosure to individuals directly

concerned within the recipient’s organisation

Commercial in Confidence : Not to be disclosed outside the recipient’s organisation

GHP only : Not to be disclosed to non GHP staff

Client’s Discretion : Distribution at the discretion of the client subject to contractual agreement

Published : Available to the general public

© 2012 GL Garrad Hassan

1. CONCEPT

The Bladed Hardware Test Module is a versatile hardware-in-the-loop testing platform allowing the Bladed turbine simulation to run with a range of hardware including controllers, pitch-systems and power conversion systems.

Figure 1 - Example Physical Arrangement for Bladed Hardware Test

The Bladed Hardware Test permits testing and demonstration of a real control-system in the office, factory and on-site, running on its intended embedded platform. Hardware testing can be applied to all elements of the control system: the software; local & remote I/O; intelligent subsystems; HMI and SCADA. The Bladed Hardware test can interface with the real physical I/O allowing testing of genuine physical fault cases of the control system. Hardware testing can be employed through out the control-system development life-cycle. This includes test-driven techniques during development or delegation of testing outside of the development team; acceptance testing as a project client; integration testing during factory assembly; commissioning and maintenance support for testing system changes against known base-lines. The GL GH testing concept is to provide high level test definition independent of the underlying hardware allowing the same turbine model and test procedures to be used with different hardware configurations. This permits testing from early development with little or no hardware to commissioning prototypes and maintenance activities for production systems.

Mappings enable

channels from

many devices to be

virtually connected

Test Procedures

manipulate

device channels

using flexible

.Net scripting

Protocol Support for a growing set of

plc and data acquisition hardware

Script Engine

Device

Protocol

Channels

Device Listener

Device

Protocol

Channels

Test Procedure

Stepsmappings Step Actions

Reporter

Db

.csv

Bladed data .html

.doc

Customisable

reporting

Fully featured testing environment

for managing multiple procedures

Plug-in interface for supporting custom

hardware, simulations and visualisations

The script engine

offers fast

evaluation of

expressions and

scripts involving

device channels

for tests and

simulation

A device defines a

set of channels

exchanged with an

external

component

Data recording

exports to xml,

text, database

A protocol is a

transport layer

e.g. udp, tcp,

serial

Figure 2 - Bladed Hardware Test Concept

Hardware testing uses a Bladed turbine model and a Test Plan. A Test Plan contains Devices for configuring interfaces to hardware or software components and Test Procedures for defining scenarios and verifying control-system behaviour. Devices define the data channels of the turbine simulation and external components. Each device specifies a Protocol for exchanging channel data with specific hardware or generic interfaces such as OPC, UDP or PC data acquisition hardware. The Bladed Hardware Test offers unrestricted customisation and extension through a scripting engine and a plug-in interface for creating new protocols for testing bespoke hardware. The Hardware Test Module includes customisable Reporting and Logging functionality for presenting test results.

2. GETTING STARTED

2.1 Requirements

Due to the demanding nature of real-time simulations, a fast (3+ GHz) multi core PC with 2Gbyte RAM, is a minimum requirement. The Hardware Test module can exploit multi-processor, dual core and hyper-threading machines for parallel processing of various tasks including managing logs and the user interface but note that the wind turbine simulation model runs in a single thread and, since this is often the most numerically intensive component, it is important to have a high speed PC. Purchase of the Hardware Test Module requires an active support contract. Training in the use of Bladed is highly recommended.

2.2 Starting the Hardware Test Environment

The Bladed Hardware Test can be started from the start-menu or from the main Bladed user interface:

Figure 3 - Starting the Bladed Hardware Test from main user interface

The first time you run the Bladed Hardware Test you will be asked to identify which version of Bladed you wish to use. Browse to your Bladed install directory and select the appropriate executable version – typically Bladed_m72.exe.

Figure 4 - Please locate bladed.exe dialog

Once started, please take a tour of the Hardware Test.

2.3 Tour of the Testing Environment

Bladed Hardware Test module provides the Bladed user with a powerful new user interface for creating test procedures and configuring devices. Different panes can be docked or floated to suit the user's actions.

Toolbar

Device Editor Window

Assertions

Test Procedures

Folders

Devices

Procedure Editor

Window

Windows can be

tabbed and docked

Output Window

Message Window

Figure 5 - Example Overview

2.3.1 The Procedure Editor

New test steps are added by right-clicking on the desired insertion point. If adding the first step into an empty procedure then right-click in the top-left corner of the procedure editor. The sequence of test-steps for editing is animated when running procedures to show the executing step.

Information about the

last test run. E.g.

pass, fail and the

time at which it was

executed

Step Types

Auto complete and

drop-down hints

where appropriate

Steps can use mathematical

expressions using any configured

device channel

Non-editable/padding

cells

Figure 6 - Editing procedure steps

Right click to create\edit\move procedure steps. Note that most test steps accept expressions as their input which can reference any device channel.

Figure 7 – Procedure Editor Popup Menu

Multiple procedure steps can be selected for edit operations like “Cut”, “Copy” and “Delete” by Ctrl-Click-ing individual rows or by clicking and dragging the mouse or by a row selection followed by the Shift+Arrow key combination. Steps that are copied/cut can then be pasted into a different location within the same procedure or into any other procedure in the current plan. In order to paste the current list of steps in the clipboard, open the procedure to paste to, select the insertion point, right click and choose the “Paste” option from the pop-up menu or issue the Ctrl-V key combination. You may also temporarily exclude a set of steps in a given procedure from being executed during a run. This is done by selecting the steps to exclude and then marking them as ignored by choosing the “Mark Ignored” option from the pop-up menu that can be accessed with a right click of the mouse. Ignored steps can later be re-introduced by selecting the steps and choosing the “Reintroduce” option from the pop-up menu. Ignored steps are rendered with a grey background and display a fall-through status icon indicating their non-execution when the procedure is run. Procedure settings support basic descriptive information and configuration of linking to external reference file and data recording. The “Execute Period” is the rate at which the procedure itself is updated. This determines how frequently steps such as WaitUntil (which involve continuously evaluating a condition) are evaluated. The “Listen Period” is the sample period of the channel data which can be exported after the test run has completed. This is independent from the actual resolution of the data used by the simulation which is determined by the device update frequency and the simulation time step. The options Disable Variable Recording and Output Window Style offer the opportunity to configure how results are presented during procedure execution. The DataStorageConfig element of the procedure settings tab lets you specify the action to take when the external file from which the procedure was imported changes. Options available are “ManualReload” where the system ignores changes to the external file, “PromptForReload” where the system notifies the user when the source file changes and “AutomaticReload” where the system reloads the procedure automatically. The option Automatic Data Export lets you export the recorded data by the procedure onto the file system. This option group also lets you choose the data export format, export interval as well as the location for such exports. Note that data recording must remain enabled (which is the case by default) for the automatic data export option to be operational.

Procedure Settings are

easily accessible

Per procedure settings

include how often to

evaluate procedure

steps and how to

present the data.

Data Export Settings:

Lets you periodically export the output

data to a location on the file system in a

format of your choice.

Data Storage Settings:

Allows sharing common procedures

across plans with a notification

mechanism for intimating users

when the externally stored

procedure changes.

Figure 8 - Editing Procedure Settings

2.3.2 The Device Editor

The device view contains tabs for defining Device Channels, creating Mappings between different channels, Scripts and Settings such as the specific protocol to use and its update frequency. Each channel has a usage (whether it is recorded and whether it is written or read from the external component) and a series of configuration fields such as a name, description, data type and unit. The “Unit” field may be used to enter the unit specification for the channel, which is then used by the system to derive the dimension and multiplication factor to associate with the channel when exporting recorded data for this channel into the Bladed export format. Entering units information makes it possible to visualize channel data from such exports better using the Bladed data view component. See unit handling for details on unit specification rules. Protocol specific fields also appear here for routing information. This can be extended by a specific device implementation and can include addresses, packet identifiers, channel numbers etc. i.e. what ever is required to uniquely identify the channel in the underlying transport.

Select the variable

type here including

various precisions

Whether the

channel is read or

written to the

device

Whether a channel

is recorded during

test execution

The name of the

channel to be used

in test steps and

scripting

Figure 9 - Editing device channels

New device channels are added by right-clicking on the desired insertion point. If adding the channel into an empty device channel table then right-click in the top-left corner of the device channel editor. This brings up a pop-up menu providing options to insert, delete or swap a variable. In addition to the above options that apply to individual channels, you may also edit the channel usage and recoding status of multiple channels in a single step. Multiple channels can be selected for such edits either by Ctrl+Click-ing individual rows or by clicking and dragging the mouse or by a row selection followed by the Shift+Arrow key combination. Once you have selected the rows you wish to edit by one of these options, right click within the device channel editor and choose the appropriate channel usage/recording option from the pop-up menu presented. The Device Channels view can also be sorted by column in either ascending or descending text order by clicking on the relevant column header in this view.

Device mappings allow one channel to be continuously set to an expression of other channels. This allows calibrations and routing of data between tests, simulations, hardware and visualisations. The left-hand side is the channel on the particular device which is to be set and the right hand side is the expression.

A mapping expression can be any

mathematical expression of device channels

permitting calibrations and transformations

Select a channel from this

device that will be mapped

(continuously set) to the

expression

Figure 10 - Editing device mappings

A device also supports a script. A script is more flexible than mappings and allows programming constructs such as loops. This can be used for easily adding diagnostic or simulation functionality to a device.

Scripts allow the inclusion of complex

actions without any need of external

compilers and can be used to implement

smaller simulations

Line numbering, support for code

folding and highlighted recent edits

Scripts can set and use

device channels as

though they were

normal variables

Syntax highlighting and Intellisense

helps those new to the .Net framework

Figure 11 - Editing device scripts

You may also synchronize devices thereby controlling the execution order of multiple devices. This is done through the “Synchronization” tab of the device editor.

List of devices

available for

synchronization.

List of devices

synchronized with

the current device,

in their execution

order.

Figure 12 – Device Synchronization The rules that apply to synchronization are:

The master device must have an update interval that is lower than that of each of its slaves

A device can be a “slave” to only one other device.

The update intervals associated with the master and slave will determine their execution order. E.g. if the master has an update interval of 0.25 seconds and the slave has an update interval of 0.5 seconds, the master will be updated twice before every slave update. If they were both 0.25 seconds then the slave will be updated after every master device update and so on.

Slave devices that have update periods that are not integral multiples of the update interval of their masters will be updated at an interval that coincides with the nearest master interval update. For example if the master device updates every 0.25 seconds and the slave’s update interval is 0.6 seconds, the slave will get updated after every two updates of the master device (0.6 seconds being closer to 0.5 seconds than 0.75 seconds, the second and third updates respectively for the master device) .

Synchronization can be cascaded, in which case the rules just get applied to all levels of the synchronization tree.

Execution order within sibling devices is determined by the order in which they are added into the synchronized devices list within their master device. Newly added slaves go to the top of the list and get executed first (following the LIFO order). You may remove and re-add devices to the list to get a desired order.

Certain additional rules come into play if you are running a plan in non-realtime mode using synchronization. These are:

In non-realtime mode you should have a single root device if you are using synchronization. The run will not be allowed to proceed if this rule is not followed.

It is recommended that you use a non-realtime time step that is the same value as the update interval of the root device. If an inconsistency is found, a warning will be issued and the test will proceed with the non-realtime time step setting taking precedence.

See Section 2.5 Timing Performance for details on how to run a plan in non-realtime mode.

2.3.3 The Assertion Editor

Assertions allow for the continuous evaluation of expressions during specified periods within a test procedure execution and an action to be taken if the expression evaluates to false. They may be used to verify that certain criteria remained fulfilled during a defined period within a test (for e.g. that the generator speed remained within an expected range from cut-in to shutdown). The assertion editor lets you define the assertion expression as well the action to take in case of the assertion failing.

Assertion Editor

Window

Assertion Expression

Failure Actions

Figure 13 – The Assertion Editor

Assertion expressions can be built up using any of the channels exposed by the devices in the plan and may also employ constant values as well as math functions available from the .Net system library. The list of available device channels and procedures is auto-populated into the dropdown controls that let you edit the “Set Variable” and “Call Procedure” failure actions. The “to” field for the “Set Variable” action may be used to define a constant value to assign to the target variable or an expression that evaluates to a value that is the same data type as the target variable.

2.3.4 Run-time View

The run-time view is typically the scrolling sequence of executing procedure steps with the recorded data samples for each device presented in associated panels. It is also possible to enable run-time graphing with very low processing overhead as shown in the figure below. A third run time feature is the Manual Request dialogue which allows tests to request confirmation of user feedback before continuing.

A manual request test step

allows user interaction with a

running test

Optional real-time plots

Indication of the currently

executing step

Samples from the running

Devices

Figure 14 - Runtime view

2.3.5 The Plan Explorer

Displays a tree-view of the devices, procedures and assertions in the plan. Test results from each run will appear beneath the procedure. Clicking on each leaf will open a tab to view that item. The nodes on the tree are ordered alphabetically, so renaming a node will change may affect its position among its sibling nodes. Right-clicking a tree node allows import, export and deletion and creation of new procedures and devices. Test procedures are logically grouped into folders which can be created by right clicking the “Test Procedures” node. Procedures can be moved between folders using drag and drop. Such move operation can be applied to multiple test procedure nodes (you can select multiple test procedures using Ctrl+Click or Shift+Click, the former for individual selections and the latter for continuous selections). Folders that do not have any procedures associated with them are automatically removed from the tree view. Actions performed on the tree view such as insertion, deletion and movement can be undone using the Ctrl+z key combination and redone using the Ctrl+y key combination.

Assertions Node:

Right click for options.

Red icon indicates

failure, green success

and grey disabled.

Test Procedures:


Test Results:

Right click for

exportoptions.

Devices:


Folders:

Helps group

procedures logically.

Figure 15 - The Plan Explorer

2.3.6 Tool Bar

Create a new Test Plan

Open an existing Test Plan

Show the plan explorer

Show the message window

Show the Search and Replace window

Start the current procedure

Pause the current procedure

Stop the current procedure

Step back a procedure step

Step over the current

procedure step

Save the current

plan

Edit plan and application settings

Check for errors

Figure 16 – Plan Toolbar

2.3.7 Output View

The output view is shown when a test procedure is started. This screen displays the current value of all the recorded channels. The data can be exported from the associated Output menu. By default, the output view is shown below the executing procedure. If the output window is redocked to a new location e.g. a side-by-side view suitable for widescreen monitors, then all subsequent windows will be shown there instead. Each device performs custom update behaviour at a regular interval e.g. socket communication or a calculation. The output window shows additional channels for helping assess device performance:

Time – the time in seconds when the device was last executed

Update period – time in seconds between the previous two device updates

Execution Duration – the seconds elapsed during the last device update The output window is updated at the User Interface Update Rate accessible in the Plan Settings screen. If the Hardware Test window is resized during execution, the channel columns will be resized to attempt to fit the most information on the screen at one time.

Figure 17 - Output View

If the output window is closed and then the results opened from the Plan Explorer, the results are displayed as a time history for easier review: You may also switch to the time history view by right clicking the static output window and selecting “Show Scrolling View”. This right click pop-up menu also lets you export the results to a variety of formats. See How to export data for details on export options and formats.

Each device shown

as a separate tab

Figure 18 – Output List View

2.3.8 Messages View

The Messages view displays a list of messages produced by the application. These include information, warning and error messages that indicate important events along with a timestamp for when they occurred. This view can be accessed from the “View” menu item on the main toolbar and serves as your first port of call when attempting to diagnose errors or unexpected behaviour.

Messages View

Figure 19 – Messages View

2.3.9 Error Messages View

The Error Messages view gives you a list of errors detected in procedures and devices by the applications error checker. These include errors such as attempting to use a channel that is not defined, assigning a value to a channel that is the wrong data type for that channel, compilation errors resulting from scripts within devices. The view gives you a description of the errors as well as a location (a procedure step, a channel number, a mapping expression number or a line within a device script). This view gets displayed automatically when an error is detected by a procedure compilation or device initialisation process. However, you may also manually display this from the View menu on the main tool bar or using the keyboard shortcut Ctrl+E.

Error Messages View

Figure 20 – Error Messages View

2.3.10 Find/Replace

The Find/Replace view lets you perform search and replace operation for strings within a selected scope of the test plan being edited. This view can be accessed from the View menu item on the application’s main tool bar or by pressing Ctrl+F or Ctrl+H keyboard shortcuts. To perform a find operation you simply insert the string you want to search for (or a pattern that is a valid regular expression of using regular expressions), define the scope of the search (which can be either the entire plan, only devices or only procedures) and select the Find All button. The Match Case and Use Regex checkboxes may be used to enable/disable those features in the search. Once the search is performed and results are found, you may double click entries in the results list to navigate directly to the location of the find. If the location is outside of the set of devices/procedures that are currently open, this will cause the target document to be opened and focus to be transferred to the section of the document that produced the search result. Once a search has been performed and results found, you may perform a replace operation on one or many of the results. In order to do this, enter the replacement string to use in the Replace textbox, select the results in which to perform the replacement and click the Replace Selected button.

You can select multiple non-contiguous items from the list by keeping the Ctrl key pressed when making the selection. Pressing down shift key lets you perform selection of items in a range or you may select all entries for replacement by clicking the Select All button in the view.

Find/Replace View

Double click on results to

navigate to the location of the

find.

Figure 21 – Find/Replace View

2.3.11 Plotter

The plotter view allows the Bladed Hardware Test Module user to plot a selection of recorded channels from the devices in their plan against time. This view can be accessed from the View menu item in the application’s main tool bar.

Plotter View

Channel Selector -

Lists recorded

channels. Lets

you choose which

channels to plot

and against which

axis.

Plot AreaDrag and Drop channels from the

selector to the plot area to set up your

plotting configuration

Plot Ttitle

Figure 22 – Plotter View

To the left of the plotter view you’ll find a tree structure that represents the devices in the plan along with all the recorded channels (those with their Record checkbox ticked in the device channel view). This display is kept in sync with edits that happen on the device channel tables, so you should be able to see newly added Recorded channels in this list as soon as the edits are made in the device. In order to enable a channel to be plotted, simply drag and drop the channel from the channel selector into the plot area. Depending on which section (right or left) of the plot area you drop the channel, the channel will be targeted for plotting against either the left-hand Y axis or the right-hand Y axis. To help with this process, a shaded area with a textual hint is displayed to confirm which axis will be used when you hover over the plot area with a dragged channel. Dragging and dropping a channel in this way will set it up to be plotted the next time a procedure in the plan is run. You may change the Y axis for such a channel either by dragging and dropping it again into the desired section of the plot area or by using a context menu that is accessible by right clicking the channel in the channel selector. This context menu also lets you remove the channel from the plot configuration. Note: Context menu for removing a channel from the plot configuration or to change its Y axis are only available for channels are already set up to be plotted. You will need to perform a drag and drop in order to introduce it to the plot configuration. The plot title is set to the value of the run for which the plot has been performed. While the test procedure is running, the plot will get updated based on plot settings chosen in the Plan and Application Settings section. These settings include the update rate for the plot as well as the time window that it keeps in view. When the test is finished (or is stopped by the user) the plotter reverts to displaying the whole data for the run. The plotter view supports the following interactive features –

1. Displaying Coordinate Values: Hover your mouse pointer over any point in the plot area to view a coordinate display that indicates the X, Y1 and Y2 values corresponding to the point under the cursor.

2. Zooming – You may zoom in/out of a plot using your mouse wheel. The corresponding touchpad equivalents may be used when using laptops with no mouse available.

3. Panning – Panning along both horizontal and vertical axes can be achieved by pressing the left/right or up/down arrow keys on your keyboard.

4. Zooming on a single axis – This feature lets you perform a zoom operation on only either the X or Y axis. To do this, select the axis to zoom on by clicking once on the axis labels for it and then performing the zoom using the mouse wheel or touchpad equivalent.

5. Context Menu Items – Right click the plot area to axes the context menu items associated with the plotter. The menu items available are:

a. Fit to View – Resets the display to a mode that removes all previous zoom, pan and reposition operations. This view shows all data points in the dataset.

b. Copy Screenshot – Copies the plot area as an image into the system clipboard (allowing it to be pasted into other applications)

c. Save Screenshot – Allows you to save the plot area as an image on your computer.

2.4 Plan and Application Settings

The Plan and Application settings can be accessed via the toolbar or by right-clicking on the root node of the Plan Explorer.

Application settings apply to the installed instance of the hardware test.

Plan settings apply only to the current plan and stored in the .plan file.

Plan and application settings

open from here

Figure 23 - Plan and Application Settings Screen

Application Settings

Bladed Executable Path – the location of the version of bladed the Hardware Test should use.

Wait for Bladed to start before performing device updates – When running a Bladed simulation, this flag controls whether or not the simulation should wait until the Bladed device has initialized before performing device updates on the other devices present in the plan

Dongle Search Order - whether to search for a network dongle

Show Splash Screen - enable\disable the logo screen shown during startup

Show procedure xml editor - show text view of a procedure

Load last used plan on startup – whether to start with a blank plan or the most recently opened plan

Maximum number of files for recently used list – Configure how many files are shown in the “Recently Opened” menu

Plotting Config o Enable Plotting – enables or disables plotting channel values o Length of time to keep data visible for – the plotter view will use this setting to

decide the pan window. E.g. if this value is set to 30, the plotter will display only the last 30 seconds worth of data during the run. However, when the run finishes or is stopped, the view will readjust to display data from the whole run.

o Plot update interval – indicates how frequently to retrieve channel values from the output and to plot it. A smaller value (which will result in more frequent updates) will give you more points on the plot but will have a negative impact on performance.

Plan Settings

Name – read only name of the plan

Description – optional description

Last modified - last modified time of the plan

User Interface Update Rate – the rate at which the UI refreshes, UI elements like the output view that shows channel values from an ongoing run update their display based on this rate

Version – plan version. Indicates the version of BHTM that was used to last save this plan.

Bladed executable path – an option to override the version of bladed used for this plan only. If it is left blank then the version of bladed in the Application Settings is used instead

Device Timer Type – the timing scheme used by the plan. See Section 2.5 Timing Performance.

Time step for non-real time executions – when running in non-real time mode, each device update cycle is treated as having advanced time by the step specified by this setting

Report Generation Config – Lets you specify configurable aspects of report generation. See Reporting for details.

2.5 Timing Performance

The real-time performance of communication protocols and simulations depends upon the accuracy of the Bladed Hardware Test event timing. The hardware test offers a number of timing schemes which have different performance characteristics on different PC hardware. These can be configured on the Plan Settings screen:

Timing Thread High overhead timing scheme with accuracy down to 200 micro-seconds on a suitably prepared machine. This requires a powerful multi-core system and is not suitable for single-core uniprocessor machines.

Multimedia Timer

The highest precision native OS timer with low overhead but accuracy of 1-2 ms. Suitable for single-core or slower systems.

Multimedia Thread A similar low overhead timing scheme as above but it will spread the load of different devices across cores better at a slight impact to accuracy.

Cooperative Thread Low overhead timing offering accuracy no better than 2 milliseconds

Twin Cooperative Thread Low overhead timing offering accuracy no better than 1 millisecond

System Timer Very low overhead timing but with very limited accuracy

NonRealTimeExecution Non-realtime mode of execution, where devices are updated as fast as the system can update them. Each update cycle is treated to be as long as real time step parameter set in the procedure’s setting. Execution order of synchronized devices is maintained just the same as in the realtime modes.

Timing Thread is the default scheme. Other schemes should only be tried if experimenting with improving performance. See 8.2 Analysing performance for further information.

2.5.1 Tips for high performance

Microsoft Windows operating system is a cheap, familiar and convenient platform for hardware testing but requires care and preparation to achieve timing accuracy within one millisecond. To achieve the highest accuracy:

Use a fresh Windows installation with only the bare-bones installed e.g. dual-boot

Shutdown all other applications

Stop all unnecessary Windows services

Disconnect from network domains and workgroups

Disable unnecessary hardware devices – wireless adapters, blue-tooth etc.

Avoid using the machine while the test is running

Run Hardware Tests from the Bladed User Interface with “Show Hardware Test during simulation” in the Hardware Test calculation parameters unticked.

2.5.2 Hardware Selection

The turbine simulation runs in a single thread so although multiple processors allow other devices and Windows’ processes to run without influencing the turbine simulation speed, it is important that the processor itself has a high clock speed. A faster dual core machine is recommended over a slower quad-core machine.

3. REAL-TIME TURBINE SIMULATION

3.1 Introduction

The Bladed User Manual [1] describes the simulation parameters which need to be set for successful real time simulations. The text below adds further explanation and explores some of the decisions pertinent to real time turbine simulation modelling with the Bladed Hardware Test module.

3.2 Signals exchanged

The data available for exchange between the Bladed device and the Hardware Test module are identical to those available for exchange between Bladed and a Bladed DLL format external controller. The signal names are visible in the Bladed device and further documented in Appendix A of the Bladed user manual [1].

3.3 Accuracy and time step

Conventional, non real time, simulations are solved with a variable order, variable step size Runge-Kutta algorithm where the step size and solution order are determined automatically in order to meet estimated accuracy and efficiency criteria and therefore the typical Bladed user is rarely concerned with the details of the numerical solution. However, for real time operation the equations of motion are solved with a fixed step 4th order Runge-Kutta integration scheme [2] and the step length is set by the Bladed user in the Simulation Options form. Immediately it is clear that the user has direct responsibility for the accuracy and efficiency of the simulation. Too small a step will result in a simulation which cannot operate in real time (or would require more processing power to do so). Too large a step will give inaccurate or even unstable solutions. Determining the correct step size ultimately comes down to a compromise between model complexity, solution accuracy and processing power. It is not an easy calculation to make and, at present, we prefer to work together with the client in order to establish the best step size and turbine model parameters. To give a flavour for the decision making process the key issues are outlined below. • Model complexity. Clearly, the more complex is the turbine model then the more numerical operations are required to solve each time step. Key areas where model complexity can be altered are listed below.

The number of blade stations; Bladed carries out calculations specific for each blade station; fewer stations will result in a significantly faster simulation.

The number of tower stations. The number of and type of output variables; for instance aerodynamic output and load

outputs in multiple co-ordinate systems entail additional calculations. The number of and types of degrees of freedom. Each modal degree of freedom

requires additional calculations, as does the solution of drive train flexibility and complex pitch actuator dynamics. The yaw degree of freedom (if it is modelled with dynamics) also introduces a number of extra calculations.

• Solution accuracy. For a linear equation of motion set then the accuracy of the solution depends entirely on the ratio of the highest simulation natural frequency (or shortest time constant) and the solution time step. With non linear turbine equations of motion then the situation is less straightforward but, nevertheless, the highest natural frequency is still a

reasonable guide as to the step length required for stability and accuracy. With the class of differential equation problems typical with turbine simulation then an accurate solution will require a significantly shorter step length than that required for stability and it is therefore accuracy which determines the allowable step length. A shorter time step will give a more accurate solution. Whether a solution is deemed sufficiently accurate or not is difficult to pin down exactly, bearing in mind potential non linearities and the effect of scaling between state variables and the simulation outputs – it is the outputs which the user requires to be ‘accurate’, but it is the state derivatives (modal velocities and generalised forces) which are

integrated. A reasonable first choice for accuracy is to use a step size no larger than 1/(2n)

where n is the highest natural frequency (in rad/s) in the simulation. Note that it may be necessary to remove higher frequency modes or other dynamics from the simulation in order to be able to run with a time step sufficiently large to solve the model equations in real time.

3.4 Simulation results and buffering

With the real time simulation then all Bladed model results are buffered in memory and written to disk only after the simulation ends. The buffer length is specified in the Bladed Calculation Options where there is also the option for a circular buffer for saving only a period of the most recent results. The Bladed progress monitor uses temporary file IO to communicate progress from the simulation engine to the Bladed user interface and to send a user Abort request back to the simulation engine. For the real time simulation this temporary file IO is suspended and so the Bladed progress monitor will not update. To stop a simulation it is necessary to stop the current procedure from the Hardware test module user interface.

3.5 Discontinuity handling

Engineers operating Bladed for non real time simulations are used to automatic iteration and solution of discontinuous simulation events, for instance, finding the exact (to a tolerance) moment where a stick/slip friction brake disc crosses zero velocity and transitions from slipping to stuck. However, the fixed step solution method adopted for real time simulation cannot match this functionality and so, whilst it is still possible to use stick-slip friction models with real time simulation it is important to bear in mind that they may not be solved accurately and, for this reason, it is recommended that stick-slip friction models are disabled for real time simulation. The one exception to this recommendation is for the drive train shaft brakes which have special logic implemented for real time simulation which forces the brake disk speed to zero whenever the stick slip friction model is deemed to be stuck.

3.6 Simulation types and initial conditions

Bladed allows wind turbine simulations to be initiated with the turbine in any of the operational states listed below, • Parked; as for idling but with shaft brake #1 deployed (Bladed supports multiple independent shaft brakes), • Idling; generator/power converter disconnected, pitch/tip brakes at a user specified position. Initial rotor speed is determined by iteration, • Power Production; generator/power converter connected and brakes released. Initial pitch angle, rotor speed and generator torque are determined by iteration (assuming that the wind turbine configuration supports these degrees of freedom).

For Idling and Power Production simulations the initial conditions are estimated so that the simulation starts in the prevailing flow conditions with minimal transient. Initial conditions are iterated in a two step process. First, a nonlinear algorithm is used to find initial values for rotor speed, pitch angle and generator torque (assuming that these variables are degrees of freedom of the turbine model; for instance, pitch angle would not be iterated for a fixed pitch machine). Having established these basic initial parameters Bladed will calculate initial values for all the remaining simulation states, including structural deflections and velocities, and additional drive train states, with a linear iteration step. When starting in power production then the turbine simulation will post initial values for pitch angle and generator torque demand, as calculated from the iterations described above, to the Bladed device and the Hardware Test module (or whichever device is routed through it) will have an opportunity to read them and initialise its own state accordingly. The simulation will then start with values for pitch angle and generator torque as determined by the values retuned to the Bladed device in the pitch angle demand and generator torque demand values respectively. Under normal conditions it is appropriate for the Hardware Test module to initialise pitch and torque demand signals equal to the initial conditions posted by Bladed so that the simulations begins with a minimum of transient disturbance. Note that where the turbine simulation is configured with a pitch rate actuator then there is no possibility for the Hardware Test module to override the simulation initial pitch angle. Bladed simulations always start with the nacelle position initialised to 0º and this corresponds to the turbine facing due North. 0º flow direction corresponds to flow approaching from the North and therefore the default initial yaw angle is also 0º. The Bladed device has nacelle angle control inputs for demanded nacelle rate or nacelle actuator torque and therefore it is not possible for the nacelle angle to start at any value other than 0º. On the other hand, the initial flow direction is easy to set from Bladed and so this would be how to commence a simulation with a non zero yaw error. The shaft brakes, grid contactor and, if appropriate, variable slip generator rotor current, may be controller by the Bladed wind turbine simulation or by the Hardware Test module according to specific Bladed device options.

3.7 Testing Configuration

The turbine simulation appears in the Test Environment as a device with a BladedProtocol and exposes all the channels that could be required or generated by the simulation for different turbine models. Not all channels will be relevant depending on the capabilities of the turbine and the selection of sub-systems to simulate. The test author can connect the inputs and outputs to their other devices using Mappings or scripts. All simulation channels are in SI units.

3.8 Running Batch Load Cases

The standard Bladed batch facility can be used to run multiple simulations in sequence [1]. When operating sequential power production simulations then it is important to bear in mind that the Bladed turbine model will expect the turbine control system to also be operating in its power production mode right from the start of the simulation. This is not a situation that a real wind turbine controller would ever encounter. If setting the controller state is problematic then it will be necessary to interleave idling and turbine start up simulation jobs in the batch list.

4. DEVICES

4.1 Overview

A Device defines the channels available for communication with an external component and it defines the transport protocol. Data transfer from the Hardware Test Module to an external component is referred to as output or a writeable channels and data transfer from the device to the hardware test are referred to as input or readable channels.

4.1.1 Channels

The set of named channels for a component include type and description fields. A channel also includes protocol specific routing information defining how the channel is exchanged with the external component.

4.1.2 Protocol

The protocol is the mechanism which the device uses to exchange channels with the external component e.g. UDP, OPC etc. Protocols are integrated in built-in devices and plug-ins are available which can be written by users in addition to provide new protocols.

4.1.3 Mappings

Channel values can be mapped to other channels including those supplied by other devices. Mappings take advantage of the scripting engine so that mapping expressions can be composed of other channels.

4.1.4 Script

If a device needs to simulate the behaviour of unavailable hardware or perform complex behaviour to derive a channel value then an independent script can be included with the device in order to implement it. The script editor supports syntax highlighting and auto-complete.

4.1.5 Settings

The settings tab allows general configuration of the device and its protocol. The Update Rate is the frequency in Hz at which the protocol is invoked to exchange data with the external component and mappings and scripts are updated. The protocol can be changed using the Protocol drop-down on the settings page. The DataStorageConfig element of the settings tab lets you specify the action to take when the external file from which the device was imported changes. Options available are “ManualReload” where the system ignores changes to the external file, “PromptForReload” where the system notifies the user when the source file changes and “AutomaticReload” where the system reloads the device without warning when the source file changes.

4.2 Channels

Each channel is populated with the fields listed below.

4.2.1 Name

The channel name is used to reference the current channel value in expressions, mappings, procedures and test output. The name should be alphanumeric and not contain spaces.

4.2.2 Data Type

The type of a channel which can be one of:

Type IEC Equivalent Description

Boolean BOOL 1 bit – true/false

Int16 INT 16 bit signed integer

UInt16 WORD 16 bit unsigned integer

Int32 DINT 32 bit signed integer

UInt32 DWORD 32 bit unsigned integer

Single REAL 32 bit float

Double DREAL 64 bit float

Note that some protocols may only support a subset of types.

4.2.3 Usage

A channel can be recorded by ticking its Record check-box in the channel listing. This allows the channel history to be exported to Bladed Data View for post processing or csv, mdb and xml formats. The recording frequency is determined by the procedure settings and not by the protocol update rate. The Usage field of a device channel determines how it is exchanged with the external component represented by the device as listed below.

4.2.3.1 Unused

The channel is not exchanged with the external component and can not be used in scripts

4.2.3.2 Script

The channel’s routing information is ignored and the channel is not exchanged with the external component. It can however be used in scripts. This allows channels to be added to a device purely as intermediate values or parameters for scripted behaviour.

4.2.3.3 On Demand

The channel is available for scripting and only exchanged with the external component on explicit Read\Write steps in a test procedure. This requires support by the protocol to be able to read and write channels on demand. If this support exists, this setting can be used for channels that are only subject to brief interest by a test procedure. This will be more bandwidth efficient than the more common continuous read/write settings.

4.2.3.4 Read Continuous

The channel is always read from the external component at the update frequency of the device. Use this setting to: record values through-out a test; for regularly used signals in scripts and expressions; or for use in the right-hand-side of a mapping expression.

4.2.3.5 Write Continuous

The channel is always written to the external component at the update frequency of the device. Use this setting to continuously write the channel’s value to the device, for example if it is to be used in the left-hand-side of a mapping expression which will be set to a function of other channels.

4.2.4 Unit

The unit field is a text input field that may be used to record the unit specification for the channel. The value entered in this field is used by the system to derive the dimension as well as multiplication factor for conversion to SI system equivalent for the quantity represented by the channel. This information (i.e. dimension and multiplication factor for SI conversion) is then embedded into data exports from the system into the Bladed binary or text format. This additional information in the exported data then lets you better visualize the channel in question using the Bladed data view component. For example, a channel representing angular velocity may be marked as having “rpm” as its unit. Adding this additional information makes it possible for the system to add the dimension for this channel (“Angle/Time”) as well as the multiplication factor required to convert the value to its SI equivalent of “rad/s” into a data export file. The Bladed data viewer picks up this information from the export file and then lets you plot this channel in different possible units for angular velocity such as rpm, rad/s, Hz etc. If this unit information is absent from the channel definition, you would only be able to plot the values for this channel as a raw number.

4.2.4.1 Rules for unit specifications

1. The list of base units recognized by the system is contained in the file Units.config,

which you’ll find in the installation folder of your Bladed hardware test module. New base units can be added to the list by entering the base unit’s label, dimension and multiplication factor for conversion to SI equivalent to this file.

Note: The application should be restarted before newly added base units to become recognized.

2. Units that combine more than one base unit should have their base units separated

by an appropriate separator.

E.g. the unit “Nm/s”, which is composed of the base units “N”, “m” and “s” should be entered as “N.m/s”, where the “.” and “/” are used respectively as the multiplication and division symbols.

3. Units that contain exponents should be converted to their simplified forms that do not use exponents. E.g. the unit “Nm/s

2” should be entered as “N.m/s.s”.

The system displays error messages if unrecognized/illegal unit specifications are found in any of the channels defined in the plan. Such errors are shown in the “Error Messages” view which comes up when you either try to check the procedure/plan for errors or when you try to run a procedure that contains an error.

4.2.5 Routing

On the right hand-side of each channel appear custom fields required by the protocol to exchange the channel with the external component. This could be a hardware vendor specific address, a specific channel of a PCI IO card or the position in a TCP/IP packet. If the name is sufficient then no further fields will appear.

4.3 Mappings

Mappings allow selected channels of a device to be continuously set by an expression of other channels. Expressions can be any mathematical expression referencing other channels that evaluates to a value of the same type as the channel. The expression can take full advantage of the.Net framework. This allows different devices to be connected together. Channels that are set by a mapping expression and are required to be written to the external component should use the Write Continuously setting.

4.4 Script

See the section on Scripting for further information.

4.5 Synchronisation

The default behaviour is for devices to operate asynchronously from one another and update at the closest approximation of the chosen frequency that the Windows platform permits. If a more precise relationship between the timing of different devices is desired then they can be synchronised by arranging in a master-slave hierarchy. The master will be updated first followed by its slaves. Note that the master must have an update frequency that is an integral factor of its slaves otherwise the devices must be run asynchronously e.g. if a device is updated every 20ms then slaves can only be updated at N x 20ms e.g. 20ms, 40ms , 60ms etc.

4.6 Included Protocols

The Hardware test module is shipped with a number of standard protocols including UDP, OPC, OMRON FINS and internal protocols for communicating with Bladed and script devices. Use of the built-in protocols is designed to be straightforward but, at the time of writing, will require bespoke training from GL GH. The hardware test module is shipped with the following standard protocols:

- Bladed (for interfacing with Bladed turbine simulations) - Adlink (supports various AdLink data acquisition cards) - Ads (for Beckhoff PLCs) - Bachmann (for Bachmann PLCs) - DemoGui (a demonstration plug-in using a Graphical User Interface)

- Discon (for interfacing with the GL GH discrete controller dll) - Dll (a generic interface to external windows dlls) - FileStreaming (enables reading in channel values from a text file) - FINS (Omron FINS protocol) - GHUDP (a GL GH proprietary protocol over UDP, can be used to communicate with

GL GH controllers running on a PLC that supports UDP) - Internal (for data exchange between devices, internal to the bladed hardware test

module) - Matlab (supports integration with Matlab) - Mita (for Mita PLC WP4x00) - National Instruments (interfaces with various National Instruments data acquisition

cards) - NDOPC (uses the Northern Dynamics implementation of OPC, preferred over the

OPC protocol) - OPC (supports the OPC consortium’s implementation of OPC) - RealTimeGraphing (enables display of a real time graph of selected channels) - UDP (supports devices that communicate over the UDP protocol) - StateSpaceSim – lets you specify a device as a state space representation

Note that, in addition to built-in or customised protocols, the user is able to interface arbitrary hardware units via the Plug-in interface described in Section 0.

4.6.1 Installing Optional Plug-Ins

Although the Bladed Hardware Test Module ships with a collection of plug-ins that support a wide array of industry standard protocols, they are not all configured to start up by default. This is done to maintain a smaller memory footprint for the application and to provide better response to the user. All supplied plug-Ins are located in the “Optional PlugIns” folder within the Bladed Hardware Test installation folder. Users who wish to activate optional plug-ins simply need to copy it into the “PlugIns” folder within the BHTM installation root and restart the application. For example, to activate the MatLab plug-in, you would need to copy the file “GH.Controllers.Matlab.dll” from the “Optional PlugIns” folder in your installation to the “PlugIns” folder and restart Hardware Test Module. See table below for plug-in file name to device type association for the most commonly used plug-ins.

Plug-In File Name Protocol/PLC

GH.Controllers.Adlink.dll AdLink data acquisition cards

GH.Controllers.Ads.dll Beckhoff PLC

GH.Controllers.Bachmann.dll Bachmann PLC

GH.Controllers.Matlab6.dll MatLab version 6

GH.Controllers.Matlab.dll Older version of MatLab

GH.Controllers.Mita.dll Mita PLC

GH.Controllers.NationalInstruments.dll National Instruments DAQ models 6514 and 6704

GH.Controllers.NationalInstrumentsManaged.dll National Instruments DAQ models 6229 and 6238

EGDProtocol.dll GE Fanuc PLC

4.6.2 Connecting to Commonly Used Platforms

Please find below instructions for connecting to the most commonly used platforms:

4.6.2.1 Bachmann PLC

Prerequisites In order to connect to a Bachmann PLC, you will need to have the Bachmann Target Manager installed on your PC, which is part of the M1Base software package supplied by Bachmann. You will also need to have installed the optional plug-in for Bachmann PLCs. See Installing Optional PlugIns for instruction on identifying and installing optional plug-ins for different PLCs. Creating a Bachmann Device In order to connect to a Bachmann PLC, create a device and set the “ProtocolType” parameter on its “Settings” tab to “GH.Controllers.Bachmann.BachmannProtocol”. You will then need to point this device to a specific PLC by setting the target IP address of the PLC, the software module to connect to on the PLC (the name of the module that performs the control function) and also credentials for logging on to the PLC. Bachmann PLCs by default have a user named M1 with a password “bachmann”, but such credentials can and do vary in practice, so you may need to connect to the PLC using Bachmann Solution Centre to find out the appropriate credentials to use if the default credentials don’t work. The image below shows an example device that is configured to connect to a module named “WTC” on the PLC.

Figure 24 – Setting Up A Bachmann Device

Having created and configured the device, you may set up new channels for the Bachmann device from the “Device Channels” tab for the device. In addition to the standard columns that appear across all device types, Bachmann device channels have a “Bachmann Address” column that needs to be filled in appropriately for the device to work. See image below for an example channel name “S_ControllerState” that is part of the WTC module on the target PLC and has a fully qualified address location of WTC/S/S_ControllerState within the Bachmann SVI channels table.

Figure 25 – Setting Up Bachmann Device Channels

Note that we have not entered the fully qualified address into the cell for the channel. This is possible because at runtime, the device will append the name of the channel to the BachmannAddress specified if the address value ends in a “/” character, in this case producing “WTC/S/S_ControllerState” which is the fully qualified address for the channel. This also means that, if you prefer to name your channels in your plan differently to their names on the PLC, you may do so, but you’ll then need to supply their fully qualified address in the BachmannAddress column. E.g. you may choose to call the above channel “MyPLCState” and provide “WTC/S/S_ControllerState” as the BachmannAddress for it. This facility to have a level of indirection between the BHTM channel names and PLC channel names is also useful when dealing with channel names on PLCs that are not valid variable names (e.g. those that start with digits or special characters) and hence cannot be used as channel names in a plan.

4.6.2.2 Beckhoff PLC

Prerequisites To connect to a Beckhoff PLC, you will need to have the Beckhoff TwinCAT software installed and running on your PC. Having installed TwinCAT, you will also need to connect to the target PLC using the TwinCAT System Manager. Once connected to the target PLC in System Manager, use the “File” –> “Open From Target” menu item in System Manager to reset the IO streams for connecting to the target device. Having done this, close the System Manager UI. Note that you should not have both System Manager and BHTM running on the same machine at the same time. You will also need to have installed the optional plug-in for Beckhoff PLCs. See Installing Optional PlugIns for instruction on identifying and installing optional plug-ins for different PLCs.

Creating a Beckhoff Device The image below illustrates the “ProtocolType” settings and device specific settings to use with devices that represent Beckhoff PLCs.

Figure 26 – Setting Up A Beckhoff Device

The “AMS Net ID” setting should be set to the AMS Net ID for the target PLC, “Server Port Number” defaults to 301 and only need be changed if the PLC is configured to use a different port and the “Controller Task Name” should refer to the name of the controller task as recognized by the PLC. Note that this may not be the same as the name of the controller executable running on the PLC. Having set up the device configuration, create device channels by going to the “Device Channels” tab for the device. In addition to the common channel properties, Beckhoff channels have an additional column named “ADS Name” that can be left blank if the channel name used in the plan matches the ADS channel name. You may however use this column if you need to define BHTM channel names that do not match the names of the ADS channels they map to.

4.6.2.3 Mita PLC

Prerequisites You will need to have installed the optional plug-in for Mita PLCs before you can set up and configure a Mita device. See Installing Optional PlugIns for instruction on identifying and installing optional plug-ins for different PLCs. Creating a Mita Device The image below illustrates the “ProtocolType” settings and device specific settings to use with devices that represent Mita PLCs.

Figure 27 – Setting Up A Mita Device

The “Mita PLC IP Address” field should be set to the IP address of the target Mita PLC. This setting defaults to “172.16.1.2” to reflect the default setting on Mita PLCs, but note that this may need to be changed. The “Perform Scaling” setting controls whether or not Hardware Test Module will attempt to scale (up/down depending on the direction of travel of data) the Mita variables that it is dealing with. The scale factors themselves are defined at the Mita variable level in the Mita VDB (Variable DataBase). When set to “True”, the scale factors associated with VDB variables will be applied to values before reading into BHTM or writing out to the PLC. Having set up the device configuration, create device channels by going to the “Device Channels” tab for the device. In addition to the common channel properties, Mita channels have an additional column named “VDB Name” that can be left blank if the channel name used in the plan matches the corresponding channel name in the Mita VDB. You may however use this column if you need to define BHTM channel names that do not match the names of the VDB channels they map to.

5. TEST PROCEDURES

Test Procedures are sequences of steps that can set values to channels, assert conditions about the controller and wait until particular states of the controller and simulation are reached. Test Procedures can invoke other Test Procedures allowing shared reuse of test functionality between multiple test cases. Example purposes of test procedures include: • Bring a controller into a known state by setting channels within safe-limits • Invoke error conditions and verify correct response of the controller • Interact with a tester to confirm visible behaviour • Record data from connected devices A test step can either pass or fail. Procedures can be configured to continue with failures or stop.

5.1 Procedure Settings

The following procedure settings are available:

5.1.1 Name

The identifying name of the procedure which can be used by other procedures to invoke it.

5.1.2 Description

Text describing the procedure. May be used for recording procedure version.

5.1.3 Author

Name of the procedure author. Helps keep track of procedure history

5.1.4 Step Update Period

The period in seconds at which the procedure is updated. Generally this can be significantly lower than the device update rates. Rates such as 0.1s are common and rates of the order of seconds will still give a responsive procedure.

5.1.5 Ignore Errors

True if the test procedure should continue if test steps fail. False if the procedure should fail.

5.1.6 De-Initialization Procedure

The procedure to execute to reset devices to a desired state when execution of this procedure finishes (as a result of all steps having passed or a step failure or upon user request).

5.1.7 Disable Data Recording

Disable all data recording. This setting overrides the “Record” setting against individual device channels.

5.1.8 Re-sampling Method for Data Export

The type of re-sampling to apply when exporting data. Defaults to “Raw” where no re-sampling is performed and data is exported as-is.

5.1.9 Re-sampling Period

The period in seconds used for performing re-sampling. This will determine the maximum sample resolution of exported data.

5.1.10 Automatic Data Export

This option lets you automatically export the data recorded by the procedure onto the file-system during a run. This option group has entries for the data export format, export interval as well as the location for exports.

5.1.11 Show Display Names for Enumeration Channels

When set to true, the output window shoes the corresponding string values for enumerated channels. Note: Enumerated channels are those that hold numeric values that correspond to a set of strings. E.g. a controller state channel may hold state values as integers that range from 1-50 with each value representing a named state.

5.1.12 Data Storage Config

This option lets you define the action to take when the source file from which the current procedure was loaded changes. The options available are

“AutomaticReload” which causes the procedure to be reloaded without warning when the source file changes.

“PromptForReload” which notifies the user when the source file changes (default)

“ManualReload” does not monitor external files. Users may reload procedures manually by selecting the procedure to reload and accessing the “Reload Procedure” pop-up menu item.

5.2 Procedure Step Types

5.2.1 Test

A test step asserts a condition which can pass or fail. If the procedure setting “Ignore Failures” is enabled then the test procedure will record the failure but continue to process the test procedure otherwise the test will stop.

Field Description Example

Test A Boolean expression that can reference device channels and .Net functions

!ContactorOn

&&

PitchPos1 <= 1.0f

5.2.2 Timed Test

A timed test asserts a condition for a specified duration. The test passes if the condition remains true for the whole duration. If the procedure setting Ignore Failures is enabled then the test procedure will record the failure but continue to process the test procedure otherwise the test will stop.


Test A Boolean expression that can reference device channels and .Net functions

!ContactorOn

&&

PitchPos1 <= 1.0f

Duration Duration to check the expression for 5000

5.2.3 Assign

An assignment step sets a value to a device channel from an expression. The expression is evaluated at run-time and may be composed of the current values of other device channels.


Assign The channel to set PitchPos1

= An expression of device channels that

evaluates to the same type as the channel which is being assigned.

Math.Min(PitchPos2,

PitchPos3)

5.2.4 Read

If a device channel is configured as On Demand then it will be automatically read from the external component. In addition, a test procedure can explicitly request that a particular channel value is updated.


Read A string expression that evaluates to the

name of the channel to read “PitchPos” + BladeNum

From The name of the device that contains

this channel PitchSystem

5.2.5 Wait

The test procedure will wait for a period of time defined by an expression before proceeding to the next step.


Wait

The wait time in milliseconds. This can simply be a literal integer or an

expression that could reference device channels or the test time.

1000

ConnectionLull - 1000

5.2.6 Wait Until

The procedure will wait until an expression evaluates before proceeding. A maximum duration can be specified to fail the step if it takes too long.


Wait Until A Boolean expression. This step

will execute until the condition evaluates to true.

AcitvePower > 0.0f

Max Duration

The maximum time to wait. If this time elapses without the

expression becoming true then the step will fail. This is an integer expression so can either be a literal value or a mathematical

expression.

30000

5.2.7 Manual Request

A request dialog is displayed to the tester which can ask them to perform a manual action (e.g. flicking a switch) or to confirm status of the system (e.g. whether a warning light is lit) or to obtain consent before continuing the test. The message displayed to the tester is defined as a string expression so that it can include information about the current controller and simulation state e.g. “Verify that the displayed pitch is 1.78 degrees”. It is then under the tester’s judgement to pass or fail the step. The displayed dialog also allows the tester to enter a response regarding an observation which will be included in the final test report.


Manual Request A string expression that will be

displayed to the tester.

“Verify that the displayed

pitch is “ + PitchPos + “

degrees”

5.2.8 Call

This type of test step allows procedures to be nested within other procedures.


Procedure The name of the procedure to call. AssertNoErrors

5.2.9 If

A branching step of the form IF expression THEN proc1 ELSE proc2 which evaluates a Boolean expression and calls proc1 if true or proc2 if false in the same manner as the “Procedure” Step.


If PitchPos1Degreed > 45

Then The name of the procedure to call if the expression evaluates to true

PitchTo

Else The name of the procedure to call

if the expression evaluates to false

5.2.10 Script

The script step lets you insert source code into a procedure step. This step can refer to all available channels as well all making use of standard .Net classes and constructs.


Script Script to run

if (WindSpeed < 4)

{

MeanWindSpeedIncrement

+= 1;

}

5.2.11 Ramp

The ramp step lets the user ramp up/down the value of a channel in a controlled manner.


Ramp The channel to ramp WindSpeed

From The value to use as the start value

for the ramp 1

To The final value to ramp to 10

At (per sec) The rate at which to perform the

ramp 2

5.2.12 Permute

To test that related system events cause the same behaviour, e.g. confirming that 200 condition monitoring errors correctly cause a shutdown and resume after being cleared would require repetition even in the creation of the procedures. Permutation steps solve this need. A procedure may define steps that define consecutive sub-procedures to call e.g. SetTemperatureError, SetCommsError. There may be other procedure

steps before and after the permutation step with the result that the procedure is run once for each option.


Permute The procedures to use in the

permutation SetTEmperatureError;setCommsError

5.2.13 Comment

A comment is a non-functional step for adding text to clarify and explain subsequent steps and mark out different sections of a test procedure.


Comment Text to explain subsequent steps The following steps clear

all active alarm conditions

5.2.14 While Loop

The while loop step lets you introduce a loop construct into a procedure by allowing the invocation of a procedure for as long as an expression remains true. The loop will not be entered if the expression evaluates to false at the point the step is first reached.


While A Boolean expression WindSpeed < 4

Call The name of the procedure to call IncrementWindSpeed

5.2.15 Enable Assertion

The enable assertion step lets you mark the point within a procedure where you would like to start running an assertion.


Assertion Name The name of the assertion to

enable AssertGenSpeedInRange

5.2.16 Disable Assertion

The disable assertion step lets you remove an assertion from the list of assertions that are currently active.


Assertion Name The name of the assertion to

disable AssertGenSpeedInRange

5.3 Recording and Exporting Data

All recorded device channels are sampled at the update period of the device. This is not guaranteed to be a precise interval so options are provided on the procedure settings tab to resample data to a fixed interval:

Raw – data will be exported at the potentially uneven period as recorded on each device update step

ResampleToDevicePeriod – data will be resampled to an integral starting second and at the Update Period specified in the device settings. Note that each device may have a different Update Period.

ResampleToProcedurePeriod – data will be resampled to an integral starting second and at the Resampling Interval specified in the procedure settings

Resampling is only applied at the point of exporting data so one can export the same data using different resampling methods by changing the procedure settings before each export.

5.3.1 How to export data

If running with a turbine simulation, Bladed results files are automatically exported to the output folder specified by the main Bladed user-interface. If starting a test procedure from the Hardware Test toolbar, they must be explicitly exported by selecting the chosen output window and exported from either:

The output menu

Right-clicking on the results in the Plan Explorer

Right-clicking on the result window tab

Right click here OR here

Figure 28 – Data Export

5.3.2 Output Formats

Data can be exported in the following formats:

Row Text - Text file containing all devices with a row for each channel. Column Text - Text file containing all devices with a column for each channel. Mdb - An access database containing a table for each device. Xml – An xml file containing an element for each sample from each device Bladed Binary Files – A file-set which can be loaded by the Bladed data-view. Consists of a header file with extension % and a binary data file with extension $ for each device. Bladed Text Files – A file set as above but with ASCII text data files Matlab Binary Files – a binary .mat file for loading into Matlab Excel Workbook – An xml file for loading into Microsoft Office Excel

5.3.3 Automatic Data Export

In addition to the manual data export detailed above, users also have the option to request automated data export at desired intervals in a chosen format to a specified location on the file system. This feature can be enabled by using the “Automatic Data Export” option group available in the procedure settings tab.

5.3.4 Opening Test Results in Bladed DataView

In addition to being able to export test data in the Bladed format to the disk, you may also directly open test results from Bladed Hardware Test Module in the Bladed DataView. In order to do this, right click on either the output view or on test result in the plan explorer and choose “Open in Bladed DataView”

Right click here OR here

Figure 29 – Open in Bladed DataView This option will first export the results to a temporary location on the disk and open it up for immediate viewing using the Bladed DataView. Note: You do not need to have Bladed installed on your machine in order to access this feature. The DataView component used here is bundled with Bladed Hardware Test Module.

5.4 Reporting

The reporting mechanism uses an XSLT template to format the xml plan file to create html compatible with MS Word. The default template can be edited to change the format and include user specific details.

5.4.1 Report Settings

Report generation settings can be accessed from the “Plan Settings” section of the “Settings” screen.

Report Generation

Settings

Figure 30 – Report Settings

The following configurable parameters control report generation:

Generate report after each procedure execution – lets you request the system to

automatically produce a report after each procedure run. This flag defaults to false.

Report Template for Procedures – The XSLT template file to use when generating

procedure reports (applies to auto-generated reports created by the system when the flag above is set to True).

Report template for plans - The XSLT template to use when generating a report for a

plan. This template applies to reports that are generated upon user request (as opposed to the auto-generated ones).

Location of additional files for reports templates – A folder that holds additional files

that may be referenced by report templates. This location may hold files which could be embedded into the reports such as company logos, icons for representing states etc.

Report output location – specifies the folder to write the report file into.

5.4.2 Reporting Modes

There are two separate types of reports that can be generated from within the Bladed Hardware Test Module. Plan Report Plan reports can be generated from the Menu->Plan->Generate Report menu item. Plan reports include details of all the procedures and devices present in the test plan and indicate the states of procedure steps in each procedure.

The XSLT template used to generated this report is specified by the “Report template for plans” parameter in the “Report Generation Config” setting.

Procedure Report A procedure report may optionally be automatically generated at the end of each procedure

run. The “Generate report after each procedure execution” flag within “Report

Generation Config” setting group determines if automated report generation is enabled. When enabled, the system produces a time-stamped report file at the report output location

using the XSLT file specified by the “Report Template for Procedures” setting.

By default, such reports will have information about all devices configured, step details from the procedure that triggered the report generation and an execution summary. Step states from any sub procedures called by the parent procedure are also pulled into this report to provide a hierarchical view of the list of executed steps and their time of execution. In addition to the step states, an execution summary is provided for each device in the plan. This summary indicates the update period for the device, total number of updates and statistics such as the min, max, mean and standard deviation of the actual update periods and execution durations achieved during the run. Such statistics can be used to determine the real time performance of the run. See the section Analysing performance for details on analysing real time performance of hardware test module runs.

6. ASSERTIONS

6.1 Overview

An assertion lets you evaluate an expression continually in the background while running a test procedure. This lets you verify that parameters remain within their operational/design limits throughout a defined period of the test run.

6.2 Assertion Expression

The assertion expression defines the criteria to be checked on every evaluation of the assertion. These expressions may be built up using any combination of the various channels exposed by the devices. You may also use valid constants and math functions available from the .Net system library. The only constraint is that the expression must evaluate to a boolean value. For example, a simple assertion to check that the generator speed remains within its range could have an expression “MesasuredGenSpeed < 1850” where “MeasuredGenSpeed” is a readable channel on a device within the plan that provides the current generator speed measurement in rpm and “1850” is the desired upper limit to check against.

6.3 Assertion Failure Actions

The ability to define a failure action for an assertion lets the user decide on a per assertion basis what should be effect of a failed assertion. The options available are: Fail Test: This is the default failure action for all newly created assertions. This failure action causes the current procedure that is running to fail immediately unless the procedure setting to “Ignore Errors” is set to true. In case “Ignore Errors” is in force, then the procedure keeps running till the end and shows a failed status after all the procedure steps have been performed. Print Warning: This failure action produces a warning message to appear in the output window of Bladed Hardware Test identifying the assertion failure. Procedure state remains unaffected. Set Variable: The set variable action lets you set the value of a variable when an assertion fails. You may choose any of the variables from the drop-down list associated with this action to identify the target variable. An expression that returns a value that is the same data-type as the variable should also be provided. As with all other expressions, this expression too can use other variables, constants and math functions. Call Procedure: The call procedure action lets you call another procedure when an assertion fails. All procedure within the plan are available for such calls. However, care must be taken to avoid unwanted recursions from being setup by such procedure call loops that could form as a result.

6.4 Assertion Life Cycle

All assertions that are defined within a plan remain in the idle state until explicitly enabled by a procedure step. In the idle state they are not

evaluated. Assertions may be moved into an active state by including an “Enabled Assertion” step within a procedure at the point where you want the assertion to start checking its criteria. For example, you may start up your test, perform initializations and then turn on the assertions to check the systems operational boundaries are not breached. Assertions are referred to by the “Enable Assertion” steps by their name. Once enabled, an assertion gets added into a list of active assertions and gets evaluated before each procedure step execution cycle until it fails. When a failure is detected, the assertion is marked as failed and removed from the active list. The pass/fail status of assertions is visually indicated on the “Plan Explorer” view by colour coded icons. Idle assertions show up with a grey icon, which then changes colour to green when they are enabled and passing. Failed assertions are indicated by a red icon. This lets you identify the assertions that were in force while the test ran and also identify the ones that passed for the whole duration and the ones that failed. The “Disable Assertion” procedure step type may be used to explicitly remove an assertion from the active assertions list. The assertion is removed from the active list at the point of execution of the “Disable Assertion” step.

7. SCRIPTING

Scripts are code fragments written in the C# .Net language. Scripts used within the Hardware Test fall into two categories: expressions that evaluate to a value and statement sequences which do not return a value and can contain constructs like loops. Expressions are used in Device Mappings and Test Steps for assignments and conditions whereas statements can be used to perform more complex multi-line operations in a Device Script or Script Step. The Hardware Test is type-safe so assignments between different types are not permitted. Setting a 32 bit real with a 64 bit real would create an error. Instead one must explicitly use a casting operator to prove the loss of information is intentional. Real number literals e.g. 1.5 are by default 64 bit whereas as 32 bit reals use an extension 1.5f.

7.1 Built-in Constants and Variables

The following built-in variables are provided by the test engine and can be used within any scripts.

Name Type Description

time int

The time in milliseconds since the test began.

BladedInFile Object

The bladed in file contains all the relevant information about the bladed turbine model for the simulation. This information can be accessed within scripts using this

object. The in file is organised into modules with named values.

BladedInFile[“Module”].GetType(“ValueName”)

e.g. to access the simulation duration, the module is

SIMCON and the value ENDT double endtime =

BladedInFile[“SIMCON”].GetDouble(“ENDT”);

DeviceUpdatePeriods

Dictionary

The device update periods dictionary holds the update periods for all devices in the plan. The dictionary is keyed

on device names. This dictionary makes it possible for user scripts to easily access the device update period for

use in calculations. For example, update period for a device name “My Controller” may be accessed using the expression DeviceUpdatePeriods[“My Controller”];

You may use this expression to store the update period’s value into a variable for use within scripts.

DeviceProtocolTypes

Dictionary

The device protocol type dictionary holds the protocol type for all devices in the plan. The dictionary is keyed on device names. Values in the dictionary indicate the

unqualified name of the protocol class for the device. E.g. for a device that uses the

“GH.Controllers.InternalProtocol”, the dictionary value would be “InternalProtocol”.

Filters Dictionary

A dictionary of filter functions available for use in the procedure being run. Users will need to create and add

new filters to this collection in order to be able to use them. A set of filter function implementations are available

by default in the product. See “Filter” functions for more details.

Built in values can also be added by plug-in authors.

7.1.1 Using Filter Functions in Scripts

Bladed Hardware Test Module provides users with the ability to apply filter functions to input signals within device scripts. The following built in filter functions are available:

Filter Name Parameters for construction

Description

DiffFilter

<None> Outputs the difference between the current value and the last value

FilteredDifferenceFilter

double timeStep, double timeConstant, double gain = 1.0F

FirstOrderFilter

double timeStep, double tau

A first order filter

GainFilter

double timeStep, double gain

Lets you apply a gain factor to the input signal

LeadLagFilter

double timeStep, double tauA, double tauB

A lead-lag compensator

LimitFilter

double timeStep, double lowerLimit = double.NegativeInfinity, double upperLimit = double.PositiveInfinity

Lets you apply a lower and/or upper limit to a signal. The lower and upper limit values are optional and are initialized with Infinity when not specified

MaximumOverPeriodFilter double timeStep, double time

A buffered filter to choose the maximum value over a period

MinimumOverPeriodFilter

double timeStep, double time

A buffered filter to choose the minimum value over a period

MovAvgFilter double timeStep, double timeConstant

A moving average filter, with a weight is defined by its timeStep and timeConstant

MovAvgAsymFilter

double timeStep, double timeConstantUp,

A moving average filter which can be setup to use

double timeConstantDown, double rateLimitUp, double rateLimitDown

different time constants as well as rate limits for +ve and -ve changes

NegEdgeFilter

<None> A negative edge filter

PosEdgeFilter

<None> A positive edge filter

RateOfChangeFilter

double timeStep, double timeConstant

Returns the rate of change averaged using a weight determined by timeStep and timeConstant

RmsAvgFilter

double timeStep, double timeConstant

Root Mean Square averaged using weight determined by timeStep and timeConstant

TrueDurationFilter

double timeStep Duration for which the value of a boolean channel has remained true

UnchangedDurationFilter

double timeStep Returns the duration since the last change in value (calculated as the number of unchanged samples * timeStep)

WrapPiFilter

<None> Wrap the input angle to the range –PI to PI

Wrap2PiFilter

<None> Wrap the input angle to the range 0 to 2*PI

In order to use a filter function within your script, you’ll first need to create an instance of the type of filter you’d like to employ and store it on the script engine’s Filters collection. You will then be able to apply this filter object to filter input signals. The following snippet shows an example of how to use a built in filter to get a moving average

of an input channel named “InputChannel” into an output channel named

“AvgOutChannel”. The moving average filter in this case is constructed with a weight (i.e.

timeStep/timeConstant) of 0.5. Device Channel Configuration: Initialized Boolean false

InputChannel Single 0.0

AvgOutChannel Single 0.0

Device Script:

if (!Initialized)

{

Filters.Add(“MyAvgFilter”, new MovAvgFilter(1,2));

Initialized = true;

}

AvgOutChannel = Filters[“MyAvgFilter”].Filter(InputChannel);

7.1.2 C# Quick Reference

Logic &&, ||, !, ==, <, >, >=, <=

Inline if (expr) ? if_true : if_false Bitwise |, &, &=, |= String Concatenation + Math operators +, -, *, \, % Math functions Math.Abs, Math.Min, Math.Max, Math.Cos etc. Math constants Math.Pi

Assignment =, +=, -=, *=, \= For Loop for (init, expr, incr) {} While Loop while (expr) {} do {} while (expr)

Casting between types (short), (ushort), (int), (uint), (float) etc. The full .NET framework is available for use in scripts which includes advance string operation, file handling, bit manipulation. See [5] for the full documentation.

8. ADDITIONAL TOOLS

8.1 Search and Replace

Search and replacements can be carried out within devices and procedures by clicking on the search toolbar button or by pressing ctrl-f or ctrl-h key combinations. Searches begin from the active cell if a spreadsheet component is currently visible. Users can limit the scope of the search operation to “Procedures”, “Devices” or choose to search the entire Plan. Searches can use regular expressions as replacements which allow the use of matching sub-expressions e.g. Text to search: ThisIsAChannel Find RegEx: (T…)(IsA)(.*) Replace RegEx: $3$2$1 Result: ChannelIsAThis For full regular expression syntax, see Reference [4] for further information.

8.2 Analysing performance

There are five ways to analyse real-time performance:

8.2.1 Update Period and Execution Duration

Update Period and Execution Duration channels are recorded for each device to help assess performance. These can be plotted with the Bladed Data View. The Update Period shows how effectively the device timing demands are being met. To achieve reliable performance one should aim to for Execution Duration to be stay below 50% of the update period. The graph below shows a run with up to 75% utilisation. The 3 ms timing goal is generally very well observed but there is a missed interval at 38s. Increasing the device Update Period or simplifying the device will help minimise missed intervals.

Figure 31 - Example of a missed interval

8.2.2 Calculation time

When running a simulation, the bladed calculation window appears and displays the current simulation time. An early indication of non-real-time behaviour can be determined if the displayed time of the bladed calculation is evidently slower than real-time.

8.2.3 Plotting Current Time

The CurrentTime channel of Bladed can be recorded from the Bladed Device allowing it to be plotted with the Bladed Data View to reveal performance during the test.

Any bumps indicate that there are interfering processes on the test machine that should be investigated before continuing testing.

If at the end of the simulation the simulation CurrentTime is not equal to the real test time (x-axis) then this indicates there had been drift and the simulation is not running in real time.

Figure 32 - Example plot of Simulation time to evaluate real-time performance

8.2.4 Performance counters

Performance counters are created by the hardware test for each test run. They can be and viewed with the Windows utility PerfMon by typing perfmon.exe in StartMenu->Run and then adding the performance counters from the category "Bladed Hardware Test". The available performance counters for each device are:

‘Device Update Rate’ - the update frequency of the device in Hz ‘Device Update Time’ - the time a single update of a device takes to execute in

Milliseconds The captured data can be used to determine the relative computational cost of each device and help in evaluating user created plug-ins.

Figure 33 - Example log of performance counters during a simulation

8.2.5 Turbine model Accuracy

As discussed in Section 3.3, performing real time simulation brings with it a responsibility on the user to ensure that the solution is progressed with sufficient accuracy. The classic means of determining accuracy in this context is to repeat simulations with a smaller time step and verify that the results are not significantly altered. Beyond this general statement it is difficult to give any definitive guidelines but the user is advised to check some specific Bladed outputs as listed below.

Inaccuracies are likely to be most apparent in the highest frequency simulation mode; assuming that the user has avoided fast actuator and sensor dynamics then, typically, the fastest mode is an in plane rotor or drive train mode. Erratic blade tip acceleration and generator speed signals are, respectively, a good indicator of poor rotor modal or drive train solution accuracy.

Where drive train dynamics are included in the turbine model (i.e. it is not a ‘locked speed’ transmission model) then the user should compare the ‘Rotor hub Mx’ from either of the two ‘hub loads’ Bladed results groups with the ‘Gearbox torque’ from the ‘Drive train’ results group. These two quantities should be very close if not identical but Bladed calculates them in different ways and significant discrepancies between them indicate an inaccurate solution.

For models with grid connected induction generators it is also useful to check the electrical power output as, for low slip generators, it is very sensitive to small solution errors.

9. HOW TO AND TIPS

9.1 Keyboard shortcuts

Key combination Action Applies To

Ctrl-s Save Plan All

Ctrl-c, Ctrl-v, Ctrl-x Copy, Paste, Cut Selected text, Procedure Steps

Delete, Back Delete the current selection Device Channels, Device Mappings, Procedure Steps, Plan Explorer and Scripts

Ctrl-f, Ctrl-h Show search and replace All

Ctrl-z Undo Device Channels, Device Mappings, Procedure Steps and Scripts

Ctrl-y Redo Device Channels, Device Mappings, Procedure Steps and Scripts

Ctrl-Up Arrow, Ctrl-Down Arrow

Move the selected procedure step Up/Down in the list

Procedure Steps

Ctrl-e Display the error messages dialog

All

Ctrl-i Insert a new procedure step or a device channel

Device Channels, Procedure Steps

Ctrl-p Open a new plan Plan Explorer

Ctrl-n Create a new procedure Plan Explorer

Ctrl-d Create a new device Plan Explorer

Ctrl-a Create a new assertion Plan Explorer

Ctrl-l Load device Plan Explorer

Ctrl-b Compile procedure Procedure Steps

Ctrl-g Run procedure Procedure Steps

9.2 Use Utility Procedures

It can prove effective to create procedures that perform useful tasks such as bring an external controller into a known state or clear alarm conditions that can then be reused at the beginning of procedures that implement actual test cases.

9.3 Smoothly ramp a channel

Add device channels to administer the ramp e.g. DirectionRampEnabled Boolean False DirectionRampRate Double 0.1 DirectionBeforeRamp Double 0.0 TimeBeforeRamp Int32 0 Add the following into the Script tab of the device: if (DirectionRampEnabled)

{

WindDirection = DirectionBeforeRamp +

(DirectionRampRate * ((time - TimeBeforeRamp) / 1000.0));

}

else

{

TimeBeforeRamp = time;

DirectionBeforeRamp = WindDirection;

}

The ramp can now be enabled\disabled within a Test procedure by adding Assign steps which set DirectionRampEnabled to true or false

9.4 Command Line

Test procedures and plans can be executed from the command line allowing integration with other automated tools. Type GHTestEnv ? at the command line for further information.

9.5 File formats

The Test Plan, Procedure and Device project files are xml text files so can be easily generated from an exiting plc project file or spreadsheet. Open up an existing Plan and the schema will be clear.

10. PLUG-INS Bladed Hardware Test supports client written protocols that seamlessly integrate into the user interface and file formats. A protocol is responsible for reading and writing the set of channels defined by a device. This is typically as an interface to hardware but can also allow client written simulations, visualisations and custom user interfaces to be integrated with the Bladed Hardware Test module. Plug-ins can be written in any .Net language (C#, VB 2005, JScript.Net, J#, C++\Cli) using the free Express versions of the Microsoft development environments. GL GH can provide training for interfacing with non .Net languages if necessary. A plug-in author needs to carry out the following tasks

1. Create a .Net dll project referencing the GH.Controllers.PluginInterface.dll assembly 2. Extend the GH.Controllers.Plugininterface.Protocol class

a. Add properties for configuring the protocol b. Implement Initialise, OnStart and Update methods

3. Extend the GH.Controllers.Plugininterface.ProtocolVariable class a. Add addition fields required by their protocol b. Implement Marshall, Unmarshall and Clone methods

4. Copy the compiled dll and any dependencies to the Hardware Test plug-in folder

All public browsable properties of the plug-in classes will be viewable and editable in the Test Environment. All read\write properties will be saved in the .Plan file. Enumerated fields will be displayed as drop down lists.

Figure 34 - Protocol and Variable class diagram

10.1 Protocol Processing

Protocol processing is separated into initialisation and running. Initialisation can occur during syntax checking of a plan so it should not attempt any resource sensitive operations such as connecting to external hardware. Running involves a single call to OnStart and OnStop at the start and end (irrespective of errors) and continuous calling of OnUpdate in between.

Initialise

PreCompileExecute

Assignments

Execute

Scripts

OnUpdateOnStopReset

OnStart

Editing Mode

Initialisation Running

Figure 35 - Protocol Processing Sequence

10.1.1 Reset

public abstract void Reset()

Optional method to reset before initialisation.

10.1.2 Initialise

public abstract void Initialise(

Hashtable onDemandVariables,

Hashtable continuousReadVariables,

Hashtable continuousWriteVariables)

The protocol channels for reading and writing are provided to the plug-in in collections for each usage type and hashed by name. The protocol is expected to validate any routing information and the settings of the protocol during initialisation and to throw a meaningful exception if there are any problems e.g. bad routing information or unsupported data types.

10.1.3 PreCompile

public virtual void PreCompile(IScriptEngine scriptEngine)

Optional method for advanced use. Implement this method to bind custom data and scripts into the script engine which can then be accessed in test and device scripts. Call

scriptEngine.Bind(). If you decide to override this method, you’ll need to add

GH.Wolverine.Util.Infrastructure.dll to your plug-in project’s references list.

10.1.4 OnStart

public abstract void OnStart(IDevice device)

The protocol should perform any initialisation required to connect to the device e.g. opening ports, loading dlls etc.

10.1.5 OnUpdate

public abstract void OnUpdate()

OnUpdate is called at the update frequency of the device. The protocol is expected to implement this method to poll, send data to external hardware or check connection health.

10.1.6 OnStop

public abstract void OnStop()

OnStop is called once the test has completed, been stopped or an error has occurred. The protocol should disconnect from external hardware and clean up any resources in a safe manner.

10.1.7 Read

public abstract void Read(ProtocolVariable readVariable)

This method will be triggered by any attempt to perform an OnDemand Read of a channel in a test procedure. The protocol should handle this as appropriate e.g. throwing an error if on demand reads are not supported or sending the explicit read request to the external hardware.

10.1.8 Write

public abstract void Write(ProtocolVariable writeVariable)

This method will be triggered by any attempt to perform an OnDemand Write of a channel in a test procedure. The protocol should handle this as appropriate e.g. throwing an error if on demand writes are not supported or sending the explicit write request to the external hardware.

10.1.9 WriteLock

public virtual void WriteLock(ProtocolVariable writeVariable)

Only needs to be implemented if there are bidirectional channels. If a channel is bidirectional, it might be continuously read but allow data to be written on demand as well. In this case, it is important that the data is not overwritten by the protocol before the on demand write has completed. Before a Write On Demand request, WriteLock will be called to give the protocol

the opportunity to freeze updates until the write has completed. Bidrectional channels are not recommended due to this additional complexity.

10.1.10 CreateVariable

public abstract ProtocolVariable CreateVariable();

The protocol must return a new instance of the protocol specific ProtocolVariable class. This is used as a factory method for use by the user interface.

10.2 Xml Serialisation

The Protocol and ProtocolVariable implementations must serialise automatically to xml to allow their configuration to be saved within test plans. For most cases, this will happen without effort and all public fields and properties will be included. There are however some features that can prevent this and need to be avoided including:

Missing default constructor

Nested classes

Recursive data-structures

Incompatible datatypes e.g. TimeSpan

Null fields. Ensure all fields are instantiated by default. If incompatible properties must be added then they should be marked the [XmlIgnore] attribute and extra properties added which represent the same information in a serialisable form.

10.3 User Interface Integration

All browsable properties of the plug-in classes will be viewable\editable in the Test Environment. All read\write properties will be saved in the .Plan file. Enumerated fields will be displayed as drop down lists. The custom fields are displayed on the following screens:

Figure 36 - Example Custom Protocol Fields

Figure 37 - Example Custom Protocol Variable Fields

The default display is sufficient for basic field types (ints, floats, strings, DateTimes etc) but it is possible to further configure how the protocol fields will be displayed using attributes. The following .Net attributes:

Attribute Purpose

[DisplayName("My name")] Define a more elegant display name

[ReadOnly] Prevent editing

[Browsable(false)] Hide

[TypeConverter(...)] Perform custom configuration for a property

GL GH also provides the following attributes:

Attribute Purpose

[GH.Util.CellDisplay(...)] Configure colour, alignment and column width

[PropertyOrder(4)] Define a specific display order

It is also possible create custom editors such as file-browsing dialogs by extending the System.Drawing.UITypeEditor. See [3] for further details.

10.4 Tracing

A plug-in author can write errors and status information to the message window of the hardware test using the Apache log4net framework as shown in the samples. Reference the supplied log4net assembly and call Debug\Info\Warn\Error.

10.5 Samples

A number of sample projects are provided that demonstrate plug-ins in different languages:

Name Language Description

SkeletonCSharp C# A template project

SkeletonVB VB A template project

SkeletonCPP C++ A template project

REFERENCES [1] Bladed User manual, Version 3.72, Garrad Hassan document 282/BR/010, July 2006 [2] ‘Numerical Recipes in C++’ Second Edition, Press et al, Cambridge University Press,

2002. [3] MSDN : ‘User Interface Type Editors Overview’

http://msdn2.microsoft.com/en-us/library/ms171839(VS.80).aspx [4] MSDN : ‘.NET Framework Regular Expressions’

http://msdn2.microsoft.com/en-us/library/aa719739(VS.71).aspx [5] MSDN : ‘C# Documentation’

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/cpref_start.asp

http://msdn2.microsoft.com/en-us/library/ms171839(VS.80).aspx

http://msdn2.microsoft.com/en-us/library/aa719739(VS.71).aspx

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/cpref_start.asp

Bladed Hardware Test User Manual

Documents

Transcript of Bladed Hardware Test User Manual