Merge pull request #21 from jfirwin/master

Reconsolidated firmware flashing sections
This commit is contained in:
Sacha Weatherstone 2021-04-17 14:58:13 +10:00 committed by GitHub
commit c662741c68
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 321 additions and 119 deletions

View file

@ -1,77 +0,0 @@
---
id: flashing_firmware_cli
title: Flashing Firmware CLI
sidebar_label: Command Line Interface
slug: /getting_started/flashing_firmware/cli
---
:::caution
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly.
:::
## Linux
Requires `Python` and `pip`
1. Download and unzip the latest Meshtastic firmware [release](https://github.com/meshtastic/Meshtastic-esp32/releases).
2. `pip install --upgrade esptool` - Installs esptool on your machine
3. Connect your radio to your USB port
4. `esptool.py chip_id` - Confirm that your device is talking to your PC by running
You should see something like:
```
mydir$ esptool.py chip_id
esptool.py v2.6
Found 2 serial ports
Serial port /dev/ttyUSB0
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC: 24:6f:28:b5:36:71
Uploading stub...
Running stub...
Stub running...
Warning: ESP32 has no Chip ID. Reading MAC instead.
MAC: 24:6f:28:b5:36:71
Hard resetting via RTS pin...
```
5. `cd` into the directory where you unzipped the latest release.
6. Install the correct firmware for your board with `device-install.sh -f firmware-BOARD-VERSION.bin`
```
./device-install.sh -f firmware-heltec-1.2.x.bin
```
7. To update a the firmware on an existing Meshtastic device, run `device-update.sh -f firmware-BOARD-VERSION.bin`
```
./device-update.sh -f firmware-heltec-1.2.x.bin
```
## MacOS
Installing on OS X through the commandline uses the same method as linux, but requires a slightly different method to install Python, pip and esptool.
OS X (10.15.3/Catalina) comes with Python 2.7 installed, but not pip.
:::note
If you don't know if Homebrew is installed on your Mac, open terminal and enter the command `brew -v` if it doesn't work [install Homebrew](https://brew.sh) before continuing.
:::
1. `brew install pyenv` - Installs PyEnv
2. `pyenv install 3.7.7` - To install and select Python 3.7.7
3. `pyenv global 3.7.7` - Selects the new version of Python
4. `brew install pip` - Installs pip3
5. `pip3 install --upgrade esptool` - Installs esptool
You may need to install a driver from Silicon Labs for the [CP210X USB to UART bridge](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
6. Now install as per installing on the Linux commandline. Replace `pip` with `pip3` in your commands.
## Windows
Requires `Python`, `pip`, `Gitbash`
1. Download and install [Python](https://www.python.org/)
2. If you have a recent version of Python, pip should be installed by default. Check using the command `py -m pip --version`. This will display the installed version of pip. If it returns an error, you will need to [install pip](https://pip.pypa.io/en/stable/installing/).
3. Download and install [Gitbash](https://gitforwindows.org/) (or other appropriate shell)
4. Run `gitbash` and complete the installation as per the instructions for linux commandline.

View file

@ -1,24 +0,0 @@
---
id: flashing_firmware_gui
title: Flashing Firmware GUI
sidebar_label: Graphic User Interface
slug: /getting_started/flashing_firmware/gui
---
:::caution
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly.
:::
## Windows & MacOS
1. Download and unzip the latest Meshtastic firmware [release](https://github.com/meshtastic/meshtastic-device/releases/latest).
2. Download [ESPHome Flasher](https://github.com/esphome/esphome-flasher) following their installation instructions.
3. Connect your radio to your USB port and open ESPHome Flasher.
4. If your board is not showing under Serial Port then you likely need to install the drivers for the CP210X serial chip. In Windows you can check by searching “Device Manager” and ensuring the device is shown under “Ports”.
5. If there is an error, download the [drivers](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers), then unzip and run the Installer application.
6. In ESPHome Flasher, refresh the serial ports and select the port to which your board is connected.
7. Browse to the previously downloaded firmware and select the correct firmware based on the board type.
8. Select Flash ESP.
9. Once complete, “Done! Flashing is complete!” will be shown.
10. The board will boot and show the Meshtastic logo.
11. Debug messages sent from the Meshtastic device can be viewed with a terminal program such as PuTTY. Within PuTTY, click “Serial”, enter the “Serial line” com port (can be found at step 4), enter “Speed” as `921600`, then click “Open”.

View file

@ -0,0 +1,100 @@
---
id: linux
title: Flashing Firmware Linux
sidebar_label: Linux
---
:::note
To check if you have a data cable that will work, plug in your device and **then** navigate to `Terminal` and enter the following command:
```bash
lsusb
```
you should see something like `CP210X USB to UART Bridge Controller`.
:::
## Download Firmware
<!--- TODO add buttons to links --->
Download the [latest](https://github.com/meshtastic/meshtastic-device/releases/latest) firmware release. Unzip the file and locate the correct device and region within the list of prebuilt binaries.
## Command Line Instructions
:::note
Check if you have `python3` and `pip` installed with the following command
```bash
python3 --version
pip3 --version
```
If `python3` is not installed, install with
```bash
sudo apt-get update
sudo apt-get install python3.6
```
If `pip` is not installed, install with
```bash
sudo apt-get install python3-pip
```
:::
1. Install `esptool`
```bash
pip install --upgrade esptool
```
2. Connect your radio to your USB port
3. Confirm that your device is talking to your Mac by running the following command in Terminal
```bash title="Command"
esptool.py chip_id
```
```bash title="Expected Output"
# You should see a result similar to this:
mydir$ esptool.py chip_id
esptool.py v2.6
Found 2 serial ports
Serial port /dev/ttyUSB0
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC: 24:6f:28:b5:36:71
Uploading stub...
Running stub...
Stub running...
Warning: ESP32 has no Chip ID. Reading MAC instead.
MAC: 24:6f:28:b5:36:71
Hard resetting via RTS pin...
```
4. `cd` into the directory where you unzipped the latest release. For example:
```bash title="Example"
cd /Downloads/firmware/
```
5. Install the correct firmware for your board with
:::caution
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly.
:::
```bash title="Command"
./device-install.sh -f firmware-BOARD-VERSION.bin
```
```bash title="Example"
./device-install.sh -f firmware-heltec-EU865-1.2.0.bin
```
6. To update a the firmware on an existing Meshtastic device, run
```bash title="Command"
./device-update.sh -f firmware-BOARD-VERSION.bin
```
```bash title="Example"
./device-update.sh -f firmware-heltec-EU865-1.2.0.bin
```
## Graphical User Interface Instructions
:::note
ESPHome Flasher for linux is a prebuilt binary for Ubuntu. These instructions were only testing on Ubuntu. Mileage may very on other distros. ESPHome Flasher also provides instructions to build from source or install via `pip` on their README.
:::
1. Download [ESPHome Flasher](https://github.com/esphome/esphome-flasher)
2. Connect your radio to your USB port.
3. Open ESPHome Flasher. There should be no installation required.
4. If your board is not showing under `Serial Port` then you may need to install the drivers for the [CP210X USB to UART bridge](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers).
5. In ESPHome Flasher, refresh the serial ports and select the port to which your board is connected.
6. Browse to the previously downloaded firmware and select the correct firmware based on the board type.
7. Select Flash ESP.
8. Once complete, “Done! Flashing is complete!” will be shown.

View file

@ -0,0 +1,109 @@
---
id: macos
title: Flashing Firmware MacOS
sidebar_label: MacOS
---
:::note
To check if you have a data cable that will work, plug in your device and **then** navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB` you should see something like `CP210X USB to UART Bridge Controller`.
:::
## Download Firmware
<!--- TODO add buttons to links --->
Download the [latest](https://github.com/meshtastic/meshtastic-device/releases/latest) firmware release. Unzip the file and locate the correct device and region within the list of prebuilt binaries.
## Command Line Instructions
OS X comes with `Python 2.7` installed, but not `pip`. The following uses Homebrew to install `python3` which includes `pip3`. On MacOS you will use `pip3` instead of `pip`.
:::note
Check if you have Homebrew installed with the following command
```bash
brew -v
```
If it's not installed, follow the instructions on the [Homebrew website](https://brew.sh) before continuing.
:::
1. Install Python3
```bash
brew install python3
```
2. Confirm `pip3` was installed alongside `python3`
```bash
pip3 -v
```
3. Install `esptool`
```bash
pip3 install --upgrade esptool
```
:::note
You may need to install a driver from Silicon Labs for the [CP210X USB to UART bridge](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
:::
4. Connect your radio to your USB port.
5. Confirm that your device is talking to your Mac by running the following command in Terminal.
```bash title="Command"
esptool.py chip_id
```
```bash title="Expected Output"
# You should see a result similar to this:
mydir$ esptool.py chip_id
esptool.py v2.6
Found 2 serial ports
Serial port /dev/ttyUSB0
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC: 24:6f:28:b5:36:71
Uploading stub...
Running stub...
Stub running...
Warning: ESP32 has no Chip ID. Reading MAC instead.
MAC: 24:6f:28:b5:36:71
Hard resetting via RTS pin...
```
6. `cd` into the directory where you unzipped the latest release. For example:
```bash title="Example"
cd /Downloads/firmware/
```
7. Install the correct firmware for your board with
:::caution
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly.
:::
```bash title="Command"
./device-install.sh -f firmware-BOARD-VERSION.bin
```
```bash title="Example"
./device-install.sh -f firmware-heltec-EU865-1.2.0.bin
```
8. To update a the firmware on an existing Meshtastic device, run
```bash title="Command"
./device-update.sh -f firmware-BOARD-VERSION.bin
```
```bash title="Example"
./device-update.sh -f firmware-heltec-EU865-1.2.0.bin
```
## Graphical User Interface Instructions
:::note
ESPHome Flasher also provides instructions to build from source or install via `pip` on their README.
:::
1. Download [ESPHome Flasher](https://github.com/esphome/esphome-flasher)
2. Connect your radio to your USB port.
3. Open ESPHome Flasher. There should be no installation required.
:::note
If you get an error saying `The application "ESPHome-Flasher.app" can't be opened` it is likely a permissions issue. See [here](https://github.com/esphome/esphome-flasher/issues/26#issuecomment-671061140) for instructions.
:::
:::note
If you get an error saying `"ESPHome-Flasher.app" cannot be opened because the developer cannot be verified`, click `cancel`. Right click on the application and select `Open`. Select `Open` on the confirmation alert.
:::
4. If your board is not showing under `Serial Port` then you may need to install the drivers for the [CP210X USB to UART bridge](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers).
5. In ESPHome Flasher, refresh the serial ports and select the port to which your board is connected.
6. Browse to the previously downloaded firmware and select the correct firmware based on the board type.
7. Select Flash ESP.
8. Once complete, “Done! Flashing is complete!” will be shown.

View file

@ -1,8 +1,7 @@
---
id: flashing_firmware_ota
id: ota
title: Flashing Firmware OTA
sidebar_label: Over The Air
slug: /getting_started/flashing_firmware/ota
---
:::caution
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly.

View file

@ -1,8 +1,7 @@
---
id: flashing_firmware_overview
id: overview
title: Overview
sidebar_label: Overview
slug: /getting_started/flashing_firmware/overview
---
## Download Firmware
@ -16,11 +15,16 @@ Be very careful to install the correct load for your board. In particular the po
| [Current Firmware](https://github.com/meshtastic/meshtastic-device/releases/latest) | [List of Firmware Versions](https://github.com/meshtastic/meshtastic-device/releases/) |
| :--------------: | :-----------------------: |
Firmware Flashing Methods
- [Command line interface](cli)
- [Graphic user interface](gui)
Firmware flashing methods
- Command line interface
- [Linux](linux#command-line-instructions)
- [MacOS](macos#command-line-instructions)
- [Windows](windows#command-line-instructions)
- Graphical user interface
- [Linux](linux#graphical-user-interface-instructions)
- [MacOS](macos#graphical-user-interface-instructions)
- [Windows](windows#graphical-user-interface-instructions)
- [Over the air](ota)
## Troubleshooting
For any issues during setup, search [our forum](https://meshtastic.discourse.group) to find a solution. If you can't find one, please post your problem, providing as much detail as possible.
:::note
Over the air (OTA) firmware installation is currently only available on the Android App.
:::

View file

@ -0,0 +1,90 @@
---
id: windows
title: Flashing Firmware Windows
sidebar_label: Windows
---
:::note
To check if you have a data cable that will work, plug in your device and navigate to `Device Manager > Ports` and ensure the device is shown. You should see something like `CP210X USB to UART Bridge Controller`.
If your device is showing up under `Device Manager > Ports > Other Devices` you need to install the driver from Silicon Labs for the [CP210X USB to UART bridge](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
:::
## Download Firmware
<!--- TODO add buttons to links --->
Download the [latest](https://github.com/meshtastic/meshtastic-device/releases/latest) firmware release. Unzip the file and locate the correct device and region within the list of prebuilt binaries.
## Command Line Instructions
1. Download and install [Python](https://www.python.org/). Make sure to click `Add Python X.Y to PATH`.
2. Download and install [Gitbash](https://gitforwindows.org/) (or other appropriate shell) and run all subsequent commands from that shell.
3. Confirm installation of `python` & `pip` with the following commands.
```bash
py --version
```
```bash
pip --version
```
<!--- Check on `gitbash` requirements --->
4. Install `esptool`
```bash
pip install --upgrade esptool
```
5. Connect your radio to your USB port.
6. Confirm that your device is talking to your Mac by running the following command in Terminal.
```bash title="Command"
esptool.py chip_id
```
```bash title="Expected Output"
# You should see a result similar to this:
mydir$ esptool.py chip_id
esptool.py v2.6
Found 2 serial ports
Serial port /dev/ttyUSB0
Connecting....
Detecting chip type... ESP32
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC: 24:6f:28:b5:36:71
Uploading stub...
Running stub...
Stub running...
Warning: ESP32 has no Chip ID. Reading MAC instead.
MAC: 24:6f:28:b5:36:71
Hard resetting via RTS pin...
```
7. `cd` into the directory where you unzipped the latest release. For example:
```bash title="Example"
cd /Downloads/firmware/
```
8. Install the correct firmware for your board with
:::caution
Be very careful to install the correct load for your board. In particular the popular 'T-BEAM' radio from TTGO is not called 'TTGO-Lora' (that is a different board). So don't install the 'TTGO-Lora' build on a TBEAM, it won't work correctly.
:::
```bash title="Command"
./device-install.sh -f firmware-BOARD-VERSION.bin
```
```bash title="Example"
./device-install.sh -f firmware-heltec-EU865-1.2.0.bin
```
9. To update a the firmware on an existing Meshtastic device, run
```bash title="Command"
./device-update.sh -f firmware-BOARD-VERSION.bin
```
```bash title="Example"
./device-update.sh -f firmware-heltec-EU865-1.2.0.bin
```
## Graphical User Interface Instructions
:::note
ESPHome Flasher also provides instructions to build from source or install via `pip` on their README.
:::
1. Download [ESPHome Flasher](https://github.com/esphome/esphome-flasher)
2. Connect your radio to your USB port.
3. Open ESPHome Flasher. There should be no installation required.
4. If your board is not showing under `Serial Port` then you may need to install the drivers for the [CP210X USB to UART bridge](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers).
5. In ESPHome Flasher, refresh the serial ports and select the port to which your board is connected.
6. Browse to the previously downloaded firmware and select the correct firmware based on the board type.
7. Select Flash ESP.
8. Once complete, “Done! Flashing is complete!” will be shown.

View file

@ -29,9 +29,9 @@ Prebuilt binaries for the supported radios are available in our releases. Your i
If your device already has Meshtastic flashed to it, You can update over the air (OTA). Otherwise you'll need a computer and a **data** USB cable.
- [Install using the command line interface (CLI)](getting_started/flashing_firmware/cli)
- [Install using a graphical user interface (GUI)](getting_started/flashing_firmware/gui)
- [Install using over-the-air (OTA)](getting_started/flashing_firmware/ota)
- Install using the command line interface (CLI)
- Install using a graphical user interface (GUI)
- Install using over-the-air (OTA)
## Connect to your Device

View file

@ -5,10 +5,11 @@ module.exports = {
"getting_started/overview",
{
"Flashing Firmware": [
"getting_started/flashing_firmware/flashing_firmware_overview",
"getting_started/flashing_firmware/flashing_firmware_cli",
"getting_started/flashing_firmware/flashing_firmware_gui",
"getting_started/flashing_firmware/flashing_firmware_ota",
"getting_started/flashing_firmware/overview",
"getting_started/flashing_firmware/linux",
"getting_started/flashing_firmware/macos",
"getting_started/flashing_firmware/ota",
"getting_started/flashing_firmware/windows",
],
"Howto's": [],
},