diff --git a/docs/halo_keymind_settings.md b/docs/halo_keymind_settings.md deleted file mode 100644 index ca2c08032..000000000 --- a/docs/halo_keymind_settings.md +++ /dev/null @@ -1,361 +0,0 @@ -# Halo and Keymind Branch Settings - -This file covers only CLI settings and helper commands added by the Halo or -Keymind branches. Use `docs/cli_commands.md` for the general MeshCore CLI. - -## Quick Start - -```text -set retry.preset rooftop -set direct.retry.heard on -set flood.retry.advert off -set flood.retry.bridge off -set flood.retry.prefixes none -set flood.retry.ignore none -``` - -Then verify: - -```text -get retry.preset -get direct.retry.heard -get flood.retry.advert -get flood.retry.prefixes -get flood.retry.ignore -``` - -Use prefixes from the analyzer or neighbors list or `get recent.repeater` after the repeater has been online for a few hours. - -## Common Examples - -Disable retrying advert packets: - -```text -set flood.retry.advert off -get flood.retry.advert -``` - -Ignore a repeater as a successful flood retry echo: -Use this if you have a car repeater and a house repeater; have the house ignore the car. - -```text -set flood.retry.ignore 71CE82,C7618C -get flood.retry.ignore -``` - -Only accept specific downstream relays as flood retry success: -You're in a hole and need to hit a mountain top repeater to get out; keep trying till one you see one of these send out your packet. - -```text -set flood.retry.prefixes A58296,860CCA,425E5C -get flood.retry.prefixes -``` - -Bridge two groups of repeaters: - -```text -set flood.retry.bridge on -set flood.retry.bucket 1 71CE82,C7618C -set flood.retry.bucket 2 BEEBB0,425E5C -get flood.retry.bucket.1 -get flood.retry.bucket.2 -``` - -Return to simple non-bridge flood retry: - -```text -set flood.retry.bridge off -set flood.retry.prefixes none -set flood.retry.ignore none -``` - -## Added Settings - -| Setting | What it does | How to use | Example | -| --- | --- | --- | --- | -| `battery.alert` | Sends opt-in low-battery warnings to `#repeaters`. | `get battery.alert`, `set battery.alert on/off` | `set battery.alert on` | -| `battery.alert.low` | Warning threshold percentage. Must be greater than `battery.alert.critical`. | `get battery.alert.low`, `set battery.alert.low <1-100>` | `set battery.alert.low 20` | -| `battery.alert.critical` | Critical threshold percentage. Critical warnings repeat more often. | `get battery.alert.critical`, `set battery.alert.critical <0-99>` | `set battery.alert.critical 10` | -| `recent.repeater` | Shows, seeds, or clears the recent repeater prefix/SNR table used by direct retry and bridge freshness checks. | `get recent.repeater`, `get recent.repeater `, `set recent.repeater `, `clear recent.repeater` | `set recent.repeater A1B2C3 -8.5` | -| `outpath` | Overrides the primary direct route used for replies to the current remote client. | `get outpath`, `set outpath `, `set outpath direct`, `set outpath clear`, `set outpath flood` | `set outpath A1B2C3,D4E5F6` | -| `altpath` | Optional second direct route used for duplicate response attempts to the current remote client. | `get altpath`, `set altpath `, `set altpath clear` | `set altpath A1B2C3,D4E5F6` | - -## Other Keymind Commands - -| Command | What it does | How to use | Example | -| --- | --- | --- | --- | -| `send text.flood` | Sends a `#repeaters` flood text message formatted as `: `. | `send text.flood ` | `send text.flood checking ridge link` | - -## Battery Alerts - -Battery alerts are off by default. When enabled, the repeater checks once per -minute and sends a flood text warning to `#repeaters` when voltage is above -`1 V` and the estimated battery percent is below `battery.alert.low`. - -Warnings repeat every `24` hours, or every `12` hours when the estimate is -below `battery.alert.critical`. - -Defaults: - -| Setting | Default | -| --- | ---: | -| `battery.alert` | `off` | -| `battery.alert.low` | `20` | -| `battery.alert.critical` | `10` | - -Example: - -```text -set battery.alert.low 20 -set battery.alert.critical 10 -set battery.alert on -get battery.alert -``` - -## Recent Repeater Table - -Direct retry uses the recent repeater table when `direct.retry.heard` is `on`. -Bridge buckets also use this table: a configured bucket prefix is active only -when it was heard within the last hour. - -Show learned rows: - -```text -get recent.repeater -get recent.repeater 2 -get recent.repeater page 3 -``` - -Seed or correct a prefix: - -```text -set recent.repeater A1B2C3 8.5 -``` - -Clear learned and manually seeded rows: - -```text -clear recent.repeater -``` - -Rows are sorted by prefix width, then SNR. A full direct retry failure lowers -the matching row by `0.25 dB`. - -Serial CLI pages contain up to `128` rows. Remote LoRa CLI pages contain up to -`7` rows. - -## Direct Path Overrides - -`outpath` and `altpath` apply to the current remote client ACL entry. They need -remote client context, so they are not useful from the local serial CLI. - -Set paths with comma-separated hop hashes. Each hop must be `2`, `4`, or `6` -hex characters, and all hops in one path must use the same width. - -```text -get outpath -set outpath A1B2C3,D4E5F6 -set outpath direct -set outpath clear -set outpath flood - -get altpath -set altpath A1B2C3,D4E5F6 -set altpath clear -``` - -`set outpath direct` sets a zero-hop direct route for a client reachable without -repeaters. `set outpath clear` forgets the override and lets normal path -discovery fill it again. `set outpath flood` forces replies to use flood packets -until the client logs in again. `altpath` sends a duplicate reply over a second -direct route; clearing it returns replies to a single route. - -## Direct Retry Settings - -Direct retry applies to direct-routed packets. A queued resend is canceled when the next-hop echo is heard. - -| Setting | What it does | How to use | Example | -| --- | --- | --- | --- | -| `retry.preset` | Applies shared direct and flood retry defaults. Values: `infra`, `rooftop`, `mobile` or `0`, `1`, `2`. | `get retry.preset`, `set retry.preset ` | `set retry.preset rooftop` | -| `direct.retry.heard` | Uses the recent repeater table as the direct retry eligibility gate. | `get direct.retry.heard`, `set direct.retry.heard on/off` | `set direct.retry.heard on` | -| `direct.retry.margin` | SNR margin in dB above the SF-specific receive floor. | `get direct.retry.margin`, `set direct.retry.margin <0-40>` | `set direct.retry.margin 5` | -| `direct.retry.count` | Maximum direct retry attempts after initial TX. | `get direct.retry.count`, `set direct.retry.count <1-15>` | `set direct.retry.count 15` | -| `direct.retry.base` | Base wait in milliseconds before retry. | `get direct.retry.base`, `set direct.retry.base <10-5000>` | `set direct.retry.base 175` | -| `direct.retry.step` | Milliseconds added per retry attempt. | `get direct.retry.step`, `set direct.retry.step <0-5000>` | `set direct.retry.step 100` | -| `direct.retry.cr` | Adaptive coding-rate thresholds for direct retry packets. Uses `CR4`, `CR5`, `CR7`, or `CR8`; `CR6` is never selected. | `get direct.retry.cr`, `set direct.retry.cr ,,,`, `set direct.retry.cr off` | `set direct.retry.cr 10.0,7.5,2.5,0` | - -The default adaptive coding-rate profile is `10.0,7.5,2.5,2.5`. -SNR `10.0 dB` and up uses `CR4`, `7.5 dB` and up uses `CR5`, -`2.5 dB` and down uses `CR8`, and the middle band uses `CR7`. If no -recent repeater table entry is available, retry packets use `CR5`. Use -`set direct.retry.cr off` to disable adaptive coding-rate overrides. If -adaptive selection chooses `CR4`, retries after the third attempt use -`CR5`. - -Preset details: - -| Preset | Base | Count | Step | SNR gate | -| --- | ---: | ---: | ---: | --- | -| `infra` | `275 ms` | `4` | `150 ms` | SF floor + `15 dB` | -| `rooftop` | `175 ms` | `15` | `100 ms` | SF floor + `5 dB` | -| `mobile` | `175 ms` | `15` | `50 ms` | SF floor | - -Example for a quiet fixed repeater: - -```text -set retry.preset rooftop -set direct.retry.heard on -set direct.retry.margin 5 -``` - -Example for a moving or weak-link node: - -```text -set retry.preset mobile -set direct.retry.margin 0 -``` - -## Flood And Advert Settings - -Flood retry applies to flood-routed packets. A queued retry is canceled when a qualifying downstream echo is heard. - -| Setting | What it does | How to use | Example | -| --- | --- | --- | --- | -| `flood.retry.count` | Maximum flood retry attempts after initial TX. `0` disables flood retry. | `get flood.retry.count`, `set flood.retry.count <0-15>` | `set flood.retry.count 7` | -| `flood.retry.path` | Maximum path hash count eligible for flood retry, or `off` to disable the gate. | `get flood.retry.path`, `set flood.retry.path <0-63/off>` | `set flood.retry.path 1` | -| `flood.retry.advert` | Allows or blocks retry for node advert packets (`type=4`). Default is `off`. | `get flood.retry.advert`, `set flood.retry.advert on/off` | `set flood.retry.advert off` | -| `flood.retry.prefixes` | Target prefixes. If set, only matching downstream echoes cancel a retry. | `get flood.retry.prefixes`, `set flood.retry.prefixes ` | `set flood.retry.prefixes BEEBB0,425E5C` | -| `flood.retry.ignore` | Ignored prefixes. In non-bridge retry, ignored last-hop echoes do not cancel retry. | `get flood.retry.ignore`, `set flood.retry.ignore ` | `set flood.retry.ignore 71CE82,C7618C` | -| `flood.retry.bridge` | Enables bucket-based bridge retry logic. | `get flood.retry.bridge`, `set flood.retry.bridge on/off` | `set flood.retry.bridge on` | -| `flood.retry.bucket.` | Shows one bridge bucket. Buckets are numbered `1`-`6`. | `get flood.retry.bucket.` | `get flood.retry.bucket.1` | -| `flood.retry.bucket` | Sets bridge bucket prefixes. | `set flood.retry.bucket <1-6> ` | `set flood.retry.bucket 1 71CE82,C7618C` | - -The shared retry preset sets these flood defaults: - -| Preset | Retry count | Path gate | -| --- | ---: | ---: | -| `infra` | `1` | `1` | -| `rooftop` | `3` | `2` | -| `mobile` | `3` | `1` | - -Example for path-gated retry: - -```text -set retry.preset rooftop -set flood.retry.path 1 -set flood.retry.advert off -set flood.retry.ignore 71CE82,C7618C -``` - -## North South Buckets - -Buckets describe groups of repeaters on different sides of this relay. Bucket -numbers do not have built-in meanings; this example uses bucket `1` for North -and bucket `2` for South. - -```text - North bucket 1 - +-----------------------+ - | A1B2C3 D4E5F6 | - | North A North B | - +-----------+-----------+ - | - v - +-----------+ - | This node | - +-----------+ - ^ - | - +-----------+-----------+ - | 71CE82 C7618C | - | South A South B | - +-----------------------+ - South bucket 2 -``` - -Configure the buckets: - -```text -set flood.retry.bridge on -set flood.retry.bucket 1 A1B2C3,D4E5F6 -set flood.retry.bucket 2 71CE82,C7618C -set flood.retry.ignore none -``` - -Packet heard from the North: - -```text - heard source - | - v - +--------------+ retry targets - | North bucket | -----> South bucket - | bucket 1 | -----> Other fresh/unbucketed relays - +--------------+ -``` - -Packet heard from the South: - -```text - heard source - | - v - +--------------+ retry targets - | South bucket | -----> North bucket - | bucket 2 | -----> Other fresh/unbucketed relays - +--------------+ -``` - -Packet heard from an unbucketed or pathless source: - -```text - heard source - | - v - +--------------+ retry targets - | Other bucket | -----> North bucket - | implicit | -----> South bucket - +--------------+ -``` - -Bridge retry stays eligible until every target bucket has been heard or -`flood.retry.count` is exhausted. A configured bucket is a target only when at -least one of its prefixes is fresh in `recent.repeater`. Prefixes in -`flood.retry.ignore` never count as bucket hits. - -## Troubleshooting - -If advert packets are still retrying: - -```text -get flood.retry.advert -set flood.retry.advert off -``` - -If ignored prefixes still appear in `flood retry good` logs: - -```text -get flood.retry.ignore -set flood.retry.ignore -``` - -The ignored prefix must match the last hop shown as `heard=`. For example, this log needs `C7618C` in the ignore list: - -```text -flood retry good (... path=7773D0>C7618C, heard=C7618C ...) -``` - -If retries are too aggressive: - -```text -set flood.retry.count 1 -set flood.retry.path 1 -set direct.retry.count 4 -``` - -If retries are too sparse: - -```text -set flood.retry.count 7 -set flood.retry.path 2 -``` diff --git a/docs/halo_settings.md b/docs/halo_settings.md new file mode 100644 index 000000000..9324487d2 --- /dev/null +++ b/docs/halo_settings.md @@ -0,0 +1,136 @@ +# Halo Direct Message Retry Settings + +This file covers only CLI settings and helper commands added for Halo direct-message retry behavior. Use `docs/cli_commands.md` for the general MeshCore CLI. + +Halo retry applies to direct-routed packets. A queued resend is canceled when the next-hop echo is heard. + +## Quick Start + +```text +set retry.preset rooftop +set direct.retry.heard on +get retry.preset +get direct.retry.heard +get direct.retry.count +get direct.retry.base +get direct.retry.step +``` + +Use prefixes from the analyzer, neighbors list, or `get recent.repeater` after the repeater has been online for a few hours. + +## Added Halo Settings + +| Setting | What it does | How to use | Example | +| --- | --- | --- | --- | +| `recent.repeater` | Shows, seeds, or clears the recent repeater prefix/SNR table used by direct retry. | `get recent.repeater`, `get recent.repeater `, `set recent.repeater `, `clear recent.repeater` | `set recent.repeater A1B2C3 -8.5` | +| `outpath` | Overrides the primary direct route used for replies to the current remote client. | `get outpath`, `set outpath `, `set outpath direct`, `set outpath clear`, `set outpath flood` | `set outpath A1B2C3,D4E5F6` | +| `altpath` | Optional second direct route used for duplicate response attempts to the current remote client. | `get altpath`, `set altpath `, `set altpath clear` | `set altpath A1B2C3,D4E5F6` | +| `retry.preset` | Applies direct retry defaults. Values: `infra`, `rooftop`, `mobile` or `0`, `1`, `2`. | `get retry.preset`, `set retry.preset ` | `set retry.preset rooftop` | +| `direct.retry.heard` | Uses the recent repeater table as the direct retry eligibility gate. | `get direct.retry.heard`, `set direct.retry.heard on/off` | `set direct.retry.heard on` | +| `direct.retry.margin` | SNR margin in dB above the SF-specific receive floor. | `get direct.retry.margin`, `set direct.retry.margin <0-40>` | `set direct.retry.margin 5` | +| `direct.retry.count` | Maximum direct retry attempts after initial TX. | `get direct.retry.count`, `set direct.retry.count <1-15>` | `set direct.retry.count 15` | +| `direct.retry.base` | Base wait in milliseconds before retry. | `get direct.retry.base`, `set direct.retry.base <10-5000>` | `set direct.retry.base 175` | +| `direct.retry.step` | Milliseconds added per retry attempt. | `get direct.retry.step`, `set direct.retry.step <0-5000>` | `set direct.retry.step 100` | +| `direct.retry.cr` | Adaptive coding-rate thresholds for direct retry packets. Uses `CR4`, `CR5`, `CR7`, or `CR8`; `CR6` is never selected. | `get direct.retry.cr`, `set direct.retry.cr ,,,`, `set direct.retry.cr off` | `set direct.retry.cr 10.0,7.5,2.5,0` | + +## Recent Repeater Table + +Direct retry uses the recent repeater table when `direct.retry.heard` is `on`. + +Show learned rows: + +```text +get recent.repeater +get recent.repeater 2 +get recent.repeater page 3 +``` + +Seed or correct a prefix: + +```text +set recent.repeater A1B2C3 8.5 +``` + +Clear learned and manually seeded rows: + +```text +clear recent.repeater +``` + +Rows are sorted by prefix width, then SNR. A full direct retry failure lowers the matching row by `0.25 dB`. + +Serial CLI pages contain up to `128` rows. Remote LoRa CLI pages contain up to `7` rows. + +## Direct Path Overrides + +`outpath` and `altpath` apply to the current remote client ACL entry. They need remote client context, so they are not useful from the local serial CLI. + +Set paths with comma-separated hop hashes. Each hop must be `2`, `4`, or `6` hex characters, and all hops in one path must use the same width. + +```text +get outpath +set outpath A1B2C3,D4E5F6 +set outpath direct +set outpath clear +set outpath flood + +get altpath +set altpath A1B2C3,D4E5F6 +set altpath clear +``` + +`set outpath direct` sets a zero-hop direct route for a client reachable without repeaters. `set outpath clear` forgets the override and lets normal path discovery fill it again. `set outpath flood` forces replies to use flood packets until the client logs in again. `altpath` sends a duplicate reply over a second direct route; clearing it returns replies to a single route. + +## Direct Retry Details + +The default adaptive coding-rate profile is `10.0,7.5,2.5,2.5`. SNR `10.0 dB` and up uses `CR4`, `7.5 dB` and up uses `CR5`, `2.5 dB` and down uses `CR8`, and the middle band uses `CR7`. If no recent repeater table entry is available, retry packets use `CR5`. + +Use `set direct.retry.cr off` to disable adaptive coding-rate overrides. If adaptive selection chooses `CR4`, retries after the third attempt use `CR5`. + +Preset details: + +| Preset | Base | Count | Step | SNR gate | +| --- | ---: | ---: | ---: | --- | +| `infra` | `275 ms` | `4` | `150 ms` | SF floor + `15 dB` | +| `rooftop` | `175 ms` | `15` | `100 ms` | SF floor + `5 dB` | +| `mobile` | `175 ms` | `15` | `50 ms` | SF floor | + +Example for a quiet fixed repeater: + +```text +set retry.preset rooftop +set direct.retry.heard on +set direct.retry.margin 5 +``` + +Example for a moving or weak-link node: + +```text +set retry.preset mobile +set direct.retry.margin 0 +``` + +## Troubleshooting + +If direct retries are too aggressive: + +```text +set direct.retry.count 4 +set direct.retry.margin 10 +``` + +If direct retries are too sparse: + +```text +set direct.retry.count 15 +set direct.retry.margin 0 +``` + +If direct retry is skipping a path you expect it to retry: + +```text +get direct.retry.heard +get recent.repeater +``` + +Either disable the heard gate with `set direct.retry.heard off`, or seed the next-hop prefix with `set recent.repeater `.