Frequently Asked Question

What are the timed commands?

Timed commands is Typhoon HIL's mechanism which allows the user to execute HIL API commands in a certain moment of time, defined with high accuracy. The resolution which is supported is the simulation time step of the electric circuit solver (down to 200 ns). By calling the HIL API command using the executeAt parameter you are specifying simulation time when you want the command to be executed. 

Time commands are not supported by all HIL API functions. To check if it is supported by a certain function, check in the HIL API documentation if that function has executeAt parameter. The functions that are typically used with timed commands are:

• set_source_constant_value()
• set_source_sine_waveform()
• set_contactor()
• set_pv_amb_params()
• start_capture()

Note: In case the executeAt parameter is not specified or it is set to None (executeAt == None), the command will be executed immediately.

When do I need to use timed commands?

Sending HIL API commands takes some undeterminable amount of time (typically 1-100 ms). This number depends on the API command, HIL device, and connection type (USB or Ethernet). This can cause some problems in three specific cases:

1. You need to send some HIL API commands in a precisely defined moment of the simulation. The typical use case is if you want to inject some fault in a specific time moment (e.g. when voltage is at its peak value).
   
   
   
   
2. You want to call multiple API commands simultaneously. The typical use case is when you want to introduce complex faults by simultaneously closing multiple switches.
   
   
   
   
3. You want to execute two API commands with a specific time gap between them. The typical use case is when you want to inject voltage deep fault for a specific duration. In that case, you will also typically use get_sim_time() to get the current simulation time (look at How to use timed commands for example).

If your application belongs to some of the above use-cases you should consider using timed commands.

Note: If your use-case does not require this level of precision it is better not to use executeAt parameter. If you want to make a time delay between two API calls and msec or sec resolution is enough, you can use one of the following API functions: wait_msec(), wait_sec().

How to use timed commands?

Timed commands are activated by specifying simulation time using executeAt parameter. The value should be defined in seconds (e.g. executeAt=2.52). Simulation time refers to the HIL device's internal clock time which is activated on the simulation start.

Time commands can be used both in standalone scripts and macro scripts inside HIL SCADA. Especially when used in the Button widgets or in the On Click handler it is necessary to know the current simulation time. This is an example of a voltage dip that is active for 0.5 seconds:

tollerance = 0.1
fault_time = 0.5
elapsed_time = hil.get_sim_time()
hil.set_source_sine_waveform('Vs3', rms=110.0, executeAt=elapsed_time+tollerance)
hil.set_source_sine_waveform('Vs3', rms=220.0, executeAt=elapsed_time+tollerance+fault_time)

Note: The important thing to have in mind is that timed commands need to be called successively. This means that you can issue the new timed command only if it is supposed to be executed after all previously called time commands (executeAt parameter must be larger than in all previous commands). If this is not the case, the command will be ignored.

Note: In case execution time that is set has already expired, the command will be executed immediately.

What are the limitations of timed commands?

Timed commands are utilizing dedicated resources inside the HIL device. Those hardware limitations are reflected on the application side in the following ways:

1. As all commands are stored in a high-speed FIFO memory structure, it is crucial to issue them successively (explained in How to use timed commands?).
2. Delay - Since the API command is issued, there is some time needed to call it, process the parameters, transfer it through the communication, and at the end activate it on the HIL device side. As you need to take those delays into account, you should call the command a bit before the actual function execution time. For most of the API functions, it is enough to put executeAt ≥ elapsed_time + 0.1
3. The maximum number of commands that can be stored in a memory buffer and wait for execution is limited. This number is not hard-coded as it depends on the type of function and time interval between functions. In a typical use case, you can store more than 100 commands in memory.
   Note: In a virtual HIL environment you don't have this restriction (you are using the memory of your PC which is enough for all practical cases).

Note: The timed commands feature is supported on all HIL devices and all firmware configurations and in a virtual HIL environment.