How ubc-thunderbots/software works
Based on both the file tree and the README, this repository is the central “Software” and firmware repository for a robotics system that participates in RoboCup Small Size League competitions. In other words, it’s a large-scale robotics software project that combines decision-making, simulation, real‐robot embedded software, and a host of utilities (such as geometry, physics, multithreading, logging, networking, etc.) built on top of a Bazel-powered build system.
• Core Framework & Build System: Represent Bazel’s BUILD/WORKSPACE files, overall source (“src”) hierarchy, and shared utilities. This provides the structural backbone of the project.
• AI and Decision-Making Module: Represent components under src/software/ai, including the high-level play selection FSM, tactics (attacker, defender, goalkeeper, etc.), evaluation, and STP (situation “play”) modules.
• Embedded and Hardware Control: Include modules under src/software/embedded, which handle communication with hardware (GPIO, power, motor control, estop, etc.), as well as firmware tasks.
• Backend & Communication Services: Capture components such as src/software/backend and networking components under src/software/networking and src/software/estop, which bridge the decision-making (AI) with robot actuation and sensor feedback.
• Simulation & Testing: Include simulation-related modules (e.g., src/software/simulation, er_force_simulator, field_tests, simulated_tests) to represent how the system is validated in a simulation environment.
• Shared Libraries & Utilities: Represent supporting libraries for geometry (src/software/geom), physics (src/software/physics), math, multithreading, logging, sensor fusion, and others that provide essential algorithms and basic services used across components.
• Communication Protocols & Protobufs: Identify directories like src/proto and parts of extlibs that handle protocol buffers and other message translations (also relevant if the system is interacting with external controllers or simulators).
Interactions and relationships
• Layering: Illustrate a layered architecture where the low-level embedded services and hardware communications serve as the foundation, above which lie real-time services (e.g., logging, network communications) and on top the AI decision and planning modules.
• Inter-Module Communication: Highlight the importance of message passing via protos and shared communications libraries (for example, between networking components and the backend) to integrate simulation results with live data.
• Testing/Simulation: Show a dedicated simulation/testing block that is “wired” into the system via the AI modules and sensor fusion, outlining how simulation results can loop back into the system as inputs for refinement/testing.
Important architectural patterns and design principles
• Modularity: The repository is organized in a highly modular way so each component (AI, Embedded, Simulation, etc.) is nearly self-contained with its BUILD files and tests.
• Separation of Concerns: Clearly separating the decision-making (AI/stp/tactics) from the hardware control (embedded) and utilities (geometry, physics) ensures that a change in one area (like updating tactics) does not negatively impact, for example, network communication.
• Extensibility and Testability: Modules for simulation, sensor fusion, and testing utilities (present in directories like src/software/simulated_tests and src/software/test_util) illustrate an architecture designed for iterative testing and extension.
Relevant technologies, frameworks, and libraries
• Bazel Build System: The presence of various BUILD files and a WORKSPACE indicates Bazel is central.
• C++ and Python: Although the codebase is predominantly in C++ (given the file extensions and naming conventions), there are Python components (for example, in thunderscope and proto message translators) used for scripting or UI tasks.
• Protocol Buffers: The numerous proto definitions and message translation modules underline the role of protobufs in inter-component communication.
• Third-Party Tools: Libraries and external toolchains (like cc_toolchain resources, nanopb, Tracy, g3log) are integral and can be noted as external dependencies.