meshtastic 0.0.179 → 0.0.181

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

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

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'pty'
+require 'digest'
+require 'timeout'
+require 'tempfile'
+require 'meshtastic/admin/firmware/serial_bootloader'
+
+RSpec.describe Meshtastic::Admin::Firmware::SerialBootloader do # rubocop:disable Metrics/BlockLength
+  def image(chip_id = 0)
+    header = [0xe9, 1, 2, 0x20, 0x40000000].pack('C4V')
+    header << [0xee, 0, 0, 0, chip_id, 0, 0, 0].pack('C4vCvv') << "\0\0\0\0\1".b
+    data = ("\xc0\xdb".b * 600)
+    body = header + [0x3ffb0000, data.bytesize].pack('V2') + data
+    body << "\0" until body.bytesize % 16 == 15
+    body << [data.bytes.reduce(0xef, :^)].pack('C')
+    body + Digest::SHA256.digest(body)
+  end
+
+  def frame(packet)
+    "\xc0".b + packet.bytes.map { |b|
+      if b == 0xc0
+        "\xdb\xdc".b
+      else
+        b == 0xdb ? "\xdb\xdd".b : b.chr
+      end
+    }.join.b + "\xc0".b
+  end
+
+  def receive_packet(io)
+    bytes = +''.b
+    started = false
+    loop do
+      b = io.readpartial(1).getbyte(0)
+      if b == 0xc0
+        return bytes.gsub("\xdb\xdc".b, "\xc0".b).gsub("\xdb\xdd".b, "\xdb".b) if started && !bytes.empty?
+
+        started = true
+      elsif started
+        bytes << b
+      end
+    end
+  end
+
+  def emulate(bytes:, chip_id: 0, failure: nil)
+    PTY.open do |master, slave|
+      commands = []
+      flash = +''.b
+      worker = Thread.new do
+        Thread.current.report_on_exception = false
+        loop do
+          packet = receive_packet(master)
+          direction, op, length, checksum = packet.unpack('CCvV')
+          payload = packet.byteslice(8..)
+          raise 'bad request framing' unless direction.zero? && length == payload.bytesize
+
+          commands << op
+          value = 0
+          response = +''.b
+          case op
+          when 8
+            raise 'bad sync' unless payload == "\x07\x07\x12\x20".b + ("\x55" * 32)
+
+            value = failure == :stub ? 0 : 0x20100707
+            next if failure == :sync_once && commands.count(8) == 1
+          when 10
+            address = payload.unpack1('V')
+            value = address == 0x40001000 ? 0x00f01d83 : 0
+            value = 0 if failure == :wrong_chip
+            value = 0x30 if failure == :secure && address == 0x3ff5a018
+          when 0x14
+            response = ([failure == :secure ? 1 : 0] + ([0] * 8) + [failure == :wrong_chip ? 99 : chip_id, 0]).pack('VC8V2')
+          when 0x0d
+            raise 'bad attach' unless payload == [0, 0].pack('V2')
+          when 0x0b
+            raise 'bad geometry' unless payload == [0, 4 * 1024 * 1024, 65_536, 4096, 256, 65_535].pack('V6')
+          when 2
+            params = payload.unpack('V*')
+            expected = [bytes.bytesize, (bytes.bytesize + 1023) / 1024, 1024, 0x10000]
+            expected << 0 unless chip_id.zero?
+            raise "bad begin #{params}" unless params == expected
+          when 3
+            size, sequence, reserved1, reserved2 = payload.unpack('V4')
+            block = payload.byteslice(16..)
+            raise 'bad block' unless size == 1024 && block.bytesize == size && sequence * 1024 == flash.bytesize && reserved1.zero? && reserved2.zero?
+            raise 'bad checksum' unless checksum == block.bytes.reduce(0xef, :^)
+
+            flash << block
+          when 0x13
+            raise 'bad verify range' unless payload == [0x10000, bytes.bytesize, 0, 0].pack('V4')
+            raise 'different flashed bytes' unless flash.byteslice(0, bytes.bytesize) == bytes
+
+            response = failure == :digest ? '0' * 32 : Digest::MD5.hexdigest(flash.byteslice(0, bytes.bytesize))
+          when 4
+            raise 'bad end' unless payload == [0].pack('V')
+          else
+            raise "unexpected opcode #{op}"
+          end
+          status = failure == op ? [1, 5, 0, 0].pack('C4') : "\0" * 4
+          response += status
+          reply = frame([1, op, response.bytesize, value].pack('CCvV') + response)
+          if op == 3
+            next if failure == :silent
+
+            reply = "\xc0\xdb\x01\xc0".b if failure == :bad_escape
+            reply = frame([1, 99, 4, 0].pack('CCvV') + ("\0" * 4)) if failure == :wrong_opcode
+            reply = frame([1, op, 99, 0].pack('CCvV') + ("\0" * 4)) if failure == :bad_length
+            reply = frame('short') if failure == :short
+          end
+          (op == 8 ? 8 : 1).times { master.write(reply) }
+          break if op == 4 || failure == op || (op == 0x13 && failure == :digest)
+        end
+      rescue EOFError, Errno::EIO
+        nil
+      end
+      begin
+        yield slave.path, commands
+      ensure
+        worker.kill
+        worker.join
+        worker.value
+      end
+    end
+  end
+
+  let(:installer) { Meshtastic::Admin::Firmware::SerialBootloader }
+  let(:bytes) { image }
+
+  it 'rejects invalid chip, image, flash geometry and options before opening any port' do
+    base = { port: '/dev/never-open', chip: :esp32, bytes: bytes, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none }
+    corrupt = bytes.dup
+    corrupt.setbyte(35, corrupt.getbyte(35) ^ 1)
+    corrupt_hash = bytes.dup
+    corrupt_hash.setbyte(-1, corrupt_hash.getbyte(-1) ^ 1)
+    invalid = [
+      { chip: :esp8266 }, { bytes: 'bad' }, { bytes: image(9) }, { bytes: corrupt },
+      { bytes: corrupt_hash },
+      { bytes: "#{bytes}junk" }, { bytes: bytes.byteslice(0, 35) },
+      { offset: -1 }, { offset: 0x10001 }, { offset: 0 }, { offset: 4 * 1024 * 1024 },
+      { flash_size: 123 }, { timeout: 0 }, { timeout: Float::INFINITY },
+      { reset: :magic }, { protocol: :nordic_serial }, { firmware: '/tmp/ambiguous' },
+      { surprise: true }, { port: '' }
+    ]
+    expect(UART).not_to receive(:open)
+    invalid.each do |change|
+      expect { installer.install(base.merge(change)) }.to raise_error(ArgumentError), change.inspect
+    end
+  end
+
+  { esp32s3: 9, esp32c3: 5 }.each do |chip, id|
+    it "identifies #{chip} with GET_SECURITY_INFO and uses extended FLASH_BEGIN" do
+      firmware = image(id)
+      emulate(bytes: firmware, chip_id: id) do |port, commands|
+        result = installer.install(port: port, chip: chip, bytes: firmware, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none)
+        expect(result[:chip]).to eq(chip)
+        expect(commands).to eq([8, 20, 13, 11, 2, 3, 3, 19, 4])
+      end
+    end
+  end
+
+  it 'retries only synchronization when the ROM misses its first request' do
+    emulate(bytes: bytes, failure: :sync_once) do |port, commands|
+      result = installer.install(port: port, chip: :esp32, bytes: bytes, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none, timeout: 0.1)
+      expect(result[:status]).to eq(:verified)
+      expect(commands.count(8)).to eq(2)
+      expect(commands.count(2)).to eq(1)
+    end
+  end
+
+  it 'rejects an already running flasher stub before any flash command' do
+    emulate(bytes: bytes, failure: :stub) do |port, commands|
+      expect { installer.install(port: port, chip: :esp32, bytes: bytes, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none) }.to raise_error(IOError, /stub/)
+      expect(commands).to eq([8])
+    end
+  end
+
+  [3, :digest, :bad_escape, :wrong_opcode, :bad_length, :short, :silent].each do |failure|
+    it "fails closed on #{failure} without reboot or replaying FLASH_DATA and closes its UART" do
+      opened = nil
+      allow(UART).to(receive(:open).and_wrap_original { |original, *args| opened = original.call(*args) })
+      emulate(bytes: bytes, failure: failure) do |port, commands|
+        error = failure == :silent ? Timeout::Error : IOError
+        expect { installer.install(port: port, chip: :esp32, bytes: bytes, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none, timeout: 0.1) }.to raise_error(error)
+        expect(commands).not_to include(4)
+        expect(commands.count(3)).to eq(failure == :digest ? 2 : 1)
+      end
+      expect(opened).to be_closed
+    end
+  end
+
+  { esp32: 0, esp32s3: 9, esp32c3: 5 }.each do |chip, id|
+    %i[secure wrong_chip].each do |failure|
+      it "rejects #{failure} on #{chip} before erasing any flash" do
+        firmware = image(id)
+        emulate(bytes: firmware, chip_id: id, failure: failure) do |port, commands|
+          expect { installer.install(port: port, chip: chip, bytes: firmware, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none) }.to raise_error(IOError)
+          expect(commands).not_to include(2, 3)
+        end
+      end
+    end
+  end
+
+  it 'reads an image file and accepts the ESP format without an appended digest' do
+    firmware = bytes.byteslice(0, bytes.bytesize - 32)
+    firmware.setbyte(23, 0)
+    Tempfile.create(['esp-app', '.bin']) do |file|
+      file.binmode
+      file.write(firmware)
+      file.flush
+      emulate(bytes: firmware) do |port, _commands|
+        result = installer.install(port: port, chip: :esp32, firmware: file.path, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none)
+        expect(result[:md5]).to eq(Digest::MD5.hexdigest(firmware))
+      end
+    end
+  end
+
+  it 'clears inherited hardware flow control and hangup reset before writing ROM bytes' do
+    allow(UART).to receive(:open).and_wrap_original do |original, *args|
+      serial = original.call(*args)
+      attrs = Termios.tcgetattr(serial)
+      attrs.cflag |= Termios::CRTSCTS | Termios::HUPCL
+      Termios.tcsetattr(serial, Termios::TCSANOW, attrs)
+      allow(serial).to receive(:write).and_wrap_original do |write, *data|
+        expect(Termios.tcgetattr(serial).cflag & (Termios::CRTSCTS | Termios::HUPCL)).to eq(0)
+        write.call(*data)
+      end
+      serial
+    end
+    emulate(bytes: bytes) do |port, _commands|
+      installer.install(port: port, chip: :esp32, bytes: bytes, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none)
+    end
+  end
+
+  it 'uses classic DTR/RTS boot reset and a final EN pulse on a dedicated UART' do
+    controls = []
+    opened = nil
+    allow(UART).to receive(:open).and_wrap_original do |original, *args|
+      opened = original.call(*args)
+      allow(opened).to receive(:ioctl) { |op, bits| controls << [op, bits.unpack1('i')] }
+      opened
+    end
+    allow(installer).to receive(:sleep)
+    emulate(bytes: bytes) do |port, _commands|
+      installer.install(port: port, chip: :esp32, bytes: bytes, offset: 0x10000, flash_size: 4 * 1024 * 1024)
+    end
+    expect(controls).to eq([
+                             [Termios::TIOCMBIC, Termios::TIOCM_DTR], [Termios::TIOCMBIS, Termios::TIOCM_RTS],
+                             [Termios::TIOCMBIS, Termios::TIOCM_DTR], [Termios::TIOCMBIC, Termios::TIOCM_RTS],
+                             [Termios::TIOCMBIC, Termios::TIOCM_DTR],
+                             [Termios::TIOCMBIS, Termios::TIOCM_RTS], [Termios::TIOCMBIC, Termios::TIOCM_RTS]
+                           ])
+    expect(opened).to be_closed
+  end
+
+  it 'opens a real UART PTY, syncs, flashes checksummed blocks and verifies the device MD5 before reboot' do
+    emulate(bytes: bytes) do |port, commands|
+      result = installer.install(port: port, chip: :esp32, bytes: bytes, offset: 0x10000, flash_size: 4 * 1024 * 1024, reset: :none)
+      expect(result).to include(status: :verified, chip: :esp32, bytes: bytes.bytesize, md5: Digest::MD5.hexdigest(bytes), reboot_requested: true, boot_verified: false)
+      expect(commands).to eq([8, 10, 10, 10, 13, 11, 2, 3, 3, 19, 4])
+    end
+  end
+end