STU Lunar SAR API Docs

Up to date for Platform 0.27.3 and STU Lunar SAR 1.0.1

Written by Neil McHenry and Connor Jakubik

Prerequisites:

STU Lunar SAR Competitor Setup & Learning

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

Changelog:

2024/10/23 Newly created

Link back to STU 2024 Lunar SAR Rules & Info: https://github.com/SimDynamX/SpaceTeamsPro/discussions/33

Link to Starter Code repository: https://github.com/SimDynamX/STU_Lunar_SAR

How to set up your development environment

Do the setup steps from here: STU Lunar SAR Competitor Setup & Learning

There are several ways to do python development; here is one way that is the typical way we at SimDynamX set it up.

Install VS Code and open it
Do Open Folder to C:\Users\YOUR WINDOWS USERNAME\AppData\Local\SimDynamX\STPro\Assets
Open one of the .py files in Repos/STU_Lunar_SAR_YourTeamName
If prompted, install the recommended python extensions, and wait for those installs to complete
Set your Python interpreter to the one that was installed during setup
1. While having a python file open, click the python version number in the bottom right of the screen
2. At the top of the screen, click Enter interpreter path...
3. Click Find...
4. Navigate to AppData\Local\SimDynamX\STPro\Versions\(the highest version number in there)\py\Scripts and select python.exe, then Select Interpreter
5. Should now be switched to the correct python interpreter
6. And you should get syntax highlighting for the spaceteams python module.

Which files to modify for Task 1

The files in the starter code repository that are in the top folder (not API or sims subfolders) are available to be edited by competitors. There are some exceptions:

There are a few things you will need to edit in the sims/STU2_SAR_Task1.json sim config file:
- All paths that reference STU_Competition2, like the Source file for the MissionManager system will need to have the STU_Competition2 changed out with the repo/folder name that you are using as the name for your copy of the starter code repo.
Don't edit CompetitionBackend.py
You can in general change the Source on any of these python systems in order to change out which .py file in your repo they are using:
- MissionManager
- EntityBehavior_LTV1
- EntityBehavior_LTV2

Where you should start is making small modifications to the starter code in ExampleMM_TaskgraphSimple.py, and seeing what happens when running the sim. Make good use of st.OnScreenLogMessage() and st.OnScreenAlert() for easy-to-see printing.

How to run the Task sims in SpaceCRAFT (the graphics portion of SpaceTeamsPRO)

Do the path rename change mentioned above (after having done all the setup steps)
Open SpaceCRAFT.exe
Log in
On the main menu, Sim->User-Created Sims->Search for and click Repos/STU_Lunar_Sar_YourTeamName/sims/STU2_SAR_Task1.json->Confirm

Handling errors and crashes

If the Compute_Server crashed on sim startup, the sim may seem to start normally but around 10 seconds later a dialog box with this message comes up:

UE Server: Failed to connect to server, reason: [10061] Failed to connect to locally-running Compute_Server for simulation; this could mean Compute_Server crashed. 
Check the latest-modified file in the Compute_Server/Logs folder for more details. 
Would you like to return to the main menu? "No" quits the application.

If the Compute_Server crashed during the sim, a dialog box with this message comes up:

Simulation stopped; reason: [10054] Existing Platform data connection to locally-running Compute_Server was forcibly closed; this could mean Compute_Server crashed. 
Check the latest-modified file in the Compute_Server/Logs folder for more details. 
Would you like to return to the main menu? "No" quits the application.

If something like this happens, find out what caused the sim to crash by finding the set of most-recently-edited .log files in /Compute_Server/Logs'. ![image](https://github.com/user-attachments/assets/3f086f37-b0ba-47d8-b91f-64447944ca9e) The shortest-name log (maybe Sim_STU2_SAR_Task1.log`) will be the main Compute_Server log. Open that one.

Common errors:

Python System Instance MissionManager invalid Source filepath
- Maybe you didn't rename the folder as explained above?
- Maybe you renamed the .py file but didn't update the sim config to match?
[FATAL]---[Main->PySys_MissionManager @NID:2]: ST Netcode: [10054] Existing connection was forcibly closed by the remote host. This is an unhandled disconnect, probably due to Python System MissionManager crashing / terminating. See Compute_Server/Logs/Sim_STU2_SAR_Task1_PySys_MissionManager.log for more details. Terminating program due to this unhandled disconnect.
- Do as it says; the error is likely in that Python System's log file.

API Documentation

Available Mission Manager Functions

This section lists the commands available for use in the mission manager script. Each command is designed to control specific actions of an entity within the simulation environment.

Movement Commands

