meshtastic 0.0.182 → 0.0.183

data/spec/lib/meshtastic/admin/firmware/hex_spec.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tmpdir'
+require 'json'
+require 'rbconfig'
+require 'open3'
+require 'meshtastic/admin/firmware/hex' if File.file?(File.expand_path('../../../../../lib/meshtastic/admin/firmware/hex.rb', __dir__))
+
+describe 'Meshtastic::Admin::Firmware::Hex' do
+  def record(type, address = 0, data = [])
+    bytes = [data.length, address >> 8, address & 255, type] + data
+    ":#{(bytes + [(-bytes.sum) & 255]).pack('C*').unpack1('H*').upcase}\n"
+  end
+
+  def backend
+    Meshtastic::Admin::Firmware.const_get(:Hex)
+  end
+
+  let(:image) { record(0, 0, [1, 2, 3, 4]) + record(1) }
+
+  it 'runs a real fake executable with guarded write, verify and reset commands' do
+    Dir.mktmpdir('hex test ;[]$') do |dir|
+      executable = File.join(dir, 'fake openocd')
+      log = File.join(dir, 'argv.json')
+      File.write(executable, <<~RUBY)
+        #!#{RbConfig.ruby}
+        require 'json'
+        File.write(#{log.inspect}, JSON.generate(ARGV))
+        script = ARGV.last
+        puts script[/MESHTASTIC_HEX_OK_[a-f0-9]+/]
+      RUBY
+      File.chmod(0o700, executable)
+      config = File.join(dir, 'trusted.cfg')
+      File.write(config, '# trusted test configuration')
+      firmware = File.join(dir, 'input ;[$].hex')
+      File.binwrite(firmware, image)
+      result = backend.install(protocol: :swd, firmware: firmware, expected_chip: :nrf52840,
+                               expected_target: 'nrf52.cpu', openocd: executable,
+                               interface_config: config, target_config: config)
+      expect(result).to include(status: :verified, flash_verified: true, reboot_verified: false)
+      args = JSON.parse(File.read(log))
+      expect(args).to include(config, 'transport select swd')
+      script = args.last
+      expect(script).to include('0x10000100', '0x52840', 'flash write_image erase', 'verify_image', 'reset run', 'shutdown error')
+      expect(script.index('0x10000100')).to be < script.index('flash write_image erase')
+      expect(script.index('verify_image')).to be < script.index('reset run')
+      expect(script).not_to include('mass_erase')
+    end
+  end
+
+  it 'quotes braces and substitution characters even inside a braced Tcl catch' do
+    value = '/tmp/a}b{c\\d"e[$x];file.hex'
+    word = backend.send(:tcl_word, value: value)
+    output, error, status = Open3.capture3('tclsh', stdin_data: "if {[catch {set path #{word}; puts $path} failure]} {puts stderr $failure; exit 1}\n")
+    expect(status.success?).to be(true), error
+    expect(output.chomp).to eq(value)
+  end
+
+  it 'rejects malformed records, unknown types, missing EOF and overlaps' do
+    invalid = [image.sub('01020304', '01020305'), image.sub(':04', ':05'), image + record(1),
+               record(0, 0, [1]), record(1), "\n#{image}", "#{image}\n", ':zz',
+               record(6) + image, record(1, 1), record(1, 0, [1]),
+               record(2, 1, [0, 0]) + image, record(4, 0, [0]) + image,
+               record(0, 0, []) + record(1), record(0, 65_535, [1, 2]) + record(1),
+               record(0, 0, [1, 2]) + record(0, 1, [2]) + record(1),
+               record(4, 0, [255, 255]) + record(0, 65_535, [1]) + record(1),
+               (record(5, 0, [0, 0, 0, 1]) * 2) + image,
+               record(5, 0, [0, 16, 0, 0]) + image]
+    invalid.each do |bytes|
+      expect { backend.validate(bytes: bytes, expected_chip: :nrf52840) }.to raise_error(ArgumentError)
+    end
+    expect { backend.validate(bytes: image, expected_chip: :nrf52832) }.to raise_error(ArgumentError)
+  end
+
+  it 'handles segment and linear bases, UICR, CRLF and start records' do
+    bytes = record(2, 0, [0x10, 0]) + record(0, 0, [1]) + record(4, 0, [0x10, 0]) +
+            record(0, 0x1000, [2]) + record(5, 0, [0, 1, 0, 1]) + record(1)
+    expect(backend.validate(bytes: bytes.gsub("\n", "\r\n"), expected_chip: :nrf52840)).to include(ranges: [[0x10000, 0x10001], [0x10001000, 0x10001001]], start_address: 0x10001)
+    bytes = record(3, 0, [0x10, 0, 0, 1]) + image
+    expect(backend.validate(bytes: bytes, expected_chip: :nrf52840)[:start_address]).to eq(0x10001)
+  end
+
+  it 'requires actual subprocess success and a completion marker and bounds runtime' do
+    Dir.mktmpdir do |dir|
+      executable = File.join(dir, 'openocd')
+      config = File.join(dir, 'config')
+      File.write(config, '# test')
+      options = { protocol: :swd, bytes: image, expected_chip: :nrf52840, expected_target: 'nrf52.cpu',
+                  openocd: executable, interface_config: config, target_config: config }
+      ['exit 0', 'puts ARGV.last[/MESHTASTIC_HEX_OK_[a-f0-9]+/]; exit 1', 'sleep 10'].each do |body|
+        File.write(executable, "#!#{RbConfig.ruby}\n#{body}\n")
+        File.chmod(0o700, executable)
+        expect { backend.install(options.merge(timeout: 0.2)) }.to raise_error(IOError)
+      end
+      File.write(executable, "#!#{RbConfig.ruby}\nabort 'must not run'\n")
+      [{ bytes: image.sub('01020304', '01020305') }, { expected_target: 'x;exit' },
+       { expected_chip: :esp32 }, { protocol: :serial }, { firmware: '/tmp/also.hex' },
+       { timeout: 0 }, { target_config: nil }, { openocd: 'openocd' }, { surprise: true }].each do |change|
+        expect { backend.install(options.merge(change)) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  it 'executes Tcl guards before erase and refuses failed verification or reset' do
+    Dir.mktmpdir do |dir|
+      executable = File.join(dir, 'openocd')
+      config = File.join(dir, 'config')
+      trace = File.join(dir, 'trace')
+      File.write(config, '# test')
+      options = { protocol: :swd, bytes: image, expected_chip: :nrf52840, expected_target: 'nrf52.cpu',
+                  openocd: executable, interface_config: config, target_config: config }
+      %w[success chip verify reset].each do |mode|
+        simulator = <<~TCL
+          set trace [open #{backend.send(:tcl_word, value: trace)} w]
+          proc init {} {}
+          proc targets {name} {if {$name ne "nrf52.cpu"} {error "wrong target"}}
+          proc reset {mode} {
+            if {$mode eq "run" && "#{mode}" eq "reset"} {error "reset failed"}
+            puts $::trace "reset $mode"
+          }
+          proc halt {} {}
+          proc read_memory {address width count} {
+            if {$address == 0x10000100} {return #{mode == 'chip' ? '0x52832' : '0x52840'}}
+            if {$address == 0x10000010} {return 4096}
+            return 256
+          }
+          proc flash {args} {puts $::trace flash}
+          proc verify_image {args} {
+            puts $::trace verify
+            if {"#{mode}" eq "verify"} {error "verification failed"}
+          }
+          proc echo {text} {puts $text}
+          proc shutdown {args} {close $::trace; if {[llength $args]} {exit 1}; exit 0}
+        TCL
+        File.write(executable, <<~RUBY)
+          #!#{RbConfig.ruby}
+          require 'open3'
+          output, error, status = Open3.capture3('tclsh', stdin_data: #{simulator.inspect} + ARGV.last)
+          print output
+          warn error unless error.empty?
+          exit status.exitstatus
+        RUBY
+        File.chmod(0o700, executable)
+        if mode == 'success'
+          expect(backend.install(options)[:flash_verified]).to be(true)
+          expect(File.read(trace)).to eq("reset init\nflash\nverify\nreset run\n")
+        else
+          expect { backend.install(options) }.to raise_error(IOError)
+          expect(File.read(trace)).not_to include('reset run')
+          expect(File.read(trace)).not_to include('flash') if mode == 'chip'
+        end
+      end
+    end
+  end
+
+  it 'validates Intel HEX bytes without a programmer or hardware' do
+    expect(backend.validate(bytes: image, expected_chip: :nrf52840)).to include(data_bytes: 4, ranges: [[0, 4]])
+  end
+end

data/spec/lib/meshtastic/admin/firmware/uf2_spec.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tmpdir'
+require 'meshtastic/admin/firmware/uf2' if File.exist?(File.expand_path('../../../../../lib/meshtastic/admin/firmware/uf2.rb', __dir__))
+
+shared_context 'UF2 bootloader files' do
+  def block(opts = {})
+    defaults = { number: 0, count: 1, address: 0x27000, family: 0xada52840, flags: 0x2000, size: 256 }.merge(opts)
+    [0x0a324655, 0x9e5d5157, defaults[:flags], defaults[:address], defaults[:size], defaults[:number], defaults[:count], defaults[:family]].pack('V8') + ('x' * 256).ljust(476, "\0") + [0x0ab16f30].pack('V')
+  end
+
+  around do |example|
+    Dir.mktmpdir('meshtastic-uf2-') do |dir|
+      @mount = File.join(dir, 'boot')
+      Dir.mkdir(@mount)
+      File.write(File.join(@mount, 'INFO_UF2.TXT'), "UF2 Bootloader 0.9.2\nModel: Test board\nBoard-ID: nRF52840-Test-v1\n")
+      @options = { protocol: :uf2, bytes: block, mount: @mount, board_id: 'nRF52840-Test-v1', family_id: 0xada52840 }
+      example.run
+    end
+  end
+end
+
+describe 'Meshtastic::Admin::Firmware::UF2 image validation' do
+  include_context 'UF2 bootloader files'
+
+  {
+    empty: -> { ''.b },
+    truncated: -> { block.byteslice(0, 511) },
+    trailing: -> { "#{block}x" },
+    mixed_families: -> { block(count: 2) + block(number: 1, count: 2, address: 0x27100, family: 0xe48bff56) },
+    duplicate_blocks: -> { block(count: 2) * 2 },
+    missing_block: -> { block(count: 2) },
+    inconsistent_count: -> { block(count: 2) + block(number: 1, address: 0x27100) },
+    out_of_range_number: -> { block(number: 1) },
+    no_family: -> { block(flags: 0) },
+    not_main_flash: -> { block(flags: 0x2001) },
+    file_container: -> { block(flags: 0x3000) },
+    md5_extension: -> { block(flags: 0x6000) },
+    extension_tags: -> { block(flags: 0xa000) },
+    unknown_flags: -> { block(flags: 0x12000) },
+    zero_payload: -> { block(size: 0) },
+    unsupported_page_size: -> { block(size: 128) },
+    unsupported_page_alignment: -> { block(address: 0x27004) },
+    oversized_payload: -> { block(size: 480) },
+    unaligned_payload: -> { block(size: 255) },
+    unaligned_address: -> { block(address: 0x27001) },
+    bootloader_address: -> { block(address: 0xf4000) },
+    softdevice_address: -> { block(address: 0) },
+    crossing_boundary: -> { block(address: 0xf3ffc) },
+    overflow_address: -> { block(address: 0xfffffffc) },
+    overlap: -> { block(count: 2) + block(number: 1, count: 2, address: 0x27000) }
+  }.each do |name, image|
+    it "rejects #{name} before creating the destination" do
+      expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(bytes: instance_exec(&image))) }.to raise_error(ArgumentError)
+      expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+    end
+  end
+
+  it 'rejects numeric lookalikes for family identifiers' do
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(family_id: 0xada52840.to_f)) }.to raise_error(ArgumentError)
+    expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'checks every magic word in every block' do
+    [0, 4, 508].each do |offset|
+      bytes = block(count: 2) + block(number: 1, count: 2, address: 0x27100)
+      bytes.setbyte(512 + offset, 0)
+      expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(bytes: bytes)) }.to raise_error(ArgumentError, /magic/)
+    end
+  end
+
+  it 'requires explicit :uf2 protocol and rejects unknown options' do
+    [@options.except(:protocol), @options.merge(protocol: :esp_rom), @options.merge(offset: 0)].each do |options|
+      expect { Meshtastic::Admin::Firmware::UF2.install(options) }.to raise_error(ArgumentError)
+    end
+    expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'validates the source file and accepts exactly one immutable snapshot' do
+    source = File.join(File.dirname(@mount), 'input.uf2')
+    File.binwrite(source, block)
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(firmware: source)) }.to raise_error(ArgumentError)
+    result = Meshtastic::Admin::Firmware::UF2.install(@options.except(:bytes).merge(firmware: source))
+    expect(result[:sha256]).to eq(Digest::SHA256.hexdigest(File.binread(source)))
+    expect(File.binread(File.join(@mount, 'FIRMWARE.UF2'))).to eq(File.binread(source))
+  end
+
+  it 'rejects missing or non-string bytes and unknown families before writing' do
+    [@options.except(:bytes), @options.merge(bytes: nil), @options.merge(bytes: 42), @options.merge(family_id: 123)].each do |options|
+      expect { Meshtastic::Admin::Firmware::UF2.install(options) }.to raise_error(ArgumentError)
+    end
+  end
+
+  it 'submits an RP2040 flash image only inside the explicitly supplied flash capacity' do
+    File.write(File.join(@mount, 'INFO_UF2.TXT'), "UF2 Bootloader v3.0\nModel: Raspberry Pi RP2\nBoard-ID: RPI-RP2\n")
+    options = @options.merge(bytes: block(address: 0x10000000, family: 0xe48bff56), board_id: 'RPI-RP2', family_id: 0xe48bff56)
+    expect { Meshtastic::Admin::Firmware::UF2.install(options) }.to raise_error(ArgumentError, /flash_size/)
+    result = Meshtastic::Admin::Firmware::UF2.install(options.merge(flash_size: 2 * 1024 * 1024))
+    expect(result[:status]).to eq(:copied)
+    expect(File.binread(result[:destination])).to eq(options[:bytes])
+  end
+
+  it 'rejects RP2040 RAM, flash overflow and invalid capacities' do
+    File.write(File.join(@mount, 'INFO_UF2.TXT'), "UF2 Bootloader v3.0\nBoard-ID: RPI-RP2\n")
+    options = @options.merge(board_id: 'RPI-RP2', family_id: 0xe48bff56, flash_size: 2 * 1024 * 1024)
+    [0x20000000, 0x10200000, 0x101ffffc].each do |address|
+      expect { Meshtastic::Admin::Firmware::UF2.install(options.merge(bytes: block(address: address, family: 0xe48bff56))) }.to raise_error(ArgumentError)
+    end
+    [0, -1, '2097152', 32 * 1024 * 1024].each do |size|
+      expect { Meshtastic::Admin::Firmware::UF2.install(options.merge(flash_size: size)) }.to raise_error(ArgumentError)
+    end
+  end
+end
+
+describe 'Meshtastic::Admin::Firmware::UF2 mount safety' do
+  include_context 'UF2 bootloader files'
+
+  it 'refuses a directory without INFO_UF2.TXT' do
+    File.unlink(File.join(@mount, 'INFO_UF2.TXT'))
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(ArgumentError, /INFO_UF2/)
+    expect(Dir.children(@mount)).to be_empty
+  end
+
+  it 'requires a canonical absolute directory selected by the caller' do
+    [nil, '', '.', '/', File.join(@mount, '..', 'boot')].each do |mount|
+      expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(mount: mount)) }.to raise_error(ArgumentError)
+    end
+    expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'refuses a symlinked directory or parent directory' do
+    link = File.join(File.dirname(@mount), 'link')
+    File.symlink(@mount, link)
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(mount: link)) }.to raise_error(ArgumentError)
+    File.unlink(link)
+    File.symlink(File.dirname(@mount), link)
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(mount: File.join(link, 'boot'))) }.to raise_error(ArgumentError)
+    expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'refuses a symlinked or nonregular marker' do
+    marker = File.join(@mount, 'INFO_UF2.TXT')
+    saved = File.join(File.dirname(@mount), 'saved')
+    File.rename(marker, saved)
+    File.symlink(saved, marker)
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(ArgumentError)
+    File.unlink(marker)
+    File.mkfifo(marker)
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(ArgumentError)
+    expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'checks the exact expected Board-ID and its MCU family' do
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(board_id: 'nRF52840-Other-v1')) }.to raise_error(ArgumentError)
+    File.write(File.join(@mount, 'INFO_UF2.TXT'), "UF2 Bootloader v3.0\nBoard-ID: RPI-RP2\n")
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(board_id: 'RPI-RP2')) }.to raise_error(ArgumentError)
+    expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'rejects malformed, oversized, missing and duplicate board metadata' do
+    ["Board-ID: nRF52840-Test-v1\n", "UF2 Bootloader\n", "UF2 Bootloader\nBoard-ID: nRF52840-Test-v1\nBoard-ID: nRF52840-Test-v1\n", 'x' * 4097].each do |text|
+      File.write(File.join(@mount, 'INFO_UF2.TXT'), text)
+      expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(ArgumentError)
+      expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+    end
+  end
+
+  it 'recognizes the lowercase standard marker filename' do
+    File.rename(File.join(@mount, 'INFO_UF2.TXT'), File.join(@mount, 'info_uf2.txt'))
+    expect(Meshtastic::Admin::Firmware::UF2.install(@options)[:status]).to eq(:copied)
+  end
+
+  it 'never overwrites existing destinations or follows destination symlinks' do
+    destination = File.join(@mount, 'FIRMWARE.UF2')
+    File.write(destination, 'existing')
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(Errno::EEXIST)
+    expect(File.read(destination)).to eq('existing')
+    File.unlink(destination)
+    outside = File.join(File.dirname(@mount), 'outside')
+    File.write(outside, 'untouched')
+    File.symlink(outside, destination)
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(Errno::EEXIST)
+    expect(File.read(outside)).to eq('untouched')
+  end
+
+  it 'does not redirect writes when the chosen mount is replaced during validation' do
+    original_mount = "#{@mount}-old"
+    allow(File).to receive(:stat).and_call_original
+    allow(File).to receive(:stat).with(@mount).and_wrap_original do |method, path|
+      File.rename(@mount, original_mount)
+      Dir.mkdir(@mount)
+      method.call(path)
+    end
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(IOError, /mount changed/)
+    expect(Dir.children(@mount)).to be_empty
+    expect(Dir.children(original_mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'propagates disconnect or fsync failure without claiming success or retrying' do
+    attempts = 0
+    allow(File).to receive(:open).and_wrap_original do |method, path, *args, &callback|
+      if path.end_with?('/FIRMWARE.UF2')
+        attempts += 1
+        method.call(path, *args) do |file|
+          allow(file).to receive(:fsync).and_raise(Errno::ENODEV)
+          callback.call(file)
+        end
+      else
+        method.call(path, *args, &callback)
+      end
+    end
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options) }.to raise_error(Errno::ENODEV)
+    expect(attempts).to eq(1)
+  end
+
+  it 'allows shuffled blocks and holes without reinterpreting addresses or reordering bytes' do
+    bytes = block(number: 1, count: 2, address: 0x28000) + block(count: 2)
+    Meshtastic::Admin::Firmware::UF2.install(@options.merge(bytes: bytes))
+    expect(File.binread(File.join(@mount, 'FIRMWARE.UF2'))).to eq(bytes)
+  end
+
+  it 'rejects a raw binary image without writing anything' do
+    expect { Meshtastic::Admin::Firmware::UF2.install(@options.merge(bytes: 'x' * 512)) }.to raise_error(ArgumentError, /magic/)
+    expect(Dir.children(@mount)).to eq(['INFO_UF2.TXT'])
+  end
+
+  it 'copies intact UF2 bytes to an explicitly selected bootloader without claiming flash verification' do
+    expect(Meshtastic::Admin::Firmware.const_defined?(:UF2)).to be true
+    result = Meshtastic::Admin::Firmware::UF2.install(@options)
+    expect(File.binread(File.join(@mount, 'FIRMWARE.UF2'))).to eq(block)
+    expect(result).to include(status: :copied, protocol: :uf2, bytes: 512, family_id: 0xada52840, board_id: 'nRF52840-Test-v1', flash_verified: false, reboot_verified: false)
+  end
+end

