revamp refinements

This commit is contained in:
sigmahour 2022-11-03 20:10:08 -04:00
parent 3b5336f231
commit eac740b05b
66 changed files with 153 additions and 61 deletions

View file

@ -291,7 +291,7 @@ Initial Requirements:
### Meshtastic channel configuration
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/mesh/radio-settings#pre-defined).
Don't use this on the "Long Range / Slow" or "Long Range / Fast" channel settings. You're welcome to try and report back, but those channels have a [very low bitrate](/docs/about/overview/radio-settings#pre-defined).
Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast".

View file

@ -2,7 +2,7 @@
title: Community Guide
sidebar_label: Contributing
slug: /contributing
sidebar_position: 2
sidebar_position: 3
---
Meshtastic is a team of volunteers, and as such there is always plenty of ways to help. This project gets great contributions from people in their off hours. Those contributors work on the features they are interested in. It is a very open and welcoming developer community, and we are always looking for help to improve Meshtastic.

View file

@ -98,7 +98,7 @@ Push the left PWR button for about 1 second.
### Where do I purchase the device hardware?
Each [supported device](/docs/hardware/supported/tbeam) has a "Purchase Link".
Each [supported device](/docs/hardware/devices/tbeam) has a "Purchase Link".
### I have my hardware. How do I install the firmware and any required drivers?
@ -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/firmware/module-api).
API documentation for creating modules is available [here](/docs/development/module-api).

View file

