Skip to content

Add companion message TX lifecycle events#2974

Draft
axhoff wants to merge 1 commit into
meshcore-dev:devfrom
axhoff:feature/companion-message-lifecycle
Draft

Add companion message TX lifecycle events#2974
axhoff wants to merge 1 commit into
meshcore-dev:devfrom
axhoff:feature/companion-message-lifecycle

Conversation

@axhoff

@axhoff axhoff commented Jul 17, 2026

Copy link
Copy Markdown

Summary

  • add a version-gated companion push event for the local radio TX outcome of ACK-tracked direct messages
  • correlate queued messages to Dispatcher TX callbacks using the full packet hash internally and the existing expected-ACK tag on the companion wire
  • distinguish local TX completion, definite start failure, and completion timeout/unknown outcome
  • preserve the existing send-accepted response and end-to-end ACK confirmation
  • document protocol v14 and add native Dispatcher lifecycle tests

Why

An ACK timeout does not prove that a direct message was not delivered: the message may have reached the recipient while only the returning ACK was lost. Today clients cannot also tell whether the message was still queued or whether the local radio actually completed its transmission.

This adds the missing local lifecycle signal so v14 clients can start the ACK timer after radio TX completion and present an expired ACK wait as delivery unconfirmed, rather than definite failure.

Protocol

Protocol v14 adds PACKET_SEND_TX_STATUS (0x91):

Byte 0:    0x91
Bytes 1-4: expected ACK / message tag
Byte 5:    local TX status

Statuses are:

  • 0: the local radio driver reported transmission complete
  • 1: the local radio rejected the transmission before it started
  • 2: completion was not reported before the firmware timeout; the over-air outcome is unknown

The timeout status deliberately retains the expected-ACK entry so a late ACK can still confirm delivery. A completed transmission is not downgraded by a later failed retry.

Compatibility and scope

  • no LoRa packet or routing wire-format changes
  • no ACK generation, retry, or routing behavior changes
  • no new frames for clients negotiating protocol v13 or lower
  • limited to plaintext, ACK-tracked contact direct messages; CLI and channel messages are unchanged
  • fixed-size storage only; no dynamic allocation is introduced
  • companion apps must adopt protocol v14 to expose the richer UI lifecycle

Validation

  • pio test -e native: 16/16 tests passed
  • pio run -e Heltec_v3_companion_radio_ble: passed (ESP32)
  • pio run -e RAK_4631_companion_radio_ble: passed (nRF52)
  • pio run -e waveshare_rp2040_lora_companion_radio_usb: passed (RP2040)
  • pio run -e wio-e5_companion_radio_usb: passed (STM32)
  • git diff --check: clean

Refs #1834

Design discussion: #1834 (comment)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant