Repository Tour

Repository Tour

There is a lot of code. This is what it does.

Top Level

The root of the repo contains a folder named shepherd, and a bunch of "metadata" files like the the .gitignore and requirements.txt. The metadata is mostly just for logistical stuff; here's a breakdown of the important files:

• .gitignore specifies the files that shouldn't be uploaded to github; for example, your google authentication token.
• .travis.yml controls Travis, which can automatically run tests on pull requests.
• requirements.txt specifies the Python dependancies you need to get Shepherd up and running.
• shepherd_tmux.sh is a script that you can use to quickly launch all the different parts of Shepherd.

All the actual source code is contained within the inner shepherd folder, so let's dive into that.

Source code

Inside the Shepherd folder are a few different folders:

• lowcar/ is magic Runtime code that we use for sensors. Check out https://github.com/pioneers/runtime for more info on that.
• protos/ are objects/messages that we use to communicate with Runtime (see: runtimeclient.py)
• sensors/ is an amalgamation of python and C code used to talk to sensors. Sensors wiki
• sheets/ is where all the static data used by sheet.py goes.
• static/ is for html/css/js/etc files used by the Flask server.
• templates/ is for html "templates" used by the Flask server. Flask server and UI wiki

Also in the main folder are the important .py files that get run. These are:

• shepherd.py is the big big. You can think of it as the "connecting" program that runs the game, and talks to UIs, sensors, Runtime, and sheets.
• ydl.py (pronounced "yodel") is how the different parts of Shepherd talk to each other. It's like a mailman that delivers messages between processes. YDL wiki
• server.py runs the Flask server. Flask server and UI wiki
• sensors/sensor_interface.py talks to sensors. Sensors wiki

Note that the above 4 files get run in parallel; they asynchronously pass YDL messages to each other. There's more code which gets imported by the big 4 (well, mostly by shepherd.py):

• utils.py is used to specify things like YDL headers, constants, available UI pages, etc.
• runtimeclient.py is a TCP client that talks to Runtime, which runs TCP servers on Raspberry Pis on the robots. Sending messages to Runtime is how we do things like tell the robots to turn on.
• sheets.py fetches data from Google Sheets, or a csv file if offline. Also pushes data to Google Sheets.
• timer.py makes Timer objects, which will asyncronously send YDL messages to shepherd.py afer a certain length of time. Since shepherd.py is usually the one that makes timers, yes, it's sending messages to itself.
• sensors.py specifies which sensors exist. This is used by sensors/sensor_interface.py.
• alliance.py, robot.py, and challenge_results.py are just objects that shepherd.py uses to store data.

The remaining files don't get run during a real game, but are still pretty important:

• coding_challenge_problems.py is, well, coding challenge problems. Don't name this code.py or the Flask server will immediately go down in flames.
• dummy_sensor.py can be used to test sensors.
• fake_runtime.py can be used to test the connection to Runtime

(note: in the future, testing framework will be added. If you see tests/, tester.py, testing_script.py, etc, that's what those are)

Shepherd's Green Crayons

Every year, parts of Shepherd get rewritten to match that year's game. In this section I'll rate how "permanent" each part of Shepherd is, on a scale of 1-5:

• alliance.py, robot.py: 1. What data Shepherd needs to store is very game specific. In sp2021, we didn't even have alliances.
• sheet.py: 1.5. In theory this should be a 4, but the google sheets authentication API changes every 2 months, and the code here depends on the layout of the spreadsheet.
• shepherd.py: 2. Since most of the game logic goes here, usually shepherd.py will keep a similar structure, but have a large volume of code be rewritten every year.
• UIs (html files): 2.5. Some parts of the UIs should be stable, but a lot of stuff is game-specific.
• utils.py: 3. Similar structure from year to year, with individual headers, constants, states, etc being added or removed.
• runtimeclient.py: 3. Different types of messages to runtime will need to be added from year to year. At some point we may need to handle receiving data from Runtime.
• Sensors: 4. The way sensors are implemented right now should be pretty stable, I think? idk
• server.py: 4.5. I don't anticipate much changing about the Flask server itself, but we may want to add more features to it in the future.
• ydl.py: 5. YDL/LCM has had the exact same interface for 4 years straight. The sun will burn out long before we need to make any changes to it.