@ -11,7 +11,8 @@ Meshtastic® is a project that enables you to use inexpensive LoRa radios as a l
### Features
- No phone required for node to node communication.
- Long range ([_166km record by Puzzled Pancake_](/docs/about/overview/field-tests/range/#current-record))
- No phone required for node to node communication
- Encrypted communication
- Excellent battery life (LoRa radios have a very low power draw)
- Send and receive text messages between members of the mesh
@ -26,13 +27,17 @@ The radios automatically rebroadcast messages they receive in order to create a
Radios can be paired to a single phone so that your friends and family are able to address a message to your specific radio. Each device supports a connection from a single user at a time.
<!--- FIXME: too technical for intro ?
When you send a message on your Meshtastic companion app, it is relayed to the radio using Bluetooth. That message is then broadcast by the radio three times over a certain interval in order to create redundancy for lost packets.
If you are interested in a more technical overview of how Meshtastic works, visit the overview section below:
When a receiving radio captures a packet, it checks to see if it has heard that message before. If it has it ignores the message. If it hasn't heard the message, it will rebroadcast it at a certain interval three times.
<div className="indexCtasBody">
<Link
className={'button button--outline button--lg cta--button'}
to={'/docs/overview'}
>
Overview
</Link>
</div>
For each message a radio rebroadcasts, it marks the "hop limit" down by one. When a radio receives a packet with a hop limit of zero, it will not rebroadcast the message.
--->
## Contributors

View file

@ -2,6 +2,7 @@
id: encryption
title: Meshtastic Encryption
sidebar_label: Encryption
sidebar_position: 2
---
Cryptography is tricky, so we've tried to 'simply' apply standard crypto solutions to our implementation. However, the project developers are not cryptography experts. Therefore we ask two things:

View file

@ -0,0 +1,25 @@
---
title: Range Tests
sidebar_label: Range Tests
sidebar_position: 1
---
## Current Record
- **Range:** 166km (103 miles)
- **Record Holder:** _Puzzled Pancake_
- **Firmware Version:** 1.2
- **Frequency:** 868MHz
- **Bandwidth:** 125
- **Spread Factor:** 12
- **Coding Rate:** 4/8
- **Devices 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)
- **Antenna:** Omnidirectional
![Topographical Map](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/a/a0a26e4d40a5b9ccba9185eb70e2eaf66f0b0587_2_1380x888.jpeg)
![Node A](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/9/99ec4bcc18b21f4e95ac1bcc0592b608c9c4f567_2_1332x1000.jpeg)
![Node B](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/1/1c8bd5fc41f7bab925404b657a9c481882de9313_2_1332x1000.jpeg)

View file

@ -0,0 +1,14 @@
---
title: Overview
sidebar_label: Overview
slug: /overview
sidebar_position: 2
---
## How it works
When you send a message on your Meshtastic companion app, it is relayed to the radio using Bluetooth. That message is then broadcast by the radio three times over a certain interval in order to create redundancy for lost packets.
When a receiving radio captures a packet, it checks to see if it has heard that message before. If it has it ignores the message. If it hasn't heard the message, it will rebroadcast it at a certain interval three times.
For each message a radio rebroadcasts, it marks the "hop limit" down by one. When a radio receives a packet with a hop limit of zero, it will not rebroadcast the message.

View file

@ -50,7 +50,7 @@ This layer is conventional non-reliable LoRa packet transmission. The transmitte
- **Packet Header - Unique ID:** The ID is a large, 32 bit ID to ensure there is enough unique state to protect an encrypted payload from attack.
- **Payload:** An encrypted and packed protobuf encoding of the SubPacket protobuf. Only the SubPacket is encrypted, while headers are not. This allows the option of eventually allowing nodes to route packets without knowing anything about the encrypted payload. For more information, see the [encryption](/docs/mesh/encryption) and [protobufs](/docs/protobufs/api) documentation. Any data past the maximum length is truncated.
- **Payload:** An encrypted and packed protobuf encoding of the SubPacket protobuf. Only the SubPacket is encrypted, while headers are not. This allows the option of eventually allowing nodes to route packets without knowing anything about the encrypted payload. For more information, see the [encryption](/docs/about/overview/encryption) and [protobufs](/docs/protobufs/api) documentation. Any data past the maximum length is truncated.
#### Carrier-Sense Multiple Access with Collision Avoidance (CSMA/CA)

View file

@ -2,6 +2,7 @@
id: radio-settings
title: Radio Settings
sidebar_label: Radio Settings
sidebar_position: 3
---
We use the same channel maps as LoRaWAN (though this is not LoRaWAN).

View file

@ -1,7 +1,7 @@
label: Mesh
label: Configuration
collapsible: true
position: 5
position: 4
link:
type: generated-index
title: The Mesh
title: Configuration
slug: /settings

View file

@ -1,9 +1,9 @@
---
id: config
title: Configuration
sidebar_label: Config
title: Device Configuration
sidebar_label: Device Config
slug: /settings/config
sidebar_position: 2
sidebar_position: 1
---
There are several config sections in the Meshtastic firmware, these are broken out so they can be sent as small admin messages over the mesh.

View file

@ -1,5 +1,5 @@
---
id: device-remote-admin
id: remote-admin
title: Remote Node Administration
sidebar_label: Remote Nodes
---

View file

@ -1,6 +1,6 @@
position: 6 # float position is supported
label: Development
collapsible: true # make the category collapsible
collapsible: true
position: 7
link:
type: generated-index
title: Developers

View file

@ -1,7 +1,8 @@
---
id: android
title: Creating a build/development environment for the Android App
title: Building the Android App
sidebar_label: Android
sidebar_position: 1
---
## Build instructions
@ -11,12 +12,11 @@ If you would like to develop this application we'd love your help! These build i
- Use Android Studio to build/debug
- Use `git submodule update --init --recursive` to pull in the various submodules we depend on
- There are a few config files which you'll need to copy from templates included in the project. Run the following commands to do so:
```
rm ./app/google-services.json
cp ./app/google-services-example.json ./app/google-services.json
rm ./app/src/main/res/values/curfirmwareversion.xml
cp ./app/special/curfirmwareversion.xml ./app/src/main/res/values/
```sh
rm ./app/google-services.json
cp ./app/google-services-example.json ./app/google-services.json
rm ./app/src/main/res/values/curfirmwareversion.xml
cp ./app/special/curfirmwareversion.xml ./app/src/main/res/values/
```
- Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator.
@ -30,14 +30,14 @@ The emulators don't support Bluetooth, so some features can not be used in that
- Analytics are included but can be disabled by the user on the settings screen
- On dev devices
```shell
```sh
adb shell setprop debug.firebase.analytics.app com.geeksville.mesh
adb shell setprop log.tag.FirebaseCrashlytics DEBUG
```
for verbose logging:
```shell
```sh
adb shell setprop log.tag.FA VERBOSE
```

View file

@ -3,5 +3,4 @@ collapsible: true
position: 1
link:
type: generated-index
title: Device
slug: /device
title: Device

View file

@ -4,7 +4,7 @@ title: Client API (Serial/TCP/BLE)
sidebar_label: Client API
---
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/firmware/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/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.

View file

@ -2,7 +2,7 @@
id: documentation
title: Maintaining Documentation
sidebar_label: Documentation
sidebar_position: 3
sidebar_position: 9
---
Meshtastic documentation is an important ingredient to the overall project. We want users to hit the ground running with the information they need right at their finger tips. This section will discuss the documentation software stack, file organization, and style guides.

View file

@ -4,10 +4,6 @@ title: Publishing Meshtastic.org
sidebar_label: Publish Meshtastic.org
---
This document is a WIP.
If youd like to do real releases with your changes, the procedure is:
## Device
- Update protobufs

View file

@ -1,12 +1,12 @@
---
id: build
title: Creating a build environment
title: Building Meshtastic Firmware
sidebar_label: Building Meshtastic
---
Meshtastic uses the [PlatformIO](https://platformio.org) development environment, that enables easy multiplatform development and centralized tooling.
Meshtastic uses [PlatformIO](https://platformio.org), a development environment that enables easy multi-platform development and centralized tooling.
## Setup
## Setup the build environment
1. Install PlatformIO, following the instructions available [here](https://platformio.org/platformio-ide).

View file

@ -1,7 +1,7 @@
---
id: oled-l10n-guide
title: OLED localization guide
sidebar_label: OLED localization
title: OLED Localization Guide
sidebar_label: OLED Localization
---
# OLED localization guide

View file

@ -1,7 +1,7 @@
---
id: portnum
title: Meshtastic port numbers
sidebar_label: Port numbers
title: Meshtastic Port Numbers
sidebar_label: Port Numbers
---
For any new apps that run on the device or via sister apps on phones/PCs they should pick and use a unique 'portnum' for their application.

View file

@ -2,6 +2,7 @@
id: module-api
title: Module API
sidebar_label: Module API
sidebar_position: 7
---
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.

View file

@ -0,0 +1,6 @@
label: Reference Material
collapsible: true
position: 20
link:
type: generated-index
title: Reference Material

View file

@ -2,7 +2,7 @@
id: protobuf-api
title: Protobuf API Reference
slug: /protobufs/api
sidebar_label: Protobuf Reference
sidebar_label: Protobufs
sidebar_position: 20
---
@ -305,6 +305,7 @@ Display Config
| compass_north_top | bool | If this is set, the displayed compass will always point north. if unset, the old behaviour (top of display is heading direction) is used. |
| flip_screen | bool | Flip screen vertically, for cases that mount the screen upside down |
| units | [`Config.DisplayConfig.DisplayUnits`](#configdisplayconfigdisplayunits) | Perferred display units |
| oled | [`Config.DisplayConfig.OledType`](#configdisplayconfigoledtype) | Override auto-detect in screen |
@ -481,6 +482,22 @@ How the GPS coordinates are displayed on the OLED screen.
### Config.DisplayConfig.OledType
:::note `enum` description
Override OLED outo detect with this if it fails.
:::
| Name | Number | Description |
| ---- | ------ | ----------- |
| `OLED_AUTO` | `0` | Default / Auto |
| `OLED_SSD1306` | `1` | Default / Auto |
| `OLED_SH1106` | `2` | Default / Auto |
### Config.LoRaConfig.ModemPreset
:::note `enum` description
@ -840,12 +857,12 @@ The other fields are either not sent at all, or sent in the special 16 byte LORA
| Field | Type | Description |
| ----- | ---- | ----------- |
| from | fixed32 | The sending node number. Note: Our crypto implementation uses this field as well. See [crypto](/docs/mesh/encryption) for details. FIXME - really should be fixed32 instead, this encoding only hurts the ble link though. |
| from | fixed32 | The sending node number. Note: Our crypto implementation uses this field as well. See [crypto](/docs/about/overview/encryption) for details. FIXME - really should be fixed32 instead, this encoding only hurts the ble link though. |
| to | fixed32 | The (immediatSee Priority description for more details.y should be fixed32 instead, this encoding only hurts the ble link though. |
| channel | uint32 | (Usually) If set, this indicates the index in the secondary_channels table that this packet was sent/received on. If unset, packet was on the primary channel. A particular node might know only a subset of channels in use on the mesh. Therefore channel_index is inherently a local concept and meaningless to send between nodes. Very briefly, while sending and receiving deep inside the device Router code, this field instead contains the 'channel hash' instead of the index. This 'trick' is only used while the payload_variant is an 'encrypted'. |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.decoded | [`Data`](#data) | TODO: REPLACE |
| [**oneof**](https://developers.google.com/protocol-buffers/docs/proto3#oneof) payload_variant.encrypted | bytes | TODO: REPLACE |
| id | fixed32 | A unique ID for this packet. Always 0 for no-ack packets or non broadcast packets (and therefore take zero bytes of space). Otherwise a unique ID for this packet, useful for flooding algorithms. ID only needs to be unique on a _per sender_ basis, and it only needs to be unique for a few minutes (long enough to last for the length of any ACK or the completion of a mesh broadcast flood). Note: Our crypto implementation uses this id as well. See [crypto](/docs/mesh/encryption) for details. FIXME - really should be fixed32 instead, this encoding only hurts the ble link though. |
| id | fixed32 | A unique ID for this packet. Always 0 for no-ack packets or non broadcast packets (and therefore take zero bytes of space). Otherwise a unique ID for this packet, useful for flooding algorithms. ID only needs to be unique on a _per sender_ basis, and it only needs to be unique for a few minutes (long enough to last for the length of any ACK or the completion of a mesh broadcast flood). Note: Our crypto implementation uses this id as well. See [crypto](/docs/about/overview/encryption) for details. FIXME - really should be fixed32 instead, this encoding only hurts the ble link though. |
| rx_time | fixed32 | The time this message was received by the esp32 (secs since 1970). Note: this field is _never_ sent on the radio link itself (to save space) Times are typically not sent over the mesh, but they will be added to any Packet (chain of SubPacket) sent to the phone (so the phone can know exact time of reception) |
| rx_snr | float | Never* sent over the radio links. Set during reception to indicate the SNR of this packet. Used to collect statistics on current link quality. |
| hop_limit | uint32 | If unset treated as zero (no forwarding, send to adjacent nodes only) if 1, allow hopping through one node, etc... For our usecase real world topologies probably have a max of about 3. This field is normally placed into a few of bits in the header. |

View file

@ -1,6 +1,6 @@
---
id: web-development-software
title: Information for developers of the web interface
title: Development Overview of the Web Interface
sidebar_label: Web Interface
sidebar_position: 4
---

View file

@ -18,9 +18,9 @@ If your ESP32 device does not have Meshtastic pre-installed flashing
Before you flash your device start by verifying 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.
:::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.
The [T-Beam 0.7](/docs/hardware/devices/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.
`firmware-tbeam0.7-1.x.x.bin` is the correct firmware. `firmware-tbeam-1.x.x.bin` is incompatible. For all other [T-Beam](/docs/hardware/supported/tbeam) boards `firmware-tbeam-1.x.x.bin` is the correct selection.
`firmware-tbeam0.7-1.x.x.bin` is the correct firmware. `firmware-tbeam-1.x.x.bin` is incompatible. For all other [T-Beam](/docs/hardware/devices/tbeam) boards `firmware-tbeam-1.x.x.bin` is the correct selection.
:::
## Command Line Interface Instructions

View file

@ -0,0 +1,7 @@
label: Guides
collapsible: true
position: 3
link:
type: generated-index
title: Guides
slug: guides

10
docs/guides/link-mqtt.mdx Normal file
View file

@ -0,0 +1,10 @@
---
id: setup-mqtt
title: Configuring MQTT
sidebar_label: Setup MQTT
sidebar_position: 1
---
import MFlasher from '../software/mqtt/index.mdx'
<MFlasher components={props.components} />

View file

@ -0,0 +1,10 @@
---
id: remote-nodes
title: Remote Node Administration
sidebar_label: Administer Remote Nodes
sidebar_position: 1
---
import MFlasher from '../configuration/remote-admin.mdx'
<MFlasher components={props.components} />

View file

@ -1,7 +1,7 @@
label: Hardware
collapsible: true
position: 3
position: 5
link:
type: generated-index
title: Hardware
title: Supported Hardware
slug: hardware

View file

@ -1,4 +1,4 @@
label: 'Supported Devices'
label: Devices
collapsible: true
position: 1
link:

View file

@ -1,6 +1,6 @@
---
id: peripherals
title: Peripherals
title: A Note on Peripherals
sidebar_label: Peripherals
sidebar_position: 2
---
@ -60,7 +60,7 @@ If doing local testing, may want to change the speed of the channel at this time
meshtastic --info
```
4. Connect the remote device via USB (or use the [remote admin](/docs/mesh/device-remote-admin) feature to reach it through the mesh)
4. Connect the remote device via USB (or use the [remote admin](/docs/configuration/remote-admin) feature to reach it through the mesh)
5. Set it to join the gpio channel you created
```shell

View file

@ -10,7 +10,7 @@ sidebar_position: 9
This project is still pretty young but moving at a pretty good pace. Not all features are fully implemented in the current alpha builds.
- We don't make these devices and they haven't been tested by UL or the FCC. If you use them, you are experimenting and we can't promise they won't burn your house down ;-)
- The encryption implementation is good but see this list of [caveats](/docs/mesh/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
- The encryption implementation is good but see this list of [caveats](/docs/about/overview/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
## Legal FAQ

View file

@ -1,6 +1,6 @@
label: Software
collapsible: true
position: 4
position: 6
link:
type: generated-index
title: Software

View file

@ -2,7 +2,7 @@
id: protobuf-api
title: Protobuf API Reference
slug: /protobufs/api
sidebar_label: Protobuf Reference
sidebar_label: Protobufs
sidebar_position: 20
---

@ -1 +1 @@
Subproject commit b3dbf380761c0934085615825c1bf23f31ca4fd9
Subproject commit a0fe9ec8614cd27af7691869ccbd20c39e48a086

View file

@ -19,6 +19,6 @@ else \
fi
# remove old generated protos
rm -rf "${PROJECT_BASE}/docs/developers/Protobufs/*"
rm -rf "${PROJECT_BASE}/docs/development/reference/protobuf-api.mdx"
protoc --doc_opt="${PROJECT_BASE}/protobuf.tmpl,protobuf-api.mdx" --doc_out="${PROJECT_BASE}/docs/development/" --proto_path="${PROJECT_BASE}/protobufs" *.proto
protoc --doc_opt="${PROJECT_BASE}/protobuf.tmpl,protobuf-api.mdx" --doc_out="${PROJECT_BASE}/docs/development/reference/" --proto_path="${PROJECT_BASE}/protobufs" *.proto