Skip to content

Commit b475bde

Browse files
mikecarpermikecarper
committed
Unify retry preset settings
1 parent ae67293 commit b475bde

5 files changed

Lines changed: 437 additions & 125 deletions

File tree

‎docs/cli_commands.md‎

Lines changed: 21 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -570,22 +570,22 @@ This document provides an overview of CLI commands that can be sent to MeshCore
570570

571571
---
572572

573-
#### View or change the direct retry timing preset
573+
#### View or change the retry preset
574574
**Usage:**
575-
- `get direct.retry.preset`
576-
- `set direct.retry.preset <value>`
575+
- `get retry.preset`
576+
- `set retry.preset <value>`
577577

578578
**Parameters:**
579579
- `value`: `infra`|`rooftop`|`mobile` or `0`|`1`|`2`
580580

581581
**Default:** `rooftop` (`1`)
582582

583583
**Presets:**
584-
- `infra` (`0`): `275 ms` base wait, `4` retries, `150 ms` added per retry, SNR gate is SF floor + `15 dB`
585-
- `rooftop` (`1`): `175 ms` base wait, `15` retries, `100 ms` added per retry, SNR gate is SF floor + `5 dB`
586-
- `mobile` (`2`): `175 ms` base wait, `15` retries, `50 ms` added per retry, SNR gate is the SF floor
584+
- `infra` (`0`): `275 ms` direct base wait, `4` direct retries, `150 ms` added per direct retry, SNR gate is SF floor + `15 dB`; flood retry defaults to `1` retry and path gate `1`
585+
- `rooftop` (`1`): `175 ms` direct base wait, `15` direct retries, `100 ms` added per direct retry, SNR gate is SF floor + `5 dB`; flood retry defaults to `3` retries and path gate `2`
586+
- `mobile` (`2`): `175 ms` direct base wait, `15` direct retries, `50 ms` added per direct retry, SNR gate is the SF floor; flood retry defaults to `3` retries and path gate `1`
587587

588-
**Note:** Selecting a preset copies those values into the direct retry settings and also resets flood retry defaults. You can refine `direct.retry.margin`, `direct.retry.count`, `direct.retry.base`, `direct.retry.step`, `flood.retry.count`, or `flood.retry.path` afterward. Retry delay is `direct.txdelay` jitter + base wait + packet-length airtime wait + per-attempt step.
588+
**Note:** Selecting a preset copies those values into the direct retry settings and resets flood retry defaults. You can refine `direct.retry.margin`, `direct.retry.count`, `direct.retry.base`, `direct.retry.step`, `flood.retry.count`, or `flood.retry.path` afterward. Retry delay is `direct.txdelay` jitter + base wait + packet-length airtime wait + per-attempt step.
589589

590590
---
591591

@@ -754,23 +754,6 @@ This document provides an overview of CLI commands that can be sent to MeshCore
754754

755755
---
756756

757-
#### View or change the flood retry preset
758-
**Usage:**
759-
- `get flood.retry.preset`
760-
- `set flood.retry.preset <value>`
761-
762-
**Parameters:**
763-
- `value`: `infra`|`rooftop`|`mobile` or `0`|`1`|`2`
764-
765-
**Presets:**
766-
- `infra` (`0`): `1` retry, path gate `1`
767-
- `rooftop` (`1`): `3` retries, path gate `2`
768-
- `mobile` (`2`): `3` retries, path gate `1`
769-
770-
**Note:** This applies only the flood retry defaults. `set direct.retry.preset` also resets these flood retry defaults.
771-
772-
---
773-
774757
#### View or change the number of flood retry attempts
775758
**Usage:**
776759
- `get flood.retry.count`
@@ -797,6 +780,20 @@ This document provides an overview of CLI commands that can be sent to MeshCore
797780

798781
---
799782

