Skip to content

Commit fc1f3f8

Browse files
CopilotRuthie-FRC
Copilot
and
Ruthie-FRC
committed
Add complete MkDocs documentation site for Luma P1
Co-authored-by: Ruthie-FRC <238046543+Ruthie-FRC@users.noreply.github.com> Agent-Logs-Url: https://github.com/FRC5892/Luma-Docs/sessions/7dfc6810-9118-4340-9a15-fea109094f1e
1 parent 4ae9259 commit fc1f3f8

14 files changed

Lines changed: 912 additions & 0 deletions

File tree

‎.github/workflows/deploy.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: Deploy MkDocs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
# Allow only one concurrent deployment
15+
concurrency:
16+
group: "pages"
17+
cancel-in-progress: false
18+
19+
jobs:
20+
build:
21+
name: Build MkDocs site
22+
runs-on: ubuntu-latest
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0 # full history needed for git-revision-date plugin if added later
28+
29+
- name: Set up Python
30+
uses: actions/setup-python@v5
31+
with:
32+
python-version: "3.12"
33+
cache: pip
34+
35+
- name: Install dependencies
36+
run: pip install -r requirements.txt
37+
38+
- name: Build MkDocs site
39+
run: mkdocs build --strict
40+
41+
- name: Upload Pages artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: site/
45+
46+
deploy:
47+
name: Deploy to GitHub Pages
48+
needs: build
49+
runs-on: ubuntu-latest
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
steps:
54+
- name: Deploy to GitHub Pages
55+
id: deployment
56+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# MkDocs build output
2+
site/
3+
4+
# Python
5+
__pycache__/
6+
*.py[cod]
7+
*.egg-info/
8+
.venv/
9+
venv/
10+
env/
11+
12+
# pre-commit
13+
.pre-commit-cache/
14+
15+
# OS
16+
.DS_Store
17+
Thumbs.db

‎.markdownlint.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Markdownlint configuration
2+
default: true
3+
4+
# Allow inline HTML (used for admonitions / custom elements)
5+
MD033:
6+
allowed_elements:
7+
- details
8+
- summary
9+
- br
10+
- kbd
11+
12+
# Allow duplicate headings in different sections
13+
MD024:
14+
siblings_only: true
15+
16+
# Allow trailing punctuation in headings (e.g. "What is Luma?")
17+
MD026: false
18+
19+
# Line length — docs text can be long
20+
MD013:
21+
line_length: 120
22+
code_blocks: false
23+
tables: false
24+
headings: false

‎.pre-commit-config.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v4.6.0
4+
hooks:
5+
- id: trailing-whitespace
6+
- id: end-of-file-fixer
7+
- id: check-yaml
8+
- id: check-merge-conflict
9+
- id: mixed-line-ending
10+
11+
- repo: https://github.com/DavidAnson/markdownlint-cli2
12+
rev: v0.13.0
13+
hooks:
14+
- id: markdownlint-cli2
15+
args: ["--config", ".markdownlint.yml"]
16+
17+
- repo: https://github.com/adrienverge/yamllint
18+
rev: v1.35.1
19+
hooks:
20+
- id: yamllint
21+
args: ["-d", "{extends: relaxed, rules: {line-length: {max: 120}}}"]

‎CNAME‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
frc-lumadocs.com

