From 7fbfc0149a8580c2be98e0911e83c65b494516f3 Mon Sep 17 00:00:00 2001 From: jeremymcgee73 Date: Sat, 24 Jan 2026 11:00:17 -0700 Subject: [PATCH] Add troubleshooting --- README.md | 3 ++- docs/adsb-to-cot.md | 2 +- docs/firmware.md | 4 +++- docs/index.md | 2 ++ docs/initial-setup.md | 2 +- docs/range-testing.md | 2 +- docs/troubleshooting.md | 47 +++++++++++++++++++++++++++++++++++++++++ 7 files changed, 57 insertions(+), 5 deletions(-) create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index 7fd3c09..e43afca 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,11 @@ - 🚀 Initial setup: **[initial-setup.html](https://openmanet.github.io/docs/initial-setup.html)** - 🧰 Hardware: **[hardware](https://openmanet.github.io/docs/hardware)** - 🕸️ Networking: **[networking](https://openmanet.github.io/docs/networking)** + - 🛠️ Troubleshooting: **[troubleshooting](https://openmanet.github.io/docs/troubleshooting)** - 📡 Range testing: **[range-testing.html](https://openmanet.github.io/docs/range-testing.html)** - ✈️ ADS-B to CoT: **[adsb-to-cot](https://openmanet.github.io/docs/adsb-to-cot)** ## Downloads -- 📦 Releases (images): **[github.com/OpenMANET/openwrt/releases](https://github.com/OpenMANET/openwrt/releases)** +- 📦 Releases (images): **[github.com/OpenMANET/firmware/releases](https://github.com/OpenMANET/firmware/releases)** Contributions and issues are welcome! diff --git a/docs/adsb-to-cot.md b/docs/adsb-to-cot.md index b832f0c..0a18757 100644 --- a/docs/adsb-to-cot.md +++ b/docs/adsb-to-cot.md @@ -1,7 +1,7 @@ --- layout: default title: ADS-B to CoT -nav_order: 7 +nav_order: 8 permalink: /adsb-to-cot description: ADS-B to Cursor on Target gateway using ADSBCOT on OpenMANET images. --- diff --git a/docs/firmware.md b/docs/firmware.md index 08bd44e..9a7d10c 100644 --- a/docs/firmware.md +++ b/docs/firmware.md @@ -8,7 +8,7 @@ description: Firmware download guidance, naming conventions, and notable changes # Firmware & Releases -Firmware images are published on GitHub: [OpenMANET OpenWrt Releases](https://github.com/OpenMANET/openwrt/releases) +Firmware images are published on GitHub: [OpenMANET Firmware Releases](https://github.com/OpenMANET/firmware/releases) This page covers how to choose the correct image and summarizes notable changes in the `1.6.x` line. @@ -56,6 +56,8 @@ If you want a truly fresh install, we recommend fully formatting the SD card wit - https://www.sdcard.org/downloads/formatter/ +In SD Card Formatter, use **Overwrite format**. + --- ## Notable Changes (1.6.x) diff --git a/docs/index.md b/docs/index.md index e4350ee..151bdbb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,6 +32,8 @@ This design is deliberately opinionated to reduce the amount of networking knowl See [Firmware & Releases](./firmware) for download guidance, naming conventions, and `1.6.x` release notes. +If you run into issues, start with [Troubleshooting](./troubleshooting) (including the recommended “wipe and re-flash” recovery path). + ## Advantages vs. the Seeed image - Different BCF radio file increases TX power (≈21 dBm → **27 dBm**) diff --git a/docs/initial-setup.md b/docs/initial-setup.md index 5608d00..47f831d 100644 --- a/docs/initial-setup.md +++ b/docs/initial-setup.md @@ -14,7 +14,7 @@ This page walks you through downloading, flashing, and configuring the OpenMANET ## Setup Steps 1. **Download the latest OpenMANET image** - Go to the Releases section: [OpenMANET OpenWrt Releases](https://github.com/OpenMANET/openwrt/releases) and download the image. + Go to the Releases section: [OpenMANET Firmware Releases](https://github.com/OpenMANET/firmware/releases) and download the image. 2. **Flash the image to an SD card** Use the official Raspberry Pi guide for instructions on flashing the image: diff --git a/docs/range-testing.md b/docs/range-testing.md index 21fa5e7..5f7e2a8 100644 --- a/docs/range-testing.md +++ b/docs/range-testing.md @@ -1,7 +1,7 @@ --- layout: default title: Range Testing -nav_order: 6 +nav_order: 7 description: Field test results of Wi-Fi HaLow (802.11ah) mesh networking with Raspberry Pi HATs at Pulpit Rock, Colorado Springs. --- diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..a28c8c8 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,47 @@ +--- +layout: default +title: Troubleshooting +nav_order: 6 +permalink: /troubleshooting +description: Quick checks for mesh connectivity, hostname access via mDNS, and a recommended recovery path if setup gets messy. +--- + +# Troubleshooting + +This page covers quick checks for common issues and the recommended “reset” workflow. + +--- + +## Don’t Hand-Tune Settings (Reset Instead) + +If something feels off after setup (odd addressing, multicast issues, services not coming up, etc.), the fastest path is usually to **start over clean** rather than changing settings outside the wizard. + +OpenWrt stores configuration in its writable overlay. If you want a truly fresh install, fully wipe the SD card and re-flash: + +1. Format the SD card with **SD Card Formatter**: https://www.sdcard.org/downloads/formatter/ +2. In SD Card Formatter, select **Overwrite format**. +3. Re-flash the latest OpenMANET image and rerun the wizard. + +--- + +## Connect By Hostname (mDNS / `.local`) + +OpenMANET uses mDNS for easy discovery inside the mesh network (on clients that support mDNS). The simplest way to connect to different nodes is by hostname: + +- If your hostname is `meshgate01`, use `meshgate01.local` +- Web UI: `https://meshgate01.local` +- SSH: `ssh root@meshgate01.local` + +To browse mDNS names from a node: +- `ubus call umdns browse` +- `avahi-browse -a` + +Note: `nslookup` typically will not resolve mDNS names. + +--- + +## Quick Mesh Sanity Checks + +- If your end user device gets a `10.41.x.x` IP, it is on the mesh. +- After running the wizard, the node will reboot after address/DHCP reservation; reconnect or renew DHCP on your end user device if needed. +