meshtastic 0.0.182 → 0.0.183

data/lib/meshtastic/admin/firmware/hex.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'securerandom'
+require 'tempfile'
+require 'timeout'
+
+module Meshtastic
+  module Admin
+    module Firmware
+      # Strict Intel HEX validation and explicitly selected nRF52840 SWD programming.
+      module Hex
+        MAX_IMAGE = 16 * 1024 * 1024
+
+        public_class_method def self.validate(opts = {})
+          raise ArgumentError, 'Only explicit expected_chip: :nrf52840 is supported' unless opts[:expected_chip] == :nrf52840
+
+          bytes = opts[:bytes]
+          raise ArgumentError, 'HEX bytes must be a nonempty String of at most 16 MiB' unless bytes.is_a?(String) && bytes.bytesize.between?(1, MAX_IMAGE)
+
+          base = 0
+          eof = false
+          start = nil
+          ranges = []
+          bytes.b.each_line do |raw|
+            line = raw.delete_suffix("\n").delete_suffix("\r")
+            raise ArgumentError, 'Invalid HEX record or data after EOF' if eof || !line.match?(/\A:(?:[0-9a-fA-F]{2}){5,260}\z/)
+
+            fields = [line[1..]].pack('H*').bytes
+            count, high, low, type = fields.first(4)
+            address = (high << 8) | low
+            data = fields[4, count]
+            raise ArgumentError, 'HEX length or checksum mismatch' unless fields.length == count + 5 && fields.sum.nobits?(255)
+
+            case type
+            when 0
+              raise ArgumentError, 'Empty data or record crosses 64 KiB boundary' unless count.positive? && address + count <= 0x10000
+
+              first = base + address
+              last = first + count
+              raise ArgumentError, 'HEX address outside nRF52840 flash/UICR' unless (first >= 0 && last <= 0x100000) || (first >= 0x10001000 && last <= 0x10002000)
+
+              ranges << [first, last]
+            when 1
+              raise ArgumentError, 'Malformed EOF record' unless count.zero? && address.zero?
+
+              eof = true
+            when 2, 4
+              raise ArgumentError, 'Malformed extended address record' unless count == 2 && address.zero?
+
+              base = data.pack('C*').unpack1('n') << (type == 2 ? 4 : 16)
+            when 3, 5
+              raise ArgumentError, 'Malformed or repeated start address record' unless count == 4 && address.zero? && start.nil?
+
+              start = if type == 3
+                        segment, offset = data.pack('C*').unpack('n2')
+                        (segment << 4) + offset
+                      else
+                        data.pack('C*').unpack1('N')
+                      end
+              raise ArgumentError, 'Start address outside flash' unless start < 0x100000
+            else
+              raise ArgumentError, "Unsupported HEX record type #{type}"
+            end
+          end
+          raise ArgumentError, 'HEX requires EOF and nonempty data' unless eof && !ranges.empty?
+
+          ranges.sort_by!(&:first)
+          raise ArgumentError, 'Overlapping HEX data records' if ranges.each_cons(2).any? { |left, right| left.last > right.first }
+
+          { data_bytes: ranges.sum { |first, last| last - first }, ranges: ranges, start_address: start }
+        end
+
+        public_class_method def self.install(opts = {})
+          allowed = %i[protocol firmware bytes expected_chip expected_target openocd interface_config target_config timeout]
+          raise ArgumentError, 'Unsupported HEX install options' unless (opts.keys - allowed).empty?
+          raise ArgumentError, 'protocol must be explicitly :swd' unless opts[:protocol] == :swd
+          raise ArgumentError, 'Supply exactly one of firmware or bytes' unless opts.key?(:firmware) ^ opts.key?(:bytes)
+
+          bytes = image_bytes(opts.merge({}))
+          metadata = validate(bytes: bytes, expected_chip: opts[:expected_chip])
+          target = opts[:expected_target]
+          raise ArgumentError, 'expected_target must be an explicit OpenOCD target name' unless target.is_a?(String) && target.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}\z/)
+
+          executable = trusted_file(path: opts[:openocd], executable: true)
+          interface = trusted_file(path: opts[:interface_config])
+          config = trusted_file(path: opts[:target_config])
+          timeout = opts.fetch(:timeout, 120)
+          raise ArgumentError, 'timeout must be finite and positive (at most 3600 seconds)' unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive? && timeout <= 3600
+
+          token = "MESHTASTIC_HEX_OK_#{SecureRandom.hex(16)}"
+          Tempfile.create(['meshtastic-', '.hex']) do |image|
+            image.binmode
+            image.write(bytes)
+            image.flush
+            path = tcl_word(value: image.path)
+            script = <<~TCL
+              if {[catch {
+                init
+                targets #{tcl_word(value: target)}
+                reset init
+                halt
+                if {[lindex [read_memory 0x10000100 32 1] 0] != 0x52840} {error "nRF52840 FICR PART mismatch"}
+                if {[lindex [read_memory 0x10000010 32 1] 0] != 4096 || [lindex [read_memory 0x10000014 32 1] 0] != 256} {error "nRF52840 flash geometry mismatch"}
+                flash write_image erase #{path} 0 ihex
+                verify_image #{path} 0 ihex
+                reset run
+              } failure]} {
+                echo $failure
+                shutdown error
+              } else {
+                echo #{token}
+                shutdown
+              }
+            TCL
+            args = [executable, '-c', 'gdb_port disabled; telnet_port disabled; tcl_port disabled',
+                    '-f', interface, '-c', 'transport select swd', '-f', config, '-c', script]
+            run_programmer(args: args, timeout: timeout, token: token)
+          end
+          metadata.merge(status: :verified, protocol: :swd, format: :hex, expected_chip: opts[:expected_chip],
+                         expected_target: target, bytes: bytes.bytesize, sha256: Digest::SHA256.hexdigest(bytes),
+                         flash_verified: true, reboot_verified: false)
+        end
+
+        private_class_method def self.image_bytes(opts = {})
+          return opts[:bytes].b.dup.freeze if opts[:bytes].is_a?(String)
+          return opts[:bytes] unless opts.key?(:firmware)
+
+          path = opts[:firmware]
+          raise ArgumentError, 'firmware must name a regular HEX file' unless path.is_a?(String) && File.file?(path)
+
+          File.open(path, File::RDONLY | File::NONBLOCK) do |file|
+            raise ArgumentError, 'firmware must be a bounded regular file' unless file.stat.file? && file.stat.size <= MAX_IMAGE
+
+            file.binmode
+            file.read(MAX_IMAGE + 1).freeze
+          end
+        end
+
+        private_class_method def self.trusted_file(opts = {})
+          path = opts[:path]
+          raise ArgumentError, 'Supply absolute paths to installed OpenOCD and trusted configuration files' unless path.is_a?(String) && path.start_with?('/') && !path.match?(/[\x00-\x1f\x7f]/) && File.file?(path) && File.readable?(path)
+          raise ArgumentError, 'openocd must be an executable file' if opts[:executable] && !File.executable?(path)
+
+          path
+        end
+
+        private_class_method def self.tcl_word(opts = {})
+          escaped = opts.fetch(:value).gsub(/[\\"\[\]${}\r\n]/) { |character| { "\r" => '\r', "\n" => '\n' }.fetch(character) { "\\#{character}" } }
+          "\"#{escaped}\""
+        end
+
+        private_class_method def self.run_programmer(opts = {})
+          Tempfile.create('meshtastic-openocd-log') do |log|
+            pid = Process.spawn(*opts.fetch(:args), in: File::NULL, out: log, err: log, pgroup: true)
+            begin
+              _, status = Timeout.timeout(opts.fetch(:timeout)) { Process.wait2(pid) }
+            rescue Timeout::Error
+              begin
+                Process.kill('KILL', -pid)
+              rescue Errno::ESRCH
+                nil
+              end
+              begin
+                Process.wait(pid)
+              rescue Errno::ECHILD
+                nil
+              end
+              raise IOError, 'OpenOCD timed out; flash state is uncertain; do not automatically retry'
+            end
+            log.rewind
+            completed = log.each_line.any? { |line| line.strip == opts.fetch(:token) }
+            raise IOError, "OpenOCD failed or did not complete verification/reset (exit #{status.exitstatus.inspect}); flash state may be partial" unless status.success? && completed
+          end
+        rescue Errno::ENOENT, Errno::EACCES => e
+          raise IOError, "Unable to execute installed OpenOCD: #{e.message}"
+        end
+
+        public_class_method def self.authors
+          'Meshtastic Ruby contributors'
+        end
+
+        public_class_method def self.help
+          puts <<~HELP
+            Validate Intel HEX without accessing hardware.
+            #{self}.validate(
+              bytes: 'required - complete Intel HEX content',
+              expected_chip: 'required - exact supported symbol :nrf52840'
+            )
+            Program and verify explicitly selected nRF52840 hardware (destructive).
+            #{self}.install(
+              protocol: 'required - explicitly :swd only',
+              firmware: 'optional - path to HEX file, exclusive with bytes',
+              bytes: 'optional - Intel HEX content, exclusive with firmware',
+              expected_chip: 'required - exact supported symbol :nrf52840',
+              expected_target: 'required - configured OpenOCD target name, e.g. nrf52.cpu',
+              openocd: 'required - absolute path to trusted installed executable',
+              interface_config: 'required - absolute path to trusted probe Tcl configuration',
+              target_config: 'required - absolute path to trusted nRF52 Tcl configuration',
+              timeout: 'optional - positive execution limit in seconds, default 120'
+            )
+            List the module contributors.
+            #{self}.authors
+          HELP
+        end
+      end
+    end
+  end
+end

