feat: RNode Flasher - Flash firmware on RNode devices via USB

[torlando-tech]

Summary

• Add complete RNode firmware flashing capability with 5-step wizard UI
• Implement core flasher protocols: Nordic DFU (nRF52) and esptool (ESP32)
• Support auto-detection of board type and firmware version
• Download firmware directly from GitHub releases with caching

Features

Core Flasher Implementation (reticulum module)

• RNodeFlasher: Main orchestration with USB/serial communication
• NordicDFUFlasher: DFU protocol for nRF52-based devices (RAK4631)
• ESPToolFlasher: esptool protocol for ESP32 devices (T-Beam, Heltec, T-Deck)
• FirmwareDownloader: Download firmware from GitHub releases
• FirmwarePackage: Parse and manage firmware ZIP packages
• RNodeDetector: Auto-detect board type and firmware version
• SLIP/KISS codecs: Serial communication framing

UI Implementation (5-step wizard)

1. Device Selection - List USB devices, request permissions
2. Device Detection - Auto-detect board/firmware or manual select
3. Firmware Selection - Choose board, frequency band, version with download
4. Flash Progress - Determinate progress bar with cancel confirmation
5. Complete - Success/failure states with next actions (Configure RNode, Flash Another)

Entry Point

Settings → RNodeFlasherCard → Open Flasher → Wizard

Test plan

• Unit tests for codec implementations (CRC16, SLIP, KISS)
• Unit tests for FirmwarePackage parsing
• Manual test: Full wizard flow with RAK4631 via USB
• Manual test: Full wizard flow with ESP32 device (T-Beam, Heltec)
• Manual test: Cancel during flash
• Manual test: USB disconnect recovery
• Manual test: Permission denied flow

Screenshots

To be added after manual testing

🤖 Generated with Claude Code

[sentry]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Overview

Greptile Summary

This PR implements a comprehensive RNode firmware flashing feature with a 5-step wizard UI that enables users to flash firmware to RNode devices via USB. The implementation includes support for both nRF52-based devices (using Nordic DFU protocol) and ESP32-based devices (using ESPTool protocol).

Key Changes

Core Flasher Implementation (reticulum module)

• RNodeFlasher: Main orchestration class that auto-detects device type and selects appropriate flashing protocol
• NordicDFUFlasher: Implements Nordic DFU protocol with 1200 baud touch bootloader entry for nRF52 devices (RAK4631, T-Echo)
• ESPToolFlasher: Implements ESP32 ROM bootloader protocol with USB-JTAG-Serial reset sequence and native USB detection for ESP32-S3 devices
• RNodeDetector: KISS protocol implementation for device detection, ROM reading, and EEPROM provisioning
• FirmwareDownloader: Downloads firmware from GitHub releases with progress tracking
• FirmwarePackage: Parses firmware ZIP files and extracts embedded firmware hashes
• SLIP and KISS codecs for serial communication framing

UI Implementation (5-step wizard)

1. Device Selection - Lists USB devices and requests permissions
2. Device Detection - Auto-detects board type and firmware version
3. Firmware Selection - Choose board, frequency band, and version with download capability
4. Flash Progress - Determinate progress bar with cancel confirmation
5. Complete - Success/failure states with next actions

Integration

• MainActivity: Added USB device auto-navigation with bootloader flash mode flag
• UsbDeviceActionScreen: User-friendly screen allowing choice between flashing or configuring
• Navigation routes integrated with existing app structure

Test Coverage

Good unit test coverage for critical components:

• CRC16, SLIP, and KISS codec implementations
• FirmwarePackage parsing
• Native USB device detection logic
• RNodeFlasher state transitions

Architecture Quality

The implementation demonstrates solid software engineering:

• Clear separation of concerns between protocols (DFU vs ESPTool)
• Proper state management with StateFlow for UI observation
• Comprehensive error handling with recoverable error states
• Platform-specific handling (ESP32 vs ESP32-S3 bootloader offsets, native USB reset sequences)
• Device provisioning with EEPROM writes and firmware hash validation

Issues Identified

• FirmwareDownloader lacks rate limiting and retry logic for GitHub API requests
• FlasherViewModel has tight coupling to MainActivity via direct companion object access, breaking MVVM architecture
• Consider extracting bootloaderFlashModeActive to a shared repository/state manager

Confidence Score: 4/5