MoveToCoord
- Moves an entity to a specified XY coordinate.
- Parameters:
  - en: The entity to be moved (e.g., LTV1).
  - xy: An XY object representing the target coordinate.
  - task_id: A unique string identifier for this move command.
- Example Usage:
```
# Create an XY coordinate object
target_xy = XY(100.0, 50.0) 

# Create a MoveToCoord command for LTV1 with task ID "Move1"
move_command = Command_MoveToCoord(LTV1, target_xy, "Move1") 
```

Orientation Commands

RotateToAzimuth
- Rotates an entity to a specified azimuth angle.
- Parameters:
  - en: The entity to be rotated.
  - azimuth: The target azimuth angle in degrees.
  - task_id: A unique string identifier for this rotate command.
- Example Usage:
```
# Create a RotateToAzimuth command for LTV2 to face 90 degrees with task ID "Rotate1"
rotate_command = Command_RotateToAzimuth(LTV2, 90.0, "Rotate1") 
```

Camera Commands (Not available in Platform 0.27.1 or 0.27.2 and STU Lunar SAR 1.0.0, will be enabled for Activity 2)

CameraPan
- Controls the pan of a camera attached to an entity.
- Parameters:
  - en: The entity whose camera will be panned.
  - azimuth_deg: The target azimuth angle in degrees.
  - elevation_deg: The target elevation angle in degrees.
  - task_id: A unique string identifier for this camera pan command.
- Example Usage:
```
# Create a CameraPan command for LTV1 with task ID "CameraPan1"
camera_command = Command_CameraPan(LTV1, 45.0, 30.0, "CameraPan1") 
```
CaptureImage
- Captures an image using a camera attached to an entity.
- Parameters:
  - en: The entity whose camera will capture the image.
  - exposure: The exposure value for the image capture.
  - task_id: A unique string identifier for this image capture command.
- Example Usage:
```
# Create a CaptureImage command for LTV2 with task ID "Capture1"
capture_command = Command_CaptureImage(LTV2, 4.0, "Capture1") 
```

Entity Telemetry

The EntityTelemetry module provides functions to access telemetry data for entities in the simulation. This data includes position, orientation, sensor readings, and communication status.

Example Usage:

import API.EntityTelemetry as ET

# Get the current XY position of LTV1
current_xy, has_comms = ET.GetCurrentXY(LTV1)

# Get lidar obstacle data from LTV1
rel_vecs, radii, had_comms = ET.GetLidarObstacles(LTV1)
st.logger_info("Lidar info: " + str(rel_vecs) + ", " + str(radii) + ", " + str(had_comms))

Entity Telemetry Functions

HasComms(en)
- Checks if an entity has communication capabilities.
- Returns: True if the entity has comms, False otherwise.
GetMovementState(en)
- Retrieves the movement state of an entity.
- Returns: A tuple containing the movement state (e.g., "Moving", "Stopped") and a boolean indicating comms status.
IsMoving(en)
- Checks if an entity is currently in motion.
- Returns: A tuple containing a boolean indicating if the entity is moving and another boolean for comms status.
GetCurrentXY(en)
- Gets the current XY coordinates of an entity.
- Returns: A tuple containing an XY object representing the coordinates and a boolean for comms status.
GetMoveToXY(en)
- Gets the target XY coordinates to which an entity is moving.
- Returns: A tuple containing an XY object representing the target coordinates and a boolean for comms status.
GetAzimuth(en)
- Gets the current azimuth angle of an entity.
- Returns: A tuple containing the azimuth angle in degrees and a boolean for comms status.
GetLidarObstacles(en)
- Retrieves lidar sensor data about obstacles around an entity.
- Returns: A tuple containing a list of relative vectors to obstacles, a list of their radii, and a boolean for comms status.
GetTargetScanStatus(en)
- Checks if the target has been detected by the scanner.
- Returns: A tuple containing a boolean indicating target detection, the target's location as a NumPy array, and a boolean for comms status.

Task Graph

The TaskGraph module provides a way to define and manage a sequence of tasks with dependencies. Each task represents an action to be performed by an entity, such as moving to a location or capturing an image. The task graph ensures that tasks are executed in the correct order and that dependencies between tasks are met.

Example Usage:

import TaskGraph as TG

# Create a task graph
task_graph = TG.TaskGraph()

# Define tasks
task1 = TG.Task("Task1", Command_MoveToCoord(LTV1, XY(10, 20), "Task1"))
task2 = TG.Task("Task2", Command_RotateToAzimuth(LTV1, 90, "Task2"))

# Add tasks to the graph with dependencies
task_graph.add_task(task1, [])  # No dependencies for the first task
task_graph.add_task(task2, ["Task1"])  # task2 depends on task1

# ... (rest of the script)