Enabling yellow bots to utilize an alternative Unix full system binary #3560

StarrryNight · 2026-01-12T01:35:14Z

Description

This ticket enables yellow bots to utilize an alternative Unix full system stored locally.

File structure:

Binary Storage and Environment Setup:

Binaries for the unix_full_system are located in the /opt/tbotspython/external_ai directory. Both the tbotspython and external_ai folders are automatically generated during the initial environment configuration by running the './setup_software.sh' script. Once these directories are created, you can integrate new binaries by simply placing them directly into the external_ai folder.

Implementation and Execution Logic:

The behavior of the yellow bots is controlled by the external_library string variable, which is found on line 430 of 'software/thunderscope/thunderscope_main.py'. If this variable is set to "default", the yellow bots will operate using the same Unix system as the blue bots. However, if you assign any other string value to external_library, the system will search the external_ai directory for a binary with a matching filename and execute it specifically for the yellow bots.
If the search doesn't result in anything, I think the program fails. But this PR is supposed to integrate with user GUI within thunderscope so I will just leave this as is.

Testing Done

Tested by copying the unix_full_system binary from another branch, enemyThreats#3373, which resolves ticket #3373. The binary logs enemy threat rankings in thunderscope every frame.
By comparing the two team's LOGs in thunderscope, we can see if it works or not.

Video:
Screencast from 2026-01-11 17-04-12.webm