• This PR is safe to merge with minor improvements recommended for network reliability and architecture
• Score reflects comprehensive implementation with good test coverage, proper error handling, and attention to hardware-specific details. The core flashing logic is well-tested and follows protocol specifications. Minor architecture improvements recommended for network resilience and MVVM separation.
• Pay attention to FirmwareDownloader.kt (add retry logic) and FlasherViewModel.kt (decouple from MainActivity)

Important Files Changed

Filename	Overview
reticulum/src/main/java/com/lxmf/messenger/reticulum/flasher/RNodeFlasher.kt	Main orchestration class implementing firmware flashing with auto-detection, platform-specific flashers, and provisioning. Well-structured with proper error handling and state management.
reticulum/src/main/java/com/lxmf/messenger/reticulum/flasher/ESPToolFlasher.kt	Implements ESP32 ROM bootloader protocol with USB-JTAG-Serial reset sequence, native USB detection, and multi-region flashing. Comprehensive implementation with proper timing delays.
reticulum/src/main/java/com/lxmf/messenger/reticulum/flasher/NordicDFUFlasher.kt	Nordic DFU protocol implementation for nRF52 devices using 1200 baud touch bootloader entry. Clean implementation following protocol spec.
reticulum/src/main/java/com/lxmf/messenger/reticulum/flasher/FirmwareDownloader.kt	Downloads firmware from GitHub releases. Missing rate limiting and retry logic for API requests.
app/src/main/java/com/lxmf/messenger/viewmodel/FlasherViewModel.kt	Manages 5-step wizard UI state with firmware selection and download. Contains tight coupling to MainActivity via direct companion object access.
app/src/main/java/com/lxmf/messenger/MainActivity.kt	Added USB device auto-navigation, bootloader flash mode flag, and navigation routes for flasher and USB action screen. Well-integrated with existing navigation.
reticulum/src/main/java/com/lxmf/messenger/reticulum/flasher/RNodeDetector.kt	KISS protocol implementation for device detection, ROM reading, and EEPROM provisioning. Properly handles device communication with timeouts.

Sequence Diagram