data/lib/meshtastic/admin/firmware/uf2.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Meshtastic
+  module Admin
+    module Firmware
+      # UF2 mass-storage submission is not a flash verification protocol.
+      module UF2
+        MAX_IMAGE = 32 * 1024 * 1024
+
+        public_class_method def self.install(opts = {})
+          raise ArgumentError, 'protocol must be explicitly :uf2' unless opts[:protocol] == :uf2
+          raise ArgumentError, 'Unsupported UF2 install options' unless (opts.keys - %i[protocol firmware bytes mount family_id board_id flash_size]).empty?
+          raise ArgumentError, 'Supply exactly one of firmware or bytes' unless opts.key?(:firmware) ^ opts.key?(:bytes)
+
+          bytes = image_bytes(opts.merge({}))
+          validate_image(opts.merge(bytes: bytes))
+          mount = opts[:mount]
+          raise ArgumentError, 'mount must be an explicit canonical absolute bootloader directory' unless mount.is_a?(String) && mount.start_with?('/') && mount != '/' && File.expand_path(mount) == mount && File.directory?(mount) && File.realpath(mount) == mount
+          raise NotImplementedError, 'Safe UF2 directory pinning requires Linux procfs and O_NOFOLLOW' unless File.directory?('/proc/self/fd') && File.const_defined?(:NOFOLLOW)
+
+          destination = File.join(mount, 'FIRMWARE.UF2')
+          File.open(mount, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |directory|
+            raise ArgumentError, 'mount must be a directory' unless directory.stat.directory?
+
+            # Use the opened directory, never re-resolve the mount path for a
+            # write: an unplug/unmount must not redirect data onto the host disk.
+            anchor = "/proc/self/fd/#{directory.fileno}"
+            validate_target(opts.merge(anchor: anchor))
+            current = File.stat(mount)
+            raise IOError, 'UF2 mount changed before submission' unless current.dev == directory.stat.dev && current.ino == directory.stat.ino && File.realpath(mount) == mount
+
+            File.open(File.join(anchor, 'FIRMWARE.UF2'), File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0o600) do |file|
+              file.binmode
+              written = file.write(bytes)
+              raise IOError, 'Incomplete UF2 submission; do not automatically retry' unless written == bytes.bytesize
+
+              file.flush
+              file.fsync
+            end
+          end
+          { status: :copied, protocol: :uf2, bytes: bytes.bytesize, sha256: Digest::SHA256.hexdigest(bytes),
+            family_id: opts.fetch(:family_id), board_id: opts.fetch(:board_id), destination: destination,
+            flash_verified: false, reboot_verified: false }
+        end
+
+        private_class_method def self.validate_target(opts = {})
+          board = opts[:board_id]
+          raise ArgumentError, 'board_id must be the exact expected INFO_UF2.TXT Board-ID' unless board.is_a?(String) && board.match?(/\A[A-Za-z0-9][A-Za-z0-9_.-]{0,255}\z/)
+
+          anchor = opts.fetch(:anchor)
+          markers = Dir.children(anchor).select { |name| name.casecmp?('INFO_UF2.TXT') }
+          raise ArgumentError, 'Exactly one INFO_UF2.TXT is required on the selected mount' unless markers.length == 1
+
+          marker = File.join(anchor, markers.first)
+          raise ArgumentError, 'INFO_UF2.TXT must be a regular nonsymlink file' unless File.lstat(marker).file?
+
+          text = File.open(marker, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+            raise ArgumentError, 'INFO_UF2.TXT must be a bounded regular file' unless file.stat.file? && file.stat.size <= 4096
+
+            file.binmode
+            file.read(4097)
+          end
+          raise ArgumentError, 'Invalid INFO_UF2.TXT bootloader identification' unless text.bytesize <= 4096 && text.match?(/\AUF2 Bootloader[^\r\n]*\r?\n/) && text.match?(/\A[\x09\x0a\x0d\x20-\x7e]*\z/)
+
+          boards = text.lines.filter_map { |line| line.chomp.delete_suffix("\r").match(/\ABoard-ID:[ \t]*(\S+)[ \t]*\z/)&.captures&.first }
+          raise ArgumentError, 'INFO_UF2.TXT Board-ID mismatch or ambiguous Board-ID' unless boards == [board]
+
+          family = if board.match?(/\AnRF52840-/i)
+                     0xada52840
+                   elsif board == 'RPI-RP2'
+                     0xe48bff56
+                   end
+          raise ArgumentError, 'INFO_UF2.TXT Board-ID does not identify the expected MCU family' unless family == opts.fetch(:family_id)
+        end
+
+        private_class_method def self.image_bytes(opts = {})
+          raw = if opts.key?(:firmware)
+                  path = opts[:firmware]
+                  raise ArgumentError, 'firmware must name a regular file' unless path.is_a?(String) && File.file?(path)
+
+                  File.open(path, File::RDONLY | File::NONBLOCK) do |file|
+                    raise ArgumentError, 'firmware must be a bounded regular file' unless file.stat.file? && file.stat.size <= MAX_IMAGE
+
+                    file.binmode
+                    file.read(MAX_IMAGE + 1)
+                  end
+                else
+                  opts[:bytes]
+                end
+          raise ArgumentError, 'UF2 image must be a binary String of at most 32 MiB' unless raw.is_a?(String) && raw.bytesize <= MAX_IMAGE
+
+          raw.b.freeze
+        end
+
+        private_class_method def self.flash_bounds(opts = {})
+          raise ArgumentError, 'family_id must be an Integer' unless opts[:family_id].is_a?(Integer)
+
+          case opts[:family_id]
+          when 0xada52840
+            raise ArgumentError, 'flash_size applies only to RP2040' if opts.key?(:flash_size)
+
+            [0x27000, 0xf4000]
+          when 0xe48bff56
+            size = opts[:flash_size]
+            raise ArgumentError, 'RP2040 requires flash_size in bytes, 4096..16777216 and 4096 aligned' unless size.is_a?(Integer) && (4096..0x1000000).cover?(size) && (size % 4096).zero?
+
+            [0x10000000, 0x10000000 + size]
+          else
+            raise ArgumentError, 'Unsupported UF2 family_id; only NRF52840 and RP2040 application images are supported'
+          end
+        end
+
+        private_class_method def self.validate_image(opts = {})
+          lower, upper = flash_bounds(opts.merge({}))
+          bytes = opts.fetch(:bytes)
+          raise ArgumentError, 'UF2 must contain complete nonempty 512-byte blocks' unless bytes.is_a?(String) && bytes.bytesize.positive? && (bytes.bytesize % 512).zero?
+
+          count = bytes.bytesize / 512
+          numbers = {}
+          regions = []
+          count.times do |index|
+            block = bytes.byteslice(index * 512, 512)
+            magic0, magic1, flags, address, size, number, total, family = block.unpack('V8')
+            raise ArgumentError, 'Invalid UF2 magic' unless magic0 == 0x0a324655 && magic1 == 0x9e5d5157 && block.byteslice(508, 4).unpack1('V') == 0x0ab16f30
+            raise ArgumentError, 'Only plain main-flash UF2 blocks with family IDs are supported' unless flags == 0x2000
+            raise ArgumentError, 'UF2 family mismatch or mixed families' unless family == opts.fetch(:family_id)
+            raise ArgumentError, 'Supported UF2 bootloaders require 256-byte payloads and target alignment' unless size == 256 && (address % 256).zero?
+            raise ArgumentError, 'Invalid UF2 block count or number' unless total == count && number < count
+            raise ArgumentError, 'Duplicate UF2 block number' if numbers[number]
+            raise ArgumentError, 'UF2 target address outside application flash' unless address >= lower && address + size <= upper
+
+            numbers[number] = true
+            regions << [address, address + size]
+          end
+          regions.sort.each_cons(2) do |left, right|
+            raise ArgumentError, 'Overlapping UF2 target addresses' if left[1] > right[0]
+          end
+        end
+
+        public_class_method def self.authors
+          "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
+        end
+
+        public_class_method def self.help
+          puts "USAGE:
+            # Validate and submit firmware through UF2 mass storage.
+            #{self}.install(
+              protocol: 'required - explicit :uf2 protocol selection',
+              bytes: 'optional - complete original UF2 image bytes instead of firmware',
+              firmware: 'optional - regular UF2 image file instead of bytes',
+              mount: 'required - absolute bootloader directory explicitly selected by the operator',
+              family_id: 'required - expected numeric UF2 MCU family identifier',
+              board_id: 'required - exact Board-ID from the selected bootloader INFO_UF2.TXT',
+              flash_size: 'optional - required for RP2040 only; installed flash capacity in bytes, 4096 aligned, at most 16 MiB'
+            )
+
+            # Return module author information.
+            #{self}.authors
+          "
+        end
+      end
+    end
+  end
+end

data/lib/meshtastic/admin/firmware.rb

@@ -13,8 +13,10 @@ module Meshtastic
       end
 
       public_class_method def self.request_ota(opts = {})
-        mode = opts.fetch(:mode, :OTA_BLE)
-        raise ArgumentError, 'mode must be :OTA_BLE or :OTA_WIFI' unless %i[OTA_BLE OTA_WIFI].include?(mode)
+        legacy = opts.keys & %i[serial_obj bluetooth_obj tcp_obj mqtt_obj]
+        raise ArgumentError, "#{legacy.join(', ')} are unsupported; use transport_obj" unless legacy.empty?
+
+        mode = ota_mode(opts.merge({}))
 
         hash = opts[:ota_hash] || sha256(opts)
         raise ArgumentError, 'ota_hash must be a raw 32-byte String' unless hash.is_a?(String) && hash.bytesize == 32
@@ -24,7 +26,23 @@ module Meshtastic
           reboot_ota_mode: mode,
           ota_hash: hash.b
         )
