How cu-robotics/firmware works
Project Type and Purpose
• This is an embedded‐firmware project targeting a PJRC Teensy 4.1 microcontroller.
• It implements layered robotics firmware that:
• Reads data from a variety of sensors (IMU, encoders, LiDAR, CAN devices, etc.)
• Applies filters and state estimation
• Runs control loops
• Exposes telemetry and command interfaces over Ethernet and HID to an external host running the hive software
• External Arduino-style libraries and a custom Teensy HAL provide low-level hardware support.
Directory and Component Analysis
• Top-level build & tooling
• Makefile & githooks: local build, upload, linting, documentation
• .github/workflows: CI for PR checks and docs deploy
• docs/: Doxygen and markdown guidelines
• tools/: helper scripts (installer, monitor, a Rust “waggle-interceptor” tool)
• External Libraries (libraries/ and teensy4/)
• Arduino-style hardware abstraction (“teensy4/”)
• Standard sensor, bus, networking, filesystem libraries (FastLED, QNEthernet with lwIP, SdFat, etc.)
• Application Source (src/)
• src/sensors: sensor drivers & SensorManager (I²C, SPI, CAN, TOF, encoders…)
• src/filters: basic signal filters (lowpass, PID)
• src/controls: state estimation, control loops, ControllerManager
• src/comms: packet definitions, HID & Ethernet comms layers, SD logging
• src/utils: timing, vector math, profiling, watchdog
• Hardware Abstraction Layer (HAL): teensy4/ sources
• External Libraries: grouped library blocks (I2C, SPI, Ethernet, FileSystem, CAN)
• Sensor Layer: SensorManager + individual drivers
• Filtering & Estimation Layer
• Control Layer: ControllerManager, state machine
• Communication Layer:
• EthernetComms (QNEthernet/lwIP)
• HIDComms
• SDManager for on-board logging
• External Host (hive): running on PC, communicates via Ethernet/HID
• Build & Docs: Makefile, CI pipelines, Doxygen (ancillary)
• HAL → Sensor drivers → SensorManager → filters → estimator → controller → comms
• Controller outputs → actuator interfaces (PWM, GPIO via HAL)
• Comms layers ↔ External Host (hive)
• SDManager logs data from SensorManager and Controller
• Build tools & CI: interacts with code base but outside of runtime flow
c. Architectural Patterns & Principles
• Layered architecture: clear separation of HAL, drivers, application logic, and communication
• Manager/Adapter pattern for sensors, filters, and controllers
• Data flow pipeline: sensor → filter → estimate → control → output/telemetry
• Modularity: each subsystem in its own directory, all using consistent C++ interfaces
• Use of external open-source libraries for reusable functionality (networking, filesystems)
d. Key Technologies & Frameworks
• C++17 (Arduino-style) on ARM Cortex-M7 (Teensy 4.1)
• QNEthernet + lwIP for TCP/UDP/Ethernet
• USB HID for alternative comms
• SdFat for SD-card logging
• Doxygen for API docs, GitHub Actions for CI/CD