This website uses local storage to ensure you get the best experience on our website.

Table of Contents

Swap Array Interface Definition

The following describes in detail the communication between Bladed and the user’s external controller code.

Data Exchange Records

External controllers compiled as EXE files exchange information with the Bladed simulation through a shared binary file consisting of a number of 4-byte records. External controllers compiled as DLLs exchange information through an array passed as the first argument to the DLL. The structure of the binary file used for EXEs and the array used for DLLs is similar and is described in the tables which follow. The type of each record of the file or element of the array may be integer, real or character, as specified in Table 1. In the EXE case, the 4-byte records in the file should be written to and/or read in as 4-byte integers, 4-byte (single precision) real (i.e. floating point) numbers, or groups of 4 characters as appropriate. In the DLL case, all the array elements are passed as real numbers, so if an element is described as type Integer, the real number must be converted to the nearest integer (and integers being sent back to the simulation must be converted to real values). Character variables are passed in separate arrays in the DLL case.

Table 1 shows the array elements or binary file records which are used for data exchange between the Bladed simulation and the external controller. As shown by the ‘Data flow’ column, some records pass information from the simulation to the controller. Conversely, some pass information from the controller back to the simulation. A few elements are used for two-way communication.

The first binary file record or array element is referred to as record or element number 1. This should not be confused with zero-based indexing adopted by certain programming languages.

Note the strict use of SI units for all variables.

The array element definitions listed in Table 1 remain fixed always. Some of the parameters passed from the simulation to the controller are constants defined in the Control Systems window. Some are variables such as measured signals. Some are only relevant for certain types of controllers such as fixed or variable speed, stall or pitch control, and pitch position or pitch rate actuators. Although the record numbers are always the same the user-defined controller need only make use of those parameters which it actually requires, and only needs to output the demands which are relevant for the particular case, for example:

  • demanded pitch angle(s) for pitch regulated machines with pitch position actuator

  • demanded pitch rate(s) for pitch regulated machines with pitch rate actuator

  • demanded generator torque for variable speed machines

  • demanded nacelle yaw rate if the external controller option was selected for active yaw with yaw rate control

  • demanded yaw actuator torque if yaw torque control was selected.

The controller may, if desired, change the status of the generator contactors and the brake.

Table 1 - list of elements in array and definitions
Record number Data flow2 Data type3 Description Units Equivalent External Controller API function
1 in I Status Flag [-] GetSimulationStatus, SetSimulationStatus
2 in R Current time s GetSimulationCurrentTime
3 in R Communication interval s GetCommunicationInterval
4 in R Blade 1 pitch angle rad GetMeasuredPitchAngle, GetCollectivePitchAngle, GetCollectivePitchRate
5 in R Below-rated pitch angle set-point4 [-] GetBelowRatedPitchAngleSetPoint
6 in R Minimum pitch angle4 rad GetMinimumPitchAngle
7 in R Maximum pitch angle4 rad GetMaximumPitchAngle
8 in R Minimum pitch rate (most negative value allowed) rad/s GetMinimumPitchRate
9 in R Maximum pitch rate rad/s GetMaximumPitchRate
10 in I 0 = pitch position actuator, 1 = pitch rate actuator [-] GetPitchActuatorType
11 in R Current demanded pitch angle rad GetDemandedPitchAngle
12 in R Current demanded pitch rate rad/s GetDemandedPitchRate
13 in R Demanded power 5 W GetDemandedPower
14 in R Measured shaft power6 W GetMeasuredShaftPower
15 in R Measured electrical power output W GetMeasuredElectricalPowerOutput
16 in R Optimal mode gain5,7 Nms$^2$/ rad$^2$ GetOptimalModeGain
17 in R Minimum generator speed 5 rad/s GetMinimumGeneratorSpeed
18 in R Optimal mode maximum speed5 rad/s GetOptimalModeMaximumSpeed
19 in R Demanded generator speed above rated 4 5 rad/s GetReferenceGeneratorSpeedAboveRated
20 in R Measured generator speed rad/s GetMeasuredGeneratorSpeed
21 in R Measured rotor rad/s GetMeasuredRotorSpeed
22 in R Demanded generator torque above rated 6 Nm GetReferenceGeneratorTorqueAboveRated
23 in R Measured generator torque 6 Nm GetMeasuredGeneratorTorque
24 in R Measured yaw error 8 rad GetMeasuredYawError
25 in I Start of below rated torque speed lookup table \(=R\) 6 7 Record Number AppendGeneratorSpeedTorqueValuePair, ClearGeneratorSpeedTorqueValues, GetGeneratorSpeedValue, GetGeneratorTorqueValue
26 in I Number of points in torque-speed lookup table \(=N\) 6 7 [-] GetNumberOfGeneratorSpeedTorqueValues
27 in R Hub wind speed 8 m/s GetHubFlowSpeed
28 in I Pitch control: 0 = collective, 1 = individual [-] GetPitchControl, enum PITCH_CONTROL
29 in I Yaw control: 0 = yaw rate control 1 = yaw torque control [-] GetYawControl, enum YAW_CONTROL
30-32 in R Blade 1-3 root out of plane bending moment 9 10 Nm
33 in R Blade 2 pitch angle rad GetMeasuredPitchAngle
34 in R Blade 3 pitch angle rad GetMeasuredPitchAngle
35 both I Generator contactor 11 [-] GetGeneratorContactor SetGeneratorContactor, enum GENERATOR_CONTACTOR
36 both I Shaft brake status: 0=off, 1=Brake 1 on 1 [-] GetShaftBrakeStatus, SetShaftBrakeStatus
37 in R Nacelle angle from North rad GetNacelleAngleFromNorth
38-40 out Demanded aileron angle when combined with pitch, blade 1 -3 SetDemandedAileronPitchAngle GetMeasuredAileronPitchAngle
41 out R Demanded yaw actuator torque 12 13 Nm SetDemandedYawActuatorTorque, SetOverrideYawRateWithTorque
42 out R Demanded blade 1 individual pitch position or rate 14 15 rad or rad/s SetDemandedPitchAngle, SetDemandedPitchRate
43 out R Demanded blade 2 individual pitch position or rate 14 15 rad or rad/s SetDemandedPitchAngle, SetDemandedPitchRate
44 out R Demanded blade 3 individual pitch position or rate 14 15 rad or rad/s SetDemandedPitchAngle, SetDemandedPitchRate
45 out R Demanded pitch angle (Collective pitch) 14 rad SetDemandedCollectivePitchAngle
46 out R Demanded pitch rate (Collective pitch) 14 rad/s SetDemandedCollectivePitchRate
47 out R Demanded generator torque Nm SetDemandedGeneratorTorque
48 out R Demanded nacelle yaw rate 12 13 rad/s SetDemandedYawRate
49 out I Message length OR -M$_0$ 16 [-] ReportInfoMessage, ReportWarningMessage, ReportErrorMessage
49 in I Maximum number of characters allowed in the “MESSAGE” 17 [-]
50 in I Number of characters in the “INFILE” argument 17 [-] GetInputFilepath
51 in I Number of characters in the “OUTNAME” argument 17 [-] GetOutnameFilepath
52 in I DLL interface version number (reserved for future use) 17 [-] GetDllInterfaceVersion
53 in R Tower top fore-aft acceleration m/s$^2$ GetMeasuredTowerTopForeAftAcceleration
54 in R Tower top side to side acceleration m/s$^2$ GetMeasuredTowerTopSideSideAcceleration
55 out I Pitch override 18 [-] GetPitchOverrideStatus, SetPitchOverrideStatus, enum OVERRIDE_STATUS
56 out I Torque override 18 [-] GetTorqueOverrideStatus, SetTorqueOverrideStatus, enum OVERRIDE_STATUS
57-59 Reserved
60 in R Rotor azimuth angle rad GetMeasuredRotorAzimuthAngle
61 in I Number of blades [-] GetNumberOfBlades
62 in I Maximum number of values which can be returned for logging 17 [-]
63 in I Record number for start of logging output 17 [-]
64 in I Maximum number of characters which can be returned in “OUTNAME” 17 [-]
65 out I Number of variables returned for logging 19 [-] GetNumberOfIndexedUserVariables
38-40 out Measured aileron angle when combined with pitch, blade 1-3 GetMeasuredAileronPitchAngle
69-71 in R Blade 1-3 root in plane bending moment 9 Nm GetMeasuredBladeInPlaneBendingMoment
72 out R Generator start-up resistance for logging ohm/ phase SetGeneratorStartupResistance
73 in R Rotating hub My (GL co-ords) 9 Nm GetMeasuredRotatingHubMy
74 in R Rotating hub Mz (GL co-ords) 9 Nm GetMeasuredRotatingHubMz
75 in R Fixed hub My (GL co-ords) 9 Nm GetMeasuredFixedHubMy
76 in R Fixed hub Mz (GL co-ords) 9 Nm GetMeasuredFixedHubMz
77 in R Yaw bearing My (GL co-ords) 9 Nm GetMeasuredYawBearingMy
78 in R Yaw bearing Mz (GL co-ords) 9 Nm GetMeasuredYawBearingMz
79 out I Request for loads 9 [-]
80 out I 1 = Variable slip current 1 demand at position 8 20 [-] GetVariableSlipStatus, SetVariableSlipStatus, enum VARIABLE_SLIP_STATUS
81 both R Variable slip current demand 20 A GetVariableSlipCurrentDemand, SetVariableSlipCurrentDemand
82 in R Nacelle roll acceleration 9 rad/s$^2$ GetMeasuredNacelleRollAcceleration
83 in R Nacelle nodding acceleration 9 rad/s$^2$ GetMeasuredNacelleNoddingAcceleration
84 in R Nacelle yaw acceleration 9 rad/s$^2$ GetMeasuredNacelleYawAcceleration
85-89 Reserved
90 in R Real time simulation time step s GetRealTimeSimulationTimeStep
91 in R Real rime simulation time step multiplier [-] GetRealTimeSimulationTimeStepMultiplier
92 out R Mean wind speed increment 21 m/s SetMeanWindSpeedIncrement
93 out R Turbulence intensity increment 21 % SetTurbulenceIntensityIncrement
94 out R Wind direction increment 21 rad SetWindDirectionIncrement
95-96 Reserved
97 in I Safety system number that has been activated [-] GetActiveSafetySystemNumber
98 out I Safety system number to activate [-] SetActiveSafetySystemNumber
99 in I Start of pitch actuator torque \(=P\)
100 in I Number of pitch actuator torques \(=NP\) GetMeasuredPitchActuatorTorque
101 in R Mean or start wind speed GetNominalStartWindSpeed
102 102 out out I I Yaw control flag 12 [-] GetYawControl, SetOverrideYawRateWithTorque
103 out R Yaw stiffness if record 102 = 1 or 3 12 [-] SetUseYawStiffness, SetUseYawStiffnessWithRate
104 out R Yaw damping if record 102 = 2 or 3 12 [-] SetUseYawDamping, SetUseYawDampingWithRate
105 in R Reserved
106 in R Reserved
107 out R Brake torque demand 1 22 Nm SetBrakeTorqueDemand
108 out R Yaw brake torque demand Nm SetYawBrakeTorqueDemand
109 in R Shaft torque (= hub Mx for clockwise rotor) 9 Nm GetMeasuredShaftTorque
110 in R Hub Fixed Fx 9 N GetMeasuredFixedHubFx
111 in R Hub Fixed Fy 9 N GetMeasuredFixedHubFy
112 in R Hub Fixed Fz 9 N GetMeasuredFixedHubFz
113 in R Network voltage disturbance factor [-] GetNetworkVoltageDisturbanceFactor
114 in R Network frequency disturbance factor [-] GetNetworkFrequencyDisturbanceFactor
115-116 Reserved
117 in I Controller state 23 [-] GetControllerState
118 in R Settling time (time to start writing output) s GetSettlingTime
119 Reserved SetTeeterLock
120-129 both out R I User-defined variables 1 to 1024 [-] SetIndexedUserVariables, GetIndexedUserVariables
130 out R Hardware pitch position blades 125 rad SetHardwarePitchPosition
131 out R Hardware pitch position blades 225 rad SetHardwarePitchPosition
132 out R Hardware pitch position blades 325 rad SetHardwarePitchPosition
133 out R Hardware pitch rate blade 125 rad SetHardwarePitchPosition
134 out R Hardware pitch rate blade 225 rad SetHardwarePitchPosition
135 out R Hardware pitch rate blade 325 rad SetHardwarePitchPosition
136 out out R I Update indicator for position and rate signals (130-135)25 [-] [-] SetHardwareInLoop
137 in R Pitch bearing Mz blade 1 Nm GetMeasuredPitchBearingMz
138 in R Pitch bearing Mz blade 2 Nm GetMeasuredPitchBearingMz
139 in R Pitch bearing Mz blade 3 Nm GetMeasuredPitchBearingMz
140 in R Pitch bearing friction blade 1 Nm GetMeasuredPitchBearingFriction
141 in R Pitch bearing friction blade 2 Nm GetMeasuredPitchBearingFriction
142 in R Pitch bearing friction blade 3 Nm GetMeasuredPitchBearingFriction
143 in R Teeter angle rad GetMeasuredTeeterAngle
144 in R Teeter velocity rad/s GetMeasuredTeeterVelocity
145 in R Pitch bearing Fxy blade 1 N GetMeasuredPitchBearingRadialForce
146 in R Pitch bearing Fxy blade 2 N GetMeasuredPitchBearingRadialForce
147 in R Pitch bearing Fxy blade 3 N GetMeasuredPitchBearingRadialForce
148 in R Pitch bearing Fz blade 1 N GetMeasuredPitchBearingAxialForce
149 in R Pitch bearing Fz blade 2 [-] GetMeasuredPitchBearingAxialForce
150 in R Pitch bearing Fz blade 2 [-] GetMeasuredPitchBearingAxialForce
151-153 Obsolete [-]
154 in R Number of effectively independent LIDAR beams \(BF\) [-] GetNumberOfLidarBeams
155 in R Number of focal points \(NF\) [-] GetNumberOfLidarBeamFocalPoints
156 Obsolete [-]
157 Obsolete [-]
158 in I Number of active dampers \(=ND\) rad GetNumberOfTurbineActiveDampers, GetNumberOfNacelleActiveDampers GetNumberOfBladeActiveDampers
159 Obsolete
160 Obsolete
161 in I Controller failure flag [-] GetControllerFailureFlag
162 in R Yaw bearing angular position rad GetMeasuredYawBearingAngularPosition
163 in R Yaw bearing angular velocity rad/s GetMeasuredYawBearingAngularVelocity
164 in R Yaw bearing angular acceleration rad/s$^2$ GetMeasuredYawBearingAngularAcceleration
165 out R Yaw motor rate demand rad/s SetDemandedYawMotorRate
166 in I Start number for additional user-defined variables \(=UDV\) [-] SetIndexedUserVariable and SetNamedUserVariable
167 in I Number of additional read only user-defined variables \(=NUDVR\) [-] SetIndexedUserVariable and SetNamedUserVariable
168 in I Number of additional write only user-defined variables \(=NUDVW\) [-] SetIndexedUserVariable and SetNamedUserVariable
169 Obsolete
170 both I Grid side converter d-axis control type rad/s$^2$ SetGridConvertedAxisControlType
171 both R Grid side converter d-axis control reference value rad/s$^2$ SetGridConvertedAxisControlReference
R in R First generator speed in lookup table 6,7 rad/s GetNumberOfGeneratorSpeedTorqueValues
R+1 in R First generator torque in lookup table 6,7 Nm GetGeneratorSpeedValue GetGeneratorTorqueValue
R+2 in R Second generator speed in lookup table 6,7 rad/s GetGeneratorSpeedValue GetGeneratorTorqueValue
R+3 in R Second generator torque in lookup table 6,7 Nm GetGeneratorSpeedValue GetGeneratorTorqueValue
... ... ... and so on, until ... ...
R+2N-2 in R Last generator speed in lookup table 6,7 rad/s
R+2N-1 in R Last generator torque in lookup table 6,7 Nm
M$_0$ out I Message length, only if record 49 is less than 0 16
M$_1$ -M$_n$ out C Message text, 4 characters per record 16 [-]
L$_1$ onwards R Variables returned SI
for logging output 19
Table 2 - Shaft brake flag index definition
Index number Brake description
1 Shaft brake 1
2 Shaft brake 2
3 Generator brake
4 Shaft brake 3
5 Brake torque set in record 107
Table 3 - Loads and accelerations available via controller
Record 79 Blade loads and accelerations Hub rotating loads Hub fixed loads Yaw bearing loads
0
1 √
2 √ √
3 √ √ √
4 √ √ √ √

