diff --git a/docs/getting-started/flashing-firmware/esp32/index.mdx b/docs/getting-started/flashing-firmware/esp32/index.mdx index 5b79ba23..31b5cf5c 100644 --- a/docs/getting-started/flashing-firmware/esp32/index.mdx +++ b/docs/getting-started/flashing-firmware/esp32/index.mdx @@ -10,4 +10,9 @@ import TabItem from '@theme/TabItem'; ## Recommended Flashing Method for ESP32 Devices -For ESP32 based device users (TBEAM, TLORA, Heltec etc.) we recommend using the [web based installer](https://flasher.meshtastic.org) or the [Meshtastic Flasher application](/docs/software/python/flasher). The 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. \ No newline at end of file +For ESP32 based device users (TBEAM, TLORA, Heltec etc.) + +We recommend using the following methods for flashing ESP32 devices: + +1. [Web-based installer](https://flasher.meshtastic.org) - The browser application requires either Chrome or Edge broswers but is an excellent choice for quickly flashing devices. +2. [Python Flasher](/docs/software/python/flasher) - The 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. \ No newline at end of file diff --git a/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx b/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx index 0bf4531b..6a84e362 100644 --- a/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx +++ b/docs/getting-started/flashing-firmware/esp32/web-flasher.mdx @@ -1,9 +1,9 @@ --- id: web-flasher title: Using Meshtastic Web Flasher -sidebar_label: Web Flasher +sidebar_label: Web Flasher (recommended) sidebar_position: 1 --- -[Web-based Installer](https://flasher.meshtastic.org) \ No newline at end of file +The [Web-based Installer](https://flasher.meshtastic.org) requires Chrome or Edge browser. \ No newline at end of file diff --git a/docs/getting-started/flashing-firmware/index.mdx b/docs/getting-started/flashing-firmware/index.mdx index 53e87e63..1ab54421 100644 --- a/docs/getting-started/flashing-firmware/index.mdx +++ b/docs/getting-started/flashing-firmware/index.mdx @@ -12,14 +12,8 @@ import TabItem from '@theme/TabItem'; Make sure not to power the radio on without first attaching the antenna! You could damage the radio chip! ::: -## Easiest Firmware install options - -If you have RAK NRF based devices or a LilyGO T-Echo, [the drag and drop firmware installation process](/docs/getting-started/flashing-firmware/nrf52/flashing-nrf52) is the easiest solution. - -For ESP32 based device users (TBEAM, TLORA, Heltec etc.) we recommend using the [web based installer](https://flasher.meshtastic.org) or the [Meshtastic Flasher application](/docs/software/python/flasher). The 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. - ## Manual Firmware Installation Firmware can be downloaded from the [Downloads](/downloads) page. Your initial installation has to happen over USB from your Mac, Windows, or Linux computer. -If you choose to flash the firmware using the manual method, [ESP32 based devices](/docs/getting-started/flashing-firmware/esp32/flashing-esp32) and [NRF52 based devices](/docs/getting-started/flashing-firmware/nrf52/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. +If you choose to flash the firmware using the manual method, [ESP32 based devices](/docs/getting-started/flashing-firmware/esp32/) and [NRF52 based devices](/docs/getting-started/flashing-firmware/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](/docs/category/supported-hardware) section. diff --git a/docs/getting-started/flashing-firmware/nrf52/flashing-nrf52.mdx b/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx similarity index 92% rename from docs/getting-started/flashing-firmware/nrf52/flashing-nrf52.mdx rename to docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx index 1bf315fb..ee1c9fe9 100644 --- a/docs/getting-started/flashing-firmware/nrf52/flashing-nrf52.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx @@ -1,10 +1,10 @@ --- -id: flashing-nrf52 -title: Drag & Drop NRF52 Firmware Updates -sidebar_label: Drag & Drop +id: drag-n-drop +title: Drag & Drop NRF52 Firmware Updates +sidebar_label: Drag & Drop (recommended) pagination_prev: getting-started/flashing-firmware/flashing-firmware pagination_next: getting-started/flashing-firmware/esp32/flashing-esp32 -sidebar_position: 2 +sidebar_position: 1 --- import Tabs from '@theme/Tabs'; diff --git a/docs/getting-started/flashing-firmware/nrf52/index.mdx b/docs/getting-started/flashing-firmware/nrf52/index.mdx index 3dc0d6b2..1ad92f4d 100644 --- a/docs/getting-started/flashing-firmware/nrf52/index.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/index.mdx @@ -10,33 +10,34 @@ import TabItem from '@theme/TabItem'; ## Recommended Flashing Method for NRF52 Devices -If you have RAK NRF based devices or a LilyGO T-Echo, [the drag and drop firmware installation process](/docs/getting-started/flashing-firmware/nrf52/flashing-nrf52) is the easiest solution. +If you have RAK NRF based devices or a LilyGO T-Echo +1. The [drag and drop](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop) firmware installation process is the easiest solution. ## Convert RAK4631-R to RAK4631 -Running Meshtastic on RAK WisBlock NRF52 based boards relies on the avaliability of the Arduino bootloader. +The RAK4631-R is just the same as the RAK4631 in terms of hardware, the only difference is the bootloader it is shipped with. -This process only needs to be performed once +The RAK4631-R is shipped with the RUI3 bootloader, the RAK4631 with the Arduino bootloader. + +Running Meshtastic on RAK WisBlock NRF52-based boards relies on the Arduino bootloader. + +The process of converting the bootloader only needs to be performed once. This conversion requires the use of either a [DAPLink](https://daplink.io/) or [J-Link](https://www.segger.com/products/debug-probes/j-link/). The most reasonably priced and avaliable is the [RAKDAP1](https://store.rakwireless.com/products/daplink-tool). 1. Install [Python](https://www.python.org/downloads/) 2. Install [pyOCD](https://pyocd.io/) - -```shell -pip3 install pyocd -``` - + ```shell + pip3 install pyocd + ``` 3. Download the required bootloader: [WisCore_RAK4631_Board_Bootloader.hex](https://github.com/RAKWireless/WisBlock/releases/download/0.4.2/WisCore_RAK4631_Board_Bootloader.hex) 4. Connect the RAKDAP as follows: [](/img/rak4631-rakdap1.png) 5. Flash the bootloader - -```shell -pyocd flash -t nrf52840 .\WisCore_RAK4631_Board_Bootloader.hex -``` - -6. Continue with the [normal instructions](/docs/getting-started/flashing-firmware/nrf52/flashing-nrf52) + ```shell + pyocd flash -t nrf52840 .\WisCore_RAK4631_Board_Bootloader.hex + ``` +6. Continue with the normal [flashing instructions](/docs/getting-started/flashing-firmware/nrf52/drag-n-drop) Alternate methods of flashing are outlined [here](https://github.com/RAKWireless/WisBlock/tree/master/bootloader/RAK4630). \ No newline at end of file diff --git a/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx b/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx index 02776928..669150f2 100644 --- a/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/python-flasher.mdx @@ -2,7 +2,7 @@ id: meshtastic-flasher-nrf52 title: Using Python Meshtastic Flasher sidebar_label: Python Flasher -sidebar_position: 1 +sidebar_position: 2 --- import MFlasher from '../../../software/python/meshtastic-flasher.mdx' diff --git a/docs/getting-started/serial-drivers/index.mdx b/docs/getting-started/serial-drivers/index.mdx index 329ff078..43d44365 100644 --- a/docs/getting-started/serial-drivers/index.mdx +++ b/docs/getting-started/serial-drivers/index.mdx @@ -8,27 +8,25 @@ sidebar_position: 1 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +:::caution +Make sure not to power the radio on without first attaching the antenna! You 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 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. +Verify that you have a **data cable** and _not_ a **charging _only_ cable** before proceeding. 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. -Once you've located a data cable, check the following to see if you need to install a driver to communicate with your device. +Once you've located a working data cable, [test for driver installation](/docs/getting-started/serial-drivers/#test-for-driver-installation) 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. -::: +If you know you have installed the correct driver, the following step can be used to check if you have a proper 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. +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: -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 do not 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. +_select your operating system below_ -Connect your Meshtastic device to your USB port, open a `Terminal` and enter the following command: -```shell -lsusb -``` +1. Connect your Meshtastic device to your USB port +2. Open a **Terminal** and enter the following command: -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)`. + ```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) + ``` -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. +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` - - + + -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. +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)` - + + +If you can see your device, you are ready to flash the firmware. Skip to the [Flashing Firmware](/docs/getting-started/flashing-firmware/) section. + +If you do not see your device after performing the check: + +1. You may be using a charging-only cable. +2. You may need to install the USB serial driver corrosponding to your device ([ESP32](/docs/getting-started/serial-drivers/installing-esp32-serial-drivers) or [NRF52](/docs/getting-started/serial-drivers/installing-nrf52-serial-drivers)). \ No newline at end of file diff --git a/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx b/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx index f9b59358..064523ed 100644 --- a/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx +++ b/docs/getting-started/serial-drivers/serial-drivers-esp32.mdx @@ -30,7 +30,6 @@ values={[ - - [CP210X USB to UART bridge - Download](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) @@ -38,7 +37,6 @@ values={[ - - [CP210X USB to UART bridge - Download](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) diff --git a/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx b/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx index c0d92e2a..50193a85 100644 --- a/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx +++ b/docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx @@ -8,10 +8,6 @@ sidebar_position: 2 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -:::important -Reboot your computer after you have installed the driver to complete the installation. -::: - ## Install NRF52 USB to Serial Drivers - [CH9102 Driver - MacOS Download](https://github.com/WCHSoftGroup/ch34xser_macos) - - - - -- [CH9102 Driver - Windows Download](http://www.wch-ic.com/downloads/CH341SER_EXE.html) - - - - - -## Remove the CH34x USB Driver (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: +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) + If you have already downloaded/installed the MacOS WCH-IC CH340/CH341 ("CH341SER_MAC") drivers via the CH34x_Install_V1.5.pkg, you will have to Uninstall the kernel extension: @@ -58,4 +52,16 @@ Uninstall the kernel extension: 3. `sudo rm -rf /Library/Extensions/usbserial.kext` 4. Reboot + + + +- [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. +::: + + + + \ No newline at end of file diff --git a/docs/hardware/supported/heltec.mdx b/docs/hardware/supported/heltec.mdx index f2bb792c..16f223fe 100644 --- a/docs/hardware/supported/heltec.mdx +++ b/docs/hardware/supported/heltec.mdx @@ -23,7 +23,6 @@ Using this device with a battery is not recommended. - Reset and Program switches - No GPS - - Firmware file: `firmware-heltec-1.x.x.bin` [](/img/hardware/heltec-v2.png) diff --git a/docs/hardware/supported/techo.mdx b/docs/hardware/supported/techo.mdx index 98dedeaf..d00e7655 100644 --- a/docs/hardware/supported/techo.mdx +++ b/docs/hardware/supported/techo.mdx @@ -7,7 +7,7 @@ sidebar_position: 2 The T-Echo is the latest device to be release by LILYGO® supporting a low power consumption microcontroller. -### See [Getting Started](/docs/getting-started/flashing-firmware/nrf52/flashing-nrf52) +### See [Getting Started](/docs/getting-started/flashing-firmware/nrf52/) - firmware file: `firmware-t-echo-1.x.x.uf2` - [Purchase link](https://www.aliexpress.com/item/1005002842456390.html) diff --git a/docs/software/python/cli/development.mdx b/docs/software/python/cli/development.mdx index b88ac473..1d7525e5 100644 --- a/docs/software/python/cli/development.mdx +++ b/docs/software/python/cli/development.mdx @@ -6,7 +6,7 @@ sidebar_label: Development ## 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 do not change formatting on lines you have not changed yourself. +We use the Visual Studio Code (VScode) 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 do not change formatting on lines you have not changed yourself. If you need to build a new release you will need: @@ -42,7 +42,7 @@ Possible options for testing: pytest -vv ``` -- To run just unit tests: +**Run just unit tests** ``` pytest @@ -52,13 +52,13 @@ pytest -m unit make ``` -- To run just integration tests: +**Run just integration tests** ``` pytest -m int ``` -- To run the smoke test with only one device connected serially (aka smoke1): +**Run the smoke test with only one device connected serially (aka smoke1)** ``` pytest -m smoke1 @@ -67,31 +67,35 @@ pytest -m smoke1 CAUTION: Running smoke1 will reset values on the device, including the region to 1 (US). Be sure to hit the reset button on the device after the test is completed. -- To run the smoke test with only two device connected serially (aka smoke2): +**Run the smoke test with only two device connected serially (aka smoke2)** ``` pytest -m smoke2 ``` -- To run the wifi smoke test: +**Run the wifi smoke test** ``` pytest -m smokewifi ``` -- To run a specific test: +**Run a specific test** ``` pytest -msmoke1 meshtastic/tests/test_smoke1.py::test_smoke1_info + # or to run a specific smoke2 test pytest -m smoke2 meshtastic/tests/test_smoke2.py::test_smoke2_info + # or to run a specific smoke_wifi test pytest -m smokewifi meshtastic/tests/test_smoke_wifi.py::test_smokewifi_info ``` -- To add another classification of tests such as "unit" or "smoke1", see [pytest.ini](https://github.com/meshtastic/Meshtastic-python/blob/master/pytest.ini). +**Add another classification of tests such as "unit" or "smoke1"** -- To see the unit test code coverage: +See [pytest.ini](https://github.com/meshtastic/Meshtastic-python/blob/master/pytest.ini). + +**To see the unit test code coverage** ``` pytest --cov=meshtastic @@ -101,7 +105,7 @@ pytest --cov-report html --cov=meshtastic make cov ``` -- To see slowest unit tests, you can run: +**To see slowest unit tests, you can run** ``` pytest --durations=0 @@ -109,8 +113,24 @@ pytest --durations=0 make slow ``` -See the [API documentation](https://python.meshtastic.org) or you can generate them locally by running: +**Generate the Python API documentation** + +Pre-generated: [API documentation](https://python.meshtastic.org) ``` bin/regen-docs.sh ``` + +## Wire encoding + +When sending protobuf packets over serial or TCP each packet is preceded by uint32 sent in network byte order (big endian). +The upper 16 bits must be 0x94C3. The lower 16 bits are packet length (this encoding gives room to eventually allow quite large packets). + +Implementations validate length against the maximum possible size of a BLE packet (our lowest common denominator) of 512 bytes. If the +length provided is larger than that we assume the packet is corrupted and begin again looking for 0x4403 framing. + +The packets flowing towards the device are ToRadio protobufs, the packets flowing from the device are FromRadio protobufs. +The 0x94C3 marker can be used as framing to (eventually) resync if packets are corrupted over the wire. + +Note: the 0x94C3 framing was chosen to prevent confusion with the 7 bit ascii character set. It also doesn't collide with any valid utf8 encoding. This makes it a bit easier to start a device outputting regular debug output on its serial port and then only after it has received a valid packet from the PC, turn off unencoded debug printing and switch to this +packet encoding. diff --git a/docs/software/python/meshtastic-flasher.mdx b/docs/software/python/meshtastic-flasher.mdx index aa524410..31441b78 100644 --- a/docs/software/python/meshtastic-flasher.mdx +++ b/docs/software/python/meshtastic-flasher.mdx @@ -20,9 +20,7 @@ The following operating systems are currently supported: Windows, Mac, and Ubunt ## Prerequisites -### Verify `python3` is installed - -#### Check `python3` version +### Verify that Python3 is installed -
- -Install/Update `python3` - +### Install or Update Python3 + - [Download directly from python.org](https://www.python.org/downloads/macos/) -- [Homebrew](https://brew.sh/) +- [Homebrew](https://brew.sh/): `brew install python@3.9` - [MacPorts](https://www.macports.org/) @@ -93,15 +89,12 @@ sudo apt install -y python3 python3-pip python3-venv -
### Install App - -For windows there is an [executable file](https://github.com/meshtastic/Meshtastic-gui-installer/releases/tag/untagged-9a69e6946635cd38df7d) that will manage installing python and flasher updates for you. +For **Windows**, the [installer](https://github.com/meshtastic/Meshtastic-gui-installer/releases/tag/untagged-9a69e6946635cd38df7d) will manage installing python and flasher updates automatically. -For MacOS and Linux it is recommended that you install using `pip` - +For **MacOS** and **Linux**, it is recommended that you install using `pip`. - - ## Flashing the Device -The Meshtastic Flasher will flash the latest firmware to esp32 and nrf52 devices. This is a newly developed application (as of February 1, 2022), so there may be some issues discovered as it is tested by users. +The Meshtastic Flasher will flash the latest firmware on esp32 and nrf52 devices. This is a newly developed application (as of February 1, 2022), so there may be some issues discovered as it is tested by users. There are three steps: -- Click the "GET VERSIONS" button to get the versions available (from GitHub). -- Click the "DETECT DEVICE" button to determine the port and device variant connected. -- Click the "FLASH" button to flash the version selected, using the port selected to the device. +1. Click the **GET VERSIONS** button to get the versions available (from GitHub). +2. Click the **DETECT DEVICE** button to determine the port and device variant connected. +3. Click the **FLASH** button to flash the version selected using the port selected to the device. ## Issues? @@ -202,5 +193,5 @@ The code can be found at the [Meshtastic-gui-installer repo](https://github.com/ 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 +- 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.