-        Admin.send(opts.except(:bytes, :firmware, :ota_hash, :mode).merge(ota_request: event))
+        Admin.send(opts.except(:bytes, :firmware, :ota_hash, :mode, :transfer).merge(ota_request: event))
+      end
+
+      private_class_method def self.ota_mode(opts = {})
+        modes = { wifi: :OTA_WIFI, ble: :OTA_BLE }
+        raise ArgumentError, 'transfer must be :wifi or :ble' if opts.key?(:transfer) && !modes.key?(opts[:transfer])
+        raise ArgumentError, 'mode must be :OTA_BLE or :OTA_WIFI' if opts.key?(:mode) && !modes.value?(opts[:mode])
+        raise ArgumentError, 'transfer contradicts mode' if opts.key?(:transfer) && opts.key?(:mode) && modes[opts[:transfer]] != opts[:mode]
+
+        return modes[opts[:transfer]] if opts.key?(:transfer)
+        return opts[:mode] if opts.key?(:mode)
+
+        transport = Admin.transport_type(transport_obj: opts[:transport_obj]) if opts[:transport_obj]
+        return :OTA_BLE if transport == :bluetooth
+        return :OTA_WIFI if transport == :tcp
+
+        raise ArgumentError, 'Specify transfer: :wifi or :ble; the control transport does not select an OTA loader'
       end
 
       public_class_method def self.enter_dfu(opts = {})
