meshtastic 0.0.179 → 0.0.181

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'timeout'
+require 'uart'
+
+module Meshtastic
+  module Admin
+    module Firmware
+      # Native ROM protocol only: never uploads an executable flasher stub.
+      module SerialBootloader
+        CHIP_IDS = { esp32: 0, esp32s3: 9, esp32c3: 5 }.freeze
+
+        public_class_method def self.install(opts = {})
+          bytes = validate(opts.merge({}))
+          chip = opts.fetch(:chip)
+          offset = opts.fetch(:offset)
+          port = UART.open(opts.fetch(:port), 115_200, '8N1')
+          attrs = Termios.tcgetattr(port)
+          attrs.cflag &= ~(Termios::CRTSCTS | Termios::HUPCL)
+          Termios.tcsetattr(port, Termios::TCSANOW, attrs)
+          reset_lines(io: port, bootloader: true) if opts.fetch(:reset, :classic) == :classic
+          context = { io: port, timeout: opts.fetch(:timeout, 120) }
+          synchronize(context.merge({}))
+          identify(context.merge(chip: chip))
+
+          command(context.merge(op: 13, payload: [0, 0].pack('V2')))
+          command(context.merge(op: 11, payload: [0, opts.fetch(:flash_size), 65_536, 4096, 256, 65_535].pack('V6')))
+          blocks = (bytes.bytesize + 1023) / 1024
+          params = [bytes.bytesize, blocks, 1024, offset]
+          params << 0 unless chip == :esp32
+          command(context.merge(op: 2, payload: params.pack('V*')))
+          blocks.times do |sequence|
+            block = bytes.byteslice(sequence * 1024, 1024).ljust(1024, "\xff".b)
+            payload = [1024, sequence, 0, 0].pack('V4') + block
+            command(context.merge(op: 3, payload: payload, checksum: block.bytes.reduce(0xef, :^)))
+          end
+          md5 = command(context.merge(op: 19, payload: [offset, bytes.bytesize, 0, 0].pack('V4'), response_size: 32)).fetch(:data)
+          raise IOError, 'ROM flash MD5 mismatch' unless md5.downcase == Digest::MD5.hexdigest(bytes)
+
+          command(context.merge(op: 4, payload: [0].pack('V')))
+          reset_lines(io: port, bootloader: false) if opts.fetch(:reset, :classic) == :classic
+          { status: :verified, chip: chip, bytes: bytes.bytesize, offset: offset, md5: md5.downcase, sha256: Digest::SHA256.hexdigest(bytes), reboot_requested: true, boot_verified: false }
+        ensure
+          port&.close
+        end
+
+        private_class_method def self.synchronize(opts = {})
+          attempts = 0
+          begin
+            attempts += 1
+            response = command(opts.merge(op: 8, payload: "\x07\x07\x12\x20".b + ("\x55" * 32), timeout: [opts.fetch(:timeout), 1].min))
+            raise IOError, 'Flasher stub detected; reset into ROM first' if response.fetch(:value).zero?
+          rescue Timeout::Error
+            raise if attempts >= 3
+
+            retry
+          end
+        end
+
+        private_class_method def self.identify(opts = {})
+          if opts.fetch(:chip) == :esp32
+            magic = command(opts.merge(op: 10, payload: [0x40001000].pack('V'))).fetch(:value)
+            raise IOError, 'Connected chip is not ESP32' unless magic == 0x00f01d83
+
+            crypt = command(opts.merge(op: 10, payload: [0x3ff5a000].pack('V'))).fetch(:value)
+            secure = command(opts.merge(op: 10, payload: [0x3ff5a018].pack('V'))).fetch(:value)
+            raise IOError, 'Secure boot/encrypted flash is unsupported' unless crypt.nobits?(0x7f << 20) && secure.nobits?(0x30)
+          else
+            info = command(opts.merge(op: 20, response_size: 20)).fetch(:data)
+            raise IOError, 'Connected chip ID does not match selected chip' unless info.byteslice(12, 4).unpack1('V') == CHIP_IDS.fetch(opts.fetch(:chip))
+            raise IOError, 'Secure boot/encrypted flash/secure download is unsupported' unless info.unpack1('V').nobits?(5) && info.getbyte(4).zero?
+          end
+        end
+
+        private_class_method def self.reset_lines(opts = {})
+          io = opts.fetch(:io)
+          bootloader = opts.fetch(:bootloader)
+          io.ioctl(Termios::TIOCMBIC, [Termios::TIOCM_DTR].pack('i')) if bootloader
+          io.ioctl(Termios::TIOCMBIS, [Termios::TIOCM_RTS].pack('i'))
+          sleep 0.1
+          io.ioctl(Termios::TIOCMBIS, [Termios::TIOCM_DTR].pack('i')) if bootloader
+          io.ioctl(Termios::TIOCMBIC, [Termios::TIOCM_RTS].pack('i'))
+          return unless bootloader
+
+          sleep 0.05
+          io.ioctl(Termios::TIOCMBIC, [Termios::TIOCM_DTR].pack('i'))
+        end
+
+        private_class_method def self.validate(opts = {})
+          allowed = %i[protocol port chip bytes firmware offset flash_size reset timeout]
+          raise ArgumentError, 'Unsupported serial bootloader options' unless (opts.keys - allowed).empty?
+          raise ArgumentError, 'protocol must be :esp_rom' unless opts.fetch(:protocol, :esp_rom) == :esp_rom
+          raise ArgumentError, 'chip must be :esp32, :esp32s3 or :esp32c3' unless CHIP_IDS.key?(opts[:chip])
+          raise ArgumentError, 'port must be a nonempty device path' unless opts[:port].is_a?(String) && !opts[:port].strip.empty?
+          raise ArgumentError, 'reset must be :classic or :none' unless %i[classic none].include?(opts.fetch(:reset, :classic))
+
+          timeout = opts.fetch(:timeout, 120)
+          raise ArgumentError, 'timeout must be finite and positive' unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+
+          capacity = opts[:flash_size]
+          raise ArgumentError, 'flash_size must be a power of two from 1 MiB to 16 MiB' unless capacity.is_a?(Integer) && (1_048_576..16_777_216).cover?(capacity) && capacity.nobits?(capacity - 1)
+
+          offset = opts[:offset]
+          raise ArgumentError, 'offset must be an application address >= 0x10000 aligned to 0x1000' unless offset.is_a?(Integer) && offset >= 0x10000 && (offset % 4096).zero?
+          raise ArgumentError, 'provide exactly one of bytes or firmware' unless opts.key?(:bytes) ^ opts.key?(:firmware)
+
+          bytes = opts.key?(:bytes) ? opts[:bytes] : File.binread(opts.fetch(:firmware))
+          raise ArgumentError, 'image must be nonempty binary String' unless bytes.is_a?(String) && !bytes.empty?
+          raise ArgumentError, 'image erase range exceeds flash_size' if offset + ((bytes.bytesize + 4095) / 4096 * 4096) > capacity
+
+          validate_image(bytes: bytes.b, chip_id: CHIP_IDS.fetch(opts[:chip]))
+          bytes.b
+        end
+
+        private_class_method def self.validate_image(opts = {})
+          bytes = opts.fetch(:bytes)
+          raise ArgumentError, 'expected ESP executable image header' unless bytes.bytesize >= 24 && bytes.getbyte(0) == 0xe9 && (1..16).cover?(bytes.getbyte(1))
+          raise ArgumentError, 'image chip ID does not match selected chip' unless bytes.byteslice(12, 2).unpack1('v') == opts.fetch(:chip_id)
+          raise ArgumentError, 'invalid image digest flag' unless [0, 1].include?(bytes.getbyte(23))
+
+          position = 24
+          checksum = 0xef
+          bytes.getbyte(1).times do
+            raise ArgumentError, 'truncated ESP segment header' if position + 8 > bytes.bytesize
+
+            size = bytes.byteslice(position + 4, 4).unpack1('V')
+            position += 8
+            raise ArgumentError, 'truncated or unaligned ESP segment' if size % 4 != 0 || position + size > bytes.bytesize
+
+            bytes.byteslice(position, size).each_byte { |byte| checksum ^= byte }
+            position += size
+          end
+          checksum_position = (position / 16 * 16) + 15
+          raise ArgumentError, 'ESP image checksum mismatch' unless bytes.getbyte(checksum_position) == checksum
+
+          ending = checksum_position + 1
+          if bytes.getbyte(23) == 1
+            raise ArgumentError, 'ESP image SHA-256 mismatch' unless bytes.byteslice(ending, 32) == Digest::SHA256.digest(bytes.byteslice(0, ending))
+
+            ending += 32
+          end
+          raise ArgumentError, 'trailing data: merged, signed and padded images are unsupported' unless bytes.bytesize == ending
+        end
+
+        private_class_method def self.command(opts = {})
+          io = opts.fetch(:io)
+          op = opts.fetch(:op)
+          payload = opts.fetch(:payload, ''.b)
+          packet = [0, op, payload.bytesize, opts.fetch(:checksum, 0)].pack('CCvV') + payload
+          encoded = packet.bytes.map do |byte|
+            if byte == 0xc0
+              "\xdb\xdc".b
+            else
+              byte == 0xdb ? "\xdb\xdd".b : byte.chr
+            end
+          end.join.b
+          Timeout.timeout(opts.fetch(:timeout)) do
+            io.write("\xc0".b + encoded + "\xc0".b)
+            loop do
+              reply = read_frame(io: io)
+              raise IOError, 'Truncated ROM response' if reply.bytesize < 12
+
+              direction, response_op, length, value = reply.unpack('CCvV')
+              raise IOError, 'Invalid ROM response header' unless direction == 1 && length == reply.bytesize - 8
+              next if response_op == 8 && op != 8 # ROM sends eight SYNC replies.
+              raise IOError, 'Unexpected ROM response opcode' unless response_op == op
+
+              data = reply.byteslice(8..)
+              # Error responses may omit the expected MD5/security data.
+              status = data.byteslice(-4, 4).bytes
+              raise IOError, format('ROM command 0x%<op>02x failed: status=%<status>d error=%<error>d', op: op, status: status[0], error: status[1]) unless status[0].zero?
+              raise IOError, 'Invalid ROM response length' unless data.bytesize == opts.fetch(:response_size, 0) + 4
+
+              return { value: value, data: data.byteslice(0, data.bytesize - 4) }
+            end
+          end
+        end
+
+        private_class_method def self.read_frame(opts = {})
+          io = opts.fetch(:io)
+          frame = +''.b
+          started = false
+          escaped = false
+          loop do
+            byte = io.readpartial(1).getbyte(0)
+            if byte == 0xc0
+              raise IOError, 'Truncated SLIP escape' if escaped
+              return frame if started && !frame.empty?
+
+              started = true
+            elsif started
+              if escaped
+                raise IOError, 'Invalid SLIP escape' unless [0xdc, 0xdd].include?(byte)
+
+                frame << (byte == 0xdc ? 0xc0 : 0xdb)
+                escaped = false
+              elsif byte == 0xdb
+                escaped = true
+              else
+                frame << byte
+              end
+              raise IOError, 'Oversized ROM response' if frame.bytesize > 4096
+            end
+          end
+        end
+
+        public_class_method def self.authors
+          "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n"
+        end
+
+        public_class_method def self.help
+          puts "USAGE:
+            # Install and verify native ESP ROM firmware.
+            #{self}.install(
+              protocol: 'optional - :esp_rom only; defaults to :esp_rom',
+              port: 'required - dedicated UART device path, not an active PhoneAPI connection',
+              chip: 'required - :esp32, :esp32s3 or :esp32c3; UART ROM only',
+              bytes: 'optional - raw unmerged application image, exclusive with firmware',
+              firmware: 'optional - application .bin file path, exclusive with bytes',
+              offset: 'required - known application partition address, >= 0x10000, sector aligned',
+              flash_size: 'required - known physical flash capacity, power of two from 1 to 16 MiB',
+              reset: 'optional - :classic DTR/RTS reset (default) or :none for manual ROM entry',
+              timeout: 'optional - positive command deadline in seconds, default 120'
+            )
+            # Print author contact information.
+            #{self}.authors
+          "
+        end
+      end
+    end
+  end
+end

