Organize LoRaPaws32 into multiple repositories

[gdellis]

Context

LoRaPaws32 is a personal ESP32 pet tracker project. It currently lives in a single monorepo but contains distinct components. Motivation is organizational (cleaner separation), not performance or community-driven.

Current remote: git@github.com:gdellis/LoRaPaws32.git

Current structure:

• firmware/ - ESP-IDF C++ (ESP32-S3/C6)
• hardware/ - KiCad PCB designs
• base_station/ - Python Flask web app
• docs/ - Markdown documentation
• .github/workflows/ - CI/CD

Key coupling points:

1. Firmware's board_config.h defines GPIO pins that must match hardware PCB layout
2. LoRa packet format must be shared between firmware (lora/sx1262.cpp) and base station (packet_parser.py)

---

Decision: Split into Separate Repos

Rationale:

• Organizational clarity (each component has its own repo)
• Independent versioning (can release firmware v1.2 while hardware is v2.0)
• Cleaner CI (each repo has focused workflows)
• Prepares for future community contributions (one component can be opened without exposing everything)
• Personal projects with separated concerns are easier to maintain

---

Proposed Structure

Repositories (all under gdellis/)

Repo	Description	License
lorapaws32-firmware	ESP-IDF C++ firmware	MIT
lorapaws32-hardware	KiCad PCB designs, STEP files	CC BY-NC-SA 4.0
lorapaws32-base-station	Python Flask web app	MIT
lorapaws32	Meta-repo (docs, README, pointers)	CC BY-NC-SA 4.0

License rationale:

• MIT for firmware and base station: Permissive, allows external contributions, widely understood, no reciprocity requirements
• CC BY-NC-SA 4.0 for hardware/docs: Appropriate for design files (non-commercial, share-alike)

---

Open Questions (Resolved)

Question	Decision
Preserve git history?	Yes - use git subtree split to extract each component with full history
Docs location?	Repo - keep docs in lorapaws32 meta-repo (or GitHub Pages later)
CI approach?	Independent per repo - focused workflows are cleaner and run faster
Naming convention?	lorapaws32-* (matches current remote name)

---

Migration Sequence

Step 1: Document Contracts (Before Splitting)

1a. Create hardware/PINOUT.md - Document pin assignments referencing board_config.h as source of truth:

• GPS TX/RX pins
• LoRa SPI pins
• Button GPIO
• LED GPIO
• I2C pins for accelerometer
• Battery voltage ADC pin

1b. Create docs/PROTOCOL.md - Document the LoRa packet binary format:

• Packet structure (header, payload, checksum)
• Field sizes and endianness
• How firmware and base station encode/decode packets
• Link to relevant source files (lora/sx1262.cpp, packet_parser.py)

1c. Update LICENSE files to MIT for code (firmware, base_station) before splitting.

Step 2: Create GitHub Repos

Create these repos on GitHub (empty, no README):

• gdellis/lorapaws32-firmware
• gdellis/lorapaws32-hardware
• gdellis/lorapaws32-base-station
• lorapaws32 (existing - will become meta-repo)

Step 3: Extract Components with History

# Extract firmware
git subtree split --prefix=firmware --branch=firmware-split
git push git@github.com:gdellis/lorapaws32-firmware.git firmware-split:main

# Extract hardware
git subtree split --prefix=hardware --branch=hardware-split
git push git@github.com:gdellis/lorapaws32-hardware.git hardware-split:main

# Extract base_station
git subtree split --prefix=base_station --branch=base-station-split
git push git@github.com:gdellis/lorapaws32-base-station.git base-station-split:main

Step 4: Update Each New Repo

lorapaws32-firmware:

• Add README.md pointing to sibling repos
• Add .github/workflows/ci.yml (current firmware CI)
• Add LICENSE (MIT)

lorapaws32-hardware:

• Add README.md pointing to sibling repos
• Add LICENSE-DESIGNS (CC BY-NC-SA 4.0)

lorapaws32-base-station:

• Add README.md pointing to sibling repos
• Add LICENSE (MIT)
• Add .github/workflows/ for Python lint + test

lorapaws32 (meta-repo):

• Add README.md with overview and links to sibling repos
• Add docs/ with pointers to contracts

---

Synchronization Strategy

Since components evolve together, coordinate releases:

Firmware	Hardware	Base Station	Notes
v1.0.0	v1.0.0	v1.0.0	Initial release
v1.1.0	v1.0.0	v1.1.0	Firmware + base station update, hardware unchanged
v1.2.0	v2.0.0	v1.2.0	Hardware redesign (new pinout), firmware adapts

Semantic versioning per component (not tied to others).

---

Rollback Plan (If Needed)

1. All history is preserved in the new repos - nothing is lost
2. Original repo is untouched until you delete it
3. To revert: update git remote in local clones to point to new repos

---

Deliverables

File	Purpose
hardware/PINOUT.md	Pin assignment reference (hardware contract)
docs/PROTOCOL.md	LoRa packet format (firmware/base station contract)
LICENSE files	MIT for code repos, CC BY-NC-SA for hardware
Per-repo README	Links to sibling repos
Per-repo CI workflows	Independent, focused builds

[gdellis]

Repository reorganization complete.

Completed

• ✅ Split into 4 separate repos with preserved git history
• ✅ Created docs/PROTOCOL.md (LoRa packet format contract)
• ✅ Created docs/hardware/PINOUT.md (pin assignments)
• ✅ Updated LICENSE files (MIT for code, CC BY-NC-SA for hardware)
• ✅ Added README.md to each repo
• ✅ Added AGENTS.md and .agents/ directory to each repo
• ✅ Added CI workflows to firmware and base-station repos
• ✅ Created GitHub Project for cross-repo tracking

Final Repos

Repo	URL
lorapaws32-firmware	https://github.com/gdellis/lorapaws32-firmware
lorapaws32-hardware	https://github.com/gdellis/lorapaws32-hardware
lorapaws32-base-station	https://github.com/gdellis/lorapaws32-base-station
LoRaPaws32 (meta-repo)	https://github.com/gdellis/LoRaPaws32

Backup

Full backup available at