Merge branch 'master' into patch-1

docs/configuration/device-config/channels.mdx

@@ -48,7 +48,7 @@ Each channel is assigned one of 3 roles:
 1. `PRIMARY` or `1`
    - This is the first channel that is created for you on initial setup.
    - Only one primary channel can exist and can not be disabled.
-   - Direct messages are only available on this channel.
+   - Periodic broadcasts like position and telemetry are only sent over this channel.
 2. `SECONDARY` or `2`
    - Can modify the encryption key (PSK).
 3. `DISABLED` or `0`

docs/configuration/gpio-peripherals.mdx

@@ -6,26 +6,12 @@ slug: /hardware/peripheral/
 sidebar_position: 6
 ---
 
-## Firmware Versions
+## Remote Hardware
 
 :::warning
 GPIO access is fundamentally dangerous because invalid options can physically damage or destroy your hardware. Ensure that you fully understand the schematic for your particular device before trying this as we do not offer a warranty. Use at your own risk.
 :::
 
-The device firmware runs on the nodes to build the mesh for communication. Each different make and model of device requires a different build of the Meshtastic firmware in order to run properly. Thankfully, due to the design of Meshtastic, it is possible to port the firmware to new devices as they become available. The firmware currently runs on a range of ESP32 based devices, but there is also increasing support for the nRF52 microprocessor with some more recent devices coming to market.
-
-The current firmware has support for a screen to display received messages, along with information about nodes on the mesh, and more detailed information about the device on which it is running.
-
-The latest firmware can be downloaded from the [Downloads](/downloads) page. If you wish to view the code or contribute to development of the firmware, please visit the device code [GitHub page](https://github.com/meshtastic/firmware).
-
-:::info
-Please be aware that there are significant changes between version branches 1.2.x and 1.3.x which mean that devices need to be running the same branch of firmware to be able to talk to each other. Python, Android, and other software applications will also need to be running the same branch to be able to talk to the device.
-
-This feature uses a preinstalled module in the device code and associated command line flags/classes in the python code. You'll need to be running at least version 1.2.23 (or later) of the python and device code to use this feature.
-:::
-
-## Remote Hardware
-
 ### Supported Operations
 
 - Set any GPIO

docs/configuration/module-config/serial.mdx

@@ -196,13 +196,7 @@ Default is to use RX GPIO 16 and TX GPIO 17.
 
 ### Interfacing PIR Sensor With External Microcontroller
 
-The following is an example of using a Raspberry Pi Pico connected to a PIR sensor to detect motion. When motion is detected, a message is sent via. serial to the T-Beam. The T-Beam transmits the message as text over the default channel by utilizing the serial module in TXTMSG mode.
+The following are examples of using either a Raspberry Pi Pico or Arduino Mini Pro connected to a PIR sensor to detect motion. When motion is detected, a message is sent via serial to the T-Beam. The T-Beam transmits the message as text over the default channel by utilizing the serial module in TXTMSG mode.
-
-#### BOM
-
-- Raspberry Pi Pico running [CircuitPython](https://learn.adafruit.com/getting-started-with-raspberry-pi-pico-circuitpython)
-- T-Beam V1.1 running Meshtastic
-- PIR Sensor ([Adafruit Breadboard Model](https://www.adafruit.com/product/4871))
 
 #### Meshtastic Software Configuration
 
@@ -210,9 +204,15 @@ The following is an example of using a Raspberry Pi Pico connected to a PIR sens
 - GPIO Pins (For T-Beam) RX 13, TX 14
 - 38400 Baud
 
-#### Wiring
+#### Rasberry Pi Pico BOM
 
-![image](https://user-images.githubusercontent.com/2799310/210852481-21ea76e5-ecaa-40c1-8f34-635ef2a1c95b.png)
+- A Raspberry Pi Pico running [CircuitPython](https://learn.adafruit.com/getting-started-with-raspberry-pi-pico-circuitpython)
+- T-Beam V1.1 running Meshtastic
+- PIR Sensor ([Adafruit Breadboard Model](https://www.adafruit.com/product/4871))
+
+#### Raspberry Pi Pico Wiring
+
+![image](/img/modules/Serial/pico-pir-wiring.png)
 
 - TX pin 14 on the T-Beam to RX pin 2 on the Pico
 - RX pin 13 on the T-Beam to TX pin 1 on the Pico
@@ -245,3 +245,52 @@ while True:
         time.sleep(30)
     time.sleep(0.5)
 ```
+
+#### Arduino Mini Pro BOM
+- An Arduino Mini Pro with example sketch from below uploaded to it.
+- T-Beam V1.1 running Meshtastic
+- PIR Sensor ([Adafruit Breadboard Model](https://www.adafruit.com/product/4871))
+
+#### Arduino Mini Pro Wiring
+
+![image](/img/modules/Serial/arduino-mini-pro-pir-wiring.png)
+
+- T-BEAM RX PIN 13 to TX PIN on the ARDUINO MINI
+- T-BEAM TX PIN 14 to RX PINon the ARDUINO MINI
+- T-BEAM PIN 3.3V to 3.3V PIN on the ARDUINO MINI
+- T-BEAM PIN GND to GND PIN on the ARDUINO MINI
+- ARDUINO MINI PIN 2 to OUT PIN on the PIR SENSOR
+- ARDUINO MINI PIN 3.3V to 3.3V on the PIR SENSOR
+- ARDUINO MINI PIN GND to GND PIN on the PIR SENSOR
+
+#### Arduino Mini Pro Code
+
+```cpp
+int LED = 13; // the pin to which the LED is connected
+int PIR = 2;  // the pin to which the sensor is connected
+int previousState = LOW; // previous state of the sensor
+
+
+void setup() {
+pinMode(LED, OUTPUT); // initialize the LED as an output
+pinMode(PIR, INPUT);  // initialize the sensor as an input
+Serial.begin(9600);   // initialize serial communication
+}
+
+void loop(){
+   int currentState = digitalRead(PIR); // read the current state of the sensor
+  if (currentState != previousState) { // check if the state has changed
+    if (currentState == HIGH) { // check if there is motion
+      digitalWrite(LED, HIGH);  // turn the LED on
+      Serial.println("Motion Detected");
+}
+    else {
+      digitalWrite(LED, LOW);  // turn the LED off
+      Serial.println("No Motion");
+    }
+previousState = currentState; // update the previous state
+  }
+  delay(100); // small delay to avoid false sensor readings
+
+}
+```

docs/development/reference/protobufs.mdx

@@ -5,4 +5,4 @@ title: Protobufs
 
 Protobufs are used by Meshtastic software to send and receive data between App and Device and Device to Device.
 
-Documentation on the Meshtastic Protobuf messages can be fund on the [BSR(Buf Schema Registry)](https://buf.build/meshtastic/protobufs).
+Documentation on the Meshtastic Protobuf messages can be found on the [BSR(Buf Schema Registry)](https://buf.build/meshtastic/protobufs).

docs/development/web/building.mdx

@@ -1,10 +0,0 @@
----
-id: building
-title: Building
-sidebar_label: Building
----
-
-Releases are automatically generated for every commit as per out [CI](https://github.com/meshtastic/web/blob/master/.github/workflows/main.yml). This performs two actions:
-
-1. Generates a perpetually updated [GitHub release](https://github.com/meshtastic/web/releases/tag/latest) with an accompanying `build.tar` that a automatically get's pulled by the firmware CI at build time.
-2. A hosted version is deployed to [client.meshtastic.org](https://client.meshtastic.org).

docs/development/web/index.mdx

@@ -1,100 +1,66 @@
 ---
 id: web-interface
-title: Development Overview of the Web Interface
+title: Web Client Development
-sidebar_label: Web Interface
+sidebar_label: Web Client
 sidebar_position: 4
 ---
 
-## Considerations
+## Overview
 
-We have a total of 458,752 bytes (448KB) available on the SPIFFS (Serial Peripheral Interface Flash File System) -- the on-board storage of the ESP32. Of that space, let's not use more than half of that (224KB) in order to leave space for other uses.
+The Meshtastic web interface can be hosted or served from a node.
 
-Right now, the Meshtastic Device Preferences as well as SSL keys use that space. We can imagine other future uses as well, such as logging chat messages and possibly saving received signal strength with GPS coordinates to create coverage heat maps.
+The official hosted version can be found at [https://client.meshtastic.org](https://client.meshtastic.org).
 
-## Static Files
+The version served from a node can be accessed by first [connecting your node to your network](/docs/settings/config/network) and then navigating to http://meshtastic.local (or your_node_ip.local).
 
-Static files can be placed in the /data folder. All files should be compressed in the .gz format with a .gz extension regardless of the file type.
 
-As an example, this would mean we will have files such as:
+## Development & Building
 
-- style.css.gz
+### Development
-- meshtastic.js.gz
-- meshtasticlogo.png.gz
 
-Unless otherwise stated, files in the `/data` folder of the source code will be stored in `/static` on the device.
+Clone the [Meshtastic Web Repo](https://github.com/meshtastic/web) repository
+   ```shell
+   git clone https://github.com/meshtastic/web.git
+   cd web
+   ```
 
-## Application Interface
+Install the dependencies.
 
-We make extensive use of [Meshtastic.js](https://github.com/meshtastic/meshtastic.js).
+```bash
+pnpm i
+```
+### Building
 
-## Embedded Server
+Build the project:
 
-### Root
+```bash
+pnpm build
+```
 
-When requesting to the root of the web server, the either /static/index.html or /static/index.html.gz will be fetched from the file system and served to the client. We require that the file is in the gzip format. Serving an uncompressed file is not supported. If both index.html and index.html.gz are on the filesystem, index.html will be served and index.html.gz will be ignored.
+Start the development server:
 
-### /static
+```bash
+pnpm dev
+```
 
-All files stored in /data/static in the Meshtastic source code will be available in /static on the Meshtastic device.
+### Packaging
 
-If a file is uploaded in a .gz format, the .gz extension will be stripped prior to being served to the client. Keep your filenames as short as possible. Short filenames work better than long file names.
+Build the project:
 
-An experimental file system browser with upload and delete capability is available by going to either:
+```bash
+pnpm build
+```
 
-- http://meshtastic.local/static
+GZip the output:
-- https://meshtastic.local/static
 
-There are known issues with uploading files with large file sizes.
+```bash
+pnpm package
+```
 
-The current preferred method to upload data is through PlatformIO and the file system browser is provided without guarantees.
 
-### /restart
+## Releases
 
-A post to this location will cause the device to restart.
+Releases are automatically generated for every commit as per out [CI](https://github.com/meshtastic/web/blob/master/.github/workflows/main.yml). This performs two actions:
 
-### /favicon.ico
+1. Generates a perpetually updated [GitHub release](https://github.com/meshtastic/web/releases/tag/latest) with an accompanying `build.tar` that a automatically get's pulled by the firmware CI at build time.
-
+2. A hosted version is deployed to [client.meshtastic.org](https://client.meshtastic.org).
-The Meshtastic logo in .ico format.
-
-### /hotspot-detect.html
-
-Used by the Apple Captive Portal Assistant.
-
-### /upload
-
-Endpoint to upload files. Used by the file manager.
-
-### /json/report
-
-Return a report of airtime statistics and current status.
-
-Formula to calculate when the current time period will roll over:
-
-`data.airtime.seconds_per_period - (data.airtime.seconds_since_boot % data.airtime.seconds_per_period)`
-
-### /json/scanNetworks
-
-Returns a json data structure of WiFi networks in the area. It's recommended to call this at least 2 or 3 times and combine the results.
-
-We purposely exclude open (insecure) networks from the list.
-
-### /json/spiffs/browse/static
-
-Returns a json data structure with the contents of /static.
-
-If a filename includes a '.gz' extension, will also return a modified version of the filename with the extension stripped. This is to support the functionality in /static (see above).
-
-### /json/spiffs/delete/static
-
-Delete file specified by the parameter "delete". Use the method "DELETE".
-
-eg: /json/spiffs/delete/static?delete=static/something.txt
-
-### Performance
-
-As a general guide, the ESP32 will return HTTP requests significantly faster than HTTPS requests. For responses of 1kb or less, expect the following for real world performance:
-
-HTTP - 3.0 requests / sec
-HTTPS - 0.4 requests / sec
-
-The bottleneck of HTTPS is with the SSL handshake. We will get better performance serving one large file rather than multiple small files.

docs/development/web/partitions.mdx

@@ -1,67 +0,0 @@
----
-id: esp32-partitions
-title: Managing ESP32 partitions
-sidebar_label: ESP32 partitions
----
-
-:::caution
-It has been reported that some of this information is out of date. 
-FIXME - Investigate and rewrite document to reflect the current ESP32 Partition mitigation.
-:::
-
-## Insufficient space to upload web interface files
-
-This problem seems to occur when your board has the partitioning structure set incorrectly. This typically occurs when the board has had a firmware other than Meshtastic on it previously. In this situation, the file upload page on the device typically shows a free space of around 48,000 bytes, rather than the ~300,000 bytes that it should have free.
-
-![Meshtastic.local's upload page showing insufficient storage space](/img/insufficient-space.png)
-
-There are a number of methods that essentially involve erasing the flash and then re-uploading the Meshtastic firmware.
-
-## Install Script
-
-The most reliable way to fix this problem is to use the install script that is included in the meshtastic firmware zip. If that doesn’t work, these other methods may work:
-
-## Alternative methods
-
-### Using the Arduino IDE:
-
-https://meshtastic.discourse.group/t/solved-help-installing-with-other-than-esphome-flasher/2214/9
-
-### Using Pio in Windows
-
-```powershell
-pio run --target erase --environment tbeam
-```
-
-Then re-install the firmware ie using ESPHome Flasher.
-
-Requires: [Python](https://www.python.org), [Pio](https://pypi.org/project/pio), command to be run in the root directory of the firmware project once you’ve cloned it (this last requirement is an assumption based on pio not knowing what a tbeam is, may also require Visual Studio Code and PlatformIO as these were installed during use).
-
-### Esptool.py
-
-@1984 posted another method using the python based esptool.py to erase and re-flash the firmware:
-
-```shell
-esptool.py --baud 921600 erase_flash
-esptool.py --baud 921600 write_flash 0x1000 system-info.bin
-esptool.py --baud 921600 write_flash 0x00390000 spiffs-*.bin
-esptool.py --baud 921600 write_flash 0x10000 firmware-tbeam-EU865-1.1.42.bin
-```
-
-Requires: [Python](https://www.python.org) and [esptool.py](https://github.com/espressif/esptool)
-
-### Visual Studio & PlatformIO
-
-There is also the method of using the Visual Studio IDE. This requires having Visual Studio and PlatformIO installed, along with having cloned the firmware code as per the [build instructions](/docs/development/firmware/build). After loading the project in Visual Studio, select the PlatformIO alien icon, then find the appropriate device, and then click the Erase Flash command.
-
-![Erasing the flash using PlatformIO in Visual Studio Code](/img/platformio-erase.png)
-
-https://meshtastic.discourse.group/t/configuring-channel-via-python-api/1948/17
-
-Requires: [Visual Studio Code](https://code.visualstudio.com), [PlatformIO](https://platformio.org), cloned copy of the Meshtastic Firmware project
-
-## How do I know it's worked?
-
-Once it has been successfully erased and re-flashed, visiting https://192.168.42.1/static should leave you with free space on the order of 300,000 bytes, rather than the ~48,000 bytes you currently have. You can then upload the files from the meshtastic web release.
-
-Occasionally, this may glitch may appear when uploading the larger app.js.gz file, but a further erase and flash typically solves this.

docs/getting-started/flashing-firmware/nrf52/ota.mdx

@@ -8,7 +8,7 @@ sidebar_position: 2
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-nRF52 devices are able to accept OTA firmware updates from a mobile device over bluetooth.
+nRF52 devices from RAK are able to accept OTA firmware updates from a mobile device over bluetooth. The T-Echo bootloader does not have OTA support.
 
 <Tabs
 groupId="settings"
@@ -21,7 +21,7 @@ values={[
 <TabItem value="android">
 
 :::info
-As of this writing, the current Android release of the nRF DFU app (v2.3.0) is not compatible with Meshtastic firmware updates.
+As of this writing, the current Android release of the nRF DFU app (v2.3.0) is not compatible with Meshtastic firmware updates. Please use the instructions below for updating via OTA with the nRF Connect App.
 :::
 
 OTA firmware updates are available for Android using an older release of the more advanced nRF Connect App __version 4.24.3__ which is available for download from the [Nordic Semiconductor GitHub page](https://github.com/NordicSemiconductor/Android-nRF-Connect/releases/tag/v4.24.3).

docs/hardware/antennas/antenna-report.mdx

@@ -7,6 +7,6 @@ sidebar_position: 2
 
 ## RicInNewMexico
 
-[_RicInNewMexico_](https://github.com/RicInNewMexico) has gone through the trouble of testing a number of commonly purchased antennas in the Meshtastic community and given an opinion on whether or not a given antenna is performing optimally.
+[_RicInNewMexico_](https://github.com/RicInNewMexico) and others have gone through the trouble of testing a number of commonly purchased antennas in the Meshtastic community and given an opinion on whether or not a given antenna is performing optimally.
 
 Please check out the project on Github: [Meshtastic-Antenna-Reports](https://github.com/RicInNewMexico/Meshtastic-Antenna-Reports)

docs/hardware/antennas/lora-antennas.mdx

@@ -17,7 +17,7 @@ The antenna's design will affect:
 - Amount of signal which is reflected back to the device itself
 
 :::caution
-While the LoRa devices we use for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an antenna or with a poorly matched antenna. Un-transmitted radio signal reflected back to the transmitter can damage the device.
+While the LoRa devices we use for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an antenna or with a poorly matched antenna. Radio signals transmitted without an antenna can reflect back and damage the device.
 :::
 
 <object data="https://www.youtube.com/embed/V3f-Y3EfsBU?autohide=1&autoplay=0" width="100%" height="400"></object>

docs/hardware/antennas/testing.mdx

@@ -27,7 +27,7 @@ Some understanding of the factors affecting radio communications will help achie
 The Meshtastic devices (of various flavors) lend themselves to experimentation, not only because you can replace their aerials, but also because of their mesh operation. All nodes will, without alteration, relay communications from any other members of the mesh around obstacles and over greater distances. The cost of aerial investment should be weighed against investment in additional low-cost nodes.
 
 :::caution
-While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Un-transmitted radio signal reflected back to the transmitter can damage the device.
+While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial. Radio signals transmitted without an antenna can reflect back and damage the device.
 :::
 
 The information collected here is by no means definitive, and necessarily abbreviated (it's a huge topic).
@@ -72,7 +72,7 @@ Unless you're using your devices in a vacuum, with clear line of sight between a
 - Absorption by materials (with varying degrees attenuation, by material and depth),
 - Reflection off surfaces (and channeling through material tunnels, including warm / cold air tunnels commonly present in the atmosphere),
 - Diffraction around obstacles (over forests and around corners).
-- [Fresnel Zone](They may not have been selected for your given frequency range, tuned or of a quality design.) - Football shape between antennas that must be clear of obstructions or else the signal is attenuated.
+- Fresnel Zone - A football shape between antennas that must be clear of obstructions or else the signal is attenuated.
 
 ### Environmental Factors
 

docs/hardware/devices/heltec/index.mdx

@@ -126,7 +126,7 @@ Not recommended because of design issues! Support is being phased out. Use V3 in
 ## Resources
 
 - Firmware file: `firmware-heltec-v3-X.X.X.xxxxxxx.bin`
-- Purchase link: [AliExpress](https://www.aliexpress.com/item/1005004970848837.html)
+- Purchase link: [AliExpress](https://www.aliexpress.us/item/3256805256690400.html)
 
 </TabItem>
 <TabItem value="Wireless Stick Lite V3">
@@ -163,7 +163,7 @@ Image Source: [Heltec](https://resource.heltec.cn/download/Wireless_Stick_Lite_V
 ## Resources
 
 - Firmware file: `firmware-heltec-wsl-v3-X.X.X.xxxxxxx.bin`
-- Purchase link: [AliExpress](https://www.aliexpress.com/item/1005004839521502.html)
+- Purchase link: [AliExpress](https://www.aliexpress.us/item/3256805256996507.html)
 
 </TabItem>
 </Tabs>

docs/hardware/devices/lora/index.mdx

@@ -84,7 +84,6 @@ This board is still in production but for various reasons not recommended for ne
 
 - Firmware file: `firmware-tlora_v1_3-X.X.X.xxxxxxx.bin`
 - Purchase link: [AliExpress](https://www.aliexpress.com/item/4000628100802.html)
-- US Distributor - Purchase link: [Rokland](https://store.rokland.com/products/lilygo-lora-v1-3-esp32-sx1276-915mhz-wifi-wireless-bluetooth-module-0-96-inch-oled-screen-support-arduino-development-board-q312?ref=8Bb2mUO5i-jKwt)
 
 ![LILYGO® TTGO Lora V1.3](/img/hardware/lora-v1.3.png)
 ![LILYGO® TTGO Lora V1.3 pin map](/img/hardware/lora-v1.3_pinmap.webp)
@@ -190,7 +189,6 @@ Early versions of some of these boards contained the wrong component in the LiPo
 ## Resources
 
 - Firmware file: `firmware-tlora-v2-1-1.8-X.X.X.xxxxxxx.bin`
-- Purchase link: [Banggood](https://www.banggood.com/LILYGO-LORA-H570-V1_8-SX1280-ESP32-2_4G-Smart-WiFi-bluetooth-Wireless-Module-0_96inch-OLED-Display-Development-Board-with-Antenna-Type-C-p-1969395.html)
 
 ![TTGO Lora V2.1-1.8](/img/hardware/lora-v2.1-1.8.jpg)
 

docs/hardware/devices/nano-g1-explorer/index.mdx

@@ -35,7 +35,7 @@ The Nano G1 Explorer, powered by Meshtastic, is a significant upgrade from the N
 
 ### Resources
 
-- Firmware file: `firmware-nano-g1-explorer-x.x.x.bin`
+- Firmware file: `firmware-nano-g1-explorer-X.X.X.xxxxxxx.bin`
 - Official Purchase Links:
   - [Official Store](https://shop.uniteng.com/product/meshtastic-mesh-device-nano-edition/)
   - [Official Tindie Store](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-nano-g1-explorer/)

docs/hardware/devices/nano-g1/index.mdx

@@ -33,8 +33,7 @@ The Nano G1 is the first dedicated hardware device to be designed from scratch p
 
 ### Resources
 
-- Firmware file: `firmware-nano-g1-1.x.x.bin`
+- Firmware file: `firmware-nano-g1-X.X.X.xxxxxxx.bin`
-- [Purchase link](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-nano-edition/)
 
 Further information on the Nano G1 can be found on [Unit Engineering's Wiki](https://uniteng.com/wiki/doku.php?id=meshtastic:nano).
 

docs/hardware/devices/rak/screens.mdx

@@ -43,7 +43,7 @@ The [RAK1400 EPD module](https://store.rakwireless.com/products/wisblock-epd-mod
 - Resolution 212 x 104 pixels
 - Occupies the IO Port of a Wisblock Base
 
-- Firmware for 5005 with RAK14000 e-paper: [`firmware-rak4631_eink-1.3.x.uf2`](/downloads)
+- Firmware for 5005 with RAK14000 e-paper: [`firmware-rak4631_eink-X.X.X.xxxxxxx.uf2`](/downloads)
 
   <img
     alt="RAK4631 5005 14000"

docs/hardware/devices/station-g1/index.mdx

@@ -35,8 +35,12 @@ The Station G1 is the second dedicated hardware device to be designed from scrat
 
 ### Resources
 
-- Firmware file: `firmware-station-g1-1.x.x.bin`
+- Firmware file: `firmware-station-g1-X.X.X.xxxxxxx.bin`
-- [Purchase link](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-station-edition/)
+- [Official Store](https://shop.uniteng.com/product/meshtastic-mesh-device-station-edition/)
+- [Official Tindie Store](https://www.tindie.com/products/neilhao/meshtastic-mesh-device-station-edition/)
+
+
+
 
 Further information on the Station G1 can be found on [Unit Engineering's Wiki](https://uniteng.com/wiki/doku.php?id=meshtastic:station).
 

docs/legal/trademark-grants.mdx

@@ -22,3 +22,5 @@ sidebar_label: Trademark Grants
   - Details: Paul primarily designs enclosures and assembles complete Meshtastic Radios for sale using modules from TTGO, Heltec and RAK. He  runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and M logos. The use of the Meshtastic Logo and Trademarks does not imply Paul is sponsored or endorsed by Meshtastic. Paul also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
 - Grant: [Keith Monaghan](http://voltaicenclosures.com/)
    - Details: Keith is a contributer of computer aided design (CAD)/3D designs primarily for device enclosures and accessories, and runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Keith is sponsored or endorsed by Meshtastic. Keith also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.
+- Grant: [Neil Hao](https://shop.uniteng.com/)
+   - Details: Neil is a contributer of hardware designs, and runs an online shop for Meshtastic powered devices which carry the "Meshtastic" and "M" logos. The use of the Meshtastic Logo and Trademarks does not imply Neil is sponsored or endorsed by Meshtastic. Neil also agrees to maintain compliance with the Meshtastic Legal requirements. This grant is revokable at any time for any reason.

docs/software/mqtt/index.mdx

@@ -17,22 +17,29 @@ You can find the settings available for MQTT [here](/docs/settings/moduleconfig/
 
 Using or emitting packets directly in/from smart home control software such as Home Assistant or other consumers that can work with JSON messages.
 
-When MQTT is enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf packet that it sees to the MQTT broker. In addition, some packet types are serialized or deserialized from/to JSON messages for easier use in consumers. All packets are sent to the broker, whether they originate from another device on the mesh, or the gateway node itself.
+When MQTT is enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf MeshPacket that it sees to the MQTT broker, encapsulated in a [ServiceEnvelope protobuf](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.ServiceEnvelope). In addition, some packet types are serialized or deserialized from/to JSON messages for easier use in consumers. All packets are sent to the broker, whether they originate from another device on the mesh, or the gateway node itself.
 
 Packets may be encrypted. If you use the default meshtastic MQTT server, packets are always encrypted. If you use a custom MQTT broker (ie set `mqtt.address`), the `mqtt.encryption_enabled` setting applies, which by default is false.
 
 IMPORTANT: When MQTT is turned on, you are potentially broadcasting your entire mesh traffic onto the public internet. This includes messages and position information.
 
-### MQTT Topics
+### MQTT [Topics](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices)
 
-The device will uplink and downlink raw ([protobuf](https://developers.google.com/protocol-buffers)) packets to the `msh/` prefix:
+If no specific [root topic](/docs/settings/moduleconfig/mqtt#root-topic) is configured, the default root topic will be `msh/`.
+Each device that is connected to MQTT will publish its MQTT state ("`online`"/"`offline`") to:
 
-`msh/2/c/ShortFast/!12345678` where
+`msh/2/stat/USERID`, where `USERID` is the user ID of the gateway device (the one connected to MQTT).
 
-- `!12345678` is the address of the gateway device.
+For each channel where uplink and/or downlink is enabled two other topics might be used.
-- `ShortFast` is the channel name.
 
-The payload is a raw protobuf. Looking at the MQTT traffic with a program like `mosquitto_sub` will tell you it's working, but you won't get much useful information out of it. For example:
+#### Protobufs topic
+A gateway node will uplink and/or downlink raw ([protobuf](https://developers.google.com/protocol-buffers)) MeshPackets to the topic:
+
+`msh/2/c/CHANNELNAME/USERID`, where `CHANNELNAME` is the name of the channel.
+
+For example: `msh/2/c/LongFast/!abcd1234`
+
+The payload is a raw protobuf, whose definitions for Meshtastic can be found [here](https://github.com/meshtastic/protobufs/blob/master/meshtastic). Reference guides for working with protobufs in several popular programming languages can be found [here](https://protobuf.dev/reference/). Looking at the MQTT traffic with a program like `mosquitto_sub` will tell you it's working, but you won't get much useful information out of it. For example:
 
 ```text
 苓????"!
@@ -40,7 +47,12 @@ The payload is a raw protobuf. Looking at the MQTT traffic with a program like `
 	ShortFast	!937bed1c
 ```
 
-Packets from the following [port numbers](/docs/development/firmware/portnum) are serialized to JSON and then forwarded to the `msh/2/json/CHANNELID/DEVICEID` topic: `TEXT_MESSAGE_APP`, `ENVIRONMENTAL_MEASUREMENT_APP`, `NODEINFO_APP` and `POSITION_APP`.
+If [encryption_enabled](/docs/settings/moduleconfig/mqtt#encryption-enabled) is set to true, the payload of the MeshPacket will remain encrypted with the key for the specified channel.
+
+#### JSON topic
+If [JSON is enabled](/docs/settings/moduleconfig/mqtt/#json-enabled), packets from the following [port numbers](/docs/development/firmware/portnum) are serialized to JSON: `TEXT_MESSAGE_APP`, `ENVIRONMENTAL_MEASUREMENT_APP`, `NODEINFO_APP` and `POSITION_APP`. These are then forwarded to the topic: 
+
+`msh/2/json/CHANNELNAME/USERID`.
 
 An example of a received `NODEINFO_APP` message:
 
@@ -62,6 +74,22 @@ An example of a received `NODEINFO_APP` message:
 }
 ```
 
+The meaning of these fields is as follows:
+
+- "`id`" is the unique ID for this message. 
+- "`channel`" is the channel index this message was received on.
+- "`from`" is the unique node number of the node on the mesh that sent this message, represented as a signed decimal number.
+- "`id`" inside the payload of a `NODEINFO_APP` message is the user ID of the node that sent it, which is currently just the hexadecimal representation of the node number. 
+- "`hardware`" is the [hardware model](https://github.com/meshtastic/protobufs/blob/master/meshtastic/mesh.proto#L215) of the node sending the `NODEINFO_APP` message.
+- "`longname`" is the long name of the device that sent the `NODEINFO_APP` message.
+- "`shortname`" is the short name of the device that sent the `NODEINFO_APP` message.
+- "`sender`" is the user ID of the gateway device, which is in this case the same node that sent the `NODEINFO_APP` message (the hexadecimal value `7efeee00` represented by an integer in decimal is `2130636288`). 
+- "`timestamp`" is the Unix Epoch when the message was received, represented as an integer in decimal.
+- "`to`" is the node number of the destination of the message. In this case, "-1" means it was a broadcast message (this is the decimal integer representation of `0xFFFFFFFF`). 
+- "`type`" is the type of the message, in this case it was a `NODEINFO_APP` message.
+
+The "from" field can thus be used as a stable identifier for a specific node. Note that (like the "`id`" and "`to`" fields) in JSON this is a signed value, whereas in protobufs it is unsigned.
+
 If the message received contains valid JSON in the payload, the JSON is deserialized and added as a JSON object rather than a string containing the serialized JSON.
 
 **Sent messages** will be checked if the MQTT payload contains a valid JSON-encoded envelope:
@@ -90,34 +118,6 @@ Check out [MQTT Settings](/docs/settings/moduleconfig/mqtt) for full information
 `uplink_enabled` will tell the device to publish mesh packets to MQTT.
 `downlink_enabled` will tell the device to subscribe to MQTT, and forward any packets from there onto the mesh.
 
-### Topics
-
-The "mesh/crypt/CHANNELID/NODEID/PORTID" [topic](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices) will be used for messages sent from/to a mesh.
-
-Gateway nodes will forward any MeshPacket from a local mesh channel with uplink_enabled. The packet (encapsulated in a ServiceEnvelope) will remain encrypted with the key for the specified channel.
-
-For any channels in the local node with downlink_enabled, the gateway node will forward packets from MQTT to the local mesh. It will do this by subscribing to mesh/crypt/CHANNELID/# and forwarding relevant packets.
-
-If the channelid 'well known'/public it could be decrypted by a web service (if the web service was provided with the associated channel key), in which case it will be decrypted by a web service and appear at "mesh/clear/CHANNELID/NODEID/PORTID". Note: This is not in the initial deliverable.
-
-#### Service Envelope
-
-The payload published on mesh/... will always be wrapped in a [ServiceEnvelope protobuf](https://buf.build/meshtastic/protobufs/docs/main:meshtastic#meshtastic.ServiceEnvelope).
-
-ServiceEnvelope will include the message, and full information about arrival time, who forwarded it, source channel, source mesh id, etc...
-
-#### NODEID
-
-The unique ID for a node. A hex string that starts with an ! symbol.
-
-#### USERID
-
-A user ID string. This string is either a user ID if known or a nodeid to simply deliver the message to whoever the local user is of a particular device (i.e. person who might see the screen). FIXME, see what riot.im uses and perhaps use that convention? Or use the signal +phone number convention? Or the email address?
-
-#### CHANNELID
-
-FIXME, figure out how channelids work
-
 ### Gateway nodes
 
 Any meshtastic node that has a direct connection to the internet (either via a helper app or installed WiFi/4G/satellite hardware) can function as a "Gateway node".