diff --git a/.pa11yci b/.pa11yci index 18429d9..91b988b 100644 --- a/.pa11yci +++ b/.pa11yci @@ -19,6 +19,7 @@ "http://127.0.0.1:8000/reach_out.html", "http://127.0.0.1:8000/docs/how-to-connect.html", "http://127.0.0.1:8000/docs/what-now.html", + "http://127.0.0.1:8000/docs/faq.html", "http://127.0.0.1:8000/docs/recommended-hardware.html", "http://127.0.0.1:8000/docs/recommended-settings.html", "http://127.0.0.1:8000/docs/suggested_channels.html", diff --git a/docs/docs/faq.md b/docs/docs/faq.md new file mode 100644 index 0000000..03654b5 --- /dev/null +++ b/docs/docs/faq.md @@ -0,0 +1,249 @@ +--- +hide: + - navigation +title: FAQ & Troubleshooting +description: Every common snag in one place. Not receiving messages, receive-works-but-can't-send, Bluetooth pairing, the 403 "Forbidden" map error, claiming your node, flashing / boot loops / bricking, and DM "No Channel" / impersonation warnings. +--- + +# FAQ & Troubleshooting + +Everything that commonly goes wrong, in one place. Already set up and stuck? Jump to your problem: + +- [I'm not receiving every message, or no messages at all](#not-receiving) +- [I can receive, but I can't send](#cant-send) (no acks / "Max Transmission Reached") +- [I don't see my own messages (or replies) in the app or in #messages](#own-messages) +- [Bluetooth won't pair or keeps dropping](#bluetooth) +- [My computer won't detect the node over USB](#usb-not-detected) +- [My node is in the wrong place on the map, or has no location](#wrong-location) +- [The map / view says "Forbidden" or 403](#forbidden-403) +- [Claiming a node fails / "This interaction failed"](#claim-node) +- [Flashing problems: boot loops, blank screen, bricking](#flashing-gotchas) +- [DM says "No Channel" or shows an impersonation warning](#dm-no-channel) + +New here and not set up yet? Start with the [How to Connect](how-to-connect.md) guide; it walks you from an unboxed radio to your first acknowledged message. + +--- + +## I'm not receiving every message, or no messages at all { #not-receiving } + +Missing some messages, or not seeing any traffic come in? Work through this in order. + +**1. Recheck every setting first.** The most common cause is a single wrong setting. Go back through the [How to Connect](how-to-connect.md) guide and confirm **all** of them match the Arizona values exactly, nothing more, nothing less: + +- **Region**, **Preset**, and especially the **Frequency Slot** (the [#1 missed setting](how-to-connect.md#step-4-join-the-discord-for-arizona-settings); leaving it on `0`/auto puts you on the wrong frequency). +- Your **primary channel name + key**, copied exactly. A [renamed primary channel](how-to-connect.md#step-4-join-the-discord-for-arizona-settings) drops you off the mesh. + +If you're not receiving a **single** message, it's almost always one of the above. Fix it and test again. + +**2. Settings confirmed but still missing traffic? Move and get higher.** If your settings are definitely right and you still can't reliably receive (or can't transmit), it's a physical/RF problem, not a configuration one. Try different locations and antenna placement: + +- **Get outside and get high.** Height beats almost everything. A window, balcony, second floor, or rooftop will pull in far more than an interior room. Even a 30-second outdoor test tells you whether your building is the problem. +- **Try a better antenna.** Most handhelds ship with a weak stock antenna. A good whip is the cheapest range upgrade you can make. See the [Antenna Guide](recommended-hardware.md#antenna-guide). +- **Try at a busier time of day.** The mesh ebbs and flows. If nobody's transmitting when you test, you'll hear nothing. + +**3. Still struggling? Consider a more capable radio.** If you've confirmed settings, moved around, tried different placement and an upgraded antenna, and reception is still poor, your hardware may be the limit. A higher-power radio or a rooftop relay node anchors coverage and pulls weak signals in. See [Recommended Hardware](recommended-hardware.md) for a more powerful radio and rooftop options. + +!!! tip "Missing only *some* messages is normal to a degree" + Meshtastic is a best-effort radio network, not the internet. Distant or low-power nodes won't always reach you, and busy-channel collisions can drop the occasional packet. If you're getting *most* traffic, your setup is working; the steps above help you catch more of it. + +If you can receive fine but your own messages never get acknowledged, that's a transmit problem with its own fix-list below. + +--- + +## I can receive, but I can't send { #cant-send } + +This is by far the most common issue people bring to the community: "I see everyone else's messages, but mine never get acknowledged," or "I keep getting **Max Transmission Reached**." + +!!! success "If you receive ANY messages, your settings are already correct" + Receiving other people's traffic proves your **region, preset, frequency slot, and primary channel** are all set right; the radio is decoding the mesh. So this is **not** a settings problem. It's an **asymmetric RF link**: you can hear a strong, high-up node, but your lower-power signal can't make the trip back. The fix is physical, not in the app. + +If you have *never* received a single message, that's a different problem; it's almost always a wrong **Frequency Slot** or a renamed primary channel. Recheck [How to Connect → Step 4](how-to-connect.md#step-4-join-the-discord-for-arizona-settings). + +### What "Max Transmission Reached" / no acks actually means + +When you send on the primary channel, your node waits to hear the message relayed back (an implicit acknowledgement). If it never hears the relay after several attempts, it reports **Max Transmission Reached** or shows no acknowledgement. It means your packet isn't reaching a node that can repeat it: your *transmit* path is weak, even though your *receive* path is fine. Big rooftop nodes transmit at several watts from high up; a handheld indoors might be a fraction of a watt behind a wall. + +### Fix it, in order of impact + +1. **Get outside.** Walls, roofs, stucco with metal lath, and Low-E windows all crush a 915 MHz signal. Step **completely outside** and send `test` again. Even a 30-second outdoor test tells you whether your building is the problem. +2. **Get high (height is might).** Elevation beats almost everything else. Move to a **second floor, balcony, or rooftop**. For a fixed home node, put the antenna in the **attic or on the roof**, not on a desk. A basic antenna up high will out-perform an expensive antenna down low, every time. +3. **Upgrade the antenna.** Most handhelds ship with a weak stock antenna (often ~69% efficient). A good whip is the single cheapest range upgrade you can make. Handheld: the [Muziworks 17cm whip (~$12)](https://muzi.works/products/whip-antenna-17cm) is the community favorite. See the full [Antenna Guide](recommended-hardware.md#antenna-guide) for rooftop options. +4. **Add a rooftop relay node.** If you live in a dead spot, the real fix is a permanent node up high that relays for you. A [Station G2 or a solar rooftop node](recommended-hardware.md#rooftop-base-station-nodes) on your roof anchors coverage for your whole area, and it relays *your* handheld back into the mesh. This is the #1 long-term fix. +5. **Check power, then time of day.** Solar/battery nodes often transmit at very low power (**0.05W-0.5W**). If you've maxed out placement and antenna, a [higher-power node (1W+)](recommended-hardware.md#rooftop-base-station-nodes) may be the answer. The mesh also ebbs and flows; if nobody's on when you test, you'll hear nothing. Try again at a busier time. + +!!! danger "Never transmit with the antenna disconnected" + Sending without an antenna can fry the radio. Always attach the antenna before powering on or transmitting. + +Still stuck? Bring it to **#i-need-help** on Discord with your hardware, antenna, and where you tested from. + +[:fontawesome-brands-discord: Ask in #i-need-help](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } + +--- + +## I don't see my own messages (or replies) in the app or in #messages { #own-messages } + +A very common new-user worry: "I can see everyone else's traffic and lots of nodes, but I don't see my own `test` message land, or I don't see anyone's replies under it." There are a few different things going on here, and most of them are normal. + +**Where messages actually show up:** + +- **In the Meshtastic app:** your sent message appears in the channel thread with a small status icon. A **checkmark / "Acknowledged"** means a node heard you and relayed it back. **Emoji tapbacks** (number reactions) under your message come from auto-responders and tell you how many hops away each node was. Replies people type appear as new messages in the same channel, not always directly "under" yours. +- **In Discord `#messages`:** this channel mirrors traffic that reaches the community MQTT server. **Your message only appears there if your node (or a node that heard you) is uplinking to MQTT.** If MQTT is off on your node and no nearby node relays you to MQTT, you can be fully on the mesh and still not see yourself in `#messages`. That is expected, not a fault. + +**Work through it:** + +1. **Look for the acknowledgement in the app first, not in Discord.** A checkmark / "Acknowledged" on your message is the real proof you were heard. `#messages` is a convenience mirror, not the source of truth. +2. **If you want to see yourself in `#messages`, turn on MQTT.** Enable **"OK to MQTT"** and channel **Uplink**; see [Recommended Settings → MQTT](recommended-settings.md#mqtt). Give it a few minutes. +3. **"I see nodes but no replies" usually means you are heard but your own transmit is weak.** If your messages never get a checkmark, that is the classic receive-works/can't-send problem; work the [I can receive, but I can't send](#cant-send) fix-list (get outside, get high, better antenna). +4. **Missing *some* messages is normal.** Meshtastic is best-effort radio, not the internet. Distant or busy-channel packets drop sometimes. Getting most traffic means your setup is working. + +--- + +## Bluetooth won't pair or keeps dropping { #bluetooth } + +Can't get your phone to connect to the node over Bluetooth, or the connection keeps freezing or dropping? This is one of the most common snags people bring to **#i-need-help**, and it's almost always one of these. + +**Pairing won't complete / freezes on "Connecting":** + +1. **Use the right pairing code.** If your node asks for a PIN, the default is usually `123456`, or it's shown on the device's screen, or printed in the device docs. Type it exactly. +2. **Forget the device and retry.** In your phone's **Bluetooth settings** (not just the Meshtastic app), forget/remove the node, then pair again from inside the Meshtastic app with **+** → select your device. +3. **Toggle Bluetooth off and on** on the phone, and **power-cycle the node** (off, wait 5 seconds, on). +4. **Make sure only one phone is connected.** A node holds one Bluetooth connection at a time. If another phone or tablet is already paired to it, your phone will get stuck connecting. +5. **Grant location/Bluetooth permissions** to the Meshtastic app. Android in particular won't scan for the node without the right permissions enabled. + +**It pairs but the connection is flaky or keeps dropping:** + +- **Distance and obstructions matter.** Bluetooth is short-range. A rooftop or far-room node will drop often. Stay close while configuring, then let it run. +- **Stuck after a firmware update or weird state?** A node that connected fine before and suddenly won't is often fixed by a **reboot**, and failing that, **re-flashing the same firmware version** (back up your keys first; see [Flashing problems](#flashing-gotchas)). +- **Configure over USB serial as a fallback.** If Bluetooth is completely uncooperative, you can connect the node by USB cable and use the [Meshtastic Web Client](https://client.meshtastic.org) (in Chrome or Edge) or the CLI to change settings, then sort out Bluetooth afterward. + +Still stuck? Bring it to **#i-need-help** with your device model and firmware version. + +[:fontawesome-brands-discord: Ask in #i-need-help](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } + +--- + +## My computer won't detect the node over USB { #usb-not-detected } + +Trying to flash or configure over USB (Web Flasher, [Web Client](https://client.meshtastic.org), or CLI) and your computer never sees the device? It's almost always the cable, the browser, or a driver, not a dead node. + +1. **Use a real data cable, not a charge-only cable.** Many USB cables (especially ones that came with a battery pack) carry power but no data. Swap to a known-good cable and try a different USB port. This is the single most common cause. +2. **Use Chrome or Edge.** Web Serial (what the Flasher and Web Client use) only works in **Chromium-based browsers**. Firefox and Safari won't connect to the serial port. On a phone, use the app instead; mobile browsers can't do Web Serial. +3. **Wake the device / put it in bootloader mode.** If the port still doesn't appear, hold the **BOOT/USR button while plugging in USB** (ESP32 boards like Heltec, Station G2, T-Deck) so it enters download mode. nRF52 boards (RAK, T-Echo) usually appear as a **USB drive** in bootloader mode. See [Flashing problems](#flashing-gotchas) for the per-chip details. +4. **Windows: install the USB-serial driver.** If Windows shows an unknown device, install the **CP210x** or **CH340** USB-to-UART driver (the chip varies by board; the device docs say which). After installing, unplug and replug. +5. **macOS:** modern macOS includes the driver, but you may need to **approve the device** under System Settings → Privacy & Security if it's blocked the first time. +6. **Still nothing?** Try another computer to rule out the cable/port, then bring it to **#i-need-help** with your board model and OS. + +--- + +## My node is in the wrong place on the map, or has no location { #wrong-location } + +Showing up in the middle of the desert, at 0,0, or not on the map at all? This is a position-data issue, not a connection problem. + +- **Rooftop and indoor nodes often never get a GPS fix.** Walls and roofs block GPS just like they block your signal, so a stationary node may report no location or a stale one. +- **The fix is to set a Fixed Position.** In the app, enable **Fixed Position** and enter your coordinates manually so your node always reports the right spot. Full context and the recommended position intervals are on [Recommended Settings → Broadcast Intervals](recommended-settings.md#broadcast-intervals). +- **Grab your coordinates** from any maps app (long-press your location → copy the latitude/longitude) and paste them in. +- **Wrong spot from earlier testing?** If you moved the node or set coordinates while testing, update Fixed Position to the real location and **save/send the config**; the map updates after your next position broadcast. +- **Don't want to publish your exact home location?** You can set Fixed Position to a nearby intersection rather than your doorstep, or leave position broadcast off entirely; you'll still be on the mesh, just without a precise pin. + +--- + +## The map / view says "Forbidden" or 403 { #forbidden-403 } + +Visiting [view.azmsh.net](https://view.azmsh.net) and getting **Forbidden / 403**? You almost certainly opened it **before** opting in on Discord, and your browser cached the denial. + +**Fix, in order:** + +1. In Discord, go to the **#getting-started** channel and **react with the :pie: pie emoji** to grant yourself the access role. Do this *first*. +2. Now open the map in an **incognito/private window**, or clear your cookies and cache for `azmsh.net` so the browser drops the old "denied" state. +3. Still blocked after a few minutes? Ask in Discord; an admin can confirm your role. + +!!! tip "React first, then visit" + The order matters. If you visit before reacting, the site remembers the rejection until you clear the cache or use a fresh incognito window. + +[:fontawesome-brands-discord: Get the access role on Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } + +--- + +## Claiming a node fails / "This interaction failed" { #claim-node } + +The claim button in Discord sometimes times out, especially if your node hasn't been seen yet. + +**Two requirements before a claim will work:** + +1. **Your node must have hit MQTT at least once.** It has to actually appear in the **node-discovery** list before it can be claimed. Turn on MQTT (see [Recommended Settings → MQTT](recommended-settings.md#mqtt)) and give it a few minutes. +2. Use the slash command instead of the button if the button keeps failing: + + ``` + /node action:claim node_identifier: + ``` + + Your node identifier can be the **decimal** node number or the **`!hex`** form (e.g. `!a1b2c3d4`). You can find it in the Meshtastic app under your node's details, or in the node-discovery list. + +If you still get **"This interaction failed,"** wait a minute and run the slash command again. It's usually a transient timeout, not a permanent error. + +The full post-setup walkthrough (claim, opt in, read the map) lives on [What Now?](what-now.md). + +--- + +## Flashing problems: boot loops, blank screen, bricking { #flashing-gotchas } + +Most "bricked" nodes aren't actually dead. They're just stuck after a flash, or were flashed with an option that doesn't suit the hardware. Here's how to avoid the common traps and recover a node that won't boot. + +### Before you flash + +Use the official [**Meshtastic Web Flasher**](https://flasher.meshtastic.org) in **Google Chrome** (other browsers frequently fail to connect to the serial port). + +!!! warning "Leave “Install Meshtastic UI” UNCHECKED (the #1 flashing mistake)" + The web flasher may offer an **"Install Meshtastic UI"** option. **Meshtastic UI (MUI)** is a separate on-device interface designed for **color touchscreen** hardware (LilyGO T-Deck, SenseCAP Indicator, and similar). It is **not** built for the small OLED screens on common boards like the **Heltec V3 and V4**, which can boot-loop or show a **blank/black screen** if you flash MUI onto them. Unless you have a supported touchscreen device and specifically want the on-device UI, leave that checkbox **unchecked**; you can always use the phone app for the interface. (Note: this is different from **InkHUD**, the on-device UI for e-paper displays like the T-Echo. Neither belongs on a small-OLED Heltec.) + +!!! danger "Never power on or transmit without an antenna" + The radio's power amplifier can be permanently damaged if it transmits with no antenna attached. Screw the antenna on **before** powering the device or sending anything. + +!!! tip "Back up your keys first" + Flashing can wipe your settings, including your node's identity keys. Export/back up your configuration from the Meshtastic app before updating, so you don't reappear as a brand-new node. + +### My screen is blank or it's boot-looping after a flash + +1. Re-open the [Web Flasher](https://flasher.meshtastic.org) in Chrome. +2. Re-flash the **same firmware version**, but this time make sure **"Install Meshtastic UI" is UNCHECKED**. +3. Let it complete and reboot. The screen issue is almost always that UI option on Heltec V3/V4. + +### My node is completely dead / the flasher can't see it + +The device probably needs to be put into **DFU (bootloader) mode** so the flasher can talk to it. + +- **How to enter DFU varies by device.** It usually means **holding a button (often BOOT/USR) while plugging in USB or pressing reset**. Check your specific device's documentation for the exact button combo. +- nRF52 devices (RAK, T-Echo, etc.) typically expose a **USB drive** when in bootloader mode. You can drag a firmware file onto it, or use the Web Flasher. +- ESP32 devices (Heltec, Station G2, T-Deck) enter download mode via the **BOOT button**; the Web Flasher will then detect the serial port. + +Once the device is in DFU/bootloader mode, the Web Flasher should detect it. Re-flash current firmware (UI option unchecked) and it should come back to life. + +--- + +## DM says "No Channel" or shows an impersonation warning { #dm-no-channel } + +Both come down to key handshakes between two nodes. + +### "No Channel" when sending a direct message + +A direct message uses a **per-node encrypted handshake**. "No Channel" means your node and the other node haven't exchanged a good key yet. + +**Fix:** + +1. On **both** devices, **forget / remove** the other node. +2. Bring the nodes back into range and let them re-exchange node info. +3. Wait for the **green lock** icon to appear next to the node. That means the key handshake succeeded and DMs will work. + +### "Possible impersonation" / key warning + +This warning means a node is presenting **low-entropy or duplicate keys**, usually from very old firmware that generated weak keys. + +**Fix:** on the affected node, **regenerate its keys** (flash current firmware and let it create fresh keys, or use the app's key-regeneration option). Then re-exchange node info so both sides record the new, unique key. + +--- + +## Still need help? + +The community is friendly and fast. Start a thread in **#i-need-help** with your device, firmware version, and what you've already tried. + +[:fontawesome-brands-discord: Join the Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } diff --git a/docs/docs/what-now.md b/docs/docs/what-now.md index 2ed65de..6541b77 100644 --- a/docs/docs/what-now.md +++ b/docs/docs/what-now.md @@ -52,9 +52,7 @@ Make sure every setting on the [Recommended Settings](/docs/recommended-settings ### Still receiving or transmitting unreliably? -A lot of solar and battery-powered nodes transmit at very low wattage: **0.05W to 0.5W**. If you've tried every location, gotten your node as high as possible, and confirmed your settings, it might be time to look at the **1W and higher** options on our [Recommended Hardware](/docs/recommended-hardware.html) page. - -A better antenna is often the **single biggest** improvement you can make before upgrading the radio itself. +Work through [FAQ & Troubleshooting → I can receive, but I can't send](faq.md#cant-send). It covers placement, antennas, low-wattage solar nodes, and when it's time to upgrade the radio. --- diff --git a/mkdocs.yml b/mkdocs.yml index 062efde..32d65b8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,6 +34,7 @@ nav: - Home: index.md - How to Connect: docs/how-to-connect.md - What Now?: docs/what-now.md + - FAQ & Troubleshooting: docs/faq.md - Recommended Hardware: docs/recommended-hardware.md - Recommended Settings: docs/recommended-settings.md - Suggested Channels: docs/suggested_channels.md