@@ -48,19 +66,39 @@ module Meshtastic
 
       public_class_method def self.install(opts = {})
         validate_verification(opts[:verify]) if opts.key?(:verify)
-        options = opts.except(:verify)
+        formats = { unified_wifi: :bin, unified_ble: :bin, esp_rom: :bin, nordic_dfu: :zip, uf2: :uf2, swd: :hex }
+        expected_format = formats[opts[:protocol]]
+        raise ArgumentError, "format must be #{expected_format.inspect} for protocol #{opts[:protocol].inspect}" if opts.key?(:format) && opts[:format] != expected_format
+
+        options = opts.except(:verify, :format)
+        options = binary_options(options) if expected_format == :bin
         result = case opts[:protocol]
+                 when :swd then Hex.install(options)
+                 when :uf2 then UF2.install(options)
                  when :unified_ble then BLE.install(options)
                  when :esp_rom then SerialBootloader.install(options)
                  when :nordic_dfu then NordicDFU.install(options)
                  when :unified_wifi then install_wifi(options)
-                 else raise NotImplementedError, 'install requires explicit protocol: :unified_wifi, :unified_ble, :esp_rom or :nordic_dfu'
+                 else raise NotImplementedError, 'install requires explicit protocol: :unified_wifi, :unified_ble, :esp_rom, :nordic_dfu, :uf2 or :swd'
                  end
         return result unless opts[:verify]
 
         result.merge(verify_reboot(opts[:verify])).merge(loader_status: result[:status], reboot_verified: true, boot_verified: true)
       end
 
