Hodmin is a tool to administrate Homie-devices (IOT, esp8266-based microcomputers with Homie-firmware: Homie)
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. If needed, these commands can be used within your own scripts, so interaction with Homie-devices is very flexible. Hodmin does not communicate with a homie-device directly. It instead uses your MQTT-broker to pull / push informations from / to a device.
List devices seen in my network and available firmwares in my Arduino-sketchbook of my workstation:
hodmin list
Left part of first three lines show us our devices with Homie-name. Column checksum shows md5 of installed firmware. Right part of table shows all Homie-firmwares found in sketchbook-directory. If a firmware is listed in same row as a device, this firmware is running on this device. If checksum is shown in green color, the latest firmware of this firmware-name is running. The third line in example above is yellow, so there is a new firmware available in our sketchbook to install.
If we like to update our 'yellow' device, we just use this command:
hodmin -m a02* pushFW -c e240*
Option -m specifies MAC-address of our device. Because there is only one device starting with a02, there is no need to type all chars of MAC. We use instead. After subcommand pushFW we need to specify firmware-file to be uploaded to our device. In this example we do it by option -c for checksum and use also.
Starting this command will send our binaryfile Over the Air (OTA) to our device. More examples are provided down below and refer to this screenshot.
All this stuff is homie-functionality, but Hodmin wraps it in some handy commands. In my point of view work with homie is more comfortable using Hodmin.
Install with gem install hodmin
. After installation start with command hodmin list
. This will put a default config-file in ~/.hodmin.yaml. Open this file with any editor and fill in your MQTT-credentials.
Hodmin ist a bundle of scripts written in Ruby. You need a running Ruby-Installation (tested: 2.0.0 and above), most modern operating systems include one (Debian-based systems: apt-get install ruby-full
or use RVMRVM). Hodmin ist developed and tested under Linux - it should run under MAC OS/X and -maybe - Windows too - but I didn' t test it until now.
Every Hodmin command starts with hodmin
optional followed by a device-description to select one or some homie-devices. Next part is a subcommand, which describes desired action, optional followed by more options describing firmware used in this action.
In every command and every subcommand you can use -h to see short help info about using a command.
Remark: Firmware-name in Homie is defined by using magic-bytes in sourcecode of your application. It is by no means connected with filename of binary-file. Same applies to firmware-version. If you do not use this magic-bytes in your sketch, Hodmin will not identify this firmware. See Homie-documentation for details.
This commands searches your MQTT-broker for Homie-devices (identfied by tree devices/homie in default config). It also searches your directory-tree for Homie-firmware (identfied by magic-bytes). So to work with Hodmin you should always compile your Homie-Firmware and save it on disk (Arduino: export bin-file).
Options before list subcommand:
Options after list subcommand
This subcommand pulls config-data from a Homie-device and shows it on screen. Use it as config-backup and boilerplate for changing config. This command does not read directly from a Homie-device, instead it reads your MQTT-broker to collect all config-info. So this command is available even if your device is offline.
Options after pullCF subcommand
-o, --outputfile=\: Give this option if you wish to save config-data in a file. Default filename ist Homie-\
Example:
- hodmin -m *747 pullCF # will create a file *Homie-6001940c5747.yaml* in your working directory.
This subcommand pushes config-data to a Homie-device (to be exact: to MQTT-broker). It reads from YAML-file (see above).
Options after pushCF subcommand
hodmin -m *747 pushCF -j '{"ota": {"enabled":false}}'
will turn off OTA-mode.-s, --shortconfig=\: Fast changing of some config-options. Possible for setting: 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.
Examples:
- hodmin -m *112 pushCF -s mqttpw:'abc' # change config for this device
- hodmin -m *112 pushCF -s "ota:off mqttpw:abc auth:true" # change multiple config for this device
- hodmin -f WLAN* pushCF -s "ota:off mqttpw:abc auth:true" # change multiple config for all devices running firmware 'WLAN*'
This subcommand pushes binary firmware-file to a Homie-device.
Options after pushFW subcommand
-a, --auto Upgrade in batch mode - do not ask for updating a device (be carefull using this option). If you use Hodmin within cron-scripts, this option might be usefull.
Examples:
- hodmin -m *747 pushFW -c 25* # will bring firmware-version 1.0.2 to device 6001940c5747 (see screenshot above).
- hodmin -m *747 pushFW -f WLAN* -u -a # will update this device without any further question.
This subcommand searches in your firmware-directory for Homie-firmware-files. Every filename not already in Hodmin-style is offered to rename. Hodmin-style: "Homie_\
This subcommand searches in your firmware-directory for Homie-firmware-files. Every filename matching your pattern is offered to be removed.
This subcommand is usefull only for the first step in setting up a Homie-device. After firmware is sent to a device for the first time (or reset) via USB, it spans a AP which is used to get config-data. Plug your workstation into this wifi-network and start initiate. This command tries to send a config file to IP 192.168.123.1. Basically it wraps only one bash-command: `curl -X PUT http://192.168.123.1/config -d @\
During startup Hodmin checks existence of file ~/.hodmin.yaml. If it is found, Hodmin reads its configuration. Otherwise Hodmin creates this file and writes a default config into it. Edit this file before starting Hodmin next time.
mqtt:
protocol: mqtt://
host: mqtt.example.net
port: '1883'
auth: true
user: '<username>'
password: '<password>'
base_topic: 'devices/homie/'
timeout: '0.3'
firmware:
dir: '/home/<username>/sketchbook/'
filepattern: '*.bin'
logging:
# STDOUT OR nil OR filename
logdestination: nil
output:
list: 'HD.mac HD.online HD.localip HD.name FW.checksum FW.fw_name FW.fw_version'
nil: # Text to be shown in table in case of NIL-value
Hodmin is a tool to administrate Homie-Devices. Copyright (C) 2017 Thomas Romeyke (rttools at gmail.com).
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.