data/lib/meshtastic/admin/firmware.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'socket'
+require 'timeout'
+
+
+module Meshtastic
+  module Admin
+    module Firmware
+      public_class_method def self.sha256(opts = {})
+        Digest::SHA256.digest(firmware_bytes(opts.merge({})))
+      end
+
+      public_class_method def self.request_ota(opts = {})
+        mode = opts.fetch(:mode, :OTA_BLE)
+        raise ArgumentError, 'mode must be :OTA_BLE or :OTA_WIFI' unless %i[OTA_BLE OTA_WIFI].include?(mode)
+
+        hash = opts[:ota_hash] || sha256(opts)
+        raise ArgumentError, 'ota_hash must be a raw 32-byte String' unless hash.is_a?(String) && hash.bytesize == 32
+        raise ArgumentError, 'ota_hash does not match firmware bytes' if opts[:ota_hash] && (opts.key?(:bytes) || opts.key?(:firmware)) && hash != sha256(opts)
+
+        event = Meshtastic::AdminMessage::OTAEvent.new(
+          reboot_ota_mode: mode,
+          ota_hash: hash.b
+        )
+        Admin.send(opts.except(:bytes, :firmware, :ota_hash, :mode).merge(ota_request: event))
+      end
+
+      public_class_method def self.enter_dfu(opts = {})
+        Admin.send(opts.merge(enter_dfu_mode_request: true))
+      end
+
+      public_class_method def self.reboot_ota(opts = {})
+        opts.merge({})
+        raise NotImplementedError, 'reboot_ota_seconds is not handled by current firmware; use request_ota'
+      end
+
+      public_class_method def self.xmodem_blocks(opts = {})
+        opts.merge({})
+        raise NotImplementedError, 'PhoneAPI XModem transfers filesystem files, not firmware images'
+      end
+
+      public_class_method def self.send_xmodem(opts = {})
+        opts.merge({})
+        raise NotImplementedError, 'PhoneAPI XModem transfers filesystem files, not firmware images'
+      end
+
+      public_class_method def self.install(opts = {})
+        validate_verification(opts[:verify]) if opts.key?(:verify)
+        options = opts.except(:verify)
+        result = case opts[:protocol]
+                 when :unified_ble then BLE.install(options)
+                 when :esp_rom then SerialBootloader.install(options)
+                 when :nordic_dfu then NordicDFU.install(options)
+                 when :unified_wifi then install_wifi(options)
+                 else raise NotImplementedError, 'install requires explicit protocol: :unified_wifi, :unified_ble, :esp_rom or :nordic_dfu'
+                 end
+        return result unless opts[:verify]
+
+        result.merge(verify_reboot(opts[:verify])).merge(loader_status: result[:status], reboot_verified: true, boot_verified: true)
+      end
+
+      private_class_method def self.install_wifi(opts = {})
+        validate_install(opts.merge({}))
+        bytes = firmware_bytes(opts.merge({}))
+        digest = Digest::SHA256.hexdigest(bytes)
+        timeout = opts.fetch(:timeout, 120)
+        socket = connect_loader(opts.merge(timeout: timeout))
+        Timeout.timeout(timeout) do
+          socket.write("VERSION\n")
+          version = response(socket: socket)
+          raise IOError, "Invalid loader VERSION: #{version}" unless version.match?(/\AOK \d+ \S+ \d+ \S+\z/)
+
+          socket.write("OTA #{bytes.bytesize} #{digest}\n")
+          line = response(socket: socket)
+          line = response(socket: socket) if line == 'ERASING'
+          raise IOError, "OTA handshake rejected: #{line}" unless line == 'OK'
+
+          upload(socket: socket, bytes: bytes)
+          { status: :verified, bytes: bytes.bytesize, sha256: digest, loader_version: version.delete_prefix('OK ') }
+        end
+      ensure
+        socket&.close
+      end
+
+      public_class_method def self.verify_reboot(opts = {})
+        validate_verification(opts.merge({}))
+        handle = nil
+        transport = { tcp: Meshtastic::TCP, bluetooth: Meshtastic::Bluetooth, serial: Meshtastic::Serial }.fetch(opts.fetch(:transport))
+        key = { tcp: :tcp_obj, bluetooth: :bluetooth_obj, serial: :serial_obj }.fetch(opts.fetch(:transport))
+        Timeout.timeout(opts.fetch(:timeout, 60)) do
+          sleep opts.fetch(:reboot_delay, 3)
+          begin
+            handle = if opts[:reconnect]
+                       opts[:reconnect].call(transport: opts.fetch(:transport), connection: opts.fetch(:connection, {}), timeout: opts.fetch(:timeout, 60))
+                     else
+                       transport.connect(opts.fetch(:connection).merge(want_config: true))
+                     end
+            transport.wait_for_config(key => handle, timeout: opts.fetch(:timeout, 60))
+          rescue IOError, SystemCallError
+            transport.disconnect(key => handle) if handle
+            handle = nil
+            sleep 0.25
+            retry
+          end
+          reply = Admin.request(key => handle, get_device_metadata_request: true, timeout: opts.fetch(:timeout, 60))
+          metadata = reply.fetch(:value).to_h
+          raise IOError, "Firmware version mismatch: #{metadata[:firmware_version].inspect}" unless metadata[:firmware_version] == opts.fetch(:expected_version)
+          raise IOError, 'Post-reboot node identity mismatch' if opts[:expected_node] && handle[:my_node_num] != opts[:expected_node]
+
+          { status: :boot_verified, firmware_version: metadata[:firmware_version], node_num: handle[:my_node_num], metadata: metadata }
+        end
+      ensure
+        transport.disconnect(key => handle) if handle
+      end
+
+      private_class_method def self.validate_verification(opts = {})
+        raise ArgumentError, 'verify must be a Hash of verify_reboot options' unless opts.is_a?(Hash)
+
+        allowed = %i[transport connection expected_version expected_node reconnect timeout reboot_delay]
+        raise ArgumentError, 'Unknown reboot verification option' unless (opts.keys - allowed).empty?
+        raise ArgumentError, 'transport must be :tcp, :bluetooth or :serial' unless %i[tcp bluetooth serial].include?(opts[:transport])
+        raise ArgumentError, 'expected_version must be a nonempty firmware version String' unless opts[:expected_version].is_a?(String) && !opts[:expected_version].empty?
+        raise ArgumentError, 'expected_node must be a numeric node ID' if opts.key?(:expected_node) && !(opts[:expected_node].is_a?(Integer) && (1..0xffffffff).cover?(opts[:expected_node]))
+
+        timeout = opts.fetch(:timeout, 60)
+        delay = opts.fetch(:reboot_delay, 3)
+        raise ArgumentError, 'timeout must be positive finite seconds' unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout.positive?
+        raise ArgumentError, 'reboot_delay must be nonnegative finite seconds' unless delay.is_a?(Numeric) && delay.real? && delay.finite? && delay >= 0
+        raise ArgumentError, 'reconnect must be callable' if opts.key?(:reconnect) && !opts[:reconnect].respond_to?(:call)
+        return if opts[:reconnect]
+
+        connection = opts[:connection]
+        required = { tcp: :host, bluetooth: :address, serial: :block_dev }.fetch(opts[:transport])
+        raise ArgumentError, "connection must specify #{required}" unless connection.is_a?(Hash) && connection[required].is_a?(String) && !connection[required].strip.empty?
+
+        keys = { tcp: %i[host port], bluetooth: %i[address adapter timeout], serial: %i[block_dev baud] }.fetch(opts[:transport])
+        raise ArgumentError, 'Only fresh connection endpoint options are allowed' unless (connection.keys - keys).empty?
+
+        if opts[:transport] == :tcp
+          port = connection.fetch(:port, 4403)
+          raise ArgumentError, 'Application TCP port must be in 1..65535' unless port.is_a?(Integer) && (1..65_535).cover?(port)
+        elsif opts[:transport] == :bluetooth
+          # Construction validates address/adapter/timeout without touching D-Bus.
+          Meshtastic::Bluetooth::BlueZ.new(address: connection[:address], adapter: connection.fetch(:adapter, 'hci0'), timeout: connection.fetch(:timeout, 15))
+        end
+      end
+
+      private_class_method def self.upload(opts = {})
+        socket = opts.fetch(:socket)
+        writer = Thread.new do
+          Thread.current.report_on_exception = false
+          socket.write(opts.fetch(:bytes))
+        rescue IOError, SystemCallError
+          socket.close
+          raise
+        end
+        loop do
+          line = response(socket: socket)
+          break if line == 'OK'
+          raise IOError, "OTA transfer rejected: #{line}" unless line == 'ACK'
+        end
+        writer.value
+      ensure
+        writer&.kill
+        writer&.join
+      end
+
+      private_class_method def self.connect_loader(opts = {})
+        attempts = 0
+        begin
+          attempts += 1
+          Socket.tcp(opts.fetch(:host), opts.fetch(:port, 3232), connect_timeout: opts.fetch(:timeout))
+        rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT
+          raise if attempts > opts.fetch(:retries, 3)
+
+          sleep opts.fetch(:retry_delay, 1)
+          retry
+        end
+      end
+
+      private_class_method def self.response(opts = {})
+        line = opts.fetch(:socket).gets("\n", 513)
+        raise IOError, 'OTA connection closed before confirmation' unless line
+        raise IOError, 'Invalid OTA response framing' unless line.end_with?("\n") && line.bytesize <= 512
+
+        line.chomp
+      end
+
+      private_class_method def self.validate_install(opts = {})
+        allowed = %i[protocol host port bytes firmware timeout retries retry_delay]
+        unknown = opts.keys - allowed
+        raise ArgumentError, "Unsupported install options: #{unknown.join(', ')}" unless unknown.empty?
+        raise ArgumentError, 'host must be a nonempty string' unless opts[:host].is_a?(String) && !opts[:host].strip.empty?
+
+        port = opts.fetch(:port, 3232)
+        retries = opts.fetch(:retries, 3)
+        timeout = opts.fetch(:timeout, 120)
+        delay = opts.fetch(:retry_delay, 1)
+        raise ArgumentError, 'port must be in 1..65535' unless port.is_a?(Integer) && (1..65_535).cover?(port)
+        raise ArgumentError, 'retries must be in 0..20' unless retries.is_a?(Integer) && (0..20).cover?(retries)
+        raise ArgumentError, 'timeout must be finite and positive' unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+        raise ArgumentError, 'retry_delay must be finite and nonnegative' unless delay.is_a?(Numeric) && delay.finite? && delay >= 0
+      end
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n        0day Inc. <support@0dayinc.com>\n      "
+      end
+
+      public_class_method def self.help
+        puts "USAGE:
+          # SHA-256 the firmware image bytes or file.
+          #{self}.sha256(
+            firmware: 'optional - path to a firmware .bin on disk',
+            bytes: 'optional - raw firmware image bytes if no path is given'
+          )
+
+          # Send Admin ota_request with the image hash and OTA mode.
+          #{self}.request_ota(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect',
+            mqtt_obj: 'optional - MQTT client from Meshtastic::MQTT.connect',
+            firmware: 'optional - path to a firmware .bin on disk',
+            ota_hash: 'optional - 32-byte SHA-256 digest if not hashing firmware',
+            mode: 'optional - :OTA_BLE or :OTA_WIFI (default: :OTA_BLE)'
+          )
+
+          # Ask the node to enter DFU / UF2 bootloader mode.
+          #{self}.enter_dfu(
+            serial_obj: 'optional - serial handle from Meshtastic::Serial.connect'
+          )
+
+          # Reject the obsolete unhandled legacy OTA reboot field.
+          #{self}.reboot_ota
+
+          # Reject filesystem XModem as a firmware update mechanism.
+          #{self}.xmodem_blocks
+
+          # Reject filesystem XModem as a firmware update mechanism.
+          #{self}.send_xmodem
+
+          # Upload using an explicitly selected native loader protocol.
+          #{self}.install(
+            protocol: 'required - :unified_wifi, :unified_ble, :esp_rom or :nordic_dfu; no protocol guessing',
+            verify: 'optional - verify_reboot options Hash; success becomes :boot_verified only after a fresh reply',
+            host: 'required - OTA loader IP address or hostname, not a mesh node ID',
+            port: 'optional - separate OTA TCP service port (default: 3232)',
+            firmware: 'optional - matching application .bin path, exclusive with bytes',
+            bytes: 'optional - nonempty raw image String, exclusive with firmware',
+            timeout: 'optional - positive seconds per connect and whole transfer (default: 120)',
+            retries: 'optional - connection refusal/timeout retries, 0..20 (default: 3)',
+            retry_delay: 'optional - nonnegative seconds between connection retries (default: 1)'
+          )
+          # First use request_ota with the matching mode to pin the same image hash.
+          # install never sends preparation commands; :verified means loader OK, not boot confirmation.
+          # BLE.help, NordicDFU.help and SerialBootloader.help document protocol-specific options.
+
+          # Reconnect and request fresh correlated application firmware metadata.
+          #{self}.verify_reboot(
+            transport: 'required - :tcp, :bluetooth or :serial for the restarted application',
+            connection: 'optional - connect options Hash with explicit host/address/block_dev; required without reconnect',
+            expected_version: 'required - exact firmware version reported by the intended application',
+            expected_node: 'optional - numeric node identity to verify after restart',
+            reconnect: 'optional - callable accepting options Hash and returning a newly connected transport handle',
+            timeout: 'optional - entire reboot/reconnect/config/metadata deadline seconds, default 60',
+            reboot_delay: 'optional - initial wait for loader restart, default 3 seconds'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+      end
+
+      private_class_method def self.firmware_bytes(opts = {})
+        raise ArgumentError, 'provide exactly one of firmware or bytes' unless opts.key?(:bytes) ^ opts.key?(:firmware)
+
+        bytes = opts.key?(:bytes) ? opts[:bytes] : File.binread(opts[:firmware])
+        raise ArgumentError, 'firmware bytes must be a nonempty String' unless bytes.is_a?(String) && !bytes.empty?
+
+        bytes.b
+      end
+    end
+  end
+end
+
+require 'meshtastic/admin/firmware/ble'
+require 'meshtastic/admin/firmware/serial_bootloader'
+require 'meshtastic/admin/firmware/nordic_dfu'