From b1058a4b7bf8e59a570ba4bd6763a6bfe9dc9618 Mon Sep 17 00:00:00 2001 From: sigmahour <> Date: Fri, 4 Nov 2022 17:09:56 -0400 Subject: [PATCH] draft skeleton for getting started sections --- docs/about/faq.mdx | 2 +- docs/about/overview/range-test.mdx | 4 +- docs/blocks/_lora-regions.mdx | 15 +++ docs/configuration/device-config/lora.mdx | 18 +-- docs/development/device/client-api.mdx | 3 +- docs/development/device/error-codes.mdx | 1 + docs/development/device/http-api.mdx | 1 + docs/development/{ => device}/module-api.mdx | 2 +- docs/development/documentation/index.mdx | 8 +- .../connect-device/_category_.yml | 7 ++ .../connect-device/bluetooth.mdx | 10 ++ .../connect-device/network.mdx | 15 +++ .../getting-started/connect-device/serial.mdx | 10 ++ .../flashing-firmware/nrf52/drag-n-drop.mdx | 2 +- .../flashing-firmware/nrf52/index.mdx | 24 ---- docs/getting-started/index.mdx | 59 +++++++++- docs/getting-started/init-config.mdx | 103 ++++++++++++++++++ docs/getting-started/serial-drivers/index.old | 83 -------------- docs/guides/convert-rak4631r.mdx | 28 +++++ 19 files changed, 261 insertions(+), 134 deletions(-) create mode 100644 docs/blocks/_lora-regions.mdx rename docs/development/{ => device}/module-api.mdx (99%) create mode 100644 docs/getting-started/connect-device/_category_.yml create mode 100644 docs/getting-started/connect-device/bluetooth.mdx create mode 100644 docs/getting-started/connect-device/network.mdx create mode 100644 docs/getting-started/connect-device/serial.mdx create mode 100644 docs/getting-started/init-config.mdx delete mode 100644 docs/getting-started/serial-drivers/index.old create mode 100644 docs/guides/convert-rak4631r.mdx diff --git a/docs/about/faq.mdx b/docs/about/faq.mdx index 97fc93dc..0ff71476 100644 --- a/docs/about/faq.mdx +++ b/docs/about/faq.mdx @@ -205,4 +205,4 @@ A list of available modules is available [here](/docs/settings/moduleconfig). ### I'd like to write a module. How do I get started? -API documentation for creating modules is available [here](/docs/development/module-api). +API documentation for creating modules is available [here](/docs/development/device/module-api). diff --git a/docs/about/overview/range-test.mdx b/docs/about/overview/range-test.mdx index 41a6310c..bacdb967 100644 --- a/docs/about/overview/range-test.mdx +++ b/docs/about/overview/range-test.mdx @@ -13,9 +13,9 @@ sidebar_position: 1 - **Bandwidth:** 125 - **Spread Factor:** 12 - **Coding Rate:** 4/8 -- **Devices A:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam) +- **Device A:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam) - **Antenna:** Omnidirectional -- **Devices B:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam) +- **Device B:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam) - **Antenna:** Omnidirectional ![Topographical Map](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/a/a0a26e4d40a5b9ccba9185eb70e2eaf66f0b0587_2_1380x888.jpeg) diff --git a/docs/blocks/_lora-regions.mdx b/docs/blocks/_lora-regions.mdx new file mode 100644 index 00000000..cc38a110 --- /dev/null +++ b/docs/blocks/_lora-regions.mdx @@ -0,0 +1,15 @@ +| Region Code | Description | +| :-------: | :--------: | +| `UNSET` | Unset | +| `US` | United States | +| `EU_433` | European Union 433MHz | +| `EU_868` | European Union 868MHz | +| `CN` | China | +| `JP` | Japan | +| `ANZ` | Australia & New Zealand | +| `KR` | Korea | +| `TW` | Taiwan | +| `RU` | Russia | +| `IN` | India | +| `NZ_865` | New Zealand 865MHz | +| `TH` | Thailand | \ No newline at end of file diff --git a/docs/configuration/device-config/lora.mdx b/docs/configuration/device-config/lora.mdx index b0ea01ab..c222f028 100644 --- a/docs/configuration/device-config/lora.mdx +++ b/docs/configuration/device-config/lora.mdx @@ -7,6 +7,7 @@ sidebar_label: LoRa import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import LoRaRegions from '../../blocks/_lora-regions.mdx'; The LoRa config options are: Region, Modem Preset, Max Hops, Transmit Power, Bandwidth, Spread Factor, Coding Rate, Frequency Offset, Transmit Enabled and Ignore Incoming Array. LoRa config uses an admin message sending a `Config.LoRa` protobuf. @@ -19,22 +20,7 @@ You must set your device's `lora.region` setting. This will ensure that you are ### Region Sets the region for your node. Default is `unset`. -| Region Code | Description | -| :-------: | :---------------------------------------------------------------------------------------: | -| `UNSET` | Unset | -| `US` | United States | -| `EU_433` | European Union 433MHz | -| `EU_868` | European Union 868MHz | -| `CN` | China | -| `JP` | Japan | -| `ANZ` | Australia & New Zealand | -| `KR` | Korea | -| `TW` | Taiwan | -| `RU` | Russia | -| `IN` | India | -| `NZ_865` | New Zealand 865MHz | -| `TH` | Thailand | - + ### Modem Preset diff --git a/docs/development/device/client-api.mdx b/docs/development/device/client-api.mdx index 2e4fe522..08ccf623 100644 --- a/docs/development/device/client-api.mdx +++ b/docs/development/device/client-api.mdx @@ -2,9 +2,10 @@ id: client-api title: Client API (Serial/TCP/BLE) sidebar_label: Client API +sidebar_position: 1 --- -This document describes the protocol for external API clients using our devices. If you are interested in running your own code on the device itself, see the [module API](/docs/development/module-api) documentation instead. +This document describes the protocol for external API clients using our devices. If you are interested in running your own code on the device itself, see the [module API](/docs/development/device/module-api) documentation instead. The Device API is designed to have only a simple stream of ToRadio and FromRadio packets and all polymorphism comes from the flexible set of Google Protocol Buffers which are sent over the wire. We use protocol buffers extensively both for the Bluetooth API and for packets inside the mesh or when providing packets to other applications on the phone. diff --git a/docs/development/device/error-codes.mdx b/docs/development/device/error-codes.mdx index af1b332c..16031db8 100644 --- a/docs/development/device/error-codes.mdx +++ b/docs/development/device/error-codes.mdx @@ -2,6 +2,7 @@ id: error-codes title: Critical Error Codes sidebar_label: Error Codes +sidebar_position: 4 --- The device might report these fault codes on the screen, but it will also be outputted on the device serial output. If you encounter a fault code, please post on the forum and we'll try to help. diff --git a/docs/development/device/http-api.mdx b/docs/development/device/http-api.mdx index 62ff9b60..72ca9c42 100644 --- a/docs/development/device/http-api.mdx +++ b/docs/development/device/http-api.mdx @@ -2,6 +2,7 @@ id: http-api title: HTTP API sidebar_label: HTTP API +sidebar_position: 2 --- :::info diff --git a/docs/development/module-api.mdx b/docs/development/device/module-api.mdx similarity index 99% rename from docs/development/module-api.mdx rename to docs/development/device/module-api.mdx index 2da2ddd4..53abdb5b 100644 --- a/docs/development/module-api.mdx +++ b/docs/development/device/module-api.mdx @@ -2,7 +2,7 @@ id: module-api title: Module API sidebar_label: Module API -sidebar_position: 7 +sidebar_position: 3 --- This is a tutorial on how to write small modules which run on the device. Modules are bits of regular 'Arduino' code that can send and receive packets to other nodes/apps/PCs using our mesh. diff --git a/docs/development/documentation/index.mdx b/docs/development/documentation/index.mdx index e5eb9be5..6e7bc0ef 100644 --- a/docs/development/documentation/index.mdx +++ b/docs/development/documentation/index.mdx @@ -2,7 +2,7 @@ id: docs title: Maintaining Documentation slug: /development/docs -sidebar_label: Documentation +sidebar_label: Docs sidebar_position: 9 --- @@ -14,7 +14,7 @@ All of our documentation resides on GitHub. Instructions for setting up your Git Our documentation is powered by [Docusaurus](https://docusaurus.io) — a documentation platform built on React that utilizes markdown files. Because markdown files are easy to edit, most content changes should be fairly simple. -Another component that we use is [Vercel](https://vercel.com) — a platform for frontend frameworks and static sites. Instructions for setting up your instance of Vercel are located [here](/docs/development/documentation/publish#publish-to-vercel). +Another component that we use is [Vercel](https://vercel.com) — a platform for front-end frameworks and static sites. Instructions for setting up your instance of Vercel are located [here](/docs/development/documentation/publish#publish-to-vercel). ## Documentation Organization @@ -24,8 +24,8 @@ Another component that we use is [Vercel](https://vercel.com) — a platform for | Meshtastic Software | `docs/software` | Current bulk of documentation running through each Meshtastic project. | | Getting Started | `docs/getting-started` | Instructions on how to get the Meshtastic firmware onto a users device. | | Device Settings | `docs/software/settings` | Details each user setting and provides explanations for what the setting does and how to configure the device using the various clients available (Android, CLI, iOS, Web) | -| Hardware Details | `docs/hardware` | Any hardware related content. Any time a user is attaching a peripheral accessory to their device. That includes 3d printed cases, antennas, buttons, chimes, rotary encoders, and screens. | -| Radio Mesh Details | `docs/mesh` | This section discusses everything relating to the Meshtastic mesh. Mesh health metrics will be discussed here as well as topics such as signal strength, range and anyting else pertaining to "over the air". | +| Hardware Details | `docs/hardware` | Any hardware related content. Any time a user is attaching a peripheral accessory to their device. That includes 3D printed cases, antennas, buttons, chimes, rotary encoders, and screens. | +| Radio Mesh Details | `docs/mesh` | This section discusses everything relating to the Meshtastic mesh. Mesh health metrics will be discussed here as well as topics such as signal strength, range and anything else pertaining to "over the air". | | Contribute to Meshtastic | `docs/developers` | Details each of the projects and how they work together to give a developer an idea of how the Meshtastic ecosystem operates. | | About the Documentation | `docs/maintaining-documentation` | This section explains how our documentation is organized, how to make edits to the documentation, view a local copy of your fork of the project. Style guides and tips will also be included here. | | Legal | `docs/legal` | Any legal information. Most changes here will be handled by developers actually working on the projects that require any legal disclosures. Examples include: the Meshtastic trademark, terms of service, and privacy policy. | diff --git a/docs/getting-started/connect-device/_category_.yml b/docs/getting-started/connect-device/_category_.yml new file mode 100644 index 00000000..4890fb02 --- /dev/null +++ b/docs/getting-started/connect-device/_category_.yml @@ -0,0 +1,7 @@ +label: Connect to Device +collapsible: true +position: 3 +link: + type: generated-index + title: Connect to Device + slug: /getting-started/connect-device \ No newline at end of file diff --git a/docs/getting-started/connect-device/bluetooth.mdx b/docs/getting-started/connect-device/bluetooth.mdx new file mode 100644 index 00000000..b61d3f32 --- /dev/null +++ b/docs/getting-started/connect-device/bluetooth.mdx @@ -0,0 +1,10 @@ +--- +id: connect-ble +title: Connecting using Bluetooth +sidebar_label: Bluetooth +#pagination_next: /docs/getting-started +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; diff --git a/docs/getting-started/connect-device/network.mdx b/docs/getting-started/connect-device/network.mdx new file mode 100644 index 00000000..83b3f8d8 --- /dev/null +++ b/docs/getting-started/connect-device/network.mdx @@ -0,0 +1,15 @@ +--- +id: connect-network +title: Connecting over TCP/IP Network (ESP32 Only) +sidebar_label: Network (ESP32) +#pagination_next: /docs/getting-started +sidebar_position: 3 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +## WiFi + +## Ethernet \ No newline at end of file diff --git a/docs/getting-started/connect-device/serial.mdx b/docs/getting-started/connect-device/serial.mdx new file mode 100644 index 00000000..6bc98873 --- /dev/null +++ b/docs/getting-started/connect-device/serial.mdx @@ -0,0 +1,10 @@ +--- +id: connect-serial +title: Connecting using Serial +sidebar_label: Serial +#pagination_next: /docs/getting-started +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; 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 65ccd4c6..57726749 100644 --- a/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/drag-n-drop.mdx @@ -9,7 +9,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; :::info -Before flashing confirm that you have [RAK4631](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK4631/) and not a [RAK4631-R](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK4631-R/) If this is not the case, fear not. The hardware is identical but requires changing the bootloader. Instructions on how to do this are located [here](/docs/getting-started/flashing-firmware/nrf52/#convert-rak4631-r-to-rak4631). +Before flashing confirm that you have [RAK4631](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK4631/) and not a [RAK4631-R](https://docs.rakwireless.com/Product-Categories/WisBlock/RAK4631-R/) If this is not the case, fear not. The hardware is identical but requires changing the bootloader. Instructions on how to do this are located [here](/docs/guides/convert-rak4631r). ::: ## Upgrading from a previous version of Meshtastic diff --git a/docs/getting-started/flashing-firmware/nrf52/index.mdx b/docs/getting-started/flashing-firmware/nrf52/index.mdx index 753c2309..0b5e8473 100644 --- a/docs/getting-started/flashing-firmware/nrf52/index.mdx +++ b/docs/getting-started/flashing-firmware/nrf52/index.mdx @@ -11,27 +11,3 @@ The NRF52 based devices have the easiest firmware upgrade process. No driver or 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. - -## Convert RAK4631-R to RAK4631 - -The only difference between the _RAK4631-R_ (RUI3) and the _RAK4631_ (Arduino) is the bootloader it is shipped with - the hardware is the same. - -Meshtastic requires the Arduino bootloader on RAK WisBlock NRF52-based boards. 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 available 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 - ``` -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 [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/index.mdx b/docs/getting-started/index.mdx index f8037ebe..2f932b3d 100644 --- a/docs/getting-started/index.mdx +++ b/docs/getting-started/index.mdx @@ -33,7 +33,7 @@ The NRF52 is much more power efficient than the esp32 and easier to update, but If your device is not listed above, please review our [supported hardware](/docs/supported-hardware) devices to determine which MCU your device has or contact us in [Discord](https://discord.gg/ktMAKGBnBs) with any questions. ::: -## Connect Device +## 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._ @@ -144,8 +144,65 @@ For RAK4631 users, if you have a RAK4631-R (the RUI3 bootloader version of the R +## Connect to Device + +Depending on your device, there are 3 ways to connect to your device: + +### Serial + +
+ + Connect using Serial + +
+ + +### Bluetooth + +
+ + Connect using Bluetooth + +
+ +### Network + +Connecting over network is only supported on ESP32 devices. + +
+ + Connect over Network + +
+ + +## Configure Device + +The initial configuration of the device includes setting the regional settings... + +
+ + 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) diff --git a/docs/getting-started/init-config.mdx b/docs/getting-started/init-config.mdx new file mode 100644 index 00000000..f4984870 --- /dev/null +++ b/docs/getting-started/init-config.mdx @@ -0,0 +1,103 @@ +--- +title: Initial Configuration +sidebar_label: Initial Configuration +slug: /getting-started/initial-config +sidebar_position: 4 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import LoRaRegions from '../blocks/_lora-regions.mdx'; + + +## Connection Supported Clients + +Depending on your connection, some configuration options are not fully supported. Find out which Client is best for your type of connection. + + + + +- [Python CLI](/docs/software/python/cli/) +- [Web Client](https://client.meshtastic.org) + + + + + +- [Web Client](https://client.meshtastic.org) + + + + + +- [Web Client](https://client.meshtastic.org) + + + + + + +### Configure Regional Settings + + + + + + + + +:::info +Region and Modem Preset can be configured on Android. +::: + + + + +:::info +Configuration of Region, Modem Preset and Hop Limit is available on iOS, iPadOS and macOS at Settings > Radio Configuration > LoRa. +::: + + + + +```sh +meshtastic --set lora.region +``` + + + + +:::info +No LoRa config options are available in the Flasher. +::: + + + + +:::info +All LoRa config options are available in the Web UI. +::: + + + + + + + + diff --git a/docs/getting-started/serial-drivers/index.old b/docs/getting-started/serial-drivers/index.old deleted file mode 100644 index 43d44365..00000000 --- a/docs/getting-started/serial-drivers/index.old +++ /dev/null @@ -1,83 +0,0 @@ ---- -id: serial-drivers -title: Installing Serial Drivers -sidebar_label: Install Serial Drivers -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 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 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. - -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_ - - - - -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)` - - - - -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/guides/convert-rak4631r.mdx b/docs/guides/convert-rak4631r.mdx new file mode 100644 index 00000000..dacebba5 --- /dev/null +++ b/docs/guides/convert-rak4631r.mdx @@ -0,0 +1,28 @@ +--- +id: convert-rak4631r +title: Convert RAK4631-R to RAK4631 +sidebar_label: Convert RAK4631-R +sidebar_position: 4 +--- + +The only difference between the _RAK4631-R_ (RUI3) and the _RAK4631_ (Arduino) is the bootloader it is shipped with - the hardware is the same. + +Meshtastic requires the Arduino bootloader on RAK WisBlock NRF52-based boards. 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 available 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 + ``` +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 [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