mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2024-09-19 23:57:31 -07:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

cleanup and reformatting content

Browse source
This commit is contained in:
sigmahour 2022-11-07 23:53:52 -05:00
parent de2c96a9b9
commit 954634437f
46 changed files with 713 additions and 660 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/1.2-End-of-life/settings/store-and-forward-module.mdx
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/about/overview/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/overview/radio-settings#pre-defined).
Either use a custom channel configuration with at an at least 1kbit data rate or use "Medium Range / Fast".

36
docs/about/contributing.mdx
View file

@ -17,44 +17,46 @@ Meshtastic is a team of volunteers, and as such there is always plenty of ways t
There are several developers, testers, and active users on [Discord](https://discord.gg/ktMAKGBnBs).
## Meshtastic Ecosystem
There are many technologies (and repositories) used in creating the Meshtastic ecosystem. Below is a breakdown:
## Protocol buffers
### Protocol Buffers
Most communication and interactions happen with protocol buffers. The [Meshtastic Protobuf Definitions](https://github.com/meshtastic/protobufs) repo is where all of the protocol buffer changes happen. See the [Protobuf API Reference](/docs/developers/protobufs/api) for more details.
## Firmware
### Device Firmware
The [firmware](https://github.com/meshtastic/firmware) is where all of the firmware development happens. This is where the code for the ESP32 and nRF52 based devices is developed. It is mainly C and C++ code.Think Arduino. It is where the first level of hardware interaction begins and ends.
## Modules
### Firmware Modules
[Modules](/docs/settings/moduleconfig) are also implemented mainly in the firmware repo above. Typically, you would add functionality in the protobufs repo and the device repo to implement module functionality. You probably also want to have some client/device use/interact with the module and that is where the Device support comes into play.
## Device Support
### CLI Apps (Device Interface)
The [meshtastic/Meshtastic-python](https://github.com/meshtastic/Meshtastic-python) repository is typically where the first device interaction takes place, but that is not a requirement. This repo has a command line utility that allows you to interact with most functionality with the devices. This python library can also be consumed for other applications.
- **Meshtastic Python CLI** - The [meshtastic/Meshtastic-python](https://github.com/meshtastic/Meshtastic-python) repository is typically where the first device interaction takes place, but that is not a requirement. This repo has a command line utility that allows you to interact with most functionality with the devices. This python library can also be consumed for other applications.
## Web Application
### Web Apps (Device Interface)
The [meshtastic/web](https://github.com/meshtastic/web) repository is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web interface overview](/docs/software/web-client) for more details.
The [meshtastic/meshtastic.js](https://github.com/meshtastic/meshtastic.js) repository is a JavaScript library that provides an interface for Meshtastic devices.
- **Meshtastic Web** - The [meshtastic/web](https://github.com/meshtastic/web) repository is where the hosted web server on the ESP32 devices in Typescript is developed. See the [Web interface overview](/docs/software/web-client) for more details.
- **Meshtastic JS** - The [meshtastic/meshtastic.js](https://github.com/meshtastic/meshtastic.js) repository is a JavaScript library that provides an interface for Meshtastic devices.
@sachaw has been making tons of progress on the web app and would love help with:
* Saving of preferences
* Better loading state indicators
* Chat scroll lock
* Various module support
* Saving of preferences
* Better loading state indicators
* Chat scroll lock
* Various module support
## Phone Apps
### Mobile Apps (Device Interface)
There are two phone apps that interact with the Meshtastic devices:
- The [meshtastic/Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repository repo contains the Kotlin code for Android based interactions with Meshtastic devices. See [here](/docs/development/android) for how to build/create a development environment for the Meshtastic Android App.
- The iOS app is in the process of a complete re-write in Swift and will have the new repo published soon. Note: There are a couple of earlier implementations.
- **Android App** - The [meshtastic/Meshtastic-Android](https://github.com/meshtastic/Meshtastic-Android) repository repo contains the Kotlin code for Android based interactions with Meshtastic devices. See the [Android development instructions](/docs/development/android) on how to create a development environment and build the Meshtastic Android App.
- **Apple Apps** - The iOS applications are in the process of a complete re-write in Swift and will have the new repo published soon. Note: There are a couple of earlier implementations.
## Documentation
### Documentation
This website is in the [Meshtastic](https://github.com/meshtastic/meshtastic) repository.

8
docs/about/faq.mdx
View file

@ -126,16 +126,12 @@ Push the left PWR button for about 10 seconds.
### How can I tell the device not to sleep?
- Android instructions see: [Android Usage](/docs/software/android/android-usage#configuration-options)
- Android instructions see: [Android Usage](/docs/software/android/usage#configuration-options)
- Python CLI instructions see: [Python Usage](/docs/software/python/cli/usage#changing-settings)
### Why does only one RAK Meshtastic Starter kit show up in my node list?
There was a bug where Meshtastic Starter kits were sent out with the same MAC address. With a single MAC address the devices all report as being the same device. Without the battery connected, flash the starter kit device(s) to 1.2.59 and then do a factory reset, disconnect and reconnect the board and run `meshtastic --info`.
### Why does only one RAK Meshtastic Starter kit show up in my node list?
There was a bug where Meshtastic Starter kits were sent out with the same MAC address. With a single MAC address the devices all report as being the same device. Without the battery connected, flash the starter kit device(s) to 1.2.59 and then do a factory reset, disconnect and reconnect the board and run `meshtastic --info`.
There was a bug where Meshtastic Starter kits were sent out with the same MAC address. With a single MAC address the devices all report as being the same device. Without the battery connected, flash the starter kit device(s) to any firmware > 1.2.59 and then do a factory reset, disconnect and reconnect the board and run `meshtastic --info`.
<!-- HAM -->

21
docs/about/introduction.mdx
View file

@ -11,7 +11,7 @@ Meshtastic® is a project that enables you to use inexpensive LoRa radios as a l
### Features
- Long range ([_166km record by Puzzled Pancake_](/docs/about/overview/range-test#current-record))
- Long range ([_166km record by PuzzledPancake_](/docs/overview/range-tests#current-record))
- No phone required for mesh communication
- Encrypted communication
- Excellent battery life
@ -34,7 +34,7 @@ If you are interested in a more technical overview of how Meshtastic works, visi
className={'button button--outline button--lg cta--button'}
to={'/docs/overview'}
>
Overview
Technical Overview
</Link>
</div>
@ -42,10 +42,23 @@ If you are interested in a more technical overview of how Meshtastic works, visi
Meshtastic is an open source project available on GitHub. Our generous volunteers donate their personal time to write and maintain this codebase. If you would like to contribute see our [GitHub](https://github.com/meshtastic), join our [Discord server](https://discord.gg/ktMAKGBnBs), and read up on our [forum](https://meshtastic.discourse.group).
<div className="indexCtasBody">
<Link
className={'button button--outline button--lg cta--button'}
to={'/docs/contributing'}
>
Contribute!
</Link>
</div>
<!--- FIXME add Github organization list/contributor list --->
## Start using Meshtastic!
Hopefully your "Getting Started" experience is straight forward and headache free. If you encounter any issues, please consider updating our documentation to improve future user experiences or reach out on the forum or Discord.
Our support is 100% volunteer based. We are passionate about the project and hope to help newcomers become Meshtastic experts!
<div className="indexCtasBody">
<Link
className={'button button--outline button--lg cta--button'}
@ -54,7 +67,3 @@ Meshtastic is an open source project available on GitHub. Our generous volunteer
Getting Started
</Link>
</div>
Hopefully your "Getting Started" experience is straight forward and headache free. If you encounter any issues, please consider updating our documentation to improve future user experiences or reach out on the forum or Discord.
Our support is 100% volunteer based. We are passionate about the project and hope to help newcomers become Meshtastic experts!

3
docs/about/overview/encryption.mdx
View file

@ -2,7 +2,8 @@
id: encryption
title: Meshtastic Encryption
sidebar_label: Encryption
sidebar_position: 2
slug: /overview/encryption
sidebar_position: 3
---
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:

11
docs/about/overview/mesh-alg.mdx
View file

@ -1,8 +1,9 @@
---
id: mesh-alg
id: mesh-algo
title: Mesh Broadcast Algorithm
slug: /overview/mesh-algo
sidebar_label: Mesh Algorithm
sidebar_position: 1
sidebar_position: 2
---
## Current Algorithm
@ -25,7 +26,7 @@ This preamble allows receiving radios to synchronize clocks and start framing. W
This layer is conventional non-reliable LoRa packet transmission. The transmitted packet has the following representation before encoding for transmission:
| Offset | Length | Type | Usage |
| ------------ | ----------------------------- | ------- | ---------------------------------------------------------------------------------------- |
|:------------:|:-----------------------------:|:-------:|:---------------------------------------------------------------------------------------- |
| 0x00 | 1 byte | Integer | syncWord, always `0x2B`. |
| 0x01 | 4 bytes | Integer | Packet header: Destination. The destination's unique NodeID. `0xFFFFFFFF` for broadcast. |
| 0x05 | 4 bytes | Integer | Packet Header: Sender. The sender's unique NodeID. |
@ -37,7 +38,7 @@ This layer is conventional non-reliable LoRa packet transmission. The transmitte
#### Packet Header Flags
| Index | # of Bits | Usage |
| ------- | --------- | ------------------------------ |
|:-------:|:---------:|:------------------------------|
| 0 | 3 | HopLimit (see note in Layer 3) |
| 3 | 1 | WantAck |
| 4 .. 32 | 28 | Currently unused |
@ -50,7 +51,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/about/overview/encryption) and [protobufs](/docs/developers/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/overview/encryption) and [protobufs](/docs/developers/protobufs/api) documentation. Any data past the maximum length is truncated.
#### Carrier-Sense Multiple Access with Collision Avoidance (CSMA/CA)

89
docs/about/overview/radio-settings.mdx
View file

@ -1,67 +1,97 @@
---
id: radio-settings
title: Radio Settings
slug: /overview/radio-settings
sidebar_label: Radio Settings
sidebar_position: 3
sidebar_position: 1
---
We use the same channel maps as LoRaWAN (though this is not LoRaWAN).
(Note, not the same channel map as TTN for US frequencies.)
:::info
Meshtastic is **not** LoRaWAN, nor TTN (TheThingsNetwork). However, Meshtastic does use the same channel maps as LoRaWAN.
:::
![freq table](/img/LoRa-Frequency-Bands.jpg)
See [this site](https://www.rfwireless-world.com/Tutorials/LoRa-channels-list.html) for more information.
## LoRaWAN Europe Frequency Band
## Europe Frequency Bands
The maximum power allowed is +14dBm ERP (Effective Radiated Power, see [this site](https://en.wikipedia.org/wiki/Effective_radiated_power) for more information).
The maximum power allowed for Europe is +14dBm ERP ([Effective Radiated Power](https://en.wikipedia.org/wiki/Effective_radiated_power)).
### 433 MHz
There are eight channels defined with a 0.2 MHz gap between them.
Channel zero starts at 433.175 MHz
The band range is from 433 to 434 MHz.
### 870 MHz
There are eight channels defined with a 0.2 MHz gap between them. Channel zero starts at 433.175 MHz
There are eight channels defined with a 0.3 MHz gap between them.
Channel zero starts at 865.20 MHz
### 868 MHz (ISM Band)
## LoRaWAN for North America
The band range is from 863 to 870 MHz.
LoRaWAN defines 64, 125 kHz channels from 902.3 to 914.9 MHz increments.
There are eight channels defined with a 0.3 MHz gap between them. Channel zero starts at 865.20 MHz.
The maximum output power for North America is +30 dBm ERP.
|Channel Number| Center Frequency|
|:---:|:---:|
| 10 |865.20 MHz|
| 11 |865.50 MHz|
| 12 |865.80 MHz|
| 13 |866.10 MHz|
| 14 |866.40 MHz|
| 15 |866.70 MHz|
| 16 |867 MHz|
| 17 |868 MHz|
The band is from 902 to 928 MHz. It mentions channel number and its respective channel frequency. All the 13 channels are separated by 2.16 MHz with respect to the adjacent channels.
Channel zero starts at 903.08 MHz center frequency.
## North America Frequency Bands
## Data-rates
The maximum output power for North America is +30 dBm ERP ([Effective Radiated Power](https://en.wikipedia.org/wiki/Effective_radiated_power)).
### About
### 915 MHz (ISM Band)
Various data-rates are selectable when configuring a channel and are inversely proportional to the theoretical range of the devices.
The band range is from 902 to 928 MHz.
Considerations:
There are thirteen channels defined with a 2.16 MHz gap between them. Channel zero starts at 903.08 MHz.
- Spreading Factor - How much we "spread" our data over time.
|Channel Number| Center Frequency|
|:---:|:---:|
| 00 |903.08 MHz|
| 01 |905.24 MHz|
| 02 |907.40 MHz|
| 03 |909.56 MHz|
| 04 |911.72 MHz|
| 05 |913.88 MHz|
| 06 |916.04 MHz|
| 07 |918.20 MHz|
| 08 |920.36 MHz|
| 09 |922.52 MHz|
| 10 |924.68 MHz|
| 11 |926.84 MHz|
| 12 |915 MHz|
## Data Rates
### Considerations
Various data-rate options are available when configuring a channel and are inversely proportional to the theoretical range of the devices.
- **Spreading Factor** - How much we "spread" our data over time.
- Each step up in Spreading Factor doubles the airtime to transmit.
- Each step up in Spreading Factor adds about 2.5db extra link budget.
- Bandwidth - How big of a slice of the spectrum we use.
- **Bandwidth** - How big of a slice of the spectrum we use.
- Each doubling of the bandwidth is almost 3db less link budget.
- Bandwidths less than 31 may be unstable unless you have a high quality Crystal Oscillator.
- Coding Rate - How much redundancy we encode to resist noise.
- **Coding Rate** - How much redundancy we encode to resist noise.
- Increasing coding rate increases reliability while decreasing data-rate.
- 4/5 - 1.25x overhead
- 4/6 - 1.5x overhead
- 4/7 - 1.75x overhead
- 4/8 - 2x overhead
### Pre-Defined
### Predefined Channels
We have six predefined channels. These are the most common settings and have been proven to work well:
| Channel setting | Alt Channel Name | Data-rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget |
| :------------------ | :--------------- | :------------------ | :----------- | :---------- | :-------- | :---------- |
| Channel setting | Alt Channel Name | Data-Rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget |
| :------------------: | :---------------: | :------------------: | :-----------: | :----------: | :--------:| :---------- :|
| Short Range / Fast | Short Fast | 6.8 kbps | 7 / 128 | 4/8 | 250 | 137dB |
| Short Range / Slow | Short Slow | 3.9 kbps | 8 / 256 | 4/8 | 250 | 140dB |
| Medium Range / Fast | Medium Fast | 2.2 kbps | 9 / 512 | 4/8 | 250 | 143dB |
@ -70,7 +100,10 @@ We have six predefined channels. These are the most common settings and have bee
| Long Range / Slow | Long Slow | 0.18 kbps | 12 / 4096 | 4/8 | 125 | 154dB |
| Very Long Range - Slow | Very Long Slow | 0.05 kbps | 12 / 4096 | 4/8 | 31.25 | 160.1dB |
Note: The link budget used by these calculations assumes a transmit power of 17dBm and an antenna with 0dB gain. Adjust your link budget assumptions based on your actual devices. Data-rate in this table is actual measured but doesn't count mesh overhead, hops and re-transmissions.
:::note
The link budget used by these calculations assumes a transmit power of 17dBm and an antenna with 0dB gain. Adjust your link budget assumptions based on your actual devices. Data-rate in this table is actual measured but doesn't count mesh overhead, hops and re-transmissions.
:::
### Custom Settings
@ -85,7 +118,7 @@ After applying the settings, you will need to restart the device. After your dev
Some example settings:
| Data-rate | SF / Symbols | Coding Rate | Bandwidth | Link Budget | Note |
| :--------- | :----------- | :---------- | :-------- | :---------- | :----------------------------------------------------------------------- |
| :---------:| :-----------:| :----------:| :--------:| :----------:| :----------------------------------------------------------------------- |
| 37.50 kbps | 6 / 64 | 4/5 | 500 | 129dB | Fastest possible speed |
| 3.125 kbps | 8 / 256 | 4/5 | 125 | 143dB | |
| 1.953 kbps | 8 / 256 | 4/8 | 125 | 143dB | |
@ -104,7 +137,7 @@ These channel settings may have not been tested. Use at your own discretion. Sha
## Cryptography
The preshared key used by the devices can be modified.
The pre-shared key (PSK) used by the devices can be modified.
- 0 = No crypto
- 1 = Default channel key

29
docs/about/overview/range-test.mdx
View file

@ -1,25 +1,38 @@
---
id: range-tests
title: Range Tests
slug: /overview/range-tests
sidebar_label: Range Tests
sidebar_position: 1
sidebar_position: 4
---
## Current Record
- **Range:** 166km (103 miles)
- **Record Holder:** _Puzzled Pancake_
- **Firmware Version:** 1.2
- **Record Holder:** _PuzzledPancake_
- **Source:** [Meshtastic Discourse](https://meshtastic.discourse.group/t/practical-range-test-results/692/44)
**Modem Settings**
- **Frequency:** 868MHz
- **Bandwidth:** 125
- **Spread Factor:** 12
- **Coding Rate:** 4/8
- **Device A:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam)
- **Antenna:** Omnidirectional
- **Device B:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam)
- **Antenna:** Omnidirectional
**Node A**
- **Device:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam)
- **Firmware Version:** 1.2
- **Antenna:** [868MHz 5dBi Antenna](https://ivent.co.nz/product/category/1000/868mhz%205dbi%20antenna%20193mm%20black%20sma%20%28m%29/38646)
**Node B**
- **Device:** [LILYGO TTGO T-Beam w/ SX1262](/docs/hardware/devices/tbeam)
- **Firmware Version:** 1.2
- **Antenna:** [868MHz Vertical 6dBi](https://ivent.co.nz/product/category/1000/868mhz%20vertical%206dbi%20antenna/38606)
![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)
![Node B](https://canada1.discourse-cdn.com/free1/uploads/meshtastic/optimized/2X/1/1c8bd5fc41f7bab925404b657a9c481882de9313_2_1332x1000.jpeg)
**Resources Used**
- http://www.heywhatsthat.com

1
docs/blocks/_lora-regions.mdx
View file

@ -1,3 +1,4 @@
| Region Code | Description |
| :-------: | :--------: |
| `UNSET` | Unset |

14
docs/configuration/device-config/bluetooth.mdx
View file

@ -28,30 +28,30 @@ Finally, `NO_PIN` disables PIN authentication.
If your pairing mode is set to fixed PIN this is the value of that fixed 6 digit pin. Default value is 123456
## Bluetooth Module Config Client Availability
## Configure Bluetooth Config
<Tabs
groupId="settings"
defaultValue="apple"
defaultValue="cli"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Flasher', value: 'flasher'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
Bluetooth module config is not available for Android.
Bluetooth config is not available for Android.
:::
</TabItem>
<TabItem value="apple">
:::info
All Bluetooth config values are available on iOS, iPadOS and macOS at Settings > Radio Configuration > Position.
:::
All Bluetooth config values are available on iOS, iPadOS and macOS.
1. Open the Meshtastic App
2. Navigate to: **Settings > Radio Configuration > Position**
</TabItem>
<TabItem value="cli">

13
docs/configuration/remote-admin.mdx
View file

@ -4,7 +4,18 @@ title: Remote Node Administration
sidebar_label: Remote Nodes
---
This feature will allow you to use the multiple channels feature to enable remote administration of Meshtastic nodes. This will let you talk through the mesh to some far away node and change that node's settings. This is an advanced feature that (currently) few users would need. Also, keep in mind it is possible (if you are not careful) to assign settings to that remote node that cause it to completely drop off of your mesh. We advise network admins have a test node to test settings with before applying changes to a remote node to prevent this.
:::caution Disclaimer
This is an advanced feature that few users should need. Keep in mind that it is possible (if you are not careful) to assign settings to a remote node that cause it to completely drop off of your mesh. We advise network admins have a test node to test settings with before applying changes to a remote node to prevent this.
:::
This feature allows you to remotely administer Meshtastic nodes through the mesh.
## Prerequisites
For any node that you want to administer, you must:
1. Configure a channel with the channel name of `admin`.
2. Set the PSK for the `admin` channel with the same key you wish to administer other all other nodes of the mesh with.
## Creating the admin channel

68
docs/development/android.mdx
View file

@ -9,38 +9,58 @@ sidebar_position: 1
If you would like to develop this application we'd love your help! These build instructions are brief and should be improved, please send a PR if you can.
- 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:
```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.
1. Use Android Studio to build/debug
2. Use `git submodule update --init --recursive` to pull in the various sub-modules we depend on.
3. 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:
```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/
```
4. Now you should be able to select "Run / Run" in the IDE and it will happily start running on your phone or the emulator.
:::note
The emulators don't support Bluetooth, so some features can not be used in that environment.
:::
## Analytics setup
## Setup Analytics
- Analytics are included but can be disabled by the user on the settings screen
- On dev devices
Analytics are included but can be disabled by the user on the settings screen.
```sh
adb shell setprop debug.firebase.analytics.app com.geeksville.mesh
adb shell setprop log.tag.FirebaseCrashlytics DEBUG
```
1. Configure analytics for development device
for verbose logging:
```sh
adb shell setprop debug.firebase.analytics.app com.geeksville.mesh
adb shell setprop log.tag.FirebaseCrashlytics DEBUG
```
2. Set verbose logging
```sh
adb shell setprop log.tag.FA VERBOSE
```
```sh
adb shell setprop log.tag.FA VERBOSE
```
## Publishing to google play
## Publish to Google Play
:::info
Only available for core developers that publish releases.
:::
1. Add repository secrets:
- **KEYSTORE_FILENAME**
- Name of the `.jks`
- **KEYSTORE**
- Convert the `.jks` to base64:
```sh
openssl base64 < filename.jks | tr -d '\n' | tee filename.txt
```
- **KEYSTORE_PROPERTIES**
- `storePassword=nononononono`
- `keyPassword=nononononono`
- `keyAlias=upload`
- `storeFile=nononononono.jks`
2. Update protobufs
3. Go to Actions / Make Release / Run Workflow
4. Pick the Releases branch
5. Enter the version found in `app/gradle.build`
- Only supported if you are a core developer that needs to do releases

7
docs/development/apple.tbd Normal file
View file

@ -0,0 +1,7 @@
---
id: building
title: Apple
sidebar_label: Apple
---
TBD

2
docs/development/device/error-codes.mdx
View file

@ -12,7 +12,7 @@ This table is derived from the [protobufs](/docs/developers/protobufs/api#critic
:::
| Name | Number | Description |
| ------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
|:------------------- :|:------:|:----------------------------------------------------------------------------------------------------------------------- |
| TxWatchdog | 1 | A software bug was detected while trying to send LoRa |
| SleepEnterWait | 2 | A software bug was detected on entry to sleep |
| NoRadio | 3 | No LoRa radio hardware could be found |

89
docs/development/device/module-api.mdx
View file

@ -5,29 +5,42 @@ sidebar_label: Module API
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.
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 the Meshtastic mesh.
## Key concepts
All modules should be subclasses of MeshModule. By inheriting from this class and creating an instance of your new module your module will be automatically registered to receive packets.
All modules should be sub-classes of MeshModule. By inheriting from this class and creating an instance of your new module - your module will be automatically registered to receive packets.
Messages are sent to particular port numbers (similar to UDP networking). Your new module should eventually pick its own port number (see below), but at first you can simply use PRIVATE_APP (which is the default).
Messages are sent to particular port numbers (similar to UDP networking). Your new module should eventually pick its own port number (see below). For development use, you can simply use `PRIVATE_APP` (which is the default).
Packets can be sent/received either as raw binary structures or as [Protobufs](https://developers.google.com/protocol-buffers).
Packets can be sent and received as either:
### Class hierarchy
1. Raw binary structures
2. [Protobufs](https://developers.google.com/protocol-buffers).
The relevant bits of the class hierarchy are as follows
- [MeshModule](http://github.com/meshtastic/firmware/tree/master/src/mesh/MeshModule.h) (in src/mesh/MeshModule.h) - you probably don't want to use this baseclass directly
- [SinglePortModule](http://github.com/meshtastic/firmware/tree/master/src/mesh/SinglePortModule.h) (in src/mesh/SinglePortModule.h) - for modules that send/receive from a single port number (the normal case)
- [ProtobufModule](http://github.com/meshtastic/firmware/tree/master/src/mesh/ProtobufModule.h) (in src/mesh/ProtobufModule.h) - for modules that send/receive a single particular Protobuf type. Inherit from this if you are using protocol buffers in your module.
## Class hierarchy
You will typically want to inherit from either SinglePortModule (if you are just sending/receiving raw bytes) or ProtobufModule (if you are sending/receiving protobufs). You'll implement your own handleReceived/handleReceivedProtobuf - probably based on the example code.
If your module needs to perform any operations at startup you can override and implement the setup() method to run your code.
The relevant bits of the class hierarchy are as follows:
If you need to send a packet you can call service.sendToMesh with code like this (from the examples):
### First Level: MeshModule
- [src/mesh/MeshModule.h](http://github.com/meshtastic/firmware/tree/master/src/mesh/MeshModule.h) - you probably don't want to use this base-class directly.
### Second Level: SinglePortModule
- [src/mesh/SinglePortModule.h](http://github.com/meshtastic/firmware/tree/master/src/mesh/SinglePortModule.h) - for modules that send/receive from a single port number (the normal case).
### Third Level: ProtobufModule
- [src/mesh/ProtobufModule.h](http://github.com/meshtastic/firmware/tree/master/src/mesh/ProtobufModule.h) - for modules that send/receive a single particular Protobuf type. Inherit from this if you are using protocol buffers in your module.
## Startup Operations
If your module needs to perform any operations at startup you can override and implement the `setup()` method to run your code.
If you need to send a packet you can call `service.sendToMesh` with code like this (from the examples):
```cpp
MeshPacket *p = allocReply();
@ -36,51 +49,51 @@ p->to = dest;
service.sendToMesh(p);
```
## Example modules
## Example Modules
A number of [key services](http://github.com/meshtastic/firmware/tree/master/src/modules) are implemented using the module API, these modules are as follows:
A number of [key services](http://github.com/meshtastic/firmware/tree/master/src/modules) are implemented using the Module API, These modules are as follows:
- [TextMessageModule](http://github.com/meshtastic/firmware/tree/master/src/modules/TextMessageModule.h) - receives text messages and displays them on the LCD screen/stores them in the local DB
- [NodeInfoModule](http://github.com/meshtastic/firmware/tree/master/src/modules/NodeInfoModule.h) - receives/sends User information to other nodes so that usernames are available in the databases
- [RemoteHardwareModule](http://github.com/meshtastic/firmware/tree/master/src/modules/RemoteHardwareModule.h) - a module that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/hardware/peripheral/#remote-hardware) for details.
- [ReplyModule](http://github.com/meshtastic/firmware/tree/master/src/modules/ReplyModule.h) - a simple module that just replies to any packet it receives (provides a 'ping' service).
- [TextMessageModule](http://github.com/meshtastic/firmware/tree/master/src/modules/TextMessageModule.h) - Receives text messages and displays them on the LCD screen/stores them in the local DB.
- [NodeInfoModule](http://github.com/meshtastic/firmware/tree/master/src/modules/NodeInfoModule.h) - Receives/sends User information to other nodes so that usernames are available in the databases.
- [RemoteHardwareModule](http://github.com/meshtastic/firmware/tree/master/src/modules/RemoteHardwareModule.h) - A module that provides easy remote access to device hardware (for things like turning GPIOs on or off). Intended to be a more extensive example and provide a useful feature of its own. See [remote-hardware](/docs/hardware/peripheral/#remote-hardware) for details.
- [ReplyModule](http://github.com/meshtastic/firmware/tree/master/src/modules/ReplyModule.h) - A simple module that just replies to any packet it receives (provides a 'ping' service).
## Getting started
The easiest way to get started is:
- [Build and install](/docs/development/firmware/build) the standard codebase from GitHub.
- Copy [src/modules/ReplyModule.\*](http://github.com/meshtastic/firmware/tree/master/src/modules/ReplyModule.cpp) into src/modules/YourModule.*. Then change the port number from *PortNum_REPLY_APP* to *PortNum_PRIVATE_APP\*.
- Edit moduless/Moduless.cpp:setupModules() to add a call to create an instance of your module (see comment at head of that function)
- Rebuild with your new messaging goodness and install on the device
- Use the [meshtastic commandline tool](https://github.com/meshtastic/Meshtastic-python) to send a packet to your board, for example `meshtastic --dest 1234 --sendping`, where _1234_ is another mesh node to send the ping to.
1. [Build the firmware](/docs/development/firmware/build) codebase.
2. Copy the [ReplyModule](http://github.com/meshtastic/firmware/tree/master/src/modules/ReplyModule.cpp) as a template into `src/modules/`.
```sh
cp src/modules/ReplyModule.* src/modules/YourModule.*
```
3. Change the port number from `PortNum_REPLY_APP` to `PortNum_PRIVATE_APP`.
4. Edit the `setupModules()` function located at `modules/Moduless.cpp` to add a call to create an instance of your module (see comment at head of that function).
5. Rebuild with your new module and install on the device.
6. Use the [Meshtastic Python CLI tool](https://github.com/meshtastic/Meshtastic-python) to send a packet to your board, for example:
- `meshtastic --dest 1234 --sendping` where _1234_ is another mesh node to send the ping to.
## Threading
It is very common that you would like your module to be invoked periodically.
We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement runOnce(). See the OSThread [documentation](http://github.com/meshtastic/firmware/tree/master/src/concurrency/OSThread.h) for more details.
We use a crude/basic cooperative threading system to allow this on any of our supported platforms. Simply inherit from OSThread and implement `runOnce()`. See the OSThread [documentation](http://github.com/meshtastic/firmware/tree/master/src/concurrency/OSThread.h) for more details.
## Sending messages
If you would like to proactively send messages (rather than just responding to them), just call service.sendToMesh(). For an example of this see [NodeInfoModule::sendOurNodeInfo(...)](http://github.com/meshtastic/firmware/tree/master/src/modules/NodeInfoModule.cpp).
If you would like to proactively send messages (rather than just responding to them), just call `service.sendToMesh()`. For an example of this, see [NodeInfoModule::sendOurNodeInfo(...)](http://github.com/meshtastic/firmware/tree/master/src/modules/NodeInfoModule.cpp).
## Picking a port number
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.
If you are making a new app using meshtastic, please send in a pull request to add your 'portnum' to [the master list](https://github.com/meshtastic/protobufs/blob/master/portnums.proto). PortNums should be assigned in the following range:
- **0-63** Core Meshtastic use; do not use for third party apps
- **64-127** Registered 3rd party apps. Send in a pull request that adds a new entry to portnums.proto to register your application
- **256-511** Use one of these portnums for your private applications that you don't want to register publicly
- **1024-66559** Are reserved for use by IP tunneling (see [here](/docs/development/firmware/portnum) for more information)
All other values are reserved.
See [Meshtastic Port Numbers](/docs/development/firmware/portnum)
## How to add custom protocol buffers
If you would like to use protocol buffers to define the structures you send over the mesh (recommended), here's how to do that.
- Create a new .proto file in the protos directory.
- Run "bin/regen-protos.sh" to regenerate the C code for accessing the protocol buffers. If you don't have the required nanopb tool, follow the instructions printed by the script to get it.
- Done! You can now use your new protobuf just like any of the existing protobufs in meshtastic.
1. Create a new `.proto` file in the protos directory.
2. Run `./bin/regen-protos.sh` to regenerate the C code for accessing the protocol buffers. If you don't have the required nanopb tool, follow the instructions printed by the script to get it.
3. Done! You can now use your new protobuf just like any of the existing protobufs in Meshtastic.

111
docs/development/documentation/publish.mdx
View file

@ -6,107 +6,16 @@ sidebar_label: Publish
## Publish Live
### Device
- Update protobufs
```shell
cd proto
git checkout master && git pull
cd ..
git add proto
git commit -m "updating proto submodule to latest"
run bin/regen-protos.sh
```
- edit version.properties to set release version
- commit and push (or merge) to root of repo - this should cause GitHub to start a release build (see the CI actions)
- edit the draft release text and click publish
#### Update Protobufs
### Android
#### Pre-requisites
- Add repository secrets
- - KEYSTORE_FILENAME
- - - name of the .jks
- - KEYSTORE
- - - we will convert the .jks to base64
- - - openssl base64 < filename.jks | tr -d '\n' | tee filename.txt
- - KEYSTORE_PROPERTIES
- - - storePassword=nononononono
keyPassword=nononononono
keyAlias=upload
storeFile=nononononono.jks
#### Instructions - Automated
- Update protobufs
- Go to Actions / Make Release / Run Workflow
- Pick the Releases branch
- Enter the version found in app/gradle.build
### iOS
TBD
### Meshtastic-flasher
A `meshtastic-flasher` release consists of publishing the release to PyPi https://pypi.org/project/meshtastic-flasher/ as well as producing single-executable files that are downloadable from Github https://github.com/meshtastic/Meshtastic-gui-installer/releases.
#### Instructions - automated
- Go to Actions / Make Release / Run Workflow https://github.com/meshtastic/Meshtastic-gui-installer/actions/workflows/release.yml
- Draft & Publish release https://github.com/meshtastic/Meshtastic-gui-installer/releases
### Python
A python release consists of publishing the release to PyPi https://pypi.org/project/meshtastic/ as well as producing single-executable files that are downloadable from Github https://github.com/meshtastic/Meshtastic-python/releases.
#### Pre-requisites
No pre-requisites are needed locally to make a release. All builds are done via Github Actions currently.
To test/validate, you will need to run:
```
pip3 install -r requirements.txt
pip install .
```
#### Instructions
- Update protobufs by running the "Update protobufs" workflow in Actions: https://github.com/meshtastic/Meshtastic-python/actions/workflows/update_protobufs.yml
- run the "smoke1" test (optional):
connect one device to the serial port and run:
```
pytest -m smoke1
```
- run unit tests: `pytest` (optional)
- run bin/test-release.sh (optional)
- Run the "Make Release" workflow in Actions: https://github.com/meshtastic/Meshtastic-python/actions/workflows/release.yml
- After the "Make Release" is done, go into Releases: https://github.com/meshtastic/Meshtastic-python/releases There should be a draft. Add the title, update the "What's Changed" (Tip: Click on the "Auto-generate release notes" button.). Uncheck the "This is a pre-release" (if applicable).
:::note
You need permissions in the GitHub project to make a build
:::
### Web
Releases are automatically generated for every commit as per out [CI](https://github.com/meshtastic/web/blob/master/.github/workflows/main.yml). This performs two actions:
1. Generates a perpetually updated [GitHub release](https://github.com/meshtastic/web/releases/tag/latest) with an accompanying `build.tar` that a automatically get's pulled by the firmware CI at build time.
2. A hosted version is deployed to [client.meshtastic.org](https://client.meshtastic.org).
1. Generate protobuf docs
```shell
cd meshtastic
./scripts/gen-proto-docs.sh
```
2. Build
```shell
pnpm build
```
3. Submit Pull Request
## Publish to Vercel

68
docs/development/firmware/build.mdx
View file

@ -1,68 +0,0 @@
---
id: build
title: Building Meshtastic Firmware
sidebar_label: Building Firmware
---
Meshtastic uses [PlatformIO](https://platformio.org), a development environment that enables easy multi-platform development and centralized tooling.
## Setup the build environment
1. Install PlatformIO, following the instructions available [here](https://platformio.org/platformio-ide).
2. Clone the [`firmware`](https://github.com/meshtastic/firmware) repository. ([Instructions on cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository))
3. Clone the repositories [Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
```shell
git submodule update --init
```
4. Some utilities and scripts use the Python programming language, Downloads available [here](https://www.python.org/downloads).
## Building
1. Open the newly cloned folder in [Visual Studio Code](https://code.visualstudio.com).
1. To select the device you you wish to build for, first open your [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) (windows: `Ctrl + Shift + P` or mac: `command + Shift + P` ) and enter: `platformio: Switch Project Environment` and select your target.
1. To build the firmware, simply run `PlatformIO: Build` from your command palette.
1. Finally flashing the firmware to your device is as easy as running `PlatformIO: Upload`
## Adding your own Hardware
The build system is modular. Adding a new board variant for an already supported architecture is straigtforward.
### Building for your own DIY hardware or mod that you don't want to distribute
1. go to the `variants` folder in the firmware sourcecode and make a new directory for your hardware, let's call it `m5stack_atom` and copy an existing configuration you wanna modify
```shell
cd variants; mkdir m5stack_atom
cp heltec_v1/* m5stack_atom
cd m5stack_atom
```
2. modify the `platformio.ini` _in this subdirectory_ from the canonical define of the hardware variant (`HELTEC_V1` in this case) to `PRIVATE_HW` and make the `-I` on the `build_flags` point to the newly created dir.
```shell
[env:m5stack-atom]
extends = esp32_base
board = m5stack-atom
monitor_filters = esp32_exception_decoder
build_flags =
${esp32_base.build_flags} -D PRIVATE_HW -I variants/m5stack_atom
lib_deps =
${esp32_base.lib_deps}
```
3. edit the `variant.h` file _in this subdirectory_ to reflect the defines and configurations for your board. The example is very well commented.
4. build, run and debug until you are satisfied with the result.
### Adding a new off-the-shelf or DIY hardware that you want to distribute (e.g. add a new canon board)
1. do all of the above until your hardware runs fine
2. [Send in a proposal to add a new board](https://github.com/meshtastic/firmware/issues/new?assignees=&labels=enhancement%2Ctriage&template=New+Board.yml&title=%5BBoard%5D%3A+)
3. if approved, go to (https://github.com/meshtastic/protobufs) and send a Pull Request for the `mesh.proto` file, adding your board to the `HardwareModel` Enum.
4. change your define in `platformio.ini` from `PRIVATE_HW` to `YOUR_BOARD`. Adjust any macro guards in the code you need to support your board.
5. add your board identifier to `configuration.h` on the firmware repo and send in that Pull Request too.
6. wait for the Pulls to be merged back into Master.
7. profit :-)

65
docs/development/firmware/building.mdx Normal file
View file

@ -0,0 +1,65 @@
---
id: build
title: Building Meshtastic Firmware
sidebar_label: Building Firmware
---
Meshtastic uses [PlatformIO](https://platformio.org), a development environment that enables easy multi-platform development and centralized tooling.
## Setup the Build Environment
1. [Install PlatformIO](https://platformio.org/platformio-ide)
2. Clone the [Meshtastic Firmware](https://github.com/meshtastic/firmware) repository
```sh
git clone https://github.com/meshtastic/firmware.git
```
3. Update the repository's [submodules](https://github.com/meshtastic/firmware/blob/master/.gitmodules)
```shell
git submodule update --init
```
## Build
1. Open the newly cloned folder in [Visual Studio Code](https://code.visualstudio.com).
2. To select the device you you wish to build, open your [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette):
- Windows: `Ctrl + Shift + P`
- Mac: `command + Shift + P`
3. Enter: `platformio: Switch Project Environment` and select your target.
4. To build the firmware, simply run `PlatformIO: Build` from your command palette.
5. Finally, flash the firmware to your device by running `PlatformIO: Upload`
## Adding Custom Hardware
The build system is modular. Adding a new board variant for an already supported architecture is straightforward.
### Build with Custom Hardware
1. Go to the `variants` folder in the firmware source code and make a new directory for your hardware, let's call it `m5stack_atom` and copy an existing configuration you wanna modify:
```shell
cd variants; mkdir m5stack_atom
cp heltec_v1/* m5stack_atom
cd m5stack_atom
```
2. Modify the `platformio.ini`_in this subdirectory_ from the canonical define of the hardware variant (`HELTEC_V1` in this case) to `PRIVATE_HW` and make the `-I` on the `build_flags` point to the newly created dir.
```shell
[env:m5stack-atom]
extends = esp32_base
board = m5stack-atom
monitor_filters = esp32_exception_decoder
build_flags =
${esp32_base.build_flags} -D PRIVATE_HW -I variants/m5stack_atom
lib_deps =
${esp32_base.lib_deps}
```
3. Edit the `variant.h` file _in this subdirectory_ to reflect the defines and configurations for your board. The example is very well commented.
4. Build, run and debug until you are satisfied with the result.
### Distribute / Publish Custom Builds
1. Perform all of the steps [building with custom hardware](#build-with-custom-hardware) until your hardware runs fine.
2. [Send a proposal](https://github.com/meshtastic/firmware/issues/new?assignees=&labels=enhancement%2Ctriage&template=New+Board.yml&title=%5BBoard%5D%3A+) to add a new board.
3. If approved, go to (https://github.com/meshtastic/protobufs) and send a Pull Request for the `mesh.proto` file, adding your board to the `HardwareModel` Enum.
4. Change your define in `platformio.ini` from `PRIVATE_HW` to `YOUR_BOARD`. Adjust any macro guards in the code you need to support your board.
5. Add your board identifier to `configuration.h` on the firmware repo and send in that Pull Request too.
6. Wait for the Pulls to be merged back into Master.
7. Profit :-)

61
docs/development/firmware/oled-guide.mdx
View file

@ -4,39 +4,32 @@ title: OLED Localization Guide
sidebar_label: OLED Localization
---
# OLED localization guide
1. Create an extended ASCII custom font. Use a glyph editor to create a new font file. The easiest way is to use the online [glyph editor](https://rawgit.com/ThingPulse/esp8266-oled-ssd1306/master/resources/glyphEditor.html) from the OLED library. ([glyph editor source code](https://github.com/ThingPulse/esp8266-oled-ssd1306/tree/master/resources))
1. Copy and paste the existing font.
2. Modify it according desired codepage and save the new font file in `graphics/font` folder.
Please note that the used font file format differs from common Adafruit GFX.
2. Update the `customFontTableLookup` function in `Screen.h`
1. To map the double-byte UTF-8 code to the corresponding extended ASCII character of the desired codepage update the `customFontTableLookup` function in the `Screen.h` file.
2. Modify the `switch (last)` statement: use left byte from UTF-8 code in the `case` label to map charachter's right byte to its extended ASCII code by specifying an offset.
3. Define language and font in `Screen.cpp`
```c
#ifdef OLED_{LANG_NAME}
#include "fonts/OLEDDisplayFonts{LANG_NAME}.h"
#endif
## 1. Create an extended ASCII custom font
Use a glyph editor to create a new font file. The easiest way is to use the online [glyph editor][glyphEditor] from the OLED library. [Glyph editor source code][glyphEditorSource]. Copy and paste the existing font, modify it according desired codepage and save the new font file in `graphics/font` folder.
...
Please note that the used font file format differs from common Adafruit GFX.
## 2. Update the `customFontTableLookup` function in `Screen.h`
To map the double-byte UTF-8 code to the corresponding extended ASCII character of the desired codepage update the `customFontTableLookup` function in the `Screen.h` file. You need to modify the `switch (last)` statement: use left byte from UTF-8 code in the `case` label to map charachter's right byte to its extended ASCII code by specifying an offset.
## 3. Define language and font in `Screen.cpp`
```
#ifdef OLED_{LANG_NAME}
#include "fonts/OLEDDisplayFonts{LANG_NAME}.h"
#endif
...
#ifdef OLED_{LANG_NAME}
#define FONT_SMALL ArialMT_Plain_10_{LANG_NAME}
#else
#define FONT_SMALL ArialMT_Plain_10
#endif
```
## 4. Define language in `variant/*/platformio.ini`
```
build_flags =
${esp32_base.build_flags}
-D xxxxx
-D OLED_{LANG_NAME}
-I variants/xxxxx
```
[glyphEditor]: <https://rawgit.com/ThingPulse/esp8266-oled-ssd1306/master/resources/glyphEditor.html>
[glyphEditorSource]: <https://github.com/ThingPulse/esp8266-oled-ssd1306/tree/master/resources>
#ifdef OLED_{LANG_NAME}
#define FONT_SMALL ArialMT_Plain_10_{LANG_NAME}
#else
#define FONT_SMALL ArialMT_Plain_10
#endif
```
4. Define language in `variant/*/platformio.ini`
```
build_flags =
${esp32_base.build_flags}
-D xxxxx
-D OLED_{LANG_NAME}
-I variants/xxxxx
```

18
docs/development/firmware/port-numbers.mdx
View file

@ -4,20 +4,22 @@ 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.
Any new app that runs on the device or via sister apps on phones/PCs should pick and use a unique "portnum" for their applications use.
If you are making a new app using meshtastic, please send in a pull request to add your 'portnum' to this master table. PortNums should be assigned in the following range:
The current list of port numbers can be found listed in the [protobufs](/docs/developers/protobufs/api#portnumsproto)
## Assignment
PortNums should be assigned by the following ranges:
| Portnum | Usage |
| ------- | ---------------------------------------------------------------------------------------------------------------------- |
| 0-63 | Core Meshtastic use, do not use for third party apps |
|:-------:|:---------------------------------------------------------------------------------------------------------------------- |
| 0-63 | Core Meshtastic use, do not use for third party apps. |
| 64-127 | Registered 3rd party apps, send in a pull request that adds a new entry to portnums.proto to register your application |
| 256-511 | Use one of these portnums for your private applications that you do not want to register publicly |
All other values are reserved.
Note: This was formerly a Type enum named `typ` with the same id #
## Integration
We have changed to this 'portnum' based scheme for specifying app handlers for particular payloads. This change is backwards compatible by treating the legacy OPAQUE/CLEAR_TEXT values identically.
The current list of port numbers can be found listed in the [protobufs](/docs/developers/protobufs/api#portnumsproto)
If you are making a new app using Meshtastic, please send a pull request to add your chosen "portnum" to this master table.

25
docs/development/firmware/stacktraces.mdx
View file

@ -8,28 +8,25 @@ sidebar_label: Stacktraces
You may encounter a situation where your device crashes and are left with a stacktrace, below are two methods of decoding them.
### Manual
### Manually
:::info
This method uses the symbols of the `firmware.elf` file generated from your latest build, you may wish to rebuild to get up-to-date symbols.
:::
First save the backtrace string to a text file:
1. Save the backtrace string to a text file:
```text title="backtrace.txt"
Backtrace: 0x....
```
```text title="backtrace.txt"
Backtrace: 0x....
```
2. Run the exception decoder:
```shell
bin/exception_decoder.py backtrace.txt
```
Now run the exception decoder:
```shell
bin/exception_decoder.py backtrace.txt
```
### Real-Time
In order to decode stack traces in real time, keep the following command (replacing `DEVICE_PORT` with your device's port) running in your terminal with the suspect device connected
### In Real-Time
In order to decode stack traces in real time, keep the following command (replacing `DEVICE_PORT` with your device's port) running in your terminal with the target device connected:
```shell
pio device monitor --port DEVICE_PORT -f esp32_exception_decoder
```

53
docs/development/python/building.mdx Normal file
View file

@ -0,0 +1,53 @@
---
id: building
title: Building
sidebar_label: Building
---
A python release consists of publishing the release to PyPi https://pypi.org/project/meshtastic/ as well as producing single-executable files that are downloadable from Github https://github.com/meshtastic/Meshtastic-python/releases.
#### Pre-requisites
No pre-requisites are needed locally to make a release. All builds are done via Github Actions currently.
To test/validate, you will need to run:
```
pip3 install -r requirements.txt
pip install .
```
#### Instructions
- Update protobufs by running the "Update protobufs" workflow in Actions: https://github.com/meshtastic/Meshtastic-python/actions/workflows/update_protobufs.yml
- run the "smoke1" test (optional):
connect one device to the serial port and run:
```
pytest -m smoke1
```
- run unit tests: `pytest` (optional)
- run bin/test-release.sh (optional)
- Run the "Make Release" workflow in Actions: https://github.com/meshtastic/Meshtastic-python/actions/workflows/release.yml
- After the "Make Release" is done, go into Releases: https://github.com/meshtastic/Meshtastic-python/releases There should be a draft. Add the title, update the "What's Changed" (Tip: Click on the "Auto-generate release notes" button.). Uncheck the "This is a pre-release" (if applicable).
:::note
You need permissions in the GitHub project to make a build
:::
### Meshtastic-flasher
A `meshtastic-flasher` release consists of publishing the release to PyPi https://pypi.org/project/meshtastic-flasher/ as well as producing single-executable files that are downloadable from Github https://github.com/meshtastic/Meshtastic-gui-installer/releases.
#### Instructions - automated
- Go to Actions / Make Release / Run Workflow https://github.com/meshtastic/Meshtastic-gui-installer/actions/workflows/release.yml
- Draft & Publish release https://github.com/meshtastic/Meshtastic-gui-installer/releases

4
docs/development/reference/protobuf-api.mdx
View file

@ -857,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/about/overview/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/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/about/overview/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/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. |

11
docs/development/web/building.mdx Normal file
View file

@ -0,0 +1,11 @@
---
id: building
title: Building
sidebar_label: Building
---
Releases are automatically generated for every commit as per out [CI](https://github.com/meshtastic/web/blob/master/.github/workflows/main.yml). This performs two actions:
1. Generates a perpetually updated [GitHub release](https://github.com/meshtastic/web/releases/tag/latest) with an accompanying `build.tar` that a automatically get's pulled by the firmware CI at build time.
2. A hosted version is deployed to [client.meshtastic.org](https://client.meshtastic.org).

7
docs/getting-started/connect-device/_category_.yml
View file

@ -1,7 +0,0 @@
label: Connect to Device
collapsible: true
position: 3
link:
type: generated-index
title: Connect to Device
slug: /getting-started/connect-device

10
docs/getting-started/connect-device/bluetooth.mdx
View file

@ -1,10 +0,0 @@
---
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';

15
docs/getting-started/connect-device/network.mdx
View file

@ -1,15 +0,0 @@
---
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

10
docs/getting-started/connect-device/serial.mdx
View file

@ -1,10 +0,0 @@
---
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';

86
docs/getting-started/index.mdx
View file

@ -1,4 +1,5 @@
---
id: getting-started
title: Getting Started
sidebar_label: Getting Started
slug: /getting-started
@ -30,7 +31,7 @@ The NRF52 is much more power efficient than the esp32 and easier to update, but
- LILYGO® TTGO T-Echo
:::info
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.
If your device is not listed above, please review our [supported devices](/docs/supported-hardware) to determine which MCU your device has or contact us in [Discord](https://discord.gg/ktMAKGBnBs) with any questions.
:::
## Setup Working Environment
@ -47,17 +48,32 @@ Some cables only provide _charging_, verify that your cable is also capable of _
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, [install the correct serial driver](#install-serial-drivers) and [test for driver installation](#test-for-driver-installation).
Once you've located a working data cable, [install the correct serial driver](#install-serial-drivers) and [test for driver installation](#test-driver-installation).
### Install serial drivers
<div className="indexCtasBody">
<div class="split left">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/serial-drivers'}
to={'/docs/getting-started/serial-drivers/esp32'}
>
Install Serial Drivers
Install ESP32 Drivers
</Link>
</div>
</div>
<div class="split right">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/serial-drivers/nrf52'}
>
Install NRF52 Drivers
</Link>
</div>
</div>
</div>
### Test driver installation
@ -120,81 +136,45 @@ If you do not see your device:
## Flash Firmware
### ESP32
:::info
If you have a RAK4631-R (the RUI3 bootloader version of the RAK4631), you must [convert the bootloader](/docs/guides/convert-rak4631r) for use with the Arduino before flashing Meshtastic firmware.
:::
<div className="indexCtasBody">
<div class="split left">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/flashing-firmware/esp32/'}
>
Flash ESP32 Firmware
</Link>
</div>
</div>
### NRF52
For RAK4631 users, if you have a RAK4631-R (the RUI3 bootloader version of the RAK4631), you must [convert it to use the Arduino bootloader](/docs/getting-started/flashing-firmware/nrf52/#convert-rak4631-r-to-rak4631)
<div className="indexCtasBody">
<div class="split right">
<div class="centered">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/flashing-firmware/nrf52/'}
>
Flash NRF52 Firmware
</Link>
</div>
## Connect to Device
Depending on your device, there are 3 ways to connect to your device:
### Serial
<div className="indexCtasBody">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/connect-device/connect-serial'}
>
Connect using Serial
</Link>
</div>
</div>
</div>
### Bluetooth
## Connect and Configure Device
<div className="indexCtasBody">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/connect-device/connect-ble'}
>
Connect using Bluetooth
</Link>
</div>
### Network
Connecting over network is only supported on ESP32 devices.
<div className="indexCtasBody">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/connect-device/connect-network'}
>
Connect over Network
</Link>
</div>
## Configure Device
The initial configuration of the device includes setting the regional settings...
After connecting to the device for the first time, you should set the regional settings for the radio as well as other optional settings such as the name of the device.
<div className="indexCtasBody">
<Link target="_blank"
className={'button button--outline button--lg cta--button'}
to={'/docs/getting-started/initial-config'}
>
Configure Device
Connect and Configure Device
</Link>
</div>

103
docs/getting-started/init-config.mdx
View file

@ -1,103 +0,0 @@
---
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.
<Tabs
groupId="settings"
defaultValue="serial"
values={[
{label: 'Serial', value: 'serial'},
{label: 'Bluetooth', value: 'ble'},
{label: 'Network', value: 'network'},
]}>
<TabItem value="serial">
- [Python CLI](/docs/software/python/cli/)
- [Web Client](https://client.meshtastic.org)
</TabItem>
<TabItem value="ble">
- [Web Client](https://client.meshtastic.org)
</TabItem>
<TabItem value="network">
- [Web Client](https://client.meshtastic.org)
</TabItem>
</Tabs>
### Configure Regional Settings
<LoRaRegions />
<Tabs
groupId="settings"
defaultValue="apple"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Flasher', value: 'flasher'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
:::info
Region and Modem Preset can be configured on Android.
:::
</TabItem>
<TabItem value="apple">
:::info
Configuration of Region, Modem Preset and Hop Limit is available on iOS, iPadOS and macOS at Settings > Radio Configuration > LoRa.
:::
</TabItem>
<TabItem value="cli">
```sh
meshtastic --set lora.region <REGION CODE>
```
</TabItem>
<TabItem value="flasher">
:::info
No LoRa config options are available in the Flasher.
:::
</TabItem>
<TabItem value="web">
:::info
All LoRa config options are available in the Web UI.
:::
</TabItem>
</Tabs>

113
docs/getting-started/initial-config.mdx Normal file
View file

@ -0,0 +1,113 @@
---
id: initial-config
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';
## Connect to Device
:::info
Connecting over network is only supported on ESP32 devices.
:::
### Clients Supported by Connection Type
Depending on your connection, some configuration options are not fully supported. Find out which Client is best for your type of connection.
<Tabs
groupId="settings"
defaultValue="serial"
values={[
{label: 'Serial', value: 'serial'},
{label: 'Bluetooth', value: 'ble'},
{label: 'Network', value: 'network'},
]}>
<TabItem value="serial">
- [Python CLI](/docs/software/python/cli/)
- [Web Client](https://client.meshtastic.org)
- [Android App](/docs/category/android-app)
</TabItem>
<TabItem value="ble">
- [Android App](/docs/category/android-app)
- [Web Client](https://client.meshtastic.org)
- [iOS App](/docs/category/apple-apps)
</TabItem>
<TabItem value="network">
- [Web Client](https://client.meshtastic.org)
- [Android App](/docs/category/android-app)
- [iOS App](/docs/category/apple-apps)
- [Python CLI](/docs/software/python/cli/)
</TabItem>
</Tabs>
## Set Regional Settings
<Tabs
groupId="settings"
defaultValue="apple"
values={[
{label: 'Android', value: 'android'},
{label: 'Apple', value: 'apple'},
{label: 'CLI', value: 'cli'},
{label: 'Web', value: 'web'},
]}>
<TabItem value="android">
1. Follow the [installation](/docs/software/android/installation) and [usage](/docs/software/python/cli/usage) instructions for [Meshtastic Android](/docs/category/android-app).
2. Open the app, connect to the device from your phone over USB Serial or Bluetooth.
3. Once paired, Click "UNSET" next to the device name.
4. Select the region from the list according to your regional location.
</TabItem>
<TabItem value="apple">
:::info
Configuration of Region, Modem Preset and Hop Limit is available on iOS, iPadOS and macOS at Settings > Radio Configuration > LoRa.
:::
</TabItem>
<TabItem value="cli">
1. Install [Meshtastic PythonCLI](/docs/software/python/cli/installation)
```sh
pip3 install --upgrade pytap2
pip3 install --upgrade meshtastic
```
2. Run the following command, replacing `<REGION-CODE>` with the region code listed above according to your regional location.
```sh
meshtastic --set lora.region <REGION-CODE>
```
</TabItem>
<TabItem value="web">
1. Open the Meshtastic Web interface: [client.meshtastic.org](https://client.meshtastic.org)
2. Navigate to the **LoRa** menu.
3. Under **Regional Settings**, set your **Region** according to your regional location.
4. Click **Save**.
</TabItem>
</Tabs>
### Region Codes
<LoRaRegions />

3
docs/getting-started/serial-drivers/serial-drivers-esp32.mdx
View file

@ -1,8 +1,7 @@
---
id: installing-esp32-serial-drivers
id: esp32
title: ESP32 Serial Drivers
sidebar_label: ESP32 Drivers
#pagination_next: /docs/getting-started
sidebar_position: 1
---

2
docs/getting-started/serial-drivers/serial-drivers-nrf52.mdx
View file

@ -1,5 +1,5 @@
---
id: installing-nrf52-serial-drivers
id: nrf52
title: NRF52 Serial Drivers
sidebar_label: NRF52 Drivers
sidebar_position: 2

10
docs/guides/gpio-peripherals.mdx Normal file
View file

@ -0,0 +1,10 @@
---
id: gpio-peripherals
title: Configuring GPIO Peripherals
sidebar_label: Setup GPIO Peripherals
sidebar_position: 6
---
import Peripherals from '../hardware/peripheral/index.mdx'
<Peripherals components={props.components} />

10
docs/guides/link-new-modules.mdx Normal file
View file

@ -0,0 +1,10 @@
---
id: writing-modules
title: Creating New Modules
sidebar_label: Create a Module
sidebar_position: 5
---
import NewModule from '../development/device/module-api.mdx'
<NewModule components={props.components} />

30
docs/hardware/peripheral/buttons/index.mdx
View file

@ -5,12 +5,26 @@ sidebar_label: Buttons
sidebar_position: 3
---
A number of devices have buttons that can be used to interact with the firmware. These buttons have a number of different functions:
## Functionality
- Reset button - This is present on most devices.
- Power button - This is present on some devices. A long press powers the device off or turns it back on again.
- Program button - This is present of some devices and has a number of functions:
- Single press - This changes the page of information displayed on the screen.
- Double press - This sets the Bluetooth pairing code to `123456` (useful if you do not have a screen on the device).
- Long press - This adjusts the contrast of the screen.
- Long press during reboot - This turns on the software WiFi access point on devices that support WiFi.
A number of devices have buttons that can be used to interact with the firmware. These buttons have a number of different functions.
### Reset Button
The reset button is present on most devices.
- _Single press_ resets the device.
### Power Button
The power button is present on some devices.
- _Long press_ powers the device off or turns it back on again.
### Program button
The program button is present of some devices and has a number of functions:
- _Single press_ changes the page of information displayed on the screen.
- _Double press_ sets the Bluetooth pairing code to `123456` (useful if you do not have a screen on the device).
- _Long press_ adjusts the contrast of the screen.
- _Long press during reboot_ turns on the software WiFi access point on devices that support WiFi.

137
docs/hardware/peripheral/index.mdx
View file

@ -7,31 +7,25 @@ sidebar_position: 2
## Firmware Versions
The device firmware runs on the nodes to build the mesh for communication. Each different make and model of device requires a different build of the Meshtastic firmware in order to run properly. Thankfully, due to the design of Meshtastic, it is possible to port the firmware to new devices as they become available. The firmware currently runs on a range of ESP32 based devices, but there is also increasing support for the nRF52 microprocessor with some more recent devices coming to market.
The current firmware has support for a screen to display received messages, along with information about nodes on the mesh, and more detailed information about the device on which it is running.
The latest firmware can be downloaded from the [Downloads](/downloads) page. If you wish to view the code or contribute to development of the firmware, please visit the device code <a href="https://github.com/meshtastic/firmware">GitHub page</a>.
:::info
Please be aware that there are significant changes between version branches 1.2.x and 1.3.x which mean that devices need to be running the same branch of firmware to be able to talk to each other. Python, Android, and other software applications will also need to be running the same branch to be able to talk to the device.
:::
## Remote Hardware
:::warning
GPIO access is fundamentally dangerous because invalid options can physically damage or destroy your hardware. Ensure that you fully understand the schematic for your particular device before trying this as we do not offer a warranty. Use at your own risk.
:::
:::note
The device firmware runs on the nodes to build the mesh for communication. Each different make and model of device requires a different build of the Meshtastic firmware in order to run properly. Thankfully, due to the design of Meshtastic, it is possible to port the firmware to new devices as they become available. The firmware currently runs on a range of ESP32 based devices, but there is also increasing support for the nRF52 microprocessor with some more recent devices coming to market.
The current firmware has support for a screen to display received messages, along with information about nodes on the mesh, and more detailed information about the device on which it is running.
The latest firmware can be downloaded from the [Downloads](/downloads) page. If you wish to view the code or contribute to development of the firmware, please visit the device code [GitHub page](https://github.com/meshtastic/firmware).
:::info
Please be aware that there are significant changes between version branches 1.2.x and 1.3.x which mean that devices need to be running the same branch of firmware to be able to talk to each other. Python, Android, and other software applications will also need to be running the same branch to be able to talk to the device.
This feature uses a preinstalled module in the device code and associated command line flags/classes in the python code. You'll need to be running at least version 1.2.23 (or later) of the python and device code to use this feature.
:::
You can get the latest python tool/library with `pip3 install --upgrade meshtastic` on Windows/Linux/OS-X. See the [python section](/docs/software/python/cli/installation) for more details.
## Remote Hardware
### Supported operations in the initial release
### Supported Operations
- Set any GPIO
- Read any GPIO
@ -39,41 +33,38 @@ You can get the latest python tool/library with `pip3 install --upgrade meshtast
### Setup
You can get the latest python tool/library with `pip3 install --upgrade meshtastic` on Windows/Linux/OS-X. See the [python section](/docs/software/python/cli/installation) for more details.
To prevent access from untrusted users, you must first make a `gpio` channel that is used for authenticated access to this feature. You'll need to install this channel on both the local and remote node.
The procedure using the python command line tool is:
1. Connect local device via USB
2. Create a gpio channel
2. Create a GPIO channel:
```shell
meshtastic --ch-add gpio
```
:::tip
If doing local testing, may want to change the speed of the channel at this time, too. (ex: "meshtastic --ch-mediumfast")
:::
3. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device
3. If doing local testing, you may also want to change the speed of the channel:
```sh
meshtastic --ch-mediumfast
```
4. Check the channel has been created and copy the long "Complete URL" that contains all the channels on that device:
```shell
meshtastic --info
```
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
5. Connect the remote device via USB (or use the [remote admin](/docs/configuration/remote-admin) feature to reach it through the mesh)
6. Set it to join the gpio channel you created:
```shell
meshtastic --seturl theurlyoucopiedinstep3
```
Now both devices should be able to talk over the `gpio` channel. Send a text message from one the other other verify. Also run "--nodes" to verify the second node shows up.
Now both devices should be able to talk over the `gpio` channel. Send a text message from one the other other verify. Also run `--nodes` to verify the second node shows up.
### A little bit of information about masks
### Masks
To determine the appropriate mask for the pin(s) that you want to know. The python program (and output) below might help:
```
```python
>>> for i in range(1,45):
... print(f'GPIO:{i} mask:{hex(2**i)}')
...
@ -123,66 +114,66 @@ GPIO:43 mask:0x80000000000
GPIO:44 mask:0x100000000000
```
### How to easily test GPIO operations?
## Testing GPIO Operations
You can add a simple LED and resistor to validate that the GPIO operations work as expected. Used the tutorial at https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/ as a guide.
You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [Python API](/docs/software/python/cli/installation) documentation for more details.
Need:
You can add a simple LED and resistor to validate that the GPIO operations work as expected. Use [this tutorial](https://www.instructables.com/Slide-Switch-With-Arduino-Uno-R3/) as a guide.
- 2 Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it)
- 2 wires (black and yellow; they can be any color but typically black is used for ground)
- breadboard (optional)
- 1 LED
- 1 220Ω resistor (somewhat optional, but recommended)
### Requirements
Prep:
- (x2) Meshtastic devices (one device could be on a local computer, and the other one just has to be powered and is the one with the LED to be connected to it)
- (x2) wires (black and yellow; they can be any color but typically black is used for ground)
- (x1) LED
- (x1) 220Ω resistor (somewhat optional, but recommended)
- (x1) Breadboard (optional)
- disconnect the remote device from power (battery/usb)
- add a resistor from yellow wire to the one end of the LED (either end of the resistor is ok, either end of the LED is ok)
- add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21)
- add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED
- power on the device
### Preparation
Validation:
By default, the pin may be "off" or "on". (It will most likely "off".) See the steps below for running commands. In the example of GPIO21, the mask would be 0x200000.
1. Disconnect the remote device from power (battery/usb)
2. Add a resistor from yellow wire to the one end of the LED (either end of the resistor is OK, either end of the LED is OK)
3. Add the yellow wire from a GPIO pin that will not cause any issues (ex: for TLoraV1, we can use GPIO21)
4. Add the black "ground" wire from the ground pin on the device (ex: for TLoraV1 it is the end pin next to the RST button) to the other end of the LED
5. Power on the device
[<img alt="T-Lora v1 with LED on GPIO 21" src="/img/LED_on_TLoraV1.jpg" style={{zoom:'25%'}} />](/img/LED_on_TLoraV1.jpg)
### Validation
### Doing GPIO operations
By default, the pin may be "off" or "on". (It will most likely "off".) See the steps below for running commands. In the example of GPIO21, the mask would be `0x200000`.
You can programmatically do operations from your own python code by using the Meshtastic `RemoteHardwareClient` class. See the [python API](/docs/software/python/cli/installation) documentation for more details.
![T-Lora v1 with LED on GPIO 21](/img/LED_on_TLoraV1.jpg)
### Using GPIOs from the python CLI
Writing a GPIO (ex: turn "on" GPIO4):
## Using GPIOs from the Python CLI
```shell title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest \!28979058
Connected to radio
Writing GPIO mask 0x10 with value 0x10 to !28979058
### Writing a GPIO
```shell title="Example: turning 'on' GPIO4"
meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest 28979058
# Connected to radio
# Writing GPIO mask 0x10 with value 0x10 to !28979058
```
Reading a GPIO (ex: read GPIO4):
### Reading a GPIO
```shell title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058
Connected to radio
Reading GPIO mask 0x10 from !28979058
GPIO read response gpio_value=16
```shell title="Example: read GPIO4"
meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest 28979058
# Connected to radio
# Reading GPIO mask 0x10 from !28979058
# GPIO read response gpio_value=16
```
:::note
If the mask and the gpio_value match, then the value is "on". If the gpio_value is 0, then the value is "off".
:::
Watching for GPIO changes (ex: watching GPIO4 for changes):
### Watching for GPIO Changes
```shell title="Expected output"
$ meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest \!28979058
Connected to radio
Watching GPIO mask 0x10 from !28979058
Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=16
Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=0
Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=16
< press ctrl-c to exit >
```shell title="Example: watching GPIO4 for changes"
meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest 28979058
# Connected to radio
# Watching GPIO mask 0x10 from !28979058
# Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=16
# Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=0
# Received RemoteHardware typ=GPIOS_CHANGED, gpio_value=16
# < press ctrl-c to exit >
```

2
docs/legal/index.mdx
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/about/overview/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/overview/encryption#summary-of-strengthsweaknesses-of-our-current-implementation) to determine risks you might face.
## Legal FAQ

2
docs/software/android/installation.mdx
View file

@ -1,5 +1,5 @@
---
id: android-installation
id: installation
title: Android Application Installation
sidebar_label: Installation
sidebar_position: 1

2
docs/software/android/usage.mdx
View file

@ -1,5 +1,5 @@
---
id: android-usage
id: usage
title: Android Application Usage
sidebar_label: Usage
sidebar_position: 2

2
docs/software/apple/usage.mdx
View file

@ -1,5 +1,5 @@
---
id: apple-apps-usage
id: usage
title: Apple Application Usage
sidebar_label: Usage
---

10
docs/software/community/index.mdx Normal file
View file

@ -0,0 +1,10 @@
---
title: Community
slug: /community
sidebar_label: Community
sidebar_position: 10
---
## Simulator
- https://github.com/GUVWAF/Meshtasticator

4
docs/software/python-flasher.mdx
View file

@ -91,12 +91,14 @@ sudo apt install -y python3 python3-pip python3-venv
</Tabs>
### Install App
### Install or Upgrade App
For **Windows**, the [installer](https://github.com/meshtastic/Meshtastic-gui-installer/releases/download/winapp1.0.3/meshtastic-flasher.zip) will manage installing python and flasher updates automatically.
For **macOS** and **Linux**, it is recommended that you install using `pip`.
Note: Update an existing installation using `pip install meshtastic-flasher -U`
<Tabs
groupId="operating-system"
defaultValue="linux"

2
protobufs

@ -1 +1 @@
Subproject commit a0fe9ec8614cd27af7691869ccbd20c39e48a086
Subproject commit 6b46e42a656dd3aab74c373e79b70e699eeac834

2
src/pages/c/index.md
View file

@ -6,4 +6,4 @@ sidebar_label: c
# Error : Something happened
Please go to [Android Usage](/docs/software/android/android-usage#join-a-channel) for more information.
Please go to [Android Usage](/docs/software/android/usage#join-a-channel) for more information.

2
src/pages/d/index.md
View file

@ -6,4 +6,4 @@ sidebar_label: d
# Error : Something happened
Please go to [Android Usage](/docs/software/android/android-usage#join-a-channel) for more information.
Please go to [Android Usage](/docs/software/android/usage#join-a-channel) for more information.