Part 5: Introduction to Connect

STK Pro, STK Premium (Air), STK Premium (Space), or STK Enterprise
You can obtain the necessary licenses for this tutorial by contacting AGI Support at support@agi.com or 1-800-924-7244.

The results of the tutorial may vary depending on the user settings and data enabled (online operations, terrain server, dynamic Earth data, etc.). It is acceptable to have different results.

Capabilities covered

This lesson covers the following capabilities of the Ansys Systems Tool Kit® (STK®) digital mission engineering software:

  • STK Pro

Problem statement

Programmers, engineers, and operators often need resources to easily build applications that communicate with the STK software. Having a spreadsheet containing data, they need to transfer the data into and out of the STK application quickly and easily. Many of the engineers and operators are not programmers. They need a simple-to-understand language and syntax to build commands to efficiently populate objects into the STK application and extract data from, or create automations with, the STK application.

Solution

You will learn what an STK Connect command is and how to find and use the Connect Command Library. Using the API Demo Utility, explore the Connect Command Library and become familiar with some simple connect commands used to quickly and easily populate objects into and obtain analytical data from an STK scenario.

What you will learn

Upon completion of this tutorial, you will understand the following:

  • The Connect Command Library
  • Simple Connect commands
  • The API Demo Utility

Video guidance

Watch the following video. Then follow the steps below, which incorporate the systems and missions you work on (sample inputs provided).

Creating a new scenario

Create a new scenario.

  1. Launch the STK application ().
  2. Click Create a Scenarioin the Welcome to STK dialog box.
  3. Enter the following in the STK: New Scenario Wizard:
    4. Option Value
    Name STK_Connect
    Location Default
    Start Default
    Stop Default
  4. Click OK once you are done.
  5. Click Save () once the scenario loads. A folder with the same name as your scenario is created for you in the location specified above.
  6. Verify the scenario name and location and click Save.

Save () often during this lesson!

Preparing your workspace

For this scenario, the Timeline View and the Insert STK Objects tool won't be used. You can close them.

  1. Close the Timeline View.
  2. Close the Insert STK Objects tool.

Opening the API Demo utility

Connect commands are normally passed from outside the STK application over a TCP/IP connection or through a COM interface. In this scenario, you'll use the API Demo Utility through an integrated Web Browser window in the STK Workspace. The API Demo Utility functions inside of the STK application; therefore, no outside connections are required. The API Demo Utility is a great tool, with which you can practice Connect commands prior to using them in an actual script.

  1. Return to the STK application.
  2. Click New Web Browser Window () on the Default toolbar.
  3. Click Browse () on the Web Browser Controls toolbar when the Web Browser window opens.
  4. Select the Example HTML Utilities folder in the left navigation pane when the Open dialog box opens.
  5. Select the STK Automation folder.
  6. Click Open.
  7. Select the API Demo folder.
  8. Click Open.
  9. Select API Demo Utility.htm.
  10. Click Open to confirm your selection and to close the Open dialog box.

Customizing your workspace

You can dock the API Demo Utility to the bottom of the STK application's workspace.

  1. Right-click on the Web Browser - API Demo Utility title bar.
  2. Select Dockable in the shortcut menu.

    3. When you select Dockable as an individual window display type, you can fix that window at certain places in the STK workspace. The window will usually will dock below the Object Browser.

  3. Place your cursor on the Web Browser - API Demo Utility title bar.
  4. Click and drag the web browser onto the marker near the bottom of the STK workspace.
  5. Release your mouse button to dock it at the bottom of the STK application window.
  6. Select the Window menu in the Menu Bar at the top of the STK application.
  7. Select Tile Vertically.

Understanding the API Demo Utility

