STU Lunar SAR Competitor Setup & Learning - SimDynamX/SpaceTeamsPRO GitHub Wiki

Up to date for Platform 0.27.6 and STU Lunar SAR 1.3.2

Written by Fernando Arias and Connor Jakubik

Rules & Info Setup & Learning (Here) STU API Docs Q&A Discussions Category Starter Code Starter Code Releases

Changelog:

  • 2024/10/27 Added video errata.
  • 2024/10/25 Changed how we refer to API Docs page, where there are some critical steps to do before running the task sims.
  • 2024/10/21 Newly created

Competitors are required to do Lessons 1-3 and 7-10, as well as the Git Setup and Task 1 file modifications to be ready to start the competition.

STU Lunar SAR Lesson Overview

The lessons on this page are logically sequenced to give you a general understanding of how to use the Space Teams PRO platform. For general use of Space Teams PRO, it is recommended to watch them in order. However, for the Lunar SAR Design Challenge, you can get started more quickly if you skip the ones marked (OPTIONAL). For the complete library of Space Teams PRO training, see the full documentation here: https://github.com/SimDynamX/SpaceTeamsPro/wiki.

Getting Started Document - Everything you need to guide you through the startup process

Competition-Specific Learning

** Lesson 1: Space Teams Setup **

In this lesson, you will learn how to set up Space Teams PRO.

Tutorial Video:

https://youtu.be/YuNOEanW6l0

Video errata (updated 2024/10/27):

  1. Initially goes to SimDynamX/SC_Platform repository. Users will not see this. Should be SimDynamX/SpaceTeamsPro.
  2. Code section on SpaceTeamsPro repo is just a few reference PDFs; it’s only there because GitHub requires a repo to have code. The meaningful sections of the SpaceTeamsPro repo are the Issues, Discussions, and Wiki.
  3. There is a new step on spaceteamspro.com to activate the personal use trial license that you get from making an account.
  4. Recommended to open the top-level install directory (SpaceTeamsPro…) in VS Code so you can see SharedData directory. For user files, recommended to open the Assets folder (same folder that it takes you to from the button in Project Management).
  5. Some updates to the UI since the video was recorded.

Related Documentation

  1. Installation Setup
  2. Starting your First Sim
  3. Space Teams Pro Wiki - Installing Space Teams
  4. How To Start a Sim

Lesson 2: Platform Basics

This lessons explains the Space Teams PRO application user interface. Learn how to set up the initial conditions of a simulation including selection of location and assets, placement, initial conditions, and choice of built-in models.

Tutorial Video:

(https://www.youtube.com/watch?v=pYcoKw95eiM&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=3)

Video errata: (TBD)

Related Documentation

  1. Starting your First Sim

Lesson 3: Simulation Configuration

This lesson explains the format and content of the Space Teams SimConfig file, which fully describes a mission scenario that you can create anywhere in the solar system and involving any asset, and models of entity behavior or the environment. NOTE: The competition only involves a limited amount of Sim Config editing, as the users are only allowed to change out which System Source files are used for the Mission Manager and Entity Behavior systems.

Tutorial Video:

https://www.youtube.com/watch?v=HVizBCWP7U8&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=2

Video Errata (updated 2024/10/27):

  1. The proper name for Sim Config files is “Sim Config”, not JSON. It happens to be JSON format and use a .json file extension for now. Many people call it a JSON anyway; this will change (later) when rename all our sim config and entity config files .simconf and .enconf.
  2. The Local Assets folder can be easily opened through a button in the Project Management UI in the main title menu.
    1. The main reason it’s in there and not Documents is the Local Assets folder should primarily be managed by tools dealing with git repos and such. If we put it in Documents, various things such as OneDrive and other backup tools would conflict with the file operations and cause chaos. Also, if someone else downloads your sim and the file paths point at Documents, there is no guarantee you don’t already have same-named files there that conflict. We might at some point add another “file location type” which points to somewhere more convenient to manage manually such as Documents.
  3. Data_Monitor is still possible to use but we have much better tools now: ParamWrangler.py and the Parameters gadget in SpaceCRAFT. Data_Monitor requires running a separate python script to start the viewing program. It's not necessary to get data out of the sim. I typically leave that out and use ParamWrangler, and set Active to false when I don’t want it to pop up.
  4. Spicy uses NAIF CSPICE, which is the C library for the SPICE toolkit, an space ephemeris processing toolkit updated by JPL. We wrote Spicy; NAIF wrote CSPICE.
  5. Should use more recent format for Time section on SimEntity; reference the sim config wiki.
  6. Gadgets will need an update for the Tabbed UI gadgets update. See https://github.com/SimDynamX/SpaceTeamsPro/issues/43.
  7. Dynamics section
    1. See https://github.com/SimDynamX/SpaceTeamsPro/wiki/The-Entity#dynamics for current info.
    2. InterpolationType, IsRebaseCenter, and GenerateCollider are deprecated; no effect on the sim.
    3. In general, there are many Dynamics parameters that are required or not depending on what propagator you are using on an Entity. Expected to have some changes soon with a refactor to how entity propagators are assigned.
    4. ResidentFrame is important. Reference the Entity wiki page for more details.
    5. PropagationType affects quite a few things. Reference the Entity wiki page for more details.
  8. Rotation is xyzw Hamilton, right handed quaternion.
  9. Much of the video content is focused on sim details of how SnapAssetToSurface and the other pawn details work. The Sim Config in particular does not require all of these elements to be there; see https://github.com/SimDynamX/SpaceTeamsPro/wiki/The-Sim-Config for current info.
  10. FromTemplate entity type loads an EntityConfig (which can be a different Entity Type) from Source_Path entity config file and applies ParamOverrides to add or replace parameters on the entity config before loading it as an entity in the sim. It has nothing to do with Model Import. Model import happens on the Object_Loaded entity type, or (older and deprecated) on a BP entity type with BP path Entity_Loaded_BP (if I recall correctly).
  11. You don’t need to be on a MoonCentered include-sim to do stuff on the moon. All of our locations, etc are relative based on ResidentFrame so you are meant to only use some of these IncludeSims:
    1. Core/Compute_Server/BaseSims/SolarSystem
    2. Core/Compute_Server/BaseSims/SolarSystem_InertialFrames (these top two are the typical ones)
    3. Core/Compute_Server/BaseSims/EarthMoonSun (SolarSystem minus everything but earth, moon, sun, and SSB)
    4. A few VERY particular ones for REALLY specialized sims.
    5. In general picking the include sims is something that our Create New Sim tool in the UI will do for you. As of 0.27.3 still work in progress.
  12. Systems that are Active: false can still be applied to entities.
  13. Sort by most-recently-created in the Logs folder to have the most recent logs be shown on top.

Code Examples

https://drive.google.com/file/d/1v8InF2F_aSa6oEFYGgNVITD0ZYGbpFMJ/view?usp=sharing

Related Documentation

  1. Sim Structure
  2. The Parameter
  3. The Sim Config

Lesson 4: Satellite Orbiter (OPTIONAL)

This lesson demonstrates the example of setting up a spacecraft in orbit around a planetary body. NOTE: The competition does not rely on any orbital sim elements.

Tutorial Video:

https://www.youtube.com/watch?v=Z-sUqkTrO-Y&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=4

Video errata: (TBD)

Code Examples

https://drive.google.com/file/d/182rRVFEPo-Wq1-pe29zJ2GL7GQLAIpLZ/view?usp=sharing

Lesson 5: Model Import (OPTIONAL)

This lesson explains how any CAD models created external to Space Teams can be imported and used within simulations. NOTE: The competition does not require user customized use of Model Import.

Tutorial Video:

https://www.youtube.com/watch?v=_3P4UlP1OhY&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=5

Video errata: (TBD)

Code Examples

https://drive.google.com/file/d/1rD2aIb-Ie0iYvzn2JSvl22nbRlv1sKf_/view?usp=sharing

Lesson 6: Pawns (OPTIONAL)

Pawns are entities for users to control their own movement within a simulation, which could be as a spectator or one of the entities. For example, walking on a planetary surface, or flying through the solar system, utilize different pawns. NOTE: The competition starter code sims already have all the pawns they need; the Spectator pawn allows the user to fly around the mission area and see operations happening in real time.

Tutorial Video:

https://www.youtube.com/watch?v=pSupeGar1U8&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=6

Video errata: (TBD)

Code Examples

https://drive.google.com/file/d/1v8InF2F_aSa6oEFYGgNVITD0ZYGbpFMJ/view?usp=sharing https://drive.google.com/file/d/1iIWTAWu1uxZHixKxcyrodwEeqEDefHoa/view?usp=sharing

Lesson 7: Python Systems

In this lesson, you will learn how you can build your own Python system and implement it in Space Teams.

Tutorial Video:

https://www.youtube.com/watch?v=ymeQkxKzFd8&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=7

Video errata: (TBD)

Code Examples

https://drive.google.com/file/d/1v8InF2F_aSa6oEFYGgNVITD0ZYGbpFMJ/view?usp=sharing https://drive.google.com/file/d/1WFuSxa3ovtSxfUvJ3p7b_1zlpNp1-Yu4/view?usp=sharing

Related Documentation

  1. Make New Python System
  2. Python API Docs

Lesson 8: Git Repo Cloning and Collaboration

This lesson explains how to integrate Space Teams with Git in order to manage and share team files that are used in your simulations.

Tutorial Video:

Coming Soon

Related Documentation

  1. Git Setup section on this page

Lesson 9: Sim Structure - STU Mission Manager, Task Graph & Entity Behavior

The event control architecture within Space Teams is explained. At the highest level, this involves an Event Manager for sim-wide event notification and actions. A Mission Manager controls the evolution of a simulation through data/state monitoring, decision making, and sending commands to all the entities. At the lowest level each entity has its own behaviors and responses to commands and the environment.

Tutorial Video:

https://www.youtube.com/watch?v=aMUDOElaqtU&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=8

Video errata: (TBD)

Related Documentation

  1. STU Lunar SAR API Docs

Lesson 10: Command and Control: Lunar Search and Rescue

This lesson focuses on programming the Mission Manager, which for this competition is key for putting your search and rescue strategy into action. It covers how to access entity data/telemetry and how to send commands to control all entities within your simulation.

Tutorial Video:

https://www.youtube.com/watch?v=zrobcd-xjGk&list=PLV9n3IHgy_dTQ1Lumj-QYev9qfvlQIndE&index=12

Video errata: (TBD)

Code Examples

https://drive.google.com/file/d/1dsCL7LxJbz2eLHUGvZDYsL79F27ub13o/view?usp=sharing

Related Documentation

  1. STU Lunar SAR API Docs
  2. The Entity
  3. The Parameter
  4. The Entity Config

Lesson 11: Running a Demo Simulation in VR (OPTIONAL)

In this lesson, you will learn how to launch Space Teams in VR and how to run a VR demo simulation.

Tutorial Video:

Coming Soon

Related Documentation

  1. How To Start a Sim - Differences for VR

Quick Git / GitHub Primer

Git is a distributed version control system used to track changes in source code during software development. It allows multiple developers to collaborate on projects (repositories) by creating, managing, and merging branches. Git stores snapshots (commits) of project files over time, enabling users to revert to previous versions if needed. It is widely used in both individual and team development workflows for its efficiency and flexibility.

GitHub is a web-based platform that hosts Git repositories, allowing developers to store, share, and collaborate on code. It provides tools for version control, issue tracking, and project management, making it easier for teams to work together. GitHub also supports features like pull requests and code reviews, streamlining the process of contributing to open-source and private projects.

STU Lunar SAR Git Setup

Our public STU_Lunar_SAR git repository, hosted on GitHub, is the starter code that we give out to participants to start programming their autonomous search and rescue algorithms. The SimDynamX copy of the repository will be consistently updated throughout the competition as we add more sims and functionality to the starter code for tasks past Task 1. The SimDynamX repository is set up as a Template Repository, so there is an easy way for participants to duplicate it and modify their (private) copy as their own repository. Once your team has made their own copy, they should probably keep using Git / GitHub to collaborate on code and data additions and changes. One good reason for that is: when it is time to submit for a task, the submission will involve filling out a form and providing a GitHub link to a particular commit (saved state) on your repository.

Some teams may opt to have only a few of the team members actually set up GitHub accounts or Git on their computers, and that is ok.

The following steps show how to set up your team's repo.

1. GitHub account setup

  1. Every member of your team should probably have their own GitHub.com account
  2. https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account

2. Create a repository from the STU Lunar SAR Template for your team:

Screenshot 2024-10-22 014644

  1. Go to https://github.com/SimDynamX/STU_Lunar_SAR
  2. Use this template -> Create a new repository Screenshot 2024-10-22 014812_marked
  3. Set the Owner to your own account, and Repository Name to STU_Lunar_SAR_Your_Team_Name, substituting a unique-enough name.
    1. For example, STU_Lunar_SAR_AstroBlasters
  4. Set repository to Private so your changes are not publicly viewable
  5. On your new repository, use Settings -> Collaborators -> Add People to give your fellow team members permissions to access and modify the repository.

3. Back on https://github.com/SimDynamX/STU_Lunar_SAR, enable notifications for Release updates

Screenshot 2024-10-22 014928 Screenshot 2024-10-22 014938

  1. Watch -> Custom -> check Releases -> Apply
  2. This way, you will be notified by email when we update the competition starter code for the remaining tasks and any bug fixes.

4. Clone your copy of the repository in Space Teams

image (14)

  1. Open SpaceCRAFT/SpaceCRAFT.exe where you installed Space Teams Pro
  2. Sign in to your account
  3. On the title menu, Project Management -> Clone a Repo
  4. Fill in the HTTPS Clone URL of your team's copy of the STU Lunar SAR repo
  5. Folder name will automatically populate
  6. Clone
  7. Refresh once the Clone is complete
  8. Now continue to the Lunar SAR API Docs wiki page for further instructions for how to set up and run sims.

STU Lunar SAR Git Collaboration

Space Teams PRO has a simplified interface in the SpaceCRAFT app Project Management tab of the main title menu for collaborating using Git Repositories in the Local Assets folder. This allows the user to:

  • Clone a repo (download it and set it up with Git in the proper folder to be visible to Space Teams)
  • Refresh button that does a git fetch operation that compares the state of all repos to their online copy
  • Pull changes (download and apply commits (changes) that were made on a different computer then Pushed)
  • Push changes (upload changes that were made on the user's computer to the online copy)

Lots of the time, these commands will be the only ones you need. When you start working, do a Refresh to see if any of your cloned repos can be updated. Do a Pull on the repos that are ahead of your copy with online changes. Do your work, changing files as you go. Every now and then, probably close to once per hour, do a Push, which uploads your changes so your team members can Pull them.

You can look through the entire history of every change that was ever pushed on the GitHub repo site for your copy.

Merge Conflicts

If two people edit the same section of the same file from the same starting point, a Merge Conflict happens. This cannot be sorted out through the Space Teams PRO git interface. We recommend setting up GitHub Desktop on your computer to handle these edge cases. More info on merge conflicts is available here: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts

GitHub Desktop Setup

  1. Install https://docs.github.com/en/desktop/installing-and-authenticating-to-github-desktop/installing-github-desktop
  2. Sign in with your GitHub account
  3. Add your STU repository
    1. (GitHub.com instructions: https://docs.github.com/en/desktop/adding-and-cloning-repositories/adding-a-repository-from-your-local-computer-to-github-desktop)
    2. with File->Add local repository->Choose...
    3. Navigate to C:\Users\YOUR WINDOWS USERNAME\AppData\Local\SimDynamX\STPro\Assets\Repos
    4. Select the STU_Lunar_SAR_YourTeamName folder
    5. Add repository
  4. Learn about how to use GitHub Desktop here: https://docs.github.com/en/desktop/overview/getting-started-with-github-desktop