updates to getting-started for flow

This commit is contained in:
rcarteraz 2023-01-21 10:32:24 -07:00
parent 6604508395
commit bfac706d52
16 changed files with 317 additions and 169 deletions

View file

@ -1,12 +1,13 @@
---
id: cli-script
title: Flashing with the CLI
sidebar_label: CLI Script
sidebar_label: CLI Script (Advanced Users)
sidebar_position: 3
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Link from "@docusaurus/Link";
:::caution
Make sure not to power the radio on without first attaching the antenna! You could damage the radio chip!
@ -269,8 +270,15 @@ Be very careful to install the correct load for your board. In particular the po
Select `Flash ESP`. It may take a minute or two. Once complete, "Done! Flashing is complete!" will be shown.
## Over the Air Update Instructions
## Connect and Configure Device
OTA updates are only currently available on Android.
After flashing the Meshtastic firmware to the device, you can proceed with the initial configuration.
<!--- TODO --->
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/initial-config"}
>
Connect and Configure Device
</Link>
</div>

View file

@ -1,12 +1,13 @@
---
id: external-serial-adapter
title: Flashing with an External Serial Adapter
sidebar_label: External Serial Adapter
sidebar_label: External Serial Adapter (Advanced Users)
sidebar_position: 4
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Link from "@docusaurus/Link";
:::info
This information will likely only be helpful if you've already attempted to go through the prerequisites and processes outlined in [meshtastic flasher](/docs/software/python/flasher) or [manually flashing](/docs/getting-started/flashing-firmware/esp32/cli-script)
@ -73,3 +74,16 @@ Sometimes you might receive an error for COM port permission in the Meshtastic F
You might need to run the process as an administrator, check to ensure software like Cura isn't monopolizing COM ports, or reboot.
![image](https://user-images.githubusercontent.com/9000580/168447232-1a3af39b-e3cc-44b9-bc3a-32843a9e6f1f.png)
## Connect and Configure Device
After flashing the Meshtastic firmware to the device, you can proceed with the initial configuration.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/initial-config"}
>
Connect and Configure Device
</Link>
</div>

View file

@ -11,7 +11,7 @@ The recommended method for firmware flashing is the [Web-Based Installer.](https
## Flashing Method for ESP32 Devices
1. The [Web-Based Installer](https://flasher.meshtastic.org) requires either Chrome or Edge browsers but is an excellent choice for quickly flashing devices. **This is the recommended method for firmware flashing, especially for those new to the project, due to its ease of use.**
1. The [Web-Based Installer](/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx) requires either Chrome or Edge browsers but is an excellent choice for quickly flashing devices. **This method is highly recommended for firmware flashing, especially for new users of the project, as it is easy to use.**
2. The [Python Flasher](/docs/software/python/flasher) does a lot under the hood to prevent you from needing to use the terminal.
3. The [CLI Script](/docs/getting-started/flashing-firmware/esp32/cli-script) is considered the "manual process" for flashing firmware.
4. Flashing your device using an [external serial adapter](/docs/getting-started/flashing-firmware/esp32/external-serial-adapter) should only be attempted as a last resort if no other method has been successful.

View file

@ -6,5 +6,6 @@ sidebar_position: 2
---
import MFlasher from "../../../software/python-flasher.mdx";
import Link from "@docusaurus/Link";
<MFlasher components={props.components} />

View file

@ -5,8 +5,23 @@ sidebar_label: Web Flasher (recommended)
sidebar_position: 1
---
import Link from "@docusaurus/Link";
## Web Flasher
1. Plug in your device
2. Visit [flasher.meshtastic.org](https://flasher.meshtastic.org) _\*requires Chrome or Edge browser_
3. Follow the instructions
## Connect and Configure Device
After flashing the Meshtastic firmware to the device, you can proceed with the initial configuration.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/initial-config"}
>
Connect and Configure Device
</Link>
</div>

View file

@ -1,12 +1,13 @@
---
id: drag-n-drop
title: Drag & Drop NRF52 Firmware Updates
title: Drag & Drop nRF52 Firmware Updates
sidebar_label: Drag & Drop (recommended)
sidebar_position: 1
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Link from "@docusaurus/Link";
:::info
@ -35,3 +36,16 @@ Previous versions of the Meshtastic firmware may save stale data, causing device
Follow the guide to [factory erase your nRF52](/docs/getting-started/flashing-firmware/nrf52/nrf52-erase) device before continuing to [flash firmware](#flash-firmware).
:::
## Connect and Configure Device
After flashing the Meshtastic firmware to the device, you can proceed with the initial configuration.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/initial-config"}
>
Connect and Configure Device
</Link>
</div>

View file

@ -9,5 +9,5 @@ sidebar_position: 2
The nRF52 based devices have the easiest firmware upgrade process. No driver or software install is required on any platform.
1. The [drag and drop](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop) firmware installation is considered the "manual process" and recommended as the easiest solution.
2. The [Python Flasher](/docs/software/python/flasher) application does a lot under the hood to prevent you from needing to use the terminal. It also allows you to configure your device.
1. The [Drag & Drop](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop) firmware installation method is considered the "manual process" and recommended as the easiest solution.
2. The [Python Flasher](/docs/software/python/flasher) application does a lot under the hood to prevent you from needing to use the terminal.

View file

@ -5,6 +5,8 @@ sidebar_label: Factory Erase nRF52
sidebar_position: 3
---
import Link from "@docusaurus/Link";
Meshtastic uses the [littlefs](https://github.com/littlefs-project/littlefs) library to store configuration, logs, and other data in the internal flash of nRF52 devices. Updating the firmware does _not_ erase this additional data, which can cause issues when the format and location of data changes between releases.
To reset the flash storage on your nRF52 board:
@ -19,4 +21,13 @@ Download and unzip the latest firmware from [Meshtastic Downloads](https://mesht
6. Connect to the device via serial console using the [Meshtastic CLI `--noproto`](/docs/software/python/cli/#--noproto) mode or a standalone serial client like `minicom`.
7. Press any key, you should see the message: `Formatting... Done`.
Once the device has been erased, you can proceed to install the latest Meshtastic firmware on a clean storage filesystem by following the [flash firmware](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop#flash-firmware) steps.
Once the device has been erased, you can proceed to install the latest Meshtastic firmware on a clean storage filesystem by clicking the link below.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/flashing-firmware/nrf52/"}
>
Flash nRF52 Firmware
</Link>
</div>

View file

@ -5,6 +5,7 @@ sidebar_label: Python Flasher
sidebar_position: 2
---
import Link from "@docusaurus/Link";
import MFlasher from "../../../software/python-flasher.mdx";
<MFlasher components={props.components} />

View file

@ -12,193 +12,112 @@ import TabItem from "@theme/TabItem";
## Identify Hardware
The first order of business in getting started is determining what type of hardware you will be working with. Meshtastic currently supports devices with either of the two Micro-Controller Units (MCU):
:::note
This guide assumes that you have already purchased the devices you will be using with Meshtastic. If you haven't, you can check out our list of [supported hardware](/docs/supported-hardware/)
to see your options.
:::
Before you begin, it's important to determine which kind of hardware you're using. Meshtastic works with devices that have either of these two types of Micro-Controller Units (MCU):
### ESP32
The ESP32 is older and consumes more power than the nrf52, but is equipped with both WiFi and Bluetooth. Supported ESP32 devices:
The ESP32 chip is older and consumes more power than the nRF52 chip, but is equipped with both WiFi and Bluetooth. Supported ESP32 devices:
- LILYGO® TTGO T-Beam
- LILYGO® TTGO Lora
- Nano G1
- Station G1
- Heltec V3 and Wireless Stick Lite V3
### NRF52
### nRF52
The NRF52 is much more power efficient than the esp32 and easier to update, but is only equipped with Bluetooth. Supported NRF52 devices:
The nRF52 chip is much more power efficient than the ESP32 chip and easier to update, but is only equipped with Bluetooth. Supported nRF52 devices:
- RAK WisBlock
- LILYGO® TTGO T-Echo
:::info
If your device is not listed above, please review our [supported devices](/docs/supported-hardware) to determine which MCU your device has or contact us in [Discord](https://discord.gg/ktMAKGBnBs) with any questions.
:::
## Setup Working Environment
:::danger STOP! Put the power cable down!
Never power on the radio without attaching an antenna! _it could damage the radio chip._
:::danger STOP! Put The Power Cable Down!
Never power on the radio without attaching an antenna! _It_ could damage the radio chip.
:::
Prior to connecting your Meshtastic device to the computer, you should perform the following basic checks.
### Verify data cable
### Verify Data Cable
Some cables only provide _charging_, verify that your cable is also capable of _transferring data_ before proceeding.
Some cables only provide _charging_, verify that your cable is also capable of _transferring data_ before proceeding. To check if your cable can also transfer data, try connecting it to another device (like a phone) and see if you can copy a file to or from it. If the file transfer works, then your cable is also able to transfer data and you can continue.
There is no definitive way to determine the difference in cables if you aren't willing to pull it apart. Trying out a few cables will be the best way to verify.
### Install Serial Drivers
Once you've located a working data cable, [install the correct serial driver](#install-serial-drivers) and [test for driver installation](#test-driver-installation).
### Install serial drivers
If you don't have serial drivers installed on your computer, please choose one of the options below and install it before continuing.
<div className="indexCtasBody">
<div class="split left">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/serial-drivers/esp32'}
>
Install ESP32 Drivers
</Link>
<div className="split-container">
<div className="split-item">
<Link
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/serial-drivers/esp32'}
>
Install ESP32 Drivers
</Link>
</div>
<div className="split-item">
<Link
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/serial-drivers/nrf52'}
>
Install NRF52 Drivers
</Link>
</div>
</div>
</div>
<div class="split right">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/serial-drivers/nrf52'}
>
Install NRF52 Drivers
</Link>
</div>
</div>
</div>
### Flash Firmware
### Test driver installation
You can verify that you have a proper data cable (rather than a charge-only type cable) and that the appropriate drivers for your system are installed by performing the following test:
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
1. Connect your Meshtastic device to your USB port
2. Open a **Terminal** and enter the following command:
```shell
lsusb
```
3. You should see something like:
```shell
ID xxxx:xxxx Silicon Labs CP210x UART Bridge
# or
ID xxxx:xxxx QinHeng Electronics USB Single Serial
# or
FIXME (WISBLOCK OUTPUT)
```
</TabItem>
<TabItem value="macos">
1. Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`.
2. You should see similar to one of the following entries:
- `CP210X USB to UART Bridge Controller`
- `CH9102 USB to UART Bridge Controller`
- `WisCore RAK4631 Board`
</TabItem>
<TabItem value="windows">
1. Navigate to `Device Manager > Ports (COM & LPT)`
2. You should see similar to one of the following entries:
- `Silicon Labs CP210X USB to UART Bridge (COM5)`
- `Silicon Labs CH9102 USB to UART Bridge (COM5)`
- `FIXME (WISBLOCK OUTPUT)`
</TabItem>
</Tabs>
:::info
If you do not see your device:
1. You may be using a charging-only cable, [verify your cable](#verify-data-cable).
2. You may need to [install the USB serial driver](/docs/getting-started/serial-drivers)).
:::
## Flash Firmware
:::info
If you have a RAK4631-R (the RUI3 bootloader version of the RAK4631), you must [convert the bootloader](/docs/getting-started/flashing-firmware/nrf52/convert-rak4631r) for use with the Arduino before flashing Meshtastic firmware.
:::
After completing the previous steps, you can now flash the Meshtastic firmware onto your device. To proceed, select the appropriate device type for your device.
<div className="indexCtasBody">
<div class="split left">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/flashing-firmware/esp32/'}
>
Flash ESP32 Firmware
</Link>
</div>
</div>
<div className="split-container">
<div className="split-item">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/flashing-firmware/esp32/"}
>
Flash ESP32 Firmware
</Link>
</div>
<div class="split right">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/flashing-firmware/nrf52/'}
>
Flash NRF52 Firmware
</Link>
<div className="split-item">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/flashing-firmware/nrf52/"}
>
Flash nRF52 Firmware
</Link>
</div>
</div>
</div>
</div>
## Connect and Configure Device
After connecting to the device for the first time, you should set the regional settings for the radio as well as other optional settings such as the name of the device.
After flashing the Meshtastic firmware onto your device, you can now move on to initial configuration.
<div className="indexCtasBody">
<Link
target="_blank"
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/initial-config"}
>
Connect and Configure Device
</Link>
</div>
## Use Meshtastic
### with Command Line Tools
- [Python CLI](/docs/software/python/cli)
### with mobile apps
- [Android](/docs/category/android-app)
- [Apple](/docs/category/apple-apps)
### with a browser
- https://client.meshtastic.org
- [Meshtastic Web](/docs/software/web-client)
### over the internet with MQTT
- [MQTT](/docs/software/mqtt/)
There are many ways to interact with and use Meshtastic, please visit the [Software](/docs/software) page for more information.

View file

@ -9,6 +9,7 @@ sidebar_position: 4
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import LoRaRegions from "../blocks/_lora-regions.mdx";
import Link from "@docusaurus/Link";
## Supported Clients per Connection Type
@ -16,7 +17,7 @@ Depending on your connection, some configuration options are not fully supported
<Tabs
groupId="settings"
defaultValue="serial"
defaultValue="ble"
values={[
{label: 'Serial', value: 'serial'},
{label: 'Bluetooth', value: 'ble'},
@ -104,3 +105,16 @@ Configuration of Region, Modem Preset and Hop Limit is available on iOS, iPadOS
### Region Codes
<LoRaRegions />
## Continue Configuration
Now that you have set the LoRa region on your device, you can continue with configuring any additional configs to suit your needs.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/settings/"}
>
Device Configuration
</Link>
</div>

View file

@ -7,6 +7,7 @@ sidebar_position: 1
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Link from "@docusaurus/Link";
## Install ESP32 USB to Serial Drivers
@ -16,7 +17,7 @@ Some newer boards may require the CH9102 (CH340/CH341) Driver.
<Tabs
groupId="operating-system"
defaultValue="linux"
defaultValue="windows"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
@ -48,5 +49,22 @@ values={[
</Tabs>
:::important
Reboot your computer after you have installed the driver to complete the installation.
After installing the driver, make sure to reboot your computer to finish the installation process.
You can also [test your serial driver installation](/docs/getting-started/serial-drivers/test-serial-driver-installation) at this step if required.
:::
### Flash Firmware
After installing the serial drivers, you can now flash the Meshtastic firmware onto your device. To proceed, select the appropriate device type for your device.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/flashing-firmware/esp32/"}
>
Flash ESP32 Firmware
</Link>
</div>

View file

@ -1,18 +1,19 @@
---
id: nrf52
title: NRF52 Serial Drivers
sidebar_label: NRF52 Drivers
title: nRF52 Serial Drivers
sidebar_label: nRF52 Drivers
sidebar_position: 2
---
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import Link from "@docusaurus/Link";
## Install NRF52 USB to Serial Drivers
## Install nRF52 USB to Serial Drivers
<Tabs
groupId="operating-system"
defaultValue="linux"
defaultValue="windows"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
@ -23,22 +24,16 @@ values={[
- [CH9102 Driver - Linux Download](http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html)
:::important
Reboot your computer after you have installed the driver to complete the installation.
:::
</TabItem>
<TabItem value="macos">
- [CH9102 Driver - macOS Download](https://github.com/WCHSoftGroup/ch34xser_macos)
:::important
Reboot your computer after you have installed the driver to complete the installation.
:::
:::caution
With the latest versions of MacOS, the USB Serial driver is built-in. Do _NOT_ download the USB device drivers unless required. If you downloaded/installed any already, please remove them.
:::
### Remove the CH34x USB Driver (macOS)
@ -58,10 +53,27 @@ Uninstall the kernel extension:
- [CH9102 Driver - Windows Download](http://www.wch-ic.com/downloads/CH341SER_EXE.html)
:::important
Reboot your computer after you have installed the driver to complete the installation.
:::
</TabItem>
</Tabs>
:::important
After installing the driver, make sure to reboot your computer to finish the installation process.
You can also [test your serial driver installation](/docs/getting-started/serial-drivers/test-serial-driver-installation) at this step if required.
:::
### Flash Firmware
After installing the serial drivers, you can now flash the Meshtastic firmware onto your device. To proceed, select the appropriate device type for your device.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/flashing-firmware/nrf52/"}
>
Flash nRF52 Firmware
</Link>
</div>

View file

@ -0,0 +1,101 @@
---
id: test-serial-driver-installation
title: Test Serial Driver Installation
sidebar_label: Test Serial Driver Installation
sidebar_position: 3
---
import Link from "@docusaurus/Link";
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
### Test Serial Driver Installation
You can verify that you have a proper data cable (rather than a charge-only type cable) and that the appropriate drivers for your system are installed by performing the following test:
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
1. Connect your Meshtastic device to your USB port
2. Open a **Terminal** and enter the following command:
```shell
lsusb
```
<!-- trunk-ignore(markdownlint/MD029) -->
3. You should see something like:
```shell
ID xxxx:xxxx Silicon Labs CP210x UART Bridge
# or
ID xxxx:xxxx QinHeng Electronics USB Single Serial
# or
FIXME (WISBLOCK OUTPUT)
```
</TabItem>
<TabItem value="macos">
1. Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`.
2. You should see similar to one of the following entries:
- `CP210X USB to UART Bridge Controller`
- `CH9102 USB to UART Bridge Controller`
- `WisCore RAK4631 Board`
</TabItem>
<TabItem value="windows">
1. Navigate to `Device Manager > Ports (COM & LPT)`
2. You should see similar to one of the following entries:
- `Silicon Labs CP210X USB to UART Bridge (COM5)`
- `Silicon Labs CH9102 USB to UART Bridge (COM5)`
- `FIXME (WISBLOCK OUTPUT)`
</TabItem>
</Tabs>
:::info
If you are unable to see your device:
- Make sure that your cable is not only for charging but also for [data transfer](/docs/getting-started/#verify-data-cable).
- It's possible that you need to [reinstall the USB serial driver](/docs/getting-started/serial-drivers).
:::
## Flash Firmware
After completing the previous steps, you can now flash the Meshtastic firmware onto your device. To proceed, select the appropriate device type for your device.
<div className="indexCtasBody">
<div className="split-container">
<div className="split-item">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/flashing-firmware/esp32/"}
>
Flash ESP32 Firmware
</Link>
</div>
<div className="split-item">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/flashing-firmware/nrf52/"}
>
Flash nRF52 Firmware
</Link>
</div>
</div>
</div>

View file

@ -197,3 +197,16 @@ The following are known limitations:
- Raspberry Pi is not available, since it is arm-based and there are no pre-built libraries for [PySide](https://wiki.qt.io/Qt_for_Python)
- Ubuntu 20.04 is the version used for testing, it may work with other versions.
- See [README](https://github.com/meshtastic/Meshtastic-gui-installer/blob/master/README.md) for more details.
## Connect and Configure Device
After flashing the Meshtastic firmware to the device, you can proceed with the initial configuration.
<div className="indexCtasBody">
<Link
className={"button button--outline button--lg cta--button"}
to={"/docs/getting-started/initial-config"}
>
Connect and Configure Device
</Link>
</div>

View file

@ -82,6 +82,13 @@ html[data-theme="dark"] .header-github-link:before {
color: var(--ifm-link-color);
}
.split-container {
display: flex;
}
.split-item {
flex: 1;
}
.indexCtasBody {
--ifm-button-size-multiplier: 1.6;
display: flex;