hodmin 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ca64ac3ab89207e68d267256ed0a4ff2f470a4f6
+  data.tar.gz: 9fe8e38d5b38c415e6dc7c0e684d4edf11bb6953
+SHA512:
+  metadata.gz: 616baeec41f7eefafc5f7b7a593dddc8d7ec23fb3db92a7ae5382bc68388133e7b5f17077f187d2c2a915deae6d78265465be341c56488bbdff20c92570babfd
+  data.tar.gz: e2e69c449d0a01e20ac92f00d609811f6fed9f8034cde446deed91bd048f9781b31636160c5645940b8a2a941c4a177098b1168aa8324abaa4d026329fc84d62

data/bin/hodmin

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+# hodmin (homie-admin): provides cli to administrate homie-devices
+
+require 'trollop'
+require 'digest/md5'
+require 'pathname'
+require 'tty/table'
+require 'tty/cursor'
+require 'pastel'
+require 'json'
+require 'logger'
+require 'yaml'
+require 'configatron'
+require 'mqtt'
+require 'hodmin.rb'
+
+require 'hodmin/hodmin_list.rb'
+require 'hodmin/hodmin_push_config.rb'
+require 'hodmin/hodmin_pull_config.rb'
+require 'hodmin/hodmin_push_firmware.rb'
+require 'hodmin/hodmin_remove.rb'
+require 'hodmin/hodmin_rename.rb'
+require 'hodmin/hodmin_tools.rb'
+require 'hodmin/hodmin_initialize.rb'
+
+MAX_HOMIEVERSION = '2.0.0'.freeze
+COMMANDS = [%w(list pushFW pushCF initialize pullCF remove rename help)].freeze
+global_opts = Trollop.options do
+  banner <<-EOS.gsub(/    /, '').gsub(/#VS#/, Hodmin::VERSION)
+    HODMIN - Homie-Administration utility for using Homie-devices (ESP8266 controlled microcomputers)
+    Version #VS# (C) T. Romeyke
+    Usage:
+         hodmin [OPTIONS] COMMAND [SUBOPTIONS]
+
+    COMMANDS
+      list			list Homie-devices and / or firmware
+      pushCF		push config-data to device
+      pullCF		pull config-data from device
+      pushFW		push firmware-file to device (OTA: Over-The-Air, WIFI)
+      rename		rename firmware-file in firmware-directory
+      remove		remove firmware-file from firmware-directory
+      initialize		initialize Homie-device after first flashing of firmware via USB. Uses WIFI-AP of Device. EXPERIMENTAL!
+
+    Options (before COMMAND)
+      Every option-string can be shorted with a star: ie: --mac c55* OR *c55 => all mac starting/ending with c55
+    where [OPTIONS] are:
+    EOS
+  opt :mac, 'select device(s) by mac', type: String
+  opt :fw_name, 'select device(s) by firmware-name', type: String
+  opt :checksum, 'select device(s) by actual firmware-checksum', type: String
+  opt :localip, 'select device(s) by actual ip4-address', type: String
+  opt :configfile, 'use this configfile instead of default', type: String, default: '~/.hodmin.yaml'
+  stop_on COMMANDS
+end
+
+cmd = ARGV.shift # get the command
+cmd_opts = case cmd
+           when 'list' # parse list options
+             Trollop.options do
+               opt :fw_name, 'Select firmware(s) by firmware-name', type: String
+               opt :checksum, 'Select firmware(s) by firmware-checksum',  type: String
+               opt :style, 'Output table style: unicode, ascii or basic', type: String
+               opt :nil, 'Text to be printed in table in case of NIL-value', type: String
+             end
+           when 'pushFW'  # parse pushFW options
+             Trollop.options do
+               opt :fw_name, 'Select firmware-file by firmware-name', type: String
+               opt :checksum, 'Select ONE firmware-files by firmware-checksum', type: String
+               opt :upgrade, 'Select newest firmware-file by firmware-name of Homie-device', type: TrueClass
+               opt :auto, 'Upgrade in batch mode (do not ask for updating a device'\
+                        + ' (be carefull using this option)', type: TrueClass, default: false
+             end
+           when 'pushCF'  # parse pushCF options
+             Trollop.options do
+               opt :jsonconfig, 'JSON-formatted string with config-option(s) to change', short: '-j', type: String
+               opt :inputfile, 'Read new config-options from YAML-file', type: String
+               opt :shortconfig, 'Fast changing of some config-options. Only name:xy ota:on|off'\
+                               + ' ssid:xy wifipw:xy host:xy port:xy base_topic:xy'\
+                               + ' auth:on|off user:xy mqttpw:xy.'\
+                               + ' Enclose multiple options in "", separate options with a blank.'\
+                               + ' Arguments (i.e. passwords) must NOT include blanks or colons.'\
+                               + ' If you need these characters, use option -j or -i.', type: String
+             end
+           when 'pullCF' # parse pullCF options
+             Trollop.options do
+               opt :outputfile, 'Save config-options to file',  type: String, default: 'Homie-<MAC>'
+             end
+           when 'initialize' # parse initialize options
+             Trollop.options do
+               opt :configfile, 'Push initiating config-options from file to new device'\
+                 , type: String, default: 'homie-initialize.yaml'
+             end
+           when 'remove' # remove binary file
+             Trollop.options do
+               opt :fw_name, 'Select firmware-file by firmware-name', type: String
+               opt :checksum, 'Select firmware-file(s) by firmware-checksum', type: String
+             end
+           when 'rename' # rename binary file
+             Trollop.options do
+               opt :fw_name, 'Select firmware-file by firmware-name', type: String
+               opt :checksum, 'Select firmware-file(s) by firmware-checksum', type: String
+             end
+           else
+             Trollop.die "unknown subcommand #{cmd.inspect}"
+           end
+
+configatron.VERSION = Hodmin::VERSION
+configatron.MAX_HOMIEVERSION = MAX_HOMIEVERSION
+
+# read config:
+configfile = ''
+if global_opts[:configfile_given]
+  # if option -o is given, use config-file named in this option
+  configfile = File.expand_path(global_opts[:configfile])
+  unless File.exist?(configfile)
+    puts "ERR: Configfile not found: #{configfile}"
+    exit
+  end
+else
+  # no special configfile given, so read global hodmin-config of this user.
+  # If reading fails, store new hodmin-config with default values and exit.
+  configfile = File.expand_path('~/.hodmin.yaml')
+  unless File.exist?(configfile)
+    File.open(configfile, 'w') { |f| f.puts default_config.to_yaml }
+    puts "WARN: Default configfile written to: #{configfile}"
+  end
+end
+
+# now we can load from configfile
+config = YAML.load_file(configfile)
+
+# check config:
+exit unless check_config_ok?(config, configfile)
+
+configatron.configure_from_hash(config)
+
+# set colors for pastel list output:
+ENV.store('PASTEL_COLORS_ALIASES', 'hd_f=black,hd_b=on_bright_green,fw_f=black,fw_b=on_bright_blue')
+
+configatron.output.nil = cmd_opts[:nil] if cmd_opts[:nil_given]
+
+case cmd
+when 'list'
+  hodmin_list(global_opts, cmd_opts)
+when 'pushFW'
+  hodmin_push_firmware(global_opts, cmd_opts)
+when 'pushCF'
+  hodmin_push_config(global_opts, cmd_opts)
+when 'pullCF'
+  hodmin_pull_config(global_opts, cmd_opts)
+when 'initialize'
+  hodmin_initialize(global_opts, cmd_opts)
+when 'remove'
+  hodmin_remove(cmd_opts)
+when 'rename'
+  hodmin_rename(global_opts, cmd_opts)
+else
+  Log.log.error "unknown CMD:#{cmd}. Opts: #{global_opts}"
+end

data/lib/hodmin.rb

@@ -0,0 +1,5 @@
+require "hodmin/version"
+
+module Hodmin
+  # nothing here right now
+end

data/lib/hodmin/hodmin_initialize.rb

@@ -0,0 +1,42 @@
+# Initiate a Homie-Device with first config from a YAML-file.
+# Uses bash CLI calling Curl-binary. Will not work, if curl is not available.
+# Perhaps a better solution should use http-requests => to be done
+# Status: experimental
+def hodmin_initialize(gopts, copts)
+  c1 = 'command -v curl >/dev/null 2>&1 || { echo  "curl required but it is not installed."; }'
+  ip = '192.168.123.1'
+  ans = `#{c1}`.to_s.strip
+  if ans.empty?
+    default_filename = 'homie-initialize.yaml'
+    filename = copts[:configfile_given] ? copts[:configfile] : default_filename
+
+    unless File.exists?(filename)
+      puts "ERR: Configfile with initializing data not found: #{filename}"
+      exit if filename != default_filename
+      # create example config-file:
+      File.open(filename, 'w') { |f| f.puts default_config_initialize.to_yaml }
+      puts "WARN: Default initializing data written to: #{filename}. Please edit this file!"
+      exit
+    end
+    
+    # write config in JSON-Format to tempfile:
+    tempfile = 'configHOMIEjson.tmp'
+    File.open(tempfile,'w'){|f| f.puts YAML.load_file(filename).to_json}
+    
+    # upload to device:
+    puts "trying to connect to #{ip} ..."
+    c2 = "curl -X PUT http://#{ip}/config -d @#{tempfile} --header 'Content-Type: application/json'"
+    ans = `#{c2}`.to_s
+    json = JSON.parse(ans)
+    if json['success']
+      puts "\nDevice is initialized now."
+    else
+      puts "\nOops. Something went wrong: curl answered: #{ans}"
+    end
+    File.delete(tempfile)
+  else
+    # curl not installed
+    puts 'ERR: curl required, but it is not installed. Aborting.'
+    exit
+  end
+end

data/lib/hodmin/hodmin_list.rb

@@ -0,0 +1,62 @@
+# Homie-Admin LIST
+# Print list of Homie-Decices with installed firmware and available firmware in our repo
+def hodmin_list(gopts, copts)
+  all_fws = fetch_homie_fw_list # we need it for checking upgrade-availability
+  my_fws = all_fws.select_by_opts(copts)\
+                  .sort do |a, b|
+                    [a.fw_brand, a.fw_name, b.fw_version] <=> \
+                      [b.fw_brand, b.fw_name, a.fw_version]
+                  end
+                  
+  # fetch all devices, set upgradable-attribute based on my_fws:
+  my_devs = fetch_homie_dev_list(my_fws).select_by_opts(gopts)
+  my_list = []
+  already_listed = []
+
+  my_devs.each do |d|
+    firmware = my_fws.select { |f| f.checksum == d.fw_checksum }
+    if firmware.count > 0
+      # found installed firmware
+      my_list << HomiePair.new(d, firmware)
+      already_listed << firmware.first.checksum # remember this firmware as already listed
+    else
+      # did not find firmware-file installed on this device
+      my_list << HomiePair.new(d, nil) unless gopts[:upgradable_given]
+    end
+  end
+
+  # now append remaining firmwares (for which we did not find any Homie running this) to my_list:
+  already_listed.uniq!
+  my_fws.select { |f| !already_listed.include?(f.checksum) }.each { |f| my_list << HomiePair.new(nil, f) }
+
+  # attributes of my_list we want to see in output:
+  # HD: attributes coming from HomieDevice
+  # FW: attributes coming from firmware-file
+  # AD: additional attributes in HomiePair-class for special purposes
+  # Read our format for table from config-file:
+  attribs = configatron.output.list.strip.split(/ /) unless configatron.output.nil?
+  
+  # create output-table
+  rows = my_list.create_output_table(attribs, copts[:style])
+  # define a header for our output-table
+  # header = attribs.map { |a| a.gsub(/HD./, '').gsub(/FW./, '').gsub(/AD./, '') }
+  header = attribs.map(&:setup_header)
+  # build table object:
+  output = TTY::Table.new header, rows
+  table_style = copts[:style_given] ? copts[:style].to_sym : :unicode # :ascii :basic
+  
+  # show our table:
+  puts output.render(table_style, alignment: copts[:style] == 'basic' ? [:left] : [:center])
+end
+
+# Extends class String with methods for using Pastel-Methods
+class String
+  def setup_header
+    pastel = Pastel.new
+    case slice(0, 2)
+    when 'HD' then pastel.white(gsub(/HD./, ''))
+    when 'FW' then pastel.white(gsub(/FW./, ''))
+    else gsub(/AD./, '')
+    end
+  end
+end

data/lib/hodmin/hodmin_pull_config.rb

@@ -0,0 +1,42 @@
+# pullCF reads Homie-device config-data via mqtt-protocol.
+# Output-format is YAML
+def hodmin_pull_config(gopts, copts)
+  my_devs = fetch_homie_dev_list.select_by_opts(gopts)
+
+  my_devs.each do |pull_dev|
+    if copts[:outputfile_given]
+      filename = pull_dev.config_yaml_filename_homie(copts[:outputfile])
+      File.open(filename, 'w') do |f|
+        f.puts "# YAML Configfile written by hodmin Version #{configatron.VERSION}"
+        f.puts "# MAC: #{pull_dev.mac}"
+        f.puts "# Status during pullCF: #{pull_dev.online_status}"
+        f.puts "# #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
+        f.puts pull_dev.implementation_config.config_from_string
+      end
+    else
+      puts "Config of device #{pull_dev.name} (#{pull_dev.mac}):"
+      puts pull_dev.implementation_config.config_from_string
+    end
+  end
+end
+
+# Converts string with config-Data (json-format) to nice output.
+class String
+  def config_from_string
+    return '' if strip.empty?
+    JSON.parse(self).to_yaml
+  end
+end
+
+# Create filename for config-data of a HomieDevice depending on default pattern
+# (Homie-<MAC>.yaml) or a given parameter replacing 'Homie'.
+class HomieDevice
+  def config_yaml_filename_homie(fn)
+    config_extension = '.yaml'
+    if fn.include?('<MAC>')
+      fn.gsub(/<MAC>/, mac) + config_extension
+    else
+      fn.gsub(/[^A-Za-z0-9]/, '') + '-' + mac + config_extension
+    end
+  end
+end

data/lib/hodmin/hodmin_push_config.rb

@@ -0,0 +1,96 @@
+# Pushes a config to Homie-device via MQTT-Broker.
+def hodmin_push_config(gopts, copts)
+  conf_cmd  = copts[:jsonconfig] || ''
+  conf_file = copts[:inputfile] || ''
+  conf_short = copts[:shortconfig] || ''
+
+  number_of_options = [:jsonconfig_given, :inputfile_given, :shortconfig_given]\
+                      .count { |e| copts.keys.include?(e) }
+
+  unless number_of_options == 1
+    puts 'ERR: please specify exactly ONE option of: -s, -j, -i'
+    return
+  end
+
+  if copts[:inputfile_given] && !File.exist?(conf_file)
+    puts "ERR: File not found: #{conf_file}"
+    return
+  end
+
+  conf_file = YAML.load_file(conf_file).to_json if copts[:inputfile_given]
+
+  conf_new = conf_cmd if copts[:jsonconfig_given]
+  conf_new = conf_file if copts[:inputfile_given]
+  conf_new = options_long(conf_short) if copts[:shortconfig_given]
+
+  if conf_new.empty?
+    puts 'ERR: No valid config-options found.'
+    return
+  end
+
+  my_devs = fetch_homie_dev_list.select_by_opts(gopts)
+
+  my_devs.each do |up_dev|
+    copts = get_config_from_option(conf_new)
+    puts "Device #{up_dev.mac} is #{up_dev.online_status}"
+    next unless up_dev.online?
+    print 'Start updating? <Yn>:'
+    answer = STDIN.gets.chomp.downcase
+    next unless up_dev.online && 'y' == answer
+    client = mqtt_connect
+    base_topic = configatron.mqtt.base_topic + up_dev.mac + '/'
+    client.subscribe(base_topic + '$implementation/config')
+    conf_old = ''
+    client.get do |_topic, message|
+      # wait for next message in our queue:
+      if conf_old == ''
+        # first loop, store existing config to compare after update:
+        conf_old = message # we do need message only
+        client.publish(base_topic + '$implementation/config/set', copts.to_json, retain: false)
+        puts 'done, device reboots, waiting for ACK...'
+      else
+        # we received a new config
+        new_conf = message
+        break if JSON.parse(new_conf).values_at(*copts.keys) == copts.values
+      end
+      puts "ACK received, device #{up_dev.mac} rebooted with new config."
+    end
+    client.disconnect
+  end
+end
+
+def get_config_from_option(cline)
+  # Example: cline = '{"ota":{"enabled":"true"}, "wifi":{"ssid":"abc", "password":"secret"}}'
+  return '' if cline.to_s.strip.empty?
+  JSON.parse(cline)
+end
+
+# Returns JSON-String with key-value pairs depending on input-string.
+# Example: hodmin pushCF -s "name:test-esp8266 ota:on ssid:xy wifipw:xy host:xy port:xy
+# base_topic:xy auth:off user:xy mqttpw:xy"
+# Enclose multiple options in "", separate options with a blank
+def options_long(short)
+  list = short.split(/ /)
+  cfg = { 'wifi' => {}, 'mqtt' => {} }
+  list.each do |o|
+    key, value = o.split(/:/).map(&:strip)
+    case key.downcase
+    when 'name' then cfg['name'] = value
+    when 'ssid' then cfg['wifi'] = Hash['ssid' => value]
+    when 'wifipw' then cfg['wifi'] = Hash['password' => value]
+    when 'host' then cfg['mqtt'] << Hash['host' => value]
+    when 'port' then cfg['mqtt'] << Hash['port' => value]
+    when 'base_topic' then cfg['mqtt'] = Hash['base_topic' => value]
+    when 'auth' then cfg['mqtt'] = cfg['mqtt'].merge(Hash['auth' => value == 'on' ? true : false])
+    when 'user' then cfg['mqtt'] << Hash['username' => value]
+    when 'mqttpw' then cfg['mqtt'] = cfg['mqtt'].merge(Hash['password' => value])
+    when 'ota' then cfg['ota'] = Hash['enabled' => value == 'on' ? true : false]
+    else
+      puts "ERR: illegal option: #{key.downcase}"
+      exit
+    end
+  end
+  cfg = cfg.delete_if { |_k, v| v.nil? || v.empty? }
+  puts "\nNew config will be: #{cfg.inspect}"
+  cfg.to_json
+end

data/lib/hodmin/hodmin_push_firmware.rb

@@ -0,0 +1,62 @@
+# Uploads firmware to Homie-Device(s)
+def hodmin_push_firmware(gopts, copts)
+  fw_checksum = copts[:checksum] || ''
+  fw_name = copts[:fw_name] || ''
+  batchmode = copts[:auto] || false
+  mac = gopts[:mac] || ''
+  hd_upgrade = gopts[:upgradable_given] && gopts[:upgradable]
+  fw_upgrade = copts[:upgrade_given] && copts[:upgrade]
+
+  gopts[:mac] = mac = '*' if hd_upgrade && gopts[:mac_given]
+
+  if fw_checksum.empty? && fw_name.empty?
+    puts "ERR: No valid firmware-referrer found. (Chksum:#{fw_checksum}, Name: #{fw_name})"
+    return
+  end
+  unless (!fw_checksum.empty? && fw_name.empty?) || (fw_checksum.empty? && !fw_name.empty?)
+    puts 'ERR: Please specify firmware either by checksum or by name (for newest of this name).'
+    return
+  end
+
+  unless !mac.empty? || !fw_name.empty?
+    puts 'ERR: No valid device specified.'
+    return
+  end
+
+  # first find our firmware:
+  my_fws = fetch_homie_fw_list.select_by_opts(copts)
+                              .sort { |a, b| [a.fw_name, b.fw_version] <=> [b.fw_name, a.fw_version] }
+
+  if my_fws.empty?
+    puts 'ERR: None of available firmwares does match this pattern'
+    return
+  else
+    if my_fws.size > 1 && !fw_upgrade
+      puts 'ERR: Firmware specification is ambigous'
+      return
+    end
+  end
+
+  # only first firmware selected for pushing:
+  my_fw = my_fws.first
+
+  # now find our device(s)
+  my_devs = fetch_homie_dev_list(my_fws).select_by_opts(gopts)
+
+  return if my_devs.empty?
+
+  my_devs.each do |up_dev|
+    next if hd_upgrade && !up_dev.upgradable
+    my_fw = my_fws.select { |f| f.fw_name == up_dev.fw_name }.sort_by(&:fw_version).last if hd_upgrade
+    puts "Device #{up_dev.mac} is #{up_dev.online_status}. (installed FW-Checksum: #{up_dev.fw_checksum})"
+    next unless up_dev.online? && up_dev.fw_checksum != my_fw.checksum
+    if batchmode
+      answer = 'y'
+    else
+      print "New firmware: #{my_fw.checksum}. Start pushing? <Yn>:"
+      answer = STDIN.gets.chomp.downcase
+    end
+    Log.log.info "Dev. #{up_dev.mac} (running #{up_dev.fw_version}) upgrading to #{my_fw.fw_version}"
+    up_dev.push_firmware_to_dev(my_fw) if 'y' == answer
+  end
+end

data/lib/hodmin/hodmin_remove.rb

@@ -0,0 +1,32 @@
+def hodmin_remove(copts)
+  fw_checksum = copts[:checksum] || ''
+  fw_name = copts[:fw_name] || ''
+
+  if fw_checksum.empty? && fw_name.empty?
+    puts "ERR: No valid firmware-referrer found. (Chksum:#{fw_checksum}, Name: #{fw_name})"
+    return
+  end
+  unless (!fw_checksum.empty? && fw_name.empty?) || (fw_checksum.empty? && !fw_name.empty?)
+    puts 'ERR: Please specify firmware either by checksum or by name (for newest of this name).'
+    return
+  end
+
+  # first find our firmware-files:
+  my_fws = fetch_homie_fw_list.select_by_opts(copts)
+                              .sort { |a, b| [a.fw_name, b.fw_version] <=> [b.fw_name, a.fw_version] }
+
+  if my_fws.empty?
+    puts 'ERR: None of available firmwares does match this pattern'
+    return
+  else
+    my_fws.each do |f|
+      puts "found Fw: Name: #{f.fw_name}, Version: #{f.fw_version}, MD5: #{f.checksum}"
+    end
+  end
+
+  my_fws.each do |my_fw|
+    print "Remove firmware: #{my_fw.fw_name}, #{my_fw.fw_version}, #{my_fw.checksum}. Remove now? <Yn>:"
+    answer = STDIN.gets.chomp.downcase
+    File.delete(my_fw.file_path) if 'y' == answer
+  end
+end

data/lib/hodmin/hodmin_rename.rb

@@ -0,0 +1,36 @@
+def hodmin_rename(_gopts, copts)
+  fw_checksum = copts[:checksum] || ''
+  fw_name = copts[:fw_name] || ''
+
+  if fw_checksum.empty? && fw_name.empty?
+    puts "ERR: No valid firmware-referrer found. (Chksum:#{fw_checksum}, Name: #{fw_name})"
+    return
+  end
+  unless (!fw_checksum.empty? && fw_name.empty?) || (fw_checksum.empty? && !fw_name.empty?)
+    puts 'ERR: Please specify firmware either by checksum or by name (for newest of this name).'
+    return
+  end
+
+  # first find our firmware-files:
+  my_fws = fetch_homie_fw_list.select_by_opts(copts)
+                              .sort { |a, b| [a.fw_name, b.fw_version] <=> [b.fw_name, a.fw_version] }
+
+  if my_fws.empty?
+    puts 'ERR: None of available firmware does match this pattern'
+    return
+  else
+    my_fws.each do |f|
+      puts "found Fw: Name: #{f.fw_name}, Version: #{f.fw_version}, MD5: #{f.checksum}"
+    end
+  end
+
+  my_fws.each do |my_fw|
+    bin_pattern = "Homie_#{my_fw.fw_name}_#{my_fw.fw_version}_#{my_fw.checksum}.bin"
+    fileobj = Pathname.new(my_fw.file_path)
+    next if bin_pattern == Pathname.new(my_fw.file_path).basename.to_s
+    puts "Rename firmware: #{my_fw.fw_name}, #{my_fw.fw_version}, #{my_fw.checksum}."
+    print "Rename to #{bin_pattern}? <Yn>:"
+    answer = STDIN.gets.chomp.downcase
+    fileobj.rename(fileobj.dirname + bin_pattern) if 'y' == answer
+  end
+end

data/lib/hodmin/hodmin_tools.rb

@@ -0,0 +1,423 @@
+# Defines a comfortable way to use logging.
+class Log
+  def self.log
+    if @logger.nil?
+      log = case configatron.logging.logdestination
+            when 'STDOUT' then STDOUT
+            when 'nil' then nil
+            else configatron.logging.logdestination.to_s
+            end
+      @logger = Logger.new(log)
+      @logger.level = Logger::DEBUG
+      @logger.datetime_format = '%Y-%m-%d %H:%M:%S '
+    end
+    @logger
+  end
+end
+
+# Defines a class for storing all attributes of a Homie-firmware.
+# Check kind of esp8266-firmware: Homie (>= V.2.0 because of magic bytes)
+# Homie: see https://github.com/marvinroger/homie-esp8266
+# Returns hash with fw-details if <filename> includes magic bytes,
+# returns empty hash if doesn't
+class FirmwareHomie < File
+  attr_reader :checksum, :fw_name, :fw_version, :fw_brand, :file_path
+
+  # Initialize a firmware-file for Homie-device. File is recognized by so called Homie-patterns (strings
+  # in binary file) that can be injected through sourcecode.
+  # Possible patterns are firmware-name, firmware-version and firmware-brand.
+  def initialize(filename)
+    @firmware_homie = false
+    return unless homie_firmware?(filename)
+    @file_path = filename
+    @firmware_homie = true
+    binfile = IO.binread(filename)
+    @checksum = Digest::MD5.hexdigest(binfile)
+    binfile = binfile.unpack('H*').first
+
+    fw_name_pattern    = ["\xbf\x84\xe4\x13\x54".unpack('H*').first, "\x93\x44\x6b\xa7\x75".unpack('H*').first]
+    fw_version_pattern = ["\x6a\x3f\x3e\x0e\xe1".unpack('H*').first, "\xb0\x30\x48\xd4\x1a".unpack('H*').first]
+    fw_brand_pattern   = ["\xfb\x2a\xf5\x68\xc0".unpack('H*').first, "\x6e\x2f\x0f\xeb\x2d".unpack('H*').first]
+
+    @fw_brand = @fw_name = @fw_version = '<none>'
+    # find Firmware-Branding
+    @fw_brand = fw_brand_pattern.find_pattern(binfile)
+    # find Firmware-Name:
+    @fw_name = fw_name_pattern.find_pattern(binfile)
+    # find Firmware-Version:
+    @fw_version = fw_version_pattern.find_pattern(binfile)
+    Log.log.info "FW found: #{@fw_name}, #{@fw_version}, #{@checksum}"
+  end
+
+  def homie?
+    @firmware_homie
+  end
+end
+
+# Searches inside binfile for Homie-patterns and returns a string with
+# firmware-brand, name or version.
+class Array
+  def find_pattern(binfile)
+    result = ''
+    if binfile.include?(first)
+      result = binfile.split(first)[1].split(last).first.to_s
+      result = [result].pack('H*') unless result.empty?
+    end
+    result
+  end
+end
+
+# Searches within a binaryfile for so called Homie-magic-bytes to detect
+# a Homie-firmware.
+# See https://homie-esp8266.readme.io/v2.0.0/docs/magic-bytes
+def homie_firmware?(filename)
+  # returns TRUE, if Homiepattern is found inside binary
+  binfile = IO.binread(filename).unpack('H*').first
+  homie_pattern = "\x25\x48\x4f\x4d\x49\x45\x5f\x45\x53\x50\x38\x32\x36\x36\x5f\x46\x57\x25".unpack('H*').first
+  binfile.include?(homie_pattern)
+end
+
+# Methods connects to a MQTT-broker and returns an object linking to this connection.
+def mqtt_connect
+  # establish connection for publishing, return client-object
+  credentials = configatron.mqtt.auth ? configatron.mqtt.user + ':' + configatron.mqtt.password + '@' : ''
+  connection = configatron.mqtt.protocol + credentials + configatron.mqtt.host
+  begin
+    MQTT::Client.connect(connection, configatron.mqtt.port)
+  rescue MQTT::ProtocolException
+    puts "ERR: Username and / or password wrong?\n#{connection} at port #{configatron.mqtt.port}"
+    exit
+  end
+end
+
+# Defines a class for storing all attributes of a Homie-device (aka ESP8266 with
+# Homie-Firmware 2.0 (see: https://github.com/marvinroger/homie).
+class HomieDevice
+  attr_reader :mac, :checksum, :fw_brand, :fw_name, :fw_version, :upgradable
+  def initialize(mqtt, *fw_list)
+    fw_list.flatten!
+    startseq = mqtt.select { |t, _m| t.include?('/$homie') }.first.first.split('$').first
+    @mac = startseq.split(/\//).last
+    mqtt.map! { |t, m| [t.gsub(startseq, ''), m] }
+    mhash = Hash[*mqtt.flatten]
+    create_attr('homieVersion', mhash['$homie'])
+    if mhash['$homie'] > configatron.MAX_HOMIEVERSION
+      Log.log.warn "Device #{mac}: Detected new Homie-version (#{mhash['$homie']})"\
+      + ' check hodmin for updates'
+    end
+    mhash.tap { |hs| hs.delete('$homie') }
+    # Some topics-names from homie do not fit our needs due to special chars like '/'.
+    # ['$fw/name','$fw/version','$fw/checksum']
+    # Replace '/' by '_':
+    mhash.each { |k, v| create_attr(k.to_s.delete('$').gsub(/\//, '_').tr('-', '_'), v) }
+
+    # mac only downcase and without separating ':'
+    @mac = mac.delete(':').downcase
+
+    # for selecting purposes we need some of our topics in different varnames:
+    @checksum = @fw_checksum
+    # do we find a higher version of this firmware than installed one?
+    @upgradable = fw_list.empty? ? false : upgradable?(fw_name, fw_version, fw_list)
+    Log.log.info "Homie-Device detected: mac=#{@mac}, #{online_status}, " \
+      + " running #{fw_name}, #{fw_version}, upgr=#{upgradable}"
+  end
+
+  # Helper to create instance variables on the fly:
+  def create_method(name, &block)
+    self.class.send(:define_method, name, &block)
+  end
+
+  # Helper to create instance variables on the fly:
+  def create_attr(name, value)
+    create_method(name.to_sym) { instance_variable_get('@' + name) }
+    instance_variable_set('@' + name, value)
+  end
+
+  # Helper to determine status of a device (online/offline). Checks it via reading the online-topic
+  # of device at time of creating this object.
+  # WARNING: If you use this in a longer running program, this info may be outdated.
+  # In this case you should create a method that establishes a connection to your broker and
+  # reads the online-topic of this device during execution time.
+  def online?
+    online.casecmp('true').zero?
+  end
+
+  # Helper to create a string containing ONLINE or OFFLINE. Gets it via reading the online-topic
+  # of the device at time of creating this object.
+  # WARNING: If you use this in a longer running program, this info may be outdated.
+  # In this case you should create a method that establishes a connection to your broker and
+  # reads the online-topic of this device during execution time.
+  def online_status
+    online? ? 'ONLINE' : 'OFFLINE'
+  end
+
+  # Helper to push a firmware-file vai MQTT to our Homie-Device.
+  def push_firmware_to_dev(new_firmware)
+    bin_file = File.read(new_firmware.file_path)
+    md5_bin_file = Digest::MD5.hexdigest(bin_file)
+    base_topic = configatron.mqtt.base_topic + mac + '/'
+    client = mqtt_connect
+    sended = FALSE
+    client.publish(base_topic + '$implementation/ota/checksum', md5_bin_file, retain = false)
+    sleep 0.1
+    client.subscribe(base_topic + '$implementation/ota/status')
+    cursor = TTY::Cursor
+    puts ' '
+    client.get do |_topic, message|
+      ms = message
+      ms = message.split(/ /).first.strip if message.include?(' ')
+      if ms == '206'
+        now, ges = message.split(/ /).last.strip.split(/\//).map(&:to_i)
+        actual = (now / ges.to_f * 100).round(0)
+        print cursor.column(1)
+        print "Pushing firmware, #{actual}% done"
+      end
+      if ms == '304'
+        puts '304, file already installed. No action needed. ' + message
+        break
+      end
+      if ms == '403'
+        puts '403, OTA disabled:' + message
+        break
+      end
+      if ms == '400'
+        puts '400, Bad checksum:' + message
+        break
+      end
+      if ms == '202'
+        puts '202, pushing file'
+        client.publish(base_topic + '$implementation/ota/firmware', bin_file, retain = false)
+        sended = TRUE
+      end
+      if ms == '200' && sended
+        puts "\nFile-md5=#{md5_bin_file} installed, device #{name} is rebooting"
+        break
+      end
+    end
+  end
+end
+
+# Class represents a pair of a Homie-Device and a firmware running on this device
+class HomiePair
+  attr_reader :hdev, :hfw
+  def initialize(dev, *fw)
+    fw.flatten!
+    @hdev = dev.nil? ? nil : dev
+    @hfw  = fw.empty? ? nil : fw.first
+  end
+end
+
+# Reads all Homie-Devices from given broker.
+# To be called with connected MQTT-client. Topic has to be set in calling program.
+# Variable timeout_seconds defines, after what time out client.get will be cancelled. Choose
+# a value high enough for your data, but fast enough for quick response. default is 0.7 sec,
+# which should be enough for a lot of Homies controlled by a broker running on a Raspberry-PI.
+def get_homies(client, *fw_list)
+  allmqtt = []
+  begin
+    Timeout.timeout(configatron.mqtt.timeout.to_f) do
+      client.get { |topic, message| allmqtt << [topic, message] }
+    end
+  # we want to read all published messages right now and then leave (otherwise we are blocked)
+  rescue Timeout::Error
+  end
+  # find all homie-IDs (MAC-addresses)
+  macs = allmqtt.select { |t, _m| t.include?('/$homie') }.map { |t, _m| t.split('/$').first.split('/').last }
+  # create a array of homie-devices for macs in our list:
+  homies = []
+  macs.each do |mac|
+    mqtt = allmqtt.select { |t, _m| t.include?(mac) }
+    homies << HomieDevice.new(mqtt, fw_list)
+  end
+  homies
+end
+
+# Return a list of Homie-Devices controlled by given broker.
+def fetch_homie_dev_list(*fw_list)
+  client = mqtt_connect
+  base_topic = configatron.mqtt.base_topic + '#'
+  client.subscribe(base_topic)
+  list = get_homies(client, fw_list)
+  client.disconnect
+  list
+end
+
+# Return a list of Homie-firmwares found in given diretory-tree. Firmwares are identfied
+# by Magic-byte (see https://homie-esp8266.readme.io/v2.0.0/docs/magic-bytes). Filenames
+# are ignored, you can specify a pattern in hodmin-config to speed up searching.
+# Default filename-pattern is '*.bin'
+def fetch_homie_fw_list
+  directory = configatron.firmware.dir + '**/' + configatron.firmware.filepattern
+  Log.log.info "Scanning dir: #{directory}"
+  binlist = Dir[directory]
+  fw_list = []
+  binlist.each do |fw|
+    fw_list << FirmwareHomie.new(fw) if homie_firmware?(fw)
+  end
+  fw_list
+end
+
+# Extends Array class with some specific selection-methods for devices and firmware
+class Array
+  # Selects Array of HomieDevices or firmwares based on options
+  def select_by_opts(options)
+    this_object = first.class == HomieDevice ? 'HD' : 'FW'
+
+    # Options valid for selecting Homie-Devices OR for firmwares
+    valid_dev_options =
+      this_object == 'HD' ? [:mac, :fw_name, :checksum, :localip] : [:checksum, :fw_name, :config]
+
+    # use only valid options:
+    my_opts = options.select { |k, _v| valid_dev_options.include?(k) }
+
+    # remove all options not used as CLI argument:
+    my_opts = my_opts.select { |_k, v| !v.to_s.empty? }
+    return self if my_opts.empty? # no options set, so all devices are selected
+
+    my_devs = self
+    # selects objects (devices or firmwares) from an array due to a filter defined by key-value-pair
+    # Example: [:checksum => 'c79*']
+    my_opts.each_pair do |k, v|
+      # puts "looking for #{k} = #{v}"
+      my_devs = my_devs.select { |h| SelectObject.new(v) =~ h.instance_variable_get("@#{k}") }
+    end
+    my_devs
+  end
+
+  # Creates an array of rows with desired output from HomiePair-objects.
+  def create_output_table(attribs, _style)
+    pastel = Pastel.new
+    empty_field = ' '
+    empty_field = configatron.output.nil.strip unless configatron.output.nil? || configatron.output.nil.nil?
+    empty_field = pastel.dim(empty_field) # dim this message
+    rows = []
+    each do |r|
+      row = []
+      # color for checksum if applicable:
+      checksum_color = if r.hdev.nil?
+                         'none'
+                       else
+                         r.hdev.upgradable ? 'yellow' : 'green'
+                       end
+      attribs.each do |a|
+        row << case a.slice(0, 2)
+               when 'HD' then
+                 var_name = a.gsub(/HD./, '')
+                 var = r.hdev.nil? ? empty_field : r.hdev.instance_variable_get("@#{a.gsub(/HD./, '')}")
+                 case var_name
+                 when 'online'
+                   var = pastel.green(var) if var == 'true'
+                   var = pastel.red(var) if var == 'false'
+                   var if var != 'true' && var != 'false'
+                 else
+                   var = var.nil? ? empty_field : var
+                 end
+               when 'FW' then
+                 if r.hfw.nil?
+                   empty_field
+                 else
+                   var_name = a.gsub(/FW./, '')
+                   var = r.hfw.instance_variable_get("@#{var_name}")
+                   case var_name
+                   when 'checksum'
+                     case checksum_color
+                     when 'none' then var
+                     when 'green' then pastel.green(var)
+                     when 'yellow' then pastel.yellow(var)
+                     end
+                   else
+                     var.nil? ? empty_field : var
+                   end
+                 end
+               when 'AD' then
+                 var = r.instance_variable_get("@#{a.gsub(/AD./, '')}")
+                 var.nil? ? empty_field : var
+               end
+      end
+      rows << row
+    end
+    rows
+  end
+end
+
+# Check a firmware against available bin-files of Homie-firmwares.
+# Returns true, if there is a higher Version than installed.
+# Returns false, if there is no suitable firmware-file found or installed version is the
+# highest version found.
+def upgradable?(fw_name, fw_version, fw_list)
+  fw_list.flatten!
+  # select highest Version of fw_name from given firmware_list:
+  return false if fw_list.empty? # No entries in Softwarelist
+  best_version = fw_list.select { |h| h.fw_name == fw_name }\
+                        .sort_by(&:fw_version).last
+  best_version.nil? ? false : fw_version < best_version.fw_version
+end
+
+# Special class to select a string via Regex. Needed for flexible search for MAC,
+# firmware-name and so on. Helper to construct a Regex.
+class SelectObject
+  def self.string_to_regex(var)
+    Regexp.new "^#{Regexp.escape(var).gsub('\*', '.*?')}$"
+  end
+
+  # Helper
+  def initialize(var)
+    @regex = self.class.string_to_regex(var)
+  end
+
+  # Helper
+  def =~(other)
+    !!(other =~ @regex)
+  end
+end
+
+# Extends String-class with the ability to check whether JSON-items with Hodmin-CFG-data
+# within self-string includes given string. Compares two strings as Hashes: if key/values
+# from str are included in self: TRUE, otherwise FALSE
+class String
+  def include_cfg?(str)
+    return false if self == '' || str == ''
+    h1 = JSON.parse(self)
+    h2 = JSON.parse(str)
+    (h2.to_a - h1.to_a).empty?
+  end
+end
+
+# Checks Hash with config-data
+def check_config_ok?(config, configfile)
+  status_ok = true
+  if config['mqtt']['host'] == 'mqtt.example.com'
+    puts "ERR: No valid config-file found.\nPlease edit config file: #{configfile}."
+    status_ok = false
+  end
+
+  if !config['mqtt']['base_topic'].empty? && config['mqtt']['base_topic'].split(//).last != '/'
+    puts "ERR: mqtt: base_topic MUST end with '/'. Base_topic given: #{config['mqtt']['base_topic']}"
+    status_ok = false
+  end
+  status_ok
+end
+
+# Returns Hash with default config-data for Hodmin. File MUST be edited after creation by user.
+def default_config
+  config = {}
+  config['mqtt'] = Hash['protocol' => 'mqtt://', 'host' => 'mqtt.example.com', 'port' => '1883',\
+                        'user' => 'username', 'password' => 'password', 'base_topic' => 'devices/homie/',\
+                        'auth' => true, 'timeout' => 0.3]
+  config['firmware'] = Hash['dir' => '/home/user/sketchbook/', 'filepattern' => '*.bin']
+  config['logging'] = Hash['logdestination' => 'nil']
+  config['output'] = Hash['list' => 'HD.mac HD.online HD.localip HD.name FW.checksum'\
+                   + 'FW.fw_name FW.fw_version HD.upgradable', 'nil' => '']
+  config
+end
+
+# Returns Hash with default config-data to initialize a Homie-device. File MUST be edited after creation by user.
+def default_config_initialize
+  config = {}
+  config['name'] = 'Homie1234'
+  config['wifi'] = Hash['ssid' => 'myWifi', 'password'=>'password']
+  config['mqtt'] = Hash['host' => 'myhost.mydomain.local', 'port' => 1883, 'base_topic'=>'devices/homie/'\
+           , 'auth'=>true, 'username'=>'user1', 'password' => 'mqttpassword']
+  config['ota'] = Hash['enabled' => true]
+  config
+end

data/lib/hodmin/version.rb

@@ -0,0 +1,3 @@
+module Hodmin
+  VERSION = "0.1.2"
+end

metadata

@@ -0,0 +1,199 @@
+--- !ruby/object:Gem::Specification
+name: hodmin
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Thomas Romeyke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-03-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: configatron
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.5.0
+- !ruby/object:Gem::Dependency
+  name: mqtt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+- !ruby/object:Gem::Dependency
+  name: trollop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+- !ruby/object:Gem::Dependency
+  name: tty-cursor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: tty-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Hodmin enables you to administrate your Homie-devices via command-line-interface
+  (CLI). It consists of some scripts to wrap homie-administration in some handy commands.
+  Hodmin does not communicate with a homie-device directly. It instead uses your MQTT-broker
+  to pass informations to a device.
+email:
+- rttools@googlemail.com
+executables:
+- hodmin
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/hodmin
+- lib/hodmin.rb
+- lib/hodmin/hodmin_initialize.rb
+- lib/hodmin/hodmin_list.rb
+- lib/hodmin/hodmin_pull_config.rb
+- lib/hodmin/hodmin_push_config.rb
+- lib/hodmin/hodmin_push_firmware.rb
+- lib/hodmin/hodmin_remove.rb
+- lib/hodmin/hodmin_rename.rb
+- lib/hodmin/hodmin_tools.rb
+- lib/hodmin/version.rb
+homepage: http://www.github.com/rttools/hodmin
+licenses:
+- GPL-3.0
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Hodmin is a tool to administrate Homie-devices (esp8266-based microcomputers
+  with Homie-firmware)
+test_files: []