diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index e2c2d1e..2f981fa 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -27,58 +27,6 @@ jobs: - name: Build site run: mkdocs build --strict - accessibility: - name: Accessibility Audit (Soft Check) - runs-on: ubuntu-latest - - steps: - - name: Checkout repo - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.x' - - - name: Set up Node.js - uses: actions/setup-node@v4 - with: - node-version: '20' - - - name: Install site dependencies - run: | - pip install mkdocs mkdocs-material mkdocs-minify-plugin mkdocs-git-revision-date-localized-plugin mkdocs-glightbox - - - name: Install pa11y-ci - run: npm install -g pa11y-ci - - - name: Build site - run: mkdocs build --strict - - - name: Start local site server - run: python -m http.server 8000 --directory site >/tmp/pa11y-server.log 2>&1 & - - - name: Wait for local site server - run: | - for i in 1 2 3 4 5; do - curl -fsS http://127.0.0.1:8000/ >/dev/null && exit 0 - sleep 2 - done - exit 1 - - - name: Run pa11y-ci - continue-on-error: true - run: pa11y-ci | tee pa11y-results.txt - - - name: Upload pa11y logs - if: always() - uses: actions/upload-artifact@v4 - with: - name: pa11y-results - path: | - pa11y-results.txt - /tmp/pa11y-server.log - deploy: name: Deploy to GitHub Pages needs: build diff --git a/docs/assets/css/extra.css b/docs/assets/css/extra.css new file mode 100644 index 0000000..8a02849 --- /dev/null +++ b/docs/assets/css/extra.css @@ -0,0 +1,119 @@ +/* =========================================================================== + Discord-gated settings boxes + Blurred dummy values + "Join The Discord" overlay. Labels stay sharp. + Built on Material for MkDocs theme variables so it inherits light/dark mode, + fonts, and the deep-orange / amber palette automatically. + =========================================================================== */ + +.azmsh-locked { + position: relative; + margin: 1.2rem 0; + padding: 1rem 1.1rem; + border: .075rem solid var(--md-default-fg-color--lightest); + border-radius: .3rem; + background: var(--md-code-bg-color); + overflow: hidden; +} + +/* The settings list itself */ +.azmsh-locked .azmsh-settings { + margin: 0; + font-size: .82rem; + line-height: 1.9; +} + +.azmsh-locked .azmsh-group-title { + font-weight: 700; + font-size: .8rem; + margin: .2rem 0 .55rem; + color: var(--md-default-fg-color); +} + +.azmsh-locked .azmsh-group-title:not(:first-child) { + margin-top: 1rem; +} + +.azmsh-locked .azmsh-row { + display: flex; + flex-wrap: wrap; + align-items: baseline; + gap: .4rem .55rem; + padding: .12rem 0; +} + +/* Sharp, readable label */ +.azmsh-locked .azmsh-label { + font-weight: 600; + color: var(--md-default-fg-color); + white-space: nowrap; +} + +/* Blurred dummy value (monospace, looks like a real setting underneath) */ +.azmsh-locked .azmsh-value { + font-family: var(--md-code-font-family, monospace); + color: var(--md-default-fg-color); + background: var(--md-default-fg-color--lightest); + border-radius: .15rem; + padding: 0 .35rem; + filter: blur(5px); + -webkit-filter: blur(5px); + user-select: none; + -webkit-user-select: none; + pointer-events: none; +} + +/* A value that is intentionally NOT a secret (e.g. "OK to MQTT: On") */ +.azmsh-locked .azmsh-value--clear { + filter: none; + -webkit-filter: none; + background: transparent; + padding: 0; + font-weight: 600; +} + +/* Dim layer that sits over the blurred settings to reinforce "locked" */ +.azmsh-locked .azmsh-overlay { + position: absolute; + inset: 0; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: .55rem; + text-align: center; + padding: 1rem; + background: color-mix(in srgb, var(--md-default-bg-color) 62%, transparent); + -webkit-backdrop-filter: blur(1.5px); + backdrop-filter: blur(1.5px); +} + +.azmsh-locked .azmsh-overlay-text { + font-weight: 700; + font-size: .78rem; + letter-spacing: .02em; + color: var(--md-default-fg-color); + text-shadow: 0 1px 2px var(--md-default-bg-color); +} + +/* Reuse the theme's primary button so the CTA looks native */ +.azmsh-locked .azmsh-overlay .md-button { + margin: 0; + box-shadow: 0 .15rem .6rem rgba(0, 0, 0, .25); +} + +/* Mobile: keep label + value stacked-readable, shrink padding a touch */ +@media screen and (max-width: 44.9375em) { + .azmsh-locked { + padding: .85rem .8rem; + } + .azmsh-locked .azmsh-settings { + font-size: .78rem; + } + .azmsh-locked .azmsh-overlay-text { + font-size: .72rem; + } + .azmsh-locked .azmsh-overlay .md-button { + font-size: .7rem; + padding: .35em .9em; + } +} diff --git a/docs/docs/additional-settings.md b/docs/docs/additional-settings.md new file mode 100644 index 0000000..2476e37 --- /dev/null +++ b/docs/docs/additional-settings.md @@ -0,0 +1,346 @@ +--- +hide: + - navigation +title: Additional Settings +description: The deeper Meshtastic settings reference for Arizona operators, laid out in the same section order as the iOS Meshtastic app (Radio Configuration, Device Configuration, Module Configuration), with Android name differences noted where they help. +--- + +# Additional Settings + +This is the deeper settings reference for your node: node roles, broadcast intervals, Neighbor Info, MQTT, and more. It's laid out in the **same section order as the iOS Meshtastic app**, grouped under **Radio Configuration**, **Device Configuration**, and **Module Configuration**, so you can read down this page with the app open and follow along section by section. + +!!! tip "New here? Start with the Start Here guide first" + If you just unboxed a radio, **don't start on this page.** Go to **[Start Here](start-here.md)** first; it walks you in order from flashing firmware to sending your first acknowledged message, and it already includes everything you need to get on the Arizona mesh. Come back here once you're connected and want to fine-tune your node. + + [:material-rocket-launch: Go to Start Here](start-here.md){ .md-button .md-button--primary } + +!!! info "The Arizona-specific values aren't repeated here" + Your **region, preset, frequency slot, primary channel name + key, and MQTT broker** are shared in [Discord](https://discord.gg/HrKtyuFEQk) so the whole mesh stays coordinated. Get those from Discord (see [Start Here → Step 3](start-here.md#step-3-get-the-arizona-radio-settings-from-discord)). Everything on this page is general guidance that's the same for any operator. + +!!! note "Names on this page follow the iOS app; Android differences are noted" + This page uses the **iOS / iPadOS / macOS** section names and setting names, in the order the iOS app lists them. Where Android uses a different word for the same setting, we note it in parentheses, like **Modem Presets (Android: Presets)**. The path to reach the settings also differs slightly: + + - **iOS / iPadOS / macOS:** **Settings → Radio Configuration / Device Configuration / Module Configuration →** the section name (e.g. **LoRa**). + - **Android:** **Settings** tab → the section name (e.g. **LoRa**). Modules appear further down the same list. + + After changing anything on iOS, remember to **Save / send the configuration** back to your node. + +--- + +# Radio Configuration + +In the iOS app, **Radio Configuration** holds **LoRa, Channels, and Security**, in that order. These are the radio-level settings that put you on the Arizona mesh. + +## LoRa { #lora } + +The **LoRa** section is the most important radio section: it's where **Region, Modem Preset, and Frequency Slot** live. Getting these exactly right is what puts you on the Arizona mesh. + +!!! note "Name differences in this section" + - **Region** is called **Region** on both apps (iOS may show it as **Set LoRa Region**). + - The preset is **Modem Presets (iOS) / Presets (Android)**. + - **Frequency Slot** and **Frequency Override** are named the same on both. + - The hop setting is **Hop Limit (iOS) / Number of Hops (Android)**. + +The Arizona **Region, Modem Preset, and Frequency Slot** values are shared in Discord. Set them exactly as listed; they are covered in [Start Here → Step 3](start-here.md#step-3-get-the-arizona-radio-settings-from-discord). + +
+
+

Arizona LoRa settings