‎docs/contributing.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Contributing
2+
3+
Thank you for your interest in improving the Luma P1 community docs!
4+
5+
!!! info "About These Docs"
6+
This documentation is an **unofficial, community-maintained** resource by
7+
[FRC Team 5892](https://github.com/FRC5892). It is **not affiliated with Luma**.
8+
For the official docs, visit [docs.luma.vision/p1](https://docs.luma.vision/p1/).
9+
10+
---
11+
12+
## How to Contribute
13+
14+
Contributions of all kinds are welcome:
15+
16+
- **Fixing typos or factual errors** — Always appreciated!
17+
- **Improving existing guides** — Clearer steps, better tips, more screenshots
18+
- **Adding new guides** — Troubleshooting, advanced configuration, WPILib integration
19+
- **Updating outdated content** — As PhotonVision and Luma firmware evolve
20+
21+
---
22+
23+
## Getting Started
24+
25+
### 1. Fork and Clone the Repository
26+
27+
```bash
28+
# Fork the repo on GitHub, then:
29+
git clone https://github.com/<your-username>/Luma-Docs.git
30+
cd Luma-Docs
31+
```
32+
33+
### 2. Install Dependencies
34+
35+
```bash
36+
pip install -r requirements.txt
37+
```
38+
39+
### 3. Run the Docs Locally
40+
41+
```bash
42+
mkdocs serve
43+
```
44+
45+
Open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser. The site hot-reloads
46+
as you edit files.
47+
48+
### 4. Make Your Changes
49+
50+
- All documentation lives in the `docs/` directory as Markdown files.
51+
- Navigation is configured in `mkdocs.yml` under the `nav:` key.
52+
- If you add a new page, add it to the `nav:` section in `mkdocs.yml`.
53+
54+
### 5. Lint Your Markdown
55+
56+
We use [markdownlint](https://github.com/DavidAnson/markdownlint) to keep formatting
57+
consistent. Configuration is in `.markdownlint.yml`.
58+
59+
If you have Node.js installed:
60+
61+
```bash
62+
npx markdownlint-cli "docs/**/*.md"
63+
```
64+
65+
### 6. Build and Verify
66+
67+
Before submitting, make sure the site builds without errors:
68+
69+
```bash
70+
mkdocs build --strict
71+
```
72+
73+
### 7. Open a Pull Request
74+
75+
Push your changes to your fork and open a PR against the `main` branch.
76+
Please include a brief description of what you changed and why.
77+
78+
---
79+
80+
## Style Guide
81+
82+
- Write in **plain, friendly English** — our audience includes new FRC students.
83+
- Use **MkDocs Material admonitions** (`!!! note`, `!!! warning`, `!!! tip`, `!!! danger`)
84+
to call out important information.
85+
- Use **numbered lists** for sequential steps, **bullet lists** for unordered items.
86+
- Code, file names, and commands should use `inline code` or fenced code blocks.
87+
- Keep lines under **120 characters** where reasonable.
88+
- Always include the standard "unofficial docs" info box at the top of guide pages:
89+
90+
```markdown
91+
!!! info "Unofficial Docs"
92+
This is an unofficial community guide. For the official Luma documentation, see
93+
[docs.luma.vision/p1](https://docs.luma.vision/p1/).
94+
```
95+
96+
---
97+
98+
## Pre-commit Hooks *(Optional)*
99+
100+
If you'd like automatic linting before each commit, install the pre-commit hooks:
101+
102+
```bash
103+
pip install pre-commit
104+
pre-commit install
105+
```
106+
107+
---
108+
109+
## Code of Conduct
110+
111+
Please be respectful and constructive. This is a community resource — we're all here to
112+
help FRC teams succeed.
113+
114+
---
115+
116+
## Questions?
117+
118+
Open an issue on [GitHub](https://github.com/FRC5892/Luma-Docs/issues) or reach out
119+
to FRC Team 5892.

‎docs/getting-started/prerequisites.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Prerequisites
2+
3+
Before you can flash and use your Luma P1, you need to gather a few tools and downloads.
4+
5+
!!! info "Unofficial Docs"
6+
This is an unofficial community guide. For the official Luma documentation, see
7+
[docs.luma.vision/p1](https://docs.luma.vision/p1/).
8+
9+
---
10+
11+
## Hardware
12+
13+
You will need the following physical items:
14+
15+
- [x] **Luma P1 camera** (one or more)
16+
- [x] **USB-C cable** — used to connect the Luma to your programming laptop for flashing
17+
- [x] **Ethernet cables** (×3 recommended) — for networking during calibration
18+
- [x] **Programming laptop** — Windows, macOS, or Linux
19+
- [x] **Vision calibration board** — for the calibration step
20+
- [x] **Surface to prop the Luma on** — during calibration
21+
- [x] **Tape or labels** — to mark which cameras have been flashed
22+
23+
---
24+
25+
## Software Downloads
26+
27+
Download and install the following on your **programming computer** before you start:
28+
29+
### 1. RPIBoot
30+
31+
RPIBoot is required to put the Luma P1 (Raspberry Pi CM5) into USB mass-storage mode so
32+
you can flash it.
33+
34+
!!! note "Download Link"
35+
See the [official Luma docs](https://docs.luma.vision/p1/) for the current download link.
36+
37+
=== "Windows"
38+
Install the RPIBoot executable. After installation, search for **"cm5"** in the Windows
39+
Start Menu — you should see an entry called **rpiboot-CM4-CM5 - Mass Storage Gadget**.
40+
41+
=== "macOS / Linux"
42+
Follow the instructions in the official Raspberry Pi documentation for building RPIBoot
43+
from source.
44+
45+
### 2. Raspberry Pi Imager
46+
47+
The Raspberry Pi Imager is used to write the PhotonVision image to the Luma P1.
48+
49+
!!! warning "Use Raspberry Pi Imager — not Balena Etcher"
50+
The flashing process requires Raspberry Pi Imager specifically. **Do not use Balena Etcher
51+
or other imaging tools**, as they do not support the required options.
52+
53+
!!! note "Download Link"
54+
Download from [raspberrypi.com/software](https://www.raspberrypi.com/software/).
55+
56+
### 3. Latest PhotonVision Image for Luma P1
57+
58+
This is the firmware image that will be written to the camera.
59+
60+
!!! note "Download Link"
61+
See the [official Luma docs](https://docs.luma.vision/p1/) for the current release download.
62+
63+
### 4. FRC Game Tools *(for calibration)*
64+
65+
FRC Game Tools includes the Driver Station and other utilities needed during setup.
66+
67+
!!! note "Download Link"
68+
See the [official Luma docs](https://docs.luma.vision/p1/) for the current download link.
69+
70+
---
71+
72+
## Summary Checklist
73+
74+
Before proceeding to the [Flashing Guide](../guides/flashing.md), confirm you have everything:
75+
76+
- [x] Luma P1 camera(s)
77+
- [x] USB-C cable
78+
- [x] RPIBoot installed
79+
- [x] Raspberry Pi Imager installed
80+
- [x] Latest PhotonVision image for Luma P1 downloaded
81+
- [x] Programming laptop ready
82+
83+
Once all boxes are checked, head over to **[Flashing your Luma P1](../guides/flashing.md)**.

‎docs/getting-started/what-is-luma.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# What is the Luma P1?
2+
3+
!!! info "Unofficial Docs"
4+
This is an unofficial community guide. For the official Luma documentation, see
5+
[docs.luma.vision/p1](https://docs.luma.vision/p1/).
6+
7+
## Overview
8+
9+
The **Luma P1** is an affordable FRC-focused vision co-processor and camera system released
10+
for the **2026 FRC Reefscape season**. It is designed to give FRC teams a capable, budget-friendly
11+
vision solution that works out of the box.
12+
13+
Under the hood, the Luma P1 is built around a **Raspberry Pi Compute Module 5 (CM5)** and
14+
runs [PhotonVision](https://photonvision.org/) as its vision processing software.
15+
16+
## How It Compares
17+
18+
If you have used a **Limelight** before, the Luma P1 will feel familiar — it's conceptually
19+
similar to running a Limelight with PhotonVision. The key differences are:
20+
21+
| Feature | Luma P1 | Typical Limelight |
22+
|---------|---------|-------------------|
23+
| Vision Software | PhotonVision | Limelight OS (or PhotonVision) |
24+
| Co-processor | Raspberry Pi CM5 | Varies |
25+
| PoE Support | ✅ Yes | ✅ Varies by model |
26+
| Price | Affordable | Varies |
27+
| Open-source software | ✅ PhotonVision | Partial |
28+
29+
!!! tip
30+
Teams already using PhotonVision on a coprocessor will find the transition to Luma P1
31+
very straightforward — the interface and WPILib integration are identical.
32+
33+
## Key Features
34+
35+
- **PoE (Power over Ethernet)** — Run a single Ethernet cable for both power and data.
36+
This simplifies wiring significantly on a competition robot.
37+
- **PhotonVision** — Industry-standard FRC vision software with AprilTag detection,
38+
object tracking, and WPILib integration.
39+
- **Raspberry Pi CM5** — Powerful, well-supported hardware with an active community.
40+
- **Affordable** — Built with FRC team budgets in mind.
41+
- **FRC 2026 ready** — Designed and tested for Reefscape.
42+
43+
## How It Works (High Level)
44+
45+
```
46+
Robot Code (RoboRIO)
47+
│
48+
│ NetworkTables / PhotonLib
49+
▼
50+
Luma P1 Camera
51+
┌─────────────────────────────┐
52+
│ Camera Sensor │
53+
│ ↓ │
54+
│ Raspberry Pi CM5 │
55+
│ (running PhotonVision) │
56+
│ ↓ │
57+
│ Ethernet (PoE) │
58+
└─────────────────────────────┘
59+
│
60+
▼
61+
Robot Network Switch / Radio
62+
```
63+
64+
The Luma P1 connects to your robot network over Ethernet. PhotonVision processes the camera
65+
feed and publishes pose estimates and target data over NetworkTables, which your robot code
66+
reads using [PhotonLib](https://docs.photonvision.org/en/latest/docs/programming/photonlib/index.html).
67+
68+
## Next Steps
69+
70+
Ready to get started? Check out the [Prerequisites](prerequisites.md) page to see what
71+
you need before flashing your Luma P1.

0 commit comments

Comments
 (0)