Merge branch 'meshtastic-master'

.env.example

@@ -0,0 +1 @@
+API_URL=

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
         with:
           submodules: true
       - name: Generate protobuf docs
-        run: protoc --doc_out="website/docs/developers/protobufs" --doc_opt="./website/protobuf.tmpl,api.md" --proto_path="protobufs" protobufs/*.proto
+        run: protoc --doc_out="docs/developers/protobufs" --doc_opt="./protobuf.tmpl,api.md" --proto_path="protobufs" protobufs/*.proto
       - uses: amondnet/vercel-action@v20
         with:
           vercel-token: ${{ secrets.VERCEL_TOKEN }}
@@ -34,4 +34,3 @@ jobs:
           vercel-org-id: ${{ secrets.ORG_ID}}
           vercel-project-id: ${{ secrets.PROJECT_ID}}
           scope: ${{ secrets.ORG_ID}}
-          working-directory: website

.github/workflows/pr.yml

@@ -13,6 +13,4 @@ jobs:
         with:
           node-version: 16
       - run: yarn install
-        working-directory: website
       - run: yarn run build
-        working-directory: website

.gitignore

@@ -4,3 +4,4 @@ node_modules/
 build
 .vercel
 .DS_Store
+.env

.gitmodules

@@ -1,7 +1,13 @@
-[submodule "website/static/img/meshtastic-design"]
-	path = website/static/img/meshtastic-design
+[submodule "static/img/meshtastic-design"]
+	path = static/img/meshtastic-design
 	url = https://github.com/meshtastic/meshtastic-design/
 [submodule "protobufs"]
 	path = protobufs
 	url = https://github.com/meshtastic/meshtastic-protobufs/
-s
+s
+[submodule "public/design"]
+	path = public/design
+	url = https://github.com/meshtastic/meshtastic-design/
+[submodule "static/design"]
+	path = static/design
+	url = https://github.com/meshtastic/meshtastic-design/

README.md

@@ -39,3 +39,5 @@ The radios automatically create a mesh to forward packets as needed, so everyone
 Meshtastic uses LoRa for the long range communcations and depending on settings used the maximum theoritical group size ranges from 30-200 device nodes. Currently each device can only support a connection from a single user at a time.
 
 Please see our [website](https://meshtastic.org) for more information about Meshtastic.
+
+[![Powered by Vercel](https://raw.githubusercontent.com/abumalick/powered-by-vercel/master/powered-by-vercel.svg)](https://vercel.com?utm_source=meshtastic&utm_campaign=oss)

docs/developers/build.md

@@ -24,4 +24,53 @@ This project uses the simple PlatformIO build system. PlatformIO is an extension
 
 :::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.
-:::
+:::
+
+## 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 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)

docs/developers/overview.md

@@ -0,0 +1,54 @@
+---
+id: overview
+title: Overview
+sidebar_label: Overview
+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 improving 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
+
+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.
+
+## 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 to interact 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.
+
+## 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 cli 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.
+
+## 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.js](https://github.com/meshtastic/meshtastic.js) is a javascript library that provides an interface for Meshtastic devices.
+
+@sachaw has been making tons of progress on the web app and would love help with:
+
+    * Saving of preferences
+    * Better loading state indicators
+    * Chat scroll lock
+    * Various plugin 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.
+
+## Documentation
+This website is in the [Meshtastic](https://github.com/meshtastic/Meshtastic) repository.

docs/software/android/usage.md

@@ -18,6 +18,10 @@ You will need a device with Meshtastic installed to go any further. See the [get
 
 Open the Settings tab (last tab), and it should look similar to the screen below. It shows any Meshtastic devices that are found over Bluetooth.
 
+:::note
+Android requires location permission granted and location must be turned on to find new devices via bluetooth. You can turn it off again afterwards.
+:::
+
 [![Device available to select](/img/android/android-settings-deselected-c.png)](/img/android/android-settings-deselected.png)
 
 1. Select the Device by name, "Meshtastic_c830" in the example below. (You will see any active devices within range, so make sure to get the right one.)
@@ -68,25 +72,33 @@ The app will generate a new QR code on the screen, and this encodes the channel
 
 ### Join a channel
 
-If another user shares a QR code, you should be able to scan it with your camera (phones with Android 9 or later will recognise QR codes).
+If another user shares a QR code, you will be able to scan it with your camera. If the channel is shared as a file or link via the Share button, you can click on the file or link and follow similar steps.
 
-1. You will see a message like Tap here to go to "www.meshtastic.org" in your browser.
-2. Proceed and it will launch the Meshtastic app, and you should see a message like "Do you want to switch to the 'Owl Team' channel?".
-3. Accept this, and the app will change to this new channel. You will lose any current channel setting!
+You should see a message with the option "open with Meshtastic".
+
+[![Open with Meshtastic](/img/android/android-open-with-c.png)](/img/android/android-open-with.png)
+
+<details>
+  <summary>Troubleshooting: Can't "open with Meshtastic".</summary>
+  <div>
+    <div>
+        If you don't see "Meshtastic" as an option to open the file or link with:<br />
+        1. Go to Android Settings > Apps > Default apps > Meshtastic > Opening links<br />
+        2. Make sure you have in "links/web address": www.meshtastic.org<br />
+        3. If you see the option "Open the supported links" make sure it is enabled.<br />
+    </div>
+  </div>
+</details>
+
+Proceed and you should see a message like "Do you want to switch to the 'Owl Team' channel?".
+Accept this, and the app will change to this new channel. You will lose any current channel setting!
 
 [![Accept new channel](/img/android/android-accept-channel-c.png)](/img/android/android-accept-channel.png)
 
-If the channel is shared as a link via a message, or email, you can click on the link and follow similar steps.
-
 :::note
-You must use a link or a QR Code to Join a Channel. Setting the Channel Settings to the same Name and Options will not work as there is also a shared key encoded in the link.
+Setting the same Name and Options will not work as there is also a unique pre-shared key encoded in the channel.
 :::
 
-:::note
-Your app must be connected to an active Meshtastic device for the link or QR Code to work.
-:::
-
-
 You can test changing channels with the QR code shown below.
 
 ![Meshtastic Default Channel](/img/android/default-channel.png)
@@ -95,12 +107,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 (but fast)	 | 21.875 kbps          |
-| Medium range (but fast)	 | 5.469 kbps           |
-| Long range (but slower)	 | 0.275 kbps           |
-| Very long range (but slow) | 0.183 kbps (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
 
@@ -152,7 +166,7 @@ This allows you to change the frequency with which your location is broadcast ac
 
 #### Device sleep period
 
-To use as little power as possible while running on battery, ESP32 based devices go into a sleep mode. Unfortunately, during this sleep mode they turn off their Bluetooth radio. They can be woken early from this sleep by either receiving a message over LoRa (the LoRa receiver never switches off), of by pressing a program button where there is one on the device. This setting allows the length of the sleep mode to be changed from the default of 300 seconds (5 minutes). To keep the bluetooth link alive for eight hours (any usage of the bluetooth protcol from your phone will reset this timer), set this to 28800 seconds.
+By default, ESP32 devices will enter sleep mode after 300 seconds of inactivity to save battery power. Unfortunately, this will also turn off the Bluetooth radio. They can be woken by either receiving a message over LoRa (the LoRa receiver never switches off), or by pressing a program button when there is one on the device. For example, to keep the Bluetooth link awake for eight hours (any usage of the Bluetooth protocol from your phone will reset this timer), set this to 28800 seconds.
 
 ### Debug page
 

docs/software/device/channels.md

@@ -0,0 +1,66 @@
+---
+id: device-channels
+title: Multiple channel support
+sidebar_label: Multiple channels
+---
+
+:::warning
+Multiple channel support is currently an experimental feature that is ONLY supported by the Python CLI. 
+:::
+
+Version 1.2 of the software adds support for multiple (simultaneous) channels.  The idea behind this feature is that a mesh can allow multiple users/groups to be share common mesh infrastructure.  Even including routing messages for others when no one except that subgroup of users has the encryption keys for their private channel.
+
+### What is the Primary channel
+
+The way this works is that each node keeps a list of channels it knows about.  One of those channels (normally the first one) is labelled as the "PRIMARY" channel.  The primary channel is the **only** channel that is used to set radio parameters.  This channel controls things like spread factor, coding rate, bandwidth etc... Indirectly this channel also is used to select the specific frequency that all members of this mesh are talking over.
+
+This channel may or may not have a PSK (encryption).  If you are providing mesh to 'the public' we recommend that you always leave this channel with its default psk.  The default PSK is technically encrypted (and random users sniffing the ether would have to use Meshtastic to decode it), but the key is included in the github source code and you should assume any 'attacker' would have it.  But for a 'public' mesh you want this, because it allows anyone using Meshtastic in your area to send packets through 'your' mesh.
+
+```bash title="Setting default channel"
+$ meshtastic --seturl https://www.meshtastic.org/d/#CgUYAyIBAQ
+Connected to radio
+```
+
+The device will now have its primary channel set to the default:
+
+```bash title="Expected output"
+$ meshtastic --info
+Connected to radio
+...
+Channels:
+  PRIMARY psk=default { "modemConfig": "Bw125Cr48Sf4096", "psk": "AQ==" }
+Primary channel URL: https://www.meshtastic.org/d/#CgUYAyIBAQ
+```
+
+### How to use Secondary channels
+
+Any channel you add after that Primary channel is Secondary.  Secondary channels are used only for encryption and (in the case of some special applications) security.  If you would like to have a private channel over a more public mesh, you probably want to create a secondary channel.  When sharing that URL with your private group you will share the "Complete URL".  The complete URL includes your secondary channel (for encryption) and the primary channel (to provide radio/mesh access).
+
+Secondary channels **must** have a PSK (encryption).
+
+```bash title="Adding a channel called testing"
+$ meshtastic --ch-add testing
+Connected to radio
+Writing modified channels to device
+```
+
+The device will now have a Secondary channel called "testing"
+
+```bash title="Expected output"
+$ meshtastic --info
+Connected to radio
+...
+Channels:
+  PRIMARY psk=default { "modemConfig": "Bw125Cr48Sf4096", "psk": "AQ==" }
+  SECONDARY psk=secret { "psk": "HW7E3nMbiNbvr6MhsDonLCmj7eSAhttzjbIx/r5OQmg=", "name": "testing" }
+Primary channel URL: https://www.meshtastic.org/d/#CgUYAyIBAQ
+Complete URL (includes all channels): https://www.meshtastic.org/d/#CgUYAyIBAQopIiAdbsTecxuI1u-voyGwOicsKaPt5ICG23ONsjH-vk5CaCoFYWRtaW4
+```
+
+Secondary channels can be deleted by specifying their index, otherwise ch-del will attempt to delete channel index 0
+
+```bash title="Deleting a secondary channel"
+$ meshtastic --ch-index 1 --ch-del
+Connected to radio
+Deleting channel 1
+```

docs/software/device/firmware.md

@@ -1,5 +1,5 @@
 ---
-id: device-software
+id: device-firmware
 title: Device firmware
 sidebar_label: Device firmware
 ---

docs/software/overview.md

@@ -0,0 +1,26 @@
+---
+id: overview
+title: Overview
+sidebar_label: Overview
+slug: /software
+---
+
+The following applications are available to support your Meshtastic network:
+
+- The [firmware](/docs/software/device/device-firmware) to run on the devices
+- Connect to the devices with our [Android app](/docs/software/android/android-installation)
+- An [iOS application](/docs/software/ios/ios-development) is in the works
+- [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)
+  - [Serial communication](/docs/software/plugins/serial-plugin)
+  - [Store and forewarding messages](/docs/software/plugins/store-forward-plugin) (in development)
+  - [Environment measurement](/docs/software/plugins/environment-plugin) (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)
+  - [PyGUI](/docs/software/community/community-pygui), a platform agnostic graphical user interface for devices
+
+The devices running Meshtastic have a large number of preferences that can be set, see the [Settings](/docs/settings) pages for more details.

docs/software/python/usage.md

@@ -4,11 +4,30 @@ title: Meshtastic-python usage
 sidebar_label: Python usage
 ---
 
-An example using Python 3 code to send a message to the mesh:
+An example using Python 3 code to send a message to the mesh, get and set a radio configuration preference:
 ```python
 import meshtastic
-interface = meshtastic.SerialInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0
-interface.sendText("hello mesh") # or sendData to send binary data, see documentations for other options.
+import meshtastic.serial_interface
+
+# By default will try to find a meshtastic device,
+# otherwise provide a device path like /dev/ttyUSB0
+interface = meshtastic.serial_interface.SerialInterface()
+# or something like this
+# interface = meshtastic.serial_interface.SerialInterface(devPath='/dev/cu.usbmodem53230050571')
+
+# or sendData to send binary data, see documentations for other options.
+interface.sendText("hello mesh")
+
+ourNode = interface.getNode('^local')
+print(f'Our node preferences:{ourNode.radioConfig.preferences}')
+
+# update a value
+print('Changing a preference...')
+ourNode.radioConfig.preferences.gps_update_interval = 60
+
+print(f'Our node preferences now:{ourNode.radioConfig.preferences}')
+ourNode.writeConfig()
+
 interface.close()
 ```
 
@@ -16,6 +35,7 @@ Another example using Python 3 code to send a message to the mesh when WiFi is e
 ```python
 import time
 import meshtastic
+import meshtastic.tcp_interface
 from pubsub import pub
 
 def onReceive(packet, interface): # called when a packet arrives
@@ -27,7 +47,7 @@ def onConnection(interface, topic=pub.AUTO_TOPIC): # called when we (re)connect
 
 pub.subscribe(onReceive, "meshtastic.receive")
 pub.subscribe(onConnection, "meshtastic.connection.established")
-interface = meshtastic.TCPInterface(hostname='192.168.68.74')
+interface = meshtastic.tcp_interface.TCPInterface(hostname='192.168.68.74')
 while True:
     time.sleep(1000)
 interface.close()
@@ -39,7 +59,8 @@ Note: Be sure to change the ip address in the code above to a valid ip address f
 You can get and update settings like this:
 ```python
 import meshtastic
-interface = meshtastic.SerialInterface()
+import meshtastic.serial_interface
+interface = meshtastic.serial_interface.SerialInterface()
 
 ourNode = interface.getNode('^local')
 print(ourNode.radioConfig.preferences)