+
Region: US
+
Modem Preset / Preset: ExamplePreset_AZ
+
Frequency Slot: 00
+
+
+ 🔒 Arizona radio settings are shared in Discord + Join The Discord +
+
+ +!!! warning "The Frequency Slot is the #1 missed setting" + Lots of people set the preset correctly but leave the **Frequency Slot** at `0`/auto, so they land on the wrong frequency and can't hear anyone. Set it to the exact slot listed in Discord. + + **iOS gotcha:** the Slot field is text entry. **Double-tap the existing value** to select it, then type the correct slot. Leave **Frequency Override** blank or `0`; entering a value there *locks* the Slot field. "Frequency Override" and "Frequency Slot" are different fields. + +!!! info "Hop Limit (iOS) / Number of Hops (Android)" + Leave this at the default (**3**) unless the community advises otherwise. Cranking up the hop count floods the mesh and rarely helps; more hops is not more range. + +The **"OK to MQTT"** toggle also lives in the LoRa section. See the [MQTT](#mqtt) section below for how it works with the MQTT module. + +--- + +## Channels { #channels } + +The **Channels** section is where you set your **primary** channel and add **secondary** channels. + +- Your **primary channel** (index 0) must match the Arizona settings exactly. Setting it up is covered in [Start Here → Step 4](start-here.md#step-4-set-up-your-primary-channel). +- **Do not rename your primary channel.** Renaming it to "AZ Mesh", "azmsh", or anything custom puts you on a *different* channel and you fall off the mesh. +- Community channels (azmsh, Weather, Traffic, Trivia) are added here as **secondary** channels. The names, keys, and per-platform steps live on the [Suggested Channels](suggested_channels.md) page. + +The fields are labeled **Channel Name** and **PSK** (the key) on both apps. + +--- + +## Security { #security } + +The **Security** section holds your node's **identity keys**. These are what let other nodes verify it's really you and what make direct messages private. + +!!! tip "Back up your keys before re-flashing" + Flashing can wipe your settings, including your node's identity keys. Export/back up your configuration from the Meshtastic app first, so you don't reappear as a brand-new node and trigger impersonation warnings for others. + +- If you ever see a **"possible impersonation"** warning about another node, or your own node is flagged, it usually means weak/duplicate keys from very old firmware. The fix is to regenerate keys on the affected node. See [FAQ → DM "No Channel" / impersonation](faq.md#dm-no-channel). + +--- + +# Device Configuration + +In the iOS app, **Device Configuration** holds **User, Bluetooth, Device, Display, Network, Position, and Power**, in that order. These set how your node identifies itself, how it behaves, and how it connects. + +## User { #user } + +The **User** section is where you set how your node identifies itself on the mesh. + +- **Long Name:** your node's full name (e.g. "Will's Rooftop"). Shows up in everyone's node list. +- **Short Name:** up to 4 characters, shown on small screens and maps. Make it recognizable. +- **Licensed Operator (iOS) / Licensed amateur radio (Android):** **leave this OFF** unless you're a licensed ham operator running under Part 97. Turning it on disables encryption and changes how your node transmits. The Arizona community mesh uses the standard encrypted ISM-band setup, so almost everyone leaves this off. + +--- + +## Bluetooth { #bluetooth } + +The **Bluetooth** section controls how your phone pairs with the node. + +- **Pairing Mode:** most devices default to a fixed PIN or a random PIN shown on screen. If you have no screen, the PIN is usually `123456` or printed in the device docs. +- If pairing fails or keeps dropping, see [FAQ → Bluetooth won't pair or keeps dropping](faq.md#bluetooth). + +--- + +## Device { #device } + +The **Device** section holds your node's **role** and rebroadcast behavior. Picking the right role is the single most important choice here, because it affects the whole mesh, not just you. + +The field is labeled **Device Role** on both apps. + +### Node Roles + +Choosing the right role for your device keeps the network clean and efficient. + +#### Client Mute + +**Use for: anything mobile** (backpacks, vehicles, pocket nodes). + +Client Mute nodes can send and receive messages but do **not** rebroadcast other people's traffic. This is the best choice for devices that move around, since mobile rebroadcasters create unpredictable routing and extra congestion. + +#### Client + +**Use for: stationary home or rooftop nodes.** + +Client is the standard role. Your node will participate in the mesh by rebroadcasting messages, which helps extend coverage for your neighbors. + +!!! tip "When in doubt, client it out" + Not sure which role to pick? Set your device to **Client Mute** and talk to a community member in Discord. You can always change it later. + +#### Router and Router Late + +!!! warning "Understand Router roles before switching" + **Router** and **Router Late** are designed for nodes at **high elevation, permanent fixed locations with good line-of-sight** (hilltops, towers, or mountain repeater sites). They aggressively rebroadcast traffic and are optimized to extend the mesh across long distances. + + Used in the wrong context (a home, an apartment, or a mobile node), these roles can cause increased congestion, routing loops, and degraded performance for everyone on the mesh. Meshtastic's own guidance is to use these roles only where they genuinely improve coverage for the wider network, not just your own reach. + + **Before switching to Router or Router Late, make sure you understand the implications.** If you're unsure whether your location and setup are a good fit, ask the community on Discord. We're happy to help. + + [:fontawesome-brands-discord: Ask the Community on Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } + +### Node Info Broadcast Interval + +Your node periodically broadcasts its name and details so others can see it. This rarely needs to change. + +| Setting | Value | Notes | +|:--------|:------|:------| +| **Node Info Broadcast Interval** | `43200` sec (12 hours) | Your node info rarely changes, so there's no need to broadcast it often. Same value for mobile and stationary nodes. | + +On iOS this setting lives on the Device screen with the broadcast interval expressed in seconds. On Android it is labeled **Node Info Broadcast Interval**. + +--- + +## Display { #display } + +The **Display** section controls the on-device screen (brightness, screen timeout, units, orientation). These are personal-preference settings and don't affect the mesh. + +- Set **Display Units** to your preference (the community generally uses imperial in Arizona). +- A shorter **Screen Timeout** saves battery on handhelds. + +--- + +## Network { #network } + +The **Network** section is for **WiFi and Ethernet**, and only applies to **ESP32-based** nodes (Heltec, Station G2, T-Deck). Bluetooth-only nRF52 nodes (most handhelds and solar nodes) don't have this. + +- Enter your **WiFi SSID and password** here if your rooftop ESP32 node will reach the community MQTT server over your home internet. +- A WiFi connection is what lets an ESP32 node uplink to MQTT **without** proxying through your phone. + +--- + +## Position { #position } + +The **Position** section controls how often your node shares its GPS location and how often it reads its own GPS. Tuning these correctly reduces channel congestion and saves battery. + +!!! note "Name differences in this section" + - **Smart Position** is called the same on both apps (sometimes shown as **Smart Position Enabled**). + - The GPS read interval is **Update Interval (iOS) / GPS Polling Interval (Android)**. + +### Mobile Nodes + +For devices that move around (in your car, backpack, pocket, etc.): + +| Setting | Value | Notes | +|:--------|:------|:------| +| **Smart Position** | **ON** | Automatically sends position updates when you move. | +| Smart Position Min Distance | `100` meters | Only broadcasts after moving at least 100 m. | +| Smart Position Min Interval | `60` seconds | No more than one smart broadcast per minute. | +| **Position Broadcast Interval** | `3600` sec (1 hour) | Fallback interval if GPS is enabled. | +| **Update Interval (iOS) / GPS Polling Interval (Android)** | `300` sec (5 minutes) | How often the device checks its own GPS. | + +### Stationary Nodes + +For devices that stay in one place (rooftop, home base, solar nodes): + +| Setting | Value | Notes | +|:--------|:------|:------| +| **Smart Position** | **OFF** | Your node is not moving, so smart positioning is not needed. | +| **Position Broadcast Interval** | `43200` sec (12 hours) | Only if GPS is enabled. Your position is fixed. | +| **Update Interval (iOS) / GPS Polling Interval (Android)** | `21600` sec (6 hours) | Minimal GPS checks since the node does not move. | + +!!! tip "No GPS? Set a fixed position instead" + Rooftop and indoor nodes often have no GPS fix. Enable **Fixed Position** and set your coordinates manually so your node still shows up in the right place on the map. + +--- + +## Power { #power } + +The **Power** section controls sleep and battery behavior. Most operators can leave this at defaults. + +- Plugged-in rooftop nodes: leave power-saving **off** so the node stays fully awake. +- Battery and solar nodes: power-saving can extend runtime, but it also delays responses. Only enable it once your node is otherwise working, and test afterward. + +--- + +# Module Configuration + +Modules are optional add-ons. In the iOS app they appear under **Module Configuration** (Android lists them further down the **Settings** list). The full iOS list is alphabetical (Ambient Lighting, Canned Messages, Detection Sensor, External Notification, MQTT, Neighbor Info, Range Test, Ringtone, Serial, Store & Forward, TAK Server, Telemetry). Below are the modules Arizona operators use most. + +## MQTT { #mqtt } + +MQTT lets your node upload diagnostic data to a shared server, which helps us monitor network health and see all nodes on the map. It does **not** send your personal messages or private data, only metadata like position, telemetry, and node info. + +!!! danger "MQTT does NOT send your messages (map + diagnostics only)" + A common misconception is that MQTT carries your text messages over the internet. It does **not**. MQTT shares only **map position, telemetry, and node info** for the community map and monitoring tools. Your text messages always travel over the LoRa radio mesh, encrypted, and are never uplinked. + +!!! info "The three toggles that make MQTT work" + - **"OK to MQTT"** (in the **LoRa** section, same name on both apps): **ON**. Lets your node's data be uplinked at all. + - **Channel Uplink** (per channel): **ON**. Sends *that channel's* node/telemetry data to the server. Labeled **Uplink Enabled** on both apps. + - **Connect to MQTT via Proxy (iOS) / Proxy to client enabled (Android):** turn **ON only if the node has no WiFi of its own.** It then relays MQTT through your phone's connection. If the node is on WiFi (most rooftop ESP32 nodes), leave it **OFF**. + +**How to Enable MQTT** + +To enable MQTT uplink, you will need the community broker settings (server address, username, and password). We keep these in Discord. + +[:fontawesome-brands-discord: Join the Discord for MQTT broker settings](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } + +Once you have the broker details: + +1. **LoRa section:** enable **"OK to MQTT"**. This allows your node's data to be uplinked. +2. **MQTT module:** enter the broker settings provided in Discord. The fields are **Server**, **Username**, **Password**, and **Root topic** on both apps. + +
+
+
Server: broker.example.net:1883
+
Username: example_uplink_user
+
Password: example_password
+
Root topic: msh/REGION/EXAMPLE
+
+
+ 🔒 Broker settings are shared in Discord + Join The Discord +
+
+ +3. **Channel settings** (for each channel you want to uplink): + - **Uplink (Uplink Enabled):** **ON**. Sends your node's data to the MQTT server. + - **Downlink (Downlink Enabled):** **OFF**. Prevents MQTT messages from being injected back into the radio mesh. + +!!! warning "Always keep Downlink OFF" + Downlinking from MQTT into the primary channel floods the radio mesh with traffic from the internet. Keep downlink disabled unless you have a specific reason and have discussed it with the community. + +!!! tip "Root topic: use your city" + A frequent question is what to put in **Root topic**. The Arizona convention is `msh/US/AZ/{city}`, where `{city}` is your local area, for example `msh/US/AZ/Phoenix`, `msh/US/AZ/Tucson`, or `msh/US/AZ/Flagstaff`. This groups nodes by region on the map and tools. If you change it, it can take a few minutes for your node to show up under the new topic. The exact broker host, username, and password (the parts that must stay coordinated) are in [Discord](https://discord.gg/HrKtyuFEQk). + +--- + +## Neighbor Info { #neighbor-info } + +Neighbor Info is a module that periodically broadcasts a list of your node's direct neighbors along with the signal quality (SNR) of each link. When enabled across multiple nodes, the community can build a real picture of how the mesh is connected, which helps identify coverage gaps, optimize node placement, and understand how traffic actually flows through the network. + +In the iOS Module Configuration list, **Neighbor Info** appears alphabetically just after MQTT. Neighbor Info packets are small and infrequent, so the channel congestion impact is very low. + +**Recommended Update Interval** + +| Node type | Interval | Seconds | +|:----------|:---------|:--------| +| **Mobile** | 4 hours | `14400` | +| **Stationary** | 11 hours | `39600` | + +4 hours is the minimum the firmware allows. Use the longer interval for stationary nodes since their neighbors rarely change. + +??? note "How to Enable on Android" + Requires Meshtastic app version 2.2.0 or higher. + + 1. Open the Meshtastic app and connect to your node. + 2. Tap the **three-dot menu** (vertical ellipsis) in the top-right corner. + 3. Select **Radio Configuration**. + 4. Scroll down and tap **Neighbor Info**. + 5. Toggle **Enabled** to ON. + 6. Set the **Update Interval** to `14400` (mobile) or `39600` (stationary). + 7. Toggle **Transmit Over LoRa** to ON. This sends the neighbor info over the radio mesh and to MQTT. + 8. Tap **Send** to save the settings to your node. + +??? note "How to Enable on Web Client" + 1. Open the Meshtastic Web UI and connect to your node (usually at `meshtastic.local` or via USB serial). + 2. Click **Config** in the left sidebar. + 3. Click **Module Config**. + 4. Click **Neighbor Info**. + 5. Toggle **Enabled** to ON. + 6. Set the **Update Interval** to `14400` (mobile) or `39600` (stationary). + 7. Toggle **Transmit Over LoRa** to ON. + 8. Click **Save** to apply the settings. + +??? note "How to Enable via CLI" + Requires the Meshtastic Python CLI version 2.2.0 or higher (`pip install meshtastic`). + + ```bash + # Enable the module + meshtastic --set neighbor_info.enabled true + + # Set update interval (seconds) — 14400 = 4 hours, 39600 = 11 hours + meshtastic --set neighbor_info.update_interval 14400 + + # Enable transmit over LoRa (sends over radio AND MQTT) + meshtastic --set neighbor_info.transmit_over_lora true + + # Verify your settings + meshtastic --get neighbor_info + ``` + + Run these commands while connected to your node over USB, Bluetooth, or TCP. + +!!! warning "iOS: Neighbor Info not currently supported" + The iOS Meshtastic app does not currently support enabling the Neighbor Info module. iOS users will need to use the Web client or CLI over a TCP/USB connection to configure this setting on their node. + +--- + +## Where to go next + +- :material-rocket-launch: **Not set up yet?** → [Start Here](start-here.md) +- :material-test-tube: **Confirm the mesh can hear you** → [How To Test](how-to-test.md) +- :material-frequently-asked-questions: **Something's not working** → [FAQ & Troubleshooting](faq.md) +- :material-radio-tower: **Add community channels** → [Suggested Channels](suggested_channels.md) +- :material-radio-handheld: **Need better hardware** → [Recommended Hardware](recommended-hardware.md) diff --git a/docs/docs/cant-transmit.md b/docs/docs/cant-transmit.md new file mode 100644 index 0000000..e91151b --- /dev/null +++ b/docs/docs/cant-transmit.md @@ -0,0 +1,16 @@ +--- +hide: + - navigation +title: Receive Works, Can't Send +description: This guide has moved into FAQ & Troubleshooting. +--- + + + +# "Receive works, can't send" has moved + +We've folded this into the **[FAQ & Troubleshooting](faq.md#cant-send)** page so every common snag lives in one place. + +You should be redirected automatically. If not: + +[:material-help-circle: Go to FAQ → I can receive, but I can't send](faq.md#cant-send){ .md-button .md-button--primary } diff --git a/docs/docs/connect.md b/docs/docs/connect.md deleted file mode 100644 index 7f84296..0000000 --- a/docs/docs/connect.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: How to Connect ---- - -### Join the Community - -Beyond the meshtastic network, we're most active in our [Discord server](https://discord.gg/HrKtyuFEQk). - -### How to Connect - -#### Get a Meshtastic Radio -- **DIY**: Build your own for around $35. Check the [official supported hardware](https://meshtastic.org/docs/hardware/) page for guidance. -- **Ready-to-go**: Consider the [Seeed Studio SenseCAP Card Tracker](https://meshtastic.org/docs/hardware/devices/seeed-studio/sensecap/card-tracker/), an excellent option for quickly starting with Meshtastic, needing minimal setup. -- **Pre-built**: Battery-powered radios with 3D-printed cases are available for $50-$100 on Etsy or eBay. -- **Outdoor Setup**: A pre-built solar-powered node ($100-$200) is ideal if you can mount it high outdoors, or you can construct your own. ( Constructing one yourself could cost as little as $50.) - -#### Set Up the Meshtastic App -- Download the official Meshtastic app for [Android](https://play.google.com/store/apps/details?id=com.geeksville.mesh) or [iOS](https://apps.apple.com/us/app/meshtastic/id1586432531). -- Pair your radio to your smartphone via Bluetooth. -- Open the Meshtastic app and start chatting! - -### Best Practices - -**Recommended Settings** - -- **MQTT**: Disabled or limited use; follow etiquette below - -- **Role**: Client (avoid Router) (Router & Client is actually Client in recent versions.) - -- **Hop Count**: 3 hops recommended - -- **Broadcast Interval**: - - Node Info & Device Metrics: Every 4-6 hours - - Position & Sensor Metrics: Every 1 hour (for mobile nodes; enable Smart Positioning with a minimum interval of 1 minute, minimum distance 100m). For stationary nodes, consider extending this interval to every 12-24 hours. - - -#### MQTT -MQTT is a useful tool for supplementing mesh connectivity but shouldn't be relied upon as a primary mesh component. Our recommended MQTT etiquette is: - -- **Downlinking** from the primary Meshtastic MQTT server is strongly discouraged, especially in the primary channel. -- **Uplinking** to the primary Meshtastic MQTT server is acceptable but not strongly encouraged. -- **Uplinking** to a local MQTT server is helpful for tracking deployed nodes not connected directly to your mesh segment. -- **Downlinking** from a local MQTT server should be avoided in the primary channel; however, it's acceptable for secondary channels. - -#### Device Roles -Previously, Meshtastic did not have intelligent routing, causing nodes in 'client/router' mode to potentially create routing inefficiencies. **With Meshtastic 2.6, intelligent routing for direct messages (DMs) has been introduced**, significantly improving targeted message delivery and network efficiency. However, we still recommend primarily using the 'client' role to simplify network traffic and maintain redundancy. - -- **Client Mode**: Ideal for most stationary nodes, minimizing unnecessary rebroadcasts. (Maybe your roof node.) -- **Client Mute**: Use for on the move nodes that do not contribute directly to message forwarding, reducing network congestion. (Maybe your mobile node.) - -#### Hop Count -Start with a hop count of 3, using only the minimum necessary hops to reach your intended destinations. - -- If consistently routing through a dedicated relay node, a hop count of 4 is reasonable. - -- At network edges or challenging locations, up to 5-7 hops might be necessary, but ensure optimal node placement before increasing hops. - -#### Broadcast Intervals -To minimize channel use and maintain high reliability: - -- **Node Information**: Every 4-6 hours - -- **Position Information**: Every 1 hour if mobile; 12-24 hours if stationary - -- **Telemetry/Sensors**: Device metrics every 4-6 hours; sensor data hourly if mobile, longer intervals if stationary diff --git a/docs/docs/faq.md b/docs/docs/faq.md new file mode 100644 index 0000000..9b6c444 --- /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 [Start Here](start-here.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 [Start Here](start-here.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](start-here.md#step-3-get-the-arizona-radio-settings-from-discord); leaving it on `0`/auto puts you on the wrong frequency). +- Your **primary channel name + key**, copied exactly. A [renamed primary channel](start-here.md#step-4-set-up-your-primary-channel) 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 [Start Here → Step 3](start-here.md#step-3-get-the-arizona-radio-settings-from-discord). + +### 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 [Additional Settings → MQTT](additional-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 [Additional Settings → Position](additional-settings.md#position). +- **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 [Start Here, Step 5](start-here.md#step-5-optional-turn-on-mqtt-for-the-map)) 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 [How To Test](how-to-test.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/flashing-gotchas.md b/docs/docs/flashing-gotchas.md new file mode 100644 index 0000000..549584c --- /dev/null +++ b/docs/docs/flashing-gotchas.md @@ -0,0 +1,16 @@ +--- +hide: + - navigation +title: Flashing & Recovery +description: This guide has moved into FAQ & Troubleshooting. +--- + + + +# Flashing & Recovery has moved + +We've folded flashing and recovery into the **[FAQ & Troubleshooting](faq.md#flashing-gotchas)** page so all troubleshooting lives in one place. + +You should be redirected automatically. If not: + +[:material-usb-flash-drive: Go to FAQ → Flashing problems](faq.md#flashing-gotchas){ .md-button .md-button--primary } diff --git a/docs/docs/host-a-node.md b/docs/docs/host-a-node.md index a3203db..46befd5 100644 --- a/docs/docs/host-a-node.md +++ b/docs/docs/host-a-node.md @@ -9,7 +9,7 @@ title: Host a Node Thinking about letting us put a Meshtastic node on your property? Awesome! Here's everything you need to know, in plain English. No tech jargon required. !!! info "What is Arizona Meshtastic Community?" - We're a volunteer-run group building a **free, open-source mesh network** across the Phoenix metro and greater Arizona. Our network lets people send text messages without cell service, Wi-Fi, or monthly fees. Using small, low-power radios. Learn more at [azmsh.net](https://azmsh.net). + We're a volunteer-run group building a **free, open-source mesh network** across the Phoenix metro and greater Arizona. Our network lets people send text messages without cell service, WiFi, or monthly fees. Using small, low-power radios. Learn more at [azmsh.net](https://azmsh.net). --- @@ -38,8 +38,8 @@ Thinking about letting us put a Meshtastic node on your property? Awesome! Here' !!! tip "Mounting is non-invasive" We use **magnetic mounts, pole clamps, or zip ties**. No drilling into your roof, walls, or structure unless you specifically approve it. The equipment can be removed without leaving any trace. -??? question "Does it use my internet or Wi-Fi?" - **No.** The node communicates entirely over radio frequencies (the 906.875 MHz unlicensed band). It does not connect to your Wi-Fi, use your internet bandwidth, or access any of your home network. +??? question "Does it use my internet or WiFi?" + **No.** The node communicates entirely over radio frequencies (the 900 MHz unlicensed ISM band). It does not connect to your WiFi, use your internet bandwidth, or access any of your home network. There is an optional feature called MQTT that *can* connect to the internet for extended range, but that is never enabled without your knowledge and permission. The default setup is fully radio-only and self-contained. @@ -49,7 +49,7 @@ Thinking about letting us put a Meshtastic node on your property? Awesome! Here' | Device | Transmit Power | |--------|---------------| | Cell phone | Up to 2,000 mW | - | Wi-Fi router | Up to 1,000 mW | + | WiFi router | Up to 1,000 mW | | **Meshtastic node** | **100-4,500 mW** | | Baby monitor | Up to 100 mW | @@ -99,10 +99,10 @@ Thinking about letting us put a Meshtastic node on your property? Awesome! Here' The magic of a mesh network is that each node extends the range. Your node doesn't need to reach the whole city. It just needs to reach the *next* node, and the message hops along from there. -??? question "Will it interfere with my Wi-Fi, TV, or garage door?" - **No.** Meshtastic operates on **906.875 MHz**, which is a completely different frequency from: +??? question "Will it interfere with my WiFi, TV, or garage door?" + **No.** Meshtastic operates on the **900 MHz ISM band**, which is a completely different frequency from: - - Wi-Fi (2.4 GHz / 5 GHz / 6 GHz) + - WiFi (2.4 GHz / 5 GHz / 6 GHz) - Cell phones (700 MHz-2.5 GHz, different bands) - TV (VHF/UHF, different bands) - Bluetooth (2.4 GHz) diff --git a/docs/docs/how-to-connect.md b/docs/docs/how-to-connect.md index f5408a1..54f1783 100644 --- a/docs/docs/how-to-connect.md +++ b/docs/docs/how-to-connect.md @@ -2,87 +2,15 @@ hide: - navigation title: How to Connect +description: This guide has moved into Start Here, the single linear onboarding page. --- -# How to Connect + -Welcome to the Arizona Meshtastic Community! This guide will walk you through getting your first device set up and connected to our local mesh network. +# How to Connect has moved -!!! info "Before you start" - **You will need a Meshtastic radio.** If you don't have one yet, check our [Recommended Hardware](/docs/recommended-hardware.html) page. You can get started for as little as $30. No monthly fees, no subscriptions, no cell service required. Meshtastic runs on unlicensed 915 MHz radio frequencies, so it is completely free and legal to use in the United States. +We've merged "How to Connect" into the **[Start Here](start-here.md)** guide so there's one linear path from an unboxed radio to your first acknowledged message. ---- - -## Step 1: Update Your Firmware - -Before anything else, make sure your device is running the latest Meshtastic firmware. - -1. Open [**Meshtastic Web Flasher**](https://flasher.meshtastic.org) in **Google Chrome** (other browsers may not work). -2. Select your device from the list. -3. Click **Flash** and follow the on-screen instructions. - -!!! tip "DFU Mode" - Some devices need to be put into DFU (Device Firmware Update) mode before flashing. Check your device's documentation for how to enter DFU mode. It usually involves holding a button while powering on. - -!!! warning "Back Up Your Settings First" - Firmware updates can wipe your device settings, including your **private key**. Before updating, go to your Meshtastic app and export/back up your configuration. Your private key is what identifies your node on the network. If you lose it, you will appear as a new node. - ---- - -## Step 2: Download the App - -Install the official Meshtastic app on your phone: - -| Platform | Link | -|:---------|:-----| -| **Android** | [Google Play Store](https://play.google.com/store/apps/details?id=com.geeksville.mesh) | -| **iOS** | [Apple App Store](https://apps.apple.com/us/app/meshtastic/id1586432531) | - ---- - -## Step 3: Pair via Bluetooth - -1. Turn on your Meshtastic device. -2. Open the Meshtastic app on your phone. -3. Tap the **+** button to add a new device. -4. Your device should appear in the list. Tap it to pair. -5. If prompted for a pairing code, the default is usually printed on your device or in its documentation. - -That is it. You should now see your node in the app! - ---- - -## Step 4: Join the Discord for Arizona Settings - -To connect to our local Arizona mesh network, you will need the community-specific **preset** and **frequency settings**. We share these in our Discord server to keep the network coordinated. - -[:fontawesome-brands-discord: Join the Arizona Meshtastic Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } - -Once you are in the server, head to the setup channel and you will find everything you need to get on the Arizona mesh. - ---- - -## Step 5: Start Chatting - -Once your settings are configured: - -1. Open the Meshtastic app. -2. Go to the **Messages** tab. -3. Send a message on the primary channel. Say hello! - -!!! info "Be Patient" - Meshtastic is a long-range, low-bandwidth radio network. Messages can take a few seconds (or longer) to propagate across the mesh. This is normal. - ---- - -## Quick Tips - -- **Keep your firmware updated**. New versions improve performance and compatibility. -- **Export your node configuration** before any firmware update so you do not lose your identity on the mesh. -- **Start with the Client Mute role** if you are not sure what to pick. It is the safest default for mobile devices. -- **Check the [Recommended Settings](/docs/recommended-settings.html) page** for detailed configuration guidance (broadcast intervals, MQTT, and more). -- **Upgrade your antenna**. The single biggest improvement you can make. See the [Recommended Hardware](/docs/recommended-hardware.html) page for our antenna picks. -- **Ask questions in Discord**. The community is friendly and happy to help new members get started. +You should be redirected automatically. If not, head to: -!!! tip "How far does Meshtastic reach?" - Range depends on terrain and antenna height. In flat desert terrain, handheld-to-handheld range is typically 1-3 miles. With a rooftop node and a good antenna, you can reach 10-30+ miles. The mesh network extends range further by relaying messages through other nodes. +[:material-rocket-launch: Go to Start Here](start-here.md){ .md-button .md-button--primary } diff --git a/docs/docs/how-to-test.md b/docs/docs/how-to-test.md new file mode 100644 index 0000000..f4eb2f2 --- /dev/null +++ b/docs/docs/how-to-test.md @@ -0,0 +1,142 @@ +--- +hide: + - navigation +title: How To Test +description: You set up your node and configured your settings. Now how do you check whether anyone can hear you? The test-your-setup playbook for new Arizona Meshtastic operators. +--- + +# How To Test Your Setup + +So you've got your node set up, the app downloaded, all your settings configured. You connected. **Now what? How do you know if it's actually working, if anyone out there can hear you?** + +This page is the moment right after [Start Here](start-here.md). Your radio is on, your settings are dialed in, and you're staring at the screen wondering: *did I do this right?* + +Here's how to find out. + +--- + +## Step 1. Say "test" on the Mesh + +Meshtastic is part art and part science. The art part is trying a lot of things and testing to see what works. Everyone's setup and location is different. + +1. Type `test` in your **primary** channel. Send it. (Send it as many times as you want.) +2. Many Arizona nodes run an auto-responder (such as **MeshMonitor**, a community tool that watches the mesh) that reacts to your message with a **tapback**: an emoji reaction attached to your message, like a thumbs-up on a text. The number in the reaction tells you how far away that node is: + - :one: :two: :three: :four: :five: :six: :seven:. How many hops away that user is from you + - :asterisk:. Direct hit (no hops, they heard you straight) +3. **Got tapbacks? Congrats. You're on the mesh.** Skip to [Step 4](#step-4-claim-your-node-opt-in-for-diagnostics). +4. **No tapbacks?** Don't panic. Keep reading. + +--- + +## Step 2. Not Getting Responses? Move Around. + +If `test` is getting crickets, the most common fixes are physical, not technical. + +1. **Try different locations.** Inside vs outside makes a huge difference. Near a window vs interior wall. Also big. +2. **Get higher.** **Height is might.** Roof, balcony, second floor. Anywhere that gives your antenna line-of-sight to the sky and the surrounding terrain. +3. **Step outside completely.** Even a 30-second outdoor test will tell you whether your indoor location is the problem. +4. **Try at different times of day.** The mesh ebbs and flows. If no one's around when you test, you'll hear nothing. + +Keep doing the above until you see something land. Try every location, see what works best for you. + +!!! tip "Can receive but can't send? That's the most common snag, and it has a full fix-list" + If you can see *other people's* messages but yours never get acknowledged (or you see **Max Transmission Reached**), your settings are fine; it's an RF/placement issue. The complete, ordered fix list lives in the [FAQ → I can receive, but I can't send](faq.md#cant-send). + +--- + +## Step 3. Still Nothing? Check Your Settings. + +The **#1 issue** we see new operators run into is missing a setting. Or turning something on that shouldn't be on. + +Make sure every setting in the [Start Here](start-here.md) guide is configured correctly, and nothing else. + +!!! tip "When in doubt, leave it alone" + If you aren't fully sure what a setting does, don't mess with it. If you want someone to check your settings, start a thread in **#i-need-help** on Discord. We're happy to take a look. + +Still stuck after all of the above? Work through the [FAQ & Troubleshooting](faq.md) page; it covers the "can't send" RF fixes, the 403 map error, node-claim failures, and flashing problems in one place. + +--- + +## Step 4. Claim Your Node + Opt In for Diagnostics + +Now that you're heard on the mesh, plug into the community side. + +**Claim your node.** In Discord, run the `/node` slash command and choose the **claim** action (`/node action:claim node_identifier:`). Discord will autocomplete the options as you type. This helps others know the node is yours, so they can tag you when they have questions, hear you on the air, or want to know if you can hear them. If the claim fails or times out, see [FAQ → Claiming a node fails](faq.md#claim-node). + +**Opt in for diagnostic data.** Click the :pie: reaction in the **#getting-started** channel on Discord. Opting in unlocks: + +- More diagnostic data on your node +- Access to [view.azmsh.net](https://view.azmsh.net). Our community map and MQTT diagnostics tool + +!!! warning "Map says “Forbidden” / 403? React with the pie emoji FIRST" + If you open [view.azmsh.net](https://view.azmsh.net) **before** reacting with the :pie: emoji, your browser caches the denied state and keeps showing **Forbidden**. React first, then open the map in an **incognito window** (or clear your cache/cookies for the site). Full steps: [FAQ → Forbidden / 403](faq.md#forbidden-403). + +[:fontawesome-brands-discord: Join the Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } + +--- + +## Step 5. Check Your Messages and Trace Routes + +Once you've opted in, search for your node on [view.azmsh.net/nodelist](https://view.azmsh.net/nodelist) to see what's actually happening on the air. + +
+ + Screenshot of view.azmsh.net/nodelist with the Traceroute button highlighted in red and a text message ID highlighted in blue. + +
view.azmsh.net/nodelist. Click to enlarge
+
+ +- **Red (Traceroutes):** Click the arrow next to the trace routes and it'll show you the path your trace routes took. And when others trace route you. You can run trace routes by clicking on a node in the node list, scrolling down, and tapping **Trace Route**. You'll get a cool graph of where your trace route went trying to hit that node and get back home. You can also see these in **#traceroutes** on Discord. +- **Blue (Message stats):** Click the number ID for any text message you sent to see the stats for that specific message, including which nodes it hit on the way. You can also see your messages in **#messages**. + +Here's what success looks like. On the MeshView map and in the Meshtastic app itself. The map shows each hop along the trace-route path; the app screenshot shows the tapback responses to a `test` message, with the **number emoji** telling you how many hops away that node was from you when they heard you. Tap any image to enlarge. + +
+
+ + Example MeshView map showing a successful trace route across the Arizona mesh. Colored markers in Phoenix metro plus a Tucson cluster, numbers indicating hop counts. + +
Trace route on the MeshView map
+
+
+ + Meshtastic app screenshot showing a 'Test' message marked Acknowledged with four tapback responses. Node IDs 0b3b, 2ef0, JICH, 82d0 each with a number emoji (2, 2, 3, 2) showing hop count. + +
Tapbacks in the Meshtastic app (number = hops away)
+
+
+ +### What a successful traceroute looks like in the Meshtastic app + +You can run a traceroute directly from the **Meshtastic app** itself (Android, iOS, or web). Tap a node in your node list, scroll down, hit **Trace Route**, and you'll get a result. Every hop on the way out, every hop on the way back, with the signal strength (dB) at each step. Green = strong signal, yellow/red = weak. + +You can also see your traceroutes on [view.azmsh.net](https://view.azmsh.net) as a network graph. The **filled, colored node** is the one you successfully traced to; the surrounding dashed boxes are the hops + neighbors the trace passed through or saw along the way. + +
+
+ + Meshtastic app traceroute result. Outbound path with dB values per hop, return path, duration 11.5s. + +
In-app traceroute result (Android shown; iOS + web work the same)
+
+
+ + MeshView graph view of a traceroute from mian t1000e through Tower Climber down to Roadrunner Ridge (the solid green node = successful hit), with neighbor branches to Empire Mountains + Bubba base visible. + +
A different traceroute viewed as a graph on view.azmsh.net. Solid colored node = successful target
+
+
+ +--- + +## You're Talking on the Mesh! + +**Nice job. You did it!** :tada: + +Here's what to do next: + +- **Join more channels.** Hop into the topic channels on Discord for traceroutes, hardware, and the help threads. +- **Sunday night chat.** Join us every Sunday at **5pm** on the **primary** channel for our weekly community chat. +- **Get your friends and family on the mesh.** The more nodes we have, the better the network works for everyone. Send them to [Start Here](start-here.md) to get started. + +[:fontawesome-brands-discord: Join the Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } diff --git a/docs/docs/recommended-hardware.md b/docs/docs/recommended-hardware.md index eb480af..a017a5b 100644 --- a/docs/docs/recommended-hardware.md +++ b/docs/docs/recommended-hardware.md @@ -12,7 +12,7 @@ New to Meshtastic? Here's what to buy. No monthly fees, no subscriptions. Just a **1. A handheld radio**. Carry it with you, pairs with your phone via Bluetooth
**2. A rooftop/attic node**. Put it up high at your home to keep you connected - That's it. Buy these two things, follow our [How to Connect](/docs/how-to-connect.html) guide, and you're on the mesh. + That's it. Buy these two things, follow our [Start Here](start-here.md) guide, and you're on the mesh. --- @@ -38,7 +38,7 @@ New to Meshtastic? Here's what to buy. No monthly fees, no subscriptions. Just a **~$125-150 in parts**. Every step is documented for first-time builders. - [:material-tools: Full Build Guide](/docs/wismesh-repeater-mini-1w.html){ .md-button .md-button--primary } + [:material-tools: Full Build Guide](wismesh-repeater-mini-1w.md){ .md-button .md-button--primary } @@ -230,12 +230,12 @@ Our #1 rooftop node. A community build that puts the RAK 1W Booster Kit (RAK3401 Plus small hardware: lever nuts (e.g. Wago) for parallel battery wiring, 3M double-sided foam tape, M3 machine screws, and hose clamps for mast mounting. A 3D printer is optional. Only the mast bracket and battery spacer are printed. !!! success "Community build by prayingmedic" - This build was designed and field-tested by **prayingmedic**, a member of the Arizona Meshtastic Community. Huge thanks to him for documenting it and sharing the photos and STL files. The [full build guide](/docs/wismesh-repeater-mini-1w.html) walks through every step. + This build was designed and field-tested by **prayingmedic**, a member of the Arizona Meshtastic Community. Huge thanks to him for documenting it and sharing the photos and STL files. The [full build guide](wismesh-repeater-mini-1w.md) walks through every step. !!! info "EIRP stays compliant" 30 dBm TX + the 5.8 dBi Alfa whip ≈ **35.8 dBm EIRP**. Just under the **36 dBm** US 915 MHz ISM limit. Don't pair this build with a higher-gain antenna at full power, or you'll go over. -:material-cart: **[Full Build Guide → WisMesh Repeater Mini 1W](/docs/wismesh-repeater-mini-1w.html){ .md-button .md-button--primary }** +:material-cart: **[Full Build Guide → WisMesh Repeater Mini 1W](wismesh-repeater-mini-1w.md){ .md-button .md-button--primary }** --- @@ -285,7 +285,7 @@ Put it in a waterproof junction box (~$10), add a 915 MHz antenna (~$15-40), and Don't want to build anything? These come fully assembled. Mount them, configure Meshtastic settings, done. !!! info "Node role for Arizona rooftop nodes" - Set your rooftop node to **CLIENT**. This is the recommended role for home installations. See the [Recommended Settings](/docs/recommended-settings.html) page for details on all roles. + Set your rooftop node to **CLIENT**. This is the recommended role for home installations. See [Additional Settings → Node Roles](additional-settings.md#device) for details on all roles. !!! warning "Understand Router roles before switching" **Router** and **Router Late** are intended for high-elevation, permanent fixed locations with good line-of-sight. Not typical home or rooftop installs. Using these roles in the wrong context can increase congestion and cause routing issues across the shared mesh. If you're considering Router or Router Late, read up on Meshtastic's guidance and ask the community on Discord before switching. @@ -301,7 +301,7 @@ Don't want to build anything? These come fully assembled. Mount them, configure - **Best value:** SenseCAP Solar P1 Pro. 5W solar panel, 4x 18650 batteries, GPS, ~$90 - **Easiest deploy:** WisMesh Repeater. IP67 weatherproof, mount and forget -- **Want the Repeater Mini?** Skip the stock version and build the **1W upgrade** instead. It's [our #1 rooftop pick](/docs/wismesh-repeater-mini-1w.html): same enclosure, 6x the TX power, no soldering. +- **Want the Repeater Mini?** Skip the stock version and build the **1W upgrade** instead. It's [our #1 rooftop pick](wismesh-repeater-mini-1w.md): same enclosure, 6x the TX power, no soldering. - **Premium turnkey:** Atlavox Beacon. Professional mounting hardware, dual SMA connectors, rugged build - **Need WiFi/MQTT?** Heltec V4 Solar Node. Heltec V4 board (+28 dBm), 25W solar panel, 6x 18650 battery bay, 5.5 dBi IP67 antenna, mast brackets included @@ -404,8 +404,8 @@ For most Arizona rooftop nodes, an **omnidirectional fiberglass antenna** is the #### Next Steps -- [How to Connect](/docs/how-to-connect.html). Set up your new radio and join the Arizona mesh -- [Recommended Settings](/docs/recommended-settings.html). Configure your node for the Arizona network +- [Start Here](start-here.md). Set up your new radio and join the Arizona mesh +- [Additional Settings](additional-settings.md). Tune your node for the Arizona network (roles, intervals, MQTT) - [Official Meshtastic Hardware List](https://meshtastic.org/docs/hardware/devices/) - [Meshtastic Getting Started Guide](https://meshtastic.org/docs/getting-started/) diff --git a/docs/docs/recommended-settings.md b/docs/docs/recommended-settings.md index 56d0ef8..3d2d395 100644 --- a/docs/docs/recommended-settings.md +++ b/docs/docs/recommended-settings.md @@ -2,172 +2,17 @@ hide: - navigation title: Recommended Settings +description: The settings reference has moved to the Additional Settings page. --- -# Recommended Settings + -These settings are based on real-world experience from the Arizona Meshtastic community. Following them helps keep our shared mesh network healthy and reliable for everyone. If you still need a radio, check our [Recommended Hardware](/docs/recommended-hardware.html) page first. +# Recommended Settings has moved -!!! note "Preset and Frequency" - The Arizona-specific **preset** and **frequency slot** are shared in our Discord server. Join to get these settings before configuring your device. +The settings reference (node roles, broadcast intervals, Neighbor Info, and MQTT) now lives on the **[Additional Settings](additional-settings.md)** page, laid out in the same order as the Meshtastic app. - [:fontawesome-brands-discord: Join the Discord to Get Settings](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } +The Arizona-specific **region, preset, and frequency slot** are shared in our [Discord server](https://discord.gg/HrKtyuFEQk) to keep the network coordinated. ---- - -## Node Roles - -Choosing the right role for your device keeps the network clean and efficient. - -### Client Mute - -**Use for: anything mobile**. Backpacks, vehicles, pocket nodes. - -Client Mute nodes can send and receive messages but do **not** rebroadcast other people's traffic. This is the best choice for devices that move around, since mobile rebroadcasters create unpredictable routing and extra congestion. - -### Client - -**Use for: stationary home or rooftop nodes.** - -Client is the standard role. Your node will participate in the mesh by rebroadcasting messages, which helps extend coverage for your neighbors. - -!!! tip "When in doubt, client it out" - Not sure which role to pick? Set your device to **Client Mute** and talk to a community member in Discord. You can always change it later. - -### Router and Router Late - -!!! warning "Understand Router roles before switching" - **Router** and **Router Late** are designed for nodes at **high elevation, permanent fixed locations with good line-of-sight**. Think hilltops, towers, or mountain repeater sites. They aggressively rebroadcast traffic and are optimized to extend the mesh across long distances. - - Used in the wrong context (a home, an apartment, or a mobile node), these roles can cause increased congestion, routing loops, and degraded performance for everyone on the mesh. Meshtastic's own guidance is to use these roles only where they genuinely improve coverage for the wider network, not just your own reach. - - **Before switching to Router or Router Late, make sure you understand the implications.** If you're unsure whether your location and setup are a good fit, ask the community on Discord. We're happy to help. - - [:fontawesome-brands-discord: Ask the Community on Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } - ---- - -## Broadcast Intervals - -Keeping broadcast intervals tuned correctly reduces channel congestion and lets everyone's messages get through reliably. - -### Mobile Nodes - -For devices that move around (in your car, backpack, pocket, etc.): - -| Setting | Value | Notes | -|:--------|:------|:------| -| **Node Info Broadcast** | `43200` sec (12 hours) | Your node info rarely changes. No need to broadcast it often. | -| **Smart Broadcast** | **ON** | Automatically sends position updates when you move. | -| Smart Broadcast Min Distance | `100` meters | Only broadcasts after moving at least 100m. | -| Smart Broadcast Min Interval | `60` seconds | No more than one smart broadcast per minute. | -| **Position Broadcast** | `3600` sec (1 hour) | Fallback interval if GPS is enabled. | -| **GPS Update Interval** | `300` sec (5 minutes) | How often the device checks its own GPS. | -| **Device Metrics** | `3600` sec (1 hour) | Battery, voltage, channel utilization, etc. | -| **Environment Metrics** | `3600` sec (1 hour) | Temperature, humidity, etc. (if sensors attached). | -| **Power Metrics** | `3600` sec (1 hour) | Power monitoring (if sensors attached). | -| **Map Report** | `3600` sec (1 hour) | Sends position to the map server. | - -### Stationary Nodes - -For devices that stay in one place (rooftop, home base, solar nodes): - -| Setting | Value | Notes | -|:--------|:------|:------| -| **Node Info Broadcast** | `43200` sec (12 hours) | Same as mobile. Node info does not change often. | -| **Smart Broadcast** | **OFF** | Your node is not moving, so smart positioning is not needed. | -| **Position Broadcast** | `43200` sec (12 hours) | Only if GPS is enabled. Your position is fixed. | -| **GPS Update Interval** | `21600` sec (6 hours) | Minimal GPS checks since the node does not move. | -| **Device Metrics** | `3600` sec (1 hour) | Still useful for monitoring battery and channel utilization. | -| **Environment Metrics** | `3600` sec (1 hour) | If sensors are attached. | -| **Power Metrics** | `3600` sec (1 hour) | If sensors are attached. | -| **Map Report** | `21600` sec (6 hours) | Less frequent since your position is fixed. | - ---- - -## Neighbor Info - -Neighbor Info is a module that periodically broadcasts a list of your node's direct neighbors along with the signal quality (SNR) of each link. When enabled across multiple nodes, the community can build a real picture of how the mesh is connected, which helps identify coverage gaps, optimize node placement, and understand how traffic actually flows through the network. - -Neighbor Info packets are small and infrequent, so the channel congestion impact is very low. - -**Recommended Update Interval** - -| Node type | Interval | Seconds | -|:----------|:---------|:--------| -| **Mobile** | 4 hours | `14400` | -| **Stationary** | 11 hours | `39600` | - -4 hours is the minimum the firmware allows. Use the longer interval for stationary nodes since their neighbors rarely change. - -??? note "How to Enable on Android" - Requires Meshtastic app version 2.2.0 or higher. - - 1. Open the Meshtastic app and connect to your node. - 2. Tap the **three-dot menu** (vertical ellipsis) in the top-right corner. - 3. Select **Radio Configuration**. - 4. Scroll down and tap **Neighbor Info**. - 5. Toggle **Enabled** to ON. - 6. Set the **Update Interval** to `14400` (mobile) or `39600` (stationary). - 7. Toggle **Transmit Over LoRa** to ON. This sends the neighbor info over the radio mesh and to MQTT. - 8. Tap **Send** to save the settings to your node. - -??? note "How to Enable on Web Client" - 1. Open the Meshtastic Web UI and connect to your node (usually at `meshtastic.local` or via USB serial). - 2. Click **Config** in the left sidebar. - 3. Click **Module Config**. - 4. Click **Neighbor Info**. - 5. Toggle **Enabled** to ON. - 6. Set the **Update Interval** to `14400` (mobile) or `39600` (stationary). - 7. Toggle **Transmit Over LoRa** to ON. - 8. Click **Save** to apply the settings. - -??? note "How to Enable via CLI" - Requires the Meshtastic Python CLI version 2.2.0 or higher (`pip install meshtastic`). - - ```bash - # Enable the module - meshtastic --set neighbor_info.enabled true - - # Set update interval (seconds): 14400 = 4 hours, 39600 = 11 hours - meshtastic --set neighbor_info.update_interval 14400 - - # Enable transmit over LoRa (sends over radio AND MQTT) - meshtastic --set neighbor_info.transmit_over_lora true - - # Verify your settings - meshtastic --get neighbor_info - ``` - - Run these commands while connected to your node over USB, Bluetooth, or TCP. - -!!! warning "iOS: Neighbor Info not currently supported" - The iOS Meshtastic app does not currently support enabling the Neighbor Info module. iOS users will need to use the Web client or CLI over a TCP/USB connection to configure this setting on their node. - ---- - -## MQTT - -MQTT lets your node upload diagnostic data to a shared server, which helps us monitor network health and see all nodes on the map. It does **not** send your personal messages or private data. Only metadata like position, telemetry, and node info. - -!!! info "What MQTT does and does not do" - - **Does**: Shares your node's position, battery level, signal metrics, and channel utilization with the community map and monitoring tools. - - **Does not**: Send your private messages, direct messages, or any encrypted channel content to any server. - -**How to Enable MQTT** - -To enable MQTT uplink, you will need the community broker settings (server address, username, and password). - -[:fontawesome-brands-discord: Join the Discord for MQTT Settings](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } - -Once you have the broker details: - -1. **LoRa Settings**: Enable **"OK to MQTT"**. This allows your node's data to be uplinked. -2. **MQTT Module**: Enter the broker settings provided in Discord. -3. **Channel Settings** (for each channel you want to uplink): - - **Uplink**: **ON**. Sends your node's data to the MQTT server. - - **Downlink**: **OFF**. Prevents MQTT messages from being injected back into the radio mesh. - -!!! warning "Always keep Downlink OFF" - Downlinking from MQTT into the primary channel floods the radio mesh with traffic from the internet. Keep downlink disabled unless you have a specific reason and have discussed it with the community. +You should be redirected automatically. If not: +[:material-tune: Go to Additional Settings](additional-settings.md){ .md-button .md-button--primary } diff --git a/docs/docs/recommended_configuration_settings.md b/docs/docs/recommended_configuration_settings.md deleted file mode 100644 index 4ba59f0..0000000 --- a/docs/docs/recommended_configuration_settings.md +++ /dev/null @@ -1,122 +0,0 @@ -# Recommended Settings - -!!! note "See the current Recommended Settings page" - This page is kept for reference. The maintained guidance lives on the - [Recommended Settings](/docs/recommended-settings.html) page, which matches - the [config checker](https://config.azmsh.net). Values here have been - reconciled to the canonical intervals (NodeInfo `43200`, stationary - Neighbor Info `39600`). - -To help maintain a healthy and reliable mesh network across Arizona, we suggest the following configuration settings for your Meshtastic devices. - -These recommendations are based on real-world use and shared experiences within the Arizona Meshtastic community. They’re designed to promote mesh stability and will likely evolve as our network grows. - ---- - -## 🔧 Radio Settings - -### 📱 Device Settings - -| Setting | Recommended Value | Details | -|--------:|:------------------|:--------| -| **Role** | `CLIENT` or `CLIENT_MUTE` | For most nodes. See [Deployment Scenarios](https://www.youtube.com/watch?v=htjwtnjQkkE) on YouTube. | -| **NodeInfo broadcast interval** | `43200` seconds (12 hours) | Keeps the mesh updated with node info without excess traffic. Node info rarely changes, so 12 hours is plenty. | - -### 📍 Position Settings - -| Setting | Recommended Value | Notes | -|--------:|:------------------|:------| -| **Smart position enabled** | `True` | Helps devices determine when they’ve moved. | -| **Position broadcast interval** | `3600` seconds (1 hour) | For mobile nodes. Disable for fixed installations. | -| **GPS update interval** | `1800` seconds (30 minutes) | Regular GPS refresh for mobile devices. | -| **Position flags** | Disable unused flags | Fixed nodes should turn off most position-related flags. | - -### 📶 LoRa Settings - -| Setting | Recommended Value | Notes | -|--------:|:------------------|:------| -| **Hop limit** | `5` | Please avoid setting higher than `6` to reduce network congestion. | -| **Ignore MQTT** | `True` | Ensures nodes don’t rely on cloud-based data relays. | -| **OK to MQTT** | `True` | (Firmware v2.5.0+) Allows your node to appear on [view.azmsh.net](https://view.azmsh.net). | - ---- - -## ⚙️ Module Settings - -### 📊 Telemetry - -| Setting | Recommended Value | Notes | -|--------:|:------------------|:------| -| **Device metrics update interval** | `3600` seconds (1 hour) | Consider `1800` (30 min) when testing or monitoring new devices. | -| **Environment metrics update interval** | `3600` seconds (1 hour) | Disable if you’re not using environmental sensors. | -| **Power metrics module** | `False` | For advanced setups with I²C sensors, usually not needed. | - -> ℹ️ *If you don’t use temperature, air quality, or similar sensors, it’s best to turn off the corresponding modules to reduce bandwidth usage.* - -### 🤝 Neighbor Info - -| Setting | Recommended Value | Notes | -|--------:|:------------------|:------| -| **Neighbor Info enabled** | `True` | Enables your node to keep track of nearby devices. | -| **Update interval** | `39600` seconds (11 hours) | Recommended for stationary nodes (neighbors rarely change). `14400` (4 hours) is the firmware minimum for mobile nodes. | -| **Transmit over LoRa** | `True` | Share info with nearby nodes via radio. | - ---- - -## 🛠️ Apply Settings Using Meshtastic CLI -If you haven’t installed the CLI yet, follow the official instructions here: -🔗 [Meshtastic CLI Installation Guide](https://meshtastic.org/docs/software/python/cli/installation/) -# Device Settings -``` -meshtastic \ - - --set device.role CLIENT \ - - --set device.node_info_broadcast_secs 43200 -``` -# Position Settings -``` -meshtastic \ - - --set position.position_broadcast_smart_enabled true \ - - --set position.position_broadcast_secs 3600 \ - - --set position.gps_update_interval 1800 \ - - --pos-fields ALTITUDE ALTITUDE_MSL HEADING SPEED -``` -# LoRa Settings -``` -meshtastic \ - - --set lora.hop_limit 5 \ - - --set lora.ignore_mqtt true \ - - --set lora.config_ok_to_mqtt true -``` -# Telemetry Module -``` -meshtastic \ - - --set telemetry.device_update_interval 3600 \ - - --set telemetry.environment_update_interval 3600 \ - - --set telemetry.power_measurement_enabled false \ - - --set telemetry.environment_measurement_enabled false \ - - --set telemetry.air_quality_enabled false -``` -# Neighbor Info Module -``` -meshtastic \ - - --set neighbor_info.enabled true \ - - --set neighbor_info.update_interval 39600 \ - - --set neighbor_info.transmit_over_lora true -``` diff --git a/docs/docs/start-here.md b/docs/docs/start-here.md new file mode 100644 index 0000000..9e764b6 --- /dev/null +++ b/docs/docs/start-here.md @@ -0,0 +1,134 @@ +--- +hide: + - navigation +title: Start Here +description: The first 30 minutes on the Arizona mesh. A single, in-order guide that takes you from an unboxed radio to sending your first message and seeing it acknowledged. +--- + +# Start Here: Your First 30 Minutes + +New to the Arizona mesh? This is the page to get going. Follow the steps **in order, top to bottom** (don't skip ahead). By the end you'll have a working node, the right Arizona settings, and proof that the mesh can hear you. Once you're connected and want to fine-tune your node, the deeper settings reference (roles, broadcast intervals, MQTT) lives on [Additional Settings](additional-settings.md). + +!!! info "What you need before you begin" + - A Meshtastic radio. Don't have one? See [Recommended Hardware](recommended-hardware.md). You can get on the mesh for about $30. + - The Meshtastic app on your phone (links in Step 2). + - About 30 minutes. Most of it is waiting for firmware to flash. + - Our Discord, which is where the Arizona radio settings live (link in Step 3). + +[:fontawesome-brands-discord: Join the Arizona Meshtastic Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } + +--- + +## Step 1: Flash the latest firmware + +1. Open the [**Meshtastic Web Flasher**](https://flasher.meshtastic.org) in **Google Chrome** (other browsers often fail to connect to the serial port). +2. Select your device, click **Flash**, and follow the prompts. + +!!! warning "Leave “Install Meshtastic UI” UNCHECKED on most devices" + The web flasher may offer an **"Install Meshtastic UI"** option. **Meshtastic UI (MUI)** is a separate on-device interface built for **color touchscreen** devices like the LilyGO T-Deck and SenseCAP Indicator. It is **not** meant for the small OLED screens on common boards like the **Heltec V3/V4** or RAK handhelds, and installing it there can leave you with a blank screen or a boot loop. Unless you have a touchscreen device and specifically want the on-device UI, leave this **unchecked** and use the phone app for the interface. If your screen is already stuck or blank, re-flash with it off. See [FAQ → Flashing problems](faq.md#flashing-gotchas). + +!!! danger "Never transmit without an antenna attached" + Powering on or sending with the antenna disconnected can permanently damage the radio. Always screw the antenna on first. + +!!! tip "Back up your keys before re-flashing" + Flashing can wipe your settings, including your node's identity keys. Export/back up your configuration from the Meshtastic app first, so you don't reappear as a brand-new node. + +--- + +## Step 2: Install the app and pair over Bluetooth + +| Platform | Link | +|:---------|:-----| +| **Android** | [Google Play Store](https://play.google.com/store/apps/details?id=com.geeksville.mesh) | +| **iOS** | [Apple App Store](https://apps.apple.com/us/app/meshtastic/id1586432531) | + +1. Turn on your radio. +2. Open the app, tap **+**, and select your device to pair over Bluetooth. +3. If prompted for a pairing code, the default is usually printed on your device or in its documentation. +4. You should now see your node in the app. + +--- + +## Step 3: Get the Arizona radio settings from Discord + +This is where most new nodes go wrong, and it's why this step points you to Discord. + +To join the Arizona mesh you need the community-specific **region, preset, and frequency slot**. We keep those values in our [Discord server](https://discord.gg/HrKtyuFEQk) so they stay coordinated and current, then you enter them in the app. + +In your Meshtastic app, open **Settings → LoRa (Radio Configuration)** and set these: + +
+
+

Arizona LoRa settings

+
1. Region: US
+
2. Preset: ExamplePreset_AZ
+
3. Frequency Slot: 00
+
+
+ 🔒 Arizona radio settings are shared in Discord + Join The Discord +
+
+ +!!! warning "The Frequency Slot is the #1 missed setting" + Lots of people set the preset correctly but leave the **Frequency Slot** at `0`/auto, so they land on the wrong frequency and can't hear anyone. Set it to the exact slot listed in Discord. + + **iOS gotcha:** the Slot field is text entry. **Double-tap the existing value** to select it, then type the correct slot. Leave **Frequency Override** blank or `0`; entering a value there *locks* the Slot field. "Override" and "Slot" are different fields. + +--- + +## Step 4: Set up your primary channel + +Open **Settings → Channels** and configure the **primary** channel (index 0) using the values from Discord. + +
+
+

Primary channel (index 0)

+
Name: ExampleName
+
Key (PSK): ExampleKey==
+
+
+ 🔒 Primary channel name + key are shared in Discord + Join The Discord +
+
+ +!!! danger "Do NOT rename your primary channel" + Renaming the primary channel to "AZ Mesh", "azmsh", or anything custom puts you on a *different* channel and you fall off the mesh entirely. Use exactly the name and key listed in Discord. + +Want the extra Arizona community channels (azmsh, Weather, Traffic, Trivia)? Those are public and live on the [Suggested Channels](suggested_channels.md) page. Add them as **secondary** channels; they don't replace your primary. + +--- + +## Step 5: (Optional) Turn on MQTT for the map + +MQTT puts your node on the community map and shares diagnostics. It does **not** carry your text messages. The full MQTT walkthrough, including the broker details, is on [Additional Settings → MQTT](additional-settings.md#mqtt). + +--- + +## Step 6: Self-test (prove the mesh can hear you) + +This is the moment of truth. + +1. Go to the **Messages** tab and open your **primary** channel. +2. Send the message: **`test`** (send it as many times as you want). +3. Wait up to a minute, then watch for **emoji tapbacks** on your message. A tapback is an emoji reaction attached to your message (like a thumbs-up on a text). Many Arizona nodes run an auto-responder that reacts with a number: + - :one: :two: :three: … = how many hops away that node was when it heard you + - :asterisk: = a direct hit, no hops + +**You got tapbacks?** :tada: You're on the Arizona mesh. Head to [How To Test](how-to-test.md) to claim your node and explore the map. + +**No tapbacks after a few tries?** That's almost always physical placement, not a settings bug. Keep reading. + +!!! tip "If you can RECEIVE any messages, your settings are correct" + Seeing *other people's* messages come in means your radio, preset, slot, and channel are all right. If you can hear them but they can't hear you, it's an RF/placement problem, not a configuration problem. Go to [FAQ → I can receive, but I can't send](faq.md#cant-send). + +--- + +## Where to go next + +- :material-test-tube: **Test your setup / see yourself on the map** → [How To Test](how-to-test.md) +- :material-help-circle: **Can't send / no acks / "Max Transmission Reached"?** → [FAQ → I can receive, but I can't send](faq.md#cant-send) +- :material-radio-tower: **Add community channels** → [Suggested Channels](suggested_channels.md) +- :material-tune: **Tune your node (roles, intervals, MQTT)** → [Additional Settings](additional-settings.md) +- :material-frequently-asked-questions: **Site says "Forbidden", node won't claim, flashing problems** → [FAQ & Troubleshooting](faq.md) diff --git a/docs/docs/suggested_channels.md b/docs/docs/suggested_channels.md index 69b088c..8f8b84c 100644 --- a/docs/docs/suggested_channels.md +++ b/docs/docs/suggested_channels.md @@ -10,14 +10,15 @@ name and encryption key so the right messages reach the right people. Adding the channels below lets you join the wider **azmsh.net** community. Chat on the Arizona channel, watch the weather roll in from rooftop stations, keep an eye on traffic, and -even play a little trivia. Everything here is shared publicly so anyone in the community can -hop on. +even play a little trivia. These community channel names and keys are public and listed +[in the table below](#the-channels). (Your **primary** channel, region, preset, and frequency +slot are coordinated in [Discord](https://discord.gg/HrKtyuFEQk); see [Start Here](start-here.md).) !!! tip "Two things to get right" - **Channel names are case-sensitive.** `Weather` and `weather` are *not* the same channel. - - **Keys must match exactly.** Copy the key from the table below character-for-character. - They're short, public, pre-shared keys (PSKs). That's by design for community channels. + - **Keys must match exactly.** Copy each key from the table below character-for-character. + They're short, pre-shared keys (PSKs). That's by design for community channels. --- @@ -27,7 +28,7 @@ Pick your platform below. The flow is the same idea everywhere: open the Meshtas find the **Channels** editor, add a channel, and enter the **Name** and **Key** from the [table further down](#the-channels) exactly as written. -???+ note "Android" +??? note "Android" 1. Open the **Meshtastic** app and make sure your node is connected over Bluetooth. 2. Tap the **Settings** tab, then open **Channels**. @@ -39,7 +40,7 @@ find the **Channels** editor, add a channel, and enter the **Name** and **Key** 6. Leave **Uplink/Downlink** at their defaults unless you have a reason to change them. 7. Tap **Save** / the send button to write the channel to your node. - > To use **MediumFast** as your primary channel, you can leave the primary channel's + > To use the default preset as your primary channel, you can leave the primary channel's > name **blank**. An empty primary name is the `default` channel. ??? note "iOS / iPadOS / macOS" @@ -54,7 +55,7 @@ find the **Channels** editor, add a channel, and enter the **Name** and **Key** 6. Enter the **Key** (PSK) from the table exactly as written. 7. Tap **Save**, then make sure you **send the configuration** back to your node. - > To use **MediumFast** as your primary channel, you can leave the primary channel's + > To use the default preset as your primary channel, you can leave the primary channel's > name **blank**. An empty primary name is the `default` channel. ??? note "Other (Web Client / Apple Watch / CLI)" @@ -81,24 +82,31 @@ find the **Channels** editor, add a channel, and enter the **Name** and **Key** ``` Adjust the `--ch-index` and values for each channel you want. Use the exact names and keys - from the table. Names are case-sensitive. + from the table below. Names are case-sensitive. --- ## The Channels -Add any of these to join the conversation. Keys are shown in monospace so you can tell them -apart at a glance (`AQ==` vs `Ww==`). The table scrolls sideways on small screens. Swipe to -see every column. +These Arizona **community** channels are public. Add them as **secondary** channels (they +don't replace your primary). Each one has a **name** and a short pre-shared **key (PSK)**. +Keys are shown in monospace so you can tell them apart at a glance (`AQ==` vs `Ww==`). The +table scrolls sideways on small screens; swipe to see every column. | Channel Name (case sensitive) | Key | Size (iOS only) | Description | |:------------------------------|:----|:----------------|:------------| -| `MediumFast` | `AQ==` | Default | The default primary MediumFast channel. Name can also be left blank. | | `azmsh` | `AQ==` | Default | The Arizona channel, great for running tests and general chatter. | | `Weather` | `Ww==` | 1-byte | Users post from their weather stations on their roofs, great for checking the weather every hour and making sure your node is consistently receiving. | | `Traffic` | `TQ==` | 1-byte | Local traffic reports along with waypoints showing where there is traffic on the map. | | `Trivia` | `MQ==` | 1-byte | Play trivia with your fellow users. Type `!help` in the channel to learn how to play. | +!!! note "Your primary channel is separate" + + The community-specific **primary** channel name + key (and the region, preset, and frequency + slot) are still coordinated in [Discord](https://discord.gg/HrKtyuFEQk). Set those up first on + [Start Here → Step 3 & 4](start-here.md#step-3-get-the-arizona-radio-settings-from-discord), + then add the public community channels above as **secondary** channels. + !!! question "Need a hand?" Stuck getting a channel to show up? Hop into our [Discord](https://discord.gg/HrKtyuFEQk) diff --git a/docs/docs/what-now.md b/docs/docs/what-now.md index 2ed65de..538a2b4 100644 --- a/docs/docs/what-now.md +++ b/docs/docs/what-now.md @@ -2,139 +2,15 @@ hide: - navigation title: What Now? -description: You set up your node and configured your settings. Now how do you check if anyone can hear you? The post-setup playbook for new Arizona Meshtastic operators. +description: This page has moved to How To Test. --- -# What Now? + -So you've got your node set up, the app downloaded, all your settings configured. You connected. **Now what? How do you know if it's actually working, if anyone out there can hear you?** +# What Now? has moved -This page is the moment right after [How to Connect](/docs/how-to-connect.html). Your radio is on, your settings are dialed in, and you're staring at the screen wondering: *did I do this right?* +We renamed this page to **[How To Test](how-to-test.md)** so it's clear what it covers: how to test your setup and confirm the mesh can hear you. -Here's how to find out. +You should be redirected automatically. If not: ---- - -## Step 1. Say "test" on the Mesh - -Meshtastic is part art and part science. The art part is trying a lot of things and testing to see what works. Everyone's setup and location is different. - -1. Type `test` in the **Primary MediumFast** channel. Send it. (Send it as many times as you want.) -2. A lot of our users run **MeshMonitor** which will respond automatically with a tapback emoji: - - :one: :two: :three: :four: :five: :six: :seven:. How many hops away that user is from you - - :asterisk:. Direct hit (no hops, they heard you straight) -3. **Got tapbacks? Congrats. You're on the mesh.** Skip to [Step 4](#step-4-claim-your-node-opt-in-for-diagnostics). -4. **No tapbacks?** Don't panic. Keep reading. - ---- - -## Step 2. Not Getting Responses? Move Around. - -If `test` is getting crickets, the most common fixes are physical, not technical. - -1. **Try different locations.** Inside vs outside makes a huge difference. Near a window vs interior wall. Also big. -2. **Get higher.** **Height is might.** Roof, balcony, second floor. Anywhere that gives your antenna line-of-sight to the sky and the surrounding terrain. -3. **Step outside completely.** Even a 30-second outdoor test will tell you whether your indoor location is the problem. -4. **Try at different times of day.** The mesh ebbs and flows. If no one's around when you test, you'll hear nothing. - -Keep doing the above until you see something land. Try every location, see what works best for you. - ---- - -## Step 3. Still Nothing? Check Your Settings. - -The **#1 issue** we see new operators run into is missing a setting. Or turning something on that shouldn't be on. - -Make sure every setting on the [Recommended Settings](/docs/recommended-settings.html) page is configured correctly, and nothing else. - -!!! tip "When in doubt, leave it alone" - If you aren't fully sure what a setting does, don't mess with it. If you want someone to check your settings, start a thread in **#i-need-help** on Discord. We're happy to take a look. - -### 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. - ---- - -## Step 4. Claim Your Node + Opt In for Diagnostics - -Now that you're heard on the mesh, plug into the community side. - -**Claim your node.** Type `/node claim` in Discord. This helps others know the node is yours. They can tag you when they have questions, hear you on the air, or want to know if you can hear them. - -**Opt in for diagnostic data.** Click the :pie: reaction in the **#getting-started** channel on Discord. Opting in unlocks: - -- More diagnostic data on your node -- Access to [view.azmsh.net](https://view.azmsh.net). Our community map and MQTT diagnostics tool - -[:fontawesome-brands-discord: Join the Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } - ---- - -## Step 5. Check Your Messages and Trace Routes - -Once you've opted in, search for your node on [view.azmsh.net/nodelist](https://view.azmsh.net/nodelist) to see what's actually happening on the air. - -
- - Screenshot of view.azmsh.net/nodelist with the Traceroute button highlighted in red and a text message ID highlighted in blue. - -
view.azmsh.net/nodelist. Click to enlarge
-
- -- **Red (Traceroutes):** Click the arrow next to the trace routes and it'll show you the path your trace routes took. And when others trace route you. You can run trace routes by clicking on a node in the node list, scrolling down, and tapping **Trace Route**. You'll get a cool graph of where your trace route went trying to hit that node and get back home. You can also see these in **#traceroutes** on Discord. -- **Blue (Message stats):** Click the number ID for any text message you sent to see the stats for that specific message, including which nodes it hit on the way. You can also see your messages in **#messages**. - -Here's what success looks like. On the MeshView map and in the Meshtastic app itself. The map shows each hop along the trace-route path; the app screenshot shows the tapback responses to a `test` message, with the **number emoji** telling you how many hops away that node was from you when they heard you. Tap any image to enlarge. - -
-
- - Example MeshView map showing a successful trace route across the Arizona mesh. Colored markers in Phoenix metro plus a Tucson cluster, numbers indicating hop counts. - -
Trace route on the MeshView map
-
-
- - Meshtastic app screenshot showing a 'Test' message marked Acknowledged with four tapback responses. Node IDs 0b3b, 2ef0, JICH, 82d0 each with a number emoji (2, 2, 3, 2) showing hop count. - -
Tapbacks in the Meshtastic app (number = hops away)
-
-
- -### What a successful traceroute looks like in the Meshtastic app - -You can run a traceroute directly from the **Meshtastic app** itself (Android, iOS, or web). Tap a node in your node list, scroll down, hit **Trace Route**, and you'll get a result. Every hop on the way out, every hop on the way back, with the signal strength (dB) at each step. Green = strong signal, yellow/red = weak. - -You can also see your traceroutes on [view.azmsh.net](https://view.azmsh.net) as a network graph. The **filled, colored node** is the one you successfully traced to; the surrounding dashed boxes are the hops + neighbors the trace passed through or saw along the way. - -
-
- - Meshtastic app traceroute result. Outbound path with dB values per hop, return path, duration 11.5s. - -
In-app traceroute result (Android shown; iOS + web work the same)
-
-
- - MeshView graph view of a traceroute from mian t1000e through Tower Climber down to Roadrunner Ridge (the solid green node = successful hit), with neighbor branches to Empire Mountains + Bubba base visible. - -
A different traceroute viewed as a graph on view.azmsh.net. Solid colored node = successful target
-
-
- ---- - -## You're Talking on the Mesh! - -**Nice job. You did it!** :tada: - -Here's what to do next: - -- **Join more channels.** Hop into the topic channels on Discord for traceroutes, hardware, and the help threads. -- **Sunday night chat.** Join us every Sunday at **5pm** on the **Primary MediumFast** channel for our weekly community chat. -- **Get your friends and family on the mesh.** The more nodes we have, the better the network works for everyone. Send them to [How to Connect](/docs/how-to-connect.html) to get started. - -[:fontawesome-brands-discord: Join the Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary } +[:material-test-tube: Go to How To Test](how-to-test.md){ .md-button .md-button--primary } diff --git a/docs/docs/wismesh-repeater-mini-1w.md b/docs/docs/wismesh-repeater-mini-1w.md index 0781b94..012e87f 100644 --- a/docs/docs/wismesh-repeater-mini-1w.md +++ b/docs/docs/wismesh-repeater-mini-1w.md @@ -213,8 +213,8 @@ The nRF52840 chip flashes by drag-and-drop. No special software, just a web brow Flashing is not configuring. **Do not skip this part.** Set the node up the same way as every other node on the Arizona mesh: -1. **Follow the [How to Connect](/docs/how-to-connect.html) guide** to pair the node and get it on the mesh. -2. **Apply everything on the [Recommended Settings](/docs/recommended-settings.html) page**. Region, role, channels, and broadcast intervals all live there. Those settings keep the whole Arizona mesh healthy; this guide doesn't repeat them. +1. **Follow the [Start Here](start-here.md) guide** to pair the node and get it on the mesh. +2. **Apply everything in [Additional Settings](additional-settings.md).** Region, role, channels, and broadcast intervals all live there. Those settings keep the whole Arizona mesh healthy; this guide doesn't repeat them. ### Settings specific to this build @@ -227,7 +227,7 @@ Only a few settings differ from a standard node because of the 1W radio and sola | **Bluetooth** | Off if not needed | Saves power. If you turn BT off, plan to manage the node with an **admin node** remotely. | !!! warning "Don't pick Router/Router Late just because it's powerful" - A 1W node is tempting to set as a Router. **Don't, unless your site genuinely calls for it.** Router roles are for high-elevation, permanent, line-of-sight repeater sites. For a home rooftop, stick with the role guidance on [Recommended Settings](/docs/recommended-settings.html). If you think your location qualifies, ask the community on Discord first. + A 1W node is tempting to set as a Router. **Don't, unless your site genuinely calls for it.** Router roles are for high-elevation, permanent, line-of-sight repeater sites. For a home rooftop, stick with the role guidance in [Additional Settings → Node Roles](additional-settings.md#device). If you think your location qualifies, ask the community on Discord first. !!! danger "EIRP compliance. Stay legal" Your **effective radiated power** is TX power **plus** antenna gain: @@ -291,10 +291,10 @@ Want to go deeper on the RAK 1W kit and its power behavior? **Atlavox** has two #### Next Steps -- [Recommended Hardware](/docs/recommended-hardware.html). See how this stacks up against other rooftop nodes -- [Recommended Settings](/docs/recommended-settings.html). Full role and interval guidance for the Arizona mesh -- [How to Connect](/docs/how-to-connect.html). Get your node on the Arizona mesh -- [What Now?](/docs/what-now.html). Confirm the mesh can actually hear you +- [Recommended Hardware](recommended-hardware.md). See how this stacks up against other rooftop nodes +- [Start Here](start-here.md). Get your node on the Arizona mesh +- [Additional Settings](additional-settings.md). The full settings reference (roles, broadcast intervals, MQTT) +- [How To Test](how-to-test.md). Confirm the mesh can actually hear you --- diff --git a/docs/index.md b/docs/index.md index db8f7e3..49a4ff5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,11 +11,13 @@ Meshtastic is a free, open-source mesh network that lets you send text messages, Whether you're brand new to radio or a seasoned operator, this is your hub to get started and connect with the Arizona Meshtastic Community. - - [:fontawesome-brands-discord: Join us on Discord](https://discord.gg/HrKtyuFEQk){ .md-button .md-button--primary target="_blank"} - [:material-information-outline: Learn how to connect](/docs/how-to-connect.html){ .md-button } + + [:material-rocket-launch: Start Here](docs/start-here.md){ .md-button .md-button--primary } + [:fontawesome-brands-discord: Join us on Discord](https://discord.gg/HrKtyuFEQk){ .md-button target="_blank"} +

New to the mesh? The Start Here guide gets you from an unboxed radio to your first acknowledged message in about 30 minutes.

+
- __Total Nodes__ diff --git a/docs/privacy.md b/docs/privacy.md index 7ed36e8..9890655 100644 --- a/docs/privacy.md +++ b/docs/privacy.md @@ -83,7 +83,7 @@ A typical packet travels like this: 2. A node on the mesh that is connected to MQTT relays that packet to an MQTT broker. 3. Our ingestion tool reads the packet from the broker and decodes it using the - public default key (AQ==). + well-known public default key that ships with every Meshtastic device. 4. The decoded data is shown in our tools, such as view.azmsh.net. Our broker is set up for uploads only. Nodes can send data to it, but downlink is @@ -95,9 +95,9 @@ changes how your node behaves.** ## Important: public-channel data is not private Meshtastic's standard channels are secured only with a default encryption key -(AQ==) that ships with every device and is publicly known. This is not unique to -one channel. The same default key is used by the common presets, such as LongFast -and MediumFast, whenever a channel is left on the default key. Because that key is +that ships with every device and is publicly known. This is not unique to +one channel. The same default key is used by the common modem presets whenever a +channel is left on the default key. Because that key is public, anyone running Meshtastic can read traffic that uses it. It is not private, even though it is technically "encrypted." diff --git a/mkdocs.yml b/mkdocs.yml index 062efde..1b514f4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,7 @@ site_name: Arizona Meshtastic Community theme: name: material + custom_dir: overrides language: en logo: assets/images/logo.png favicon: assets/images/favicon.png @@ -8,6 +9,8 @@ theme: - search.suggest - search.highlight - search.share + # navigation.instant is intentionally NOT enabled: it breaks reliable + # keyboard focus / screen-reader announcement on page change (a11y, PR #25). - navigation.tabs - navigation.tabs.sticky palette: @@ -30,19 +33,35 @@ site_url: https://azmsh.net repo_name: azmsh-site repo_url: https://github.com/ArizonaMeshtasticCommunity/azmsh-site +# A single linear newcomer journey (Home -> Start Here -> What Now?) followed by +# reference pages, plus one consolidated troubleshooting hub. nav: - Home: index.md - - How to Connect: docs/how-to-connect.md - - What Now?: docs/what-now.md + - Start Here: docs/start-here.md + - How To Test: docs/how-to-test.md + - FAQ & Troubleshooting: docs/faq.md + - Additional Settings: docs/additional-settings.md - Recommended Hardware: docs/recommended-hardware.md - - Recommended Settings: docs/recommended-settings.md - Suggested Channels: docs/suggested_channels.md - Host a Node: docs/host-a-node.md - Reach Out: reach_out.md -# Accessibility and Privacy Policy are intentionally not in the top nav; they are -# linked from the footer (see the `copyright` setting below). +# Pages intentionally kept out of the top nav. +# Redirect stubs (meta-refresh) so old / external links never 404 after the +# consolidation / rename: +# how-to-connect -> folded into Start Here +# recommended-settings -> now redirects to the Additional Settings page +# cant-transmit, flashing-gotchas -> folded into FAQ & Troubleshooting +# what-now -> renamed to How To Test (how-to-test.md) +# wismesh-repeater-mini-1w is a deep build guide linked from Recommended Hardware. +# accessibility and privacy are linked from the footer. not_in_nav: | + /docs/how-to-connect.md + /docs/recommended-settings.md + /docs/cant-transmit.md + /docs/flashing-gotchas.md + /docs/what-now.md + /docs/wismesh-repeater-mini-1w.md /accessibility.md /privacy.md @@ -71,15 +90,17 @@ markdown_extensions: extra_css: - stylesheets/extra.css # Accessibility (WCAG AA contrast) overrides + - assets/css/extra.css # Discord-gated settings boxes extra_javascript: - assets/js/nodeData.js # Node Info - assets/js/a11y.js # Skip-link focus management +# The Accessibility / Privacy footer links are rendered by the custom +# overrides/partials/copyright.html partial using {{ base_url }} so they +# resolve at every page depth on both azmsh.net and the preview sub-path. copyright: > Copyright © 2026 Arizona Meshtastic Community -  ·  Accessibility -  ·  Privacy Policy extra: social: - icon: fontawesome/brands/discord diff --git a/overrides/partials/copyright.html b/overrides/partials/copyright.html new file mode 100644 index 0000000..aea3739 --- /dev/null +++ b/overrides/partials/copyright.html @@ -0,0 +1,23 @@ +{#- + Custom override of Material's copyright partial. + The Accessibility / Privacy footer links (Logan's a11y wiring) are built from + {{ base_url }} so they resolve correctly at every page depth AND on any host: + the production root (azmsh.net) and the project-pages preview sub-path + (rancur.github.io/azmsh-site/). Absolute "/accessibility.html" links would + 404 on the preview sub-path, so they are intentionally NOT used here. +-#} +
+ {% if config.copyright %} +
+ {{ config.copyright }} +  ·  Accessibility +  ·  Privacy Policy +
+ {% endif %} + {% if not config.extra.generator == false %} + Made with + + Material for MkDocs + + {% endif %} +