+      private_class_method def self.binary_options(opts = {})
+        extension = File.extname(opts[:firmware].to_s).downcase
+        raise ArgumentError, "#{extension} format cannot be streamed as a binary image" if %w[.uf2 .zip .hex .dfu].include?(extension)
+
+        bytes = firmware_bytes(opts.merge({}))
+        uf2 = bytes.start_with?([0x0a324655, 0x9e5d5157].pack('V2'))
+        zip = bytes.start_with?("PK\x03\x04".b, "PK\x05\x06".b, "PK\x07\x08".b)
+        hex = bytes.match?(/\A\s*:[0-9a-fA-F]{10}/)
+        raise ArgumentError, 'UF2, ZIP or Intel HEX format cannot be streamed as a binary image' if uf2 || zip || hex
+
+        opts.except(:firmware).merge(bytes: bytes)
+      end
+
       private_class_method def self.install_wifi(opts = {})
         validate_install(opts.merge({}))
         bytes = firmware_bytes(opts.merge({}))
@@ -104,7 +142,7 @@ module Meshtastic
             sleep 0.25
             retry
           end
-          reply = Admin.request(key => handle, get_device_metadata_request: true, timeout: opts.fetch(:timeout, 60))
+          reply = Admin.request(transport_obj: handle, get_device_metadata_request: true, timeout: opts.fetch(:timeout, 60))
           metadata = reply.fetch(:value).to_h
           raise IOError, "Firmware version mismatch: #{metadata[:firmware_version].inspect}" unless metadata[:firmware_version] == opts.fetch(:expected_version)
           raise IOError, 'Post-reboot node identity mismatch' if opts[:expected_node] && handle[:my_node_num] != opts[:expected_node]
