8. Bus Class¶
The bus class encapsulates all the modules that make up a single bus (node) of the power system. When a bus class is created, one of each event, transformer, sensor, network, and status module is spawned. Multiple Bus instances can coexist. The bus class instances are kept in an array of bus instances in a functional global available to the framework.
IMPORTANT NOTE: Internal to the software, the following terms are synonomous:
“SENSOR” = “PMU IMPAIRMENT”
“STATUS” = “FLAGS”
Figure 20: Bus Class UML
Figure 19 shows the properties and public methods of the bus class. Each bus has an index number and an ID number for each of the modules in the bus. Since only one App and OutputToFile module exists for all buses, their numbers are duplicated in each instance of the Bus Class that is created.
8.1. Scripted State Machine (SSM)¶
Module initialization and update is managed by construct called a “scripted state machine” (SSM). The state machine accepts an array command strings which forms a sequence of calls to one or more states. The sequence of commands MUST end with “Stop” command. If this is not included in the script, a timeout will produce an error message.
Inputs to the SSM are an array of command strings and a variant that can carry any data type that the commands can recognize. When the Data variant input is used, any command state that uses the input will need to use an “Unflatten to Data vi with the appropriate data typedef wired to it. If the typedef does not match the variant type then an error will be thrown. Usually the data type input to the SSM is the clBusData.ctl typedef, this data type can contain the config and parameter data of the modules of a single bus as well as the outputs from those modules.
Figure 21: Project showing the Bus Class and the Scripted State Machine (highlighted)
8.1.1. Script¶
An array of strings which will be the commands for the SSM. The script MUST end with a STOP command. The plugin “.ini” files contain “scriptlets” which are snippets of a script with no “Stop” command. When a test is run, the scriptlets in the Application plugin’s .ini file is concatenated with the scriptlet from the OutputToFile plugin’s .ini file, a Stop command is appended then run by the SSM. A similar occurrence happens for the modules in each bus, except those are run in the Bus Controller. See section 4.2 for detailed information about the bus controller.
8.1.2. SSM Parameters in¶
The Data In input is a variant type. A particular typedef will be expected for each state. In many cases, this type will be a clBusData.ctl typedef which holds most of the configurations and parameters for all modules in the bus on which the state machine is acting.
8.1.3. SSM Data Out¶
The Data Out is a variant type. The default “Stop” command places the SSM’s internal clBusData onto the data output, however other custom commands could be added which stop the SSM and place other data read from the modules onto the Data Out.
8.1.4. clBusData¶
When called, the SSM will create an empty clBusData cluster. The cluster will be populated by calls to the various Read or Get states listed below. A standard Stop call will place the populated cluster on the Data Out variant. Note that only data that was populated by Read or Get calls will be present. The data is not stored from one SSM call to the next.
| Data Type | DESCRIPTION |
|---|---|
| BusNumber | Since the Bus is an object, and multiple instance can run in parallel, each bus is given a number beginning at 1. No bus should ever be given number 0 or an error will occur. |
| EvtPluginINIFilePath | Path to the .INI file for the plugin used by this bus’s event |
| EvtParams | A table containing a 2D array of doubles and row and column headers depending on this bus’s event plugin |
| EvtConfig | Configuration cluster with data elements as follows |
| EvtConfig.UTC Time 0 | The UTC time offset to be assigned to the timearray time 0. The time array may start at a negative number |
| EvtConfig.Nominal Frequency | 50 or 60 Hz (F0) |
| EvtConfig.Reporting Rate | Depends on the Nominal Frequency 10 FPS through to the Nominal Frequency (Fs) |
| EvtConfig.FSamp | The internal sampling rate to be used to create Event Signals and PMU Impairments |
| Start Time | The time of the first report from the PMU less the UTC Time 0. This may be 0, or a negative or positive number |
| End Time | The time of the last report from the PMU |
| PmuImpairPluginINIFile | Path to the .INI file for the plugin used by this bus’s PMU Impairment module |
| PmuImpairParams | A table containing a 2D array of doubles and the row headers depending on this bus’s PMU Impairment plugin |
| PmuImpairconfig | Configuration cluster with data elements as follows: |
| FilterType | Enumerated list of possible PMU filter window types. (e.g. Blackman, hamming, Hann, etc.) |
| bPosSeq | Boolean value deytermines if a positive sequence phasor will be created or not. |
| NetImpairPluginINIFile | Path to the .INI file for the plugin used by this bus’s network Impairment module |
| NetImpairParams | A table containing a 2D array of doubles and the row and column headers depending on this bus’s Network Impairment plugin |
| FlagImpairPluginINIFile | Path to the .INI file for the plugin used by this bus’s Flag Impairment module |
| FlagImpairParams | A table containing a 2D array of doubles and the row and column headers depending on this bus’s Flag Impairment plugin |
| AppPluginINIFile | Path to the .INI file for the plugin used by this bus’s Application module |
| AppConfig | A Variant data type which contains the application plugin’s configuration data in XML form. Because different applications can have very different configuration data, XML is used as a common data format and each App plugin parses or unparsed the XML data as appropriate. |
| AppOutput | A variant data type. Different apps will have different data typedefs so any software receiving this data will need to be able to unflatten from variant into the appropriate data type. |
8.1.5. Scripted State Machine Command Reference¶
| STATE | INPUT | OUTPUT | DESCRIPTION |
|---|---|---|---|
| Initialize | none | n/a | Called initially when the state machine starts, this enqueues the script presented to the state machine at the script input. Users should not call this state in their scripts. |
| LoadEvtPlugin | clBusData .EvtPluginIniFilePath | none | The plugin called out in the selected Event plugin’s .ini file will be loaded into the event module for this bus |
| ReadEvtPluginPath | none | clBusData .EvtPluginIniFilePath | Reads the path to the plugin’s INI file from the module. |
| LoadPmuImpairPlugin | clBusData .PmuPluginIniFilePath | none | The plugin called out in the selected plugin’s .ini file will be loaded into the module for this bus |
| ReadPmuImpairPluginPath | none | clBusData .PmuPluginIniFilePath | Reads the path to the plugin’s INI file from the module. |
| LoadNetImpairPlugin | none | none | The plugin called out in the selected plugin’s .ini file will be loaded into the module for this bus |
| ReadNetImpairPluginPath | none | none | Reads the path to the plugin’s INI file from the module. |
| LoadFlagImpairPlugin | none | clBusData | The plugin called out in the selected plugin’s .ini file will be loaded into the module for this bus |
| ReadFlagImpairPluginPath | none | none | Reads the path to the plugin’s INI file from the module. |
| LoadAppPlugin | none | clBusData | The plugin called out in the selected plugin’s .ini file will be loaded into the application module |
| ReadAppPluginPath | none | none | Reads the path to the plugin’s INI file from the app module. |
| LoadOutToFilePlugin | none | clBusData | The plugin called out in the selected plugin’s .ini file will be loaded into the application module |
| ReadOutToFilePluginPath | none | none | Reads the path to the plugin’s INI file from the app module. |
| PopulateEvtFrontPanel | none | clFrontPanel- ControlRefs | For the selected bus, reads the Event module’s config and parameter information and populates the Event front panel controls |
| PopulatePmuImpairFrontPanel | none | clFrontPanel- ControlRefs | For the selected bus, reads the PMU Impairment module’s config and parameter information and populates the Sensor front panel controls |
| PopulateNetImpairFrontPanel | none | clFrontPanel- ControlRefs | For the selected bus, reads the Network Impairment module’s config and parameter information and populates the Network Impairment front panel controls |
| PopulateFlagImpairFrontPanel | none | clFrontPanel- ControlRefs | For the selected bus, reads the Network Impairment module’s config and parameter information and populates the Network Impairment front panel controls |
| StripIniPaths | none | none | The paths to the .ini files in the modules are absolute paths. When the paths have been read by the SSM, this command strips the paths down to relative paths for use in front panel controls or files storage. |
| Aggregate | none | none | When a test is being run, Sends a request to the App module to begin aggregating all the data queued by the running Bus Controllers. when aggregation is complete, the App module broadcasts a status messege. this command blocks all other commands until either the app status messege is received or a 10 second timeout has occured. |
| GetAppOutput | none | clBusData| .AppOutput | Sends a request to get output from the application module, receives the output and places it into the AppOutput variant in the clBusData |
| ReadAppInputData | none | clBusdata .ImpairReportArray | Sends a request to read the aggregated input data from the Application module and places that data into the ImpairReportArray |
| WriteAppConfig | clBusData .AppConfig | none | Sends the clBusData.AppConfig (XML) to the application module |
| ReadAppConfig | none | clBusData .AppConfig | Sends a request to the App module to read the App Config XML data. |
| WriteOutputFilePath | clBusData .OutFilePath | none | Sends the OutputFilePath to the OutputToFile Module |
| ReadOutputFilePath | none | clBusData .OutFilePath | Sends the OutputFilePath to the OutToFile Module |
| ReadOutToFileConfig | none | clBusData .clConfigOptions | Sends a request to read this bus’s OutToFile module’s config cluster and places that data into the clBusData.clConfigOptions |
| WriteEvtBusNumber | clBusData .BusNumber | none | Sends the Bus Number to this bus’s Event Module |
| WriteEvtParams | clBusData .EvtParams | none | Writes the parameters to this bus’s Event Module |
| ReadEvtParams | none | clBusData .EvtParams | Sends a request to read this bus’s Event module’s parameters and places that data into the clBusData.EvtParams |
| WriteEvtConfig | clBusData .EvtConfig | none | Writes the event config cluster to this bus’s Event Module |
| ReadEvtConfig | none | clBusData .EvtConfig | Sends a request to read this bus’s Event module’s config cluster and places that data into the clBusData.EvtConfig |
| WriteEvtRptTimeArray | clBusData .Start Time, .End Time and .EvtConfig.Reporting Rate | none | Uses the clbusData Start Time, End time, and Reporting Rate to create an time vector array thern sends it to the event module. The Event Report time array is used for generating the event’s theoretical reports. Events only keep one time array which is used both for generating theoretical reports and for signals so this must be called immediately before requesting event reports to ensure that the time array is not holding a signal time array (see WriteEvtSigTimeArray) |
| ReadEvtTime | none | clBusData .Start Time, .End Time and .EvtConfig.Reporting Rate | |
| GetEvtReports | none | clBusData .EvtReportArray | Sends a command to this bus’s Event Module to generate a set of Event Synchrophasor reports and places them into the clBusData.EvtReportArray |
| GetEvtSignal | none | clBusData .EvtSignalArray | Enqueues up a series of SSM commands wich lead to requesting this bus’s Event Module to send the Event Signal. The commands that the SSM will run are in the following order: ReadEvtConfig, ReadPMUImpairPArams,ReadEvtTime, WriteEvtSigTimeArray, AquireEvtSignal, TransferEvtTimeArrayToEvt. |
| WriteEvtSigTimeArray | clBusData .Start Time, .End Time and .EvtConfig.Reporting Rate | none | The Event Report time array is used for generating the event’s signal. The signal time is the event time extended by two impairment filter periods at both the beginning and end of the time array. Events only keep one time array which is used both for generating theoretical reports and for signals so this must be called immediately before requesting the event signal to ensure that the time array is not holding a report time array (see WriteEvtRptTimeArray) |
| TransferEvtTimeArrayToEvt | none | none | This has no input parameters because it uses the Start Time, End Time, and Reporting Rate stored in the SSM’s internal clBusData cluster. This is used durint the GetEvtSignal command to restore the report time array since the time array must be extended by the size of the PMUImpairment window on both sides of the time array. |
| AquireEvtSignal | none | clBusData .EvtSignalArray | DO NOT CALL THIS DIRECTLY. The event must first be set up. Call GetEvtSignal to set up and get the Event Signal. |
| WritePmuImpairBusNumber | clBusData .BusNumber | none | Sends the bus number to this bus’s Sensor module |
| WritePMUImpairParams | clBusData .PmuImpairParams | none | Writes the impairment parameters to the sensor impairment module. |
| ReadPMUImpairParams | none | clBusData .PmuImpairParams | Reads the impairment parameters from the sensor impairment module. |
| WritePmuImpairConfig | clBusData .PmuImpairConfig | none | Writes the impairment configuration cluster to the sensor impairment module. |
| ReadPmuImpairConfig | none | clBusData .PmuImpairConfig | Reads the impairment configuration cluster from the sensor impairment module. |
| WritePmuImpairEvtConfig | clBusData .EventConfig | none | Writed the Event configuration data to the sensor module. |
| TransferEvtReportsToPmuImpair | none | none | Event reports that were read by GetEvtReports are written to the Sensor module |
| TransferEvtReportsToOutputToFile | none | none | Event reports that were read by GetEvtReports are written to the output to file module |
| TransferPMUImpairReportsToApp | none | none | Sensor impairment reports that were read by GetPmuImpairReports are written to the Application module |
| TransferFlagsToOutputToFile | none | none | |
| TransferPktDlyToOutputToFile | none | none | |
| TransferPktLossToOutputToFile | none | none | |
| OutputErrorsToFile | |||
| OutputImpairedFileRequest | |||
| TransferEvtSignalToPmuImpair | |||
| WriteNetImpairParams | |||
| ReadNetImpairParams | |||
| TransferTimeArrayToNetImpair | |||
| WriteFlagImpairParams | |||
| WritePmuConfig | |||
| TransferEvtConfigToApp | none | none | |
| Abort | none | none | DO NOT CALL THIS DIRECTLY. Clears the SSM command queue and exits the SSM in response to user “Abort” response to error dialog. |
| Stop | Must be called at the end of every script. | ||
| Error | DO NOT CALL THIS DIRECTLY. SSM error handler state displays errors and reacts to user input to the error dialog. | ||
| Default | DO NOT CALL THIS DIRECTLY. Throws an error if an unrecodnized command is received. |