Skip to content

FORK_SETUP.md

Latest commit

 

History

History
293 lines (208 loc) · 7.3 KB

FORK_SETUP.md

File metadata and controls

293 lines (208 loc) · 7.3 KB
Raw

Fork Setup Guide

Step-by-step instructions to create your own fork of drone-mesh-mapper on GitHub with all the enhanced firmware, base station scripts, and mapper patches integrated.

Step 1 — Fork the Upstream Repo

  1. Go to github.com/colonelpanichacks/drone-mesh-mapper
  2. Click Fork (top right)
  3. Select your account as the destination
  4. Uncheck "Copy the main branch only" (keep all branches)
  5. Click Create Fork

You now have github.com/YOUR_USERNAME/drone-mesh-mapper

Step 2 — Clone Your Fork Locally

git clone https://github.com/YOUR_USERNAME/drone-mesh-mapper.git
cd drone-mesh-mapper

Set the upstream remote so you can pull future updates from colonelpanichacks:

git remote add upstream https://github.com/colonelpanichacks/drone-mesh-mapper.git
git fetch upstream

Step 3 — Create a Feature Branch

git checkout -b enhanced-v2.1.0

Step 4 — Copy the Enhanced Files

From this package, copy these directories into your fork:

# From wherever you extracted this package
PACKAGE=/path/to/drone-mesh-mapper-fork

# Firmware (new directory — doesn't exist in upstream)
cp -r $PACKAGE/firmware ./

# Base station scripts (new directory)
cp -r $PACKAGE/base-station ./

# Patches for mesh-mapper.py
cp -r $PACKAGE/patches ./

# Meshtastic configuration guide (new directory)
cp -r $PACKAGE/meshtastic-config ./

# Documentation
cp -r $PACKAGE/docs ./

# Updated gitignore (merge with existing)
cat $PACKAGE/.gitignore >> .gitignore
sort -u .gitignore -o .gitignore

# Changelog
cp $PACKAGE/CHANGELOG.md ./

# Updated README (replaces upstream README)
# NOTE: You may want to keep the upstream README and add a section instead.
# Option A: Replace entirely
cp $PACKAGE/README.md ./README.md

# Option B: Keep upstream README, add fork notes at top (manual edit)

Step 5 — Apply Patches to mesh-mapper.py

The upstream mesh-mapper.py is in the repo root. Apply the patches in order:

# P0: Critical bug fixes (thread safety, duplicate defs, headless fix)
python3 patches/patch_mesh_mapper_p0.py mesh-mapper.py

# R2: v2.1.0 feature additions (detection display, node markers, CSV)
python3 patches/patch_mesh_mapper_r2.py mesh-mapper.py

Each patch creates a .bak backup and validates its work. Review the output to confirm all fixes applied.

Verify the patched file:

python3 -c "compile(open('mesh-mapper.py').read(), 'mesh-mapper.py', 'exec'); print('Syntax OK')"

Step 6 — Commit and Push

git add -A
git commit -m "v2.1.0: Enhanced firmware, base station bridge, mapper patches

New:
- firmware/: XIAO ESP32S3 detection firmware v2.1.0
  - Dual-core WiFi+BLE ODID scanning
  - OUI/SSID drone presence detection
  - GPS support (GY-NEO6MV2)
  - Channel hopping, FreeRTOS thread safety
- base-station/: RPi mesh bridge (Meshtastic USB -> PTY)
- meshtastic-config/: Setup guide for V3 and Tracker V1.1

Patched mesh-mapper.py:
- Thread safety locks on tracked_pairs and CSV writes
- Removed 9 duplicate function definitions
- Fixed --headless to keep web server running
- Reduced polling overhead (restorePaths 200ms -> 10s)
- v2.1.0 field support (detect, oui_hint, node_id, node_lat/long/alt)
- Detection method display in popups
- OUI manufacturer badge in drone list
- Node position markers on map
- /api/node_positions endpoint
- --observer-lat/--observer-long CLI args
- Enhanced CSV with 6 new columns"

git push origin enhanced-v2.1.0

