DragScript Flow of Control

From Voyager Unofficial Wiki
Jump to: navigation, search

These DragScript elements control the flow of execution through your script. You can use the DragScript Simulator to test how control will flow when the DragScript actions complete with OK, ERROR or TIMEOUT status, and when Emergency Suspend, Resume and Exit events happen.

Variables

DragScript has several variable types: counters (integers), string variables and decimal numbers. They must be declared with the Counter, String or Decimal Number actions before they can be used. You can set and change their values, and then make decisions to execute DragScript actions based on their value. For example, you may build a script that runs from zero to ten sequences based on the value of a counter variable you set at the start of the script.

Dragscript-variables1.png

Type

  • Counter: Declare a counter (integer) variable and give it an initial value. You must declare a variable before using it

Dragscript-counter.png

  • Label: The name for this counter variable. There are no restrictions on length or legal characters, so just use something that makes sense for your control flow
  • Init Value: Initial value for the counter. Must be an integer between -2,000,000,000 and +2,000,000,000
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window
  • String: Declare a string variable and give it an initial value. You must declare a variable before using it

Dragscript-string.png

  • Label: The name for this string variable
  • Init Value: Initial value for the string
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window
  • Decimal Number: Declare a decimal number variable and give it an initial value. You must declare a variable before using it

Decimal-number.png

  • Label: The name for this decimal number variable
  • Init Value: Initial value for the decimal number - must be between the limits shown in the dialog box
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window

Manage

  • Update Counter: Update the value of a counter variable:

Dragscript-update-counter.png

  • Counter: Select the counter to update from the drop-down list. Counter variables must be declared with a Counter DragScript action before they can be updated
  • Update Type:
    • Set to: If selected, set the counter variable to the value in the Update Value field
    • Offset by: If selected, add the value in the Update Value field to the counter. The Update Value field can be negative or positive.
  • Update Value: A negative or positive integer value to either set the counter variable to or offset the counter variable by
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Update String: Update the value of a string variable:

Dragscript-update-string.png

  • String: Select the string variable to update from the drop-down list
  • Update Value: Enter the new value for the string variable
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Update Decimal Number: Update the value of a decimal number

Update-decimal-number.png

  • Decimal Number: Select the decimal number variable to update from the drop-down list
  • Update Type:
    • Set to: Set the decimal number value to the number in the Update Value field
    • Offset by: Add the +/- number in the Update Value field to the current value of the decimal number
  • Update Value: Enter the new value for the decimal number variable
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Update Decimal Number from Observing Conditions: Set the value of a decimal number from the observing conditions returned from I/O cards via Viking or from an ASCOM Observing Conditions driver:

Update-decimal-from-condx.png

  • Decimal Number: Select the decimal number variable to update from the drop-down list
  • Observing Condition: Select the observing condition whose value should be placed into the decimal number. These values come from Viking, a companion product from Starkeeper.it or from an ASCOM Observing Conditions driver
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Update Decimal Number from Focuser Temperature: Set the value of a decimal number from the temperature returned by the focuser or auto-focus system

Update-decimal-from-focus-temp.png

  • Decimal Number: Select the decimal number variable to update from the drop-down list
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Update Decimal Number with Autofocus HFD: Set the value of a decimal number with the final HFD (Half Flux Diameter) value from the last autofocus operation

Update-decimal-hfd.png

  • Decimal Number: Select the decimal number variable to update from the drop-down list
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window
    Important Note! At this time only RoboFire LocalField, RoboStar, and FocusMax return the HFD value - if you use a different autofocus routine, the HFD is not available

Jumps

Jumps are used to goto a specified block of the DragScript. You can jump to the Start, End or a named Block.

Dragscript-jumps.png

  • Goto Start: Jump to the Start block of the script
  • Goto Block: Jump to a named block in the script

Dragscript-block-goto.png

  • Block: Select the named from the drop-down list, or type in the name of a block
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Goto End: Jump to the End block of the script


Repeats

Repeats are used to execute a DragScript block a specified number of times, or until a specific time, or until astronomical night ends.

