From bfac706d528742d3fc6ee87d0c7671a79abc4356 Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Sat, 21 Jan 2023 10:32:24 -0700 Subject: [PATCH] updates to getting-started for flow --- .../flashing-firmware/esp32/cli-script.mdx | 16 +- .../esp32/external-serial-adapter.mdx | 16 +- .../flashing-firmware/esp32/index.mdx | 2 +- .../esp32/python-flasher.mdx | 1 + .../flashing-firmware/esp32/web-flasher.mdx | 15 ++ .../flashing-firmware/nrf52/drag-n-drop.mdx | 16 +- .../flashing-firmware/nrf52/index.mdx | 4 +- .../flashing-firmware/nrf52/nrf52-erase.mdx | 13 +- .../nrf52/python-flasher.mdx | 1 + docs/getting-started/index.mdx | 199 ++++++------------ docs/getting-started/initial-config.mdx | 16 +- .../serial-drivers/serial-drivers-esp32.mdx | 22 +- .../serial-drivers/serial-drivers-nrf52.mdx | 44 ++-- .../test-serial-driver-installation.mdx | 101 +++++++++ docs/software/python-flasher.mdx | 13 ++ src/css/custom.css | 7 + 16 files changed, 317 insertions(+), 169 deletions(-) create mode 100644 docs/getting-started/serial-drivers/test-serial-driver-installation.mdx diff --git a/docs/getting-started/flashing-firmware/esp32/cli-script.mdx b/docs/getting-started/flashing-firmware/esp32/cli-script.mdx index 722a6e75..85d0cece 100644 --- a/docs/getting-started/flashing-firmware/esp32/cli-script.mdx +++ b/docs/getting-started/flashing-firmware/esp32/cli-script.mdx @@ -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. - +
+ + Connect and Configure Device + +
diff --git a/docs/getting-started/flashing-firmware/esp32/external-serial-adapter.mdx b/docs/getting-started/flashing-firmware/esp32/external-serial-adapter.mdx index 4cfffcb4..590985e5 100644 --- a/docs/getting-started/flashing-firmware/esp32/external-serial-adapter.mdx +++ b/docs/getting-started/flashing-firmware/esp32/external-serial-adapter.mdx @@ -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. + +
+ + Connect and Configure Device + +
diff --git a/docs/getting-started/flashing-firmware/esp32/index.mdx b/docs/getting-started/flashing-firmware/esp32/index.mdx index 1b9f1835..4b48ea5c 100644 --- a/docs/getting-started/flashing-firmware/esp32/index.mdx +++ b/docs/getting-started/flashing-firmware/esp32/index.mdx @@ -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. diff --git a/docs/getting-started/flashing-firmware/esp32/python-flasher.mdx b/docs/getting-started/flashing-firmware/esp32/python-flasher.mdx index ff3b9f1e..f9bee5dd 100644 --- a/docs/getting-started/flashing-firmware/esp32/python-flasher.mdx +++ b/docs/getting-started/flashing-firmware/esp32/python-flasher.mdx @@ -6,5 +6,6 @@ sidebar_position: 2 --- import MFlasher from "../../../software/python-flasher.mdx"; +import Link from "@docusaurus/Link"; diff --git a/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx b/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx index 79d6c4da..b6cc4233 100644 --- a/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx +++ b/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx @@ -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. + +
+ + Connect and Configure Device + +
diff --git a/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx b/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx index 2ebd1d55..2418b0d4 100644 --- a/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx @@ -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. + +
+ + Connect and Configure Device + +
diff --git a/docs/getting-started/flashing-firmware/nrf52/index.mdx b/docs/getting-started/flashing-firmware/nrf52/index.mdx index 2fb8a7ef..ab7105b5 100644 --- a/docs/getting-started/flashing-firmware/nrf52/index.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/index.mdx @@ -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. diff --git a/docs/getting-started/flashing-firmware/nrf52/nrf52-erase.mdx b/docs/getting-started/flashing-firmware/nrf52/nrf52-erase.mdx index 82865595..3e23e7c5 100644 --- a/docs/getting-started/flashing-firmware/nrf52/nrf52-erase.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/nrf52-erase.mdx @@ -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. + +
+ + Flash nRF52 Firmware + +
diff --git a/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx b/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx index ff3b9f1e..375a9872 100644 --- a/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx @@ -5,6 +5,7 @@ sidebar_label: Python Flasher sidebar_position: 2 --- +import Link from "@docusaurus/Link"; import MFlasher from "../../../software/python-flasher.mdx"; diff --git a/docs/getting-started/index.mdx b/docs/getting-started/index.mdx index 88d37153..ac6dee23 100644 --- a/docs/getting-started/index.mdx +++ b/docs/getting-started/index.mdx @@ -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.
-
-
- - Install ESP32 Drivers - +
+
+ + Install ESP32 Drivers + +
+ +
+ + Install NRF52 Drivers + +
-
-
- - Install NRF52 Drivers - -
-
-
+### 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: - - - - -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) -``` - - - - -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` - - - - -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)` - - - - -:::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.
-
-
- - Flash ESP32 Firmware - -
-
+
+
+ + Flash ESP32 Firmware + +
-
-
- - Flash NRF52 Firmware - +
+ + Flash nRF52 Firmware + +
-
## 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.
Connect and Configure Device
- -## 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. diff --git a/docs/getting-started/initial-config.mdx b/docs/getting-started/initial-config.mdx index 31346f7d..140c7c0c 100644 --- a/docs/getting-started/initial-config.mdx +++ b/docs/getting-started/initial-config.mdx @@ -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 + +## 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. + +
+ + Device Configuration + +
diff --git a/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx b/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx index ed8213f5..7ae12650 100644 --- a/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx +++ b/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx @@ -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. :::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. + +
+ + Flash ESP32 Firmware + +
diff --git a/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx b/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx index c67f0d3d..52ec415b 100644 --- a/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx +++ b/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx @@ -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 - [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. -::: - + +:::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. + +
+ + Flash nRF52 Firmware + +
diff --git a/docs/getting-started/serial-drivers/test-serial-driver-installation.mdx b/docs/getting-started/serial-drivers/test-serial-driver-installation.mdx new file mode 100644 index 00000000..0e5b5365 --- /dev/null +++ b/docs/getting-started/serial-drivers/test-serial-driver-installation.mdx @@ -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: + + + + +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) +``` + + + + +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` + + + + +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)` + + + + +:::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. + +
+
+
+ + Flash ESP32 Firmware + +
+ +
+ + Flash nRF52 Firmware + +
+
+
diff --git a/docs/software/python-flasher.mdx b/docs/software/python-flasher.mdx index 420a45db..980bb189 100644 --- a/docs/software/python-flasher.mdx +++ b/docs/software/python-flasher.mdx @@ -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. + +
+ + Connect and Configure Device + +
diff --git a/src/css/custom.css b/src/css/custom.css index ee8a13c1..1b050496 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -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;