check_shelly (Shelly IOT devices monitoring plugin)

Last update: February 16, 2022

Monitoring Plugin check_shelly

This is a monitoring plugin to check power relay / power meter devices from Shelly. The checks show device information (such as firmware version) and show performance statistics for several sensors (power meter, temperature) which can be used to create graphs.
This plugin was developed for a Shelly Pro 4 PM device, which is a 2nd generation Shelly device. Other 2nd generation Shelly devices should therefore be compatible.

Commercial support

If you are looking for commercial support for this monitoring plugin, need customized modifications or in general customized monitoring plugins, contact us at Infiniroot.com.

Download

Download check_shelly.py

check_shelly.py

294 downloads so far...

Download plugin and save it in your Nagios/Monitoring plugin folder (usually /usr/lib/nagios/plugins, depending on your distribution). Afterwards adjust the permissions (usually chmod 755).

Community contributions welcome on GitHub repository.

Version history / Changelog

20220214-16: Development on Shelly Pro 4 PM (2nd Gen device)
20220216 0.1: Code published in public repository

Requirements

  • Python: python3
  • Python modules: requests (sudo pip3 install requests)

Definition of the parameters

Parameter short Parameter long Description
-H * --host * Hostname or ip address of Shelly device
-a --auth Toggle this if your Shelly device requires authentication
-u --user Username if authentication is required (Shelly username is actually always admin)
-p --password Password if authentication is required
-t * --type * Type of check to run (see definition of the check types below)
-m + --model + Hardware model of Shelly device (defaults to Pro4PM)
-s --switch Select the switch id of this Shelly device (e.g. switch_0 would be 0, defaults to 0)
N/A --ignore-restart Do not warn when Shelly device requires a restart
-h --help Help!

* mandatory parameter

+ reserved for future use (not used yet)

Definition of the check types

Type Description
info Show device information (model, generation, firmware, ...)
system Check device's system (file system, memory, firmware) and health. Performance data for system statistics.
meter Shows statistics (power usage) from relay switch (defaults to switch_0, change with -s parameter). Performance data for several statistics.

Usage / running the plugin on the command line

Usage:

./check_shelly.py [-h] -H HOST [-a] [-u USER] [-p PASSWORD] -t {info,system,meter} [-m SHELLY_MODEL] [-s SHELLY_SWITCH] [--ignore-restart]

Example: Info check. The Shelly device's information is retrieved and shown.

./check_shelly.py -H IPofShelly -t info
SHELLY OK: Device Pro4PM (Model: SPSW-004PE16EU, Generation: 2, Firmware: 0.9.3) is running - Authentication is enabled

Example: Authentication is required. When authentication is enabled on the Shelly device, the plugin will notify:

./check_shelly.py -H IPofShelly -t system
SHELLY WARNING: unable to authenticate (Shelly requires authentication)

Example: System check. Check the system health of the Shelly device using authentication. If the device requires a restart, a warning is shown:

./check_shelly.py -H IPofShelly -t system -a -p secret
SHELLY WARNING: Device (shellypro4pm-XXXXXXXXXXXX) requires a restart |uptime=154966 memory=110472B;;;0;234888 disk=229376B;;;0;524288

Example: Ignore restart required. The previous alert (Device requires restart) can be ignored with an additional parameter:

./check_shelly.py -H IPofShelly -t system -a -p secret --ignore-restart
SHELLY OK: Device (shellypro4pm-XXXXXXXXXXXX), uptime 155265 |uptime=155265 memory=110480B;;;0;234924 disk=229376B;;;0;524288

Example: Power Meter check. Show power statistics from the device's relay switches. Defaults to Switch_0 if there are multiple switches:

./check_shelly.py -H IPofShelly -t meter -a -p secret
SHELLY OK: Device (shellypro4pm-XXXXXXXXXX) SWITCH_0, currently using 479 Watt / 2 Amp |power=479 current=2 total_power=11155.536 temp=51.3

Example: Power Meter check on different switch ID. Show power statistics from the device's Switch_1:

