Merge pull request #266 from jfirwin/data-cord

Data cable and driver edits
This commit is contained in:
Foster Irwin 2022-03-02 12:38:13 -07:00 committed by GitHub
commit b4874ef1e9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 320 additions and 172 deletions

View file

@ -2,7 +2,6 @@
id: concepts
title: Concepts
sidebar_label: Concepts
slug: /getting-started/concepts
---
Various high level concepts used in the Meshtastic meta verse:

View file

@ -9,50 +9,13 @@ import TabItem from '@theme/TabItem';
## Prerequisites
### Check Data Cable
### Device connectivity
Plug your device into your computer using a USB cable and then do the following:
:::important
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)
Some newer boards may require the drivers for the [CH9102 Windows](http://www.wch.cn/downloads/CH343SER_ZIP.html) or [Direct Download](https://github.com/Xinyuan-LilyGO/CH9102_Driver) for Windows 7. For [CH9102 Mac](http://www.wch.cn/downloads/CH34XSER_MAC_ZIP.html). Click the big blue button with the down arrow. Be sure to open up the application and click "Install" after the package is installed. Also, reboot.
:::
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
> Connect your Meshtastic device to your USB port, open a `Terminal` and enter the following command:
>
> ```bash
> lsusb
> ```
>
> You should see something like: `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X or `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102
</TabItem>
<TabItem value="macos">
> Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`.
> You should see something like `CP210X USB to UART Bridge Controller`. If not download the appropriate drivers
</TabItem>
<TabItem value="windows">
> Navigate to `Device Manager > Ports (COM & LPT)`. You should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)`. If not download the appropriate drivers
</TabItem>
</Tabs>
Ensure your computer is communicating with the device correctly by following [these instructions](flashing-firmware).
### Download Latest Firmware
Firmware can be downloaded from the [Downloads](/downloads) page. Your initial installation has to happen over USB from your Mac, Windows, or Linux PC. Once our software is installed, all future software updates happen over Bluetooth from your phone.
Firmware can be downloaded from the [Downloads](/downloads) page. Your initial installation has to happen over USB from your Mac, Windows, or Linux computer. Over the air updates are currently only available using the Android application after this initial installation.
:::note
The [T-Beam 0.7](/docs/hardware/supported/tbeam#t-beam---v07) board is an earlier version of the T-Beam board, and due to changes in the design in subsequent iterations this board uses a specific firmware file different from the other T-Beam boards.
@ -74,38 +37,38 @@ values={[
### Install Prerequisite Software
> 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
> ```
>
> If `pip` is not installed, install with
>
> ```bash
> sudo apt-get install python3-pip
> ```
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
```
If `pip` is not installed, install with
```bash
sudo apt-get install python3-pip
```
### Install `esptool`
> ```bash
> pip3 install --upgrade esptool
> ```
```bash
pip3 install --upgrade esptool
```
</TabItem>
<TabItem value="macos">
### Install Prerequisite Software
> 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`.
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
@ -117,37 +80,37 @@ brew -v
If it's not installed, follow the instructions on the [Homebrew website](https://brew.sh) before continuing.
:::
> Check if you have `python3` and `pip` installed with the following command
>
> ```bash
> python3 --version
> pip3 --version
> ```
>
> If `python3` is not installed, install with
> Install Python3
>
> ```bash
> brew install python3
> ```
>
> Confirm `pip3` was installed alongside `python3`
>
> ```bash
> pip3 -v
> ```
Check if you have `python3` and `pip` installed with the following command
```bash
python3 --version
pip3 --version
```
If `python3` is not installed, install with
Install Python3
```bash
brew install python3
```
Confirm `pip3` was installed alongside `python3`
```bash
pip3 -v
```
### Install `esptool`
> ```bash
> pip3 install --upgrade esptool
> ```
```bash
pip3 install --upgrade esptool
```
</TabItem>
<TabItem value="windows">
> - Download and install [Python](https://www.python.org/). When installing, make sure to click `Add Python X.Y to PATH`.
> - Download and install [Gitbash](https://gitforwindows.org/) (or other appropriate shell) and run all subsequent commands from that shell.
- Download and install [Python](https://www.python.org/). When installing, make sure to click `Add Python X.Y to PATH`.
- Download and install [Gitbash](https://gitforwindows.org/) (or other appropriate shell) and run all subsequent commands from that shell.
:::note
Confirm installation of `python` & `pip` with the following commands.
@ -164,9 +127,9 @@ pip --version
### Install `esptool`
> ```bash
> pip install --upgrade esptool
> ```
```bash
pip install --upgrade esptool
```
</TabItem>
</Tabs>
@ -245,45 +208,45 @@ values={[
#### Install
> ```bash title="Command"
> ./device-install.sh -f firmware-BOARD-VERSION.bin
> ```
```bash title="Command"
./device-install.sh -f firmware-BOARD-VERSION.bin
```
#### Update
> ```bash title="Command"
> ./device-update.sh -f firmware-BOARD-VERSION.bin
> ```
```bash title="Command"
./device-update.sh -f firmware-BOARD-VERSION.bin
```
</TabItem>
<TabItem value="macos">
#### Install
> ```bash title="Command"
> ./device-install.sh -f firmware-BOARD-VERSION.bin
> ```
```bash title="Command"
./device-install.sh -f firmware-BOARD-VERSION.bin
```
#### Update
> ```bash title="Command"
> ./device-update.sh -f firmware-BOARD-VERSION.bin
> ```
```bash title="Command"
./device-update.sh -f firmware-BOARD-VERSION.bin
```
</TabItem>
<TabItem value="windows">
#### Install
> ```bash title="Command"
> ./device-install.bat -f firmware-BOARD-VERSION.bin
> ```
```bash title="Command"
./device-install.bat -f firmware-BOARD-VERSION.bin
```
#### Update
> ```bash title="Command"
> ./device-update.bat -f firmware-BOARD-VERSION.bin
> ```
```bash title="Command"
./device-update.bat -f firmware-BOARD-VERSION.bin
```
</TabItem>
</Tabs>

View file

@ -0,0 +1,162 @@
---
id: flashing-firmware
title: Firmware Flashing Prerequisites
sidebar_label: Prerequisites
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
## Overview
Before you flash your device it is prudent to verify that we have proper connectivity with the device being flashed. Outlined below are steps that can be taken to verify connectivity and, if necessary, to install the appropriate drivers. If you end up needing to install drivers be sure to reboot your computer afterwards to verify the installation is complete.
## Prerequisites
### Verify data cable
Verify you have a data cable (not a charging only cable) before proceeding. There's 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.
Once you've located a data cable, check the following to see if you need to install a driver to communicate with your device.
:::tip
If you know you have installed the correct driver, the following step can be used to check if your cable is a data cable.
:::
### Test for 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. Select your operating system below.
If you can see your device, you are ready to flash the firmware. Skip to the[Choose Firmware Flashing Method section](#choose-firmware-flashing-method).
If you don't see your device in the following test, you either:
1. Need to [install a driver](#install-appropriate-drivers).
2. Are currently using a charging only cable.
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
Connect your Meshtastic device to your USB port, open a `Terminal` and enter the following command:
```bash
lsusb
```
You should see something like: `ID xxxx:xxxx Silicon Labs CP210x UART Bridge`, `ID xxxx:xxxx QinHeng Electronics USB Single Serial`, or `FIXME (WISBLOCK OUTPUT)`.
</TabItem>
<TabItem value="macos">
Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`. You should see something like `CP210X USB to UART Bridge Controller`, `CH9102 USB to UART Bridge Controller`, or `WisCore RAK4631 Board`. If not download the appropriate drivers below.
</TabItem>
<TabItem value="windows">
Navigate to `Device Manager > Ports (COM & LPT)`. You should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)`, `Silicon Labs CH9102 USB to UART Bridge (COM5)`, or `FIXME (WISBLOCK OUTPUT)`. If not download the appropriate drivers below.
</TabItem>
</Tabs>
## Install Appropriate Drivers
### ESP32 Drivers
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)
Some newer boards may require the CH9102 (CH340/CH341) Driver.
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
[CP210X USB to UART bridge - Download](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
[CH9102 Driver - Linux Download](http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html)
</TabItem>
<TabItem value="macos">
[CP210X USB to UART bridge - Download](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
[CH9102 Driver - MacOS Download](http://www.wch.cn/downloads/CH34XSER_MAC_ZIP.html)
</TabItem>
<TabItem value="windows">
[CP210X USB to UART bridge - Download](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)
[CH9102 Driver - Windows Download](http://www.wch.cn/downloads/CH343SER_ZIP.html)
[CH9102 Driver - Windows Download (Direct Download for Windows 7)](https://github.com/Xinyuan-LilyGO/CH9102_Driver)
</TabItem>
</Tabs>
### NRF52 Drivers
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
[CH9102 Driver - Linux Download](http://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html)
</TabItem>
<TabItem value="macos">
[CH9102 Driver - MacOS Download](http://www.wch-ic.com/downloads/CH341SER_MAC_ZIP.html)
:::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:
<details>
<summary>Removing the CH34x (CH340/CH341) USB Drivers</summary>
<div>
<div>
If you have already downloaded/installed the MacOS WCH-IC CH340 ("CH341SER_MAC") drivers via the CH34x_Install_V1.5.pkg, you will have to Uninstall the kernel extension:
<br />
<br />
1. Unplug your T-Echo<br />
2. Open the Terminal and run:<br />
3. sudo -rf /Library/Extensions/usbserial.kext<br />
4. Reboot
</div>
</div>
</details>
:::
</TabItem>
<TabItem value="windows">
[CH9102 Driver - Windows Download](http://www.wch-ic.com/downloads/CH341SER_EXE.html)
</TabItem>
</Tabs>
:::important
Reboot your computer after you have installed the driver to complete the installation.
:::
## Choose Firmware Flashing Method
For most users we recommend using the [Meshtastic Flasher application](meshtastic-flasher). It does a lot under the hood to prevent you from needing to use the terminal. It also allows you to set device settings and configure your device.
If you choose to flash the firmware using the manual method, [ESP32 based devices](flashing-esp32) and [NRF52 based devices](flashing-nrf52) have different methods. Select the appropriate one. If you don't know what chipset your device is, take a look at our supported hardware section.

View file

@ -7,66 +7,23 @@ sidebar_label: nRF52 devices
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
## Pre-requisites
## Prerequisites
:::tip
Please ensure that you use a data USB-C cable, as many USB-C cables provide power only and not the data lines.
:::
### Device connectivity
### T-Echo
Ensure your computer is communicating with the device correctly by following [these instructions](flashing-firmware).
:::tip
The USB-C to USB-A cable from LILYGO is _NOT_ a "data cable", and can only be used for charging.
:::
### Download Latest Firmware
#### Windows:
Firmware can be downloaded from the [Downloads](/downloads) page. Your initial installation has to happen over USB from your Mac, Windows, or Linux computer. Over the air updates are currently only available using the Android application after this initial installation.
You may need to install the [USB device drivers](http://www.wch-ic.com/search?q=ch340&t=downloads) if your device does not show up when connected.
#### Mac OS
Last Verified T-Echo nRF52840 on: Mac OS Monterey v12.0.1 (Intel chipset)
:::tip
You can use the latest [Apple USB-C Charge cables](https://www.apple.com/shop/product/MLL82AM/A/usb-c-charge-cable-2-m). The cable that is provided with the iPad Pro works. Older Laptop USB-C Power cables will _NOT_ work, as they are missing the data lines.
:::
:::caution
With the latest versions of MacOS, the USB Serial driver is built-in. Do _NOT_ download any USB device drivers - this will actually prevent you from connecting to your T-Echo from your Mac. If you downloaded/installed any already, please Remove them.
:::
<details>
<summary>Removing the CH34x (CH340/CH341) USB Drivers</summary>
<div>
<div>
If you have already downloaded/installed the MacOS WCH-IC CH340 ("CH341SER_MAC") drivers via the CH34x_Install_V1.5.pkg, you will have to Uninstall the kernel extension:
<br />
<br />
1. Unplug your T-Echo<br />
2. Open the Terminal and run:<br />
3. sudo -rf /Library/Extensions/usbserial.kext<br />
4. Reboot
</div>
</div>
</details>
Verify successful connections with:
- Plug in your T-Echo
- Open the Terminal
- `ls -l /dev/tty.usbmodem*`
If the device file exists, you will also notice a "TECHOBOOT" volume in the Finder, or in the Terminal after double-clicking the Reset Button (see below)
- `ls /Volumes/TECHOBOOT`
### WisBlock RAK4631
### WisBlock RAK4631 Bootloader
Please ensure that you have updated the bootloader to the latest version using the information on the [RAK Documentation Center](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK4631/Quickstart/#how-to-check-if-you-have-the-updated-rak4631-bootloader) website.
## Download Latest Firmware
Firmware can be downloaded from the [Downloads](/downloads) page. Your initial installation has to happen over USB from your Mac, Windows or Linux PC. Once our software is installed, all future software updates happen over Bluetooth from your phone.
:::tip
[Meshtastic Flasher](meshtastic-flasher) can assist you in updating the bootloader to the latest version.
:::
## Install/Update Firmware

View file

@ -4,6 +4,7 @@ title: Getting Started
sidebar_label: Getting Started
slug: /getting-started
---
import Link from '@docusaurus/Link';
## What is Meshtastic?
@ -13,10 +14,23 @@ The radios automatically create a mesh to forward packets as needed, so everyone
Meshtastic uses LoRa for the long range communications and depending on settings used, the maximum theoretical group size ranges from 30-200 device nodes. Currently, each device can only support a connection from a single user at a time.
<Link
className={'button button--outline button--lg cta--button'}
to={'/docs/about'}>
Learn More
</Link>
## Purchase a Radio
The easiest way is to [buy a device with the software already installed](https://www.aliexpress.com/item/4001178678568.html). Other devices are [available](/docs/hardware/supported/tbeam). In the Americas get the 915MHz version, in Europe the 868MHz, or Asia 923MHz. See this listing by [The Things Network](https://www.thethingsnetwork.org/docs/lorawan/frequencies-by-country.html) for frequencies by specific countries.
<Link
className={'button button--outline button--lg cta--button'}
to={'/docs/hardware'}>
Purchase Hardware
</Link>
## Setup the Radio
When it arrives, install your antenna and make sure you install the battery correctly. Reversing the battery can damage your device. Make sure the antenna is on when you power up the board.
@ -25,18 +39,25 @@ When it arrives, install your antenna and make sure you install the battery corr
Make sure not to power the radio on without first attaching the antenna! You could damage the radio chip!
:::
## Download Firmware
Firmware can be downloaded from the [Downloads](/downloads) page. Your initial installation has to happen over USB from your Mac, Windows, or Linux PC. Once our software is installed, all future software updates happen over Bluetooth from your phone.
## Flashing Firmware
If your device already has Meshtastic flashed to it, you can update it over the air (OTA). Otherwise, you'll need a computer and a **data** USB cable. This can be done in the following ways:
If your device already has Meshtastic flashed to it, you can update it over the air (OTA). Otherwise, you'll need a computer and a **data** USB cable. Flashing firmware can be done in the following ways:
- Install using the command line interface (CLI)
- Install using a graphical user interface (GUI)
- Install using Meshtastic Flasher:
The firmware installation method will also depend on whether you have an ESP32 based device or a nRF52 based device. See our [hardware section](/docs/hardware) to determine which microcontroller your device is based on.
This all in one application will download the appropriate firmware, detect your device, flash the device, and allow you to configure your settings.
- Install using manual method:
Manual firmware files can be downloaded from the [Downloads](/downloads) page.
The manual firmware installation method will also depend on whether you have an ESP32 based device or a nRF52 based device. See our [hardware section](/docs/hardware) to determine which microcontroller your device is based on.
<Link
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/flashing-firmware'}>
Flash Firmware
</Link>
## Connect to your Device
@ -48,7 +69,7 @@ There are many ways to connect to your new radio!
- Bluetooth
- Web app over Wifi (in development)
## A good first test (connect via USB and CLI)
### A good first test (connect via USB and CLI)
If you have at least two radios with the Meshtastic firmware, you may consider connecting one via USB and the other battery powered. Communicate with the USB radio using a CLI like [Meshtastic-python](https://meshtastic.org/docs/software/python/python-installation).
@ -60,7 +81,7 @@ If you have at least two radios with the Meshtastic firmware, you may consider c
- Run `meshtastic --nodes` to see if other nodes show in the display.
- Messages sent from the USB radio should be sent to the other radio(s) via LoRa. The default settings should allow this to work.
## A good second test (connect via Bluetooth)
### A good second test (connect via Bluetooth)
The Android app is currently more robust than the iOS app. But, they both should be able to interact with the radios.
@ -72,7 +93,7 @@ The Android app is currently more robust than the iOS app. But, they both should
- Note: The radio connected via Bluetooth will not show messages sent.
- Verify that all other radios are receiving the message(s). Might have to click on the button on the radio to see most recent message.
## A good third test (connect via Wifi/HTTP)
### A good third test (connect via Wifi/HTTP)
- Configure the _wifi_ssid_ and _wifi_password_. `meshtastic --set wifi_ssid 'xxx' --set wifi_password 'yyy'` (where xxx and yyy are the appropriate values for your network)
- Reboot radio by either removing power or pressing the power button.

View file

@ -14,6 +14,46 @@ Meshtastic Flasher is a graphical user interface for flashing [supported devices
Install Meshtastic Flasher by either [downloading the executable file](https://github.com/meshtastic/Meshtastic-gui-installer/releases) or installing using `pip`. The following operating systems are currently supported: Windows, Mac, and Ubuntu.
### Check Data Cable
Plug your device into your computer using a USB cable and then do the following:
:::important
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)
Some newer boards may require the drivers for the [CH9102 Windows](http://www.wch.cn/downloads/CH343SER_ZIP.html) or [Direct Download](https://github.com/Xinyuan-LilyGO/CH9102_Driver) for Windows 7. For [CH9102 Mac](http://www.wch.cn/downloads/CH34XSER_MAC_ZIP.html). Click the big blue button with the down arrow. Be sure to open up the application and click "Install" after the package is installed. Also, reboot.
:::
<Tabs
groupId="operating-system"
defaultValue="linux"
values={[
{label: 'Linux', value: 'linux'},
{label: 'macOS', value: 'macos'},
{label: 'Windows', value: 'windows'},
]}>
<TabItem value="linux">
Connect your Meshtastic device to your USB port, open a `Terminal` and enter the following command:
```bash
lsusb
```
You should see something like: `ID 10c4:ea60 Silicon Labs CP210x UART Bridge` for CP210X or `ID 1a86:55d4 QinHeng Electronics USB Single Serial` for CH9102
</TabItem>
<TabItem value="macos">
Navigate to `Apple Menu  > About This Mac > System Report... > Hardware > USB`. You should see something like `CP210X USB to UART Bridge Controller`. If not download the appropriate drivers
</TabItem>
<TabItem value="windows">
Navigate to `Device Manager > Ports (COM & LPT)`. You should see something like `Silicon Labs CP210X USB to UART Bridge (COM5)`. If not download the appropriate drivers
</TabItem>
</Tabs>
### Install using `pip`
<Tabs
groupId="operating-system"

View file

@ -131,6 +131,7 @@ module.exports = {
"getting-started/faq",
{
"Flashing firmware": [
"getting-started/flashing-firmware",
"getting-started/meshtastic-flasher",
{
"Manual Method": [

View file

@ -50,3 +50,8 @@ html[data-theme="dark"] .header-github-link:before {
box-shadow: 0 0 0 0 rgba(0, 0, 0, 0);
}
}
.cta--button {
--ifm-button-border-color: var(--ifm-link-color);
color: var(--ifm-link-color);
}