meshtastic 0.0.182 → 0.0.184

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

@@ -2,6 +2,13 @@
 
 require 'spec_helper'
 
+RSpec.describe Meshtastic::Admin::Channel 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
+
 shared_context 'channel serial framing' do
   def fake_serial_obj
     written = +''.b
@@ -26,16 +33,23 @@ end
 describe Meshtastic::Admin::Channel do
   include_context 'channel serial framing'
 
+  it 'rejects legacy connection keys before filtering or building channel options' do
+    %i[serial_obj bluetooth_obj tcp_obj mqtt_obj].each do |key|
+      expect { described_class.set(transport_obj: fake_serial_obj, key => nil, index: -1) }
+        .to raise_error(ArgumentError, /#{key}.*transport_obj/)
+    end
+  end
+
   it 'requests a channel by index via Admin' do
     serial_obj = fake_serial_obj
-    described_class.get(serial_obj: serial_obj, index: 1)
+    described_class.get(transport_obj: serial_obj, index: 1)
     expect(decode_admin(serial_obj).get_channel_request).to eq(2)
   end
 
   [0, 7].each do |index|
     it "requests zero-based slot #{index} with its one-based wire index" do
       serial_obj = fake_serial_obj
-      described_class.get(serial_obj: serial_obj, index: index)
+      described_class.get(transport_obj: serial_obj, index: index)
       expect(decode_admin(serial_obj).get_channel_request).to eq(index + 1)
     end
   end
@@ -43,7 +57,7 @@ describe Meshtastic::Admin::Channel do
   it 'sets a Channel protobuf including settings and role' do
     serial_obj = fake_serial_obj
     settings = described_class.build_settings(name: 'LongFast', uplink_enabled: true)
-    described_class.set(serial_obj: serial_obj, index: 0, role: :PRIMARY, settings: settings)
+    described_class.set(transport_obj: serial_obj, index: 0, role: :PRIMARY, settings: settings)
     channel = decode_admin(serial_obj).set_channel
     expect(channel.index).to eq(0)
     expect(channel.role).to eq(:PRIMARY)
@@ -124,7 +138,7 @@ describe Meshtastic::Admin::Channel, 'channel URL support' do
   it 'rejects invalid settings lengths and slot indexes before any write' do
     [-1, 8, 0.5, 'junk'].each do |index|
       serial_obj = fake_serial_obj
-      expect { described_class.set(serial_obj: serial_obj, index: index, role: :PRIMARY) }.to raise_error(ArgumentError)
+      expect { described_class.set(transport_obj: serial_obj, index: index, role: :PRIMARY) }.to raise_error(ArgumentError)
       expect(serial_obj[:written]).to be_empty
     end
     expect { described_class.build_settings(psk: 'bad') }.to raise_error(ArgumentError)
@@ -137,7 +151,7 @@ describe Meshtastic::Admin::Channel, 'channel URL support' do
   it 'validates and overlays supplied channel/settings before transmission' do
     serial_obj = fake_serial_obj
     original = Meshtastic::Channel.new(index: 2, role: :SECONDARY, settings: { name: 'before', uplink_enabled: true })
-    described_class.set(serial_obj: serial_obj, channel: original, name: 'after', uplink_enabled: false)
+    described_class.set(transport_obj: serial_obj, channel: original, name: 'after', uplink_enabled: false)
     written = decode_admin(serial_obj).set_channel
     expect(written.index).to eq(2)
     expect(written.settings.name).to eq('after')
@@ -145,7 +159,7 @@ describe Meshtastic::Admin::Channel, 'channel URL support' do
     expect(original.settings.name).to eq('before')
     expect(described_class.build(settings: { name: 'hash' }).settings.name).to eq('hash')
     invalid = Meshtastic::Channel.new(index: 8)
-    expect { described_class.set(serial_obj: fake_serial_obj, channel: invalid) }.to raise_error(ArgumentError)
+    expect { described_class.set(transport_obj: fake_serial_obj, channel: invalid) }.to raise_error(ArgumentError)
     expect { described_class.build(settings: { psk: 'bad' }) }.to raise_error(ArgumentError)
   end
 
@@ -153,7 +167,7 @@ describe Meshtastic::Admin::Channel, 'channel URL support' do
     serial_obj = fake_serial_obj
     channel_set = Meshtastic::ChannelSet.new(settings: [{ name: 'main' }, { name: 'other' }], lora_config: { region: :US })
     url = "https://meshtastic.org/e/##{Base64.urlsafe_encode64(channel_set.to_proto, padding: false)}"
-    results = described_class.apply_url(serial_obj: serial_obj, url: url, session_passkey: 'test-key')
+    results = described_class.apply_url(transport_obj: serial_obj, url: url, session_passkey: 'test-key')
     frames = serial_obj[:written].dup
     messages = []
     until frames.empty?
@@ -176,11 +190,11 @@ describe Meshtastic::Admin::Channel, 'channel URL support' do
     serial_obj = fake_serial_obj
     invalid = Meshtastic::ChannelSet.new(settings: [{ name: 'good' }, { psk: 'bad' }])
     url = "https://meshtastic.org/e/##{Base64.urlsafe_encode64(invalid.to_proto, padding: false)}"
-    expect { described_class.apply_url(serial_obj: serial_obj, url: url) }.to raise_error(ArgumentError)
+    expect { described_class.apply_url(transport_obj: serial_obj, url: url) }.to raise_error(ArgumentError)
     expect(serial_obj[:written]).to be_empty
     valid = Meshtastic::ChannelSet.new(settings: [{ name: 'test' }])
     url = "https://meshtastic.org/e/?add=true##{Base64.urlsafe_encode64(valid.to_proto, padding: false)}"
-    expect { described_class.apply_url(serial_obj: serial_obj, url: url) }.to raise_error(ArgumentError, /add-only/)
+    expect { described_class.apply_url(transport_obj: serial_obj, url: url) }.to raise_error(ArgumentError, /add-only/)
     expect(serial_obj[:written]).to be_empty
   end
 

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

@@ -2,6 +2,13 @@
 
 require 'spec_helper'
 
+RSpec.describe Meshtastic::Admin::Config 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
+
 describe Meshtastic::Admin::Config do
   def fake_serial_obj
     written = +''.b
@@ -22,9 +29,18 @@ describe Meshtastic::Admin::Config do
     Meshtastic::AdminMessage.decode(Meshtastic::ToRadio.decode(body).packet.decoded.payload)
   end
 
+  it 'rejects legacy connection keys rather than silently filtering them' do
+    %i[serial_obj bluetooth_obj tcp_obj mqtt_obj].each do |key|
+      handle = fake_serial_obj
+      expect { described_class.set_device_ui(transport_obj: handle, key => nil, device_ui: {}) }
+        .to raise_error(ArgumentError, /#{key}/)
+      expect(handle[:written]).to be_empty
+    end
+  end
+
   it 'requests LoRa config via Admin' do
     serial_obj = fake_serial_obj
-    described_class.get(serial_obj: serial_obj, config_type: :LORA_CONFIG)
+    described_class.get(transport_obj: serial_obj, config_type: :LORA_CONFIG)
     expect(decode_admin(serial_obj).get_config_request).to eq(:LORA_CONFIG)
   end
 
@@ -32,13 +48,13 @@ describe Meshtastic::Admin::Config do
     serial_obj = fake_serial_obj
     config = Meshtastic::Config.new
     config.device = Meshtastic::Config::DeviceConfig.new(role: :CLIENT)
-    described_class.set(serial_obj: serial_obj, config: config)
+    described_class.set(transport_obj: serial_obj, config: config)
     expect(decode_admin(serial_obj).set_config.device.role).to eq(:CLIENT)
   end
 
   it 'requests each ConfigType via named getters' do
     serial_obj = fake_serial_obj
-    described_class.get_lora(serial_obj: serial_obj)
+    described_class.get_lora(transport_obj: serial_obj)
     expect(decode_admin(serial_obj).get_config_request).to eq(:LORA_CONFIG)
   end
 
@@ -48,7 +64,7 @@ describe Meshtastic::Admin::Config do
     it "writes the #{field.name} section through real serial framing" do
       serial_obj = fake_serial_obj
       section = field.subtype.msgclass.new
-      described_class.public_send("set_#{field.name}", serial_obj: serial_obj, field.name.to_sym => section)
+      described_class.public_send("set_#{field.name}", transport_obj: serial_obj, field.name.to_sym => section)
       config = decode_admin(serial_obj).set_config
       expect(config.payload_variant).to eq(field.name.to_sym)
       expect(config[field.name]).to eq(section)
@@ -57,7 +73,7 @@ describe Meshtastic::Admin::Config do
 
   it 'rejects an empty config before writing bytes' do
     serial_obj = fake_serial_obj
-    expect { described_class.set(serial_obj: serial_obj, config: Meshtastic::Config.new) }.to raise_error(ArgumentError)
+    expect { described_class.set(transport_obj: serial_obj, config: Meshtastic::Config.new) }.to raise_error(ArgumentError)
     expect(serial_obj[:written]).to be_empty
   end
 
@@ -66,31 +82,31 @@ describe Meshtastic::Admin::Config do
 
     it "accepts a field hash for #{field.name}" do
       serial_obj = fake_serial_obj
-      described_class.public_send("set_#{field.name}", serial_obj: serial_obj, field.name.to_sym => {})
+      described_class.public_send("set_#{field.name}", transport_obj: serial_obj, field.name.to_sym => {})
       expect(decode_admin(serial_obj).set_config.payload_variant).to eq(field.name.to_sym)
     end
 
     it "rejects missing #{field.name} before writing bytes" do
       serial_obj = fake_serial_obj
-      expect { described_class.public_send("set_#{field.name}", serial_obj: serial_obj) }.to(raise_error { |error| expect([ArgumentError, KeyError]).to include(error.class) })
+      expect { described_class.public_send("set_#{field.name}", transport_obj: serial_obj) }.to(raise_error { |error| expect([ArgumentError, KeyError]).to include(error.class) })
       expect(serial_obj[:written]).to be_empty
     end
   end
 
   it 'uses dedicated device UI requests and stores instead of firmware no-op Config fields' do
     serial_obj = fake_serial_obj
-    described_class.get_device_ui(serial_obj: serial_obj)
+    described_class.get_device_ui(transport_obj: serial_obj)
     expect(decode_admin(serial_obj).payload_variant).to eq(:get_ui_config_request)
     serial_obj = fake_serial_obj
-    described_class.set_device_ui(serial_obj: serial_obj, device_ui: {})
+    described_class.set_device_ui(transport_obj: serial_obj, device_ui: {})
     expect(decode_admin(serial_obj).payload_variant).to eq(:store_ui_config)
   end
 
   it 'rejects the read-only session-key placeholder without transmitting' do
     serial_obj = fake_serial_obj
     config = Meshtastic::Config.new(sessionkey: {})
-    expect { described_class.set(serial_obj: serial_obj, config: config) }.to raise_error(ArgumentError, /request-only/)
-    expect { described_class.set_sessionkey(serial_obj: serial_obj, sessionkey: {}) }.to raise_error(ArgumentError, /request-only/)
+    expect { described_class.set(transport_obj: serial_obj, config: config) }.to raise_error(ArgumentError, /request-only/)
+    expect { described_class.set_sessionkey(transport_obj: serial_obj, sessionkey: {}) }.to raise_error(ArgumentError, /request-only/)
     expect(serial_obj[:written]).to be_empty
   end
 
@@ -101,7 +117,7 @@ describe Meshtastic::Admin::Config do
   }.each do |section, config_type|
     it "requests #{section} using its protocol ConfigType" do
       serial_obj = fake_serial_obj
-      described_class.public_send("get_#{section}", serial_obj: serial_obj)
+      described_class.public_send("get_#{section}", transport_obj: serial_obj)
       message = decode_admin(serial_obj)
       expect(message.payload_variant).to eq(:get_config_request)
       expect(message.get_config_request).to eq(config_type)

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