Take a look at the API Demo Utility window to see how it is set up.

  1. Look at the API Demo Utility.
  2. Review the Examples on the left side of the API Demo Utility

    3. When you click an example Connect command, the associated Connect command appears in the Code Sandbox. Connect isn't compiled code; Connect is simply a string of text written in a way that the STK software understands. Connect is sometimes referred to as "The Language of STK."

  3. Review the Code Sandbox.

    4. The Code Sandbox is where you enter your Connect commands or load the prebuilt example Connect commands.

    • Connect and Object Model options: When you load an example Connect command, you can view it as a Connect command or you can select Object Model to see examples of how a line of code might look inside an application like MATLAB.
    • Running the code: Clicking Run Code will send your Connect command to your scenario.
  4. Review the Output field:

    5. The Output field is used if you send a Connect command which returns data such as the data inside an access report.

Using the New command

The New command allows you to create a new scenario or add a new object to the current scenario. The Syntax is:

New <ApplicationPath> <ClassPath> <NewObjectName> {NewOptions}

  1. Select Add facility in the In the API Demo Utility's Examples list.
  2. A string of text has been added to the Code Sandbox:

    3. New / */Facility MyFacility_Con

  3. You can break down the Connect command to understand what it is doing:
    4. String of Text in Add Facility Meaning
    New Connect command
    / ApplicationPath
    */Facility ClassPath
    MyFacility_Con NewObjectName
    • Wildcards can be used in Connect commands. To understand wildcards, view the Wildcards in Object Paths help page.
    • <ApplicationPath> is the path to the instance of the current application (for example the STK application).
    • <ClassPath> specifies the full class path of the object to be created. In this case, it's the new Facility () object you're entering into the scenario.
    • <NewObjectName> is the name of the Facility () object.
      • Object Names can not be more the 64 characters in length.
      • Object Names can contain only alphanumerics, underscores and hyphens.
      • Object names, in Connect, are not case-sensitive, however Class names are case-sensitive.
      • An object name cannot be "_Default" or "end" (regardless of case), as these are reserved words in the STK software.
  4. Click Run Code.

A Facility () object has been inserted into the scenario using its default properties.

Using the Connect Command Library

There is a whole section in STK Help devoted to Connect. You can use the commands in the Connect Command Library to easily build applications that communicate with the STK software.

  1. Select the Help menu in the Menu Bar.
  2. Select STK Help.
  3. Select Integrating with STK in the table of contents.
  4. Select Connect Command Library.

There's a lot of information in the Connect Command Library to include breaking down Connect commands by object, 2D and 3D Graphics windows, by capability, etc. To keep things simple, you'll focus on the API Demo Utility Examples. You can find much more in depth training in the Optional Third-Party Programs (Level 2 - Advanced Training), specifically Integrating STK with MATLAB and Integrating STK with Python. A Level 3 - Focused / Problem Specific lesson that uses Connect is Drive STK with Connect Commands and Excel.

Viewing the Alphabetical Listing of Connect Commands

The Alphabetical listing includes all Connect commands, regardless of their groupings.

  1. Select the Alphabetical Listing of Connect Commands link on the Connect Command Listings page.
  2. Select N at the top of the page.
  3. Select the New command.

The page describes the command, syntax, related commands, options, and examples. Whenever you're starting to write Connect commands, look at the examples. You'll have to change them to work with your object types and such, but it's a great place to start.

Viewing the SetPosition command page

You can use the SetPosition command to set the position of a facility, place, target or area target.

  1. Return to the Alphabetical Listing of Connect Commands.
  2. Select S at the top of the page.
  3. Select SetPosition (Facility, Place, Target & Area Target).
  4. Ensure you have the correct syntax:

    5. SetPosition <ObjectPath> [{Type}] {CoordType} <Parameters>

  5. Scroll down the page until you find the chart of coordinate types and parameters in the Description section.
  6. Note the Geodetic coordinate type parameters:

    7. <Lat> <Lon> {<Altitude> | Terrain} [MSL].

  7. Return to the STK application.

You don't have to keep jumping back and forth between the STK application and the Connect Command Library. However, feel free to go there on your own as you proceed through the training.

Understanding the SetPosition command