sequenceDiagram
    participant User
    participant FlasherUI as RNodeFlasherScreen
    participant VM as FlasherViewModel
    participant Flasher as RNodeFlasher
    participant Detector as RNodeDetector
    participant DFU as NordicDFUFlasher
    participant ESP as ESPToolFlasher
    participant Downloader as FirmwareDownloader
    participant USB as KotlinUSBBridge
    participant Device as USB Device

    User->>FlasherUI: Open Flasher
    FlasherUI->>VM: Initialize
    VM->>Flasher: getConnectedDevices()
    Flasher->>USB: getConnectedUsbDevices()
    USB-->>Flasher: List of USB devices
    Flasher-->>VM: Device list
    VM-->>FlasherUI: Update state with devices
    
    User->>FlasherUI: Select device
    FlasherUI->>VM: selectDevice()
    VM->>Flasher: requestPermission()
    Flasher->>USB: requestPermission()
    USB-->>User: Permission dialog
    User-->>USB: Grant permission
    USB-->>Flasher: Permission granted
    Flasher-->>VM: Permission callback
    
    User->>FlasherUI: Click Continue
    FlasherUI->>VM: detectDevice()
    VM->>Flasher: detectDevice(deviceId)
    Flasher->>USB: connect(deviceId)
    USB->>Device: Connect
    Device-->>USB: Connected
    Flasher->>Detector: getDeviceInfo()
    Detector->>USB: Send KISS detect command
    USB->>Device: CMD_DETECT
    Device-->>USB: DETECT_RESP
    Detector->>USB: Read platform, MCU, board, ROM
    USB->>Device: CMD_PLATFORM, CMD_MCU, etc.
    Device-->>USB: Device info
    Detector-->>Flasher: RNodeDeviceInfo
    Flasher->>USB: disconnect()
    Flasher-->>VM: Device info
    VM-->>FlasherUI: Update with detected board
    
    User->>FlasherUI: Select firmware
    FlasherUI->>VM: selectFirmware() or downloadFirmware()
    alt Download firmware
        VM->>Flasher: firmwareDownloader
        Flasher->>Downloader: getAvailableReleases()
        Downloader->>Downloader: HTTP GET GitHub API
        Downloader-->>Flasher: Release list
        VM->>Downloader: downloadFirmware()
        Downloader->>Downloader: HTTP GET firmware ZIP
        Downloader-->>VM: Firmware data
        VM->>Flasher: firmwareRepository.saveFirmware()
    end
    
    User->>FlasherUI: Click Flash
    FlasherUI->>VM: startFlashing()
    VM->>Flasher: flashFirmware()
    Flasher->>Flasher: Verify integrity
    
    alt ESP32 device
        Flasher->>ESP: flash()
        ESP->>USB: connect(deviceId)
        ESP->>USB: enableRawMode()
        ESP->>ESP: trySyncQuick() - check if already in bootloader
        alt Not in bootloader
            ESP->>ESP: enterBootloader() - DTR/RTS sequence
            ESP->>USB: setRts/setDtr control signals
            USB->>Device: Reset to bootloader
        end
        ESP->>USB: Send ESP_SYNC command
        Device-->>USB: Sync response
        ESP->>USB: Send ESP_CHANGE_BAUDRATE
        ESP->>USB: Send ESP_SPI_ATTACH
        ESP->>USB: Send ESP_FLASH_BEGIN
        loop For each flash region
            ESP->>USB: Send ESP_FLASH_DATA packets
            USB->>Device: Write firmware blocks
            Device-->>USB: ACK
            ESP-->>VM: Progress update
            VM-->>FlasherUI: Update progress bar
        end
        ESP->>USB: Send ESP_FLASH_END
        ESP->>ESP: hardReset()
        ESP->>USB: disconnect()
    else nRF52 device
        Flasher->>DFU: flash()
        DFU->>USB: connect(deviceId, 1200 baud)
        DFU->>USB: disconnect() - triggers bootloader
        DFU->>DFU: Wait for bootloader
        DFU->>USB: connect(deviceId, 115200 baud)
        DFU->>USB: Send DFU_START_PACKET
        DFU->>USB: Send DFU_INIT_PACKET
        loop For each firmware block
            DFU->>USB: Send DFU_DATA_PACKET
            USB->>Device: Write firmware
            DFU-->>VM: Progress update
            VM-->>FlasherUI: Update progress bar
        end
        DFU->>USB: Send DFU_STOP_DATA_PACKET
        DFU->>USB: disconnect()
    end
    
    Flasher->>Flasher: Wait for device reboot
    Flasher->>Flasher: provisionDevice()
    Flasher->>USB: connect(deviceId) - with retries
    Flasher->>Detector: getDeviceInfo()
    alt Already provisioned
        Detector->>Detector: setFirmwareHash()
    else Not provisioned
        Detector->>Detector: provisionAndSetFirmwareHash()
        Detector->>USB: Write EEPROM (product, model, serial)
        Detector->>USB: Set firmware hash
        Detector->>USB: Send CMD_RESET
    end
    Flasher->>USB: disconnect()
    Flasher-->>VM: FlashState.Complete
    VM-->>FlasherUI: Show success
    FlasherUI-->>User: Flash complete!

Loading

[greptile-apps]