@@ -218,16 +256,17 @@ module Meshtastic
 
           # Send Admin ota_request with the image hash and OTA mode.
           #{self}.request_ota(
-            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
-            mqtt_obj: 'optional - MQTT client from Meshtastic::MQTT.connect',
+            transport_obj: 'required - connected Serial, Bluetooth, TCP handle or MQTT client',
             firmware: 'optional - path to a firmware .bin on disk',
             ota_hash: 'optional - 32-byte SHA-256 digest if not hashing firmware',
-            mode: 'optional - :OTA_BLE or :OTA_WIFI (default: :OTA_BLE)'
+            transfer: 'optional - :wifi or :ble; required for serial/MQTT unless mode is explicit',
+            mode: 'optional - explicit :OTA_BLE or :OTA_WIFI alias; must agree with transfer'
+            # Bluetooth transport infers :ble; TCP transport infers :wifi.
           )
 
           # Ask the node to enter DFU / UF2 bootloader mode.
           #{self}.enter_dfu(
-            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+            transport_obj: 'required - connected Serial, Bluetooth, TCP handle or MQTT client'
           )
 
           # Reject the obsolete unhandled legacy OTA reboot field.
@@ -241,7 +280,8 @@ module Meshtastic
 
           # Upload using an explicitly selected native loader protocol.
           #{self}.install(