data/spec/lib/meshtastic/admin/firmware_spec.rb

@@ -1,10 +1,101 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+
+RSpec.describe Meshtastic::Admin::Firmware do
+  it 'documents transport_obj rather than legacy connection keywords' do
+    expect { described_class.help }.to output(/transport_obj:/).to_stdout
+    expect { described_class.help }.not_to output(/serial_obj:|bluetooth_obj:|tcp_obj:|mqtt_obj:/).to_stdout
+  end
+end
 require 'socket'
 require 'digest'
 require 'tempfile'
 
+RSpec.describe Meshtastic::Admin::Firmware do
+  it 'dispatches Intel HEX to the explicit SWD programmer' do
+    expect(described_class.const_defined?(:Hex, false)).to be true
+    options = { protocol: :swd, bytes: ':00000001FF', expected_chip: :nrf52840 }
+    expect(described_class::Hex).to receive(:install).with(options).and_return(status: :verified)
+    expect(described_class.install(options.merge(format: :hex))).to eq(status: :verified)
+  end
+
+  it 'rejects legacy OTA connection keys explicitly before inference or file access' do
+    %i[serial_obj bluetooth_obj tcp_obj mqtt_obj].each do |key|
+      expect(Meshtastic::Admin).not_to receive(:send)
+      expect { described_class.request_ota(key => nil, firmware: '/missing') }
+        .to raise_error(ArgumentError, /#{key}.*transport_obj/)
+    end
+  end
+
+  it 'separates explicit OTA transfer selection from the Admin control handle' do
+    handle = { serial_conn: Object.new }
+    expect(Meshtastic::Admin).to receive(:send) do |options|
+      expect(options[:transport_obj]).to equal(handle)
+      expect(options).not_to have_key(:transfer)
+      expect(options[:ota_request].reboot_ota_mode).to eq(:OTA_WIFI)
+    end
+    described_class.request_ota(transport_obj: handle, transfer: :wifi, bytes: 'abc')
+  end
+
+  it 'requires an unambiguous supported transfer choice before sending OTA' do
+    invalid = [{ transport_obj: { serial_conn: Object.new } }, { transport_obj: MQTT::Client.new }, {},
+               { transfer: :mqtt }, { transfer: nil }, { transfer: :wifi, mode: :OTA_BLE },
+               { transfer: :ble, mode: :UNKNOWN }]
+    expect(Meshtastic::Admin).not_to receive(:send)
+    invalid.each do |options|
+      expect { described_class.request_ota(options.merge(bytes: 'abc')) }.to raise_error(ArgumentError, /transfer|mode/)
+    end
+  end
+
+  it 'infers OTA transfer only from a single Bluetooth or TCP control handle' do
+    tcp_socket = Object.new
+    [{ transport_obj: { bluetooth_conn: Object.new } },
+     { transport_obj: { tcp_socket: tcp_socket, serial_conn: tcp_socket } }].zip(%i[OTA_BLE OTA_WIFI]).each do |options, mode|
+      expect(Meshtastic::Admin).to receive(:send) { |request| expect(request[:ota_request].reboot_ota_mode).to eq(mode) }
+      described_class.request_ota(options.merge(bytes: 'abc'))
+    end
+  end
+
+  it 'dispatches explicit UF2 format to the mounted-volume installer' do
+    expect(described_class.const_defined?(:UF2, false)).to be true
+    options = { protocol: :uf2, bytes: 'UF2 fixture', mount: '/selected/volume' }
+    expect(described_class::UF2).to receive(:install).with(options).and_return(status: :copied)
+    expect(described_class.install(options.merge(format: :uf2))).to eq(status: :copied)
+  end
+
+  it 'rejects incompatible declared formats before invoking an installer' do
+    expect(described_class::BLE).not_to receive(:install)
+    expect(described_class::SerialBootloader).not_to receive(:install)
+    expect(described_class::NordicDFU).not_to receive(:install)
+    expect(Socket).not_to receive(:tcp)
+    { unified_wifi: :uf2, unified_ble: :zip, esp_rom: :hex, nordic_dfu: :bin }.each do |protocol, format|
+      expect { described_class.install(protocol: protocol, format: format, bytes: 'abc') }.to raise_error(ArgumentError, /format/)
+    end
+  end
+
+  it 'rejects UF2 ZIP and Intel HEX content before opening binary loaders' do
+    expect(described_class::BLE).not_to receive(:install)
+    expect(described_class::SerialBootloader).not_to receive(:install)
+    expect(Socket).not_to receive(:tcp)
+    images = ["#{[0x0a324655, 0x9e5d5157].pack('V2')}payload", "PK\x03\x04archive", ':020000040000FA\n']
+    %i[unified_wifi unified_ble esp_rom].each do |protocol|
+      images.each do |bytes|
+        expect { described_class.install(protocol: protocol, bytes: bytes) }.to raise_error(ArgumentError, /format/)
+      end
+    end
+  end
+
+  it 'rejects nonbinary filename formats even when their contents look binary' do
+    expect(described_class::BLE).not_to receive(:install)
+    Tempfile.create(['image', '.uf2']) do |file|
+      file.write('abc')
+      file.flush
+      expect { described_class.install(protocol: :unified_ble, format: :bin, firmware: file.path) }.to raise_error(ArgumentError, /format/)
+    end
+  end
+end
+
 RSpec.describe Meshtastic::Admin::Firmware do
   it 'dispatches explicitly to independent native bootloader protocols' do
     %i[esp_rom nordic_dfu].each do |protocol|
@@ -39,6 +130,17 @@ RSpec.describe Meshtastic::Admin::Firmware do
     end
   end
 
+  it 'uses transport_obj for reboot metadata but named keys for low-level lifecycle calls' do
+    handle = { serial_conn: Object.new, my_node_num: 123 }
+    expect(Meshtastic::Serial).to receive(:wait_for_config).with(serial_obj: handle, timeout: 1).and_return(handle)
+    expect(Meshtastic::Serial).to receive(:disconnect).with(serial_obj: handle)
+    expect(Meshtastic::Admin).to receive(:request).with(transport_obj: handle, get_device_metadata_request: true, timeout: 1)
+                                                  .and_return(value: Meshtastic::DeviceMetadata.new(firmware_version: 'expected'))
+    result = described_class.verify_reboot(transport: :serial, reconnect: ->(_options) { handle },
+                                           expected_version: 'expected', reboot_delay: 0, timeout: 1)
+    expect(result).to include(status: :boot_verified, node_num: 123)
+  end
+
   it 'ignores cached metadata and checks a fresh correlated Admin reply after callback reconnect' do
     queue = Queue.new
     writer = Object.new
@@ -170,6 +272,7 @@ describe Meshtastic::Admin::Firmware do
     [{ bytes: '' }, { bytes: 123 }, { bytes: nil }, { firmware: '/missing', bytes: 'abc' },
      { host: '' }, { port: 0 }, { timeout: 0 }, { timeout: Float::INFINITY },
      { retries: -1 }, { retry_delay: -1 }, { mode: :OTA_BLE }, { tcp_obj: Object.new },
+     { transport_obj: { tcp_socket: Object.new, serial_conn: Object.new } },
      { to: '!aabbccdd' }, { protocol: :unified_wifi, bluetooth_obj: Object.new }].each do |invalid|
       expect(Socket).not_to receive(:tcp)
       expect { described_class.install(defaults.merge(invalid)) }.to raise_error(ArgumentError)
@@ -197,7 +300,7 @@ describe Meshtastic::Admin::Firmware do
     end
     connection.define_singleton_method(:flush) { true }
     serial = { serial_conn: connection, my_node_num: 0xb0b }
-    described_class.request_ota(serial_obj: serial, bytes: 'abc', mode: :OTA_WIFI)
+    described_class.request_ota(transport_obj: serial, bytes: 'abc', mode: :OTA_WIFI)
     length = written.byteslice(2, 2).unpack1('n')
     packet = Meshtastic::ToRadio.decode(written.byteslice(4, length)).packet
     admin = Meshtastic::AdminMessage.decode(packet.decoded.payload)
@@ -205,7 +308,7 @@ describe Meshtastic::Admin::Firmware do
     expect(admin.ota_request.reboot_ota_mode).to eq(:OTA_WIFI)
     expect(admin.ota_request.ota_hash).to eq(Digest::SHA256.digest('abc'))
     written.clear
-    described_class.enter_dfu(serial_obj: serial)
+    described_class.enter_dfu(transport_obj: serial)
     length = written.byteslice(2, 2).unpack1('n')
     packet = Meshtastic::ToRadio.decode(written.byteslice(4, length)).packet
     expect(Meshtastic::AdminMessage.decode(packet.decoded.payload).enter_dfu_mode_request).to be true
@@ -306,7 +409,7 @@ describe Meshtastic::Admin::Firmware do
   end
 
   it 'rejects PhoneAPI and MQTT installation without sending any commands' do
-    %i[serial_obj tcp_obj bluetooth_obj mqtt_obj].each do |transport|
+    %i[transport_obj serial_obj tcp_obj bluetooth_obj mqtt_obj].each do |transport|
       expect(Meshtastic::Admin).not_to receive(:send)
       expect { described_class.install(transport => Object.new, bytes: 'abc') }
         .to raise_error(NotImplementedError, /unified_wifi/)