OSUSat Contributor Manual & Engineering Guidelines
Procedures, hardware & firmware design, toolchain requirements, submodules, design reviews, and contribution protocol
Section 1: Orientation & Repository Architecture
What this repository contains
OSUSat is a student-built, open-source Earth-imaging
CubeSat. This monorepo holds every subsystem's
hardware (KiCad)
and firmware (C, CMake) in one place, plus the process documents that
control how changes are made.
Electrical Power System: solar charging, battery management, power distribution & protection, power profile decision making.
On-Board Computer: command & telemetry management, GNC logic, image downlink, experiment processing.
Science & Optics: dual-camera imaging controller & high-speed data capture.
Attitude Control: magnetorquers, orientation sensors, and algorithms.
Radio Comms: UHF transceiver for ground station communication & downlink.
PCB with connectors, power, and signals routed between boards, as well as the keying spec and pinout ICDs.
.github/ # Issue + PR templates, CI workflow adcs/ eps/ obc/ payload/ comms/ v1/firmware/ # CMake, CUnit host-side tests, HAL hardware mocks v1/hardware/ # KiCad schematic (.kicad_sch) & layout (.kicad_pcb) documentation/ # Subsystem info doc, trade studies, design reviews backplane/ # Shared connector standard, keying scheme shared/kicad/footprints/ # OSUSAT_* .pretty footprint libraries, 3D models, design rules documentation/ design_guidelines/ # Rules: schematic/layout standards, HAL policy, event-driven pattern checklists/ # Review checklists: schematic, layout, firmware, bring-up templates/ # ICD, ATPs icd/ # Contains ICDs atp/ # Contains ATPs process/ # Documents for controlling work throughout its lifecycle
README.md for
mission context and system architecture diagram
before doing any work.
Section 2: Toolchain Setup & Build Verification
Set up the repo on your local machine
Clone with submodules
The repo pulls in
osusat/core
and
osusat/messaging
as submodules.
$ git clone --recurse-submodules git@github.com:OSUSat/cubesat.git # if you already cloned without submodules, you can bring them in $ git submodule update --init --recursive
Install the firmware toolchain
Needed for any
*/v1/firmware
work:
gcc-arm-none-eabi,
cmake,
make,
g++,
plus
doxygen
and Python 3 +
sphinx
for docs generation.
Build and test one subsystem
$ cd eps/v1/firmware $ cmake -B build_hitl -S . -DTARGET_ARCH=HOST -DBUILD_HITL=ON $ cmake --build build_hitl $ cd build_hitl && ctest --output-on-failure
Open hardware in KiCad
Every board's
fp-lib-table
points at
shared/kicad/footprints/OSUSAT_*.pretty
via a relative
${KIPRJMOD}/../../...
path. You must open the
.kicad_pro
from inside its own folder so that path
resolves. Don't drop new part footprints
into a subsystem specific folder,
instead adding them to the shared
.pretty
library so every subsystem can reuse
them.
Section 3: Issue Tracking & Flatsat GitHub Project
Find something to work on
The program uses GitHub Issues for tracking work throughout its full lifecycle. Work must be encapsulated by an issue before it starts. Status is tracked on the OSUSat CubeSat FlatSat project board.
Picking something up
Cards in the Ready tab are cleared to start and unclaimed. Once you pick something, assign yourself and comment your intent before starting.
Labels
Issues are also labeled by type:
design-review,
bug,
enhancement,
documentation,
good first issue,
help wanted. You
can filter by them from the label picker on the
Issues tab. If you're new to the project, look for
issues labeled
good first issue.
These issues are suitable for members with low
experience or those just getting involved.
Section 4: The Lifecycle of Work
The life of a change
Every hardware or firmware change must follow the same process from review to release.
Open a Design Review issue before doing work
Use the Design Review Request issue template. It forces you to name the subsystem, the requirement it satisfies, description of the work, open questions, and more such as part-tradeoffs up front. Additionally, as you work, ensure that you create sub-issues to encapsulate sub-tasks so the work becomes easier to reason about.
Get it cleared to proceed
After opening a design review issue, request a reviewer to look over your proposed changes before proceeding. Larger issues may require one or more meetings to sort out concerns, interactions with other subsystems, or mechanical constraints. After an issue is cleared to proceed by a reviewer, work can begin.
Do the work, following the design guidelines
Hardware: Schematic & Layout Design guidelines and Preliminary Hardware Design Guidelines. Firmware: Event Driven Service Refactors and Keeping the HAL Policy Free. As you work, or before you submit changes for review, use the Self Review Log.
Self-check against the relevant checklists
Before opening a PR: Schematic Review Checklist and/or Layout Review Checklist for hardware, Firmware Service for firmware. Fill them out honestly.
Open the PR, get a peer review, merge
Delete unused checklist sections from the PR template if they aren't applicable. Before a merge, always wait for CI pipelines to finish. Someone other than the author must sign off before merging.
Section 5: Github Procedures & Pull Requests
Using Git & GitHub for Work
The project board
Open the FlatSat project, find your issue
(assignee:you), and drag it or change its
Status field in the sidebar
to one that matches the work's current
status.
Branches and pull requests
Always create a branch for your work. Pushes
to main directly are not allowed and are
enforced automatically. Branch names should
follow the
First-Last/Feature-Name
format.
To create a branch, you can use the Project UI or the Git CLI.
To use the Project UI, first open the issue
panel. From the issue's sidebar
Development section, click
Create a branch. Push your
branch, open the PR, and add
Closes #<issue>
in the description to auto-link and close
the issue on merge.
If you're using the Git CLI, first run
git branch -m
First-Last/Feature-Name. If you need to switch to your branch
later, run
git checkout
First-Last/Feature-Name.
Section 6: Task Hierarchy & Sub-Issues
Bugs, subtasks & staying readable
The main project view is purposefully broad, mainly with only one card per subsystem deliverable, so the board stays quickly readable. More granular issues like bugs and sub-tasks are also encapsulated in issues, but a separate project view is used to view them (the "All Issues" view).
Default View: Only Broad Deliverables
This view removes issues or tasks that have a parent issue, so only deliverables appear. Deliverables show their sub-task progress so you can gague how far along the work is, and you can view their sub-issues by clicking on the issue panel.
"All Issues" View: Deliverables & Sub-Issues
This view shows all issues including sub-issues. Remember to create sub-issues when performing work, as it makes it easier to divide work, read, reason about, and easier to review.
Section 7: Branching, Commit & PR Conventions
Branch, commit, PR conventions
| What | Convention | Example |
|---|---|---|
| Branch name |
First-Last/Feature-In-Title-Case
|
Ethan-Eggert/Backplane-PCB-Design
|
| Commit subject | lowercase, imperative, no period |
stitching vias,
repour
|
| PR title | short sentence, capitalized, describes delta | "Add hardware design files for Backplane PCBs" |
| Merge style |
PRs merge into
main
after review
|
— |
Section 8: Canonical Documentation Framework
The documentation system
Before writing docs, look in documentation/templates/ for an existing template rather than creating a new format.
Subsystem Info doc
One per-subsystem, containing mission context, electrical & mechanical information, functional requirements, references, deliverables, and more. You should start here if onboarding with a new subsystem.
The template can be found here
ICD: Interface Control Document
Used when describing and formalizing an interface between two or more subsystems, or between a subsystem and an external system like the ground. Any time subsystems share connectors, data protocols, power rails, etc., an ICD formally captures how that interface works. Changes to the ICD must also be recorded, so consumers know exactly when and why a change was made.
The Backplane Pinout ICD is a good example, as it defines the shared pinout and connector interface between every subsystem on the satellite.
The template can be found here. The guide for writing an ICD can be found here
Trade study
Employed when considering different parts for a hardware project. Documents which candidates were considered, rationale, and more.
Section 9: Hardware Design Specifications
Hardware-specific notes
KiCad Hardware Templates
When creating new hardware designs, you can create the KiCad project using the daughterboard template available in the repo, which is already set up with the board outline, connectors, design rules, and schematic organization that you need to get started. The README contains information about setting up the KiCad template.
Design Guidelines
Design guidelines must be followed when making hardware changes. Preliminary hardware design guidelines can be found here, and schematic & layout guidelines can be found here
Shared footprint libraries
KiCad libraries are shared across every board design. They are found in shared/kicad/footprints/. Add new footprints, symbols, and models to the shared libraries, not the local ones.
Section 10: Firmware & Hal Design Guidelines
Firmware-specific notes
Section 11: Technical Support & Contacts
Getting unstuck
-
Scope or requirement questions
— check the subsystem
documentation/subsystem_info.mddocument. - Architecture questions — ask in Open questions / risks on your Design Review issue.
-
Reviewer assignment — tag
@OSUSat/osusat-reviewers. - Getting Help — create a forum post in the #help channel in Discord