HomieMonitor

An exploration into Homie-esp8266, using modules from Dry-RB, Paho.MQTT.Ruby, JRuby and Roda tooling. This application is designed to act as a Homie Controller, or Monitor, in support of IOT/Devices using Homie-esp8266; although any Homie Device implementation should be supported.

References:

Screenshots

Features

Device Discovery for Homie Version 2+ devices.
Real-Time Status of all discovered devices.
Stale Device deletion (from MQTT) for decommissioned Homie Devices.
Scheduled MQTT/OTA by device. binary or base64 flavored.
Homie Image upload and retention.
Ad-Hoc messaging to any device.
In-App Configuration
Current Device Inventory stored in YAML file.
Docker, JRuby, MRI/Ruby runtimes.

Configuration and Demonstration Mode

The configuration module will prefer environment, or in-app settings over the internal settings files values in that order. The default runtime state is demonstration mode, which uses a stored collection of test messages from mosquitto_sub for V2 and V3 devices. The In-App Settings page is the quickest way to configure the application to your environment and is preferred.

Configuring for:

Java warFile use environment vars.
JRuby or Ruby use in-app settings page.
Docker use in-app page or environment vars.

Installation

(a) Ruby/JRuby

Setup Application and Create Directories
     $ git clone https://github.com/skoona/HomieMonitor.git
     $ cd HomieMonitor
     ***Edit*** .ruby-version and remove Gemfile.lock, and vendor directory if changing rubies
     $ bin/setup
Start Server with Puma, Port 8585:
     $ bundle exec puma config.ru -v
Start Console with Pry:
     $ bin/console

(b) Java HomieMonitor warFile and script

Download warFile and `homieMonitor.sh`
    homie_monitor_esp-<version>.war and homieMonitor.sh	    
Edit `homieMonitor.sh` script
    set your mqtt credentials
Start the app on port 8585
    $ homieMonitor

Configuration Environment Vars

The configuration module prefers environment variables over all other methods. Don't use unless needed.

RACK_ENV            defaults to `'production'`          UI Performance is greater with `production`
HM_MQTT_HOST        defaults are invalid                Absence will force :demo_mode, unless using yaml configs or In-App overrides
HM_MQTT_PORT        defaults to 1883
HM_MQTT_USER        defaults are invalid
HM_MQTT_PASS        defaults are invalid
HM_BASE_TOPICS      defaults to `'[["sknSensors/#",0],["homie/#",0]]'`

HM_MQTT_SSL_ENABLE_FLAG defaults to false
HM_MQTT_SSL_CERT_PATH   defaults are invalid
HM_MQTT_SSL_KEY_PATH    defaults are invalid

HM_MQTT_LOG         defaults to empty (not nil)
HM_FIRMWARE_PATH    defaults to './content/firmwares/'
HM_SPIFFS_PATH      defaults to './content/spiffs/'
HM_DATA_STORE       defaults to './content/db/HomieMonitor_store.yml'
HM_OTA_TYPE         binary, base64strict, base64, RFC4648_pad, RFC4648_no_pad 
                    - are the content choices for OTA transmissions; defaults to `binary`

Example Bash script homieMonitor.sh

homieMonitor.sh

#!/bin/bash