Record 1 Status Flag

As described in the EXE case, record 1 of the shared binary file is used for handshaking.

In the DLL case, element 1 of the “DATA” array is set by the simulation as follows:

  • 0: First call at time zero

  • 1: All subsequent timesteps

  • -1: Final call at the end of the simulation.

  • 2 Real Time update step (for Real Time Test simulations only). On a call with the status flag set to 2, the DLL must exchange data with the turbine controller.

The DLL may set the value to –1 to request the simulation to terminate during the simulation.

Pitch and torque override

If the external controller is used for supervisory control actions such as starts stops, while the built-in continuous-time PI controllers are used for power production control, then it may be necessary for the external controller to specify the instant at which the supervisory control action takes over from the in-built controller action. Set record or element 55 to integer 0 whenever the external controller is to control the pitch, overriding the built-in PI controller. Set it to 1 when the built-in PI controller should be controlling the pitch.

For variable speed turbines, use record 56 in the same way to determine whether the external or the built-in controller should be controlling the generator torque.

Last updated 11-12-2024

  1. To apply brakes use this binary flag. Specify a value of \(\Sigma_i 2^{i-1} B_i\) where \(B_i=1\) if the brake with index \(i\) is applied, otherwise \(B_i=0\). The brake index numbers are defined in Table 2.↩↩↩

  2. in = data supplied by simulation, which may be used but not changed by the external controller.
    out = data supplied by the external controller to the simulation.
    both = data which is written by the simulation but which may be changed by the external controller.↩

  3. Record type for EXE case. I = integer, R = real (floating point), C = character. In the DLL case, all records are actually passed as 4-byte real (floating point) numbers.↩

  4. Pitch regulated case only.↩↩↩↩

  5. Not for variable speed pitch regulated case.↩↩↩↩↩

  6. Variable speed case only.↩↩↩↩↩↩↩↩↩↩↩

  7. If the lookup table option is selected for the optimal mode below rated control, then record 16 is zero, record 25 contains the record number (R) of the start of the lookup table, and record 26 contains the number of points in the table (N).↩↩↩↩↩↩↩↩↩

  8. Based on free wind at hub position - no modelling of actual nacelle anemometer or wind vane.↩↩

  9. Record 79 is used to request additional measured loads and accelerations to be provided by the simulation. Load and acceleration signals available are described in Table 3.↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩↩

  10. If the wind turbine model has individually hinged blades then record 38 is an integer used to switch on or off the built in hinge motion restraint equations and records 57-59 are interpreted as blade 1,2 & 3 hinge moments to be added to the moment generated by the built in hinge motion restraints. Also, records 30-32 will contain the flap angles and 66-68 will contain the flap velocities.↩

  11. 0 = off, 1 = main (high-speed) or variable speed generator, 2 = low speed generator.↩

  12. See record 29.↩↩↩↩↩

  13. Yaw control flag in record 102 (affects the flexible yaw model only):

    • 0: Default (record 48 sets the yaw rate demand).
    • 1: As 0 but change the linear yaw stiffness according to record 103 (no effect on hydraulic accumulator model).
    • 2: As 0 but change the yaw damping according to record 104.
    • 3: As 1 but also change the yaw damping according to record 104.
    • 4: Use record 41 (yaw torque demand) to override the yaw spring and damper.

    ↩↩

  14. See record 28.↩↩↩↩↩

  15. Depending on record 10.↩↩↩

  16. EXE case only.↩↩↩

  17. DLL case only.↩↩↩↩↩↩↩

  18. See Pitch and Torque Override.↩↩

  19. See logging output. Only applied in the DLL case.↩↩

  20. Only used with the variable slip generator electrical model. Set record 80 to 1 if using record 81 to send a rotor current demand. If record 80 is 0 (default), then the torque demand (record 47) will be used to control the generator.↩↩

  21. For the Real Time Test facility, it is useful for the user to be able to change the wind conditions manually during a simulation from code in the external controller. Bladed will increase the mean wind speed, turbulence intensity (of all components) and wind direction by the value set in the respective field.↩↩↩

  22. Brake torque demand used for brake index 51.↩

  23. Controller state flag is set by the Bladed internal controller as follows:

    • 0: Power production
    • 1: Parked
    • 2: Idling
    • 3: Start-up
    • 4: Normal stop
    • 5: Emergency stop

    ↩

  24. May be used to share information between user-defined DLLs for different turbine components.↩

  25. For use with the Hardware Test module if an external pitch actuator is used to override the pitch actuator simulated by Bladed. The (integer) value of record 136 must be changed whenever the hardware pitch positions or rates have been changed, to signal to the simulation that new values are available.↩↩↩↩↩↩↩