Add Companion Selective Repeat Ability (CSRA)

[copelaje]

Background

There are plenty of situations where you want a well-positioned companion (always powered, good antenna) to extend the reach of another device stuck in poor coverage, but only for your own traffic. A roof-mounted companion covering a pocket device that ducks into a store is one example.

The existing options don't fit. The built-in client_repeat mode repeats everything for everybody, and critically, it requires moving off your normal companion frequency onto a dedicated repeater band. The common community workaround, a "car-peater" or mobile repeater, also introduces trouble in that it isn't selective and thus can create known paths that are transient and unstable for many users.

Proposed Solution

This PR adds a third option alongside the two that exist today. off repeats nothing and all repeats everything on a dedicated repeater frequency, both unchanged. The new selective mode repeats only traffic on your allowlist and stays on your normal companion frequency. I'm calling the capability CSRA, Companion Selective Repeat Ability, a nod to the CSRA mesh region (Central Savannah River Area) I'm building out near Augusta GA, USA. I'm definitely open to alternate methods of indicating allowlist should the community decide that is a good path to not overload use of favorites.

As implemented, the allowlist reuses the existing favorite flag on contacts, so there's no new setting to manage and the capability works without companion app updates. You mark the contacts you want selectively repeated, and it also repeats the specific group channels you already carry.

Limiting impact on the larger mesh

This was the central design consideration, so I want to address it head on. A repeater that isn't selective is a burden on the mesh. Every flood it hears it rebroadcasts, and that retransmission consumes airtime every nearby node has to wait through. CSRA is built specifically to avoid that. It rebroadcasts a message only when the source contact is on your allowlist, or the message is on a channel you carry. Everything else is dropped with no retransmission at all. The practical result is that a CSRA node adds essentially no flood traffic to the mesh beyond the specific conversations its owner has opted into. That is a real improvement over an all-mode car-peater sitting in the same location and rebroadcasting indiscriminately.

The same selectivity keeps the node from quietly turning into a general next-hop for unrelated routed traffic. It will only relay along paths it created for allowlisted conversations, and it forwards nothing else.

What gets repeated

Traffic moves in two directions. Outbound is a message leaving your device toward the wider mesh. Inbound is the reply coming back.

On the outbound side, a direct message involving a favorited contact gets repeated, and so does a group message on a channel you carry on the CSRA enabled companion. Anything else, meaning a message from a contact you haven't favorited or on a channel you don't carry, is ignored and not repeated.

On the inbound side, the reply or acknowledgement heading back to you is forwarded even though the far party is not on your allowlist. The return arrives in one of two ways. Once the node has built a path, the reply comes back along that path, and dropping it would break the route the node created. Before any path exists, which is the usual case while your device is shielded behind the node, the reply arrives as a flood addressed to your device. The node recognizes your device as the destination and repeats it, and that repeated flood is what lets the return path be found so the acknowledgement gets home. Traffic that is not part of one of your conversations is ignored here as well.

Three implementation points for reviewers. First, when the node repeats one of your messages it inserts itself into the message path. That is what gives the reply a way back. Without it the message goes out but the acknowledgement has nowhere to return, and the DM looks like it silently failed. Second, the allowlist check looks at both ends of a message, the sender and the recipient, rather than the sender alone. A favorited device is amplified whether it is sending a flood out or receiving one back, and that second case is what carries the first acknowledgement home before any path exists. Third, the node only steps in when a message is actually flooding. If your device already knows a direct route to a contact, that message does not need help and the node leaves it untouched. CSRA engages precisely when coverage is poor and the device has fallen back to flooding.

Testing

I verified all cases DM/flood worked (and didn't work) as expected by flashing KISS on a device and watching all the raw OTA packets traversing through the various cases in a "bench test" scenario. I and other have also field tested the firmware and found the capability works as intended (see "test yourself! section below).

Companion tooling

There is a companion-side piece, a new command to set the repeat mode, that I have ready in meshcore_py and meshcore-cli. I am holding those until there is intent to merge this firmware change, and they will need to be coordinated with a client app update as well.

Test yourself!

Given there is no current client app support, I've gone ahead and built CSRA auto-enabled companion firmware for all supported devices available here: https://github.com/copelaje/MeshCore/releases If you flash these, these your companion will behave in the manner described above for personal testing purposes. Long term my intent is that this mode be selectable within client apps (see "Companion tooling" above. I'm happy to provide MRs and coordinate in this regard.

[copelaje]

I've attempted to engage devs in the #development channel on meshcore.io discord but haven't received any response. I recall someone attempting this on the old discord, but don't think that topic started again in the split. I may add one for discussion on this if needed. There are already several "issues" regarding a capability like this #2261 #2396 #2599

Lets see if we can get a workable solution!