Before you run the code, look at the SetPosition command in the API Demo Utility.

  1. Select Modify facility in the In the API Demo Utility's Examples list.
  2. Note the code that's been added to the Code Sandbox:

    3. SetPosition */Facility/MyFacility_Con Geodetic 37.9 -75.5 0.0

  3. Notice the SetPosition code in the Code Sandbox matches the Connect command syntax (for example, Type, Latitude, Longitude, Altitude).
  4. Right-click on MyFacility_Con () in the Object Browser.
  5. Select Properties () in the shortcut menu.
  6. Select the Basic - Position page when the Properties Browser opens.

    7. You can see that the Connect command syntax matches the fields in the Position panel.

  7. Click Cancel to close the Properties Browser.
  8. Return to the API Demo Utility.

Modifying the SetPosition command

Update the default SetPosition code and examine the second command before running it.

  1. Remove 0.0 (which is the altitude) at the end of the SetPosition Connect command.
  2. Enter Terrain at the end of the Connect command.

    3. Since you have streaming terrain from Terrain Server, by removing the altitude and inserting Terrain, the Facility object will be placed on top of the terrain at the coordinates in the command.

    The second command is another New command. Note the path. It follows the object type to object name like you see it in the Object Browser. The New command inserts a Sensor () object and attaches it to the MyFacility_Con ().

  3. Click Run Code.

MyFacility_Con () has new coordinates and an attached Sensor () object named MyFacSensor_Con.

Inserting a Satellite object

Using the API Demo Utility to add a Satellite () object to the scenario and name it MySat.

  1. Select Add satellite In the API Demo Utility's Example list.
  2. Note the code that's been added to the Code Sandbox:

    3. New / */Satellite MySatellite_Con

  3. Change the Satellite object's name from MySatellite_Con to MySat.
  4. Click Run Code.

A Satellite object named MySat () has been added to the scenario, but its orbit still needs to be propagated.

Propagating MySat

The SetState Classical command sets the orbit state of the satellite using classical coordinates. The syntax is:

SetState <VehObjectPath> Classical {Propagator} {NoProp | {TimeInterval}} <StepSize> {CoordSystem} "<OrbitEpoch>" <SemiMajorAxis> <Eccentricity> <Inclination> <ArgOfPerigee> <RAAN> <MeanAnom>

  1. Select Modify satellite in the API Demo Utility's Examples list.
  2. Note the code that's been added to the Code Sandbox:

    3. SetState */Satellite/MySatellite_Con Classical TwoBody {TimeInterval} 60 J2000 "<OrbitEpoch>" 6678140 0 28.5 0 0 0

  3. Compare the text in the Code Sandbox to the syntax and change the following:
    4. Option Value
    Object name MySat
    Inclination 45
    RAAN 180

    The value for the SemiMajorAxis is in meters, which is the default distance unit when using Connect. Default distances in the STK software are in kilometers.

  4. Click Run Code.

Inserting an Aircraft object

Use the API Demo Utility to insert a new Aircraft () object.

  1. Select Add aircraft in the API Demo Utility's Examples list.
  2. Look at the code in the Code Sandbox:

    3. New / */Aircraft MyAircraft_Con
    SetPropagator */Aircraft/MyAircraft_Con GreatArc
    AltitudeRef */Aircraft/MyAircraft_Con Ref MSL
    AddWaypoint */Aircraft/MyAircraft_Con DetTimeAccFromVel 39.7674 -79.7292 11000 257.22222
    AddWaypoint */Aircraft/MyAircraft_Con DetTimeAccFromVel 38.3721 -120.116 11000 257.22222

    The New command inserts an Aircraft () object named MyAircraft_Con. Then it sets the propagator to Great Arc, sets the aircraft's altitude reference to mean sea level (MSL), and creates waypoints for its route.

    Command Description
    SetPropagator Sets the propagator of a great arc vehicle
    AltitudeRef Sets the altitude reference for a Great Arc vehicle
    AddWaypoint Adds waypoints to a great arc vehicle
  3. Click Run Code.

Modifying MyAircraft_Con