783+
#### View or change whether advert packets are flood-retried
784+
**Usage:**
785+
- `get flood.retry.advert`
786+
- `set flood.retry.advert <state>`
787+
788+
**Parameters:**
789+
- `state`: `on` or `off`
790+
791+
**Default:** `off`
792+
793+
**Note:** When this is `off`, node advert packets (`PAYLOAD_TYPE_ADVERT`, type `4`) are not queued for flood retry.
794+
795+
---
796+
800797
#### View or change flood retry target prefixes
801798
**Usage:**
802799
- `get flood.retry.prefixes`

‎docs/halo_keymind_settings.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# Halo and Keymind Branch Settings
2+
3+
This file covers only CLI settings added by the Halo or Keymind branches. Use
4+
`docs/cli_commands.md` for the general MeshCore CLI.
5+
6+
## Quick Start
7+
8+
Use this baseline when bringing a Halo or Keymind repeater onto the network:
9+
10+
```text
11+
set retry.preset rooftop
12+
set direct.retry.heard on
13+
set flood.retry.advert off
14+
set flood.retry.bridge off
15+
set flood.retry.prefixes none
16+
set flood.retry.ignore none
17+
```
18+
19+
Then verify:
20+
21+
```text
22+
get retry.preset
23+
get direct.retry.heard
24+
get flood.retry.advert
25+
get flood.retry.prefixes
26+
get flood.retry.ignore
27+
```
28+
29+
Use prefixes from debug logs such as `path=7773D0>BEEBB0` or `heard=C7618C`. Prefix lists are comma-separated hex values, for example `71CE82,C7618C`.
30+
31+
## Prefix Worksheet
32+
33+
Keep Halo and Keymind prefixes in one place before programming buckets or ignore lists.
34+
35+
| Network | Prefix | Node or site | Use | Notes |
36+
| --- | --- | --- | --- | --- |
37+
| Halo | `A1B2C3` | example remote relay | bucket/target | Replace with real prefix |
38+
| Keymind | `71CE82` | example observed relay | ignore/target | Replace with real prefix |
39+
| Keymind | `C7618C` | example observed relay | ignore/target | Replace with real prefix |
40+
41+
## Common Examples
42+
43+
Disable retrying advert packets:
44+
45+
```text
46+
set flood.retry.advert off
47+
get flood.retry.advert
48+
```
49+
50+
Ignore a relay as a successful flood retry echo:
51+
52+
```text
53+
set flood.retry.ignore 71CE82,C7618C
54+
get flood.retry.ignore
55+
```
56+
57+
Only accept specific downstream relays as flood retry success:
58+
59+
```text
60+
set flood.retry.prefixes BEEBB0,425E5C
61+
get flood.retry.prefixes
62+
```
63+
64+
Bridge two groups of repeaters:
65+
66+
```text
67+
set flood.retry.bridge on
68+
set flood.retry.bucket 1 71CE82,C7618C
69+
set flood.retry.bucket 2 BEEBB0,425E5C
70+
get flood.retry.bucket.1
71+
get flood.retry.bucket.2
72+
```
73+
74+
Return to simple non-bridge flood retry:
75+
76+
```text
77+
set flood.retry.bridge off
78+
set flood.retry.prefixes none
79+
set flood.retry.ignore none
80+
```
81+
82+
## Added Settings
83+
84+
| Setting | What it does | How to use | Example |
85+
| --- | --- | --- | --- |
86+
| `recent.repeater` | Shows or seeds the recent repeater prefix/SNR table used by direct retry and bridge freshness checks. | `get recent.repeater`, `get recent.repeater <page>`, `set recent.repeater <prefix> <snr_db>` | `set recent.repeater A1B2C3 -8.5` |
87+
| `radio.fem.rxgain` | Controls the external LoRa FEM receive-path LNA where the board supports it. | `get radio.fem.rxgain`, `set radio.fem.rxgain on/off` | `set radio.fem.rxgain on` |
88+
89+
## Recent Repeater Table
90+
91+
Direct retry uses the recent repeater table when `direct.retry.heard` is `on`.
92+
Bridge buckets also use this table: a configured bucket prefix is active only
93+
when it was heard within the last hour.
94+
95+
Show learned rows:
96+
97+
```text
98+
get recent.repeater
99+
get recent.repeater 2
100+
```
101+
102+
Seed or correct a prefix:
103+
104+
```text
105+
set recent.repeater A1B2C3 -8.5
106+
```
107+
108+
Rows are sorted by prefix width, then SNR. A full direct retry failure lowers
109+
the matching row by `0.25 dB`.
110+
111+
## Direct Retry Settings
112+
113+
Direct retry applies to direct-routed packets. A queued resend is canceled when the next-hop echo is heard.
114+
115+
| Setting | What it does | How to use | Example |
116+
| --- | --- | --- | --- |
117+
| `retry.preset` | Applies shared direct and flood retry defaults. Values: `infra`, `rooftop`, `mobile` or `0`, `1`, `2`. | `get retry.preset`, `set retry.preset <value>` | `set retry.preset rooftop` |
118+
| `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` |
119+
| `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` |
120+
| `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` |
121+
| `direct.retry.base` | Base wait in milliseconds before retry. | `get direct.retry.base`, `set direct.retry.base <10-5000>` | `set direct.retry.base 175` |
122+
| `direct.retry.step` | Milliseconds added per retry attempt. | `get direct.retry.step`, `set direct.retry.step <0-5000>` | `set direct.retry.step 100` |
123+
124+
Preset details:
125+
126+
| Preset | Base | Count | Step | SNR gate |
127+
| --- | ---: | ---: | ---: | --- |
128+
| `infra` | `275 ms` | `4` | `150 ms` | SF floor + `15 dB` |
129+
| `rooftop` | `175 ms` | `15` | `100 ms` | SF floor + `5 dB` |
130+
| `mobile` | `175 ms` | `15` | `50 ms` | SF floor |
131+
132+
Example for a quiet fixed repeater:
133+
134+
```text
135+
set retry.preset rooftop
136+
set direct.retry.heard on
137+
set direct.retry.margin 5
138+
```
139+
140+
Example for a moving or weak-link node:
141+
142+
```text
143+
set retry.preset mobile
144+
set direct.retry.margin 0
145+
```
146+
147+
## Flood And Advert Settings
148+
149+
Flood retry applies to flood-routed packets. A queued retry is canceled when a qualifying downstream echo is heard.
150+
151+
| Setting | What it does | How to use | Example |
152+
| --- | --- | --- | --- |
153+
| `flood.retry.count` | Maximum flood retry attempts after initial TX. `0` disables flood retry. | `get flood.retry.count`, `set flood.retry.count <0-3>` | `set flood.retry.count 3` |
154+
| `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` |
155+
| `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` |
156+
| `flood.retry.prefixes` | Target prefixes. If set, only matching downstream echoes cancel a retry. | `get flood.retry.prefixes`, `set flood.retry.prefixes <prefixes/none/off>` | `set flood.retry.prefixes BEEBB0,425E5C` |
157+
| `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 <prefixes/none/off>` | `set flood.retry.ignore 71CE82,C7618C` |
158+
| `flood.retry.bridge` | Enables bucket-based bridge retry logic. | `get flood.retry.bridge`, `set flood.retry.bridge on/off` | `set flood.retry.bridge on` |
159+
| `flood.retry.bucket.<n>` | Shows one bridge bucket. Buckets are numbered `1`-`6`. | `get flood.retry.bucket.<n>` | `get flood.retry.bucket.1` |
160+
| `flood.retry.bucket` | Sets bridge bucket prefixes. | `set flood.retry.bucket <1-6> <prefixes/none/off>` | `set flood.retry.bucket 1 71CE82,C7618C` |
161+
162+
The shared retry preset sets these flood defaults:
163+
164+
| Preset | Retry count | Path gate |
165+
| --- | ---: | ---: |
166+
| `infra` | `1` | `1` |
167+
| `rooftop` | `3` | `2` |
168+
| `mobile` | `3` | `1` |
169+
170+
Example for Keymind path-gated retry:
171+
172+
```text
173+
set retry.preset rooftop
174+
set flood.retry.path 1
175+
set flood.retry.advert off
176+
set flood.retry.ignore 71CE82,C7618C
177+
```
178+
179+
Example for Halo targeted retry:
180+
181+
```text
182+
set flood.retry.bridge off
183+
set flood.retry.prefixes A1B2C3,D4E5F6
184+
set flood.retry.ignore none
185+
```
186+
187+
Example for Halo/Keymind bridge retry:
188+
189+
```text
190+
set flood.retry.bridge on
191+
set flood.retry.bucket 1 A1B2C3,D4E5F6
192+
set flood.retry.bucket 2 71CE82,C7618C
193+
set flood.retry.advert off
194+
```
195+
196+
## North South Buckets
197+
198+
Buckets describe groups of repeaters on different sides of this relay. Bucket
199+
numbers do not have built-in meanings; this example uses bucket `1` for North
200+
and bucket `2` for South.
201+
202+
```text
203+
North bucket 1
204+
+-----------------------+
205+
| A1B2C3 D4E5F6 |
206+
| North A North B |
207+
+-----------+-----------+
208+
|
209+
v
210+
+-----------+
211+
| This node |
212+
+-----------+
213+
^
214+
|
215+
+-----------+-----------+
216+
| 71CE82 C7618C |
217+
| South A South B |
218+
+-----------------------+
219+
South bucket 2
220+
```
221+
222+
Configure the buckets:
223+
224+
```text
225+
set flood.retry.bridge on
226+
set flood.retry.bucket 1 A1B2C3,D4E5F6
227+
set flood.retry.bucket 2 71CE82,C7618C
228+
set flood.retry.ignore none
229+
```
230+
231+
Packet heard from the North:
232+
233+
```text
234+
heard source
235+
|
236+
v
237+
+--------------+ retry targets
238+
| North bucket | -----> South bucket
239+
| bucket 1 | -----> Other fresh/unbucketed relays
240+
+--------------+
241+
```
242+
243+
Packet heard from the South:
244+
245+
```text
246+
heard source
247+
|
248+
v
249+
+--------------+ retry targets
250+
| South bucket | -----> North bucket
251+
| bucket 2 | -----> Other fresh/unbucketed relays
252+
+--------------+
253+
```
254+
255+
Packet heard from an unbucketed or pathless source:
256+
257+
```text
258+
heard source
259+
|
260+
v
261+
+--------------+ retry targets
262+
| Other bucket | -----> North bucket
263+
| implicit | -----> South bucket
264+
+--------------+
265+
```
266+
267+
Bridge retry stays eligible until every target bucket has been heard or
268+
`flood.retry.count` is exhausted. A configured bucket is a target only when at
269+
least one of its prefixes is fresh in `recent.repeater`. Prefixes in
270+
`flood.retry.ignore` never count as bucket hits.
271+
272+
## Troubleshooting
273+
274+
If advert packets are still retrying:
275+
276+
```text
277+
get flood.retry.advert
278+
set flood.retry.advert off
279+
```
280+
281+
If ignored prefixes still appear in `flood retry good` logs:
282+
283+
```text
284+
get flood.retry.ignore
285+
set flood.retry.ignore <prefix>
286+
```
287+
288+
The ignored prefix must match the last hop shown as `heard=<prefix>`. For example, this log needs `C7618C` in the ignore list:
289+
290+
```text
291+
flood retry good (... path=7773D0>C7618C, heard=C7618C ...)
292+
```
293+
294+
If retries are too aggressive:
295+
296+
```text
297+
set flood.retry.count 1
298+
set flood.retry.path 1
299+
set direct.retry.count 4
300+
```
301+
302+
If retries are too sparse:
303+
304+
```text
305+
set retry.preset rooftop
306+
set flood.retry.count 3
307+
set flood.retry.path 2
308+
```

0 commit comments

Comments
 (0)