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

```bash #!/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='' # HM_MQTT_PORT= # HM_MQTT_USER='' # HM_MQTT_PASS='' # 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 ///... # 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-.war to bin directory # cp -v $HOME/Downloads/homie_monitor-.war $HOME/homieMonitor/bin/ # Java warFile execution java -Dwarbler.port=8585 -jar $HOME/homieMonitor/bin/homie_monitor_esp-.war #end ``` </p> </details> ## 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](https://docs.docker.com/compose/). We provide sample of [docker-compose.yml](/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](https://cloud.docker.com/repository/registry-1.docker.io/skoona/homie-monitor) $ 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= --name my-homie-monitor homie-monitor * Browse `http://: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 1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create a new Pull Request Find me on Gitter! ## License The application is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

HomieMonitor

Monitor for IOT devices which implement the excellent Homie Convention.

HomieMonitor

References:

Screenshots

Features

Configuration and Demonstration Mode

Installation

(a) Ruby/JRuby

(b) Java HomieMonitor warFile and script

Configuration Environment Vars

Example Bash script homieMonitor.sh