_{7 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

no rate limiting or retry logic for GitHub API requests - may hit rate limits or fail on transient errors

Suggested change

	* Get available firmware releases from GitHub.
	*/
	suspend fun getAvailableReleases(): List<GitHubRelease>? =
	withContext(Dispatchers.IO) {
	try {
	val url = URL(GITHUB_RELEASES)
	val connection = url.openConnection() as HttpURLConnection
	connection.requestMethod = "GET"
	connection.setRequestProperty("Accept", "application/vnd.github.v3+json")
	connection.setRequestProperty("User-Agent", USER_AGENT)
	connection.connectTimeout = CONNECT_TIMEOUT_MS
	connection.readTimeout = READ_TIMEOUT_MS
	if (connection.responseCode != HttpURLConnection.HTTP_OK) {
	Log.e(TAG, "GitHub API returned ${connection.responseCode}")
	return@withContext null
	}
	val responseBody = connection.inputStream.bufferedReader().readText()
	json.decodeFromString<List<GitHubRelease>>(responseBody)
	} catch (e: Exception) {
	Log.e(TAG, "Failed to fetch releases", e)
	null
	}
	}
	suspend fun getAvailableReleases(maxRetries: Int = 3): List<GitHubRelease>? =
	withContext(Dispatchers.IO) {
	repeat(maxRetries) { attempt ->
	try {
	val url = URL(GITHUB_RELEASES)
	val connection = url.openConnection() as HttpURLConnection
	connection.requestMethod = "GET"
	connection.setRequestProperty("Accept", "application/vnd.github.v3+json")
	connection.setRequestProperty("User-Agent", USER_AGENT)
	connection.connectTimeout = CONNECT_TIMEOUT_MS
	connection.readTimeout = READ_TIMEOUT_MS
	if (connection.responseCode == HttpURLConnection.HTTP_FORBIDDEN) {
	// Check for rate limit headers
	val rateLimitRemaining = connection.getHeaderField("X-RateLimit-Remaining")?.toIntOrNull()
	if (rateLimitRemaining == 0) {
	Log.e(TAG, "GitHub API rate limit exceeded")
	return@withContext null
	}
	}
	if (connection.responseCode != HttpURLConnection.HTTP_OK) {
	if (attempt < maxRetries - 1) {
	delay(1000L * (attempt + 1)) // Exponential backoff
	return@repeat
	}
	Log.e(TAG, "GitHub API returned ${connection.responseCode}")
	return@withContext null
	}
	val responseBody = connection.inputStream.bufferedReader().readText()
	return@withContext json.decodeFromString<List<GitHubRelease>>(responseBody)
	} catch (e: Exception) {
	if (attempt < maxRetries - 1) {
	Log.w(TAG, "Retry attempt ${attempt + 1} failed, retrying...", e)
	delay(1000L * (attempt + 1))
	} else {
	Log.e(TAG, "Failed to fetch releases after $maxRetries attempts", e)
	return@withContext null
	}
	}
	}
	null
	}

Prompt To Fix With AI

This is a comment left during a code review.
Path: reticulum/src/main/java/com/lxmf/messenger/reticulum/flasher/FirmwareDownloader.kt
Line: 46:71

Comment:
no rate limiting or retry logic for GitHub API requests - may hit rate limits or fail on transient errors

```suggestion
    suspend fun getAvailableReleases(maxRetries: Int = 3): List<GitHubRelease>? =
        withContext(Dispatchers.IO) {
            repeat(maxRetries) { attempt ->
                try {
                    val url = URL(GITHUB_RELEASES)
                    val connection = url.openConnection() as HttpURLConnection

                    connection.requestMethod = "GET"
                    connection.setRequestProperty("Accept", "application/vnd.github.v3+json")
                    connection.setRequestProperty("User-Agent", USER_AGENT)
                    connection.connectTimeout = CONNECT_TIMEOUT_MS
                    connection.readTimeout = READ_TIMEOUT_MS

                    if (connection.responseCode == HttpURLConnection.HTTP_FORBIDDEN) {
                        // Check for rate limit headers
                        val rateLimitRemaining = connection.getHeaderField("X-RateLimit-Remaining")?.toIntOrNull()
                        if (rateLimitRemaining == 0) {
                            Log.e(TAG, "GitHub API rate limit exceeded")
                            return@withContext null
                        }
                    }

                    if (connection.responseCode != HttpURLConnection.HTTP_OK) {
                        if (attempt < maxRetries - 1) {
                            delay(1000L * (attempt + 1)) // Exponential backoff
                            return@repeat
                        }
                        Log.e(TAG, "GitHub API returned ${connection.responseCode}")
                        return@withContext null
                    }

                    val responseBody = connection.inputStream.bufferedReader().readText()
                    return@withContext json.decodeFromString<List<GitHubRelease>>(responseBody)
                } catch (e: Exception) {
                    if (attempt < maxRetries - 1) {
                        Log.w(TAG, "Retry attempt ${attempt + 1} failed, retrying...", e)
                        delay(1000L * (attempt + 1))
                    } else {
                        Log.e(TAG, "Failed to fetch releases after $maxRetries attempts", e)
                        return@withContext null
                    }
                }
            }
            null
        }
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

direct access to MainActivity companion object creates tight coupling and breaks MVVM architecture - FlasherViewModel should not directly manipulate MainActivity state

Better to use a repository or state manager:

// In a shared repository/manager
object FlasherStateManager {
    @Volatile
    var bootloaderFlashModeActive: Boolean = false
}

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: app/src/main/java/com/lxmf/messenger/viewmodel/FlasherViewModel.kt
Line: 144:146

Comment:
direct access to MainActivity companion object creates tight coupling and breaks MVVM architecture - FlasherViewModel should not directly manipulate MainActivity state

Better to use a repository or state manager:
```
// In a shared repository/manager
object FlasherStateManager {
    @Volatile
    var bootloaderFlashModeActive: Boolean = false
}
```

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.