Runtime

PiE C-Runtime

Welcome to the PiE Runtime repo! If you're new a staff member, then welcome to PiE, and welcome to the Runtime project! We're so glad to have you with us, and that you chose to give Runtime a shot! This Wiki will hopefully be a nice overview of what Runtime is all about and how it's built, and answer some basic questions you might have about our project and this code. If you have any questions, please ask the Runtime project manager(s)! We highly encourage you to read through the whole thing, it'll be really useful, we promise! Without further ado, let's get started...

What is Runtime?

As you know, Pioneers in Engineering is a student organizations that hosts a robotics competition for underserved high schools in the SF Bay Area. To do this, we build everything in house, including our software. So, when the students get their robotics kits to build their robots, it includes motors, sensors, servos, gears, metal, and a computer to actually run their robot. Runtime is responsible for writing the software that runs on that computer (a Raspberry Pi, at the time of this writing), as well as the software that runs on the Arduinos attached to all the motors, sensors, and servos.

Students also write their own code to control their robots, which they upload to the robot for it to run. Most of their code consists of things like "when the Y button on the gamepad is pressed, I want to move this servo to this position" which does something that scores points. The code that Runtime writes for the Raspberry Pi needs to be able to run the student's code and translate that into actual commands to the sensors on the robots.

Students use the "Dawn" computer application (also made by PiE) running on their laptops to write their code, connect their Xbox controllers (we call them "gamepads" in Runtime) to, and view the current state of the various devices attached to their robot. Runtime's software must be able to communicate with Dawn to receive commands and student code, and report device data back to Dawn.

During the competition, the software "Shepherd" (another PiE software project) is used to control the field and run the game. Shepherd connects to the robots in order to tell them which side of the field they're on, where the robots are starting within each side, and when to go into autonomous (auto) mode, teleoperated (teleop) mode, and idle mode. Runtime's software must be able to communicate with Shepherd to receive these commands and report any status updates back to Shepherd.

The devices that are attached to the robot (motors, servos, sensors) must, of course, interact with the software on the Raspberry Pi. When the student's code wants to command a motor or servo to a new speed or position, it needs to send that information to the Arduino on the device that is controlling it. When the student's code wants to read the value of a sensor, the software on the Raspberry Pi must make that information available to it. And, the software on the Raspberry Pi must be able to detect when new devices have connected, or devices have been disconnected (unplugged) from the robot. Runtime is responsible for ensuring all of this behavior.

So, as you can see, Runtime does a lot! But, how does it all work?

Design Principles

Runtime is all about speed and reliability.

It needs to be fast, so that student code doesn't lag, so that inputs from the gamepads don't lag, and so that it can handle as many devices as the students would ever put onto their robot without crashing or noticeable slowing down of the system. This guided a lot of our early design decisions, and is part of the reason why we chose to write the entire system in C. ¹

Runtime also needs to be easy to debug and very robust, because nothing frustrates a student more than when the robot's software breaks while they're working, and it has nothing to do with their code. They get even more frustrated when they bring the broken robot to PiE staff members, who then take hours to try and solve the problem because the staff members can't debug the problem efficiently.

Lastly, Runtime should be as easy to understand, set up, and maintain as possible, because the last thing we want is for the learning curve for staff to become so steep that it becomes impossible to keep the code stable, simple, and healthy.

With that said, we now see the need for the following design principles:

• Keep It Simple, Stupid (KISS). In Runtime, this means that we want to keep the number of dependencies on third-party libraries to a minimum. This reduces the complexity of building Runtime. Third party-libraries also often have incomplete or questionable documentation; having fewer third-party dependencies means that there is less documentation new staff members have to read in order to begin understanding and working on Runtime.
• Document, document, document. As you can probably tell by the length and detail in this README, we take our documentation seriously. Mark your TODO items. Describe your functions. Name things well. Write and update READMEs whenever possible. We need to document everything to make it easy for staff to onboard, and for seasoned staff to maintain and extend the code.
• Be Able to Log Anywhere. Runtime has a logger that can send logs from anywhere within the system to a file, terminal, or over the network to Dawn if Dawn is connected. It is crucial that this logger be maintained, and for log statements to be added into the program wherever necessary (including in the Arduino devices). When a problem arises, staff must be able to turn on these logs, allowing them to see exactly what is happening in the system from somewhere, which enables efficient debugging.
• Consider All Posssibilities. Try to consider all the errors and situations possible. What should happen in each case? Should Runtime restart? Should it handle the error and continue as normal? Should it revert to some default behavior? This all helps make Runtime as robust as possible, helps us debug efficiently when Runtime crashes, and helps keep students happy when Runtime doesn't crash.
• Test, test, test. It is hard to test such a large system, but if at all possible, the effort must be made to test our code.