# ##
# Setup HomieMonitor Java executable
# - Ref: https://github.com/skoona/HomieMonitor
#
# ##
#  Description
#  ----------------------------------------------
# RACK_ENV='production'         Use `production` for UI performance, or `development` for debug logging
# HM_MQTT_HOST='<mqtt-server-fqdn-or-ip_address>'
# HM_MQTT_PORT=<mqtt-connection-port>
# HM_MQTT_USER='<mqtt-username>'
# HM_MQTT_PASS='<mqtt-user-password>'
# HM_MQTT_SSL_ENABLE_FLAG defaults to false
# HM_MQTT_SSL_CERT_PATH   defaults are invalid, full-path required if ssl=true
# HM_MQTT_SSL_KEY_PATH    defaults are invalid, full-path required if ssl=true
# HM_BASE_TOPICS='[["sknSensors/#",0],["homie/#",0]]'   base mqtt message name <homie>/<device-id>/<node-id>/...
# HM_MQTT_LOG=`./log/paho-debug.log`        extra mqtt specific logfile, from paho-mqtt-ruby.gem
# HM_FIRMWARE_PATH="$HOME/homieMonitor/content/firmwares/"      Directory to store uploaded homie Firmware
# HM_DATA_STORE="$HOME/homieMonitor/content/db/HomieMonitor_store.yml"  Full path and filename of YAML storage of OTA Subscriptions
# HM_OTA_TYPE='base64strict'          binary, base64strict, base64, RFC4648_pad, RFC4648_no_pad
#                                     - are the choice for OTA transmissions; defaults to `binary`
#
# Special Paths
# 1. with HM_MQTT_SSL_CERT_PATH & HM_MQTT_SSL_KEY_PATH value empty `''`, set HM_MQTT_SSL_ENABLE_FLAG='true'
# 2. if above fails then certs are required.  populate HM_MQTT_SSL_CERT_PATH & HM_MQTT_SSL_KEY_PATH with proper file paths
#
# export RACK_ENV HM_MQTT_HOST HM_MQTT_PORT HM_MQTT_USER HM_MQTT_PASS 
# export HM_OTA_TYPE HM_MQTT_SSL_ENABLE_FLAG HM_MQTT_SSL_CERT_PATH HM_MQTT_SSL_KEY_PATH
# export HM_BASE_TOPICS HM_MQTT_LOG HM_FIRMWARE_PATH HM_DATA_STORE 

# Make runtime dirs
[ -w $HOME/homieMonitor/ ] || {
	echo 'Setting Up HomieMonitor' ;	 
	mkdir -p $HOME/homieMonitor/{content/firmwares,content/spiffs,content/db,bin,log,tmp,tmp/pids} ;
}

# Set Environment Vars
RACK_ENV='production'
HM_MQTT_HOST='mqtt-server-fqdn-or-ip_address'
HM_MQTT_USER='mqtt-username'
HM_MQTT_PASS='mqtt-user-password'

# Export Environment (not required)
export RACK_ENV HM_MQTT_HOST HM_MQTT_USER HM_MQTT_PASS 

# copy homie_monitor-<version>.war to bin directory
# cp -v $HOME/Downloads/homie_monitor-<version>.war $HOME/homieMonitor/bin/

# Java warFile execution
java -Dwarbler.port=8585 -jar $HOME/homieMonitor/bin/homie_monitor_esp-<version>.war

#end

Alternate Builds

Switch Ruby

To use MRI edit .ruby-version and change jruby-9.2.6.0 to ruby-2.6.2, before proceeding.

Docker Compose

To simplify startup instance of the container use Docker Compose.

We provide sample of docker-compose.yml which could be used to start the container with one comand in the same directory where docker-compose.yml is stored:

    $ git clone https://github.com/skoona/HomieMonitor.git
    $ cd HomieMonitor
    
    $ docker-compose up
    -- or --
    $ docker-compose up -d

In the compose file the binding of the Docker volumes is defined to retain the data of the application using Docker Named Volumes.

Docker Container

Primary Docker Container

  $ git clone https://github.com/skoona/HomieMonitor.git
  $ cd HomieMonitor
  
  $ docker build -t homie-monitor .

Run created Container in DEMO mode:

  $ docker run -it -p 8585:8585 --name my-homie-monitor homie-monitor

Run created Container connected to your MQTT-Server:

You have to pass environment variables for MQTT hostname and port within run script; Or using the In-App Settings page.
```
  $ docker run -it -p 8585:8585 -e HM_MQTT_HOST=<hostname|ip> -e HM_MQTT_PORT=<port> --name my-homie-monitor homie-monitor
```

Browse http://<host>:8585/

If you want to retain the data of HomieMonitor you have to bind the volumes of the container to the host using parameter on docker run. E.g.:

  $ docker run -it -p 8585:8585 --mount type=volume,source=homieMonitor-store,target=/homieMonitor/content --mount type=volume,source=homieMonitor-configs,target=/homieMonitor/config --mount type=volume,source=homieMonitor-logs,target=/homieMonitor/logs --name my-homie-monitor homie-monitor

Contributors

Docker configuration contributed by Stephan Strittmatter @stritti on DockerHub, Gitter.
Qos = 0 configuration value contributed by Marcus Klein @kleini on Gitter.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Find me on Gitter!

License

The application is available as open source under the terms of the MIT License.