./check_shelly.py -H IPofShelly -t meter -a -p secret -s 1
SHELLY OK: Device (shellypro4pm-XXXXXXXXXXXX) SWITCH_1, currently using 0 Watt / 0 Amp |power=0 current=0 total_power=0.000 temp=51.0

Command definition

Command definition in Nagios, Icinga 1.x, Shinken, Naemon

The following command definition allows optional parameters all defined within ARG4.

# 'check_shelly' command definition
define command{
  command_name check_shelly
  command_line $USER1$/check_shelly.py -H $HOSTADDRESS$ -t $ARG1$ $ARG2$
}

Command definition in Icinga 2.x

object CheckCommand "check_shelly" {
  import "plugin-check-command"
  command = [ PluginContribDir + "/check_shelly.py" ]
  arguments = {
    "-H" = {
        value = "$shelly_address$"
        description = "Hostname or IP Address of Shelly device"
        required = true
    }
    "-a" = {
        set_if = "$shelly_authentication$"
        description = "Use authentication (requires password)"
    }
    "-u" = {
        value = "$shelly_user$"
        description = "Username if authentication is required (default: admin)"
    }
    "-p" = {
        value = "$shelly_password$"
        description = "Password if authentication is required"
    }
    "-t" = {
        value = "$shelly_checktype$"
        description = "Define what you want to check"
        required = true
    }
    "-m" = {
        value = "$shelly_model$"
        description = "Hardware model of Shelly device (defaults to Pro4PM) - not used yet"
    }
    "-s" = {
        value = "$shelly_switch$"
        description = "Define which Shelly switch ID should be monitored using the 'meter' check type (default: 0)"
    }
    "--ignore-restart" = {
        set_if = "$shelly_ignore_restart$"
        description = "Do not warn when Shelly device requires a restart"
    }
  }
  vars.shelly_address = "$address$"
  vars.shelly_user = "admin"
  vars.shelly_switch = "0"
}

Service definition

Service definition in Nagios, Icinga 1.x, Shinken, Naemon

# Check Shelly Information
define service{
  use generic-service
  host_name shelly1
  service_description Shelly Info
  check_command check_shelly!info
}

# Check Shelly System
define service{
  use generic-service
  host_name shelly1
  service_description Shelly System
  check_command check_shelly!system!-a -p secret
}

# Check Shelly Meter Switch_0
define service{
  use generic-service
  host_name shelly1
  service_description Shelly Switch_0
  check_command check_shelly!meter!-a -p secret -s 0
}

# Check Shelly Meter Switch_1
define service{
  use generic-service
  host_name shelly1
  service_description Shelly Switch_1
  check_command check_shelly!meter!-a -p secret -s 1
}

Service object definition Icinga 2.x

# Check Shelly Info
object Service "Shelly Info" {
  import "generic-service"
  host_name = "shelly1"
  check_command = "check_shelly"
  vars.shelly_checktype = "info"
}

# Check Shelly System
object Service "Shelly System" {
  import "generic-service"
  host_name = "shelly1"
  check_command = "check_shelly"
  vars.shelly_checktype = "system"
  vars.shelly_password = "secret"
  vars.shelly_authentication = true
}

# Check Shelly Switch_0 Meter
object Service "Shelly Switch_0 Meter" {
  import "generic-service"
  host_name = "shelly1"
  check_command = "check_shelly"
  vars.shelly_checktype = "meter"
  vars.shelly_password = "secret"
  vars.shelly_authentication = true
  vars.shelly_switch = "0"
}

# Check Shelly Switch_1 Meter
object Service "Shelly Switch_1 Meter" {
  import "generic-service"
  host_name = "shelly1"
  check_command = "check_shelly"
  vars.shelly_checktype = "meter"
  vars.shelly_password = "secret"
  vars.shelly_authentication = true
  vars.shelly_switch = "1"
}

Screenshots

check_shelly Shelly IOT device in Icinga 2 monitoring
check_shelly Shelly Power Usage (Watt) Graph
check_shelly Shelly Current Usage (Amp) Graph
check_shelly Shelly System Memory Usage Graph
check_shelly Shelly Temperature Graph