feat(remote-shell): PTY-over-mesh terminal with retro-CRT UI

Adds a full RemoteShell (portnum=13) implementation matching Jonathan's
dmshell_client.py protocol:

Protocol layer:
- Seq/ack reliability: incrementing seq on every non-ACK frame, piggybacked
  ack_seq, out-of-order frame buffering, gap detection and replay requests
- TX history ring buffer (last 50 frames) for retransmission on request
- ACK frames carry optional 4-byte big-endian REPLAY_REQUEST payload
- PING/PONG heartbeat with 8-byte status payload (lastTxSeq, lastRxSeq);
  PONG handler triggers replay if peer is behind
- PKI: DataPacket.PKC_CHANNEL_INDEX so CommandSenderImpl applies
  Curve25519 encryption (firmware rejects non-PKI DMShell packets)
- Input batching: 500ms debounce (matches Python client), immediate flush
  on \r, \t, buffer-full (64 bytes), or Enter

Terminal UI:
- Retro-CRT composables: TerminalCanvas (phosphor glow, two-pass bloom),
  ScanlinesOverlay, FlickerEffect (animated brightness variation),
  CrtCurvatureModifier (AGSL barrel distortion on Android 12+, no-op on JVM)
- PhosphorPreset enum: GREEN (P1), AMBER (P3), WHITE (P4)
- Pending-input rendered inline in preset.dim colour; snaps to confirmed on flush
- Hidden zero-size BasicTextField captures soft and hardware keyboard input
- Phosphor colour picker dropdown in top bar

Capabilities gate:
- supportsRemoteShell gated to UNRELEASED (9.9.9)
- Entry only visible in AdministrationSection when node.capabilities.supportsRemoteShell
This commit is contained in:
James Rich 2026-04-14 12:23:49 -05:00 committed by James Rich
parent 0f900fe7d7
commit 8701b8645d
18 changed files with 1563 additions and 0 deletions

View file

@ -48,6 +48,7 @@ import org.meshtastic.core.repository.PacketHandler
import org.meshtastic.core.repository.PacketRepository
import org.meshtastic.core.repository.PlatformAnalytics
import org.meshtastic.core.repository.RadioConfigRepository
import org.meshtastic.core.repository.RemoteShellHandler
import org.meshtastic.core.repository.ServiceBroadcasts
import org.meshtastic.core.repository.ServiceRepository
import org.meshtastic.core.repository.StoreForwardPacketHandler
@ -96,6 +97,7 @@ class MeshDataHandlerImpl(
private val storeForwardHandler: StoreForwardPacketHandler,
private val telemetryHandler: TelemetryPacketHandler,
private val adminPacketHandler: AdminPacketHandler,
private val remoteShellHandler: RemoteShellHandler,
@Named("ServiceScope") private val scope: CoroutineScope,
) : MeshDataHandler {
@ -181,6 +183,12 @@ class MeshDataHandlerImpl(
adminPacketHandler.handleAdminMessage(packet, myNodeNum)
}
PortNum.REMOTE_SHELL_APP -> {
remoteShellHandler.handleRemoteShell(packet)
// Do not broadcast — RemoteShell frames are point-to-point PTY I/O
shouldBroadcast = false
}
PortNum.NEIGHBORINFO_APP -> {
neighborInfoHandler.handleNeighborInfo(packet)
shouldBroadcast = true

View file

@ -0,0 +1,55 @@
/*
* Copyright (c) 2025-2026 Meshtastic LLC
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
package org.meshtastic.core.data.manager
import co.touchlab.kermit.Logger
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.asSharedFlow
import org.koin.core.annotation.Single
import org.meshtastic.core.model.util.decodeOrNull
import org.meshtastic.core.repository.ReceivedShellFrame
import org.meshtastic.core.repository.RemoteShellHandler
import org.meshtastic.proto.MeshPacket
import org.meshtastic.proto.RemoteShell
/**
* Handles incoming [RemoteShell] packets (REMOTE_SHELL_APP portnum = 13).
*
* This is a scaffold implementation. The RemoteShell firmware feature is currently unreleased (gated to
* [org.meshtastic.core.model.Capabilities.supportsRemoteShell]). When the firmware ships, this handler should be
* expanded to manage PTY session state and relay I/O to the UI.
*/
@Single
class RemoteShellPacketHandlerImpl : RemoteShellHandler {
/**
* Emits every received [ReceivedShellFrame] (decoded frame + sender node number).
*
* Uses [MutableSharedFlow] with a buffer so that rapid or structurally-identical frames are never silently dropped
* (unlike `StateFlow` which conflates by equality).
*/
private val _lastFrame = MutableSharedFlow<ReceivedShellFrame>(extraBufferCapacity = 16)
override val lastFrame: SharedFlow<ReceivedShellFrame> = _lastFrame.asSharedFlow()
override fun handleRemoteShell(packet: MeshPacket) {
val payload = packet.decoded?.payload ?: return
val frame = RemoteShell.ADAPTER.decodeOrNull(payload, Logger) ?: return
Logger.d { "RemoteShell frame from ${packet.from}: op=${frame.op} sessionId=${frame.session_id}" }
_lastFrame.tryEmit(ReceivedShellFrame(from = packet.from, frame = frame))
}
}