Step 7 — Create a Pull Request (Optional)

If you want to merge into your main branch:

  1. Go to your fork on GitHub
  2. Click Compare & pull request for enhanced-v2.1.0
  3. Review the changes
  4. Merge into main

Step 8 — Deploy to the RPi

Option A: Clone from your fork (recommended)

ssh analyst@<RPi-IP>
cd /opt
sudo git clone https://github.com/YOUR_USERNAME/drone-mesh-mapper.git mesh-mapper
sudo chown -R analyst:analyst /opt/mesh-mapper

# Install dependencies
sudo pip3 install meshtastic flask flask-socketio pyserial requests urllib3 --break-system-packages

Option B: Copy files to existing install

# Copy base station scripts
scp base-station/mesh_bridge.py analyst@<RPi-IP>:/opt/mesh-mapper/
scp base-station/start_base_station.py analyst@<RPi-IP>:/opt/mesh-mapper/

# Apply patches remotely
scp patches/*.py analyst@<RPi-IP>:/opt/mesh-mapper/
ssh analyst@<RPi-IP> "cd /opt/mesh-mapper && python3 patch_mesh_mapper_p0.py mesh-mapper.py && python3 patch_mesh_mapper_r2.py mesh-mapper.py"

Set up systemd services

ssh analyst@<RPi-IP>

# Bridge service
sudo tee /etc/systemd/system/mesh-bridge.service << 'EOF'
[Unit]
Description=Meshtastic USB Bridge
After=network.target

[Service]
Type=simple
User=analyst
WorkingDirectory=/opt/mesh-mapper
ExecStart=/usr/bin/python3 /opt/mesh-mapper/mesh_bridge.py --port /dev/ttyUSB0
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Mapper service
sudo tee /etc/systemd/system/mesh-mapper.service << 'EOF'
[Unit]
Description=Drone Mesh Mapper
After=mesh-bridge.service
Requires=mesh-bridge.service

[Service]
Type=simple
User=analyst
WorkingDirectory=/opt/mesh-mapper
Environment=DISPLAY=
ExecStartPre=/bin/sleep 5
ExecStart=/usr/bin/python3 /opt/mesh-mapper/mesh-mapper.py --debug
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable mesh-bridge mesh-mapper
sudo systemctl start mesh-bridge mesh-mapper

Step 9 — Flash the Detection Nodes

On your development machine (Mac/Linux with PlatformIO):

cd firmware

# Put XIAO in boot mode: hold BOOT, tap RESET, release BOOT
pio run -e remote_node -t upload

Configure each Heltec — see meshtastic-config/README.md.

Step 10 — Verify Everything

# Check services
sudo systemctl status mesh-bridge mesh-mapper

# Check web UI
curl -s http://localhost:5000/api/diagnostics | python3 -m json.tool

# Check node positions (after detection nodes are deployed)
curl -s http://localhost:5000/api/node_positions | python3 -m json.tool

# Open web UI in browser
# http://<RPi-IP>:5000

Staying in Sync with Upstream

To pull future updates from colonelpanichacks without losing your enhancements:

git fetch upstream
git checkout main
git merge upstream/main

# Re-apply patches if mesh-mapper.py was updated
git checkout enhanced-v2.1.0
git rebase main

# Re-run patches if needed (they're idempotent)
python3 patches/patch_mesh_mapper_p0.py mesh-mapper.py
python3 patches/patch_mesh_mapper_r2.py mesh-mapper.py

Troubleshooting

Patch script says "SKIPPED" for a fix: The upstream file may have changed. Check the specific pattern the patch is looking for (documented in the script output) and apply manually if needed.

Merge conflicts after upstream update: The patches modify specific patterns in mesh-mapper.py. If upstream changes the same lines, you'll need to resolve conflicts manually. The patch scripts are designed to be re-runnable — after resolving conflicts, just re-run both patches.

Firmware won't compile: Make sure you have PlatformIO installed and the XIAO ESP32S3 board support. The firmware requires Arduino framework for ESP32.

pio pkg install -e remote_node
pio run -e remote_node