Repeats must be placed inside a block (note: Script: is a special block that contains the entire script.

If the result of evaluating a Repeat is to repeat the block, control returns to the block statement that contains the repeat.

Dragscript-repeats.png

  • Repeat Block for n Times: Repeat the containing block a specified number of times

Dragscript-repeat-block.png

  • Times: Number of times to repeat this block
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window
  • Repeat Current Block Until Time: Repeat the contained block until the specified time:

Dragscript-until-time.png

  • Time: Repeat the current block until this time
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window
  • Repeat Block Until Astronomical Night End:

Dragscript-repeat-until-night-end.png

  • Get Latitude and Longitude from Mount: Retrieve the current latitude and longitude from the connected mount, which must support this command. This location is used, along with the current date, to determine the time that astronomical night ends
  • Use the Latitude and Longitude indicated below: Specify your current latitude and longitude in the fields below. This location is used, along with the current date, to determine the time that astronomical night ends
  • Offset: Time in HH MM SS
    • Offset Before: If selected, repeat the block until this amount of time before astronomical night ends
    • Offset After: If selected, repeat the block this amount of time after astronomical night ends
  • Default: Use the default settings
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


Important Note! The time will be considered to have been reached if it is within 12 hours of the current time when the check is performed. E.g., if we set a repeat until 05:00, if it is 23:30 the repeat will be done since 23:30 is more than 12 hours in the future and less than 12 hours in the past, relative to 05:00. If it is 11:00, the repeat will be skipped, since 11:00 is later than 05:00 and more than 12 hours in the past.


Decisions

Decisions control the flow of your DragScript based on the results of an action (OK, ERROR, TIMEOUT), operating conditions (current time, date or target altitude), or the value of a variable.

Important Note! A Decision element will create a new indent level in your DragScript. Drag new elements and drop them on the Decision element, or copy and paste them to it, to have their execution controlled by the result of the Decision


Decisions-with-decimal.png

  • Action Results: Do the actions at the indent level created by the Decision block based on the results of the action preceding the decision
    • IF OK: Do the actions following this statement if the result of the previous action was OK - meaning the action was successful
    • IF ERROR: Do the actions following this statement if the result of the previous action was ERROR - meaning the action failed
    • IF TIMEOUT: Do the actions following this statement if the result of the previous action was a TIMEOUT - meaning the action reached a specified timeout value without succeeding

Operating Conditions:

Do the actions at the indent level created by the Decision block based on the time, date or target altitude

  • DO IF ALTITUDE: Do the actions if a target specified by RA and DEC coordinates has risen above or set below a specified altitude:

Dragscript-do-if-altitude.png

  • RA Target J2000: RA coordinates of the object you want to reach the Reference Altitude in HH MM SS or HH MM SS.sss
  • DEC Target J2000: DEC coordinates of the object you want to reach the Reference Altitude in DD MM SS or DD MM SS.sss
  • Reference Altitude: Altitude to reach in degrees
  • Do If Actual Altitude GREATER than or EQUAL (>=) to reference: Do the actions if the target has reached or risen above the reference altitude
  • Do If Actual Altitude LOWER than or EQUAL (>=) to reference: Do the actions if the target has reached or set below the reference altitude
  • Default: Use the default settings
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • DO IF TIME BETWEEN: Do the actions if the time is between the specified start and end times

Dragscript-do-if-time.png

  • Start: Beginning time of interval within which to do the following actions
  • End: End time of interval within which to do the following actions
  • Default: Use the default settings
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • DO IF DATE BETWEEN: Do the actions at the indent level created by the DO statement if the date is between the start and end dates:

Dragscript-do-if-date.png

  • Start: Start date of the interval
  • End: End date of the interval
  • Default: Use the default settings
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


Variable Check

Do the actions at the indent level created by the DO IF statement based on the value of a variable. Variables must be declared before they can be tested in a DO IF statement

Decisions-variable-check.png

  • DO IF COUNTER VALUE: Check the value of a counter (integer) variable and do the following actions if the value of the counter meets the specified criteria:

Dragscript-do-if-counter.png

  • Label: Choose the counter variable to test from the drop-down list
  • is Lower than: Do the following actions if the selected counter value is less than the number in the counter field
  • is Lower than or Equal to: Do the following actions if the selected counter value is less than or equal to the number in the counter field
  • is Equal to: Do the following actions if the selected counter value is equal to the number in the counter field
  • is Greater or Equal to: Do the following actions if the selected counter value is greater than or equal to the number in the counter field
  • is Greater than: Do the following actions if the selected counter value is greater than the number in the counter field
  • is Between: Do the following actions if the selected counter value is between the values in the two counter fields (greater than or equal to the left value AND less than or equal to the right field)
  • is Not Equal to: Do the following actions if the selected counter value is not equal to the number in the counter field
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window
    • DO IF STRING VALUE: Do the actions at the indent level created by the DO IF statement if a string variable is equal to, not equal to, or contains a specified string:

Dragscript-do-if-string.png

  • Label: Choose the string variable to test from the drop-down list
  • is Equal to: Do the following actions if the selected string value is equal to the specified string
  • is Not Equal to: Do the following actions if the selected string value is not equal to the specified string
  • Contains: Do the following actions if the selected string value contains the specified string
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


Important Note! String comparisons are case sensitive, i.e. TargetName is not equal to targetname


  • DO IF DECIMAL VALUE: Do the actions at the indent level created by the DO IF statement if the value of the decimal number meets the specified criteria:

Do-if-decimal-value.png

  • Label: Choose the counter variable to test from the drop-down list
  • is Lower than: Do the following actions if the selected decimal number value is less than the number in the decimal number field
  • is Lower than or Equal to: Do the following actions if the selected decimal number value is less than or equal to the number in the decimal number field
  • is Equal to: Do the following actions if the selected decimal number value is equal to the number in the counter field
  • is Greater or Equal to: Do the following actions if the selected decimal number value is greater than or equal to the number in the decimal number field
  • is Greater than: Do the following actions if the selected decimal number value is greater than the number in the decimal number field
  • is Between: Do the following actions if the selected decimal number value is between the values in the two decimal number fields (greater than or equal to the left value AND less than or equal to the right field)
  • is Not Equal to: Do the following actions if the selected decimal number value is not equal to the number in the decimal number field
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window



Events

DragScript execution can be suspended, terminated (exited) and resumed based on the occurrence of Emergency Exit, Emergency Suspend and Emergency Resume events.

The most common use of Events is together with a weather monitoring system, as configured in Weather Setup. You can specify at a detailed level which events should cause DragScript execution to SUSPEND (such as overcast clouds), EXIT (such as rain), or RESUME (such as clouds moving out so it becomes clear again).

In addition to weather events, you can raise Emergency Exit, Emergency Suspend and Emergency Resume events at any point in your DragScript.

When an Event is raised, control flow goes immediately to the appropriate block (Exit, Suspend or Resume) in the Events block of your DragScript. Create those blocks by dragging elements from the Events: Manage list.

Dragscript-events.png

Manage

See the DragScript Examples section to see how these blocks work in a DragScript.

  • Emergency Exit: Drag this element to the Events block of your DragScript. Then drag the actions you wish to take place when an Emergency Exit event is raised. For example, stop tracking, stop guiding, park your mount, and close the observatory roof
  • Emergency Suspend: Drag this element to the Events block of your DragScript. Then drag the actions you wish to take place when an Emergency Suspend event is raised. For example, stop tracking and stop guiding

Dragscript-suspend-2.png

  • Wait Resume until absolute time: If the time specified in HH MM SS is reached without an Emergency Resume event being raised, perform the action selected from the radio buttons in this dialog window
  • Wait Resume for a time interval of: If the time period specified in HH MM SS elapses without an Emergency Resume event being raised, perform the action selected from the radio buttons in this dialog window
  • Wait Resume until end of Astronomical Night (to allow calculation mount must be connected to Voyager): If the end of Astronomical Night arrives without an Emergency Resume event being raised, perform the action selected from the radio buttons in this dialog window
  • On Resume Timeout End DragScript: If the time specified above is reached without an Emergency Resume event occurring, end the DragScript
  • On Resume Timeout Exec Emergency Exit Event: If the time specified above is reached without an Emergency Resume event occurring, raise an Emergency Exit event
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Emergency Resume: Execute these actions when an Emergency Resume event is raised. For example, start tracking and start guiding

Raise

Raise an Emergency Exit, Suspend or Resume event

  • Raise Emergency Exit Event: Raise the Emergency Exit event. Execution of the DragScript will go immediately to the Emergency Exit block in the Events block
  • Raise Emergency Suspend Event: Raise the Emergency Suspend event. Execution of the DragScript will go immediately to the Emergency Suspend block in the Events block
  • Raise Emergency Resume Event: Raise the Emergency Resume event. Execution of the DragScript will go immediately to the Emergency Resume block in the Events block


Various

  • Resume from Block: Resume execution starting with the specified block. This can only be placed in the Emergency Resume block in the Events block

Dragscript-resume-from-block.png

  • Block: Choose the block where execution should resume from the drop-down list
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


  • Disable Events: Disable event processing. Emergency Exit, Suspend and Resume events will be ignored
  • Enable Events: Enable event processing. Emergency Exit, Suspend and Resume events will be recognized and handled


Block

The Block element creates a new block in your DragScript. Drag and Drop it on a DragScript element that creates a new indent level, e.g. Script, DO IF, IF, Emergency Exit, Emergency Suspend, or Emergency Resume.

Dragscript-block.png

  • Label: Give your block a name. This name can be referenced by other script elements such as jumps and resumes
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window


Remark

The Remark element adds a non-executable comment to your script for documentation purposes

Dragscript-remark.png

  • Remark: Enter a comment that will appear in your script
  • OK: Save changes and close the window
  • Cancel: Discard changes and close the window