-            protocol: 'required - :unified_wifi, :unified_ble, :esp_rom or :nordic_dfu; no protocol guessing',
+            protocol: 'required - :unified_wifi, :unified_ble, :esp_rom, :nordic_dfu, :uf2 or :swd; no protocol guessing',
+            format: 'optional - :bin, :zip, :uf2 or :hex; defaults to the selected protocol format; mismatches rejected',
             verify: 'optional - verify_reboot options Hash; success becomes :boot_verified only after a fresh reply',
             host: 'required - OTA loader IP address or hostname, not a mesh node ID',
             port: 'optional - separate OTA TCP service port (default: 3232)',
@@ -251,9 +291,9 @@ module Meshtastic
             retries: 'optional - connection refusal/timeout retries, 0..20 (default: 3)',
             retry_delay: 'optional - nonnegative seconds between connection retries (default: 1)'
           )
-          # First use request_ota with the matching mode to pin the same image hash.
+          # For unified OTA first use request_ota with the matching transfer to pin the same image hash.
           # install never sends preparation commands; :verified means loader OK, not boot confirmation.
-          # BLE.help, NordicDFU.help and SerialBootloader.help document protocol-specific options.
+          # BLE.help, NordicDFU.help, SerialBootloader.help, UF2.help and Hex.help document backend options.
 
           # Reconnect and request fresh correlated application firmware metadata.
           #{self}.verify_reboot(
@@ -286,3 +326,5 @@ end
 require 'meshtastic/admin/firmware/ble'
 require 'meshtastic/admin/firmware/serial_bootloader'
 require 'meshtastic/admin/firmware/nordic_dfu'
+require 'meshtastic/admin/firmware/uf2'
+require 'meshtastic/admin/firmware/hex'