Run the Modify aircraft example code to update MyAircraft_Con.

  1. Select Modify aircraft in the API Demo Utility's Examples list.
  2. Look at the code in the Code Sandbox:

    3. Waypoints */Aircraft/MyAircraft_Con Clear
    AddWaypoint */Aircraft/MyAircraft_Con DetTimeAccFromVel 20.7674 -79.7292 11000 257.22222
    AddWaypoint */Aircraft/MyAircraft_Con DetTimeAccFromVel 15.3721 -120.116 11000 257.22222

    The Waypoints command and the Clear WaypointOption clears the original waypoints and AddWaypoint inserts new waypoints.

    Command Description
    Waypoints Clears all waypoints from a great arc vehicle
  3. Click Run Code.

Computing access

Run the Compute access sample code to compute access from MySat () to MyFacility_Con ().

  1. Select Compute access in the API Demo Utility's Examples list.
  2. Look at the code in the Code Sandbox:

    3. Access */Satellite/MySatellite_Con */Facility/MyFacility_Con

    The Access command will compute access from the satellite to the facility.

    Command Description
    Access Calculates access intervals between two objects
  3. Change the Satellite name from MySatellite_Con to MySat.
  4. Click Run Code.
  5. Bring the 2D Graphics window to the front.

    6. You will see access lines above MyFacility_Con ().

  6. Look at the API Demo Utility's Output field.

    7. You can see the full path to each object followed by individual accesses.

Adding vectors

Add a vector which points from the Facility () object to the Satellite object.

  1. Select Add vectors in the API Demo Utility's Examples list.
  2. Look at the code in the Code Sandbox:

    3. VO */Facility/MyFacility_Con SetVectorGeometry Add "Facility/MyFacility_Con Satellite/MySatellite_Con Vector" Show On
    VO * View FromTo FromRegName "STK Object" FromName "Facility/MyFacility_Con" ToRegName "STK Object" ToName "Facility/MyFacility_Con" WindowID 1

    The first command creates a new To Vector and turns it on in the 3D Graphics window. The second configures the view in the 3D Graphics window.

    Command Description
    VO SetVectorGeometry Defines the display of geometric components in the 3D Graphics window
    VO View Sets parameters for the view in a 3D window
  3. Change the Satellite name from MySatellite to MySat in the VO SetVectorGeometry code line.
  4. View both lines of code.
  5. Click Run Code.
  6. Bring the 3D Graphics window to the front.
  7. Note that the VO View command set the view in the 3D Graphics window to be centered on MyFacility_Con ().

    8. To better view the vector pointing from MyFacility_Con () to MySat (), you might have to set your view in the 3D Graphics window so that you're under the terrain. The vector is only visible above the terrain when MyFacility_Con () has an access to MySat ().

  8. Click Start () on the Animation toolbar to animate the scenario.
  9. Click Reset () when finished.

Saving your work

Clean up your workspace and save your scenario.

  1. Close any open reports, properties and tools which are still open.
  2. Save () your work.

Summary

This was an introduction to the STK Connect module and the Connect Command Library. You were introduced to the API Demo Utility — just one of a few tools that come with the STK application — which you can use to send Connect commands.

  • STK Button Tool : The STK Button Tool is a Perl script with a graphical user interface (GUI) that you can use to associate STK Connect commands with buttons. It is installed with the STK application in the Connect folder.
  • Send_A_Connect_Command.htm: Located in the STK Automation folder in the Example HTML Utilities folder. This is a utility that allows you to send a Connect command to the STK application by entering it into a text field and submitting it. Common application-level Connect commands can also be selected, pasted, and executed to provide useful information with just a few clicks.

Connect is an easy way to automate functions and quickly populate scenarios (for example, Drive STK with Connect Commands and Excel.

On your own

Throughout the tutorial, hyperlinks were provided that pointed to in depth information on Connect commands. Now's a good time to go back through this tutorial and view that information. Create your own Connect commands that add new objects to the scenario. Try creating reports and export them outside of the STK application. If you are planning on writing the simplest script to automate a function in the STK application, now's your chance to practice.

If you're interested in automating and extending your mission building, check out the Integrating STK with Python tutorial.