(TLDR: Blue doesn't log, yellow does, so it works.)

Resolved Issues

Resolves #3555

Length Justification and Key Files to Review

Review Checklist

It is the reviewers responsibility to also make sure every item here has been covered

Function & Class comments: All function definitions (usually in the .h file) should have a javadoc style comment at the start of them. For examples, see the functions defined in thunderbots/software/geom. Similarly, all classes should have an associated Javadoc comment explaining the purpose of the class.
Remove all commented out code
Remove extra print statements: for example, those just used for testing
Resolve all TODO's: All TODO (or similar) statements should either be completed or associated with a github issue

…tbotspython

Andrewyx · 2026-01-12T03:42:49Z

Did you know that for the Review Checklist, you can do [x] to have it show as a check instead. Basically get rid of the extra space

Andrewyx

Left some comments, nice work so far

src/software/thunderscope/binary_context_managers/full_system.py

src/software/thunderscope/thunderscope_main.py

Andrewyx · 2026-01-12T04:00:48Z

src/software/thunderscope/thunderscope_main.py

+                friendly_colour_yellow=False,
+                should_restart_on_crash=False,
+                run_sudo=args.sudo,
+                running_in_realtime=(not args.ci_mode),
+                path_to_binary="software/unix_full_system",


note that blue will also need to be able to be adjusted

Andrewyx

Also, what triggered all of this formatting?

src/software/thunderscope/thunderscope_main.py

Andrewyx · 2026-01-12T22:36:32Z

src/software/thunderscope/thunderscope_main.py

+        blue_external_ai = "default"
+        yellow_external_ai = "default"


We can specify this as None type to avoid an edgecase for if someone's AI is named default

Andrewyx · 2026-01-12T22:42:25Z

src/software/thunderscope/thunderscope_main.py

+        if blue_external_ai == "default":
+            blue_path_to_binary = "software/unix_full_system"
+        else:
+            blue_path_to_binary = "/opt/tbotspython/external_ai/{}".format(
+                blue_external_ai
+            )
+
+        if yellow_external_ai == "default":
+            yellow_path_to_binary = "software/unix_full_system"
+        else:
+            yellow_path_to_binary = "/opt/tbotspython/external_ai/{}".format(
+                yellow_external_ai
+            )


Suggested change

if blue_external_ai == "default":

blue_path_to_binary = "software/unix_full_system"

else:

blue_path_to_binary = "/opt/tbotspython/external_ai/{}".format(

blue_external_ai

)

if yellow_external_ai == "default":

yellow_path_to_binary = "software/unix_full_system"

else:

yellow_path_to_binary = "/opt/tbotspython/external_ai/{}".format(

yellow_external_ai

)

default_full_system_path = "software/unix_full_system"

external_full_system_dir = "/opt/tbotspython/external_ai"

blue_path_to_binary = default_full_system_path if blue_external_ai is None else f"{external_full_system_dir}/{blue_external_ai}"

yellow_path_to_binary = default_full_system_path if yellow_external_ai is None else f"{external_full_system_dir}/{yellow_external_ai}"

Andrewyx · 2026-01-12T22:43:23Z

Left some small nits

This reverts commit 4d887e6.

nycrat · 2026-01-14T05:28:17Z

environment_setup/setup_software.sh

I think your autoformatter just made a bunch of changes to this file irrelevant to this PR, I would suggest reverting them

nycrat · 2026-01-14T05:29:52Z

src/software/thunderscope/binary_context_managers/full_system.py

+        self.full_system = "{} --runtime_dir={} {} {}".format(
+            self.path_to_binary,
            self.full_system_runtime_dir,
            "--friendly_colour_yellow" if self.friendly_colour_yellow else "",
            "--ci" if not self.running_in_realtime else "",


I think for now this is fine cause we're using our own AI, but with other teams' the arguments such as --runtime_dir should be changed. I'm not exactly sure how we would handle that but thats for later to figure out

Yeah, I agree, we should add a todo to investigate this. We will probably need some additional common interface for recieving protos aside from unix sockets

nycrat · 2026-01-14T05:35:09Z

src/software/thunderscope/thunderscope_main.py

+        blue_external_ai = "None"
+        yellow_external_ai = "None"


I think Andrew's suggestion above was to use None instead of a string. And then just change the if statements to use is None instead

Yup, the built-in None type can be used here. It should be the responsibility of the Installer to set this value, and the most clear "default" type is I think None. Also, this might be personal preference, but I like to squash simple code like this using ternaries to reduce duplicated code. It lets readers glance past this code since its not really that important to the bigger picture of thunderscope

Oops. That makes sense. Anyway, I think these two variables are just placeholders for now? When we integrate the backend we will make it read the toml file from external_ai.

nycrat · 2026-01-14T05:36:55Z

src/software/thunderscope/thunderscope_main.py

This file also has some python formatting changes, but I guess if our auto-formatter doesn't care its ok ?

Andrewyx

Almost there, left some more comments

Andrewyx · 2026-01-14T06:27:12Z

src/software/thunderscope/binary_context_managers/full_system.py

+        self.full_system = "{} --runtime_dir={} {} {}".format(
+            self.path_to_binary,
            self.full_system_runtime_dir,
            "--friendly_colour_yellow" if self.friendly_colour_yellow else "",
            "--ci" if not self.running_in_realtime else "",


Yeah, I agree, we should add a todo to investigate this. We will probably need some additional common interface for recieving protos aside from unix sockets

src/software/thunderscope/binary_context_managers/full_system.py

Andrewyx · 2026-01-14T06:37:07Z

src/software/thunderscope/binary_context_managers/full_system.py

        should_restart_on_crash: bool = True,
        run_sudo: bool = False,
        running_in_realtime: bool = True,
+        path_to_binary: str = "software/unix_full_system",


A default value here should not exist if we are also setting it in thunderscope_main. Conceptually, this makes sense since it really shouldn't be the responsibility of this binary to decide alternative launch paths. Additionally, this would be a case of semantic coupling with the default path location in thunderscope (i.e. they are hard coded to be the same which is bad for refactoring)

Andrewyx · 2026-01-14T06:42:20Z

src/software/thunderscope/thunderscope_main.py

+        blue_external_ai = "None"
+        yellow_external_ai = "None"


Yup, the built-in None type can be used here. It should be the responsibility of the Installer to set this value, and the most clear "default" type is I think None. Also, this might be personal preference, but I like to squash simple code like this using ternaries to reduce duplicated code. It lets readers glance past this code since its not really that important to the bigger picture of thunderscope

Andrewyx

pending merge conflicts, but LGTM

nycrat · 2026-01-15T19:55:15Z

@StarrryNight also if you could revert the formatting changes while you're sorting out the merge conflicts that would be great

adrianchan787

Looks good! From a previous issue of mine I think Andrew said not to use wildcard imports (though Eric also mentioned code consistency which makes sense). Idk if they should be changed, but a lot of the imports aren't wildcard imports so maybe?

StarrryNight · 2026-01-15T22:40:23Z

Looks good! From a previous issue of mine I think Andrew said not to use wildcard imports (though Eric also mentioned code consistency which makes sense). Idk if they should be changed, but a lot of the imports aren't wildcard imports so maybe?

Yes that should be changed. But those where there from the start and is not related to the ticket so I think we might have to open a separate issue to remove most (if not all) wildcard imports

annieisawesome2

looks good!

StarrryNight added 4 commits January 11, 2026 16:23

add option to change unix system binary path for yellow

36fa101

change setup.sh to automatically generate external_ai folder in /opt/…

05601ff

…tbotspython

remove convoluted file strucutre required in external_ai

59a4862

set to default

2bd5268

StarrryNight requested review from Andrewyx, sauravbanna and williamckha as code owners January 12, 2026 01:35

Andrewyx reviewed Jan 12, 2026

View reviewed changes

enable same thing for blue bots and add docs

04e6099

Andrewyx reviewed Jan 12, 2026

View reviewed changes

StarrryNight added 4 commits January 12, 2026 19:53

change default to None

4d887e6

Revert "change default to None"

b2c6b37

This reverts commit 4d887e6.

add TODO link

9c4303d

format

3df840e

StarrryNight requested review from Andrewyx, adrianchan787, annieisawesome2 and nycrat January 13, 2026 19:15

nycrat reviewed Jan 14, 2026

View reviewed changes

Andrewyx reviewed Jan 14, 2026

View reviewed changes

StarrryNight added 2 commits January 14, 2026 22:23

Remove default binary parameter

136f3e3

Change None from string and use ternaries for logic

f6009bc

Andrewyx previously approved these changes Jan 15, 2026

View reviewed changes

nycrat previously approved these changes Jan 15, 2026

View reviewed changes

adrianchan787 previously approved these changes Jan 15, 2026

View reviewed changes

Merge branch 'master' into externalDirectoryInitialization

39e1daf

StarrryNight dismissed stale reviews from adrianchan787, nycrat, and Andrewyx via 39e1daf January 15, 2026 23:34

annieisawesome2 previously approved these changes Jan 16, 2026

View reviewed changes

Fix merge conflict

a19a9ee

StarrryNight dismissed annieisawesome2’s stale review via a19a9ee January 16, 2026 20:26

StarrryNight and others added 2 commits January 16, 2026 14:12

Update thunderscope_main.py

d3e2569

fix merge issues

6c8b249

Enabling yellow bots to utilize an alternative Unix full system binary #3560

Are you sure you want to change the base?

Enabling yellow bots to utilize an alternative Unix full system binary #3560

Uh oh!

Conversation

StarrryNight commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing Done

Resolved Issues

Length Justification and Key Files to Review

Review Checklist

Uh oh!

Andrewyx commented Jan 12, 2026

Uh oh!

Andrewyx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andrewyx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andrewyx commented Jan 12, 2026

Uh oh!

nycrat Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andrewyx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andrewyx left a comment

Choose a reason for hiding this comment

Uh oh!

nycrat commented Jan 15, 2026

Uh oh!

adrianchan787 left a comment

Choose a reason for hiding this comment

Uh oh!

StarrryNight commented Jan 15, 2026

Uh oh!

annieisawesome2 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

StarrryNight commented Jan 12, 2026 •

edited

Loading

nycrat Jan 14, 2026 •

edited

Loading