From 7f56825c4069c4248ec2afb651911d9f7a897b73 Mon Sep 17 00:00:00 2001 From: Sacha Weatherstone Date: Wed, 9 Mar 2022 18:10:41 +1100 Subject: [PATCH] Simplify build instrucions and rename plugins. --- .../documentation-change-request.md | 17 +- docs/about/concepts/channels.md | 3 +- docs/about/concepts/external-devices.md | 23 +- docs/about/concepts/internet.md | 3 +- docs/about/concepts/mesh.md | 5 +- docs/developers/android/build.md | 20 +- docs/developers/build.md | 90 +---- docs/developers/device/device-api.md | 2 +- docs/developers/device/encryption.md | 6 +- docs/developers/device/mesh-alg.md | 60 ++-- .../device/{plugin-api.md => module-api.md} | 40 +-- docs/developers/overview.md | 38 ++- docs/faq/bluetooth.md | 3 +- docs/faq/client-ios.md | 3 +- docs/faq/device.md | 7 +- docs/faq/faq.md | 4 +- docs/faq/modules.md | 18 + docs/faq/plugins.md | 18 - docs/getting-started/flashing-esp32.md | 10 +- docs/hardware/antenna/resources.md | 45 ++- docs/hardware/antenna/testing.md | 10 +- docs/hardware/supported/heltec.md | 2 +- docs/legal/privacy.md | 6 +- ...age-plugin.md => canned-message-module.md} | 184 ++++++----- ....md => environmental-measurment-module.md} | 293 +++++++++-------- ...gin.md => external-notification-module.md} | 197 ++++++----- docs/settings/mqtt.md | 311 ++++++++++-------- ...ge-test-plugin.md => range-test-module.md} | 146 ++++---- ...der-plugin.md => rotary-encoder-module.md} | 292 ++++++++-------- .../{serial-plugin.md => serial-module.md} | 193 +++++------ ...-plugin.md => store-and-forward-module.md} | 237 ++++++------- docs/software/android/installation.md | 5 +- docs/software/android/location-access.md | 36 +- docs/software/android/usage.md | 28 +- docs/software/community/atak.md | 21 +- docs/software/community/overview.md | 4 +- docs/software/device/remote-admin.md | 4 +- .../device/remote-hardware-service.md | 53 +-- docs/software/js/connecting.md | 27 +- docs/software/js/getting-started.md | 2 +- .../{plugins => modules}/canned-message.md | 75 ++--- docs/software/modules/environment.md | 222 +++++++++++++ .../external-notifications.md | 62 ++-- .../plugin-api.md => modules/module-api.md} | 0 .../plugins.md => modules/modules.md} | 10 +- .../{plugins => modules}/range-test.md | 104 +++--- docs/software/modules/serial.md | 40 +++ docs/software/modules/store-forward.md | 213 ++++++++++++ docs/software/other/build-instructions.md | 2 +- docs/software/other/install-OSX.md | 2 +- docs/software/other/mqtt.md | 68 ++-- docs/software/other/sw-design.md | 2 +- docs/software/overview.md | 16 +- docs/software/plugins/environment.md | 215 ------------ docs/software/plugins/serial.md | 40 --- docs/software/plugins/store-forward.md | 214 ------------ docs/software/python/installation.md | 261 ++++++++------- docs/software/python/uses.md | 2 +- docs/software/web/overview.md | 12 +- docs/software/web/partitions.md | 12 +- sidebars.js | 107 +++--- src/pages/downloads/index.tsx | 59 +++- .../store_and_forward-overview.png | Bin 63 files changed, 2161 insertions(+), 2043 deletions(-) rename docs/developers/device/{plugin-api.md => module-api.md} (69%) create mode 100644 docs/faq/modules.md delete mode 100644 docs/faq/plugins.md rename docs/settings/{canned-message-plugin.md => canned-message-module.md} (52%) rename docs/settings/{environmental-measurment-plugin.md => environmental-measurment-module.md} (56%) rename docs/settings/{external-notification-plugin.md => external-notification-module.md} (65%) rename docs/settings/{range-test-plugin.md => range-test-module.md} (71%) rename docs/settings/{rotary-encoder-plugin.md => rotary-encoder-module.md} (63%) rename docs/settings/{serial-plugin.md => serial-module.md} (65%) rename docs/settings/{store-and-forward-plugin.md => store-and-forward-module.md} (56%) rename docs/software/{plugins => modules}/canned-message.md (70%) create mode 100644 docs/software/modules/environment.md rename docs/software/{plugins => modules}/external-notifications.md (65%) rename docs/software/{plugins/plugin-api.md => modules/module-api.md} (100%) rename docs/software/{plugins/plugins.md => modules/modules.md} (74%) rename docs/software/{plugins => modules}/range-test.md (56%) create mode 100644 docs/software/modules/serial.md create mode 100644 docs/software/modules/store-forward.md delete mode 100644 docs/software/plugins/environment.md delete mode 100644 docs/software/plugins/serial.md delete mode 100644 docs/software/plugins/store-forward.md rename static/img/{plugins => modules}/store_and_forward/store_and_forward-overview.png (100%) diff --git a/.github/ISSUE_TEMPLATE/documentation-change-request.md b/.github/ISSUE_TEMPLATE/documentation-change-request.md index a3eeb2f2..c717229e 100644 --- a/.github/ISSUE_TEMPLATE/documentation-change-request.md +++ b/.github/ISSUE_TEMPLATE/documentation-change-request.md @@ -1,20 +1,19 @@ --- name: Documentation Change Request about: Create a report about our documentation to help us improve -title: 'Documentation Change Request' -labels: '' -assignees: '' - +title: "Documentation Change Request" +labels: "" +assignees: "" --- -Please - if you just have a question, post in our [forum](https://meshtastic.discourse.group/) instead. Please reserve this system for requesting changes to the Meshtastic documentation. +Please - if you just have a question, post in our [forum](https://meshtastic.discourse.group) instead. Please reserve this system for requesting changes to the Meshtastic documentation. **Describe what section of the docs is outdated or otherwise in need of change** -Be as clear and concise as possible. Provide a URL or GitHub path to the doc you are referencing. +Be as clear and concise as possible. Provide a URL or GitHub path to the doc you are referencing. **Suggested Changes** -What specifically in that documentation area needs to be changed / removed / added? -If possible provide replacement text when requesting changes or new text to fill in missing documentation. +What specifically in that documentation area needs to be changed / removed / added? +If possible provide replacement text when requesting changes or new text to fill in missing documentation. **Additional Notes** -Add any other context here. \ No newline at end of file +Add any other context here. diff --git a/docs/about/concepts/channels.md b/docs/about/concepts/channels.md index 9371b756..bac828ad 100644 --- a/docs/about/concepts/channels.md +++ b/docs/about/concepts/channels.md @@ -3,9 +3,10 @@ id: channels title: Channels sidebar_label: Channels --- + ## Overview -Meshtastic Channels: Can create a *somewhat* secure method of communication on the same mesh network. The channel can be encrypted to prevent normal people from listening in on the traffic. But, it could probably be easily [cracked](https://crypto.stackexchange.com/questions/46559/what-are-the-chances-that-aes-256-encryption-is-cracked) by determined individuals. See [Channel Config](https://meshtastic.org/docs/software/settings/channel) for more info. It is also possible that your location could be triangulated by determined individuals. +Meshtastic Channels: Can create a _somewhat_ secure method of communication on the same mesh network. The channel can be encrypted to prevent normal people from listening in on the traffic. But, it could probably be easily [cracked](https://crypto.stackexchange.com/questions/46559/what-are-the-chances-that-aes-256-encryption-is-cracked) by determined individuals. See [Channel Config](/docs/software/settings/channel) for more info. It is also possible that your location could be triangulated by determined individuals. ## Channels diff --git a/docs/about/concepts/external-devices.md b/docs/about/concepts/external-devices.md index 6365fa3a..6c69b74e 100644 --- a/docs/about/concepts/external-devices.md +++ b/docs/about/concepts/external-devices.md @@ -3,32 +3,33 @@ id: external-devices title: External Devices sidebar_label: External Devices --- + ## Overview -External hardware can be connected to your device using a GPIO (General Purpose Input/Output) interface. Using GPIO, you are able to connect external buttons, circuits, rotary encoders, environmental sensors and more. Many of our plugins offer solutions to implement additional functionality. +External hardware can be connected to your device using a GPIO (General Purpose Input/Output) interface. Using GPIO, you are able to connect external buttons, circuits, rotary encoders, environmental sensors and more. Many of our modules offer solutions to implement additional functionality. Soldering is likely required when attaching items to your device, so practice your skills elsewhere before trying on your radio. If you're not careful or don't know what your doing, you can damage your hardware. ## Features using External Devices -Many of our plugins require external hardware to be attached to the device. +Many of our modules require external hardware to be attached to the device. -### Canned Message Plugin +### Canned Message Module -Requires use of the [rotary encoder plugin](#rotary-encoder-plugin). The rotary encoder acts as an input to select one of up to 50 customizable messages. This way you can send canned messages without needing to pair your device to a phone. +Requires use of the [rotary encoder module](#rotary-encoder-module). The rotary encoder acts as an input to select one of up to 50 customizable messages. This way you can send canned messages without needing to pair your device to a phone. -### Environmental Measurment Plugin +### Environmental Measurement Module -Broadcast environmental measurments to your mesh! Temperature, Humidity, Pressure, & VOC Gas are all options that are currently available with the supported sensors. +Broadcast environmental measurements to your mesh! Temperature, Humidity, Pressure, & VOC Gas are all options that are currently available with the supported sensors. -### External Notifications Plugin +### External Notifications Module Use lights, buzzers, or speakers to alert you of incoming messages. -### Rotary Encoder Plugin +### Rotary Encoder Module -Currently used only for the [canned message plugin](#canned-message-plugin), this plugin allows you to connect a rotary encoder to be used as an additional input to the device. +Currently used only for the [canned message module](#canned-message-module), this module allows you to connect a rotary encoder to be used as an additional input to the device. -### Serial Plugin +### Serial Module -Available for ESP32 based devices, the serial plugin allows you to send messages over the mesh by sending strings over a serial port. +Available for ESP32 based devices, the serial moduleallows you to send messages over the mesh by sending strings over a serial port. diff --git a/docs/about/concepts/internet.md b/docs/about/concepts/internet.md index 6fab9fed..83f4e0c2 100644 --- a/docs/about/concepts/internet.md +++ b/docs/about/concepts/internet.md @@ -3,9 +3,10 @@ id: internet title: Internet Connectivity sidebar_label: Internet Connectivity --- + ## Overview -Captive Portal: Using Meshtastic, you can create a separate Wifi network for you join your phone or computer on a mesh network. See [Web Interface](https://meshtastic.org/docs/software/web/web-app-software) for more info. This is ideal in a situation where you are remote, such as in the forest, on a mountain, or if there is a major power/internet outage such as in a storm or other disaster. +Captive Portal: Using Meshtastic, you can create a separate Wifi network for you join your phone or computer on a mesh network. See [Web Interface](/docs/software/web/web-app-software) for more info. This is ideal in a situation where you are remote, such as in the forest, on a mountain, or if there is a major power/internet outage such as in a storm or other disaster. ## Features using Internet Connectivity diff --git a/docs/about/concepts/mesh.md b/docs/about/concepts/mesh.md index eb122d0f..dce417d8 100644 --- a/docs/about/concepts/mesh.md +++ b/docs/about/concepts/mesh.md @@ -3,10 +3,11 @@ id: mesh title: Mesh Routing sidebar_label: Mesh Routing --- + ## Overview -Mesh Networking: An interconnected network by using [low-power radios](https://meshtastic.org/docs/hardware) to connect other low-power radios using LoRa to be able to send and receive messages and data. This can be completely separate from any other networks such as the internet. You can start small and get two devices to start experimenting. Do not expect to stream music or videos as LoRa is intended for smaller, lower bandwidth type uses such as text communication. - +Mesh Networking: An interconnected network by using [low-power radios](/docs/hardware) to connect other low-power radios using LoRa to be able to send and receive messages and data. This can be completely separate from any other networks such as the internet. You can start small and get two devices to start experimenting. Do not expect to stream music or videos as LoRa is intended for smaller, lower bandwidth type uses such as text communication. + ## Devices ## Routers diff --git a/docs/developers/android/build.md b/docs/developers/android/build.md index 92f1ad29..60a19b14 100644 --- a/docs/developers/android/build.md +++ b/docs/developers/android/build.md @@ -6,11 +6,11 @@ sidebar_label: Building Android App ## Build instructions -If you would like to develop this application we'd love your help! These build instructions are brief and should be improved, please send a PR if you can. +If you would like to develop this application we'd love your help! These build instructions are brief and should be improved, please send a PR if you can. -* Use Android Studio 4.1.2 to build/debug (other versions might work but no promises) -* Use `git submodule update --init --recursive` to pull in the various submodules we depend on -* There are a few config files which you'll need to copy from templates included in the project. Run the following commands to do so: +- Use Android Studio 4.1.2 to build/debug (other versions might work but no promises) +- Use `git submodule update --init --recursive` to pull in the various submodules we depend on +- There are a few config files which you'll need to copy from templates included in the project. Run the following commands to do so: ``` rm ./app/google-services.json @@ -21,13 +21,14 @@ If you would like to develop this application we'd love your help! These build cp ./app/special/curfirmwareversion.xml ./app/src/main/res/values/ ``` -* (Unfortunately) you need to get a (free) mapbox developer token [here](https://docs.mapbox.com/android/maps/guides/install/) and put that token in your user gradle.properties. +- (Unfortunately) you need to get a (free) mapbox developer token [here](https://docs.mapbox.com/android/maps/guides/install) and put that token in your user gradle.properties. + ``` ~/development/meshtastic/MeshUtil$ cat ~/.gradle/gradle.properties MAPBOX_DOWNLOADS_TOKEN=sk.yourtokenherexxx ``` -* Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator. +- Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator. :::note The emulators don't support Bluetooth, so some features can not be used in that environment. @@ -35,8 +36,8 @@ The emulators don't support Bluetooth, so some features can not be used in that ## Analytics setup -* Analytics are included but can be disabled by the user on the settings screen -* On dev devices +- Analytics are included but can be disabled by the user on the settings screen +- On dev devices ```shell adb shell setprop debug.firebase.analytics.app com.geeksville.mesh @@ -44,10 +45,11 @@ adb shell setprop log.tag.FirebaseCrashlytics DEBUG ``` for verbose logging: + ```shell adb shell setprop log.tag.FA VERBOSE ``` ## Publishing to google play -* Only supported if you are a core developer that needs to do releases +- Only supported if you are a core developer that needs to do releases diff --git a/docs/developers/build.md b/docs/developers/build.md index 72dced56..e86fdcfd 100644 --- a/docs/developers/build.md +++ b/docs/developers/build.md @@ -1,88 +1,20 @@ --- id: build-env -title: Creating a build/development environment +title: Creating a build environment sidebar_label: Building Meshtastic --- -This project uses the simple PlatformIO build system. PlatformIO is an extension to Microsoft VSCode. +Meshtastic uses the [PlatformIO](https://platformio.org) development environment, that enables easy multiplatform development and centralized tooling. -## GUI Installation +## Setup -1. Install [Python](https://www.python.org/downloads/). -2. Install [Git](https://git-scm.com/downloads) or [GitHub Desktop](https://desktop.github.com/) -3. Install [Microsoft Visual Studio Code](https://code.visualstudio.com/) -4. Install [PlatformIO](https://platformio.org/platformio-ide). -5. Click the PlatformIO icon on the side bar. - ![platformio icon](https://user-images.githubusercontent.com/47490997/89482668-77c7ea00-d7ee-11ea-8785-5faf8ff99800.png) -6. Under `Quick Access, Miscellaneous, Clone Git Project` enter the URL of the Meshtastic repo found [here](https://github.com/meshtastic/Meshtastic-device). - ![image](https://user-images.githubusercontent.com/47490997/89483047-4c91ca80-d7ef-11ea-91f4-1d53d4e8acd9.png) -7. Select a file location to save the repo. -8. Once loaded, open the `platformio.ini` file. -9. At the line `default_envs` you can change it to the board type you are building for ie. `tlora-v2, tlora-v1, tlora-v2-1-1.6, tbeam, heltec, tbeam0.7` (boards are listed further down in the file). -10. The hardware can be configured for different countries by adding a definition to the `configuration.h` file. `#define HW_VERSION_US` or `HW_VERSION_EU433, HW_VERSION_EU865, HW_VERSION_CN, HW_VERSION_JP`. Other country settings can be found in `MeshRadio.h`. The default is `HW_VERSION_US`. -11. Click the PlatformIO icon on the side bar. Under `Project Tasks` you can now build or upload. +1. Install PlatformIO, following the instructions available [here](https://platformio.org/platformio-ide). +2. Clone the `meshtastic-device` repository located [here](https://github.com/meshtastic/meshtastic-device). ([Instructions on cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)) +3. Some utilities and scripts use the Python programming language, Downloads available [here](https://www.python.org/downloads). -:::note -To get a clean build you may have to delete the auto-generated file `./.vscode/c_cpp_properties.json`, close and re-open Visual Studio and WAIT until the file is auto-generated before compiling again. -::: +## Building -## Manual Installation on Linux -1. On a Linux distro (like Ubuntu), ensure you have pre-requisites installed: - -``` -sudo apt-get update -sudo apt-get install python3 python3-dev g++ zip -``` - -2. Install PlatformIO (which is usually via wget/curl command). - -``` -wget https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -O get-platformio.py -chmod +x get-platformio.py -python3 get-platformio.py -``` - -3. Clone the repo https://github.com/meshtastic/Meshtastic-device - -4. Change into the Meshtastic-device and then download submodules - -``` -cd Meshtastic-device -git submodule update --init --recursive -``` - -Note: If you get an error like this: - -``` -Compiling .pio/build/rak4631_5005/src/plugins/PositionPlugin.cpp.o -src/nrf52/NRF52CryptoEngine.cpp:3:10: fatal error: ocrypto_aes_ctr.h: No such file or directory -``` - -then you need to run that submodule command from the main Meshtastic-device directory. - - -5. Activate the Platformio python virtual environment - -``` -source ~/.platformio/penv/bin/activate -``` - -6. Build everything (optionally just build what you really need by editing platformio.ini) - -``` -./bin/build-all.sh -``` - -7. See the newly built bits in release/archive/firmware-1.2.49.XXX.zip (where XXX is the git commit) - -## Running the Native environment on Linux - -(From @caveman99 ) - -- linux. flavour doesn't matter. in my case it Centos stream. -- pio run -e native -- then cd .pio/build/native -- gdb program -- on the gdb prompt, execute "run" -- if it eventually coredumps it returns to the gdb prompt, then run bt for a backtrace. -- the actual name of the binary is 'program' +1. Open the newly cloned folder in [Visual Studio Code](https://code.visualstudio.com). +1. To select the device you you wish to build for, first open your [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (`Ctrl + Shift + P`) and enter: `platformio: Switch Project Environment` and select your target. +1. To build the firmware, simply run `PlatformIO: Build` from your command palette. +1. Finally flashing the firmware to your device is as easy as running `PlatformIO: Upload` diff --git a/docs/developers/device/device-api.md b/docs/developers/device/device-api.md index 8c632b71..affe865a 100644 --- a/docs/developers/device/device-api.md +++ b/docs/developers/device/device-api.md @@ -4,7 +4,7 @@ title: Bluetooth/serial/TCP protocol API sidebar_label: Device API --- -This document describes the protocol for external API clients using our devices. If you are interested in running your own code on the device itself, see the [plugin API](plugin-api.md) documentation instead. +This document describes the protocol for external API clients using our devices. If you are interested in running your own code on the device itself, see the [module API](module-api.md) documentation instead. The Device API is design to have only a simple stream of ToRadio and FromRadio packets and all polymorphism comes from the flexible set of Google Protocol Buffers which are sent over the wire. We use protocol buffers extensively both for the Bluetooth API and for packets inside the mesh or when providing packets to other applications on the phone. diff --git a/docs/developers/device/encryption.md b/docs/developers/device/encryption.md index 3e8d0631..f8f52e79 100644 --- a/docs/developers/device/encryption.md +++ b/docs/developers/device/encryption.md @@ -9,7 +9,7 @@ Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutio - If you are a cryptography expert, please review these notes and our questions below. Can you help us by reviewing our notes below and offering advice? We will happily give as much or as little credit as you wish ;-). - Consider our existing solution 'alpha' and probably fairly secure against a not particularly aggressive adversary (but we can't yet make a more confident statement). -Always keep in mind [xkcd's note on encryption](https://xkcd.com/538/). +Always keep in mind [xkcd's note on encryption](https://xkcd.com/538). ## Summary of strengths/weaknesses of our current implementation @@ -31,7 +31,7 @@ Possible future areas of work (if there is enough interest - post in our [forum] If you are reviewing our implementation, this is a brief statement of our method. - We do all crypto at the SubPacket (payload) level only, so that all meshtastic nodes will route for others - even those channels which are encrypted with a different key. -- Mostly based on reading [Wikipedia](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_(CTR)) and using the modes the ESP32 provides support for in hardware. +- Mostly based on reading [Wikipedia]() and using the modes the ESP32 provides support for in hardware. - We use AES256-CTR as a stream cypher (with zero padding on the last BLOCK) because it is well supported with hardware acceleration. - Our AES key is 128 or 256 bits, shared as part of the 'Channel' specification. - The node number concatenated with the packet number is used as the NONCE. This nonce will be stored in flash in the device and should essentially never repeat. If the user makes a new 'Channel' (i.e. picking a new random 256 bit key), the packet number will start at zero. @@ -51,4 +51,4 @@ I'm assuming that meshtastic is being used to hike in places where someone capab - I think the bigger encryption question is "what does the encryption need to do"? As it stands, an attacker who has yet to capture any of the devices cannot reasonably capture text or location data. An attacker who captures any device in the channel/mesh can read everything going to that device, everything stored on that device, and any other communication within the channel that they captured in encrypted form. If that capability basically matches your expectations, it is suitable for whatever adventures this was intended for, then, based on information publicly available or widely disclosed, the encryption is good. If those properties are distressing (like, device history is deliberately limited and you don't want a device captured today to endanger the information sent over the channel yesterday) we could talk about ways to achieve that (most likely synchronizing time and replacing the key with its own SHA256 every X hours, and ensuring the old key is not retained unnecessarily). - Two other things to keep in mind are that AES-CTR does not itself provide authenticity (e.g. an attacker can flip bits in replaying data and scramble the resulting plaintext), and that the current scheme gives some hints about transmission in the size. So, if you worry about an adversary deliberately messing-up messages or knowing the length of a text message, it looks like those might be possible. -I'm guessing that the network behaves somewhat like a store-and-forward network - or, at least, that the goal is to avoid establishing a two-way connection to transmit data. I'm afraid I haven't worked with mesh networks much, but remember studying them briefly in school about ten years ago. \ No newline at end of file +I'm guessing that the network behaves somewhat like a store-and-forward network - or, at least, that the goal is to avoid establishing a two-way connection to transmit data. I'm afraid I haven't worked with mesh networks much, but remember studying them briefly in school about ten years ago. diff --git a/docs/developers/device/mesh-alg.md b/docs/developers/device/mesh-alg.md index def9bf66..20639deb 100644 --- a/docs/developers/device/mesh-alg.md +++ b/docs/developers/device/mesh-alg.md @@ -6,7 +6,7 @@ sidebar_label: Mesh algorithm ## Current Algorithm -The routing protocol for Meshtastic is really quite simple (and suboptimal). It is heavily influenced by the mesh routing algorithm used in [RadioHead](https://www.airspayce.com/mikem/arduino/RadioHead/) (which was used in very early versions of this project). It has four conceptual layers. +The routing protocol for Meshtastic is really quite simple (and suboptimal). It is heavily influenced by the mesh routing algorithm used in [RadioHead](https://www.airspayce.com/mikem/arduino/RadioHead) (which was used in very early versions of this project). It has four conceptual layers. ### A Note About Protocol Buffers @@ -23,23 +23,23 @@ This preamble allows receiving radios to synchronize clocks and start framing. W This layer is conventional non-reliable LoRa packet transmission. The transmitted packet has the following representation before encoding for transmission: -| Offset | Length | Type | Usage | -|--------|--------|------|-------| -| 0x00 | 1 byte | Integer | syncWord, always `0x2B`. | -| 0x01 | 4 bytes | Integer | Packet header: Destination. The destination's unique NodeID. `0xFFFFFFFF` for broadcast. | -| 0x05 | 4 bytes | Integer | Packet Header: Sender. The sender's unique NodeID. | -| 0x09 | 4 bytes | Integer | Packet Header: The sending node's unique packet ID for this packet. | -| 0x0D | 32 bits | Bits | Packet Header: Flags. See the [header flags](#packet-header-flags) for usage. | -| 0x11 .. 0xFD | Varies, maximum of 237 bytes. | Bytes | Actual packet data. Unused bytes are not transmitted. | -| 0xFE .. 0xFF | 2 Bytes | Bytes | Unused. | +| Offset | Length | Type | Usage | +| ------------ | ----------------------------- | ------- | ---------------------------------------------------------------------------------------- | +| 0x00 | 1 byte | Integer | syncWord, always `0x2B`. | +| 0x01 | 4 bytes | Integer | Packet header: Destination. The destination's unique NodeID. `0xFFFFFFFF` for broadcast. | +| 0x05 | 4 bytes | Integer | Packet Header: Sender. The sender's unique NodeID. | +| 0x09 | 4 bytes | Integer | Packet Header: The sending node's unique packet ID for this packet. | +| 0x0D | 32 bits | Bits | Packet Header: Flags. See the [header flags](#packet-header-flags) for usage. | +| 0x11 .. 0xFD | Varies, maximum of 237 bytes. | Bytes | Actual packet data. Unused bytes are not transmitted. | +| 0xFE .. 0xFF | 2 Bytes | Bytes | Unused. | #### Packet Header Flags -| Index | # of Bits | Usage | -|-------|-----------|-------| -| 0 | 3 | HopLimit (see note in Layer 3) | -| 3 | 1 | WantAck | -| 4 .. 32 | 28 | Currently unused | +| Index | # of Bits | Usage | +| ------- | --------- | ------------------------------ | +| 0 | 3 | HopLimit (see note in Layer 3) | +| 3 | 1 | WantAck | +| 4 .. 32 | 28 | Currently unused | #### Usage Details @@ -55,20 +55,20 @@ This layer is conventional non-reliable LoRa packet transmission. The transmitte All transmitters must listen before attempting to transmit. If another node is heard transmitting, the listening node will reattempt transmission after a calculated delay. The delay depends on various settings and is based on Semtech's [LoRa Modem Design Guide](/documents/LoRa_Design_Guide.pdf), section 4 and implemented in `RadioInterface::getPacketTime`. The following tables contains some calculated values for how long it takes to transmit a packet, which is used to calculate the delay. -| Payload Bytes | Spreading Factor | Bandwidth | Coding Rate | Time | -|---------------|------------------|-----------|-------------|------| -| 0 | 7 | 125 kHz | 4/5 | 13 ms | -| 237 | 7 | 125 kHz | 4/5 | 100 ms | -| 0 | 7 | 500 kHz | 4/5 | 4 ms | -| 237 | 7 | 500 kHz | 4/5 | 25 ms | -| 0 | 10 | 250 kHz | 4/7 | 51 ms | -| 237 | 10 | 250 kHz | 4/7 | 391 ms | -| 0 | 11 | 250 kHz | 4/6 | 101 ms | -| 237 | 11 | 250 kHz | 4/6 | 633 ms | -| 0 | 9 | 31.25 kHz | 4/8 | 201 ms | -| 237 | 9 | 31.25 kHz | 4/8 | 2.413 **seconds** | -| 0 | 12 | 125 kHz | 4/8 | 402 ms | -| 237 | 12 | 125 kHz | 4/8 | 3.482 **seconds** | +| Payload Bytes | Spreading Factor | Bandwidth | Coding Rate | Time | +| ------------- | ---------------- | --------- | ----------- | ----------------- | +| 0 | 7 | 125 kHz | 4/5 | 13 ms | +| 237 | 7 | 125 kHz | 4/5 | 100 ms | +| 0 | 7 | 500 kHz | 4/5 | 4 ms | +| 237 | 7 | 500 kHz | 4/5 | 25 ms | +| 0 | 10 | 250 kHz | 4/7 | 51 ms | +| 237 | 10 | 250 kHz | 4/7 | 391 ms | +| 0 | 11 | 250 kHz | 4/6 | 101 ms | +| 237 | 11 | 250 kHz | 4/6 | 633 ms | +| 0 | 9 | 31.25 kHz | 4/8 | 201 ms | +| 237 | 9 | 31.25 kHz | 4/8 | 2.413 **seconds** | +| 0 | 12 | 125 kHz | 4/8 | 402 ms | +| 237 | 12 | 125 kHz | 4/8 | 3.482 **seconds** | The actual delay calculation is a random value between 100ms (a hardcoded minimum) and the time taken to transmit just the header, which is given in the table as a 0 Byte payload. @@ -81,7 +81,7 @@ The default messaging provided by Layer 1 is extended by setting the `WantAck` f > This packet is being sent as a reliable message, we would prefer it to arrive at the destination. We would like to receive an ACK packet in response. > > Broadcast messages treat this flag specially: Since ACKs for broadcasts would rapidly flood the channel, the normal ACK behavior is suppressed. Instead, the original sender listens to see if at least one node is rebroadcasting this -packet (because naive flooding algorithm). If it hears that, the odds (given typical LoRa topologies) are very high that every node should eventually receive the message. So FloodingRouter.cpp generates an implicit ACK which is delivered to the original sender. If after some time we don't hear anyone rebroadcast our packet, we will timeout and retransmit, using the regular resend logic. +> packet (because naive flooding algorithm). If it hears that, the odds (given typical LoRa topologies) are very high that every node should eventually receive the message. So FloodingRouter.cpp generates an implicit ACK which is delivered to the original sender. If after some time we don't hear anyone rebroadcast our packet, we will timeout and retransmit, using the regular resend logic. If a transmitting node does not receive an ACK (or NAK) packet within FIXME milliseconds, it will use Layer 1 to attempt a retransmission of the sent packet. A reliable packet (at this 'zero hop' level) will be resent a maximum of three times. If no ACK or NAK has been received by then the local node will internally generate a NAK (either for local consumption or use by higher layers of the protocol). diff --git a/docs/developers/device/plugin-api.md b/docs/developers/device/module-api.md similarity index 69% rename from docs/developers/device/plugin-api.md rename to docs/developers/device/module-api.md index b9e66e00..7e1ab059 100644 --- a/docs/developers/device/plugin-api.md +++ b/docs/developers/device/module-api.md @@ -1,16 +1,16 @@ --- -id: plugin-api -title: Plugin API -sidebar_label: Plugin API +id: module-api +title: Module API +sidebar_label: Module API --- -This is a tutorial on how to write small plugins which run on the device. Plugins are bits regular 'Arduino' code that can send and receive packets to other nodes/apps/PCs using our mesh. +This is a tutorial on how to write small modules which run on the device. Modules are bits of regular 'Arduino' code that can send and receive packets to other nodes/apps/PCs using our mesh. ## Key concepts -All plugins should be subclasses of MeshPlugin. By inheriting from this class and creating an instance of your new plugin your plugin will be automatically registered to receive packets. +All modules should be subclasses of MeshPlugin. By inheriting from this class and creating an instance of your new module your module will be automatically registered to receive packets. -Messages are sent to particular port numbers (similar to UDP networking). Your new plugin should eventually pick its own port number (see below), but at first you can simply use PRIVATE_APP (which is the default). +Messages are sent to particular port numbers (similar to UDP networking). Your new module should eventually pick its own port number (see below), but at first you can simply use PRIVATE_APP (which is the default). Packets can be sent/received either as raw binary structures or as [Protobufs](https://developers.google.com/protocol-buffers). @@ -19,12 +19,12 @@ Packets can be sent/received either as raw binary structures or as [Protobufs](h The relevant bits of the class hierarchy are as follows - [MeshPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/MeshPlugin.h) (in src/mesh/MeshPlugin.h) - you probably don't want to use this baseclass directly - - [SinglePortPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/SinglePortPlugin.h) (in src/mesh/SinglePortPlugin.h) - for plugins that send/receive from a single port number (the normal case) - - [ProtobufPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/ProtobufPlugin.h) (in src/mesh/ProtobufPlugin.h) - for plugins that send/receive a single particular Protobuf type. Inherit from this if you are using protocol buffers in your plugin. + - [SinglePortPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/SinglePortPlugin.h) (in src/mesh/SinglePortPlugin.h) - for modules that send/receive from a single port number (the normal case) + - [ProtobufPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/mesh/ProtobufPlugin.h) (in src/mesh/ProtobufPlugin.h) - for modules that send/receive a single particular Protobuf type. Inherit from this if you are using protocol buffers in your module. You will typically want to inherit from either SinglePortPlugin (if you are just sending/receiving raw bytes) or ProtobufPlugin (if you are sending/receiving protobufs). You'll implement your own handleReceived/handleReceivedProtobuf - probably based on the example code. -If your plugin needs to perform any operations at startup you can override and implement the setup() method to run your code. +If your module needs to perform any operations at startup you can override and implement the setup() method to run your code. If you need to send a packet you can call service.sendToMesh with code like this (from the examples): @@ -35,33 +35,33 @@ p->to = dest; service.sendToMesh(p); ``` -## Example plugins +## Example modules -A number of [key services](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins) are implemented using the plugin API, these plugins are as follows: +A number of [key services](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules) are implemented using the module API, these modules are as follows: -- [TextMessagePlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/TextMessagePlugin.h) - receives text messages and displays them on the LCD screen/stores them in the local DB -- [NodeInfoPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/NodeInfoPlugin.h) - receives/sends User information to other nodes so that usernames are available in the databases -- [RemoteHardwarePlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/RemoteHardwarePlugin.h) - a plugin that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/software/other/remote-hardware-service) for details. -- [ReplyPlugin](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/ReplyPlugin.h) - a simple plugin that just replies to any packet it receives (provides a 'ping' service). +- [TextMessageModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/TextMessageModule.h) - receives text messages and displays them on the LCD screen/stores them in the local DB +- [NodeInfoModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/NodeInfoModule.h) - receives/sends User information to other nodes so that usernames are available in the databases +- [RemoteHardwareModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/RemoteHardwareModule.h) - a module that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/software/other/remote-hardware-service) for details. +- [ReplyModule](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/ReplyModule.h) - a simple module that just replies to any packet it receives (provides a 'ping' service). ## Getting started The easiest way to get started is: - [Build and install](/docs/software/other/build-instructions) the standard codebase from GitHub. -- Copy [src/plugins/ReplyPlugin.\*](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/ReplyPlugin.cpp) into src/plugins/YourPlugin.*. Then change the port number from *PortNum_REPLY_APP* to *PortNum_PRIVATE_APP\*. -- Edit plugins/Plugins.cpp:setupPlugins() to add a call to create an instance of your plugin (see comment at head of that function) +- Copy [src/modules/ReplyModule.\*](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/ReplyModule.cpp) into src/modules/YourModule.*. Then change the port number from *PortNum_REPLY_APP* to *PortNum_PRIVATE_APP\*. +- Edit moduless/Moduless.cpp:setupModules() to add a call to create an instance of your module (see comment at head of that function) - Rebuild with your new messaging goodness and install on the device - Use the [meshtastic commandline tool](https://github.com/meshtastic/Meshtastic-python) to send a packet to your board, for example `meshtastic --dest 1234 --sendping`, where _1234_ is another mesh node to send the ping to. ## Threading -It is very common that you would like your plugin to be invoked periodically. -We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement runOnce(). See the OSThread [documentation](http://github.com/meshtastic/meshtastic-device/tree/master/src/concurrency/OSThread.h) for more details. For an example consumer of this API see RemoteHardwarePlugin::runOnce. +It is very common that you would like your module to be invoked periodically. +We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement runOnce(). See the OSThread [documentation](http://github.com/meshtastic/meshtastic-device/tree/master/src/concurrency/OSThread.h) for more details. For an example consumer of this API see RemoteHardwareModule::runOnce. ## Sending messages -If you would like to proactively send messages (rather than just responding to them), just call service.sendToMesh(). For an example of this see [NodeInfoPlugin::sendOurNodeInfo(...)](http://github.com/meshtastic/meshtastic-device/tree/master/src/plugins/NodeInfoPlugin.cpp). +If you would like to proactively send messages (rather than just responding to them), just call service.sendToMesh(). For an example of this see [NodeInfoModule::sendOurNodeInfo(...)](http://github.com/meshtastic/meshtastic-device/tree/master/src/modules/NodeInfoModule.cpp). ## Picking a port number diff --git a/docs/developers/overview.md b/docs/developers/overview.md index e2bf3994..a998f7c9 100644 --- a/docs/developers/overview.md +++ b/docs/developers/overview.md @@ -4,36 +4,42 @@ title: Contribute to Meshtastic sidebar_label: Contribute to Meshtastic slug: /developers --- + # How to Help Meshtastic is a team of volunteers, and as such there is always plenty of ways to help. This project gets great contributions from people in their off hours. Those contributors work on the features they are interested in. It is a very open and welcoming developer community, and we are always looking for help to improve Meshtastic. -* If you're a developer, there's plenty stuff to do. Dig in! -* If you're interacting with Meshtastic radios, we could use help with testing, documenting, and providing feedback. -* If you're into Web Development, check out the different web repos. -* If you're into Kotlin and Android, check out the link to the repo below. -* If you're into Python, check out the link to the repo below -* If you're into Ham Radio and LoRa, then this is a great project for you! -* ... basically... we would love to have your help and feedback +- If you're a developer, there's plenty stuff to do. Dig in! +- If you're interacting with Meshtastic radios, we could use help with testing, documenting, and providing feedback. +- If you're into Web Development, check out the different web repos. +- If you're into Kotlin and Android, check out the link to the repo below. +- If you're into Python, check out the link to the repo below +- If you're into Ham Radio and LoRa, then this is a great project for you! +- ... basically... we would love to have your help and feedback There are several developers, testers, and active users on [Discord](https://discord.gg/UQJ5QuM7vq). There are many technologies (and repositories) used in creating the Meshtastic ecosystem. Below is a breakdown: ## Protocol buffers -Most communication and interactions happen with protocol buffers. The [Meshtastic-protobufs](https://github.com/meshtastic/Meshtastic-protobufs) repo is where all of the protocol buffer changes happen. See the [Protobuf API Reference](https://meshtastic.org/docs/developers/protobufs/api) for more details. + +Most communication and interactions happen with protocol buffers. The [Meshtastic-protobufs](https://github.com/meshtastic/Meshtastic-protobufs) repo is where all of the protocol buffer changes happen. See the [Protobuf API Reference](/docs/developers/protobufs/api) for more details. ## Firmware + The [Meshtastic-device](https://github.com/meshtastic/Meshtastic-device) is where all of the firmware development happens. This is where the code for the ESP32 and nRF52 based devices is developed. It is mainly C and C++ code.Think Arduino. It is where the first level of hardware interaction begins and ends. -## Plugins -[Plugins](https://meshtastic.org/docs/software/plugins/) are also implemented mainly in the Meshtastic-device repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement plugin functionality. You probably also want to have some client/device use/interact with the plugin and that is where the Device support comes into play. +## modules + +[Modules](/docs/software/modules) are also implemented mainly in the Meshtastic-device repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement module functionality. You probably also want to have some client/device use/interact with the module and that is where the Device support comes into play. ## Device Support -The [Meshtastic-python](https://github.com/meshtastic/Meshtastic-python) is typically where the first device interaction takes place, but that is not a requirement. This repo has a command line utility that allows you to interact with most functionality with the devices. This python library can also be consumed for other applications. See [Community applications](https://meshtastic.org/docs/software/community/community-overview) for other Meshtastic applications. + +The [Meshtastic-python](https://github.com/meshtastic/Meshtastic-python) is typically where the first device interaction takes place, but that is not a requirement. This repo has a command line utility that allows you to interact with most functionality with the devices. This python library can also be consumed for other applications. See [Community applications](/docs/software/community/community-overview) for other Meshtastic applications. ## Web Application -The [Meshtastic-web](https://github.com/meshtastic/meshtastic-web) is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web interface overview](https://meshtastic.org/docs/software/web/web-app-software) for more details. + +The [Meshtastic-web](https://github.com/meshtastic/meshtastic-web) is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web interface overview](/docs/software/web/web-app-software) for more details. The [meshtastic.js](https://github.com/meshtastic/meshtastic.js) is a JavaScript library that provides an interface for Meshtastic devices. @@ -42,13 +48,15 @@ The [meshtastic.js](https://github.com/meshtastic/meshtastic.js) is a JavaScript * Saving of preferences * Better loading state indicators * Chat scroll lock - * Various plugin support + * Various module support ## Phone Apps + There are two phone apps that interact with the Meshtastic devices: -* The [Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repo contains the Kotlin code for Android based interactions with Meshtastic devices. See [here](https://meshtastic.org/docs/developers/android/build-app) for how to build/create a development environment for the Meshtastic Android App. -* The iOS app is in the process of a complete re-write in Swift and will have the new repo published soon. Note: There are a couple of earlier implementations. +- The [Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repo contains the Kotlin code for Android based interactions with Meshtastic devices. See [here](/docs/developers/android/build-app) for how to build/create a development environment for the Meshtastic Android App. +- The iOS app is in the process of a complete re-write in Swift and will have the new repo published soon. Note: There are a couple of earlier implementations. ## Documentation + This website is in the [Meshtastic](https://github.com/meshtastic/Meshtastic) repository. diff --git a/docs/faq/bluetooth.md b/docs/faq/bluetooth.md index d941cfd2..d0fcf4cc 100644 --- a/docs/faq/bluetooth.md +++ b/docs/faq/bluetooth.md @@ -3,11 +3,12 @@ id: bluetooth title: FAQs - Bluetooth sidebar_label: Bluetooth --- + ## Overview ### How do I pair my phone to the device if my device doesn't have a screen? -Use [Wifi](https://meshtastic.org/docs/software/device/device-wifi) or Bluetooth with screenless pairing: before you initiate pairing, double click on the device button. The LED will blink 3 times in confirmation and the PIN will be set temporarily to `123456`. +Use [Wifi](/docs/software/device/device-wifi) or Bluetooth with screenless pairing: before you initiate pairing, double click on the device button. The LED will blink 3 times in confirmation and the PIN will be set temporarily to `123456`. ### Can I have Bluetooth enabled and use WiFi radio? diff --git a/docs/faq/client-ios.md b/docs/faq/client-ios.md index 448d1ab3..2bb71336 100644 --- a/docs/faq/client-ios.md +++ b/docs/faq/client-ios.md @@ -3,6 +3,7 @@ id: client-ios title: FAQs - iOS sidebar_label: iOS --- + ## Overview ### What version of iOS does the Meshtastic iOS App Require? @@ -11,4 +12,4 @@ The now-in-beta iOS app requires iOS v15. ### How do I get the Meshtastic iOS App? -See [iOS App](https://meshtastic.org/docs/software/ios/ios-development) +See [iOS App](/docs/software/ios/ios-development) diff --git a/docs/faq/device.md b/docs/faq/device.md index 99b9ab13..455495a5 100644 --- a/docs/faq/device.md +++ b/docs/faq/device.md @@ -3,11 +3,12 @@ id: device title: FAQs - Device sidebar_label: Device --- + ## Overview ### Where do I purchase the device hardware? -Each [supported device](https://meshtastic.org/docs/hardware/supported/tbeam) has a "Purchase Link". +Each [supported device](/docs/hardware/supported/tbeam) has a "Purchase Link". ### I have my hardware. How do I install the firmware and any required drivers? @@ -35,5 +36,5 @@ Push the left PWR button for about 1 second. ### How can I tell the device not to sleep? -- Android instructions see: [Android Usage](https://meshtastic.org/docs/software/android/android-usage#configuration-options) -- Python CLI instructions see: [Python Usage](https://meshtastic.org/docs/software/python/python-cli#changing-device-settings) +- Android instructions see: [Android Usage](/docs/software/android/android-usage#configuration-options) +- Python CLI instructions see: [Python Usage](/docs/software/python/python-cli#changing-device-settings) diff --git a/docs/faq/faq.md b/docs/faq/faq.md index ccd08c32..9cd4370a 100644 --- a/docs/faq/faq.md +++ b/docs/faq/faq.md @@ -4,6 +4,7 @@ title: FAQs - General sidebar_label: General slug: /faq --- + + ## Overview ### What is Meshtastic? @@ -32,4 +34,4 @@ After reading this FAQ and checking out the links on the left, there are two pla ### How can I contribute to Meshtastic? -Everyone contributes in a different way. Join the [Forum](https://meshtastic.discourse.group) and/or the [Meshtastic Discord](https://discord.com/invite/UQJ5QuM7vq) and introduce yourself. We're all very friendly. If you'd like to pitch in some code, check out the [Developers](https://meshtastic.org/docs/developers) menu on the left. +Everyone contributes in a different way. Join the [Forum](https://meshtastic.discourse.group) and/or the [Meshtastic Discord](https://discord.com/invite/UQJ5QuM7vq) and introduce yourself. We're all very friendly. If you'd like to pitch in some code, check out the [Developers](/docs/developers) menu on the left. diff --git a/docs/faq/modules.md b/docs/faq/modules.md new file mode 100644 index 00000000..d12c9db4 --- /dev/null +++ b/docs/faq/modules.md @@ -0,0 +1,18 @@ +--- +id: modules +title: FAQs - Modules +sidebar_label: Modules +--- +## Overview + +### What are Modules? + +Modules are features that expand the basic device functionality and/or integrate with other services. + +### What modules do we have available? + +A list of available modules is available [here](/docs/software/modus). + +### I'd like to write a module. How do I get started? + +API documentation for creating modules is available [here](/docs/developers/device/module-api). diff --git a/docs/faq/plugins.md b/docs/faq/plugins.md deleted file mode 100644 index be96753b..00000000 --- a/docs/faq/plugins.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -id: plugins -title: FAQs - Plugins -sidebar_label: Plugins ---- -## Overview - -### What are Plugins? - -Plugins are features that expand the basic device functionality and/or integrate with other services. - -### What plugins do we have available? - -To see the list of available plugins, please go to: https://meshtastic.org/docs/software/plugins/ - -### I'd like to write a plugin. How do I get started? - -See: https://meshtastic.org/docs/developers/device/plugin-api diff --git a/docs/getting-started/flashing-esp32.md b/docs/getting-started/flashing-esp32.md index 5f179db7..27b18456 100644 --- a/docs/getting-started/flashing-esp32.md +++ b/docs/getting-started/flashing-esp32.md @@ -111,8 +111,8 @@ pip3 install --upgrade esptool -- Download and install [Python](https://www.python.org/). When installing, make sure to click `Add Python X.Y to PATH`. -- Download and install [Gitbash](https://gitforwindows.org/) (or other appropriate shell) and run all subsequent commands from that shell. +- Download and install [Python](https://www.python.or). When installing, make sure to click `Add Python X.Y to PATH`. +- Download and install [Gitbash](https://gitforwindows.org) (or other appropriate shell) and run all subsequent commands from that shell. :::note Confirm installation of `python` & `pip` with the following commands. @@ -146,9 +146,9 @@ values={[ {label: 'macOS', value: 'macos'}, {label: 'Windows', value: 'windows'}, ]}> - - - + + + :::important On Windows, you must explicitly declare esptool as a .py script. Use `esptool.py chip_id`. diff --git a/docs/hardware/antenna/resources.md b/docs/hardware/antenna/resources.md index 8a3795f3..b0c26075 100644 --- a/docs/hardware/antenna/resources.md +++ b/docs/hardware/antenna/resources.md @@ -7,47 +7,44 @@ slug: /hardware/resources ### More antenna information -* [Hackaday's Introduction to Antenna Basics](https://www.youtube.com/playlist?list=PL_tws4AXg7authztKFg5ZN5qWGtq3N_nI) - * An excellent series of presentations on the basics of antenna design and function, presented by spacecraft radio engineer Karen Rucker. +- [Hackaday's Introduction to Antenna Basics](https://www.youtube.com/playlist?list=PL_tws4AXg7authztKFg5ZN5qWGtq3N_nI) + - An excellent series of presentations on the basics of antenna design and function, presented by spacecraft radio engineer Karen Rucker. + ### Coverage prediction -* [Tower Coverage.com](https://www.towercoverage.com/) - * Commercial, but has free options +- [Tower Coverage.com](https://www.towercoverage.com) + - Commercial, but has free options -* [HeyWhat'sThat](http://www.heywhatsthat.com/) - * Free with path profiling options +- [HeyWhat'sThat](http://www.heywhatsthat.com) + - Free with path profiling options -* [Radio Mobile Online](https://www.ve2dbe.com/rmonline_s.asp) - * Radio Mobile Online is a radio wave propagation prediction tool dedicated to amateur radio - +- [Radio Mobile Online](https://www.ve2dbe.com/rmonline_s.asp) + - Radio Mobile Online is a radio wave propagation prediction tool dedicated to amateur radio ### RF Tools -* [Times Microwave Systems](https://www.timesmicrowave.com/calculator/?Product=RG-6&RunLength=10&Frequency=868) - * Coaxial Cable Attenuation & Power Handling Calculator +- [Times Microwave Systems](https://www.timesmicrowave.com/calculator/?Product=RG-6&RunLength=10&Frequency=868) + - Coaxial Cable Attenuation & Power Handling Calculator -* [Solwise Link Budget Calculator](https://www.solwise.co.uk/link-budget.htm) - * Predict the received signal strength +- [Solwise Link Budget Calculator](https://www.solwise.co.uk/link-budget.htm) + - Predict the received signal strength -* [Amateur Radio Toolkit](https://play.google.com/store/apps/details?id=com.daveyhollenberg.amateurradiotoolkit) - * Android app with lots of antenna information - +- [Amateur Radio Toolkit](https://play.google.com/store/apps/details?id=com.daveyhollenberg.amateurradiotoolkit) + - Android app with lots of antenna information ### Antenna designs -* [1/4 Wave Ground Plane Antenna Calculator](https://m0ukd.com/calculators/quarter-wave-ground-plane-antenna-calculator/) +- [1/4 Wave Ground Plane Antenna Calculator](https://m0ukd.com/calculators/quarter-wave-ground-plane-antenna-calculator) +- [Quadrifilar helicoidal antenna calculator](https://jcoppens.com/ant/qfh/calc.en.php) -* [Quadrifilar helicoidal antenna calculator](https://jcoppens.com/ant/qfh/calc.en.php) +- [Building an 868/915 MHz co-linear antenna tutorial](https://www.youtube.com/watch?v=1_1LxuOngHs) + - [868 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/Collinear868MHzLoRaantenna.PDF) + - [915 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/CollinearLoRaantenna915MHzIRNAS.PDF) -* [Building an 868/915 MHz co-linear antenna tutorial](https://www.youtube.com/watch?v=1_1LxuOngHs) - * [868 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/Collinear868MHzLoRaantenna.PDF) - * [915 MHz antenna schematic PDF](https://github.com/IRNAS/ttn-irnas-gw/blob/master/CollinearLoRaantenna915MHzIRNAS.PDF) - - -* [NEC based antenna modeler and optimizer](https://www.qsl.net/4nec2/) +- [NEC based antenna modeler and optimizer](https://www.qsl.net/4nec2) diff --git a/docs/hardware/antenna/testing.md b/docs/hardware/antenna/testing.md index b4694fdc..33c70488 100644 --- a/docs/hardware/antenna/testing.md +++ b/docs/hardware/antenna/testing.md @@ -9,27 +9,29 @@ Testing of antennas can be both simple and complex. At its simplest, testing inv ## Range testing As mentioned, while stating the obvious, the simplest way of performing a test is: + - Walk around with a radio sending messages, - For each message, note location and whether 'ACK' ticks are received, - Also, note reported signal strengths, - Change aerials, repeat, and evaluate results. :::note -The [range test plugin](/docs/software/plugins/range-test-plugin) has been designed for exactly this purpose. It allows one node to transmit a frequent message, and another node to record which messages were received. This data is saved and can be imported to applications such as Google Earth. +The [range test module](/docs/software/modules/range-test-module) has been designed for exactly this purpose. It allows one node to transmit a frequent message, and another node to record which messages were received. This data is saved and can be imported to applications such as Google Earth. ::: -On the topic of testing - performing your own testing and providing feedback is the lifeblood of Meshtastic and open source projects. +On the topic of testing - performing your own testing and providing feedback is the lifeblood of Meshtastic and open source projects. ## Signal strength testing Real world testing is also discussed by Andreas Spiess (the 'guy with the Swiss accent') in his [tutorial](https://www.youtube.com/watch?v=J3PBL9oLPX8). He has written [code](https://github.com/SensorsIot/Antenna-Tester) for testing antennas using two Lora32 V1 boards to compare how different antennas behave. Lilygo have also made code available for testing the RSSI on the [LORA32](https://github.com/LilyGO/TTGO-LORA32) [boards](https://github.com/Xinyuan-LilyGO/TTGO-LoRa-Series) and the [T-Beam](https://github.com/LilyGO/TTGO-T-Beam). -Here are a [couple](https://medium.com/home-wireless/testing-lora-antennas-at-915mhz-6d6b41ac8f1d) of [excellent](https://medium.com/home-wireless/testing-and-reviewing-lora-antennas-5b37dfa594a3) aerial comparisons. Their utility goes beyond the specific aerials tested, giving insight into: +Here are a [couple](https://medium.com/home-wireless/testing-lora-antennas-at-915mhz-6d6b41ac8f1d) of [excellent](https://medium.com/home-wireless/testing-and-reviewing-lora-antennas-5b37dfa594a3) aerial comparisons. Their utility goes beyond the specific aerials tested, giving insight into: + - Aerial types & their characteristics, - Testing approaches. ## Antenna matching & vector network analyzers -One of the first things to ensure, is that the antenna you have is tuned to the frequency that you are using. A lot of cheap antennas come labeled with an incorrect working frequency, and this will immediately reduce the emitted signal strength. A Vector Network Analyzer (VNA) can be used to ensure that the antenna is appropriately matched to the transmission circuit, ensuring that it is operating at the correct impedance, and has a low level of power reflected back from the antenna to the transmitter at the desired transmission frequency. +One of the first things to ensure, is that the antenna you have is tuned to the frequency that you are using. A lot of cheap antennas come labeled with an incorrect working frequency, and this will immediately reduce the emitted signal strength. A Vector Network Analyzer (VNA) can be used to ensure that the antenna is appropriately matched to the transmission circuit, ensuring that it is operating at the correct impedance, and has a low level of power reflected back from the antenna to the transmitter at the desired transmission frequency. Andreas Spiess also gives a great explanation of [how to use Vector Network Analyzers](https://www.youtube.com/watch?v=ZpKoLvqOWyc) to correctly tune your antennas, as well as a more [in depth tutorial of how to use VNAs](https://www.youtube.com/watch?v=_pjcEKQY_Tk). It is important to remember however, that VNAs can only tell you if the antenna is well-matched, not how well it is transmitting. A 50 ohm resistor across the transmitter output would show as ideally matched, but it would be useless at transmitting a signal. There are a number of VNAs now available for less than $100, making this no longer out of reach for most hobbyists, unlike expensive spectrum analyzers. diff --git a/docs/hardware/supported/heltec.md b/docs/hardware/supported/heltec.md index 9c199ef0..be79f31a 100644 --- a/docs/hardware/supported/heltec.md +++ b/docs/hardware/supported/heltec.md @@ -19,7 +19,7 @@ sidebar_label: Heltec - No GPS - Firmware file: `firmware-heltec-1.x.x.bin` -- [Purchase link](https://heltec.org/project/wifi-lora-32/) +- [Purchase link](https://heltec.org/project/wifi-lora-32) [](/img/hardware/heltec-v2.png) diff --git a/docs/legal/privacy.md b/docs/legal/privacy.md index 461a4fa2..86d555aa 100644 --- a/docs/legal/privacy.md +++ b/docs/legal/privacy.md @@ -9,10 +9,10 @@ We don't collect any personal identifying information. We never capture username If you opt-in to analytics on the Android app (thank you - that helps us know what things we need to improve), we will receive anonymized information about user behavior. This includes crash reports, screens used in the app, etc... Analytics is provided by [Firebase Crashlytics](https://firebase.google.com/products/crashlytics). -Maps provided by Mapbox require analytics to work. For more information about what they collect, please see the [Mapbox privacy policy](https://www.mapbox.com/legal/privacy/). +Maps provided by Mapbox require analytics to work. For more information about what they collect, please see the [Mapbox privacy policy](https://www.mapbox.com/legal/privacy). -The search engine for this website is provided by Algolia, please see their [privacy policy](https://www.algolia.com/policies/privacy/) for details of what information they collect. +The search engine for this website is provided by Algolia, please see their [privacy policy](https://www.algolia.com/policies/privacy) for details of what information they collect. -This is an open-source project run by hobbyists, and we try to be completely transparent. If you have questions on this policy, please post on the forum, and we'll reply/clarify/correct. +This is an open-source project run by hobbyists, and we try to be completely transparent. If you have questions on this policy, please post on the forum, and we'll reply/clarify/correct. Keep being awesome! diff --git a/docs/settings/canned-message-plugin.md b/docs/settings/canned-message-module.md similarity index 52% rename from docs/settings/canned-message-plugin.md rename to docs/settings/canned-message-module.md index 5ab3e5b5..d81c1fc3 100644 --- a/docs/settings/canned-message-plugin.md +++ b/docs/settings/canned-message-module.md @@ -1,8 +1,9 @@ --- -id: canned-message-plugin -title: Canned Message Plugin -sidebar_label: Canned Message Plugin +id: canned-message-module +title: Canned Message Module +sidebar_label: Canned Message Module --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -11,54 +12,58 @@ GPIO access is fundamentally dangerous because invalid options can physically da ::: + :::note -This plugin requires attaching a peripheral accessory to your device. It will not work without one. It also requires use of the [Rotary Encoder Plugin](rotary-encoder-plugin) to configure the input source. +This module requires attaching a peripheral accessory to your device. It will not work without one. It also requires use of the [Rotary Encoder Module](rotary-encoder-module) to configure the input source. ::: ## Overview -The CannedMessage Plugin will allow you to send messages to the mesh network from the device without using the phone app. You can predefine text messages to choose from. +The CannedMessage Module will allow you to send messages to the mesh network from the device without using the phone app. You can predefine text messages to choose from. :::tip -Once plugin settings are changed, a **reset** is required for them to take effect. +Once module settings are changed, a **reset** is required for them to take effect. ::: ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| canned_message_plugin_allow_input_source | `rotEnc1`, `_any` | `_any` | -| canned_message_plugin_enabled | `true`, `false` | `false` | -| canned_message_plugin_messages | `string` | `""` | -| canned_message_plugin_send_bell | `true`, `false` | `false` | +| Setting | Acceptable Values | Default | +| :--------------------------------------: | :---------------: | :-----: | +| canned_message_module_allow_input_source | `rotEnc1`, `_any` | `_any` | +| canned_message_module_enabled | `true`, `false` | `false` | +| canned_message_module_messages | `string` | `""` | +| canned_message_module_send_bell | `true`, `false` | `false` | -### canned_message_plugin_allow_input_source +### canned_message_module_allow_input_source -Input event source accepted by the canned message plugin. +Input event source accepted by the canned message module. -| Value | Description | -| :---: | :---------: | -| `_any` | Default. Allows any peripheral input device connected to the device. | -| `rotEnc1` | Hardcoded value naming the input device that this plugin listens to. This could allow multiple input devices to be named with future software development. At present, this doesn't do anything differently than the default setting. | +| Value | Description | +| :-------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| `_any` | Default. Allows any peripheral input device connected to the device. | +| `rotEnc1` | Hardcoded value naming the input device that this module listens to. This could allow multiple input devices to be named with future software development. At present, this doesn't do anything differently than the default setting. | #### Set input source + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Set Allowed Input Source" -meshtastic --set canned_message_plugin_allow_input_source "_any" +meshtastic --set canned_message_module_allow_input_source "_any" ``` + ```bash title="Specify Allowed Input Source" -meshtastic --set canned_message_plugin_allow_input_source "rotEnc1" +meshtastic --set canned_message_module_allow_input_source "rotEnc1" ``` + @@ -83,31 +88,35 @@ Configuring this setting is not yet available for the selected platform. If this -### canned_message_plugin_enabled +### canned_message_module_enabled -Enables the plugin. +Enables the module. :::tip -Using the canned message plugin requires you set up the [rotary encoder plugin](rotary-encoder-plugin). See [prerequisites](#prerequisites) below. +Using the canned message module requires you set up the [Rotary Encoder Module](rotary-encoder-module). See [prerequisites](#prerequisites) below. ::: -#### Enable/Disable the plugin - - -```bash title="Enable Canned Message Plugin" -meshtastic --set canned_message_plugin_enabled true +#### Enable/Disable the module + + + + +```bash title="Enable Canned Message Module" +meshtastic --set canned_message_module_enabled true ``` -```bash title="Disable Canned Message Plugin" -meshtastic --set canned_message_plugin_enabled false + +```bash title="Disable Canned Message Module" +meshtastic --set canned_message_module_enabled false ``` + @@ -132,27 +141,29 @@ Configuring this setting is not yet available for the selected platform. If this -### canned_message_plugin_messages +### canned_message_module_messages -Predefined messages for CannedMessagePlugin separated by `|` characters. +Predefined messages for CannedMessageModule separated by `|` characters. You can define up to 50 messages with a total length 1024 bytes. #### Set canned messages + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Set Canned Messages" -meshtastic --set canned_message_plugin_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger" +meshtastic --set canned_message_module_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger" ``` + @@ -177,29 +188,32 @@ Configuring this setting is not yet available for the selected platform. If this -### canned_message_plugin_send_bell +### canned_message_module_send_bell -CannedMessagePlugin also sends a bell character with the messages. -The [External Notification Plugin](external-notification-plugin) can benefit from this feature as it utilizes the bell character. +CannedMessageModule also sends a bell character with the messages. +The [External Notification Module](external-notification-module) can benefit from this feature as it utilizes the bell character. #### Enable/Disable bell character + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Enable Bell Character" -meshtastic --set canned_message_plugin_send_bell true +meshtastic --set canned_message_module_send_bell true ``` + ```bash title="Disable Bell Character" -meshtastic --set canned_message_plugin_send_bell false +meshtastic --set canned_message_module_send_bell false ``` + @@ -229,20 +243,22 @@ Configuring this setting is not yet available for the selected platform. If this ### Prerequisites + - Attach a compatible peripheral device. Take note of the GPIO numbers you use, as they will be used in the following step. -- Once attached, configure peripheral device with [Rotary Encoder Plugin Settings](rotary-encoder-plugin). +- Once attached, configure peripheral device with [Rotary Encoder Module](rotary-encoder-module) Settings. :::note Replace each `GPIO` (x3) below with the GPIO numbers from hardware setup. - ```bash title="Canned Message Plugin - Required Rotary Encoder Plugin Settings" - meshtastic --set rotary1_pin_a GPIO - meshtastic --set rotary1_pin_b GPIO - meshtastic --set rotary1_pin_press GPIO - meshtastic --set rotary1_event_cw KEY_UP - meshtastic --set rotary1_event_ccw KEY_DOWN - meshtastic --set rotary1_event_press KEY_SELECT - meshtastic --set rotary1_enabled True - ``` +```bash title="Canned Message Module - Required Rotary Encoder Module Settings" +meshtastic --set rotary1_pin_a GPIO +meshtastic --set rotary1_pin_b GPIO +meshtastic --set rotary1_pin_press GPIO +meshtastic --set rotary1_event_cw KEY_UP +meshtastic --set rotary1_event_ccw KEY_DOWN +meshtastic --set rotary1_event_press KEY_SELECT +meshtastic --set rotary1_enabled True +``` + ::: -That's it! With a functioning and enabled rotary encoder, you're ready to begin configuring the Canned Message Plugin. +That's it! With a functioning and enabled rotary encoder, you're ready to begin configuring the Canned Message Module. diff --git a/docs/settings/environmental-measurment-plugin.md b/docs/settings/environmental-measurment-module.md similarity index 56% rename from docs/settings/environmental-measurment-plugin.md rename to docs/settings/environmental-measurment-module.md index 32f45367..8749dc5a 100644 --- a/docs/settings/environmental-measurment-plugin.md +++ b/docs/settings/environmental-measurment-module.md @@ -1,8 +1,9 @@ --- -id: environmental-measurement-plugin -title: Environmental Measurement Plugin Settings -sidebar_label: Environmental Measurement Plugin +id: environmental-measurement-module +title: Environmental Measurement Module Settings +sidebar_label: Environmental Measurement Module --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -11,52 +12,55 @@ GPIO access is fundamentally dangerous because invalid options can physically da ::: + :::note -This plugin requires attaching a peripheral accessory to your device. It will not work without one. +This module requires attaching a peripheral accessory to your device. It will not work without one. ::: ## Overview -The Environment Measurement Plugin will allow nodes to send a specific message with information from connected environmental sensors. Currently supported sensors are BME280, BME680, DHT11, DHT12, DHT21, DHT22 and Dallas 1-wire DS18B20. +The Environment Measurement Module will allow nodes to send a specific message with information from connected environmental sensors. Currently supported sensors are BME280, BME680, DHT11, DHT12, DHT21, DHT22 and Dallas 1-wire DS18B20. :::tip -Once plugin settings are changed, a **reset** is required for them to take effect. +Once module settings are changed, a **reset** is required for them to take effect. ::: ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| environmental_measurement_plugin_display_farenheit | `true`, `false` | `false` | -| environmental_measurement_plugin_measurement_enabled | `true`, `false` | `false` | -| environmental_measurement_plugin_read_error_count_threshold | `integer` | `0` | -| environmental_measurement_plugin_recovery_interval | `integer` (seconds) | `0` | -| environmental_measurement_plugin_screen_enabled | `true`, `false` | `0` | -| environmental_measurement_plugin_sensor_pin | `integer` | `0` | -| environmental_measurement_plugin_sensor_type | `0-6` | `0` | -| environmental_measurement_plugin_update_interval | `integer` (seconds) | `0` | +| Setting | Acceptable Values | Default | +| :-----------------------------------------: | :-----------------: | :-----: | +| telemetry_module_display_farenheit | `true`, `false` | `false` | +| telemetry_module_measurement_enabled | `true`, `false` | `false` | +| telemetry_module_read_error_count_threshold | `integer` | `0` | +| telemetry_module_recovery_interval | `integer` (seconds) | `0` | +| telemetry_module_screen_enabled | `true`, `false` | `0` | +| telemetry_module_sensor_pin | `integer` | `0` | +| telemetry_module_sensor_type | `0-6` | `0` | +| telemetry_module_update_interval | `integer` (seconds) | `0` | -### environmental_measurement_plugin_display_farenheit +### telemetry_module_display_farenheit The sensor is always read in Celsius, but the user can opt to view the temperature display in Fahrenheit using this setting. #### Display Farenheit/Celsius + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Display Farenheit" -meshtastic --set environmental_measurement_plugin_display_farenheit true +meshtastic --set telemetry_module_display_farenheit true ``` + ```bash title="Display Celsius" -meshtastic --set environmental_measurement_plugin_display_farenheit false +meshtastic --set telemetry_module_display_farenheit false ``` @@ -83,28 +87,31 @@ Configuring this setting is not yet available for the selected platform. If this -### environmental_measurement_plugin_measurement_enabled +### telemetry_module_measurement_enabled -Enables the plugin. +Enables the module. + +#### Enable/Disable the module -#### Enable/Disable the plugin - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + -```bash title="Enable Plugin" -meshtastic --set environmental_measurement_plugin_measurement_enabled true +```bash title="Enable Module" +meshtastic --set telemetry_module_measurement_enabled true ``` -```bash title="Disable Plugin" -meshtastic --set environmental_measurement_plugin_measurement_enabled false + +```bash title="Disable Module" +meshtastic --set telemetry_module_measurement_enabled false ``` + @@ -129,25 +136,27 @@ Configuring this setting is not yet available for the selected platform. If this -### environmental_measurement_plugin_read_error_count_threshold +### telemetry_module_read_error_count_threshold Sometimes sensor reads can fail. If this happens, we will retry a configurable number of attempts. Each attempt will be delayed by the minimum required refresh rate for that sensor -#### Configure environmental_measurement_plugin_read_error_count_threshold - - +#### Configure telemetry_module_read_error_count_threshold -```bash title="Configure environmental_measurement_plugin_read_error_count_threshold to 3 tries" -meshtastic --set environmental_measurement_plugin_read_error_count_threshold 3 + + + +```bash title="Configure telemetry_module_read_error_count_threshold to 3 tries" +meshtastic --set telemetry_module_read_error_count_threshold 3 ``` + @@ -172,25 +181,27 @@ Configuring this setting is not yet available for the selected platform. If this -### environmental_measurement_plugin_recovery_interval +### telemetry_module_recovery_interval Sometimes we can end up with more than read_error_count_threshold failures. In this case, we will stop trying to read from the sensor for a while. Wait this long until trying to read from the sensor again. -#### Configure environmental_measurement_plugin_recovery_interval - - +#### Configure telemetry_module_recovery_interval -```bash title="Configure environmental_measurement_plugin_recovery_interval to 120 seconds" -meshtastic --set environmental_measurement_plugin_recovery_interval 120 + + + +```bash title="Configure telemetry_module_recovery_interval to 120 seconds" +meshtastic --set telemetry_module_recovery_interval 120 ``` + @@ -215,28 +226,31 @@ Configuring this setting is not yet available for the selected platform. If this -### environmental_measurement_plugin_screen_enabled +### telemetry_module_screen_enabled -Enable/Disable the environmental measurement plugin on-device display. +Enable/Disable the environmental measurement module on-device display. + +#### Enable/Disable the module on device screen -#### Enable/Disable the plugin on device screen - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Enable on device screen" -meshtastic --set environmental_measurement_plugin_screen_enabled true +meshtastic --set telemetry_module_screen_enabled true ``` + ```bash title="Disable on device screen" -meshtastic --set environmental_measurement_plugin_screen_enabled false +meshtastic --set telemetry_module_screen_enabled false ``` + @@ -261,10 +275,10 @@ Configuring this setting is not yet available for the selected platform. If this -### environmental_measurement_plugin_sensor_pin +### telemetry_module_sensor_pin :::note -The preferred setup is using I2C, so the `environmental_measurement_plugin_sensor_pin` may not be needed. +The preferred setup is using I2C, so the `telemetry_module_sensor_pin` may not be needed. ::: Specify the preferred GPIO Pin for sensor readings. May not be needed if using I2C. @@ -273,20 +287,21 @@ Specify the preferred GPIO Pin for sensor readings. May not be needed if using I To prevent damaging your device, double check your device's schematics before attaching to the GPIO pins and setting this value. ::: -#### Set plugin sensor pin - - +#### Set module sensor pin -```bash title="Set plugin sensor pin" -meshtastic --set environmental_measurement_plugin_sensor_pin PINNUMBER + + + +```bash title="Set module sensor pin" +meshtastic --set telemetry_module_sensor_pin PINNUMBER ``` @@ -313,43 +328,44 @@ Configuring this setting is not yet available for the selected platform. If this -### environmental_measurement_plugin_sensor_type +### telemetry_module_sensor_type Specify the sensor type. -| Value | Description | Sensor Features | -| :---: | :---------: | :-------------: | -| `0` | DHT11 | Temperature, Humidity | -| `1` | DS18B20 (Dallas 1-wire) | Temperature | -| `2` | DHT12 | Temperature, Humidity | -| `3` | DHT21 | Temperature, Humidity | -| `4` | DHT22 | Temperature, Humidity | -| `5` | BME280 | Temperature, Humidity, Pressure | -| `6` | BME680 | Temperature, Humidity, Pressure, VOC Gas | -| `7` | MCP9808 | Precision Temperature | +| Value | Description | Sensor Features | +| :---: | :---------------------: | :--------------------------------------: | +| `0` | DHT11 | Temperature, Humidity | +| `1` | DS18B20 (Dallas 1-wire) | Temperature | +| `2` | DHT12 | Temperature, Humidity | +| `3` | DHT21 | Temperature, Humidity | +| `4` | DHT22 | Temperature, Humidity | +| `5` | BME280 | Temperature, Humidity, Pressure | +| `6` | BME680 | Temperature, Humidity, Pressure, VOC Gas | +| `7` | MCP9808 | Precision Temperature | #### Set sensor type - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note The CLI is able to take the `value` or the `name` of the sensor from the table above. ::: ```bash title="Set sensor type to DS18B20" -meshtastic --set environmental_measurement_plugin_sensor_type 1 +meshtastic --set telemetry_module_sensor_type 1 ``` + ```bash title="Set sensor type to DS18B20" -meshtastic --set environmental_measurement_plugin_sensor_type DS18B20 +meshtastic --set telemetry_module_sensor_type DS18B20 ``` @@ -376,24 +392,25 @@ Configuring this setting is not yet available for the selected platform. If this -### environmental_measurement_plugin_update_interval +### telemetry_module_update_interval Interval in seconds of how often we should try to send our measurements to the mesh. -#### Set plugin update interval - - +#### Set module update interval -```bash title="Set plugin update interval to 15 seconds" -meshtastic --set environmental_measurement_plugin_update_interval 15 + + + +```bash title="Set module update interval to 15 seconds" +meshtastic --set telemetry_module_update_interval 15 ``` @@ -428,4 +445,4 @@ The sensors can be wired differently, here's [one example](https://randomnerdtut ### Known Problems -* No default configuration values are currently set, so this must be done when enabling the plugin. +- No default configuration values are currently set, so this must be done when enabling the module. diff --git a/docs/settings/external-notification-plugin.md b/docs/settings/external-notification-module.md similarity index 65% rename from docs/settings/external-notification-plugin.md rename to docs/settings/external-notification-module.md index bd75a9a2..b41dafba 100644 --- a/docs/settings/external-notification-plugin.md +++ b/docs/settings/external-notification-module.md @@ -1,8 +1,9 @@ --- -id: external-notification-plugin -title: External Notification Plugin Settings -sidebar_label: External Notification Plugin +id: external-notification-module +title: External Notification Module Settings +sidebar_label: External Notification Module --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -11,30 +12,31 @@ GPIO access is fundamentally dangerous because invalid options can physically da ::: + :::note -This plugin requires attaching a peripheral accessory to your device. It will not work without one. +This module requires attaching a peripheral accessory to your device. It will not work without one. ::: ## Overview -The External Notification Plugin will allow you to connect a speaker, LED, or other device to notify you when a message has been received from the mesh network. +The External Notification Module will allow you to connect a speaker, LED, or other device to notify you when a message has been received from the mesh network. :::tip -Once plugin settings are changed, a **reset** is required for them to take effect. +Once module settings are changed, a **reset** is required for them to take effect. ::: ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| ext_notification_plugin_active | `true`, `false` | `false` | -| ext_notification_plugin_alert_bell | `true`, `false` | `false` | -| ext_notification_plugin_alert_message | `true`, `false` | `false` | -| ext_notification_plugin_enabled | `true`, `false` | `false` | -| ext_notification_plugin_output | `integer` | `0` | -| ext_notification_plugin_output_ms | `integer` (milliseconds) | `0` | +| Setting | Acceptable Values | Default | +| :-----------------------------------: | :----------------------: | :-----: | +| ext_notification_module_active | `true`, `false` | `false` | +| ext_notification_module_alert_bell | `true`, `false` | `false` | +| ext_notification_module_alert_message | `true`, `false` | `false` | +| ext_notification_module_enabled | `true`, `false` | `false` | +| ext_notification_module_output | `integer` | `0` | +| ext_notification_module_output_ms | `integer` (milliseconds) | `0` | -### ext_notification_plugin_active +### ext_notification_module_active Specifies whether the external circuit is triggered when the device's GPIO is low or high. @@ -43,23 +45,26 @@ To prevent damaging your device, double check your device's schematics before at ::: #### Specify High/Low GPIO triggers circuit + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="GPIO active high" -meshtastic --set ext_notification_plugin_active true +meshtastic --set ext_notification_module_active true ``` + ```bash title="GPIO active low (default)" -meshtastic --set ext_notification_plugin_active false +meshtastic --set ext_notification_module_active false ``` + @@ -84,28 +89,31 @@ Configuring this setting is not yet available for the selected platform. If this -### ext_notification_plugin_alert_bell +### ext_notification_module_alert_bell Specifies if an alert should be sent when receiving an incoming bell. #### Enable/Disable alert on incoming bell + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Enable alert on incoming bell" -meshtastic --set ext_notification_plugin_alert_bell true +meshtastic --set ext_notification_module_alert_bell true ``` + ```bash title="Disable alert on incoming bell" -meshtastic --set ext_notification_plugin_alert_bell false +meshtastic --set ext_notification_module_alert_bell false ``` + @@ -130,28 +138,31 @@ Configuring this setting is not yet available for the selected platform. If this -### ext_notification_plugin_alert_message +### ext_notification_module_alert_message Specifies if an alert should be sent when receiving an incoming message. #### Enable/Disable Alert on incoming message + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Enable alert on incoming message" -meshtastic --set ext_notification_plugin_alert_message true +meshtastic --set ext_notification_module_alert_message true ``` + ```bash title="Disable alert on incoming message" -meshtastic --set ext_notification_plugin_alert_message false +meshtastic --set ext_notification_module_alert_message false ``` + @@ -176,28 +187,31 @@ Configuring this setting is not yet available for the selected platform. If this -### ext_notification_plugin_enabled +### ext_notification_module_enabled -Enables the plugin. +Enables the module. + +#### Enable/Disable the module -#### Enable/Disable the plugin - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + -```bash title="Enable Plugin" -meshtastic --set ext_notification_plugin_enabled true +```bash title="Enable Module" +meshtastic --set ext_notification_module_enabled true ``` -```bash title="Disable Plugin" -meshtastic --set ext_notification_plugin_enabled false + +```bash title="Disable Module" +meshtastic --set ext_notification_module_enabled false ``` + @@ -222,7 +236,7 @@ Configuring this setting is not yet available for the selected platform. If this -### ext_notification_plugin_output +### ext_notification_module_output Specifies the GPIO that your external circuit is attached to on the device. @@ -231,24 +245,26 @@ To prevent damaging your device, double check your device's schematics before at ::: #### Specify GPIO for circuit to monitor + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note Replace `GPIO` in the below command with the GPIO number your circuit is attached to. ::: ```bash title="Specify GPIO that circuit is connected to" -meshtastic --set ext_notification_plugin_output GPIO +meshtastic --set ext_notification_module_output GPIO ``` + @@ -273,28 +289,31 @@ Configuring this setting is not yet available for the selected platform. If this -### ext_notification_plugin_output_ms +### ext_notification_module_output_ms Specifies how long in milliseconds you would like your external circuit triggered. Default is `1000`. (Because of the way that defaults are handled in the protobufs `0` is interpreted as `1000`) #### Specify how many milliseconds to trigger circuit + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + ```bash title="Set to default (1000ms)" -meshtastic --set ext_notification_plugin_output_ms 0 +meshtastic --set ext_notification_module_output_ms 0 ``` + ```bash title="Set to other value" -meshtastic --set ext_notification_plugin_output_ms 1500 +meshtastic --set ext_notification_module_output_ms 1500 ``` + diff --git a/docs/settings/mqtt.md b/docs/settings/mqtt.md index 877f4c9e..5d5f8273 100644 --- a/docs/settings/mqtt.md +++ b/docs/settings/mqtt.md @@ -19,48 +19,52 @@ You may want to change your [GPS location sharing settings](gps#location_share) If your device is connected to WiFi you can enable it to forward messages along to an MQTT server. This allows users on the local mesh to communicate with users on the internet. -Be sure to checkout this [MQTT](https://meshtastic.org/docs/software/other/mqtt) too. +Be sure to checkout this [MQTT](/docs/software/other/mqtt) too. ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| downlink_enabled | `true`, `false` | `false` | -| mqtt_disabled | `true`, `false` | `false` | -| mqtt_encryption_enabled | `true`, `false` | `false` | -| mqtt_password | `string` | `""` | -| mqtt_server | `string` | `""` | -| mqtt_username | `string` | `""` | -| uplink_enabled | `true`, `false` | `false` | +| Setting | Acceptable Values | Default | +| :---------------------: | :---------------: | :-----: | +| downlink_enabled | `true`, `false` | `false` | +| mqtt_disabled | `true`, `false` | `false` | +| mqtt_encryption_enabled | `true`, `false` | `false` | +| mqtt_password | `string` | `""` | +| mqtt_server | `string` | `""` | +| mqtt_username | `string` | `""` | +| uplink_enabled | `true`, `false` | `false` | ### downlink_enabled This is a channel specific setting. If your channel has this set to `true` and you are connected to WiFi, the device will forward along messages from the MQTT server specified [here](#mqtt_server) to the mesh from this device. #### Enable/Disable downlink_enabled - - - ```bash title="Enable downlink_enabled on PRIMARY channel" - meshtastic --ch-set downlink_enabled true --ch-index 0 - ``` - ```bash title="Disable downlink_enabled on PRIMARY channel" - meshtastic --ch-set downlink_enabled false --ch-index 0 - ``` - ```bash title="Enable downlink_enabled on OTHER channel" - meshtastic --ch-set downlink_enabled true --ch-index 1 - ``` - ```bash title="Disable downlink_enabled on OTHER channel" - meshtastic --ch-set downlink_enabled false --ch-index 1 - ``` + + + +```bash title="Enable downlink_enabled on PRIMARY channel" +meshtastic --ch-set downlink_enabled true --ch-index 0 +``` + +```bash title="Disable downlink_enabled on PRIMARY channel" +meshtastic --ch-set downlink_enabled false --ch-index 0 +``` + +```bash title="Enable downlink_enabled on OTHER channel" +meshtastic --ch-set downlink_enabled true --ch-index 1 +``` + +```bash title="Disable downlink_enabled on OTHER channel" +meshtastic --ch-set downlink_enabled false --ch-index 1 +``` @@ -91,23 +95,25 @@ Configuring this setting is not yet available for the selected platform. If this If a meshtastic node is able to reach the internet it will normally attempt to gateway any channels that are marked as `uplink_enabled` or `downlink_enabled`. But if this flag is set, all MQTT features will be disabled and no servers will be contacted. #### Enable/Disable MQTT - - - ```bash title="Enable MQTT (Default)" - meshtastic --set mqtt_disabled false - ``` - ```bash title="Disable MQTT" - meshtastic --set mqtt_disabled true - ``` + + + +```bash title="Enable MQTT (Default)" +meshtastic --set mqtt_disabled false +``` + +```bash title="Disable MQTT" +meshtastic --set mqtt_disabled true +``` @@ -142,23 +148,25 @@ If you are using the default Meshtastic MQTT server, this setting will take no e ::: #### Enable/Disable MQTT Encryption - - - ```bash title="Publish decrypted packets to MQTT (Default)" - meshtastic --set mqtt_encryption_enabled false - ``` - ```bash title="Publish encrypted packets to MQTT" - meshtastic --set mqtt_encryption_enabled true - ``` + + + +```bash title="Publish decrypted packets to MQTT (Default)" +meshtastic --set mqtt_encryption_enabled false +``` + +```bash title="Publish encrypted packets to MQTT" +meshtastic --set mqtt_encryption_enabled true +``` @@ -189,26 +197,29 @@ Configuring this setting is not yet available for the selected platform. If this MQTT password to use (most useful for a custom MQTT server). If using a custom server, this will be honoured even if empty. If using the default server, this will only be honoured if set, otherwise the device will use the default password `large4cats`. #### Configure mqtt_password - - - ```bash title="Set mqtt_password" - meshtastic --set mqtt_password mypassword - ``` - ```bash title="Set mqtt_password (with spaces)" - meshtastic --set mqtt_password "my password" - ``` - ```bash title="Unset mqtt_password (Default)" - meshtastic --set mqtt_password "" - ``` + + + +```bash title="Set mqtt_password" +meshtastic --set mqtt_password mypassword +``` + +```bash title="Set mqtt_password (with spaces)" +meshtastic --set mqtt_password "my password" +``` + +```bash title="Unset mqtt_password (Default)" +meshtastic --set mqtt_password "" +``` @@ -239,30 +250,33 @@ Configuring this setting is not yet available for the selected platform. If this The server to use for our MQTT global message gateway feature. If not set, the default server will be used #### Enable/Disable MQTT Server + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::tip When the mqtt_server is set to `""`, it will default to `mqtt.meshtastic.org` ::: - ```bash title="Enable MQTT Server - Public Meshtastic MQTT Server (Default)" - meshtastic --set mqtt_server "" - ``` - ```bash title="Enable MQTT Server - Personal MQTT Server (by IP)" - meshtastic --set mqtt_server 198.168.0.2 - ``` - ```bash title="Enable MQTT Server - Personal MQTT Server (by URL)" - meshtastic --set mqtt_server mqtt.mydomain.com - ``` +```bash title="Enable MQTT Server - Public Meshtastic MQTT Server (Default)" +meshtastic --set mqtt_server "" +``` + +```bash title="Enable MQTT Server - Personal MQTT Server (by IP)" +meshtastic --set mqtt_server 198.168.0.2 +``` + +```bash title="Enable MQTT Server - Personal MQTT Server (by URL)" +meshtastic --set mqtt_server mqtt.mydomain.com +``` @@ -293,26 +307,29 @@ Configuring this setting is not yet available for the selected platform. If this MQTT username to use (most useful for a custom MQTT server). If using a custom server, this will be honoured even if empty. If using the default server, this will only be honoured if set, otherwise the device will use the default username `meshdev`. #### Configure mqtt_username - - - ```bash title="Set mqtt_username" - meshtastic --set mqtt_username myusername - ``` - ```bash title="Set mqtt_username (with spaces)" - meshtastic --set mqtt_username "my username" - ``` - ```bash title="Unset mqtt_username (Default)" - meshtastic --set mqtt_username "" - ``` + + + +```bash title="Set mqtt_username" +meshtastic --set mqtt_username myusername +``` + +```bash title="Set mqtt_username (with spaces)" +meshtastic --set mqtt_username "my username" +``` + +```bash title="Unset mqtt_username (Default)" +meshtastic --set mqtt_username "" +``` @@ -343,29 +360,33 @@ Configuring this setting is not yet available for the selected platform. If this This is a channel specific setting. If your channel has this set to `true` and you are connected to WiFi, the device will forward along messages to whatever MQTT server is specified in [mqtt_server](#mqtt_server). #### Enable/Disable uplink_enabled - - - ```bash title="Enable uplink_enabled on PRIMARY channel" - meshtastic --ch-set uplink_enabled true --ch-index 0 - ``` - ```bash title="Disable uplink_enabled on PRIMARY channel" - meshtastic --ch-set uplink_enabled false --ch-index 0 - ``` - ```bash title="Enable uplink_enabled on OTHER channel" - meshtastic --ch-set uplink_enabled true --ch-index 1 - ``` - ```bash title="Disable uplink_enabled on OTHER channel" - meshtastic --ch-set uplink_enabled false --ch-index 1 - ``` + + + +```bash title="Enable uplink_enabled on PRIMARY channel" +meshtastic --ch-set uplink_enabled true --ch-index 0 +``` + +```bash title="Disable uplink_enabled on PRIMARY channel" +meshtastic --ch-set uplink_enabled false --ch-index 0 +``` + +```bash title="Enable uplink_enabled on OTHER channel" +meshtastic --ch-set uplink_enabled true --ch-index 1 +``` + +```bash title="Disable uplink_enabled on OTHER channel" +meshtastic --ch-set uplink_enabled false --ch-index 1 +``` @@ -406,7 +427,7 @@ values={[ {label: 'iOS', value: 'iOS'}, {label: 'Web', value: 'web'}, ]}> - + ```bash title="Set server" meshtastic --set mqtt_server 192.168.123.234 @@ -423,8 +444,8 @@ mosquitto_sub -h 192.168.123.234 -v -t msh/# :::note FIXME some documentation says msh/# , some says mesh/# . As of 1.2.39 the messages are on msh/# ::: - - + + :::info Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page. diff --git a/docs/settings/range-test-plugin.md b/docs/settings/range-test-module.md similarity index 71% rename from docs/settings/range-test-plugin.md rename to docs/settings/range-test-module.md index 44cd9450..bacd1211 100644 --- a/docs/settings/range-test-plugin.md +++ b/docs/settings/range-test-module.md @@ -1,7 +1,7 @@ --- -id: range-test-plugin -title: Range Test Plugin Settings -sidebar_label: Range Test Plugin +id: range-test-module +title: Range Test Module Settings +sidebar_label: Range Test Module --- import Tabs from '@theme/Tabs'; @@ -9,42 +9,44 @@ import TabItem from '@theme/TabItem'; ## Overview -This plugin allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh. +This module allows you to test the range of your Meshtastic nodes. It requires at least two nodes, a sender and a receiver. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into [Google Earth](https://earth.google.com), [Google Maps - My Maps](https://mymaps.google.com), or any other program capable of processing .csv files. This can enable you to visualize your mesh. :::tip -Once plugin settings are changed, a **reset** is required for them to take effect. +Once module settings are changed, a **reset** is required for them to take effect. ::: ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| range_test_plugin_enabled | `true`, `false` | `false` | -| range_test_plugin_save | `true`, `false` | `false` | -| range_test_plugin_sender | `integer` (Seconds) | `0` | +| Setting | Acceptable Values | Default | +| :-----------------------: | :-----------------: | :-----: | +| range_test_module_enabled | `true`, `false` | `false` | +| range_test_module_save | `true`, `false` | `false` | +| range_test_module_sender | `integer` (Seconds) | `0` | -### range_test_plugin_enabled +### range_test_module_enabled -Enables the plugin. +Enables the module. + +#### Enable/Disable the module -#### Enable/Disable the plugin - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Enable the plugin" - meshtastic --set range_test_plugin_enabled true - ``` - ```bash title="Disable the plugin" - meshtastic --set range_test_plugin_enabled true - ``` +```bash title="Enable the module" +meshtastic --set range_test_module_enabled true +``` + +```bash title="Disable the module" +meshtastic --set range_test_module_enabled true +``` @@ -70,28 +72,30 @@ Configuring this setting is not yet available for the selected platform. If this -### range_test_plugin_save +### range_test_module_save If enabled, we will save a log of all received messages to `/static/rangetest.csv` which you can access from the web server. We will abort writing if there is less than 50k of space on the filesystem to prevent filling up the storage. #### Enable/Disable range test save `csv` - - - ```bash title="Enable range test save" - meshtastic --set range_test_plugin_save true - ``` - ```bash title="Disable range test save" - meshtastic --set range_test_plugin_save false - ``` + + + +```bash title="Enable range test save" +meshtastic --set range_test_module_save true +``` + +```bash title="Disable range test save" +meshtastic --set range_test_module_save false +``` @@ -117,28 +121,30 @@ Configuring this setting is not yet available for the selected platform. If this -### range_test_plugin_sender +### range_test_module_sender Number of seconds to wait between sending packets. Using the long_slow channel configuration, it's best not to go more frequent than once every 60 seconds. You can be more aggressive with faster settings. `0` is default which disables sending messages. #### Enable/Disable range test sender - - - ```bash title="Enable range test sender (send every 60 seconds)" - meshtastic --set range_test_plugin_sender 60 - ``` - ```bash title="Disable range test sender" - meshtastic --set range_test_plugin_sender 0 - ``` + + + +```bash title="Enable range test sender (send every 60 seconds)" +meshtastic --set range_test_module_sender 60 +``` + +```bash title="Disable range test sender" +meshtastic --set range_test_module_sender 0 +``` @@ -166,14 +172,14 @@ Configuring this setting is not yet available for the selected platform. If this ## Details -While a minimum of two radios is required, more can be used. You can have any number of receivers and senders that your mesh is able to handle. You can test having a single sender with multiple receivers or a single receiver with multiple senders. Let us know on the [forum thread](https://meshtastic.discourse.group/t/new-plugin-rangetestplugin/2591/) the results of your configuration. +While a minimum of two radios is required, more can be used. You can have any number of receivers and senders that your mesh is able to handle. You can test having a single sender with multiple receivers or a single receiver with multiple senders. Let us know on the [forum thread](https://meshtastic.discourse.group/t/new-plugin-rangetestplugin/2591) the results of your configuration. -Be sure to turn off either the plugin configured as a sender or the device where the plugin setup as sender when not in use. This will use a lot of time on air and will spam your channel. +Be sure to turn off either the module configured as a sender or the device where the module setup as sender when not in use. This will use a lot of time on air and will spam your channel. Also be mindful of your space usage on the file system. It has protections from filling up the space but it's best to delete old range test results. :::note -Leaving this plugin on can slow down your mesh. Currently, the messages are sent using the same `TEXT_MESSAGE_APP` [port that all other messages](/docs/developers/protobufs/api#portnumsproto) are sent on. +Leaving this module on can slow down your mesh. Currently, the messages are sent using the same `TEXT_MESSAGE_APP` [port that all other messages](/docs/developers/protobufs/api#portnumsproto) are sent on. ::: ### Accessing your CSV @@ -187,7 +193,7 @@ http://198.168.0.X/static/rangetest.csv ### Recommended Sender Settings -| Radio Setting | `range_test_plugin_sender` | +| Radio Setting | `range_test_module_sender` | | :-----------: | :------------------------: | | Long Slow | 60 | | Long Alt | 30 | @@ -210,8 +216,8 @@ values={[ ```bash title="Example - Sender Node" -meshtastic --set range_test_plugin_enabled true -meshtastic --set range_test_plugin_sender 60 +meshtastic --set range_test_module_enabled true +meshtastic --set range_test_module_sender 60 ``` @@ -252,8 +258,8 @@ values={[ ```bash title="Example - Receiver Node" -meshtastic --set range_test_plugin_enabled true -meshtastic --set range_test_plugin_save true +meshtastic --set range_test_module_enabled true +meshtastic --set range_test_module_save true ``` diff --git a/docs/settings/rotary-encoder-plugin.md b/docs/settings/rotary-encoder-module.md similarity index 63% rename from docs/settings/rotary-encoder-plugin.md rename to docs/settings/rotary-encoder-module.md index d6b8a5ae..93e8ecb7 100644 --- a/docs/settings/rotary-encoder-plugin.md +++ b/docs/settings/rotary-encoder-module.md @@ -1,8 +1,9 @@ --- -id: rotary-encoder-plugin +id: rotary-encoder-module title: Rotary Encoder sidebar_label: Rotary Encoder --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -11,8 +12,9 @@ GPIO access is fundamentally dangerous because invalid options can physically da ::: + :::note -This plugin requires attaching a peripheral accessory to your device. It will not work without one. +This module requires attaching a peripheral accessory to your device. It will not work without one. ::: ## Overview @@ -22,42 +24,45 @@ Currently, one rotary encoder (`rotary1`) is defined, but later more rotary enco can be added (if needed) the same way. :::tip -Once plugin settings are changed, a **reset** is required for them to take effect. +Once module settings are changed, a **reset** is required for them to take effect. ::: ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| rotary1_enabled | `true`, `false` | `false` | -| rotary1_event_cw | `InputEventChar` | (not defined) | -| rotary1_event_ccw | `InputEventChar` | (not defined) | -| rotary1_event_press | `InputEventChar` | (not defined) | -| rotary1_pin_a | `integer` | (not defined) | -| rotary1_pin_b | `integer` | (not defined) | -| rotary1_pin_press | `integer` | (not defined) | +| Setting | Acceptable Values | Default | +| :-----------------: | :---------------: | :-----------: | +| rotary1_enabled | `true`, `false` | `false` | +| rotary1_event_cw | `InputEventChar` | (not defined) | +| rotary1_event_ccw | `InputEventChar` | (not defined) | +| rotary1_event_press | `InputEventChar` | (not defined) | +| rotary1_pin_a | `integer` | (not defined) | +| rotary1_pin_b | `integer` | (not defined) | +| rotary1_pin_press | `integer` | (not defined) | ### rotary1_enabled + Enable the rotary encoder #1 #### Enable/Disable rotary1 - - - ```bash title="Enable rotary1" - meshtastic --set rotary1_enabled true - ``` - ```bash title="Disable rotary1" - meshtastic --set rotary1_enabled true - ``` + + + +```bash title="Enable rotary1" +meshtastic --set rotary1_enabled true +``` + +```bash title="Disable rotary1" +meshtastic --set rotary1_enabled true +``` @@ -81,30 +86,33 @@ Configuring this setting is not yet available for the selected platform. If this ### rotary1_event_cw + Generate input event on CW of this kind. :::tip -For using with CannedMessagePlugin you must choose value `KEY_UP` here. +For using with CannedMessageModule you must choose value `KEY_UP` here. ::: #### Specify rotary1 event cw - - - ```bash title="Set rotary1 event cw to 'KEY_UP'" - meshtastic --set rotary1_event_press KEY_UP - ``` - ```bash title="Unset rotary1 event cw" - meshtastic --set rotary1_event_press "" - ``` + + + +```bash title="Set rotary1 event cw to 'KEY_UP'" +meshtastic --set rotary1_event_press KEY_UP +``` + +```bash title="Unset rotary1 event cw" +meshtastic --set rotary1_event_press "" +``` @@ -128,30 +136,33 @@ Configuring this setting is not yet available for the selected platform. If this ### rotary1_event_ccw + Generate input event on CCW of this kind. :::tip -For using with CannedMessagePlugin you must choose value `KEY_DOWN` here. +For using with CannedMessageModule you must choose value `KEY_DOWN` here. ::: #### Specify rotary1 event ccw - - - ```bash title="Set rotary1 event ccw to 'KEY_DOWN'" - meshtastic --set rotary1_event_ccw KEY_DOWN - ``` - ```bash title="Unset rotary1 event ccw" - meshtastic --set rotary1_event_ccw "" - ``` + + + +```bash title="Set rotary1 event ccw to 'KEY_DOWN'" +meshtastic --set rotary1_event_ccw KEY_DOWN +``` + +```bash title="Unset rotary1 event ccw" +meshtastic --set rotary1_event_ccw "" +``` @@ -175,30 +186,33 @@ Configuring this setting is not yet available for the selected platform. If this ### rotary1_event_press + Generate input event on Press of this kind. :::tip -For using with CannedMessagePlugin you must choose value `KEY_SELECT` here. +For using with CannedMessageModule you must choose value `KEY_SELECT` here. ::: #### Specify rotary1 event press - - - ```bash title="Set rotary1 event press to 'KEY_SELECT'" - meshtastic --set rotary1_event_press KEY_SELECT - ``` - ```bash title="Unset rotary1 event press" - meshtastic --set rotary1_event_press "" - ``` + + + +```bash title="Set rotary1 event press to 'KEY_SELECT'" +meshtastic --set rotary1_event_press KEY_SELECT +``` + +```bash title="Unset rotary1 event press" +meshtastic --set rotary1_event_press "" +``` @@ -222,6 +236,7 @@ Configuring this setting is not yet available for the selected platform. If this ### rotary1_pin_a + GPIO pin for rotary encoder A port. :::caution @@ -229,24 +244,25 @@ To prevent damaging your device, double check your device's schematics before at ::: #### Specify rotary1 pin a + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note Replace `GPIO` below with the GPIO number from hardware setup. ::: - ```bash title="Specify rotary1 pin a" - meshtastic --set rotary1_pin_a GPIO - ``` +```bash title="Specify rotary1 pin a" +meshtastic --set rotary1_pin_a GPIO +``` @@ -270,6 +286,7 @@ Configuring this setting is not yet available for the selected platform. If this ### rotary1_pin_b + GPIO pin for rotary encoder B port. :::caution @@ -277,24 +294,25 @@ To prevent damaging your device, double check your device's schematics before at ::: #### Specify rotary1 pin b + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note Replace `GPIO` below with the GPIO number from hardware setup. ::: - ```bash title="Specify rotary1 pin b" - meshtastic --set rotary1_pin_b GPIO - ``` +```bash title="Specify rotary1 pin b" +meshtastic --set rotary1_pin_b GPIO +``` @@ -318,6 +336,7 @@ Configuring this setting is not yet available for the selected platform. If this ### rotary1_pin_press + GPIO pin for rotary encoder Press port. :::caution @@ -325,24 +344,25 @@ To prevent damaging your device, double check your device's schematics before at ::: #### Specify rotary1 pin press + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note Replace `GPIO` below with the GPIO number from hardware setup. ::: - ```bash title="Specify rotary1 pin press" - meshtastic --set rotary1_pin_press GPIO - ``` +```bash title="Specify rotary1 pin press" +meshtastic --set rotary1_pin_press GPIO +``` @@ -369,35 +389,37 @@ Configuring this setting is not yet available for the selected platform. If this -Configuring the rotary encoder plugin require attaching the compatible hardware. +Configuring the rotary encoder module require attaching the compatible hardware. ## Examples -### Configure rotary encoder for Canned Message Plugin +### Configure rotary encoder for Canned Message Module + - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note Replace each `GPIO` (x3) below with the GPIO numbers from hardware setup. ::: - ```bash title="Canned Message Plugin - Required Rotary Encoder Plugin Settings" - meshtastic --set rotary1_pin_a GPIO - meshtastic --set rotary1_pin_b GPIO - meshtastic --set rotary1_pin_press GPIO - meshtastic --set rotary1_event_cw KEY_UP - meshtastic --set rotary1_event_ccw KEY_DOWN - meshtastic --set rotary1_event_press KEY_SELECT - meshtastic --set rotary1_enabled True - ``` +```bash title="Canned Message Module - Required Rotary Encoder Module Settings" +meshtastic --set rotary1_pin_a GPIO +meshtastic --set rotary1_pin_b GPIO +meshtastic --set rotary1_pin_press GPIO +meshtastic --set rotary1_event_cw KEY_UP +meshtastic --set rotary1_event_ccw KEY_DOWN +meshtastic --set rotary1_event_press KEY_SELECT +meshtastic --set rotary1_enabled True +``` + :::info diff --git a/docs/settings/serial-plugin.md b/docs/settings/serial-module.md similarity index 65% rename from docs/settings/serial-plugin.md rename to docs/settings/serial-module.md index 60013bfc..28de486c 100644 --- a/docs/settings/serial-plugin.md +++ b/docs/settings/serial-module.md @@ -1,8 +1,9 @@ --- -id: serial-plugin -title: Serial Plugin Settings -sidebar_label: Serial Plugin +id: serial-module +title: Serial Module Settings +sidebar_label: Serial Module --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -11,7 +12,7 @@ GPIO access is fundamentally dangerous because invalid options can physically da ::: :::note -This plugin requires attaching a peripheral accessory to your device. It will not work without one. +This module requires attaching a peripheral accessory to your device. It will not work without one. ::: ## Overview @@ -19,41 +20,42 @@ This plugin requires attaching a peripheral accessory to your device. It will no This is a simple interface to send messages over the mesh network by sending strings over a serial port. :::tip -Once plugin settings are changed, a **reset** is required for them to take effect. +Once module settings are changed, a **reset** is required for them to take effect. ::: ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| serialplugin_enabled | `true`, `false` | `false` | -| serialplugin_echo | `true`, `false` | `false` | -| serialplugin_mode | `integer` | `0` | -| serialplugin_rxd | `integer` (GPIO) | `0` | -| serialplugin_timeout | `integer` (seconds) | `0` | -| serialplugin_txd | `integer` (GPIO) | `0` | +| Setting | Acceptable Values | Default | +| :-------------------: | :-----------------: | :-----: | +| serial_module_enabled | `true`, `false` | `false` | +| serial_module_echo | `true`, `false` | `false` | +| serial_module_mode | `integer` | `0` | +| serial_module_rxd | `integer` (GPIO) | `0` | +| serial_module_timeout | `integer` (seconds) | `0` | +| serial_module_txd | `integer` (GPIO) | `0` | -### serialplugin_enabled +### serial_module_enabled -Enables the plugin. +Enables the module. - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Enable plugin" - meshtastic --set serialplugin_enabled true - ``` - ```bash title="Disable plugin" - meshtastic --set serialplugin_enabled false - ``` +```bash title="Enable module" +meshtastic --set serial_module_enabled true +``` + +```bash title="Disable module" +meshtastic --set serial_module_enabled false +``` @@ -79,27 +81,28 @@ Configuring this setting is not yet available for the selected platform. If this -### serialplugin_echo +### serial_module_echo If set, any packets you send will be echoed back to your device. - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Enable serialplugin_echo" - meshtastic --set serialplugin_echo true - ``` - ```bash title="Disable serialplugin_echo" - meshtastic --set serialplugin_echo false - ``` +```bash title="Enable serial_module_echo" +meshtastic --set serial_module_echo true +``` + +```bash title="Disable serial_module_echo" +meshtastic --set serial_module_echo false +``` @@ -125,20 +128,20 @@ Configuring this setting is not yet available for the selected platform. If this -### serialplugin_mode +### serial_module_mode - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::info Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page. @@ -168,7 +171,7 @@ Configuring this setting is not yet available for the selected platform. If this -### serialplugin_rxd +### serial_module_rxd Set the GPIO pin to the RXD pin you have set up. @@ -177,23 +180,23 @@ To prevent damaging your device, double check your device's schematics before at ::: - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note Replace `GPIO` in the below command with the GPIO number your circuit is attached to. ::: - ```bash title="Set RXD to GPIO pin number" - meshtastic --set serialplugin_rxd GPIO - ``` +```bash title="Set RXD to GPIO pin number" +meshtastic --set serial_module_rxd GPIO +``` @@ -219,24 +222,24 @@ Configuring this setting is not yet available for the selected platform. If this -### serialplugin_timeout +### serial_module_timeout The amount of time to wait before we consider your packet as "done". - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Set serialplugin_timeout to 15 seconds" - meshtastic --set serialplugin_timeout 15 - ``` +```bash title="Set serial_module_timeout to 15 seconds" +meshtastic --set serial_module_timeout 15 +``` @@ -262,7 +265,7 @@ Configuring this setting is not yet available for the selected platform. If this -### serialplugin_txd +### serial_module_txd Set the GPIO pin to the TXD pin you have set up. @@ -271,23 +274,23 @@ To prevent damaging your device, double check your device's schematics before at ::: - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + :::note Replace `GPIO` in the below command with the GPIO number your circuit is attached to. ::: - ```bash title="Set TXD to GPIO pin number" - meshtastic --set serialplugin_txd GPIO - ``` +```bash title="Set TXD to GPIO pin number" +meshtastic --set serial_module_txd GPIO +``` diff --git a/docs/settings/store-and-forward-plugin.md b/docs/settings/store-and-forward-module.md similarity index 56% rename from docs/settings/store-and-forward-plugin.md rename to docs/settings/store-and-forward-module.md index d537353e..0fd87f00 100644 --- a/docs/settings/store-and-forward-plugin.md +++ b/docs/settings/store-and-forward-module.md @@ -1,15 +1,16 @@ --- -id: store-and-forward-plugin +id: store-and-forward-module title: Store and Forward Settings sidebar_label: Store and Forward --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info Currently only available for ESP32 based devices with external PSRAM. Requires the device to be set as a router. -**Don't enable Store and Forward Plugin on multiple [routers](router).** +**Don't enable Store and Forward Module on multiple [routers](router).** ::: ## Overview @@ -18,45 +19,46 @@ Currently only available for ESP32 based devices with external PSRAM. Requires t This is a work in progress and is partially available. Stability is not guaranteed. ::: -The Store Forward Plugin is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network. +The Store Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network. Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage nor is it advised to use this for SF12 (Long Range / Slow). :::tip -Once plugin settings are changed, a **reset** is required for them to take effect. +Once module settings are changed, a **reset** is required for them to take effect. ::: ## Settings -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| store_forward_plugin_enabled | `true`, `false` | `false` | -| store_forward_plugin_heartbeat | `true`, `false` | `false` | -| store_forward_plugin_history_return_max | `integer` | `0` | -| store_forward_plugin_history_return_window | `integer` | `0` | -| store_forward_plugin_records | `integer` | `0` | +| Setting | Acceptable Values | Default | +| :----------------------------------------: | :---------------: | :-----: | +| store_forward_module_enabled | `true`, `false` | `false` | +| store_forward_module_heartbeat | `true`, `false` | `false` | +| store_forward_module_history_return_max | `integer` | `0` | +| store_forward_module_history_return_window | `integer` | `0` | +| store_forward_module_records | `integer` | `0` | -### store_forward_plugin_enabled +### store_forward_module_enabled -Enables the plugin. +Enables the module. - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Enable the plugin" - meshtastic --set store_forward_plugin_enabled true - ``` - ```bash title="Disable the plugin" - meshtastic --set store_forward_plugin_enabled false - ``` +```bash title="Enable the module" +meshtastic --set store_forward_module_enabled true +``` + +```bash title="Disable the module" +meshtastic --set store_forward_module_enabled false +``` @@ -82,24 +84,24 @@ Configuring this setting is not yet available for the selected platform. If this -### store_forward_plugin_heartbeat +### store_forward_module_heartbeat The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. A client like Android, iOS, or Web can (if supported) indicate to the user whether a store and forward router is available. - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Set store_forward_plugin_heartbeat to default" - meshtastic --set store_forward_plugin_heartbeat 0 - ``` +```bash title="Set store_forward_module_heartbeat to default" +meshtastic --set store_forward_module_heartbeat 0 +``` @@ -125,28 +127,28 @@ Configuring this setting is not yet available for the selected platform. If this - -### store_forward_plugin_history_return_max +### store_forward_module_history_return_max Sets the maximum number of messages to return to a client device. - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Set store_forward_plugin_history_return_max to default" - meshtastic --set store_forward_plugin_history_return_max 0 - ``` - ```bash title="Set store_forward_plugin_history_return_max to 100 messages" - meshtastic --set store_forward_plugin_history_return_max 100 - ``` +```bash title="Set store_forward_module_history_return_max to default" +meshtastic --set store_forward_module_history_return_max 0 +``` + +```bash title="Set store_forward_module_history_return_max to 100 messages" +meshtastic --set store_forward_module_history_return_max 100 +``` @@ -172,28 +174,28 @@ Configuring this setting is not yet available for the selected platform. If this - -### store_forward_plugin_history_return_window +### store_forward_module_history_return_window Limits the time period (in minutes) a client device can request. - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Set store_forward_plugin_history_return_window to default" - meshtastic --set store_forward_plugin_history_return_window 0 - ``` - ```bash title="Set store_forward_plugin_history_return_window to 1 day (1440 minutes)" - meshtastic --set store_forward_plugin_history_return_window 1440 - ``` +```bash title="Set store_forward_module_history_return_window to default" +meshtastic --set store_forward_module_history_return_window 0 +``` + +```bash title="Set store_forward_module_history_return_window to 1 day (1440 minutes)" +meshtastic --set store_forward_module_history_return_window 1440 +``` @@ -219,28 +221,28 @@ Configuring this setting is not yet available for the selected platform. If this +### store_forward_module_records -### store_forward_plugin_records - -Set this to the maximum number of records to save. Best to leave this at the default (`0`) where the plugin will use 2/3 of your device's available PSRAM. This is about 11,000 records. +Set this to the maximum number of records to save. Best to leave this at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records. - +groupId="settings" +defaultValue="cli" +values={[ +{label: 'CLI', value: 'cli'}, +{label: 'Android', value: 'android'}, +{label: 'iOS', value: 'iOS'}, +{label: 'Web', value: 'web'}, +]}> + - ```bash title="Set store_forward_plugin_records to default (≈11,000 records)" - meshtastic --set store_forward_plugin_records 0 - ``` - ```bash title="Set store_forward_plugin_records to 100 records" - meshtastic --set store_forward_plugin_records 100 - ``` +```bash title="Set store_forward_module_records to default (≈11,000 records)" +meshtastic --set store_forward_module_records 0 +``` + +```bash title="Set store_forward_module_records to 100 records" +meshtastic --set store_forward_module_records 100 +``` @@ -266,27 +268,26 @@ Configuring this setting is not yet available for the selected platform. If this - ## Details ### How it works -![Store & Forward - Overview](/img/plugins/store_and_forward/store_and_forward-overview.png) +![Store & Forward - Overview](/img/modules/store_and_forward/store_and_forward-overview.png) ### Requirements Initial Requirements: -* Must be installed on a router node. - * This is an artificial limitation, but is in place to enforce best practices. - * Router nodes are intended to be always online. If this plugin misses any messages, the reliability of the stored messages will be reduced. -* Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others) +- Must be installed on a router node. + - This is an artificial limitation, but is in place to enforce best practices. + - Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced. +- Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others) ### Usage Overview -* To use / test this you will want at least 3 devices - * One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point. - * Two others will be regular clients. Nothing special required. +- To use / test this you will want at least 3 devices + - One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point. + - Two others will be regular clients. Nothing special required. ### Meshtastic channel configuration @@ -296,7 +297,7 @@ Either use a custom channel configuration with at an at least 1kbit data rate or Recommended channel setting is for 1.343kbps: -```bash title="Recommended channel setting for S&F plugin" +```bash title="Recommended channel setting for S&F module" meshtastic --setchan spread_factor 11 --setchan coding_rate 4 --setchan bandwidth 500 ``` @@ -305,21 +306,21 @@ With an aftermarket coaxial antenna or moxon antenna, that will give you roughly ### Router setup :::warning -Don't enable the Store and Forward plugin on multiple routers! +Don't enable the Store and Forward module on multiple routers! ::: -* Configure your device as a [meshtastic router](router). -* Name your router node something that makes it easily identifiable, aka "Router". -* Configure the Store and Forward plugin - ```bash title="Required - Enable the plugin" - meshtastic --set store_forward_plugin_enabled true +- Configure your device as a [meshtastic router](router). +- Name your router node something that makes it easily identifiable, aka "Router". +- Configure the Store and Forward module + ```bash title="Required - Enable the module" + meshtastic --set store_forward_module_enabled true ``` ```bash title="Optional - Set maximum number of records to save to device" - meshtastic --set store_forward_plugin_records 100 + meshtastic --set store_forward_module_records 100 ``` -:::tip -Best to leave `store_forward_plugin_records` at the default (`0`) where the plugin will use 2/3 of your device's available PSRAM. This is about 11,000 records. -::: + :::tip + Best to leave `store_forward_module_records` at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records. + ::: ### Client Usage @@ -327,9 +328,9 @@ Currently, no special configuration is required. To request your history sent to Available Commands: -| Command | Definition | -| :-----: | :---------------: | -| SF | Send the last few messages I may have missed | -| SFm | Send a 240 byte payload (Used for testing) | +| Command | Definition | +| :-----: | :------------------------------------------: | +| SF | Send the last few messages I may have missed | +| SFm | Send a 240 byte payload (Used for testing) | -The Store and Forward plugin will only service one client at a time. If a second client requests messages while the S&F is busy, the S&F will send a private message to the second client that they will need to wait. +The Store and Forward module will only service one client at a time. If a second client requests messages while the S&F is busy, the S&F will send a private message to the second client that they will need to wait. diff --git a/docs/software/android/installation.md b/docs/software/android/installation.md index 910ff48a..1c8f287b 100644 --- a/docs/software/android/installation.md +++ b/docs/software/android/installation.md @@ -3,9 +3,10 @@ id: android-installation title: Android application installation sidebar_label: Installation --- + Our Android application is available to download on Google Play Store. -

Download at https://play.google.com/store/apps/details?id=com.geeksville.mesh

+

Download at https://play.google.com/store/apps/details?id=com.geeksville.mesh

The app is also available on the Amazon [Appstore](https://www.amazon.com/Geeksville-Industries-Meshtastic/dp/B08CY9394Q). You will need to install the Amazon Appstore onto your phone in order to install the Meshtastic application. @@ -30,7 +31,7 @@ Click on the image to see a quick video of where I found it on my phone. There is a [beta program](https://play.google.com/apps/testing/com.geeksville.mesh) for the app, which will let you test the cutting edge changes, though this may come with extra bugs. You can join this via Google Play. It is recommended that you follow the [Meshtastic Discourse Alpha Testers](https://meshtastic.discourse.group/c/development/alpha-testers) channel if you decide to join this. -The app uses anonymous usage statistics and crash reports to allow us to catch problems with Meshtastic and fix them. Analytics are also required to be able to use the "free" plan of our map provider [Mapbox](https://docs.mapbox.com/help/how-mapbox-works/). You can disable this by unticking the checkbox on the settings page. +The app uses anonymous usage statistics and crash reports to allow us to catch problems with Meshtastic and fix them. Analytics are also required to be able to use the "free" plan of our map provider [Mapbox](https://docs.mapbox.com/help/how-mapbox-works). You can disable this by unticking the checkbox on the settings page. [![Settings page with statistics consent box highlighted](/img/android/android-stats-consent-sm.png)](/img/android/android-stats-consent.png) diff --git a/docs/software/android/location-access.md b/docs/software/android/location-access.md index abf0c368..7dc93d9c 100644 --- a/docs/software/android/location-access.md +++ b/docs/software/android/location-access.md @@ -1,13 +1,13 @@ # Location access and meshtastic -Google Play has some newish requirements for access to background location. This doc is a collection of work items needed to meet those requirements. +Google Play has some newish requirements for access to background location. This doc is a collection of work items needed to meet those requirements. -The app is currently removed from the Play Store ([broken store link](https://play.google.com/store/apps/details?id=com.geeksville.mesh)), and some kind Googlers inside of Google are helping with this problem. **Hopefully** it will be -relisted soon (while we address these newish requirements), but we've got to do a bit of code to add a new dialog (and make a video for Google). It will take about a week to make these changes (including testing time with the [alpha-tester group](https://meshtastic.discourse.group/c/development/alpha-testers/) on the forum). +The app is currently removed from the Play Store ([broken store link](https://play.google.com/store/apps/details?id=com.geeksville.mesh)), and some kind Googlers inside of Google are helping with this problem. **Hopefully** it will be +relisted soon (while we address these newish requirements), but we've got to do a bit of code to add a new dialog (and make a video for Google). It will take about a week to make these changes (including testing time with the [alpha-tester group](https://meshtastic.discourse.group/c/development/alpha-testers) on the forum). -Until relisted in the Play Store (hopefully they can relist while we make these fixes), you'll need to install [raw APKs from GitHub](https://github.com/meshtastic/Meshtastic-Android/releases). Which is not ideal, but works. +Until relisted in the Play Store (hopefully they can relist while we make these fixes), you'll need to install [raw APKs from GitHub](https://github.com/meshtastic/Meshtastic-Android/releases). Which is not ideal, but works. -Sorry ya'll. +Sorry ya'll. (The remainder of this public document is mostly for Googlers) @@ -15,18 +15,18 @@ Sorry ya'll. We need foreground location access for two reasons: -* (Primarily) [This app](https://github.com/meshtastic/Meshtastic-Android) is a navigation app that uses long range LoRa mesh radios for communication in the back country. These radios can run for weeks on a charge and talk to the user's phone over USB or Bluetooth to provide the UX. We need foreground location so we can show the user's current position on the same map that is showing positions of the other users. -* (Secondarily) Using the old Bluetooth BLE API (which we need to use to support older devices), scanning for Bluetooth low energy devices requires this permission (because 'beacons' etc... could leak location info to the app). Without this permission (on older phones) the BLE discovery results are always empty. +- (Primarily) [This app](https://github.com/meshtastic/Meshtastic-Android) is a navigation app that uses long range LoRa mesh radios for communication in the back country. These radios can run for weeks on a charge and talk to the user's phone over USB or Bluetooth to provide the UX. We need foreground location so we can show the user's current position on the same map that is showing positions of the other users. +- (Secondarily) Using the old Bluetooth BLE API (which we need to use to support older devices), scanning for Bluetooth low energy devices requires this permission (because 'beacons' etc... could leak location info to the app). Without this permission (on older phones) the BLE discovery results are always empty. -If it is helpful, [here](https://meshtastic.org/docs/software/android/android-usage) is a slightly stale set of screenshots/instructions showing how the user uses our application. +If it is helpful, [here](/docs/software/android/android-usage) is a slightly stale set of screenshots/instructions showing how the user uses our application. ## Why this app needs "background location access" -When the user has the LoRa device in their pocket occasionally (every 15 minutes ish), the Android sister app background service will acquire the GPS position and provide it to the LoRa [firmware](https://github.com/meshtastic/Meshtastic-device). Without background location access, this core (the primary feature) of our app would not work (because you wouldn't be able to see the last known position of the hikers/skiers/users in your group). +When the user has the LoRa device in their pocket occasionally (every 15 minutes ish), the Android sister app background service will acquire the GPS position and provide it to the LoRa [firmware](https://github.com/meshtastic/Meshtastic-device). Without background location access, this core (the primary feature) of our app would not work (because you wouldn't be able to see the last known position of the hikers/skiers/users in your group). -This location is shared only over an [encrypted](https://meshtastic.org/docs/developers/device/encryption) link and each group of users has their own AES256 key for their 'channel'. Our privacy policy is [here](https://meshtastic.org/docs/legal/privacy). +This location is shared only over an [encrypted](/docs/developers/device/encryption) link and each group of users has their own AES256 key for their 'channel'. Our privacy policy is [here](/docs/legal/privacy). -(This description has been simplified a bit: This project works with a [variety](https://meshtastic.org/docs/hardware) of LoRa devices, some of which have their own built-in GPS. For the devices that have a GPS built-in, we do not use Android to get the user's location) +(This description has been simplified a bit: This project works with a [variety](/docs/hardware) of LoRa devices, some of which have their own built-in GPS. For the devices that have a GPS built-in, we do not use Android to get the user's location) ## Fixes needed for these new Play Store background position requirements @@ -39,17 +39,17 @@ per https://support.google.com/googleplay/android-developer/answer/9799150 The existing text explains what the app does, but it needs to be even more explicit: Requirements from Google site: -If you plan to use location in the background in your app, you should communicate this to users in the Google Play Store Listing via your app description, screenshots and (if applicable) title or icon. +If you plan to use location in the background in your app, you should communicate this to users in the Google Play Store Listing via your app description, screenshots and (if applicable) title or icon. Here are some suggestions on how to highlight use of location in the background to users: Provide a short description to signal 'location' (for example, 'find anywhere' or 'always know where'). -Include an in-app screenshot that shows a map/user location or geotagged images. +Include an in-app screenshot that shows a map/user location or geotagged images. If applicable, your app title or icon may also signal the location feature of your app. ## TODO: In app dialog -We currently explain why we need location access on the settings page and in the help. But we need a new dialog at launch, which needs to be **super** explicit: +We currently explain why we need location access on the settings page and in the help. But we need a new dialog at launch, which needs to be **super** explicit: Requirements from Google site: Must be within the app itself, not only in the app description or on a website; @@ -68,7 +68,7 @@ If you extend permitted usage to ads, you must include the following: 'used to p Example disclosure statements Below are two example statements that can be used in your disclosure; the latter includes the use of location for ads for which you can choose the most relevant phrasing): -'[This app] collects location data to enable "feature", "feature" and "feature" even when the app is closed or not in use'. +'[This app] collects location data to enable "feature", "feature" and "feature" even when the app is closed or not in use'. '[This app] collects location data to enable "feature", "feature" and "feature" even when the app is closed or not in use and it is also used to support advertising'. The prominent disclosure may include other information to ensure compliance to policy requirements and clarity for users but must at least include the above, where relevant. @@ -76,15 +76,15 @@ Note: If the feature does not have a user-facing interface when location in the ## TODO: Video demonstration -I'm awful at making videos, so I'll ask someone from the [forum](https://meshtastic.discourse.group/) to help with this! +I'm awful at making videos, so I'll ask someone from the [forum](https://meshtastic.discourse.group) to help with this! Requirements from Google site: -As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use). +As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use). You can see an example of what this video demonstration should look like below. See an example video demonstration -As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use). The video should demonstrate the background location feature and the required steps to encounter and enable this feature in-app. The video should show: 1. Runtime prompt, 2. the prominent in-app disclosure dialog displayed to users (described below), and the feature being activated from the background. 3. The recommended duration is 30 seconds or less. A YouTube link is the preferred video format, but Google Drive storage links to an mp4 or other common video file formats are also supported. Note: If the feature does not have a user-facing interface when location in the background is active, please note this in your declaration and demonstrate the feature or its impacts as much as possible in the video. Ensure your video is made using an Android device. +As part of the permissions declaration, you must provide a link to a short video that demonstrates the location-based feature in your app that requires access to location in the background (while the app is not in use). The video should demonstrate the background location feature and the required steps to encounter and enable this feature in-app. The video should show: 1. Runtime prompt, 2. the prominent in-app disclosure dialog displayed to users (described below), and the feature being activated from the background. 3. The recommended duration is 30 seconds or less. A YouTube link is the preferred video format, but Google Drive storage links to an mp4 or other common video file formats are also supported. Note: If the feature does not have a user-facing interface when location in the background is active, please note this in your declaration and demonstrate the feature or its impacts as much as possible in the video. Ensure your video is made using an Android device. Video requirements The video should demonstrate the background location feature and the required steps to encounter and enable this feature in-app. The video should show: diff --git a/docs/software/android/usage.md b/docs/software/android/usage.md index 4b11862a..b84b965b 100644 --- a/docs/software/android/usage.md +++ b/docs/software/android/usage.md @@ -47,7 +47,6 @@ The cloud icon at the top right corner indicates if you are connected to a devic ![Sleeping](/img/android/android-cloud-up.png) Cloud with an up arrow in it: Device is connected, but currently sleeping or out of range. - ## Common tasks Once you are connected to a device, the App will work, and you can test it by "sending" a message. However, you will need to join or create a new mesh network so you have someone to communicate with. If you have been sent a QR code or link for Meshtastic, then skip ahead to [Join a Channel](#join-a-channel), otherwise you will need to Setup a Channel. @@ -107,14 +106,14 @@ You can test changing channels with the QR code shown below. Various data-rates are selectable when configuring a channel and are inversely proportional to the theoretical range of the devices: -| Channel setting | Data-rate | -|------------------------|----------------------| -| Short Range / Fast | 19346.94 bps | -| Short Range / Slow | 4800.00 bps | -| Medium Range / Fast | 1227.18 bps | -| Medium Range / Slow | 763.29 bps | -| Long Range / Fast | 196.74 bps | -| long Range / Slow | 136.71 bps (default) | +| Channel setting | Data-rate | +| ------------------- | -------------------- | +| Short Range / Fast | 19346.94 bps | +| Short Range / Slow | 4800.00 bps | +| Medium Range / Fast | 1227.18 bps | +| Medium Range / Slow | 763.29 bps | +| Long Range / Fast | 196.74 bps | +| long Range / Slow | 136.71 bps (default) | ### Send a message @@ -122,10 +121,10 @@ The message window operates like any chat applications. Note that any messages s With LoRa (or any radio) there is some uncertainty that the messages has been received, so there is a confirmation built-in to the protocol. There are small cloud icons shown to the right of the messages you send: -* Cloud with an up arrow: the application is waiting for the device to some out of sleep mode (or come back into Bluetooth range), to upload the message to the device. -* Cloud only: message has been sent via Bluetooth and transmitted via LoRa. -* Cloud with a check mark: message has been delivered to at least one node in the mesh and at least one node sent back a confirmation (successfully received by the initial sender). -* Cloud crossed out: message may have been delivered to at least one node in the mesh. The initial sender did not receive at least one node's confirmation within a certain timeout. +- Cloud with an up arrow: the application is waiting for the device to some out of sleep mode (or come back into Bluetooth range), to upload the message to the device. +- Cloud only: message has been sent via Bluetooth and transmitted via LoRa. +- Cloud with a check mark: message has been delivered to at least one node in the mesh and at least one node sent back a confirmation (successfully received by the initial sender). +- Cloud crossed out: message may have been delivered to at least one node in the mesh. The initial sender did not receive at least one node's confirmation within a certain timeout. Thus, in a group size of 3 and up, confirmations could be from any one device (not person), so it is good practice to respond, so the initial sender knows you have read their message. @@ -147,8 +146,7 @@ The Map tab will show a local map with an icon for each active mesh node that ha [![Mapping provided by Mapbox](/img/android/android-map-sm.png)](/img/android/android-map.png) -The map is not developed by the Meshtastic project, and the source of the mapping system is [Mapbox](https://docs.mapbox.com/help/how-mapbox-works/) (free-tier), and the map data is sourced from [OpenStreetMap OSM](https://www.openstreetmap.org/). Mapbox currently requires analytics to be enabled for you to use their mapping system. There is currently no off-line maps (phone needs mobile data or Wifi), although this will be improved in the future. If you don't see the features that you'd expect on the map then head over to [OpenStreetMap OSM](https://www.openstreetmap.org/) where you can contribute new data to the map. - +The map is not developed by the Meshtastic project, and the source of the mapping system is [Mapbox](https://docs.mapbox.com/help/how-mapbox-works) (free-tier), and the map data is sourced from [OpenStreetMap OSM](https://www.openstreetmap.org). Mapbox currently requires analytics to be enabled for you to use their mapping system. There is currently no off-line maps (phone needs mobile data or Wifi), although this will be improved in the future. If you don't see the features that you'd expect on the map then head over to [OpenStreetMap OSM](https://www.openstreetmap.org) where you can contribute new data to the map. ## Configuration options diff --git a/docs/software/community/atak.md b/docs/software/community/atak.md index 6ad93618..3c512829 100644 --- a/docs/software/community/atak.md +++ b/docs/software/community/atak.md @@ -1,24 +1,23 @@ --- id: community-atak -title: ATAK plugin -sidebar_label: ATAK plugin +title: ATAK module +sidebar_label: ATAK module --- :::note This is a community project maintained by @paulmandal. -Development can be followed on [GitHub](https://github.com/paulmandal/atak-forwarder/). +Development can be followed on [GitHub](https://github.com/paulmandal/atak-forwarder). Support should be sought from the respective authors. ::: -This is a plugin for ATAK (Android Team Awareness Kit) that uses Meshtastic to provide off-grid communications. This includes plotting the position of others on the map, transmission of markers and routes, and chat messages. It has been signed by the TAK Product Center for use with the Play Store version of ATAK. He is currently distributing development builds via [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex), aiming to publish it to the Play Store in the future. +This is a module for ATAK (Android Team Awareness Kit) that uses Meshtastic to provide off-grid communications. This includes plotting the position of others on the map, transmission of markers and routes, and chat messages. It has been signed by the TAK Product Center for use with the Play Store version of ATAK. He is currently distributing development builds via [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex), aiming to publish it to the Play Store in the future. -![ATAK Plugin](/img/atak-animation.gif) +![ATAK Module](/img/atak-animation.gif) -The builds of the plugin on the Google Drive are now signed for the Play Store version of ATAK, as of 6/3/2021. +The builds of the module on the Google Drive are now signed for the Play Store version of ATAK, as of 6/3/2021. -The ATAK plugin requires the Meshtastic Android app to be installed. - -* A walk-through on how to [set up ATAK](https://paul-mandal.medium.com/atak-for-hikers-d96d5246193e). -* The plugin source is available on [GitHub](https://github.com/paulmandal/atak-forwarder/), along with instructions for setting it up. -* Development builds are available on [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex). +The ATAK module requires the Meshtastic Android app to be installed. +- A walk-through on how to [set up ATAK](https://paul-mandal.medium.com/atak-for-hikers-d96d5246193e). +- The module source is available on [GitHub](https://github.com/paulmandal/atak-forwarder), along with instructions for setting it up. +- Development builds are available on [Google Drive](https://drive.google.com/drive/folders/1xeKJnn9tmzkkmuDbMp0LCLOV9OzHU-Ex). diff --git a/docs/software/community/overview.md b/docs/software/community/overview.md index a7760d24..bb54844c 100644 --- a/docs/software/community/overview.md +++ b/docs/software/community/overview.md @@ -4,10 +4,10 @@ title: Community applications sidebar_label: Community apps --- -The Meshtastic ecosystem is highly extensible, and a number of community projects have been made to fit different people's needs. If you wish to create your own application or plugin, please read the information in the developers section, and tell us about your project on the forum. +The Meshtastic ecosystem is highly extensible, and a number of community projects have been made to fit different people's needs. If you wish to create your own application or module, please read the information in the developers section, and tell us about your project on the forum. Current community projects: - * [Meshtastic plugin for ATAK](/docs/software/community/community-atak) (Android Team Awareness Kit) + * [Meshtastic module for ATAK](/docs/software/community/community-atak) (Android Team Awareness Kit) * [PyGUI](/docs/software/community/community-pygui) - Platform independent graphical user interface for Meshtastic devices * [Go CLI](/docs/software/community/community-go) - A command line interface using Go that requires no pre-requisites to be installed diff --git a/docs/software/device/remote-admin.md b/docs/software/device/remote-admin.md index b72497a0..81c60330 100644 --- a/docs/software/device/remote-admin.md +++ b/docs/software/device/remote-admin.md @@ -144,8 +144,8 @@ Completed getting preferences For further reading, I recommend starting out with [Meshtastic-python](/docs/software/python/python-cli) if you haven't already gone through this (hopefully you have since you are reading this). But for a full reference to the settings you can change, please see: -[Settings Overview](/docs/settings) and -[Complete list of user settings in Protobufs](https://meshtastic.org/docs/developers/protobufs/api#radioconfiguserpreferences) +[Settings Overview](/docs/settings) and +[Complete list of user settings in Protobufs](/docs/developers/protobufs/api#radioconfiguserpreferences) ## Areas for future development diff --git a/docs/software/device/remote-hardware-service.md b/docs/software/device/remote-hardware-service.md index a5fe6960..b57d7d2d 100644 --- a/docs/software/device/remote-hardware-service.md +++ b/docs/software/device/remote-hardware-service.md @@ -9,7 +9,7 @@ GPIO access is fundamentally dangerous because invalid options can physically da ::: :::note -This feature uses a preinstalled plugin 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. +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. ::: You can get the latest python tool/library with `pip3 install --upgrade meshtastic` on Windows/Linux/OS-X. See the [python section](/docs/software/python/python-installation) for more details. @@ -22,34 +22,33 @@ You can get the latest python tool/library with `pip3 install --upgrade meshtast ## Setup - -To prevent access from untrusted users, you must first make a `gpio` channel that is used for authenticated access to this feature. You'll need to install this channel on both the local and remote node. +To prevent access from untrusted users, you must first make a `gpio` channel that is used for authenticated access to this feature. You'll need to install this channel on both the local and remote node. The procedure using the python command line tool is: 1. Connect local device via USB 2. Create a gpio channel - ```bash - meshtastic --ch-add gpio - ``` + ```bash + meshtastic --ch-add gpio + ``` :::tip If doing local testing, may want to change the speed of the channel at this time, too. (ex: "meshtastic --ch-mediumfast") ::: 3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device - ```bash - meshtastic --info - ``` + + ```bash + meshtastic --info + ``` 4. Connect the remote device via USB (or use the [remote admin](device-remote-admin) feature to reach it through the mesh) 5. Set it to join the gpio channel you created - ```bash - meshtastic --seturl theurlyoucopiedinstep3 - ``` - + ```bash + meshtastic --seturl theurlyoucopiedinstep3 + ``` Now both devices should be able to talk over the `gpio` channel. Send a text message from one the other other verify. Also run "--nodes" to verify the second node shows up. @@ -112,32 +111,34 @@ GPIO:44 mask:0x100000000000 You can add a simple LED and resistor to validate that the GPIO operations work as expected. Used the tutorial at https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/ as a guide. Need: -* 2 Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it) -* 2 wires (black and yellow; they can be any color but typically black is used for ground) -* breadboard (optional) -* 1 LED -* 1 220Ω resistor (somewhat optional, but recommended) + +- 2 Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it) +- 2 wires (black and yellow; they can be any color but typically black is used for ground) +- breadboard (optional) +- 1 LED +- 1 220Ω resistor (somewhat optional, but recommended) Prep: -* disconnect the remote device from power (battery/usb) -* add a resistor from yellow wire to the one end of the LED (either end of the resistor is ok, either end of the LED is ok) -* add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21) -* add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED -* power on the device + +- disconnect the remote device from power (battery/usb) +- add a resistor from yellow wire to the one end of the LED (either end of the resistor is ok, either end of the LED is ok) +- add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21) +- add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED +- power on the device Validation: By default, the pin may be "off" or "on". (It will most likely "off".) See the steps below for running commands. In the example of GPIO21, the mask would be 0x200000. [T-Lora v1 with LED on GPIO 21](/img/LED_on_TLoraV1.jpg) - ## Doing GPIO operations -You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [python API](https://meshtastic.org/docs/software/python/python-installation) documentation for more details. +You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [python API](/docs/software/python/python-installation) documentation for more details. ## Using GPIOs from the python CLI Writing a GPIO (ex: turn "on" GPIO4): + ```bash title="Expected output" $ meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest \!28979058 Connected to radio @@ -145,6 +146,7 @@ Writing GPIO mask 0x10 with value 0x10 to !28979058 ``` Reading a GPIO (ex: read GPIO4): + ```bash title="Expected output" $ meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058 Connected to radio @@ -157,6 +159,7 @@ If the mask and the gpio_value match, then the value is "on". If the gpio_value ::: Watching for GPIO changes (ex: watching GPIO4 for changes): + ```bash title="Expected output" $ meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest \!28979058 Connected to radio diff --git a/docs/software/js/connecting.md b/docs/software/js/connecting.md index 3e5d0849..17faa46e 100644 --- a/docs/software/js/connecting.md +++ b/docs/software/js/connecting.md @@ -4,17 +4,24 @@ title: Connecting to a device sidebar_label: Connecting --- -Currently, two connection methods are supported, HTTP and BLE. -## HTTP - -## BLE - -```typescript -//connection method -``` ```tsx -//connection button -const a = ; +import type React from 'React'; + +import { IHTTPConnection } from '@meshtastic/meshtasticjs'; + +export const Connection = (): JSX.Element => { + const connection = new IHTTPConnection(); + + const connect = (): void => { + void connection.connect({ + address: '10.0.0.10', + fetchInterval: 3000, + }); + } + + return ; +}; + ``` diff --git a/docs/software/js/getting-started.md b/docs/software/js/getting-started.md index 6e94df94..3dc679c1 100644 --- a/docs/software/js/getting-started.md +++ b/docs/software/js/getting-started.md @@ -12,7 +12,7 @@ Full API documentation is available at [js.meshtastic.org](https://js.meshtastic Meshtastic.js is a JavaScript library that provides an interface to Meshtastic devices. It can be used to build applications to interface with a Meshtastic network. Currently, HTTP(S) and Bluetooth connections are supported. -If you wish to view the code or contribute to development of the library, please visit the JavaScript code GitHub page. +If you wish to view the code or contribute to development of the library, please visit the JavaScript code [GitHub page](https://github.com/meshtastic/meshtastic.js). ## Connection methods diff --git a/docs/software/plugins/canned-message.md b/docs/software/modules/canned-message.md similarity index 70% rename from docs/software/plugins/canned-message.md rename to docs/software/modules/canned-message.md index 6b046cf3..79c0484d 100644 --- a/docs/software/plugins/canned-message.md +++ b/docs/software/modules/canned-message.md @@ -1,11 +1,12 @@ --- -id: canned-message-plugin +id: canned-message-module title: Canned messages sidebar_label: Canned messages --- + ## About -The CannedMessage Plugin will allow you to send messages to the mesh network +The Canned Message Module will allow you to send messages to the mesh network from the device without using the phone app. You can predefine text messages to choose from. @@ -13,13 +14,13 @@ You can predefine text messages to choose from. To navigate through messages and select one, you will require some hardware attached to your device. -Currently, the plugin is tested with a generic rotary encoder, but this is +Currently, the module is tested with a generic rotary encoder, but this is not a limitation further input methods can be added in the future. ### Rotary encoder Meshtastic supports hardwired rotary encoders as input devices. -(Technically CannedMessage plugin is independent of rotary +(Technically the Canned Message Module is independent of rotary encoders. It is described here, because no other module utilizes rotary encoders just yet.) You will need a generic rotary encoder. The types listed below has five legs @@ -28,11 +29,11 @@ but any other types will likely do the job. You can also use a three-legged version, where the "press" action should be wired from an independent switch. -* [Amazon link](https://www.amazon.com/Rotary-Encoder-Washers-Digital-Potentiometer/dp/B07Y619CZR/ref=sr_1_21?keywords=rotary+encoder&qid=1642317807&sprefix=rotary+enco%2Caps%2C186&sr=8-21) -* [Amazon.DE link](https://www.amazon.de/-/en/sourcing-Degree-Rotary-Encoder-Digital/dp/B07RLZPX5K/ref=sr_1_12?keywords=rotary+encoder&qid=1642320025&sprefix=rotary%2Caps%2C105&sr=8-12) -* [Aliexpress link1](https://www.aliexpress.com/item/32992227812.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-23&pdp_ext_f=%7B%22sku_id%22%3A%2266940265509%22%7D&pdp_pi=-1%3B1.66%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) -* [Aliexpress link2](https://www.aliexpress.com/item/32946444853.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&aem_p4p_detail=2022011523263276283624312400022072680&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-6&pdp_ext_f=%7B%22sku_id%22%3A%2266223434642%22%7D&pdp_pi=-1%3B1.91%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) -* [Aliexpress link3](https://www.aliexpress.com/item/10000056483250.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-9&pdp_ext_f=%7B%22sku_id%22%3A%2220000000116682147%22%7D&pdp_pi=-1%3B2.51%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) +- [Amazon link](https://www.amazon.com/Rotary-Encoder-Washers-Digital-Potentiometer/dp/B07Y619CZR/ref=sr_1_21?keywords=rotary+encoder&qid=1642317807&sprefix=rotary+enco%2Caps%2C186&sr=8-21) +- [Amazon.DE link](https://www.amazon.de/-/en/sourcing-Degree-Rotary-Encoder-Digital/dp/B07RLZPX5K/ref=sr_1_12?keywords=rotary+encoder&qid=1642320025&sprefix=rotary%2Caps%2C105&sr=8-12) +- [Aliexpress link1](https://www.aliexpress.com/item/32992227812.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-23&pdp_ext_f=%7B%22sku_id%22%3A%2266940265509%22%7D&pdp_pi=-1%3B1.66%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) +- [Aliexpress link2](https://www.aliexpress.com/item/32946444853.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&aem_p4p_detail=2022011523263276283624312400022072680&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-6&pdp_ext_f=%7B%22sku_id%22%3A%2266223434642%22%7D&pdp_pi=-1%3B1.91%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) +- [Aliexpress link3](https://www.aliexpress.com/item/10000056483250.html?spm=a2g0o.productlist.0.0.1afe21a50SLvi2&algo_pvid=a19c4182-08aa-406d-bfdf-132582ef5ebb&algo_exp_id=a19c4182-08aa-406d-bfdf-132582ef5ebb-9&pdp_ext_f=%7B%22sku_id%22%3A%2220000000116682147%22%7D&pdp_pi=-1%3B2.51%3B-1%3B-1%40salePrice%3BUSD%3Bsearch-mainSearch) Connect your rotary encoder as follows. The rotary encoder has two rows of legs. One of the rows contains two legs, the other contains three @@ -46,7 +47,7 @@ The two legs is to sense the press action (or push). Connect one of the two to GROUND and the other to a GPIO pin. (No matter which one goes where.) Let's call this connected ports 'PRESS'. -The three legs is to sense the rotation action. +The three legs is to sense the rotation action. Connect the middle leg to GROUND and the ones on the side to GPIO pins. Let's call these ports 'A' and 'B', according to the scheme below. @@ -57,10 +58,10 @@ the scheme below. Recommended GPIO pins for connecting a rotary encoder. -* TTGO LoRa V1: - * A - GPIO-22 - * B - GPIO-23 - * PRESS - GPIO-21 +- TTGO LoRa V1: + - A - GPIO-22 + - B - GPIO-23 + - PRESS - GPIO-21 There is a reference case 3D-design utilizing the rotary encoder for TTGO LoRa V1: [Case for TTGO-ESP32-LORA-OLED-v1.0 with rotary encoder](https://www.thingiverse.com/thing:5178495) @@ -81,35 +82,35 @@ There is a reference case 3D-design utilizing the rotary encoder for TTGO LoRa V rotary1_event_cw Generate input event on CW of this kind. - For using with CannedMessagePlugin you must choose value "UP" here! + For using with CannedMessageModule you must choose value "UP" here! rotary1_event_ccw Generate input event on CCW of this kind. - For using with CannedMessagePlugin you must choose value "DOWN" here! + For using with CannedMessageModule you must choose value "DOWN" here! rotary1_event_press Generate input event on Press of this kind. - For using with CannedMessagePlugin you must choose value "SELECT" here! + For using with CannedMessageModule you must choose value "SELECT" here! The rotary encoder #1 will send input events under name "rotEnc1". -## Configuration of the plugin +## Configuration of the module -Following configuration can be set for the plugin. +Following configuration can be set for the module. - canned_message_plugin_enabled - Enable/disable CannedMessagePlugin. + canned_message_module_enabled + Enable/disable CannedMessageModule. - canned_message_plugin_allow_input_source - Input event origin accepted by the canned message plugin. + canned_message_module_allow_input_source + Input event origin accepted by the Canned Message Module. Can be e.g. "rotEnc1" or keyword "_any" - canned_message_plugin_messages - Predefined messages for CannedMessagePlugin separated by '|' characters. + canned_message_module_messages + Predefined messages for CannedMessageModule separated by '|' characters. - canned_message_plugin_send_bell - CannedMessagePlugin also sends a bell character with the messages. - ExternalNotificationPlugin can benefit from this feature. + canned_message_module_send_bell + CannedMessagemodule also sends a bell character with the messages. + ExternalNotificationModule can benefit from this feature. ## Usage Notes @@ -124,13 +125,13 @@ need to execute a sequence like this: meshtastic --set rotary1_event_press KEY_SELECT meshtastic --set rotary1_enabled True -For setting up the plugin you will +For setting up the module you will need to execute a sequence like this: - meshtastic --set canned_message_plugin_allow_input_source "_any" - meshtastic --set canned_message_plugin_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger" - meshtastic --set canned_message_plugin_send_bell False - meshtastic --set canned_message_plugin_enabled True + meshtastic --set canned_message_module_allow_input_source "_any" + meshtastic --set canned_message_module_messages "I'm fine|I'm out|I'm back|Need helping hand|Help me with saw|I need an alpinist|I need ambulance|Keep Calm|On my way|I will be late|I'm already waiting|We have company|Beer is cold|Roger" + meshtastic --set canned_message_module_send_bell False + meshtastic --set canned_message_module_enabled True :::note You can define up to 50 messages with a total length 200 bytes. @@ -139,11 +140,11 @@ Use short texts as end of line will be truncated on the screen. ::: :::note -The device must be restarted after the settings have been changed for the plugin to take effect. +The device must be restarted after the settings have been changed for the module to take effect. ::: ## Known Problems -* Rotary encoder input uses a technology called "interrupts". Using the -rotary encoder might cause unexpected software problems. This needs to be -tested. \ No newline at end of file +- Rotary encoder input uses a technology called "interrupts". Using the + rotary encoder might cause unexpected software problems. This needs to be + tested. diff --git a/docs/software/modules/environment.md b/docs/software/modules/environment.md new file mode 100644 index 00000000..a2f0c6e3 --- /dev/null +++ b/docs/software/modules/environment.md @@ -0,0 +1,222 @@ +--- +id: environment-module +title: Environment measurement +sidebar_label: Environment measurement +--- + +## About + +The Environment Measurement Module will allow nodes to send a specific message with information from connected environmental sensors. Currently supported sensors are `BME280`, `BME680`, `DHT11`, `DHT12`, `DHT21`, `DHT22`, Dallas 1-wire `DS18B20`, and `MCP9808`. + +The preferred setup is using I2C, so the `telemetry_module_sensor_pin` may not be needed. + +## Configuration + +These are the settings that can be configured. + + telemetry_module_enabled + Is the module enabled? + + 0 = Disabled (Default) + 1 = Enabled + + telemetry_module_screen_enabled + Show received sensor readings on device screen. + + 0 = Disabled (Default) + 1 = Enabled + + telemetry_module_read_error_count_threshold + Error count threshold for failed sensor readings. + + Default = 0 + + preferences.telemetry_module_update_interval + How often (in seconds) should sensor readings be broadcasted? + + Default = 0 + + telemetry_module_recovery_interval + For how long should we wait (in seconds) before trying to read sensors again upon exceeded error threshold? + + Default = 0 + + telemetry_module_display_fahrenheit + Should temperature readings be converted to fahrenheit? + + 0 = Disabled (Default) + 1 = Enabled + + telemetry_module_sensor_type + What sensor is connected? + + 0 = DHT11 (Default) + 1 = Dallas 1-wire DS18B20 + 2 = DHT12 + 3 = DHT21 + 4 = DHT22 + 5 = BME280 + 6 = BME680 + 7 = MCP9808 + + telemetry_module_sensor_pin + Which pin is the sensor connected to? + + Default = 0 + +## Usage Notes + +For basic usage, start with: + +```bash +telemetry_module_enabled = 1 + +telemetry_module_screen_enabled = 1 +``` + +Depending on which pin your sensor is connected to, set it accordingly: + +```bash +telemetry_module_sensor_pin = 13 +``` + +:::note +The device must be restarted after the settings have been changed for the module to take effect. +::: + +## Hardware + +The sensors can be wired differently, here's one example for sensor DS18B20 https://randomnerdtutorials.com/esp32-ds18b20-temperature-arduino-ide + +## Example of T-LoraV1 with DHT22 temperature sensor + +Setup of a T-LoraV1 with DHT22 temperature sensor. + +[](/img/hardware/lora_v1_with_DHT22.jpg) + +Requirements: + +- T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use) +- DHT22 sensor +- 10 Kohm resistor (optional, but recommended) +- breadboard (optional) +- two red wires (could be a different color, but 5V is typically red) +- two yellow wires for GPIO (could be a different color) +- one black wire (could be a different color, but GROUND is typically black) + +Steps: + +- disconnect power/battery +- connect black wire from GROUND to "-" on the DHT22 +- connect yellow wire from middle PIN to a row on bread board +- connect red wire from 5V to a row on breadboard +- connect resistor between red and yellow rows +- connect red wire from row with red to "+" on DHT22 +- connect yellow wire from yellow row to GPIO on device (ex: GPIO21) +- double check the cabling (if you get it wrong, you can damage the device and/or the DHT22 sensor) +- plug in device +- configure the device: + +```bash +meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type DHT22 --set telemetry_module_sensor_pin 21 +``` + +:::tip +You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above. +::: + +- reboot/reset the device (press the RST button or unplug/plug in the device) +- when the device boots it should say "Environment" and it may show the sensor data +- if "no data", then triple check the wiring +- if still "no data", run: + +```bash +meshtastic --info +``` + +and verify the the `telemetry_module_sensor_type and` `telemetry_module_sensor_pin` + +## Example of T-LoraV1 with Dallas DS18B20 temperature sensor + +Setup of a T-LoraV1 with DS18B20 temperature sensor. + +[](/img/hardware/lora_v1_with_DS18B20.jpg) + +Requirements: + +- T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use) +- DS18B20 sensor +- 10 Kohm resistor (optional, but recommended) +- breadboard (optional) +- two red wires (could be a different color, but 5V is typically red) +- two yellow wires for GPIO (could be a different color) +- one black wire (could be a different color, but GROUND is typically black) + +Steps: + +- disconnect power/battery +- connect black wire from GROUND to "-" on the DS18B20 +- connect yellow wire from DAT pin to a row on bread board +- connect red wire from 5V to a row on breadboard +- connect resistor between red and yellow rows +- connect red wire from row with red to "VCC" on DS18B20 +- connect yellow wire from yellow row to GPIO on device (ex: GPIO21) +- double check the cabling (if you get it wrong, you can damage the device and/or the sensor) +- plug in device +- configure the device: + +```bash +meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type DS18B20 --set telemetry_module_sensor_pin 21 +``` + +:::tip +You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above. +::: + +- reboot/reset the device (press the RST button or unplug/plug in the device) +- when the device boots it should say "Environment" and it may show the sensor data +- if "no data", then triple check the wiring +- if still "no data", run: + +```bash +meshtastic --info +``` + +and verify the the `telemetry_module_sensor_type` and `telemetry_module_sensor_pin` + +## Example of RAK 4631 with Environment Sensor + +Setup of a RAK 4631 with Environment Sensor + +[](/img/hardware/rak/RAK4631_with_EnvSensor.jpg) + +Requirements: + +- RAK4631 +- Environment Sensor + +Steps: + +- configure the device: + +```bash +meshtastic --set telemetry_module_measurement_enabled true --set telemetry_module_screen_enabled true --set telemetry_module_update_interval 15 --set telemetry_module_display_farenheit true --set telemetry_module_sensor_type 6 +``` + +:::tip +You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above. +::: + +- reboot/reset the device (press the button or unplug/plug in the device) +- when the device boots it should say "Environment" and it may show the sensor data +- if still "no data", run: + +```bash +meshtastic --info +``` + +and verify the the `telemetry_module_sensor_type` + +## Known Problems + +- No default configuration values are currently set, so this must be done when enabling the module. diff --git a/docs/software/plugins/external-notifications.md b/docs/software/modules/external-notifications.md similarity index 65% rename from docs/software/plugins/external-notifications.md rename to docs/software/modules/external-notifications.md index aa56cc03..7220830d 100644 --- a/docs/software/plugins/external-notifications.md +++ b/docs/software/modules/external-notifications.md @@ -1,93 +1,93 @@ --- -id: ext-notif-plugin +id: ext-notif-module title: External notifications sidebar_label: External notifications --- + ## About -The ExternalNotification Plugin will allow you to connect a speaker, LED or other device to notify you when a message has been received from the mesh network. +The ExternalNotification Module will allow you to connect a speaker, LED or other device to notify you when a message has been received from the mesh network. ## Configuration These are the settings that can be configured. - ext_notification_plugin_enabled - Is the plugin enabled? - + ext_notification_module_enabled + Is the module enabled? + 0 = Disabled (Default) 1 = Enabled - ext_notification_plugin_active + ext_notification_module_active Is your external circuit triggered when our GPIO is low or high? 0 = Active Low (Default) 1 = Active High - ext_notification_plugin_alert_message + ext_notification_module_alert_message Do you want to be notified on an incoming message? 0 = Disabled (Default) 1 = Alert when a text message comes - ext_notification_plugin_alert_bell + ext_notification_module_alert_bell Do you want to be notified on an incoming bell? 0 = Disabled (Default) 1 = Alert when the bell character is received - ext_notification_plugin_output + ext_notification_module_output What GPIO is your external circuit attached? GPIO of the output. (Default = 13) - ext_notification_plugin_output_ms + ext_notification_module_output_ms How long do you want us to trigger your external circuit? - - Amount of time in ms for the alert. Default is 1000. + Amount of time in ms for the alert. Default is 1000. ## Usage Notes For basic usage, start with: - ext_notification_plugin_enabled = 1 + ext_notification_module_enabled = 1 + + ext_notification_module_alert_message = 1 - ext_notification_plugin_alert_message = 1 - Depending on how your external circuit is configured, you may need to set the active state to true. - ext_notification_plugin_active = 1 + ext_notification_module_active = 1 :::note -The device must be restarted after the settings have been changed for the plugin to take effect. +The device must be restarted after the settings have been changed for the module to take effect. ::: - + ### Alert Types We support being alerted on two events: -1) Incoming Text Message +1. Incoming Text Message -2) Incoming Text Message that contains the ASCII bell character. At present, only the Python API can send an ASCII bell character, but more support may be added in the future. +2. Incoming Text Message that contains the ASCII bell character. At present, only the Python API can send an ASCII bell character, but more support may be added in the future. #### Bell Character -The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification_plugin_alert_bell enabled, we will issue an external notification. - +The bell character is ASCII 0x07. Include 0x07 anywhere in the text message and with ext_notification_module_alert_bell enabled, we will issue an external notification. + ## External Hardware Be mindful of the max current sink and source of the ESP32 GPIO. The easiest devices to interface with would be either an LED or Active Buzzer. Ideas for external hardware: -* LED -* Active Buzzer -* Flame thrower -* Strobe Light -* Siren - +- LED +- Active Buzzer +- Flame thrower +- Strobe Light +- Siren + ## Known Problems -* This won't directly support a passive (normal) speaker as it does not generate any audio wave forms. -* This currently only supports the ESP32. Other targets may be possible, I just don't have to test with. -* This plugin only monitors text messages. We won't trigger on any other packet types. +- This won't directly support a passive (normal) speaker as it does not generate any audio wave forms. +- This currently only supports the ESP32. Other targets may be possible, I just don't have to test with. +- This module only monitors text messages. We won't trigger on any other packet types. diff --git a/docs/software/plugins/plugin-api.md b/docs/software/modules/module-api.md similarity index 100% rename from docs/software/plugins/plugin-api.md rename to docs/software/modules/module-api.md diff --git a/docs/software/plugins/plugins.md b/docs/software/modules/modules.md similarity index 74% rename from docs/software/plugins/plugins.md rename to docs/software/modules/modules.md index da3f717b..80fb55b6 100644 --- a/docs/software/plugins/plugins.md +++ b/docs/software/modules/modules.md @@ -1,17 +1,17 @@ --- -id: plugins -title: Plugins overview +id: modules +title: Modules overview sidebar_label: Overview --- -There are a number of plugins that have been integrated into the device firmware. These can be turned on using the Meshtastic python command line program. Please note that these plugins require the device to be rebooted once they have been enabled for them to start running. +There are a number of modules that have been integrated into the device firmware. These can be turned on using the Meshtastic python command line program. Please note that these modules require the device to be rebooted once they have been enabled for them to start running. -These plugins are currently integrated into the firmware: +These modules are currently integrated into the firmware: * Range test - Allows automated testing of communication range of nodes * External notifications - Allows a speaker, LED or other device to indicate when a message has been received * Canned messages - Device can be used without the phone to send a message by choosing a predefined text * Serial - Allows messages to be sent across the mesh by sending strings across a serial port -These plugins are currently in development: +These modules are currently in development: * Store and forward - Allows a node to store messages and resend them to nodes that have intermittent connection to the mesh * Environment measurement - Allows a node to measure it's local environment and report across the mesh diff --git a/docs/software/plugins/range-test.md b/docs/software/modules/range-test.md similarity index 56% rename from docs/software/plugins/range-test.md rename to docs/software/modules/range-test.md index c9ff9c43..c4d12399 100644 --- a/docs/software/plugins/range-test.md +++ b/docs/software/modules/range-test.md @@ -1,75 +1,75 @@ --- -id: range-test-plugin -title: Range test plugin -sidebar_label: Range test +id: range-test-module +title: Range Test Module +sidebar_label: Range Test --- -This plugin allows you to test the range of your Meshtastic nodes. It uses two nodes, one to send a message every minute, and another to receive the messages. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into, for example, Google Earth, allowing you to see where you have coverage. +This module allows you to test the range of your Meshtastic nodes. It uses two nodes, one to send a message every minute, and another to receive the messages. The receiving node then saves the messages along with the GPS coordinates at which they were received into a .csv file. This .csv file can then be integrated into, for example, Google Earth, allowing you to see where you have coverage. ## Configuration These are the settings that can be configured. - range_test_plugin_enabled - Is the plugin enabled? - + range_test_module_enabled + Is the Module enabled? + 0 = Disabled (Default) 1 = Enabled - range_test_plugin_save + range_test_module_save If enabled, we will save a log of all received messages to /static/rangetest.csv which you can access from the webserver. We will abort writing if there is less than 50k of space on the filesystem to prevent filling up the storage. 0 = Disabled (Default) 1 = Enabled - range_test_plugin_sender + range_test_module_sender Number of seconds to wait between sending packets. Using the long_slow channel configuration, it's best not to go more frequent than once every 60 seconds. You can be more agressive with faster settings. 0 is default which disables sending messages. :::note -The device must be restarted after the settings have been changed for the plugin to take effect. +The device must be restarted after the settings have been changed for the module to take effect. ::: ### Usage Notes For basic usage, you will need two devices both with a GPS. A device with a paired phone with GPS may work, I have not tried it. -The first thing to do is to turn on the plugin. The device will need to be restarted after applying the settings. With the plugin turned on, the other settings will be available: +The first thing to do is to turn on the module. The device will need to be restarted after applying the settings. With the module turned on, the other settings will be available: - range_test_plugin_enabled = 1 + range_test_module_enabled = 1 If you want to send a message every 60 seconds: - range_test_plugin_sender = 60 + range_test_module_sender = 60 To save a log of the messages: - range_test_plugin_save = 1 + range_test_module_save = 1 Recommended settings for a sender at different radio settings: - Long Slow ... range_test_plugin_sender = 60 - Long Alt ... range_test_plugin_sender = 30 - Medium ... range_test_plugin_sender = 15 - Short Fast ... range_test_plugin_sender = 15 + Long Slow ... range_test_module_sender = 60 + Long Alt ... range_test_module_sender = 30 + Medium ... range_test_module_sender = 15 + Short Fast ... range_test_module_sender = 15 ### Python API Examples Sender -`meshtastic --set range_test_plugin_enabled 1` +`meshtastic --set range_test_module_enabled 1` -`meshtastic --set range_test_plugin_sender 60` +`meshtastic --set range_test_module_sender 60` Receiver -`meshtastic --set range_test_plugin_enabled 1` +`meshtastic --set range_test_module_enabled 1` -`meshtastic --set range_test_plugin_save 1` +`meshtastic --set range_test_module_save 1` ### Other things to keep in mind -Be sure to turn off either the plugin configured as a sender or the device where the plugin setup as sender when not in use. This will use a lot of time on air and will spam your channel. +Be sure to turn off either the module configured as a sender or the device where the module setup as sender when not in use. This will use a lot of time on air and will spam your channel. Also, be mindful of your space usage on the file system. It has protections from filling up the space but it's best to delete old range test results. @@ -80,21 +80,21 @@ Also, be mindful of your space usage on the file system. It has protections from Steps: 1. [Download](https://www.google.com/earth/versions/#download-pro) and open Google Earth - 1. Select File > Import - 2. Select CSV - 3. Select Delimited, Comma - 4. Make sure the button that states “This dataset does not contain latitude/longitude information, but street addresses” is unchecked - 5. Select “rx lat” & “rx long” for the appropriate lat/lng fields - 6. Click finish + 1. Select File > Import + 2. Select CSV + 3. Select Delimited, Comma + 4. Make sure the button that states “This dataset does not contain latitude/longitude information, but street addresses” is unchecked + 5. Select “rx lat” & “rx long” for the appropriate lat/lng fields + 6. Click finish 2. When it prompts you to create a style template, click yes. - 1. Set the name field to whichever column you want to be displayed on the map (don’t worry about this too much, when you click on an icon, all the relevant data appears) - 2. Select a color, icon, etc. and hit OK. + 1. Set the name field to whichever column you want to be displayed on the map (don’t worry about this too much, when you click on an icon, all the relevant data appears) + 2. Select a color, icon, etc. and hit OK. Your data will load onto the map, make sure to click the checkbox next to your dataset in the sidebar to view it. ### My Maps -You can use [My Maps](http://mymaps.google.com/). It takes CSVs and the whole interface is much easier to work with. +You can use [My Maps](http://mymaps.google.com). It takes CSVs and the whole interface is much easier to work with. Google has instructions on how to do that [here](https://support.google.com/mymaps/answer/3024836?co=GENIE.Platform%3DDesktop&hl=en#zippy=%2Cstep-prepare-your-info%2Cstep-import-info-into-the-map). @@ -110,26 +110,34 @@ Right now range test messages go over the `TEXT_MESSAGE_APP` port. We need a tog ## FAQ -Q: Where is rangetest.csv saved? -* Turn on the WiFi on your device as either a WiFi client or a WiFi AP. Once you can connect to your device, go to /static and you will see rangetest.csv. +Q: Where is rangetest.csv saved? -Q: Do I need to have WiFi turned on for the file to be saved? -* Nope, it'll just work. +- Turn on the WiFi on your device as either a WiFi client or a WiFi AP. Once you can connect to your device, go to /static and you will see rangetest.csv. -Q: Do I need a phone for this plugin? -* There's no need for a phone. +Q: Do I need to have WiFi turned on for the file to be saved? -Q: Can I use this as a message logger? -* While it's not the intended purpose, sure, why not. Do it! +- Nope, it'll just work. -Q: What will happen if I run out of space on my device? -* We have a protection in place to keep you from completely filling up your device. This will make sure that other device critical functions will continue to work. We will reserve at least 50k of free space. +Q: Do I need a phone for this module? -Q: What do I do with the rangetest.csv file when I'm done? -* Go to /static and delete the file. +- There's no need for a phone. -Q: Can I use this as a sender while on battery power? -* Yes, but your battery will run down quicker than normal. While sending, we tell the device not to go into low-power mode since it needs to keep to a fairly strict timer. +Q: Can I use this as a message logger? -Q: Why is this operating on incoming messages instead of the existing location discovery protocol? -* This plugin is still young and currently supports monitoring just one port at a time. I decided to use the existing message port because that is easy to test with. A future version will listen to multiple ports to be more promiscuous. +- While it's not the intended purpose, sure, why not. Do it! + +Q: What will happen if I run out of space on my device? + +- We have a protection in place to keep you from completely filling up your device. This will make sure that other device critical functions will continue to work. We will reserve at least 50k of free space. + +Q: What do I do with the rangetest.csv file when I'm done? + +- Go to /static and delete the file. + +Q: Can I use this as a sender while on battery power? + +- Yes, but your battery will run down quicker than normal. While sending, we tell the device not to go into low-power mode since it needs to keep to a fairly strict timer. + +Q: Why is this operating on incoming messages instead of the existing location discovery protocol? + +- This module is still young and currently supports monitoring just one port at a time. I decided to use the existing message port because that is easy to test with. A future version will listen to multiple ports to be more promiscuous. diff --git a/docs/software/modules/serial.md b/docs/software/modules/serial.md new file mode 100644 index 00000000..2a96a961 --- /dev/null +++ b/docs/software/modules/serial.md @@ -0,0 +1,40 @@ +--- +id: serial-module +title: Serial communication module +sidebar_label: Serial communication +--- + +## About + +This is a simple interface to send messages over the mesh network by sending strings over a serial port. + +Default is to use RX GPIO 16 and TX GPIO 17. + +## Basic Usage: + +1. Enable the module by setting `serial_module_enabled` to `1`. +2. Set the pins (`serial_module_rxd` / `serial_module_rxd`) for your preferred RX and TX GPIO pins. On tbeam boards it is recommended to use: + - RXD 35 + - TXD 15 +3. Set `serial_module_timeout` to the amount of time to wait before we consider your packet as "done". +4. (Optional) In serial_module.h set the port to `PortNum_TEXT_MESSAGE_APP`if you want to send messages to/from the general text message channel. +5. Connect to your device over the serial interface at `38400 8N1`. +6. Send a packet up to 240 bytes in length. This will get relayed over the mesh network. +7. (Optional) Set `serial_module_echo` to `1` and any message you send out will be echoed back to your device. + +:::note +The device must be restarted after the settings have been changed for the module to take effect. +::: + +## TODO (in this order): + +- Define a verbose RX mode to report on mesh and packet information. + +:::note +This won't happen any time soon. +::: + +## Known Problems + +- Until the module is initialized by the startup sequence, the TX pin is in a floating state. Device connected to that pin may see this as "noise". +- Will not work on NRF and the Linux device targets. diff --git a/docs/software/modules/store-forward.md b/docs/software/modules/store-forward.md new file mode 100644 index 00000000..32f787f5 --- /dev/null +++ b/docs/software/modules/store-forward.md @@ -0,0 +1,213 @@ +--- +id: store-forward-module +title: Store and Forward Module +sidebar_label: Store and Forward +--- + +## About + +:::caution +This is a work in progress and is partially available. Stability is not guaranteed. +::: + +The Store Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network. + +Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage nor is it advised to use this for SF12 (Long Range / Slow). + +### About - How it works + +![Store & Forward - Overview](/img/modules/store_and_forward/store_and_forward-overview.png) + +## Requirements + +Initial Requirements: + +- Must be installed on a router node. +- - This is an artificial limitation, but is in place to enforce best practices. +- - Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced. +- Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others) + +## Usage Overview + +- To use / test this you will want at least 3 devices +- - One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point. +- - Two others will be regular clients. Nothing special required. + +### Meshtastic channel configuration + +Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/device/radio-settings#pre-defined). + +Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast". + +Recommended channel setting is for 1.343kbps: + +```bash +meshtastic --setchan spread_factor 11 --setchan coding_rate 4 --setchan bandwidth 500 +``` + +With an aftermarket coaxial antenna or moxon antenna, that will give you roughly the same range as "Long Range / Slow" and 5x the bitrate. + +### Router setup + +- Configure your device as a meshtastic router. +- - https://meshtastic.org/docs/software/settings/router +- Configure the Store and Forward Module +- - Required configuration +- - - store_forward_module_enabled - Set this to true to enable the module. False to disable the module. +- - Optional configuration +- - - store_forward_module_records - Set this to the maximum number of records to save. Best to leave this at the default (0) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records. +- Name your router node something that makes it easily identifiable, aka "Router". + +Don't enable the Store and Forward module on multiple routers! + +### Client Usage + +Currently, no special configuration is required. To request your history sent to you, send the command into the message field "SF". That's it. This will eventually change to make it easier. At the moment, that message will be sent to everyone on the mesh but we'll (eventually) make it easier to use where there'll be a button (or maybe it'll be transparent) and the command isn't sent as a text message to the mesh. + +Available Commands: + +| Command | Definition | +| :-----: | :------------------------------------------: | +| SF | Send the last few messages I may have missed | +| SFm | Send a 240 byte payload (Used for testing) | + +The Store and Forward module will only service one client at a time. If a second client requests messages while the S&F is busy, the S&F will send a private message to the second client that they will need to wait. + +## Settings + +| Setting | Acceptable Values | Default | +| :-------------------------------------------: | :---------------: | :-----: | +| store_forward_module_enabled | `true`, `false` | `false` | +| store_forward_module_records | integer | `0` | +| store_forward_module_replay_max_records (tbd) | integer | `0` | +| store_forward_module_replay_max_time (tbd) | integer | `0` | + +## Example Request/Response + +### Request History (Use Router Defaults) + +Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed. The router will return the messages. + +- Carol +- - Packet (Port: STORE_FORWARD_APP) +- - - To: Broadcast (Optionally, direct to router) +- - - StoreAndForward.rr.CLIENT_HISTORY +- Router +- - Packet (Port: STORE_FORWARD_APP) +- - - To: Carol +- - - StoreAndForward.rr.ROUTER_HISTORY +- - - StoreAndForward.history.HistoryMessages = 42 // Router has 42 messages that will be sent to Carol. +- - - StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours. +- - - StoreAndForward.history.LastRequest = 0 // Carol has never asked for the history. +- - Packet (Port: TEXT_MESSAGE_APP) +- - - ... a series of 42 text messages + +### Request History (No history available) + +Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed but the router indicates there are no messages available. + +- Carol +- - Packet (Port: STORE_FORWARD_APP) +- - - To: Broadcast (Optionally, direct to router) +- - - StoreAndForward.rr.CLIENT_HISTORY +- Router +- - Packet (Port: STORE_FORWARD_APP) +- - - To: Carol +- - - StoreAndForward.rr.ROUTER_HISTORY +- - - StoreAndForward.history.HistoryMessages = 0 // Router has no messages to be sent to Carol. +- - - StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours. +- - - StoreAndForward.history.LastRequest = (timestamp) // Last time carol requested the history. + +### Store & Forward Router Heartbeat + +Story: The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. Client will not respond to network but (optionally) indicate to the user that a S&F router is available or not available. + +- Router +- - Packet (Port: STORE_FORWARD_APP) +- - - To: Broadcast +- - - StoreAndForward.rr.ROUTER_HEARTBEAT +- - - StoreAndForward.heartbeat.Period = 120 // Expect a heartbeat every 2 minutes. +- - - StoreAndForward.heartbeat.Secondary = false // If true, this is a secondary "backup" S&F node. Will be (eventually) used for router election in the event there are multiple S&F Routers. + +## Meshpacket + +To support functionality of Store and Forward, a new enum has been added to the MeshPacket. + +``` +typedef enum _MeshPacket_Delayed { + MeshPacket_Delayed_NO_DELAY = 0, + MeshPacket_Delayed_DELAYED_BROADCAST = 1, + MeshPacket_Delayed_DELAYED_DIRECT = 2 +} MeshPacket_Delayed; +``` + +- NO_DELAY - The packet was sent in real time. Store and Forward had no hand in this message. This is the default case. +- DELAYED_BROADCAST - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a broadcast packet. +- DELAYED_DIRECT - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a direct packet. + +As a reminder, broadcast messages are messages where the "to" of a payload is directed at NODENUM_BROADCAST or (0xFFFFFFFF). + +Example Cases: + +- Real time :: BROADCAST +- - Delayed = MeshPacket_Delayed_NO_DELAY +- - From: Ann +- - To: BROADCAST +- Real time :: Direct +- - Delayed = MeshPacket_Delayed_NO_DELAY +- - From: Ann +- - To: Bob +- Delayed :: BROADCAST +- - Delayed = MeshPacket_Delayed_DELAYED_BROADCAST +- - From: Ann +- - To: Bob +- Delayed :: Direct +- - Delayed = MeshPacket_Delayed_DELAYED_DIRECT +- - From: Ann +- - To: Bob + +When a message is 'real time', time a message is sent is the same as the time the message was received. In the case the message is delayed, there is no timestamp available for the message. + +Where the message is a delayed broadcast, the "To" is _not_ a broadcast address but rather the address of the device that requested the messages to be replayed. This is to allow the message to be routed over the mesh network and not displayed in the message screen of other devices. + +## Developer TODO + +Not necessarily in this order: + +- Client Interface (Web, Android, Python or iOS when that happens) to request packets be resent. + +- Router sends a heartbeat so the client knows there is a router in range. + +- Support for a mesh to have multiple routers that have the store & forward functionality (for redundancy). + +- Add a default channel at about 1.5kbit / sec. + +- Eventually we could add a "want_store_and_forward" bit to MeshPacket and that could be nicer than whitelists in this module. Initially we'd only set that bit in text messages (and any other module messages that can cope with this). This change would be backward wire compatible so can add easily later. + +- Have a "cool down" period to disallow a client to request the history too often. + +- Message with SF status on requests. + +- Be able to identify if you're within range of a router. + +- Be able to specify the HOP MAX to reduce airtime. Is this necessary? + +- Restrict operation of S&F on the slow channel configurations. + +- Create a TX queue to prevent the history from being modified in flight. + +- Only allow n-number of requests to the router at any one time. + +- Set number of max messages from the history. + +- Calculate a new channel with 250kHz bandwidth and ~1.5kbit. + +\*\*\* Done + +- Disable ACK. If the router is within range, so is the requester. + +- Currently the way we allocate messages in the device code is super inefficient. It always allocates the worst case message size. Really we should dynamically allocate just the # of bytes we need. This would allow many more MeshPackets to be kept in RAM. + +- Allow max history to be defined by radioConfig.preferences.store_forward_module_records. + +- Add a starting to send / finished sending message. diff --git a/docs/software/other/build-instructions.md b/docs/software/other/build-instructions.md index 69b60cad..12f76043 100644 --- a/docs/software/other/build-instructions.md +++ b/docs/software/other/build-instructions.md @@ -11,7 +11,7 @@ If you encounter any problems, please post a question in [our forum](https://mes ## GUI 1. Purchase a suitable [radio](/docs/hardware). -2. Install [Python](https://www.python.org/downloads/). +2. Install [Python](https://www.python.org/downloads). 3. Install [Git](https://git-scm.com/downloads). 4. Reboot your computer. 5. Install [PlatformIO](https://platformio.org/platformio-ide). diff --git a/docs/software/other/install-OSX.md b/docs/software/other/install-OSX.md index f4eb602d..68aa3b5a 100644 --- a/docs/software/other/install-OSX.md +++ b/docs/software/other/install-OSX.md @@ -42,7 +42,7 @@ After I installed that, esptool.py was completely happy and the firmware loaded brew install openssl ``` -- Set some flags in your bash/zsh/whichever profile for `esptool` to install [cryptography](https://cryptography.io/en/latest/installation/) as a dependency correctly: +- Set some flags in your bash/zsh/whichever profile for `esptool` to install [cryptography](https://cryptography.io/en/latest/installation) as a dependency correctly: ``` export LDFLAGS="-L/usr/local/opt/openssl/lib" diff --git a/docs/software/other/mqtt.md b/docs/software/other/mqtt.md index 45e363d7..c59fee30 100644 --- a/docs/software/other/mqtt.md +++ b/docs/software/other/mqtt.md @@ -5,29 +5,30 @@ sidebar_label: MQTT --- ## MQTT - -Meshtastic devices with wifi hardware (ESP32) are able to connect to an MQTT broker to uplink and downlink mesh packets. This is useful for a number of purposes: -- Connecting your mesh to the official Meshtastic MQTT broker. This makes your devices appear on the world map, and provides a limited copy of your mesh traffic, translated into JSON. +Meshtastic devices with wifi hardware (ESP32) are able to connect to an MQTT broker to uplink and downlink mesh packets. This is useful for a number of purposes: + +- Connecting your mesh to the official Meshtastic MQTT broker. This makes your devices appear on the world map, and provides a limited copy of your mesh traffic, translated into JSON. - Using a custom MQTT broker to bridge several mesh networks together, via the internet (or just a local IP network) -- Using a custom MQTT broker and a translator program to decode the raw protobuf packets and translate them into a plain text form for use in other systems. eg plotting temperature readings in Grafana, or device positions in Traccar. +- Using a custom MQTT broker and a translator program to decode the raw protobuf packets and translate them into a plain text form for use in other systems. eg plotting temperature readings in Grafana, or device positions in Traccar. -When MQTT enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf packet that it sees to the MQTT broker. All packets are sent to the broker, whether they originate from another device on the mesh, or the gateway node itself. +When MQTT enabled, the Meshtastic device simply uplinks and/or downlinks every raw protobuf packet that it sees to the MQTT broker. 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_server`), the `mqtt_encryption_enabled` setting applies, which by default is false. +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_server`), 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. +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 Topic The device will uplink and downlink packets to the `msh/` prefix: -`msh/1/c/ShortFast/!12345678` where +`msh/1/c/ShortFast/!12345678` where - `!12345678` is the address of the gateway device. - `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: +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: + ``` 苓????"! !937bed1cTanksTnk"D???05??=???aP` @@ -36,36 +37,34 @@ The payload is a raw protobuf. Looking at the MQTT traffic with a program like ### Basic Configuration -Check out [MQTT Settings](https://meshtastic.org/docs/software/settings/mqtt) for full information. For quick start instructions, read on. +Check out [MQTT Settings](/docs/software/settings/mqtt) for full information. For quick start instructions, read on. - Connect your gateway node to wifi, by setting the `wifi_ssid` and `wifi_password` preferences. -- Configure your broker settings: `mqtt_server`, `mqtt_username`, and `mqtt_password`. If all are left blank, the device will connect to the Meshtastic broker. -- Set `uplink_enabled` and `downlink_enabled` as appropriate for each channel. Most users will just have a single channel (at channel index 0). `meshtastic --ch-index 0 --ch-set uplink_enabled true` +- Configure your broker settings: `mqtt_server`, `mqtt_username`, and `mqtt_password`. If all are left blank, the device will connect to the Meshtastic broker. +- Set `uplink_enabled` and `downlink_enabled` as appropriate for each channel. Most users will just have a single channel (at channel index 0). `meshtastic --ch-index 0 --ch-set uplink_enabled true` `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. ### Getting plain data out of the mesh -As of firmware 1.2.53, it is possible for the device to decrypt the protobufs before publishing to MQTT. To translate this into a plain format: +As of firmware 1.2.53, it is possible for the device to decrypt the protobufs before publishing to MQTT. To translate this into a plain format: - Set up a gateway node to uplink packets to your MQTT broker: - - `meshtastic --set wifi_ssid XXXX` - - `meshtastic --set wifi_password XXXX` - - `meshtastic --set mqtt_server 192.168.1.1` - - `meshtastic --set mqtt_username XXXX` - - `meshtastic --set mqtt_password XXXX` - - `meshtastic --set mqtt_encryption_enabled false` - - `meshtastic --ch-index 0 --ch-set uplink_enabled true` + - `meshtastic --set wifi_ssid XXXX` + - `meshtastic --set wifi_password XXXX` + - `meshtastic --set mqtt_server 192.168.1.1` + - `meshtastic --set mqtt_username XXXX` + - `meshtastic --set mqtt_password XXXX` + - `meshtastic --set mqtt_encryption_enabled false` + - `meshtastic --ch-index 0 --ch-set uplink_enabled true` - Grab the meshtastic-mqtt script from [here](https://github.com/joshpirihi/meshtastic-mqtt) - - `git clone https://github.com/joshpirihi/meshtastic-mqtt && cd meshtastic-mqtt` - - Edit `meshtastic_mqtt/meshtastic_mqtt.py` and enter your mqtt broker details - - Install the script with `pip install .` - - Run `meshtastic-mqtt`. It will print some debug output by default, and publish the plain values to the `meshtastic/` prefix. - - View the plain data with `mosquitto_sub -h YOUR_MQTT_SERVER -t meshtastic/# -v` - - You can then consume the data easily in other systems. For example, nodered->influx db->grafana. - - + - `git clone https://github.com/joshpirihi/meshtastic-mqtt && cd meshtastic-mqtt` + - Edit `meshtastic_mqtt/meshtastic_mqtt.py` and enter your mqtt broker details + - Install the script with `pip install .` + - Run `meshtastic-mqtt`. It will print some debug output by default, and publish the plain values to the `meshtastic/` prefix. + - View the plain data with `mosquitto_sub -h YOUR_MQTT_SERVER -t meshtastic/# -v` + - You can then consume the data easily in other systems. For example, nodered->influx db->grafana. #Original brainstorming for MQTT: @@ -82,7 +81,7 @@ This is a mini-doc/RFC sketching out a development plan to satisfy a number of 1 - A text messaging bridge when a node in the mesh can gateway to the internet. Issue #[353](https://github.com/meshtastic/Meshtastic-device/issues/353) and this nicely documented [android issue](https://github.com/meshtastic/Meshtastic-Android/issues/2). - An easy way to let desktop app developers remotely control GPIOs. Issue #[182](https://github.com/meshtastic/Meshtastic-device/issues/182) - Remote attribute access (to change settings of distant nodes). Issue #182 -- Be sure to checkout [MQTT Settings](https://meshtastic.org/docs/software/settings/mqtt) +- Be sure to checkout [MQTT Settings](/docs/software/settings/mqtt) ## Short term goals @@ -118,7 +117,7 @@ Any gateway-device will contact the MQTT broker. ### 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. +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. @@ -132,7 +131,7 @@ FIXME, discuss possible attacks by griefers and how they can be prevented #### Service Envelope -The payload published on mesh/... will always be wrapped in a [ServiceEnvelope protobuf](https://meshtastic.org/docs/developers/protobufs/api#serviceenvelope). +The payload published on mesh/... will always be wrapped in a [ServiceEnvelope protobuf](/docs/developers/protobufs/api#serviceenvelope). ServiceEnvelope will include the message, and full information about arrival time, who forwarded it, source channel, source mesh id, etc... @@ -161,7 +160,7 @@ deduplicate if needed by using the packet ID of each message. #### Public MQTT broker service -An existing public [MQTT broker](https://mosquitto.org/) will be the default for this service, but clients can use any MQTT broker they choose. +An existing public [MQTT broker](https://mosquitto.org) will be the default for this service, but clients can use any MQTT broker they choose. FIXME - figure out how to avoid impersonation (because we are initially using a public MQTT server with no special security options). FIXME, include some ideas on this in the ServiceEnvelope documentation. @@ -169,7 +168,7 @@ FIXME - figure out how to avoid impersonation (because we are initially using a @Geeksville will run a riot.im bridge that talks to the public MQTT broker and sends/receives into the riot.im network. -There is apparently [already](https://github.com/derEisele/tuple) a riot.im [bridge](https://matrix.org/bridges/) for MQTT. That will possibly need to be customized a bit. But by doing this, we should be able to let random riot.im users send/receive messages to/from any meshtastic device. (FIXME ponder security). See this [issue](https://github.com/meshtastic/Meshtastic-Android/issues/2#issuecomment-645660990) with discussion with the dev. +There is apparently [already](https://github.com/derEisele/tuple) a riot.im [bridge](https://matrix.org/bridges) for MQTT. That will possibly need to be customized a bit. But by doing this, we should be able to let random riot.im users send/receive messages to/from any meshtastic device. (FIXME ponder security). See this [issue](https://github.com/meshtastic/Meshtastic-Android/issues/2#issuecomment-645660990) with discussion with the dev. ### Deprecated concepts @@ -282,12 +281,13 @@ mosquitto_pub -h localhost -q 0 -t test/hello -m 'yo!' ``` 5. For Meshtastic to be able to access that server, two settings need to be changed in the -`/usr/local/etc/mosquitto/mosquitto.conf` file: + `/usr/local/etc/mosquitto/mosquitto.conf` file: ``` listener 1883 0.0.0.0 allow_anonymous true ``` + 6. Restart the service: ``` diff --git a/docs/software/other/sw-design.md b/docs/software/other/sw-design.md index 9e42cd19..469ee043 100644 --- a/docs/software/other/sw-design.md +++ b/docs/software/other/sw-design.md @@ -7,7 +7,7 @@ sidebar_label: Software Design This is a mini design doc for developing the meshtastic software. - [Build instructions](build-instructions.md) -- [On device plugin API](/docs/developers/device/plugin-api) - a tutorial on how to write small Plugins which run on the device and can message other nodes. +- [On device module API](/docs/developers/device/module-api) - a tutorial on how to write small modules which run on the device and can message other nodes. - Our [project board](https://github.com/orgs/meshtastic/projects/1) - shows what things we are currently working on and remaining work items for the current release. - [Power Management](power.md) - [Mesh algorithm](/docs/developers/device/mesh-alg) diff --git a/docs/software/overview.md b/docs/software/overview.md index 3d3f8a61..e9470e0c 100644 --- a/docs/software/overview.md +++ b/docs/software/overview.md @@ -13,15 +13,15 @@ The following applications are available to support your Meshtastic network: - [Meshtastic.js](/docs/software/js/getting-started) provides a JavaScript library to interface with devices - [Meshtastic-python](/docs/software/python/python-installation) provides access from desktop computers including a command line interface - A [web interface](/docs/software/web/web-app-software) can be accessed over Wifi on ESP32 devices -- Pre-installed device plugins for: - - [Range testing](/docs/software/plugins/range-test-plugin) - - [External notifications](/docs/software/plugins/ext-notif-plugin) - - [Canned messages](/docs/software/plugins/canned-message-plugin) - - [Serial communication](/docs/software/plugins/serial-plugin) - - [Store and forwarding messages](/docs/software/plugins/store-forward-plugin) (in development) - - [Environment measurement](/docs/software/plugins/environment-plugin) (in development) +- Pre-installed device modules for: + - [Range testing](/docs/software/modules/range-test-module) + - [External notifications](/docs/software/modules/ext-notif-module) + - [Canned messages](/docs/software/modules/canned-message-module) + - [Serial communication](/docs/software/modules/serial-module) + - [Store and forwarding messages](/docs/software/modules/store-forward-module) (in development) + - [Environment measurement](/docs/software/modules/environment-module) (in development) - Community projects include: - - A [plugin](/docs/software/community/community-atak) for the [Android Team Awareness Kit (ATAK)](https://play.google.com/store/apps/details?id=com.atakmap.app.civ) + - A [module](/docs/software/community/community-atak) for the [Android Team Awareness Kit (ATAK)](https://play.google.com/store/apps/details?id=com.atakmap.app.civ) - [PyGUI](/docs/software/community/community-pygui), a platform agnostic graphical user interface for devices The devices running Meshtastic have many preferences that can be set, see the [Settings](/docs/settings) pages for more details. diff --git a/docs/software/plugins/environment.md b/docs/software/plugins/environment.md deleted file mode 100644 index 28af7d35..00000000 --- a/docs/software/plugins/environment.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -id: environment-plugin -title: Environment measurement -sidebar_label: Environment measurement ---- -## About - -The Environment Measurement Plugin will allow nodes to send a specific message with information from connected environmental sensors. Currently supported sensors are BME280, BME680, DHT11, DHT12, DHT21, DHT22, Dallas 1-wire DS18B20, and MCP9808. - -The preferred setup is using I2C, so the `environmental_measurement_plugin_sensor_pin` may not be needed. - -## Configuration - -These are the settings that can be configured. - - environmental_measurement_plugin_enabled - Is the plugin enabled? - - 0 = Disabled (Default) - 1 = Enabled - - environmental_measurement_plugin_screen_enabled - Show received sensor readings on device screen. - - 0 = Disabled (Default) - 1 = Enabled - - environmental_measurement_plugin_read_error_count_threshold - Error count threshold for failed sensor readings. - - Default = 0 - - preferences.environmental_measurement_plugin_update_interval - How often (in seconds) should sensor readings be broadcasted? - - Default = 0 - - environmental_measurement_plugin_recovery_interval - For how long should we wait (in seconds) before trying to read sensors again upon exceeded error threshold? - - Default = 0 - - environmental_measurement_plugin_display_fahrenheit - Should temperature readings be converted to fahrenheit? - - 0 = Disabled (Default) - 1 = Enabled - - environmental_measurement_plugin_sensor_type - What sensor is connected? - - 0 = DHT11 (Default) - 1 = Dallas 1-wire DS18B20 - 2 = DHT12 - 3 = DHT21 - 4 = DHT22 - 5 = BME280 - 6 = BME680 - 7 = MCP9808 - - environmental_measurement_plugin_sensor_pin - Which pin is the sensor connected to? - - Default = 0 - - -## Usage Notes - -For basic usage, start with: - - environmental_measurement_plugin_enabled = 1 - - environmental_measurement_plugin_screen_enabled = 1 - -Depending on which pin your sensor is connected to, set it accordingly: - - environmental_measurement_plugin_sensor_pin = 13 - - -:::note -The device must be restarted after the settings have been changed for the plugin to take effect. -::: - - -## Hardware - -The sensors can be wired differently, here's one example for sensor DS18B20 https://randomnerdtutorials.com/esp32-ds18b20-temperature-arduino-ide - -## Example of T-LoraV1 with DHT22 temperature sensor - -Setup of a T-LoraV1 with DHT22 temperature sensor. - -[](/img/hardware/lora_v1_with_DHT22.jpg) - -Requirements: -* T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use) -* DHT22 sensor -* 10 Kohm resistor (optional, but recommended) -* breadboard (optional) -* two red wires (could be a different color, but 5V is typically red) -* two yellow wires for GPIO (could be a different color) -* one black wire (could be a different color, but GROUND is typically black) - -Steps: -* disconnect power/battery -* connect black wire from GROUND to "-" on the DHT22 -* connect yellow wire from middle PIN to a row on bread board -* connect red wire from 5V to a row on breadboard -* connect resistor between red and yellow rows -* connect red wire from row with red to "+" on DHT22 -* connect yellow wire from yellow row to GPIO on device (ex: GPIO21) -* double check the cabling (if you get it wrong, you can damage the device and/or the DHT22 sensor) -* plug in device -* configure the device: - -``` -meshtastic --set environmental_measurement_plugin_measurement_enabled true --set environmental_measurement_plugin_screen_enabled true --set environmental_measurement_plugin_update_interval 15 --set environmental_measurement_plugin_display_farenheit true --set environmental_measurement_plugin_sensor_type DHT22 --set environmental_measurement_plugin_sensor_pin 21 -``` - -:::tip -You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above. -::: - -* reboot/reset the device (press the RST button or unplug/plug in the device) -* when the device boots it should say "Environment" and it may show the sensor data -* if "no data", then triple check the wiring -* if still "no data", run: - -``` -meshtastic --info -``` - -and verify the the environmental_measurement_plugin_sensor_type and environmental_measurement_plugin_sensor_pin - - -## Example of T-LoraV1 with Dallas DS18B20 temperature sensor - -Setup of a T-LoraV1 with DS18B20 temperature sensor. - -[](/img/hardware/lora_v1_with_DS18B20.jpg) - -Requirements: -* T-LoraV1 (but any esp32 should work, just be sure to double check which GPIO to use) -* DS18B20 sensor -* 10 Kohm resistor (optional, but recommended) -* breadboard (optional) -* two red wires (could be a different color, but 5V is typically red) -* two yellow wires for GPIO (could be a different color) -* one black wire (could be a different color, but GROUND is typically black) - -Steps: -* disconnect power/battery -* connect black wire from GROUND to "-" on the DS18B20 -* connect yellow wire from DAT pin to a row on bread board -* connect red wire from 5V to a row on breadboard -* connect resistor between red and yellow rows -* connect red wire from row with red to "VCC" on DS18B20 -* connect yellow wire from yellow row to GPIO on device (ex: GPIO21) -* double check the cabling (if you get it wrong, you can damage the device and/or the sensor) -* plug in device -* configure the device: - -``` -meshtastic --set environmental_measurement_plugin_measurement_enabled true --set environmental_measurement_plugin_screen_enabled true --set environmental_measurement_plugin_update_interval 15 --set environmental_measurement_plugin_display_farenheit true --set environmental_measurement_plugin_sensor_type DS18B20 --set environmental_measurement_plugin_sensor_pin 21 -``` - -:::tip -You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above. -::: - -* reboot/reset the device (press the RST button or unplug/plug in the device) -* when the device boots it should say "Environment" and it may show the sensor data -* if "no data", then triple check the wiring -* if still "no data", run: - -``` -meshtastic --info -``` - -and verify the the environmental_measurement_plugin_sensor_type and environmental_measurement_plugin_sensor_pin - -## Example of RAK 4631 with Environment Sensor - -Setup of a RAK 4631 with Environment Sensor - -[](/img/hardware/rak/RAK4631_with_EnvSensor.jpg) - -Requirements: -* RAK4631 -* Environment Sensor - -Steps: -* configure the device: - -``` -meshtastic --set environmental_measurement_plugin_measurement_enabled true --set environmental_measurement_plugin_screen_enabled true --set environmental_measurement_plugin_update_interval 15 --set environmental_measurement_plugin_display_farenheit true --set environmental_measurement_plugin_sensor_type 6 -``` - -:::tip -You can change the values above to suit your needs. The commands can be run one at a time or in a group as show above. -::: - -* reboot/reset the device (press the button or unplug/plug in the device) -* when the device boots it should say "Environment" and it may show the sensor data -* if still "no data", run: - -``` -meshtastic --info -``` - -and verify the the environmental_measurement_plugin_sensor_type - -## Known Problems - -* No default configuration values are currently set, so this must be done when enabling the plugin. diff --git a/docs/software/plugins/serial.md b/docs/software/plugins/serial.md deleted file mode 100644 index 7ba10ce1..00000000 --- a/docs/software/plugins/serial.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: serial-plugin -title: Serial communication plugin -sidebar_label: Serial communication ---- - -## About - -This is a simple interface to send messages over the mesh network by sending strings over a serial port. - -Default is to use RX GPIO 16 and TX GPIO 17. - -## Basic Usage: - -1. Enable the plugin by setting `serialplugin_enabled` to `1`. -2. Set the pins (`serialplugin_rxd` / `serialplugin_rxd`) for your preferred RX and TX GPIO pins. On tbeam boards it is recommended to use: - * RXD 35 - * TXD 15 -3. Set `serialplugin_timeout` to the amount of time to wait before we consider your packet as "done". -4. (Optional) In SerialPlugin.h set the port to `PortNum_TEXT_MESSAGE_APP`if you want to send messages to/from the general text message channel. -5. Connect to your device over the serial interface at `38400 8N1`. -6. Send a packet up to 240 bytes in length. This will get relayed over the mesh network. -7. (Optional) Set `serialplugin_echo` to `1` and any message you send out will be echoed back to your device. - -:::note -The device must be restarted after the settings have been changed for the plugin to take effect. -::: - -## TODO (in this order): - -* Define a verbose RX mode to report on mesh and packet information. - -:::note -This won't happen any time soon. -::: - -## Known Problems - -* Until the plugin is initialized by the startup sequence, the TX pin is in a floating state. Device connected to that pin may see this as "noise". -* Will not work on NRF and the Linux device targets. diff --git a/docs/software/plugins/store-forward.md b/docs/software/plugins/store-forward.md deleted file mode 100644 index c571224f..00000000 --- a/docs/software/plugins/store-forward.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -id: store-forward-plugin -title: Store and Forward plugin -sidebar_label: Store and Forward ---- - -## About -:::caution -This is a work in progress and is partially available. Stability is not guaranteed. -::: - -The Store Forward Plugin is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network. - -Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage nor is it advised to use this for SF12 (Long Range / Slow). - -### About - How it works - -![Store & Forward - Overview](/img/plugins/store_and_forward/store_and_forward-overview.png) - -## Requirements - -Initial Requirements: - -* Must be installed on a router node. -* * This is an artificial limitation, but is in place to enforce best practices. -* * Router nodes are intended to be always online. If this plugin misses any messages, the reliability of the stored messages will be reduced. -* Esp32 Processor based device with external PSRAM. (tbeam v1.0 and tbeamv1.1, and maybe others) - -## Usage Overview - -* To use / test this you will want at least 3 devices -* * One device will (currently) need be a tbeam v1.0 and tbeamv1.1 configured as a Meshtastic router. Other devices with built in PSRAM will be supported at some point. -* * Two others will be regular clients. Nothing special required. - -### Meshtastic channel configuration - -Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/developers/device/radio-settings#pre-defined). - -Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast". - -Recommended channel setting is for 1.343kbps: - -```bash -meshtastic --setchan spread_factor 11 --setchan coding_rate 4 --setchan bandwidth 500 -``` - -With an aftermarket coaxial antenna or moxon antenna, that will give you roughly the same range as "Long Range / Slow" and 5x the bitrate. - -### Router setup - -* Configure your device as a meshtastic router. -* * https://meshtastic.org/docs/software/settings/router -* Configure the Store and Forward plugin -* * Required configuration -* * * store_forward_plugin_enabled - Set this to true to enable the plugin. False to disable the plugin. -* * Optional configuration -* * * store_forward_plugin_records - Set this to the maximum number of records to save. Best to leave this at the default (0) where the plugin will use 2/3 of your device's available PSRAM. This is about 11,000 records. -* Name your router node something that makes it easily identifiable, aka "Router". - -Don't enable the Store and Forward plugin on multiple routers! - -### Client Usage - -Currently, no special configuration is required. To request your history sent to you, send the command into the message field "SF". That's it. This will eventually change to make it easier. At the moment, that message will be sent to everyone on the mesh but we'll (eventually) make it easier to use where there'll be a button (or maybe it'll be transparent) and the command isn't sent as a text message to the mesh. - -Available Commands: - -| Command | Definition | -| :-----: | :---------------: | -| SF | Send the last few messages I may have missed | -| SFm | Send a 240 byte payload (Used for testing) | - -The Store and Forward plugin will only service one client at a time. If a second client requests messages while the S&F is busy, the S&F will send a private message to the second client that they will need to wait. - -## Settings - -| Setting | Acceptable Values | Default | -| :-----: | :---------------: | :-----: | -| store_forward_plugin_enabled | `true`, `false` | `false` | -| store_forward_plugin_records | integer | `0` | -| store_forward_plugin_replay_max_records (tbd) | integer | `0` | -| store_forward_plugin_replay_max_time (tbd) | integer | `0` | - - -## Example Request/Response - -### Request History (Use Router Defaults) - -Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed. The router will return the messages. - -* Carol -* * Packet (Port: STORE_FORWARD_APP) -* * * To: Broadcast (Optionally, direct to router) -* * * StoreAndForward.rr.CLIENT_HISTORY -* Router -* * Packet (Port: STORE_FORWARD_APP) -* * * To: Carol -* * * StoreAndForward.rr.ROUTER_HISTORY -* * * StoreAndForward.history.HistoryMessages = 42 // Router has 42 messages that will be sent to Carol. -* * * StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours. -* * * StoreAndForward.history.LastRequest = 0 // Carol has never asked for the history. -* * Packet (Port: TEXT_MESSAGE_APP) -* * * ... a series of 42 text messages - -### Request History (No history available) - -Story: Carol has been away from the mesh with device turned off. She would like to get a replay of what she has missed but the router indicates there are no messages available. - -* Carol -* * Packet (Port: STORE_FORWARD_APP) -* * * To: Broadcast (Optionally, direct to router) -* * * StoreAndForward.rr.CLIENT_HISTORY -* Router -* * Packet (Port: STORE_FORWARD_APP) -* * * To: Carol -* * * StoreAndForward.rr.ROUTER_HISTORY -* * * StoreAndForward.history.HistoryMessages = 0 // Router has no messages to be sent to Carol. -* * * StoreAndForward.history.Window = 120 // Router searched for messages over the last two hours. -* * * StoreAndForward.history.LastRequest = (timestamp) // Last time carol requested the history. - -### Store & Forward Router Heartbeat - -Story: The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. Client will not respond to network but (optionally) indicate to the user that a S&F router is available or not available. - -* Router -* * Packet (Port: STORE_FORWARD_APP) -* * * To: Broadcast -* * * StoreAndForward.rr.ROUTER_HEARTBEAT -* * * StoreAndForward.heartbeat.Period = 120 // Expect a heartbeat every 2 minutes. -* * * StoreAndForward.heartbeat.Secondary = false // If true, this is a secondary "backup" S&F node. Will be (eventually) used for router election in the event there are multiple S&F Routers. - -## Meshpacket - -To support functionality of Store and Forward, a new enum has been added to the MeshPacket. - -``` -typedef enum _MeshPacket_Delayed { - MeshPacket_Delayed_NO_DELAY = 0, - MeshPacket_Delayed_DELAYED_BROADCAST = 1, - MeshPacket_Delayed_DELAYED_DIRECT = 2 -} MeshPacket_Delayed; -``` - -* NO_DELAY - The packet was sent in real time. Store and Forward had no hand in this message. This is the default case. -* DELAYED_BROADCAST - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a broadcast packet. -* DELAYED_DIRECT - This is a delayed message. The 'to' of the packet has been directed at a named user but was previously a direct packet. - -As a reminder, broadcast messages are messages where the "to" of a payload is directed at NODENUM_BROADCAST or (0xFFFFFFFF). - -Example Cases: - -* Real time :: BROADCAST -* * Delayed = MeshPacket_Delayed_NO_DELAY -* * From: Ann -* * To: BROADCAST -* Real time :: Direct -* * Delayed = MeshPacket_Delayed_NO_DELAY -* * From: Ann -* * To: Bob -* Delayed :: BROADCAST -* * Delayed = MeshPacket_Delayed_DELAYED_BROADCAST -* * From: Ann -* * To: Bob -* Delayed :: Direct -* * Delayed = MeshPacket_Delayed_DELAYED_DIRECT -* * From: Ann -* * To: Bob - -When a message is 'real time', time a message is sent is the same as the time the message was received. In the case the message is delayed, there is no timestamp available for the message. - -Where the message is a delayed broadcast, the "To" is *not* a broadcast address but rather the address of the device that requested the messages to be replayed. This is to allow the message to be routed over the mesh network and not displayed in the message screen of other devices. - -## Developer TODO - -Not necessarily in this order: - -* Client Interface (Web, Android, Python or iOS when that happens) to request packets be resent. - -* Router sends a heartbeat so the client knows there is a router in range. - -* Support for a mesh to have multiple routers that have the store & forward functionality (for redundancy). - -* Add a default channel at about 1.5kbit / sec. - -* Eventually we could add a "want_store_and_forward" bit to MeshPacket and that could be nicer than whitelists in this plugin. Initially we'd only set that bit in text messages (and any other plugin messages that can cope with this). This change would be backward wire compatible so can add easily later. - -* Have a "cool down" period to disallow a client to request the history too often. - -* Message with SF status on requests. - -* Be able to identify if you're within range of a router. - -* Be able to specify the HOP MAX to reduce airtime. Is this necessary? - -* Restrict operation of S&F on the slow channel configurations. - -* Create a TX queue to prevent the history from being modified in flight. - -* Only allow n-number of requests to the router at any one time. - -* Set number of max messages from the history. - -* Calculate a new channel with 250kHz bandwidth and ~1.5kbit. - -*** Done - -* Disable ACK. If the router is within range, so is the requester. - -* Currently the way we allocate messages in the device code is super inefficient. It always allocates the worst case message size. Really we should dynamically allocate just the # of bytes we need. This would allow many more MeshPackets to be kept in RAM. - -* Allow max history to be defined by radioConfig.preferences.store_forward_plugin_records. - -* Add a starting to send / finished sending message. - diff --git a/docs/software/python/installation.md b/docs/software/python/installation.md index 0fa18162..55f2a007 100644 --- a/docs/software/python/installation.md +++ b/docs/software/python/installation.md @@ -3,6 +3,7 @@ id: python-installation title: Meshtastic-python installation sidebar_label: Installation --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -10,11 +11,11 @@ This library provides a command line interface (CLI) for Meshtastic nodes and pr The [Meshtastic-python repo](https://github.com/meshtastic/Meshtastic-python) and [API documentation](https://python.meshtastic.org) are excellent sources of information. -If you wish to view the code or contribute to development of the python library or the command line interface, please visit the Meshtastic python GitHub page. +If you wish to view the code or contribute to development of the python library or the command line interface, please visit the Meshtastic python [GitHub page](https://github.com/meshtastic/Meshtastic-python). -There are standalone executables for Mac, Windows and Ubuntu if you do not want to install python and/or the python libraries required to run the mestastic CLI tool. See [Standalone](https://meshtastic.org/docs/software/python/python-standalone) for more information. +There are standalone executables for Mac, Windows and Ubuntu if you do not want to install python and/or the python libraries required to run the mestastic CLI tool. See [Standalone](/docs/software/python/python-standalone) for more information. -Installation can also be easily done through the [Python package installer pip](https://pypi.org/project/meshtastic/): +Installation can also be easily done through the [Python package installer pip](https://pypi.org/project/meshtastic): :::note You must use pip version 20 or later. To upgrade to the latest pip, do: `pip install --upgrade pip` ::: @@ -28,163 +29,167 @@ Some newer boards may require the drivers for the [CH9102](http://www.wch.cn/dow ::: +groupId="operating-system" +defaultValue="linux" +values={[ +{label: 'Linux', value: 'linux'}, +{label: 'macOS', value: 'macos'}, +{label: 'Windows', value: 'windows'}, +{label: 'Termux for Android', value: 'termux'}, +]}> -* Check that your computer has the required serial drivers installed - * Connect your Meshtastic device to your USB port - * Use the command - ```bash - lsusb - ``` - * You should see something like: - * `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X - * `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102 +- Check that your computer has the required serial drivers installed -* Check that your computer has Python 3 installed. - * Use the command - ```bash - python3 -V - ``` - * If this does not return a version, install python - ```bash - sudo apt-get update - sudo apt-get install python3 - ``` - -* Pip is typically installed if you are using python 3 version >= 3.4 - * Check that pip is installed using this command - ```bash - pip3 -V - ``` - * If this does not return a version, install pip - ```bash - sudo apt-get install python3-pip - ``` - -* Optional: use a python virtual environment (otherwise jump to step "Install pytap2") - * Install python-virtualenvwrapper (arch based distros as an example) - ```bash - sudo pacman -Syu python-virtualenvwrapper - ``` - * Create a virtual environment - ```bash - source /usr/bin/virtualenvwrapper.sh - mkvirtualenv meshtastic - workon meshtastic - ``` -* Install pytap2 + - Connect your Meshtastic device to your USB port + - Use the command ```bash - pip3 install --upgrade pytap2 + lsusb ``` -* Install meshtastic: + - You should see something like: + - `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X + - `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102 + +- Check that your computer has Python 3 installed. + + - Use the command ```bash - pip3 install --upgrade meshtastic + python3 -V ``` + - If this does not return a version, install python + ```bash + sudo apt-get update + sudo apt-get install python3 + ``` + +- Pip is typically installed if you are using python 3 version >= 3.4 + + - Check that pip is installed using this command + ```bash + pip3 -V + ``` + - If this does not return a version, install pip + ```bash + sudo apt-get install python3-pip + ``` + +- Optional: use a python virtual environment (otherwise jump to step "Install pytap2") + - Install python-virtualenvwrapper (arch based distros as an example) + ```bash + sudo pacman -Syu python-virtualenvwrapper + ``` + - Create a virtual environment + ```bash + source /usr/bin/virtualenvwrapper.sh + mkvirtualenv meshtastic + workon meshtastic + ``` +- Install pytap2 + ```bash + pip3 install --upgrade pytap2 + ``` +- Install meshtastic: + ```bash + pip3 install --upgrade meshtastic + ``` -* Check that your computer has the required serial drivers installed - * Connect your Meshtastic device to your USB port - * Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB` - * You should see something like `CP210X USB to UART Bridge Controller` - * If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers). -* Check that your computer has Python 3 installed. - * Use the command - ```bash - python3 -V - ``` - * If this does not return a version, install [python](https://www.python.org) - * The following uses Homebrew to install `python3` which includes `pip3`. - * Check if you have Homebrew installed with the following command - ```bash - brew -v - ``` - If it's not installed, follow the instructions on the [Homebrew website](https://brew.sh) before continuing. - * Install Python3 - ```bash - brew install python3 - ``` -* Pip is typically installed if you are using python 3 version >= 3.4 - * Check that pip is installed using this command - ```bash - pip3 -V - ``` - * If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing/) +- Check that your computer has the required serial drivers installed + - Connect your Meshtastic device to your USB port + - Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB` + - You should see something like `CP210X USB to UART Bridge Controller` + - If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers). +- Check that your computer has Python 3 installed. + - Use the command + ```bash + python3 -V + ``` + - If this does not return a version, install [python](https://www.python.org) + - The following uses Homebrew to install `python3` which includes `pip3`. + - Check if you have Homebrew installed with the following command + ```bash + brew -v + ``` + If it's not installed, follow the instructions on the [Homebrew website](https://brew.sh) before continuing. + - Install Python3 + ```bash + brew install python3 + ``` +- Pip is typically installed if you are using python 3 version >= 3.4 -* Install pytap2 + - Check that pip is installed using this command ```bash - sudo pip3 install --upgrade pytap2 - ``` -* Install meshtastic: - ```bash - sudo pip3 install --upgrade meshtastic + pip3 -V ``` + - If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing) + +- Install pytap2 + ```bash + sudo pip3 install --upgrade pytap2 + ``` +- Install meshtastic: + ```bash + sudo pip3 install --upgrade meshtastic + ``` -* Check that your computer has the required serial drivers installed - * Connect your Meshtastic device to your USB port - * Open Device Manager - * Under `Ports (COM & LPT)` you should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)` - * If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers) or use the direct link below. +- Check that your computer has the required serial drivers installed + - Connect your Meshtastic device to your USB port + - Open Device Manager + - Under `Ports (COM & LPT)` you should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)` + - If not download the drivers from [Silicon Labs](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers) or use the direct link below. :::warning You must install the [CP210x Universal Windows Driver](https://www.silabs.com/documents/public/software/CP210x_Universal_Windows_Driver.zip). If you do not install this driver, your device may not work and the driver may need to be uninstalled from device manager before installing the correct driver. ::: -* Check that your computer has Python 3 installed. - * Use the command - ```powershell - py -V - ``` - * If this does not return a version, install [python](https://www.python.org) -* Pip is typically installed if you are using python 3 version >= 3.4 - * Check that pip is installed using this command - ```powershell - pip3 -V - ``` - * If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing/) -* Install pytap2 +- Check that your computer has Python 3 installed. + - Use the command ```powershell - pip3 install --upgrade pytap2 + py -V ``` -* Install meshtastic: + - If this does not return a version, install [python](https://www.python.org) +- Pip is typically installed if you are using python 3 version >= 3.4 + - Check that pip is installed using this command ```powershell - pip3 install --upgrade meshtastic + pip3 -V ``` + - If this does not return a version, install [pip](https://pip.pypa.io/en/stable/installing) +- Install pytap2 + ```powershell + pip3 install --upgrade pytap2 + ``` +- Install meshtastic: + ```powershell + pip3 install --upgrade meshtastic + ``` :::note -Wifi connection is currently under development and may not be working properly just yet. If you would like to provide feedback or test this feature, please visit our [forum](https://meshtastic.discourse.group/) or join our [Discord server](https://discord.gg/RjQKWHmzPZ) for more information. +Wifi connection is currently under development and may not be working properly just yet. If you would like to provide feedback or test this feature, please visit our [forum](https://meshtastic.discourse.group) or join our [Discord server](https://discord.gg/RjQKWHmzPZ) for more information. ::: -* Install [Termux](https://f-droid.org/en/packages/com.termux/) from the F-Droid app store (Google play does not currently support the latest builds) -* Load Termux and update the package list - ``` - pkg update - ``` -* Upgrade the installed packages - ``` - pkg upgrade - ``` -* Install python - ``` - pkg install python - ``` -* Upgrade pip and installed meshtastic and some of its dependencies - ``` - pip install --upgrade pip pygatt pytap2 wheel mesthtastic - ``` +- Install [Termux](https://f-droid.org/en/packages/com.termux) from the F-Droid app store (Google play does not currently support the latest builds) +- Load Termux and update the package list + ``` + pkg update + ``` +- Upgrade the installed packages + ``` + pkg upgrade + ``` +- Install python + ``` + pkg install python + ``` +- Upgrade pip and installed meshtastic and some of its dependencies + ``` + pip install --upgrade pip pygatt pytap2 wheel mesthtastic + ``` :::note Be aware that the Meshtastic CLI is not able to control the nodes over USB through termux, but you can control devices over Wifi using the `--host x.x.x.x` option with the device IP address. However, only ESP32 devices can use Wifi currently. diff --git a/docs/software/python/uses.md b/docs/software/python/uses.md index 0f74bf37..b796a33c 100644 --- a/docs/software/python/uses.md +++ b/docs/software/python/uses.md @@ -7,7 +7,7 @@ sidebar_label: Uses This section covers using the "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the Meshtastic devices. :::note -The `meshtastic` command is not run within python but is a script run from your operating system shell prompt. When you type "meshtastic" and the prompt is unable to find the command in Windows, check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path/). +The `meshtastic` command is not run within python but is a script run from your operating system shell prompt. When you type "meshtastic" and the prompt is unable to find the command in Windows, check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path). ::: ## Getting a list of User Preferences diff --git a/docs/software/web/overview.md b/docs/software/web/overview.md index 317d107d..eff05b8c 100644 --- a/docs/software/web/overview.md +++ b/docs/software/web/overview.md @@ -6,7 +6,7 @@ sidebar_label: Overview -Meshtastic Web is a [Progressive Web App](https://web.dev/progressive-web-apps/) that runs directly in your browser. +Meshtastic Web is a [Progressive Web App](https://web.dev/progressive-web-apps) that runs directly in your browser. There are three ways of accessing the app: 1. Served directly from an ESP32 based node via [meshtastic.local](http://meshtastic.local) or the device's IP Address. @@ -15,7 +15,7 @@ There are three ways of accessing the app: ## Compatibility -The application will work in all major browsers, but specific functionality is limited in some cases, for the best experience we reccomend using [Google Chrome](https://www.google.com/chrome/) +The application will work in all major browsers, but specific functionality is limited in some cases, for the best experience we reccomend using [Google Chrome](https://www.google.com/chrome) ### HTTP @@ -34,15 +34,13 @@ You have two primary options for accessing your device over HTTP, those being [C ### Bluetooth -Bluetooth support is governed by the availability of the [Web Bluetooth API](https://web.dev/bluetooth/) as illustrated blow, support is primarily available in Chromium browsers +Bluetooth support is governed by the availability of the [Web Bluetooth API](https://web.dev/bluetooth) as illustrated blow, support is primarily available in Chromium browsers ![Web Bluetooth compatability matrix](https://caniuse.bitsofco.de/image/web-bluetooth.png) - - ### Serial (USB) -The method with the least platform support, uses the [Web Serial API](https://web.dev/serial/) allows us to connect directly to a Meshtastic node over USB, accessing it directly within your browser. +The method with the least platform support, uses the [Web Serial API](https://web.dev/serial) allows us to connect directly to a Meshtastic node over USB, accessing it directly within your browser. ![Web Serial compatability matrix](https://caniuse.bitsofco.de/image/web-serial.png) @@ -50,8 +48,6 @@ The method with the least platform support, uses the [Web Serial API](https://we The web interface is now included in firmware releases. There is active development ongoing to fix some issues with updating the web interface from the web interface directly. Please be patient with us as we work on this. Use [Meshtastic-flasher](/docs/getting-started/meshtastic-flasher) to update your device to the current stable build which includes the web interface. - - :::warning Old documentation below. diff --git a/docs/software/web/partitions.md b/docs/software/web/partitions.md index 68c5e2af..12c78311 100644 --- a/docs/software/web/partitions.md +++ b/docs/software/web/partitions.md @@ -3,6 +3,7 @@ id: web-partitions-software title: Managing ESP32 partitions sidebar_label: ESP32 partitions --- + :::caution It has been reported that some of this information is out of date. Flashing the device with [Meshtastic-flasher](/docs/getting-started/meshtastic-flasher) should fix these partition issues and update you to the current web interface. @@ -28,15 +29,19 @@ The most reliable way to fix this problem is to use the install script that is i 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 meshtastic-device 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). +Requires: [Python](https://www.python.org), [Pio](https://pypi.org/project/pio), command to be run in the root directory of the meshtastic-device 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: + ```bash esptool.py --baud 921600 erase_flash esptool.py --baud 921600 write_flash 0x1000 system-info.bin @@ -44,16 +49,17 @@ 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) +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 meshtastic-device code as per the [build instructions](/docs/software/other/build-instructions). 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-device project +Requires: [Visual Studio Code](https://code.visualstudio.com), [PlatformIO](https://platformio.org), cloned copy of the Meshtastic-device project ## How do I know it's worked? diff --git a/sidebars.js b/sidebars.js index 2c7a6df6..ce09283a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -3,7 +3,7 @@ module.exports = { "About Meshtastic": [ "about/overview", { - "Concepts": [ + Concepts: [ "about/concepts/overview", "about/concepts/channels", "about/concepts/clients", @@ -14,13 +14,13 @@ module.exports = { }, "about/expectations", { - "FAQs": [ + FAQs: [ "faq/faq", "faq/antenna", "faq/bluetooth", "faq/channel", { - "Clients": [ + Clients: [ "faq/client-android", "faq/client-python-cli", "faq/client-ios", @@ -30,10 +30,10 @@ module.exports = { "faq/device", "faq/mesh", "faq/mqtt", - "faq/plugins", + "faq/modules", "faq/wifi", ], - } + }, ], }, Software: { @@ -88,14 +88,14 @@ module.exports = { ], }, { - Plugins: [ - "software/plugins/plugins", - "software/plugins/range-test-plugin", - "software/plugins/ext-notif-plugin", - "software/plugins/canned-message-plugin", - "software/plugins/serial-plugin", - "software/plugins/store-forward-plugin", - "software/plugins/environment-plugin", + Modules: [ + "software/modules/modules", + "software/modules/range-test-module", + "software/modules/ext-notif-module", + "software/modules/canned-message-module", + "software/modules/serial-module", + "software/modules/store-forward-module", + "software/modules/environment-module", ], }, { @@ -130,12 +130,12 @@ module.exports = { }, ], "Additional Documentation": [ - {type: "ref", id: "getting-started/overview"}, - {type: "ref", id: "settings/overview"}, - {type: "ref", id: "hardware/overview"}, - {type: "ref", id: "developers/overview"}, - {type: "ref", id: "developers/maintaining-documentation/overview"}, - {type: "ref", id: "legal/overview"}, + { type: "ref", id: "getting-started/overview" }, + { type: "ref", id: "settings/overview" }, + { type: "ref", id: "hardware/overview" }, + { type: "ref", id: "developers/overview" }, + { type: "ref", id: "developers/maintaining-documentation/overview" }, + { type: "ref", id: "legal/overview" }, ], }, Configuration: { @@ -154,9 +154,7 @@ module.exports = { ], }, { - "Connect to Device": [ - "getting-started/clients", - ], + "Connect to Device": ["getting-started/clients"], }, "getting-started/first-steps", ], @@ -171,27 +169,24 @@ module.exports = { "settings/router", "settings/wifi", { - Plugins: [ - "settings/canned-message-plugin", - "settings/environmental-measurement-plugin", - "settings/external-notification-plugin", - "settings/range-test-plugin", - "settings/rotary-encoder-plugin", - "settings/serial-plugin", - "settings/store-and-forward-plugin", - ], - Advanced: [ - "settings/channel-advanced", - "settings/misc", + Modules: [ + "settings/canned-message-module", + "settings/environmental-measurement-module", + "settings/external-notification-module", + "settings/range-test-module", + "settings/rotary-encoder-module", + "settings/serial-module", + "settings/store-and-forward-module", ], + Advanced: ["settings/channel-advanced", "settings/misc"], }, ], "Additional Documentation": [ - {type: "ref", id: "hardware/overview"}, - {type: "ref", id: "software/overview"}, - {type: "ref", id: "developers/overview"}, - {type: "ref", id: "developers/maintaining-documentation/overview"}, - {type: "ref", id: "legal/overview"}, + { type: "ref", id: "hardware/overview" }, + { type: "ref", id: "software/overview" }, + { type: "ref", id: "developers/overview" }, + { type: "ref", id: "developers/maintaining-documentation/overview" }, + { type: "ref", id: "legal/overview" }, ], }, Hardware: { @@ -220,12 +215,12 @@ module.exports = { }, ], "Additional Documentation": [ - {type: "ref", id: "getting-started/overview"}, - {type: "ref", id: "settings/overview"}, - {type: "ref", id: "software/overview"}, - {type: "ref", id: "developers/overview"}, - {type: "ref", id: "developers/maintaining-documentation/overview"}, - {type: "ref", id: "legal/overview"}, + { type: "ref", id: "getting-started/overview" }, + { type: "ref", id: "settings/overview" }, + { type: "ref", id: "software/overview" }, + { type: "ref", id: "developers/overview" }, + { type: "ref", id: "developers/maintaining-documentation/overview" }, + { type: "ref", id: "legal/overview" }, ], }, Contribute: { @@ -244,7 +239,7 @@ module.exports = { "developers/device/mesh-alg", "developers/device/encryption", "developers/device/portnum", - "developers/device/plugin-api", + "developers/device/module-api", "developers/device/http-api", "developers/device/documents", ], @@ -277,11 +272,11 @@ module.exports = { }, ], "Additional Documentation": [ - {type: "ref", id: "getting-started/overview"}, - {type: "ref", id: "settings/overview"}, - {type: "ref", id: "hardware/overview"}, - {type: "ref", id: "software/overview"}, - {type: "ref", id: "legal/overview"}, + { type: "ref", id: "getting-started/overview" }, + { type: "ref", id: "settings/overview" }, + { type: "ref", id: "hardware/overview" }, + { type: "ref", id: "software/overview" }, + { type: "ref", id: "legal/overview" }, ], }, Legal: { @@ -292,11 +287,11 @@ module.exports = { "legal/privacy", ], "Additional Documentation": [ - {type: "ref", id: "getting-started/overview"}, - {type: "ref", id: "settings/overview"}, - {type: "ref", id: "hardware/overview"}, - {type: "ref", id: "software/overview"}, - {type: "ref", id: "developers/overview"}, + { type: "ref", id: "getting-started/overview" }, + { type: "ref", id: "settings/overview" }, + { type: "ref", id: "hardware/overview" }, + { type: "ref", id: "software/overview" }, + { type: "ref", id: "developers/overview" }, ], }, }; diff --git a/src/pages/downloads/index.tsx b/src/pages/downloads/index.tsx index 84c8f4b5..810d7a03 100644 --- a/src/pages/downloads/index.tsx +++ b/src/pages/downloads/index.tsx @@ -7,12 +7,12 @@ import Layout from '@theme/Layout'; import { Release } from '../../utils/github'; import { fetcher } from '../../utils/swr'; +import { DownloadCard } from './_components/DownloadCard'; import { FirmwareCard, PlaceholderFirmwareCard, } from './_components/FirmwareCard'; -import { HeaderText } from './_components/HeaderText' -import { DownloadCard } from './_components/DownloadCard' +import { HeaderText } from './_components/HeaderText'; const Firmware = (): JSX.Element => { const { data, error } = useSWR( @@ -30,10 +30,7 @@ const Firmware = (): JSX.Element => { >
- +
{ buttonText="Download Meshtastic Flasher" url="https://github.com/meshtastic/Meshtastic-gui-installer/releases/latest" notes={[ - "To download using ", pip, " follow ",these instructions,"." + "To download using ", + pip, + " follow ", + + these instructions + , + ".", ]} />
@@ -69,7 +72,17 @@ const Firmware = (): JSX.Element => { client="Android" imgUrl="https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png" url="https://play.google.com/store/apps/details?id=com.geeksville.mesh&referrer=utm_source=downloads-page" - notes={["To sideload, ",download the latest .apk," from Github", ]} + notes={[ + "To sideload, ", + + download the latest .apk + , + " from Github", + ]} /> { )} - Once downloaded, follow the flashing instructions for ESP32 chipsets, NRF52 chipsets, or the GUI instructions for Meshtastic Flasher. + Once downloaded, follow the flashing instructions for{" "} + + ESP32 chipsets + + ,{" "} + + NRF52 chipsets + + , or the{" "} + + GUI instructions for Meshtastic Flasher + + .
- Google Play and the Google Play logo are trademarks of Google LLC. + + Google Play and the Google Play logo are trademarks of Google LLC. +
diff --git a/static/img/plugins/store_and_forward/store_and_forward-overview.png b/static/img/modules/store_and_forward/store_and_forward-overview.png similarity index 100% rename from static/img/plugins/store_and_forward/store_and_forward-overview.png rename to static/img/modules/store_and_forward/store_and_forward-overview.png