Merge branch 'master' of github.com:meshtastic/Meshtastic

.github/workflows/update_protobufs.yml

@@ -22,4 +22,5 @@ jobs:
           git config --global user.name 'github-actions'
           git config --global user.email 'bot@noreply.github.com'
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}
+          git add protobufs
           git commit -m "Update protobuf submodule" && git push || echo "No changes to commit"

protobufs

@@ -1 +1 @@
-Subproject commit 9c32c4baa1f413a3dd8c318e2673dfce1042e1ef
+Subproject commit 6e5ca5b82e22f56d611e695930e326f067fd6a4b

website/docs/hardware/antenna.md

@@ -4,3 +4,114 @@ title: Antennas
 sidebar_label: Antennas
 slug: /hardware/antenna
 ---
+
+## TL; DR
+
+If you have sufficient range with your existing aerial, skip this section.  If you don't, consider either getting more nodes and / or replace the stock aerial with one tuned (to your region transmitter's frequency): 
+
+- A quarter quarter wave _tuned_ stubby aerial (<10cm for fit-in-pocket) should have a real-world range of a couple of km without significant obstacles (buildings / hills). 
+- Aerial criteria: 50 Ohm, SMA male connector, low VSWR (<2) (at tuning frequency - see its datasheet), gain > 0 dbi .
+- Caution, avoid suppliers who:
+  - don't state the aerial's tuned frequency and its specific purpose (LoRa network)
+  - claim huge gain figures on omni-directional aerials
+  - don't provide boringly professional data-sheets. 
+- If you want more range, directionality, specificity read on.
+
+## General guidance
+
+The Meshtastic system is designed to be simple and intuitive to use.  However, its LoRa radios rely on point to point communications, unit to unit, aerial to aerial; quite different to the near ubiquitous radio coverage of today's cellphone & wi-fi connections.
+
+Some understanding of the factors affecting radio communications will help achieve substantially better service, faster transmission, over a greater range with your devices.  Here, we'll attempt to provide a top-level set of guidance for use and aerial selection, how to test the aerials, and a set of resources for further research and plenty of opportunity for going deeper.
+
+The Meshtastic devices (of various flavours) lend themselves to experimentation, not only because you can replace their aerials, but also because of their mesh operation.  All nodes will, without alteration, relay communications from any other members of the mesh around obstacles and over greater distances.  The cost of aerial investment should be weighed against investment in additional low-cost nodes.
+
+:::caution
+Do not switch on your Meshtastic device (or any other transmitter) without an aerial attached - see below.
+:::
+
+The information collected here is by no means definitive, and necessarily abbreviated (it's a huge topic).
+
+## Non aerial factors affecting transmission
+
+Unless you're using your devices in a vacuum with clear line of sight between aerials:
+- Weather (temperature, humidity & air pressure),
+- Transmission power, spreading and other associated channel factors,
+- Number of nodes within reach in the mesh (affects retries consequent duty cycle hit),
+- Absorption by materials (with varying degrees attenuation, by material and depth),
+- Reflection off surfaces (and channeled through material tunnels, including warm / cold air tunnels commonly present in the atmosphere),
+- Diffraction around obstacles (over forests and around corners).
+
+## Aerial selection
+
+The stock aerials provided bundled with the t-Beam and other boards are, in general a 'mixed bag'.  They may not have been selected for your given frequency range, tuned or of a quality design.
+
+Matching an aerial to the frequency of transmission is important, as is choosing an appropriate design.
+
+The aerial's design will affect:
+- proportion of the signal which leaves the aerial (efficiency), 
+- directions in which it's transmitted, and whether it will be affected by horizontal / vertical polarisation,
+- proportion of signal which is reflected back within the device itself.
+
+:::caution
+While the LoRa devices we are using for Meshtastic are relatively low power radios, care should be taken _not_ to operate any radio transmission device without an aerial or with a poorly matched aerial.  Un-transmitted radio signal reflected back to the transmitter can damage the device.
+:::
+
+### Important considerations:
+
+- What transmission frequency are you using? (varies by region)
+  - Devices on another frequency will not be able to interact with yours.
+  - Only specific frequencies are licensed [radio settings](docs/developers/device/radio-settings).
+- How will you be carrying / transporting the radio?
+  - A large directional aerial will transmit over significantly greater distance than an omni-directional aerial.  However, it must be pointed at its target so isn't optimal for mobile use.
+  - A tuned half wave whip aerial may have more omni-directional range than the quarter wave stubby; but it will be conspicuous in your pocket.
+- Do you want transmission in all directions?
+  - While humans (mostly water) don't attenuate signal greatly (at LoRa frequencies), buildings & walls do.  
+  - If your aerial is permanently positioned against a building, signal transmitted towards the wall will be largely lost.
+- Does my Meshtastic device have the right power range, impedance & connector for the aerial?
+  - For the T-Beam devices it should be 50 Ohm impedance, with SMA connector, many will be recommended for LoRa use in their technical details.
+  - By contrast, a close range, contact-less Personal Area Network antenna, or a huge aerial at the end of length of coax designed for a 100W transmitter are not going to be operable.
+- Cost, quality and supply service?
+  - The perfect aerial on paper, sourced from the other side of the world with mixed reviews doesn't compare to a local supplier who has spent time carefully collating all of the aerial data-sheets for comparison _and_ holds stock immediately available - personally I prefer to pay significantly more for a time saving, quality service.
+
+## Terminology / references & further research
+
+You could also do worse than reading the [wikipedia entry for Antenna](https://en.wikipedia.org/wiki/Antenna_(radio)).
+
+Instead of repeat listing the terms, let us recommend this superb [tutorial](https://www.youtube.com/watch?v=J3PBL9oLPX8) by Andreas Speiss (the 'guy with the Swiss accent').
+
+See in the references of the above LoRa world record transmission distance details & instructions on self-build Moxon antennae.
+
+### Environmental
+
+For a bit of light reading on environmental research:
+
+  -  [RF attentuation in vegetation](https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.833-9-201609-I!!PDF-E.pdf) (yes really); if you wander through the woods wondering how your RF is bouncing off leaves dependent on their variety, and wind speed … well you do, now.
+  -  [RF attentuation with various building materials](https://www.ofcom.org.uk/__data/assets/pdf_file/0016/84022/building_materials_and_propagation.pdf).
+  -  This one by ITU again is very detailed in its [analysis of the drivers of attenuation](https://www.itu.int/dms_pubrec/itu-r/rec/p/R-REC-P.2040-1-201507-I!!PDF-E.pdf) (I wasn’t aware that all EMF radiation exhibits reflection / transmission characteristics akin to light hitting a material boundary. So, depending on the angle of incidence, material and the EMF wavelength, it will be reflected and / or transmitted through).
+  - These RF bands are also made more [noisy by adjacent LTE](https://www.ofcom.org.uk/__data/assets/pdf_file/0023/55922/lte-coexistence.pdf)
+
+In summary - our wavelengths in Europe fair well in plain sight, curve over not-so-tall obstacles (including trees), reflect of surfaces at low angles of incidence. They go through humans without much attenuation; but not brick or stone or anything much above glass / kevlar. Oh, and don’t sit under an LTE tower and expect it to be plain sailing.
+
+### Testing
+
+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 comparison & testing videos.  Their utility goes beyond the specific aerials tested:
+- Insight into aerial types & their characteristics,
+- Testing approaches.
+
+On the topic of testing - performing your own testing and providing feedback is the lifeblood of Meshtastic and OpenSource projects.  
+
+Stating the obvious: 
+- 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 & contrast.
+
+:::note
+This can be done by utilising the [range test plugin](/docs/software/plugins/range-test-plugin)
+:::
+
+## Discussion
+
+To comment on / join in antenna range [Meshtastic discourse](https://meshtastic.discourse.group/t/antenna-improved-range/227/35?u=sens8tion)
+
+There, you will also find reference to Meshtastic range achievements, aerial recommendations (note we've stopped short of making specific supplier aerial recommendations in this wiki).

website/docs/software/android/installation.md

@@ -0,0 +1,22 @@
+---
+id: android-installation
+title: Android application installation
+sidebar_label: Installation
+---
+Our Android application is available to download on Google Play.
+
+<p align="center"><a href="https://play.google.com/store/apps/details?id=com.geeksville.mesh&referrer=utm_source%3Dgithub-homepage"><img alt="Download at https://play.google.com/store/apps/details?id=com.geeksville.mesh" src="https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png" style={{zoom:'35%'}} /></a></p>
+
+The application may not be found if your phone/Android version are too old. The minimum Android version is 5.0 (Lollipop 2014, first BLE support). However Android 6, Marshmallow 2015, is recommended as the Bluetooth is more stable.
+
+On installing the Meshtastic app, load it and navigate to the settings page. The app will ask you to give it permissions to access your location. This is needed for any app to use bluetooth, as the app is then able to scan the local area for bluetooth devices and, in theory, could triangulate your location based the devices it sees. If you give location permissions "only while using the app", the app will only be able to use bluetooth while it is open and visible to the user. This means if the screen is locked, or you are using another app, Meshtastic will not be able to use bluetooth, and will not be able to receive any messages from the node.
+
+[![Messages page](/img/android/android-messages-sm.png)](/img/android/android-messages-sm.png) [![Nodes page](/img/android/android-nodes-sm.png)](/img/android/android-nodes.png) [![Channel page](/img/android/android-channel-sm.png)](/img/android/android-channel.png) [![Settings page](/img/android/android-settings-sm.png)](/img/android/android-settings.png) [![Debug page](/img/android/android-debug-sm.png)](/img/android/android-debug.png)
+
+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.
+
+[![Settings page with statistics consent box highlighted](/img/android/android-stats-consent-sm.png)](/img/android/android-stats-consent.png)
+
+Google Play and the Google Play logo are trademarks of Google LLC.

website/docs/software/android/usage.md

@@ -0,0 +1,172 @@
+---
+id: android-usage
+title: Android application usage
+sidebar_label: Usage
+---
+
+## Introduction
+
+The Meshtastic Android app handles the communication and shows the location of everyone in your private group. Each member of your private mesh can always see the location and distance of all other members and any text messages sent to your group chat.
+
+Open the App and you should see a screen like this. You can move through the tabs but nothing much will be visible until you connect to a radio device.
+
+[![No device connected](/img/android/android-settings-none-sm.png)](/img/android/android-settings-none.png)
+
+## Connecting
+
+You will need a device with Meshtastic installed to go any further. See the [flashing firmware](/docs/getting-started/flashing-firmware/overview) section for information on how to do this.
+
+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.
+
+[![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.)
+2. You will need to "pair" the device by entering a PIN shown on the device screen. This can alternatively be done in the phone Bluetooth settings. If the Device has no screen, but it's connected via USB, it may be displayed on a serial terminal (921600 Baud). For a development device, the PlatformIO terminal would come in handy. Some nodes have buttons allowing you to change the page displayed on the nodes screen. If you double click this button, it will set the pairing code to `123456`.
+3. Edit the "Your name", e.g. to be "Mike Bird". This is the name that other people will see, so make it unique within your group.
+4. The initials e.g. "MB" should also be unique and will be used to identify you in the message history and on the device screens.
+
+[![Changing device name](/img/android/android-settings-mike-sm.png)](/img/android/android-settings-mike.png)
+
+5. This should start the communication with the Device. The cloud icon, on the status bar, will have a tick.
+
+![Connected](/img/android/android-cloud-tick.png)
+
+If there is no Device shown, just the `None (disable)` as below, then the device may be off, or in a sleep mode. Try to reset, or press a button to wake it.
+
+[![No devices available](/img/android/android-settings-none-c.png)](/img/android/android-settings-none-c.png)
+
+The cloud icon at the top right corner indicates if you are connected to a device. This currently has three states:
+
+![Not connected](/img/android/android-cloud-cross.png) Cloud with a slash through it: No device connected to the application.
+
+![Connected](/img/android/android-cloud-tick.png) Cloud with a tick in it: Device connected to the application.
+
+![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, otherwise you will need to Setup a Channel.
+
+### Setup a channel
+
+To use Meshtastic you need to setup a Channel, and share the details with your group. The group is private and only those who have the details can join the group and see the messages. You will need to do this once initially, and then only when you want to change or make a new mesh network group. For a new device you will see there is a default setting, shown as `#LongSlow-1, Very long range (but slow)`. It is OK to use this initially.
+
+The Channel tab allows you to do this. This screen is initially locked, so that you don't change it accidentally. Press the lock symbol, and you will be able to edit. First, select the Channel options, as shown here, and chose the most appropriate option:
+
+[![Changing channel settings](/img/android/android-change-channel-sm.png)](/img/android/android-change-channel.png)
+
+Here we selected `Very long range (but slow)`, and then made a Channel Name using the keyboard. This identifies your group, here "Owl Team".
+
+[![Changing channel name](/img/android/android-channel-owl-sm.png)](/img/android/android-channel-owl.png)
+
+You will see a warning because changing the Channel will break communications with your group, i.e. if you change your settings without sharing the new details with the group.
+
+[![Do you want to change the channel?](/img/android/android-new-channel-sm.png)](/img/android/android-new-channel.png)
+
+The app will generate a new QR code on the screen, and this encodes the channel details and a random 256-bit key for sharing with the new group. You can share the QR code with other Meshtastic users, or use the Share button and share the link via chat message, SMS, email (the link is a very long code, for example: https://www.meshtastic.org/d/#CgUYAyIBAQ
+
+### 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).
+
+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!
+
+[![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.
+:::
+
+:::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)
+
+### Configure a channel
+
+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) |
+
+### Send a message
+
+The message window operates like any chat applications. Note that any messages sent go to the whole group, and there is no one-to-one message feature.
+
+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. If at least one node sent a confirmation back the initial sender did not receive the 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.
+
+There is no long-term store-and-forward of messages, so messages not received within a time-out (duration?) are lost.
+
+[![Messages](/img/android/android-messages-sm.png)](/img/android/android-messages.png)
+
+### View your network
+
+The network list shows all the users (devices) that have connected to the same Channel. For each entry, it shows the last time they were active, their distance, and their last known power status (battery & percentage, or external power). In the example below, Eddie is the local user, Mike is active and 29m away, and a third node has been inactive since 9:02pm.
+
+This is a list of network nodes, rather than users, so where there is a named user connected to the device, you will see the user name, otherwise the node is shown as `Unknown a3c9` (where `a3c9` is the last 4 hex digits from the MAC address.)
+
+[![Local Meshtastic network](/img/android/android-nodes-sm.png)](/img/android/android-nodes.png)
+
+### View the map
+
+The Map tab will show a local map with an icon for each active mesh node that has a known position. The users names are shown against the icon.
+
+[![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 maps 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), 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
+
+[![Meshtastic configuration options](/img/android/android-settings-options-c.png)](/img/android/android-settings-options.png)
+
+### Advanced settings
+
+[![Advanced settings](/img/android/android-advanced-settings-c.png)](/img/android/android-advanced-settings.png)
+
+#### Broadcast position period
+
+This allows you to change the frequency with which your location is broadcast across the mesh. By default this is set to 900 seconds (15 minutes). The minimum time this can be set to is 375 seconds, the reasons for which have been [discussed on the forum](https://meshtastic.discourse.group/t/lost-messages-while-testing/2455/19).
+
+#### 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). Setting the period to 0 seconds disables the sleep function on the device.
+
+### Debug page
+
+[![Debug page](/img/android/android-debug-sm.png)](/img/android/android-debug.png)
+
+The debug page allows you to see all packets sent between the application and the device. This can then be used for debugging purposes.
+
+### Save messages as csv
+
+This allows you to save your messages to a .csv (comma sparated value) file on your phone.
+
+### Theme
+
+This allows you to change between light and dark themes, or to select the system default.
+
+[![Meshtastic theme](/img/android/android-settings-theme-c.png)](/img/android/android-settings-theme.png)
+
+
+

website/docs/software/ios/development.md

@@ -0,0 +1,12 @@
+---
+id: ios-development
+title: iOS application development
+sidebar_label: App development
+---
+
+The Meshtastic iOS app is currently in early development, with two community projects to get this working.
+
+* https://github.com/jeksys/Meshtastic-iOS
+* https://github.com/thepoweroftwo/meshtastic-ios
+
+There is a [github discussion](https://github.com/meshtastic/Meshtastic/discussions/2) and [discourse discussion](https://meshtastic.discourse.group/t/meshtastic-ios-app-first-alpha-release/2733) ongoing if you wish to contribute to this.

website/docs/software/python/cli.md

@@ -0,0 +1,111 @@
+---
+id: python-cli
+title: Command line interface
+sidebar_label: CLI usage
+---
+
+This pip package will also install a "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the meshtastic devices. The source code for this tool is also a good [example](https://github.com/meshtastic/Meshtastic-python/blob/master/meshtastic/__main__.py) of a 'complete' application that uses the meshtastic python API.
+
+:::note
+This command is not run inside of python, you run it from your operating system shell prompt directly.  If when you type "meshtastic" it doesn't find the command and you are using Windows: Check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path/).
+:::
+
+To display a (partial) list of the available commands:
+```bash
+meshtastic -h
+```
+
+## Changing device settings
+
+You can also use this tool to set any of the device parameters which are stored in persistent storage. For instance, here's how to set the device
+to keep the bluetooth link alive for eight hours (any usage of the bluetooth protcol from your phone will reset this timer)
+
+```bash title="Expected Output"
+# You should see a result similar to this:
+mydir$ meshtastic --set wait_bluetooth_secs 28800
+Connected to radio...
+Setting preference wait_bluetooth_secs to 28800
+Writing modified preferences to device...
+```
+
+Or to set a node at a fixed position and never power up the GPS.
+
+```bash
+meshtastic --setlat 25.2 --setlon -16.8 --setalt 120
+```
+
+Or to configure an ESP32 based board to join a wifi network as a station:
+
+```bash
+meshtastic --set wifi_ap_mode false --set wifi_ssid mywifissid --set wifi_password mywifipsw
+```
+
+Or to configure an ESP32 to run as a Wifi access point:
+
+```bash
+meshtastic --set wifi_ap_mode true --set wifi_ssid mywifissid --set wifi_password mywifipsw
+```
+
+:::note
+For a full list of preferences which can be set (and their documentation) can be found in the [protobufs](/docs/developers/protobufs/api#radioconfiguserpreferences)
+:::
+
+### Changing channel settings
+
+The channel settings can be changed similiarly.  Either by using a standard (sharable) meshtastic URL or you can set partiular channel parameters (for advanced users).
+
+The URL is constructed automatically based off of the current channel settings. So if you want to customize a channel you could do something like:
+
+```bash
+meshtastic --setchan name mychan --setchan channel_num 4 --info
+```
+
+This will change some channel params and then show device info (which will include the current channel URL)
+
+You can even set the channel preshared key to a particular AES128 or AES256 sequence.
+
+```bash
+meshtastic --setchan psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
+```
+
+Use `--setchan psk none` to turn off encryption.  
+
+Use `--setchan psk random` will assign a new (high quality) random AES256 key to the primary channel (similar to what the Android app does when making new channels).
+
+Use `--setchan psk default` to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.
+
+### Ham radio support
+
+Meshtastic is designed to be used without a radio operator license.  If you do have a license you can set your operator ID and turn off encryption with:
+
+```bash title="Expected Output"
+# You should see a result similar to this:
+mydir$ meshtastic --port /dev/ttyUSB1 --set-ham KI1345
+Connected to radio
+Setting HAM ID to KI1345 and turning off encryption
+Writing modified channels to device
+```
+
+## FAQ/common problems
+
+This is a collection of common questions and answers from our friendly forum.
+
+### Permission denied: ‘/dev/ttyUSB0’
+
+As previously discussed on the [forum](https://meshtastic.discourse.group/t/question-on-permission-denied-dev-ttyusb0/590/3?u=geeksville)
+
+This indicates an OS permission problem for access by your user to the USB serial port.  Typically this is fixed by the following.
+
+```bash
+sudo usermod -a -G dialout <username>
+```
+
+### Mac OS Big Sur
+
+There is a problem with Big Sur and pyserial. The workaround is to install a newer version of pyserial:
+
+```bash
+pip3 install -U --pre pyserial
+```
+
+Afterwards you can use the meshatstic python client again on MacOS.

website/docs/software/python/installation.md

@@ -0,0 +1,69 @@
+---
+id: python-installation
+title: Meshtastic-python installation
+sidebar_label: Installation
+---
+
+This is a python library for using Meshtastic devices. This small library (and example application) provides an easy API for sending and receiving messages over mesh radios. It also provides access to any of the operations/data available in the device user interface or the Android application. Events are delivered using a publish-subscribe model, and you can subscribe to only the message types you are interested in.
+
+[Full documentation](https://meshtastic.github.io/Meshtastic-python) for the library, including examples, is available.
+
+Installation is easily done through the Python package installer pip (note, you must use pip version 20 or later):
+
+## Linux
+
+- 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 `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)
+- 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/)
+- Install pytap2
+    ```bash
+    sudo pip3 install --upgrade pytap2
+    ```
+- Install meshtastic:
+    ```bash
+    sudo pip3 install --upgrade meshtastic
+    ```
+## Windows
+
+- 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).
+- 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
+    ```powershell
+    pip3 install --upgrade pytap2
+    ```
+- Install meshtastic:
+    ```powershell
+    pip3 install --upgrade meshtastic
+    ```

website/docs/software/python/usage.md

@@ -0,0 +1,25 @@
+---
+id: python-usage
+title: Meshtastic-python usage
+sidebar_label: Python usage
+---
+
+An example using Python 3 code to send a message to the mesh:
+```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.
+interface.close()
+```
+
+For the rough notes/implementation plan see [TODO](https://github.com/meshtastic/Meshtastic-python/blob/master/TODO.md). See the API for full details of how to use the library.
+
+## A note to developers of this lib
+
+We use the visual-studio-code default python formatting conventions (autopep8).  So if you use that IDE you should be able to use "Format Document" and not generate unrelated diffs.  If you use some other editor, please don't change formatting on lines you haven't changed.
+
+If you need to build a new release you'll need:
+```bash title="Command"
+apt install pandoc
+sudo pip3 install markdown pandoc webencodings pyparsing twine autopep8
+```

website/docs/software/web/partitions.md

@@ -8,7 +8,7 @@ sidebar_label: ESP32 partitions
 
 This problem seems to occur when your board has the partitioning structure set incorrectly. This typically occurs when the board has had a firmware other than Meshtastic on it previously. In this situation, the file upload page on the device typically shows a free space of around 48,000 bytes, rather than the ~300,000 bytes that it should have free.
 
-![Meshtastic.local's upload page showing insufficient storage space](https://raw.githubusercontent.com/meshtastic/Meshtastic-device/master/images/Insufficient%20space.png)
+![Meshtastic.local's upload page showing insufficient storage space](/img/insufficient-space.png)
 
 There are a number of methods that essentially involve erasing the flash and then re-uploading the Meshtastic firmware.
 
@@ -44,7 +44,7 @@ Requires: [Python](https://www.python.org/) and [esptool.py](https://github.com/
 #### 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](https://github.com/meshtastic/Meshtastic-device/blob/master/docs/software/build-instructions.md)<!-- link to be changed once build page is completed -->. 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](https://raw.githubusercontent.com/meshtastic/Meshtastic-device/master/images/platformio-erase.png)
+![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
 

website/sidebars.js

@@ -18,7 +18,15 @@ module.exports = {
     Software: [
       "software/overview",
       {
-        "Meshtastic Android": [],
+        "Meshtastic Android": [
+          "software/android/android-installation",
+          "software/android/android-usage",
+        ],
+      },
+      {
+        "Meshtastic iOS": [
+          "software/ios/ios-development",
+        ],
       },
       {
         "Meshtastic.js": [
@@ -35,6 +43,9 @@ module.exports = {
       },
       {
         "Meshtastic-python": [
+          "software/python/python-installation",
+          "software/python/python-cli",
+          "software/python/python-usage",
           {
             type: "link",
             label: "API Docs",