update-firmware-documentation-readme

README.md

@@ -1,57 +1,47 @@
-# Firmware 
-This repo contains the source code for the CU Boulder Robotics Teams' microcontroller firmware. It runs on a PJRC Teensy 4.1 and interfaces with any device running `hive`.
+# CU Robotics Firmware
 
-## Documentation
-You can find up-to-date documentation at [cu-robotics.github.io/firmware](cu-robotics.github.io/firmware/), compiled on merges to `main`.
+Firmware for CU Robotics robots built around the PJRC Teensy 4.1. The code implements the real-time control loop, sensor interfaces, and communications layers that tie into the Hive control stack and Waggle telemetry. This document focuses on the commands and workflow you should follow before sending a change for review.
 
-You can find our documentation guidelines at [docs/README](docs/README.md), and how to access your documentation before being merged to main.
+## Before You Start
+- Linux or macOS host with `bash`, `git`, `make`, and `python3`.
+- USB access to a Teensy 4.1 and permissions to use `tycmd` (the upload utility).
+- Optional: [Doxygen](https://www.doxygen.nl/index.html) and [Graphviz](https://graphviz.org/) if you plan to rebuild docs locally.
 
-## Installation
-To begin, clone the repository:
+## One-Time Setup
 ```bash
 git clone git@github.com:CU-Robotics/firmware.git
+cd firmware
+git config --local core.hooksPath .githooks  # enables the branch-protection hook
+make install                                 # installs TyTools/tycmd and the Arm GNU toolchain
 ```
 
-Then, install dependencies:
-
-`githooks` provide branch protection locally. Set the .githook/ directory with:
-```bash
-git config --local core.hooksPath .githooks
-```
-
-Install the required tools
-```bash
-make install
-```
-
-## Usage
-
-Now, navigate to the main directory, and run:
-
-```bash
-make
-```
+Need Arduino CLI support? Run `./tools/install_arduino.sh` (idempotent, installs the same compiler toolchain).
+
+## Daily Workflow
+- `make` — builds the firmware with `-Werror` and writes artifacts to `build/` plus top-level `.elf`, `.hex`, and `.map` files.
+- `make upload` — flashes the connected Teensy via `tycmd` (press the physical button if the bootloader does not auto-enter).
+- `make monitor` — tails serial output using `tools/monitor.sh`.
+- `make gdb` — launches `arm-none-eabi-gdb` after preparing the correct device path.
+- `make help` — lists all supported targets.
+- `make cdb` — regenerates `compile_commands.json` via Bear for IDE/clangd support.
+- `make clean`, `make clean_src`, `make clean_libs`, `make clean_teensy4` — remove build artifacts selectively.
+- `python tools/tcm_blame.py build/firmware.map 20` — inspect ITCM/DTCM usage when chasing memory pressure.
+
+## Directory Layout
+- `src/` — firmware sources grouped by concern (`comms`, `controls`, `sensors`, `filters`, `utils`, `main.cpp`).
+- `libraries/` — vendored dependencies (treat as read-only unless you are updating a library).
+- `teensy4/` — PJRC board files and linker scripts.
+- `tools/` — install scripts, flashing/monitor utilities, GDB helpers, Waggle interceptor.
+- `docs/` — Doxygen configuration and documentation guidelines.
 
-This will build the current firmware. To upload, run:
-
-```bash
-make upload
-```
-
-There are a few other nice helper functions within the makefile. This will list them:
-
-```bash
-make help
-```
-
-
-## Contributing
-`main` is the production branch, which is required to be in an always working state.
-- Only authorized members can merge to `main`. All merges must go through a review and pull request. Direct pushes to `main` branches are strictly forbidden.
-- To contribute, create a new branch with a descriptive name for your change. Create a pull request when done, and provide a short explanation for the change.
-- Pull Requests (PRs) should be as small as possible, dedicated to a specific purpose. A feature does not have to be complete for a pull request to be made, but what *is* added must be functional and tested. Multiple small PRs is better than one large PR.
-    - Smaller PRs are significantly faster to review and test, so expect a slower review process for massive PRs.
-- All software is required to pass [documentation](docs/README.md), build, and unit tests, and have all warnings resolved, before being merged into the `main` branch.
-
-## Licensing
-This repository uses the MIT License, which covers the code and tools written for our robot firmware. See separate copyright/licensing information for the external libraries used in the repo (in the libaries/ and teensy4/ directories).
+## Documentation
+- Run `doxygen Doxyfile` to regenerate HTML docs (output in `docs/html/index.html`).
+- Follow the standards in `docs/README.md` when adding docblocks; `doxygen_warnings.txt` lists any missing coverage.
+- The main site publishes from `main` at <https://cu-robotics.github.io/firmware/>.
+
+## Contribution Checklist
+- Format touched C/C++ files with `clang-format -i`.
+- Run `make` (and `make upload` if the change affects hardware behaviour) before requesting review.
+- Capture serial logs or bench notes when relevant and attach them to the PR.
+- Keep documentation changes factual and scoped to what you validated.
+- Coordinate structural or hardware-impacting changes with the firmware leads before merging.