mirror of
https://github.com/meshtastic/meshtastic.git
synced 2024-11-09 23:24:10 -08:00
Resurrect Store&Forward documentation
This commit is contained in:
Thomas Göttgens
parent
ef2dd72105
commit
ba72737609
326
docs/configuration/module-config/store-and-forward-module.mdx
Normal file
326
docs/configuration/module-config/store-and-forward-module.mdx
Normal file
|
|
@ -0,0 +1,326 @@
|
|||
---
|
||||
id: store-and-forward-module
|
||||
title: Store & Forward Module Settings
|
||||
sidebar_label: Store & Forward Module
|
||||
---
|
||||
|
||||
import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
:::info
|
||||
Currently only available for ESP32 based devices with external PSRAM. Requires the device to be set as a ROUTER or ROUTER_CLIENT.
|
||||
|
||||
**Don't enable Store & Forward Module on multiple nodes.**
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
:::caution
|
||||
This is a work in progress and is partially available. Stability is not guaranteed.
|
||||
:::
|
||||
|
||||
The Store & Forward Module is an implementation of a Store and Forward system to enable resilient messaging in the event that a client device is disconnected from the main network.
|
||||
|
||||
Because of the increased network traffic for this overhead, it's not advised to use this if you are duty cycle limited for your airtime usage (EU_868 and EU_433) nor is it advised to use this for presets using SF11 or SF12 (e.g. all of the LongRange and VeryLongRange presets).
|
||||
|
||||
## Settings
|
||||
|
||||
| Setting | Acceptable Values | Default |
|
||||
| :---------------------------------: | :---------------: | :-----: |
|
||||
| store_forward.enabled | `true`, `false` | `false` |
|
||||
| store_forward.heartbeat | `true`, `false` | `false` |
|
||||
| store_forward.history_return_max | `integer` | `0` |
|
||||
| store_forward.history_return_window | `integer` | `0` |
|
||||
| store_forward.records | `integer` | `0` |
|
||||
|
||||
### store_forward.enabled
|
||||
|
||||
Enables the module.
|
||||
|
||||
<Tabs
|
||||
groupId="settings"
|
||||
defaultValue="cli"
|
||||
values={[
|
||||
{label: 'CLI', value: 'cli'},
|
||||
{label: 'Android', value: 'android'},
|
||||
{label: 'iOS', value: 'iOS'},
|
||||
{label: 'Web', value: 'web'},
|
||||
]}>
|
||||
<TabItem value="cli">
|
||||
|
||||
```shell title="Enable the module"
|
||||
meshtastic --set store_forward.enabled true
|
||||
```
|
||||
|
||||
```shell title="Disable the module"
|
||||
meshtastic --set store_forward.enabled false
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="android">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="iOS">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="web">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### store_forward.heartbeat
|
||||
|
||||
The Store & Forward Router sends a periodic message onto the network. This allows connected devices to know that a router is in range and listening to received messages. A client like Android, iOS, or Web can (if supported) indicate to the user whether a store and forward router is available.
|
||||
|
||||
<Tabs
|
||||
groupId="settings"
|
||||
defaultValue="cli"
|
||||
values={[
|
||||
{label: 'CLI', value: 'cli'},
|
||||
{label: 'Android', value: 'android'},
|
||||
{label: 'iOS', value: 'iOS'},
|
||||
{label: 'Web', value: 'web'},
|
||||
]}>
|
||||
<TabItem value="cli">
|
||||
|
||||
```shell title="Set store_forward.heartbeat to default"
|
||||
meshtastic --set store_forward.heartbeat 0
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="android">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="iOS">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="web">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### store_forward.history_return_max
|
||||
|
||||
Sets the maximum number of messages to return to a client device.
|
||||
|
||||
<Tabs
|
||||
groupId="settings"
|
||||
defaultValue="cli"
|
||||
values={[
|
||||
{label: 'CLI', value: 'cli'},
|
||||
{label: 'Android', value: 'android'},
|
||||
{label: 'iOS', value: 'iOS'},
|
||||
{label: 'Web', value: 'web'},
|
||||
]}>
|
||||
<TabItem value="cli">
|
||||
|
||||
```shell title="Set store_forward.history_return_max to default"
|
||||
meshtastic --set store_forward.history_return_max 0
|
||||
```
|
||||
|
||||
```shell title="Set store_forward.history_return_max to 100 messages"
|
||||
meshtastic --set store_forward.history_return_max 100
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="android">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="iOS">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="web">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### store_forward.history_return_window
|
||||
|
||||
Limits the time period (in minutes) a client device can request.
|
||||
|
||||
<Tabs
|
||||
groupId="settings"
|
||||
defaultValue="cli"
|
||||
values={[
|
||||
{label: 'CLI', value: 'cli'},
|
||||
{label: 'Android', value: 'android'},
|
||||
{label: 'iOS', value: 'iOS'},
|
||||
{label: 'Web', value: 'web'},
|
||||
]}>
|
||||
<TabItem value="cli">
|
||||
|
||||
```shell title="Set store_forward.history_return_window to default"
|
||||
meshtastic --set store_forward.history_return_window 0
|
||||
```
|
||||
|
||||
```shell title="Set store_forward.history_return_window to 1 day (1440 minutes)"
|
||||
meshtastic --set store_forward.history_return_window 1440
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="android">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="iOS">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="web">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### store_forward.records
|
||||
|
||||
Set this to the maximum number of records to save. Best to leave this at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
|
||||
|
||||
<Tabs
|
||||
groupId="settings"
|
||||
defaultValue="cli"
|
||||
values={[
|
||||
{label: 'CLI', value: 'cli'},
|
||||
{label: 'Android', value: 'android'},
|
||||
{label: 'iOS', value: 'iOS'},
|
||||
{label: 'Web', value: 'web'},
|
||||
]}>
|
||||
<TabItem value="cli">
|
||||
|
||||
```shell title="Set store_forward.records to default (≈11,000 records)"
|
||||
meshtastic --set store_forward.records 0
|
||||
```
|
||||
|
||||
```shell title="Set store_forward.records to 100 records"
|
||||
meshtastic --set store_forward.records 100
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="android">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="iOS">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="web">
|
||||
|
||||
:::info
|
||||
Configuring this setting is not yet available for the selected platform. If this is incorrect please update the documentation for this page.
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Details
|
||||
|
||||
### How it works
|
||||
|
||||
|
||||
|
||||
### Requirements
|
||||
|
||||
Initial Requirements:
|
||||
|
||||
- Must be installed on a ROUTER or ROUTER_CLIENT node.
|
||||
- This is an artificial limitation, but is in place to enforce best practices.
|
||||
- Router nodes are intended to be always online. If this module misses any messages, the reliability of the stored messages will be reduced.
|
||||
- ESP32 Processor based device with external PSRAM. (tbeam > v1.0, T3S3, and maybe others)
|
||||
|
||||
### Usage Overview
|
||||
|
||||
- To use / test this you will want at least 3 devices
|
||||
- One ESP32 device with PSRAM configured as a Meshtastic router.
|
||||
- Two others will be regular clients. Nothing special required.
|
||||
|
||||
### Meshtastic channel configuration
|
||||
|
||||
Don't use this on the "LongRange" channel settings. You're welcome to try and report back, but those channels have a [low bitrate](/docs/overview/radio-settings#pre-defined).
|
||||
|
||||
Either use a custom channel configuration with at an at least 1kbit data rate or use a Medium or Short range preset.
|
||||
|
||||
### Router setup
|
||||
|
||||
:::warning
|
||||
Don't enable the Store and Forward module on multiple nodes for now!
|
||||
:::
|
||||
|
||||
- Configure your device as a router.
|
||||
- Name your router node something that makes it easily identifiable, aka "Router".
|
||||
- Configure the Store and Forward module
|
||||
|
||||
```shell title="Required - Enable the module"
|
||||
meshtastic --set store_forward.enabled true
|
||||
```
|
||||
|
||||
```shell title="Optional - Set maximum number of records to save to device"
|
||||
meshtastic --set store_forward.records 100
|
||||
```
|
||||
|
||||
:::tip
|
||||
Best to leave `store_forward.records` at the default (`0`) where the module will use 2/3 of your device's available PSRAM. This is about 11,000 records.
|
||||
:::
|
||||
|
||||
### Client Usage
|
||||
|
||||
Currently, no special configuration is required. To request your history sent to you, send the command into the message field "SF". That's it. This will eventually change to make it easier. At the moment, that message will be sent to everyone on the mesh but we'll (eventually) make it easier to use where there'll be a button (or maybe it'll be transparent) and the command isn't sent as a text message to the mesh.
|
||||
|
||||
Available Commands:
|
||||
|
||||
| Command | Definition |
|
||||
| :-----: | :----------------------------------------------------: |
|
||||
| SF | Send the last hour worth of messages I may have missed |
|
||||
|
||||
The Store and Forward module will only service one client at a time. If a second client requests messages while the S&F is busy, the S&F will send a private message to the second client that they will need to wait.
|
||||
Loading…
Reference in a new issue