meshtastic 0.0.180 → 0.0.181

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

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe Meshtastic::Admin::Channel do
+shared_context 'channel serial framing' do
   def fake_serial_obj
     written = +''.b
     serial_conn = Object.new
@@ -21,11 +21,23 @@ describe Meshtastic::Admin::Channel do
     body = frame.byteslice(4, (frame.getbyte(2) << 8) + frame.getbyte(3))
     Meshtastic::AdminMessage.decode(Meshtastic::ToRadio.decode(body).packet.decoded.payload)
   end
+end
+
+describe Meshtastic::Admin::Channel do
+  include_context 'channel serial framing'
 
   it 'requests a channel by index via Admin' do
     serial_obj = fake_serial_obj
     described_class.get(serial_obj: serial_obj, index: 1)
-    expect(decode_admin(serial_obj).get_channel_request).to eq(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)
+      expect(decode_admin(serial_obj).get_channel_request).to eq(index + 1)
+    end
   end
 
   it 'sets a Channel protobuf including settings and role' do
@@ -39,6 +51,151 @@ describe Meshtastic::Admin::Channel do
     expect(channel.settings.uplink_enabled).to be true
   end
 
+  it 'copies an existing channel and preserves settings when changing its role' do
+    original = Meshtastic::Channel.new(index: 2, role: :SECONDARY, settings: { name: 'test', psk: "\x01".b })
+    updated = described_class.build(channel: original, role: :DISABLED)
+    expect(updated.settings).to eq(original.settings)
+    expect(original.role).to eq(:SECONDARY)
+    expect(updated).not_to equal(original)
+  end
+
+  it 'builds all settings including nested hashes without mutating existing settings' do
+    original = Meshtastic::ChannelSettings.new(name: 'before', uplink_enabled: true)
+    settings = described_class.build_settings(settings: original, name: 'after', psk: "\x01".b, channel_num: 3,
+                                              id: 17, uplink_enabled: false, downlink_enabled: true,
+                                              use_aead: true, module_settings: { position_precision: 13 })
+    expect(settings.to_h).to include(name: 'after', psk: "\x01".b, channel_num: 3, id: 17,
+                                     downlink_enabled: true, use_aead: true)
+    expect(settings.uplink_enabled).to be false
+    expect(settings.module_settings.position_precision).to eq(13)
+    expect(original.name).to eq('before')
+    expect(original.uplink_enabled).to be true
+  end
+end
+
+describe Meshtastic::Admin::Channel, 'channel URL support' do
+  include_context 'channel serial framing'
+
+  it 'exports primary first and enabled secondary settings with LoRa in a channel URL' do
+    primary = Meshtastic::Channel.new(index: 0, role: :PRIMARY, settings: { name: 'main', psk: "\x01".b })
+    secondary = Meshtastic::Channel.new(index: 2, role: :SECONDARY, settings: { name: 'other' })
+    disabled = Meshtastic::Channel.new(index: 3, settings: { name: 'hidden' })
+    lora = Meshtastic::Config::LoRaConfig.new(region: :US, use_preset: true)
+    url = described_class.export_url(channels: [secondary, disabled, primary], lora_config: lora)
+    expect(url).to start_with('https://meshtastic.org/e/#')
+    require 'base64'
+    channel_set = Meshtastic::ChannelSet.decode(Base64.urlsafe_decode64(url.split('#').last))
+    expect(channel_set.settings.map(&:name)).to eq(%w[main other])
+    expect(channel_set.lora_config).to eq(lora)
+    expect(url).not_to end_with('=')
+  end
+
+  it 'imports official e and legacy d URLs as offline ChannelSet protobufs' do
+    expected = Meshtastic::ChannelSet.new(settings: [{ name: 'test', psk: "\x01".b }], lora_config: { region: :US })
+    encoded = Base64.urlsafe_encode64(expected.to_proto, padding: false)
+    %w[e d].each do |path|
+      expect(described_class.import_url(url: "https://meshtastic.org/#{path}/##{encoded}")).to eq(expected)
+    end
+  end
+
+  it 'rejects invalid URL envelopes and empty or oversized channel sets without leaking the URL' do
+    empty = Base64.urlsafe_encode64(Meshtastic::ChannelSet.new.to_proto, padding: false)
+    oversized = Base64.urlsafe_encode64(Meshtastic::ChannelSet.new(settings: Array.new(9) { { name: 'test' } }).to_proto, padding: false)
+    valid = Base64.urlsafe_encode64(Meshtastic::ChannelSet.new(settings: [{ name: 'test' }]).to_proto, padding: false)
+    urls = ["https://example.org/e/##{valid}", "https://meshtastic.org/v/##{valid}",
+            'https://meshtastic.org/e/', 'https://meshtastic.org/e/#not!base64',
+            'https://meshtastic.org/e/#_w', "https://meshtastic.org/e/##{empty}",
+            "https://meshtastic.org/e/##{oversized}", "https://user:secret@meshtastic.org/e/##{valid}"]
+    urls.each do |url|
+      expect { described_class.import_url(url: url) }.to raise_error(ArgumentError, 'invalid channel URL')
+    end
+  end
+
+  it 'exports only primary when include_all is false and requires exactly one primary' do
+    primary = Meshtastic::Channel.new(role: :PRIMARY, settings: { name: 'main' })
+    secondary = Meshtastic::Channel.new(index: 1, role: :SECONDARY, settings: { name: 'other' })
+    url = described_class.export_url(channels: [primary, secondary], include_all: false)
+    expect(described_class.import_url(url: url).settings.map(&:name)).to eq(['main'])
+    [[], [secondary], [primary, primary]].each do |channels|
+      expect { described_class.export_url(channels: channels) }.to raise_error(ArgumentError)
+    end
+  end
+
+  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(serial_obj[:written]).to be_empty
+    end
+    expect { described_class.build_settings(psk: 'bad') }.to raise_error(ArgumentError)
+    expect { described_class.build_settings(name: 'a' * 12) }.to raise_error(ArgumentError)
+    [0, 1, 16, 32].each do |length|
+      expect(described_class.build_settings(psk: 'x' * length).psk.bytesize).to eq(length)
+    end
+  end
+
+  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)
+    written = decode_admin(serial_obj).set_channel
+    expect(written.index).to eq(2)
+    expect(written.settings.name).to eq('after')
+    expect(written.settings.uplink_enabled).to be false
+    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.build(settings: { psk: 'bad' }) }.to raise_error(ArgumentError)
+  end
+
+  it 'applies an imported URL as indexed channel writes followed by its LoRa section' 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')
+    frames = serial_obj[:written].dup
+    messages = []
+    until frames.empty?
+      length = (frames.getbyte(2) << 8) + frames.getbyte(3)
+      packet = Meshtastic::ToRadio.decode(frames.byteslice(4, length)).packet
+      messages << Meshtastic::AdminMessage.decode(packet.decoded.payload)
+      frames = frames.byteslice((length + 4)..)
+    end
+    expect(results.length).to eq(3)
+    expect(messages.map(&:payload_variant)).to eq(%i[set_channel set_channel set_config])
+    expect(messages.first.set_channel.index).to eq(0)
+    expect(messages.first.set_channel.role).to eq(:PRIMARY)
+    expect(messages[1].set_channel.index).to eq(1)
+    expect(messages[1].set_channel.role).to eq(:SECONDARY)
+    expect(messages.last.set_config.lora.region).to eq(:US)
+    expect(messages.map(&:session_passkey)).to all(eq('test-key'))
+  end
+
+  it 'preflights all URL settings and refuses add-only links before writing' 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(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(serial_obj[:written]).to be_empty
+  end
+
+  it 'rejects unsupported channel roles before writing' do
+    expect { described_class.build(role: 99) }.to raise_error(ArgumentError)
+  end
+
+  it 'rejects oversized or invalid enabled channel sets on export' do
+    primary = Meshtastic::Channel.new(role: :PRIMARY, settings: { name: 'main' })
+    secondary = Meshtastic::Channel.new(role: :SECONDARY, settings: { name: 'other' })
+    expect { described_class.export_url(channels: [primary] + Array.new(8, secondary)) }.to raise_error(ArgumentError)
+    primary.settings.psk = 'bad'
+    expect { described_class.export_url(channels: [primary]) }.to raise_error(ArgumentError)
+  end
+
   it 'prints usage without raising' do
     expect { described_class.help }.to output(/USAGE/).to_stdout
   end

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

@@ -42,6 +42,72 @@ describe Meshtastic::Admin::Config do
     expect(decode_admin(serial_obj).get_config_request).to eq(:LORA_CONFIG)
   end
 
+  Meshtastic::Config.descriptor.each do |field|
+    next if %w[sessionkey device_ui].include?(field.name)
+
+    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)
+      config = decode_admin(serial_obj).set_config
+      expect(config.payload_variant).to eq(field.name.to_sym)
+      expect(config[field.name]).to eq(section)
+    end
+  end
+
+  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(serial_obj[:written]).to be_empty
+  end
+
+  Meshtastic::Config.descriptor.each do |field|
+    next if %w[sessionkey device_ui].include?(field.name)
+
+    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 => {})
+      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(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)
+    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: {})
+    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(serial_obj[:written]).to be_empty
+  end
+
+  {
+    device: :DEVICE_CONFIG, position: :POSITION_CONFIG, power: :POWER_CONFIG,
+    network: :NETWORK_CONFIG, display: :DISPLAY_CONFIG, lora: :LORA_CONFIG,
+    bluetooth: :BLUETOOTH_CONFIG, security: :SECURITY_CONFIG, sessionkey: :SESSIONKEY_CONFIG
+  }.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)
+      message = decode_admin(serial_obj)
+      expect(message.payload_variant).to eq(:get_config_request)
+      expect(message.get_config_request).to eq(config_type)
+    end
+  end
+
   it 'prints usage without raising' do
     expect { described_class.help }.to output(/USAGE/).to_stdout
   end

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

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+class UnifiedGattFixture
+  attr_reader :writes, :closed, :subscriptions
+
+  def initialize(final: "OK\n")
+    @writes = []
+    @notifications = []
+    @subscriptions = []
+    @command = +''
+    @binary = false
+    @received = 0
+    @final = final
+  end
+
+  def subscribe(uuid:)
+    @subscriptions << uuid
+  end
+
+  def write(uuid:, bytes:, response:)
+    raise 'must subscribe before writing' if @subscriptions.empty?
+    raise 'unconsumed ACK' unless @notifications.empty?
+
+    @writes << { uuid: uuid, bytes: bytes, response: response }
+    if @binary
+      @received += bytes.bytesize
+      @notifications << (@received == @size ? @final : "ACK\n")
+    else
+      @command << bytes
+      if @command.end_with?("\n")
+        if @command == "VERSION\n"
+          @notifications << "OK 1 2.7.0 3 v1.0\n"
+        else
+          @size = @command.split[1].to_i
+          @notifications << "ERASING\nOK\n"
+          @binary = true
+        end
+        @command.clear
+      end
+    end
+    bytes.bytesize
+  end
+
+  def notification(timeout:)
+    raise ArgumentError, 'timeout must be positive' unless timeout.positive?
+    raise Timeout::Error, 'silent GATT' if @notifications.empty?
+
+    { uuid: Meshtastic::Admin::Firmware::BLE::TX_UUID, bytes: @notifications.shift }
+  end
+
+  def close
+    @closed = true
+  end
+end
+
+describe 'Firmware selected-device BlueZ GATT' do
+  it 'scopes writes and notification matches to the selected device without requiring bootloader pairing' do
+    klass = Meshtastic::Admin::Firmware::BLE.const_get(:BlueZ)
+    service = Meshtastic::Admin::Firmware::BLE::SERVICE_UUID
+    uuid = Meshtastic::Admin::Firmware::BLE::TX_UUID
+    device = '/org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF'
+    objects = {
+      '/org/bluez/hci0' => { 'org.bluez.Adapter1' => { 'Powered' => true } },
+      '/other/s' => { 'org.bluez.GattService1' => { 'Device' => '/other', 'UUID' => service } },
+      '/other/c' => { 'org.bluez.GattCharacteristic1' => { 'Service' => '/other/s', 'UUID' => uuid } },
+      device => { 'org.bluez.Device1' => { 'Address' => 'AA:BB:CC:DD:EE:FF', 'Adapter' => '/org/bluez/hci0', 'ServicesResolved' => true, 'Connected' => true, 'Paired' => false } },
+      "#{device}/s" => { 'org.bluez.GattService1' => { 'Device' => device, 'UUID' => service } },
+      "#{device}/s/c" => { 'org.bluez.GattCharacteristic1' => { 'Service' => "#{device}/s", 'UUID' => uuid } }
+    }
+    socket, peer = UNIXSocket.pair
+    queue = DBus::MessageQueue.allocate
+    queue.instance_variable_set(:@socket, socket)
+    queue.instance_variable_set(:@buffer, +''.b)
+    queue.instance_variable_set(:@read_buffer, +''.b)
+    queue.instance_variable_set(:@mutex, Mutex.new)
+    bus = double('private bus', message_queue: queue)
+    calls = []
+    signal_handler = nil
+    allow(bus).to receive(:process) { |message| signal_handler.call(message) }
+    allow(DBus::ASystemBus).to receive(:allocate).and_return(bus)
+    allow(bus).to receive(:initialize)
+    allow(bus).to receive(:add_match) do |rule, &handler|
+      expect(rule.to_s).to include("path='#{device}/s/c'")
+      signal_handler = handler
+    end
+    allow(bus).to receive(:send_sync_or_async) do |message|
+      calls << message
+      case message.member
+      when 'GetManagedObjects' then [objects]
+      when 'GetAll' then [objects.fetch(message.path).fetch(message.params.first.last)]
+      when 'WriteValue'
+        signal = DBus::Message.new(DBus::Message::SIGNAL)
+        signal.path = "#{device}/s/c"
+        signal.interface = 'org.freedesktop.DBus.Properties'
+        signal.member = 'PropertiesChanged'
+        signal.add_param('s', 'org.bluez.GattCharacteristic1')
+        signal.add_param('a{sv}', { 'Value' => ['ay', [79, 75, 10]] })
+        signal.add_param('as', [])
+        peer.write(signal.marshall)
+        []
+      else []
+      end
+    end
+    backend = klass.new(address: 'AA:BB:CC:DD:EE:FF', service_uuid: service, timeout: 0.1).connect
+    backend.subscribe(uuid: uuid)
+    backend.write(uuid: uuid, bytes: 'abc', response: true)
+    expect(backend.notification(timeout: 0.1)).to eq(uuid: uuid, bytes: "OK\n")
+    expect(calls.select { |m| m.member == 'WriteValue' }.map(&:path)).to eq(["#{device}/s/c"])
+    expect(calls.map(&:member)).not_to include('Pair', 'StartDiscovery')
+    objects.delete("#{device}/s/c")
+    expect { backend.write(uuid: uuid, bytes: 'must not reach decoy', response: false) }.to raise_error(IOError, /selected device/)
+    expect { backend.notification(timeout: 0.01) }.to raise_error(IOError, /notification timed out/)
+    backend.close
+    expect(socket).to be_closed
+  ensure
+    socket&.close unless socket&.closed?
+    peer&.close
+  end
+end
+
+describe 'Unified BLE firmware installation' do
+  it 'rejects another protocol in the direct BLE helper before touching GATT' do
+    backend = UnifiedGattFixture.new
+    expect do
+      Meshtastic::Admin::Firmware::BLE.install(protocol: :legacy_ble, backend: backend, bytes: 'abc')
+    end.to raise_error(ArgumentError, /protocol/)
+    expect(backend.writes).to be_empty
+  end
+
+  it 'uses the selected-address BlueZ backend by default' do
+    backend = UnifiedGattFixture.new
+    expect(Meshtastic::Admin::Firmware::BLE::BlueZ).to receive(:new)
+      .with(address: 'AA:BB:CC:DD:EE:FF', adapter: 'hci0', timeout: 120, service_uuid: Meshtastic::Admin::Firmware::BLE::SERVICE_UUID)
+      .and_return(backend)
+    expect(backend).to receive(:connect).and_return(backend)
+    expect(Meshtastic::Admin::Firmware.install(protocol: :unified_ble, address: 'AA:BB:CC:DD:EE:FF', bytes: 'abc')[:status]).to eq(:verified)
+  end
+
+  it 'validates timeout and unknown options before any BLE command' do
+    [{ timeout: 0 }, { timeout: Float::INFINITY }, { to: '!aabbccdd' }, { chunk_size: 512 }].each do |invalid|
+      backend = UnifiedGattFixture.new
+      expect do
+        Meshtastic::Admin::Firmware.install({ protocol: :unified_ble, backend: backend, bytes: 'abc' }.merge(invalid))
+      end.to raise_error(ArgumentError)
+      expect(backend.writes).to be_empty
+    end
+  end
+
+  it 'never treats ACK, ERR or disconnect as final completion or retries image bytes' do
+    ["ACK\n", "ERR Hash Mismatch\n", nil].each do |final|
+      backend = UnifiedGattFixture.new(final: final)
+      expect do
+        Meshtastic::Admin::Firmware.install(protocol: :unified_ble, backend: backend, bytes: 'abc')
+      end.to raise_error(IOError)
+      expect(backend.writes.count { |w| w[:bytes] == 'abc' }).to eq(1)
+      expect(backend.closed).to be true
+    end
+  end
+
+  it 'fragments commands to ATT size and waits for ACK per data chunk and final OK' do
+    backend = UnifiedGattFixture.new
+    result = Meshtastic::Admin::Firmware.install(protocol: :unified_ble, backend: backend, bytes: 'x' * 45)
+    expect(result).to include(status: :verified, bytes: 45, sha256: Digest::SHA256.hexdigest('x' * 45))
+    expect(backend.writes.map { |write| write[:bytes].bytesize }.max).to be <= 20
+    expect(backend.writes.map { |write| write[:bytes] }.join).to eq("VERSION\nOTA 45 #{Digest::SHA256.hexdigest('x' * 45)}\n#{'x' * 45}")
+    expect(backend.closed).to be true
+  end
+end

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

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'zlib'
+require 'meshtastic/admin/firmware/nordic_dfu' if File.exist?(File.expand_path('../../../../../lib/meshtastic/admin/firmware/nordic_dfu.rb', __dir__))
+
+# A stateful byte-level peer, not canned success responses. It enforces the
+# SDK11 command order, image sizing, PRN cadence, and independent image CRC.
+class NordicDFUPeer
+  CONTROL = '00001531-1212-efde-1523-785feabcd123'
+  PACKET = '00001532-1212-efde-1523-785feabcd123'
+  attr_reader :image, :activated, :closed, :writes
+  attr_accessor :fault
+
+  def initialize
+    @state = :idle
+    @events = []
+    @image = ''.b
+    @init = ''.b
+    @writes = []
+    @count = 0
+  end
+
+  def subscribe(uuid:)
+    raise 'wrong subscription' unless uuid == CONTROL
+
+    @subscribed = true
+  end
+
+  def write(uuid:, bytes:, response:)
+    raise 'not subscribed' unless @subscribed
+
+    @writes << [uuid, bytes, response]
+    if uuid == CONTROL
+      raise 'control requires write response' unless response
+
+      control(bytes)
+    else
+      raise 'invalid packet write' unless uuid == PACKET && !response && bytes.bytesize <= 20
+
+      packet(bytes)
+    end
+  end
+
+  def control(bytes)
+    case [@state, bytes.bytes]
+    when [:idle, [1, 4]] then @state = :size
+    when [:started, [2, 0]] then @state = :init
+    when [:init, [2, 1]]
+      raise 'bad init' unless @init.bytesize == 14 && @init.unpack1('v') == 0x52
+
+      reply(2)
+      @state = :initialized
+    when [:ready, [3]] then @state = :image
+    when [:received, [4]]
+      @image.setbyte(0, @image.getbyte(0) ^ 1) if @fault == :flash_corruption
+      reply(4, crc(@image) == @init.byteslice(-2, 2).unpack1('v') ? 1 : 5)
+      @state = :validated
+    when [:validated, [5]] then @activated = true
+    else
+      raise "unexpected command #{@state}: #{bytes.bytes}" unless @state == :initialized && bytes.getbyte(0) == 8 && bytes.bytesize == 3
+
+      @interval = bytes.byteslice(1, 2).unpack1('v')
+      raise 'receipts disabled' unless @interval.positive?
+
+      @state = :ready
+    end
+  end
+
+  def packet(bytes)
+    case @state
+    when :size
+      sd, bl, @size = bytes.unpack('V3')
+      raise 'bad image sizes' unless bytes.bytesize == 12 && sd.zero? && bl.zero? && @size.positive?
+
+      @state = :started
+      reply(1)
+    when :init then @init << bytes
+    when :image
+      raise 'unaligned image packet' unless (bytes.bytesize % 4).zero?
+
+      @image << bytes
+      raise 'image overflow' if @image.bytesize > @size
+
+      @count += 1
+      if @image.bytesize == @size
+        @state = :received
+        reply(3)
+      elsif (@count % @interval).zero?
+        receipt = @image.bytesize + (@fault == :receipt ? 4 : 0)
+        @events << [17, receipt].pack('CV')
+      end
+    else raise "packet in #{@state}"
+    end
+  end
+
+  def reply(opcode, status = 1)
+    status = 6 if @fault == :reject && opcode == 2
+    opcode = 4 if @fault == :wrong_opcode && opcode == 1
+    @events << [16, opcode, status].pack('C*')
+  end
+
+  def notification(timeout:)
+    raise 'unbounded wait' unless timeout.positive?
+    return nil if @fault == :timeout
+
+    bytes = @events.shift
+    raise 'client waited when peer owes no response' unless bytes
+
+    { uuid: CONTROL, bytes: bytes }
+  end
+
+  def close
+    @closed = true
+  end
+
+  def crc(bytes)
+    crc = 0xffff
+    bytes.each_byte do |byte|
+      crc ^= byte << 8
+      8.times { crc = ((crc << 1) ^ (crc.anybits?(0x8000) ? 0x1021 : 0)) & 0xffff }
+    end
+    crc
+  end
+end
+
+RSpec.describe 'Meshtastic::Admin::Firmware::NordicDFU' do
+  let(:installer) { Meshtastic::Admin::Firmware::NordicDFU }
+  let(:peer) { NordicDFUPeer.new }
+  let(:image) { (0...244).to_a.pack('C*') }
+  let(:init) { [0x52, 0xffff, 1, 1, 0xfffe, peer.crc(image)].pack('vvVvvv') }
+  let(:manifest) { { manifest: { application: { bin_file: 'app.bin', dat_file: 'app.dat' } } } }
+  let(:entries) { { 'manifest.json' => JSON.generate(manifest), 'app.bin' => image, 'app.dat' => init } }
+
+  def zip(entries, compression: 0)
+    local = ''.b
+    central = ''.b
+    entries.each do |name, bytes|
+      raw = if compression == 8
+              deflater = Zlib::Deflate.new(Zlib::DEFAULT_COMPRESSION, -Zlib::MAX_WBITS)
+              begin
+                deflater.deflate(bytes, Zlib::FINISH)
+              ensure
+                deflater.close
+              end
+            else
+              bytes
+            end
+      crc = Zlib.crc32(bytes)
+      central << [0x02014b50, 20, 20, 0, compression, 0, 0, crc, raw.bytesize, bytes.bytesize,
+                  name.bytesize, 0, 0, 0, 0, 0, local.bytesize].pack('VvvvvvvVVVvvvvvVV') << name
+      local << [0x04034b50, 20, 0, compression, 0, 0, crc, raw.bytesize, bytes.bytesize,
+                name.bytesize, 0].pack('VvvvvvVVVvv') << name << raw
+    end
+    local + central + [0x06054b50, 0, 0, entries.length, entries.length, central.bytesize, local.bytesize, 0].pack('VvvvvVVv')
+  end
+
+  {
+    'image CRC mismatch' => ->(entries) { entries.merge('app.bin' => 'x' * 244) },
+    'unaligned image' => ->(entries) { entries.merge('app.bin' => 'x') },
+    'empty image' => ->(entries) { entries.merge('app.bin' => '') },
+    'signed extension' => ->(entries) { entries.merge('app.dat' => entries.fetch('app.dat').byteslice(0, 12) + [2, 244].pack('V2') + ('x' * 96)) },
+    'secure protobuf init' => ->(entries) { entries.merge('app.dat' => "\x12\x08\x0a\x06secure".b) },
+    'bootloader update' => ->(entries) { entries.merge('manifest.json' => JSON.generate(manifest: { bootloader: { bin_file: 'app.bin', dat_file: 'app.dat' } })) },
+    'traversal entry' => ->(entries) { entries.merge('../outside' => 'unsafe') },
+    'missing init' => ->(entries) { entries.except('app.dat') }
+  }.each do |description, mutate|
+    it "rejects #{description} before any bootloader writes" do
+      expect { installer.install(package_bytes: zip(mutate.call(entries)), gatt: peer) }.to raise_error(ArgumentError)
+      expect(peer.writes).to be_empty
+    end
+  end
+
+  it 'rejects truncated ZIP data without writing to the bootloader' do
+    expect { installer.install(package_bytes: zip(entries).byteslice(0, 100), gatt: peer) }.to raise_error(ArgumentError)
+    expect(peer.writes).to be_empty
+  end
+
+  it 'reads a package file without requiring any external unpacker' do
+    require 'tempfile'
+    Tempfile.create(['nordic', '.zip']) do |file|
+      file.binmode
+      file.write(zip(entries))
+      file.flush
+      installer.install(package: file.path, gatt: peer)
+      expect(peer.activated).to be(true)
+    end
+  end
+
+  it 'rejects ambiguous package sources before touching GATT' do
+    expect { installer.install(package_bytes: zip(entries), package: '/unused.zip', gatt: peer) }.to raise_error(ArgumentError, /exactly one/)
+    expect(peer.writes).to be_empty
+  end
+
+  it 'rejects unknown options rather than ignoring secure or retry requests' do
+    expect { installer.install(package_bytes: zip(entries), gatt: peer, secure: true) }.to raise_error(ArgumentError, /Unsupported.*secure/)
+    expect(peer.writes).to be_empty
+  end
+
+  it 'rejects a JSON scalar manifest with an operator-usable error' do
+    malformed = entries.merge('manifest.json' => JSON.generate('not a manifest'))
+    expect { installer.install(package_bytes: zip(malformed), gatt: peer) }.to raise_error(ArgumentError, /manifest/)
+    expect(peer.writes).to be_empty
+  end
+
+  it 'rejects malformed manifest application types clearly before I/O' do
+    malformed = entries.merge('manifest.json' => JSON.generate(manifest: { application: 'oops' }))
+    expect { installer.install(package_bytes: zip(malformed), gatt: peer) }.to raise_error(ArgumentError, /application/)
+    expect(peer.writes).to be_empty
+  end
+
+  %i[receipt reject wrong_opcode timeout flash_corruption].each do |fault|
+    it "fails closed on #{fault} without replaying unsequenced packets" do
+      peer.fault = fault
+      expect { installer.install(package_bytes: zip(entries), gatt: peer) }.to raise_error(fault == :timeout ? Timeout::Error : IOError)
+      expect(peer.activated).not_to be(true)
+      expect(peer.closed).to be(true)
+      expect(peer.writes.count { |_uuid, bytes, _response| bytes == [1, 4].pack('C*') }).to eq(1)
+    end
+  end
+
+  it 'connects the shared production BlueZ backend to the legacy service by default' do
+    require 'meshtastic/admin/firmware/ble'
+    expect(Meshtastic::Admin::Firmware::BLE::BlueZ).to receive(:new).with(
+      address: 'AA:BB:CC:DD:EE:FF', adapter: 'hci0', timeout: 30,
+      service_uuid: '00001530-1212-efde-1523-785feabcd123'
+    ).and_return(peer)
+    expect(peer).to receive(:connect).and_return(peer)
+    installer.install(package_bytes: zip(entries), address: 'AA:BB:CC:DD:EE:FF')
+    expect(peer.activated).to be(true)
+  end
+
+  it 'reads a deflated ZIP generated by normal DFU package tools' do
+    installer.install(package_bytes: zip(entries, compression: 8), gatt: peer)
+    expect(peer.image).to eq(image)
+    expect(peer.activated).to be(true)
+  end
+
+  it 'installs a legacy application ZIP through real command and receipt states' do
+    expect(defined?(Meshtastic::Admin::Firmware::NordicDFU)).to eq('constant')
+    result = installer.install(package_bytes: zip(entries), gatt: peer)
+    expect(peer.image).to eq(image)
+    expect(peer.activated).to be(true)
+    expect(peer.closed).to be(true)
+    expect(result).to include(status: :verified, bytes: image.bytesize, protocol: :nordic_dfu, reboot_verified: false)
+  end
+end