Fork me on GitHub

pimatic-shell-execute by Oliver Schneider (sweetpi) | github | npm

pimatic shell execute plugin

This plugin let you define devices that execute shell commands. Additionally, it allows you to execute shell commands in rule actions. So you can define rules of the form:

if ... then execute "some command"

Configuration

You can load the plugin by editing your config.json to include:

{ 
   "plugin": "shell-execute"
}

Commands are executed parallel by default. With the optional boolean attribute sequentialset to trueshell commands are executed sequentially.

{ 
   "plugin": "shell-execute",
   "sequential": true
}

Optionally, it is also possible to define the shell to be used to execute commands. By default, '/bin/sh' is used on UNIX, and 'cmd.exe' on Windows. It is also possible to set the current working directory (cwd). By default, the current working directory of pimatic is used.

{ 
   "plugin": "shell-execute",
   "shell": "/bin/bash",
   "cwd": "/home/pi/scripts"
}

ShellSwitch Device

Devices can be defined by adding them to the devices section in the config file. Set the class attribute to ShellSwitch. For example:

{ 
  "id": "light",
  "name": "Lamp",
  "class": "ShellSwitch", 
  "onCommand": "echo on > /home/pi/switchState",
  "offCommand": "echo off > /home/pi/switchState",
  "getStateCommand": "echo /home/pi/switchState",
  "interval": 10000,
  "forceExecution": false
}

If the getStateCommand option is set and the interval option is set to a value greater than 0, the getStateCommand is executed in this ms interval to update the state of the switch.

ShellSensor Device

You can define a sensor device with an attribute which gets updated with the output of shell command:

{ 
  "id": "temperature",
  "name": "Room Temperature",
  "class": "ShellSensor", 
  "attributeName": "temperature",
  "attributeType": "number",
  "attributeUnit": "°C",
  "attributeAcronym": "Room",
  "command": "echo 42.0"
}

If you're running pimatic on a RaspberryPi, you can use the following sensors for a quick overview of your system health:

{
  "id": "wlan-strength",
  "name": "WLAN Strength",
  "class": "ShellSensor",
  "attributeName": "wlan-strength",
  "attributeType": "number",
  "attributeUnit": "%",
  "command": "iwconfig wlan0 | grep Signal | sed -n -e 's/^.*Signal level.\\([0-9]*\\).*/\\1/gp'",
  "interval": 15000
},
{
  "id": "mem-usage",
  "name": "Memory Usage",
  "class": "ShellSensor",
  "attributeName": "mem-usage",
  "attributeType": "number",
  "attributeUnit": "MB",
  "command": "free -m | awk '$5 ~ /[0-9.]+/ { print $3 }'",
  "interval": 60000
},
{
  "id": "disk-usage",
  "name": "Disk Usage",
  "class": "ShellSensor",
  "attributeName": "disk-usage",
  "attributeType": "number",
  "attributeUnit": "%",
  "command": "df | awk '/^\\/dev\\/root/ { printf \"%.1f\", ($3/$2)*100 }'",
  "interval": 300000
},
{
  "id": "cpu-temp",
  "name": "CPU Temperature",
  "class": "ShellSensor",
  "attributeName": "cpu-temp",
  "attributeType": "number",
  "attributeUnit": "°C",
  "command": "/opt/vc/bin/vcgencmd measure_temp | cut -d \"=\" -f2 | cut -d \"'\" -f1",
  "interval": 60000
}

ShellButtons Device

You can define a button device with buttons that trigger individual shell commands, eliminating the need for individual rules:

{ 
  "id": "tv-remote",
  "name": "TV Remote",
  "class": "ShellButtons",
  "buttons": [
    {
      "id": "tv-power",
      "text": "PWR",
      "onPress": "irsend SEND_ONCE tvset KEY_POWER",
      "confirm": true
    }
  ]
}

The given example shows the possibility to create an infrared remote in the pimatic frontend using lirc. The onPress command can be any bash command or file you may want to execute.

ShellPresenceSensor Device

You can define a presence sensor whose state gets updated with the output of shell command. In some use cases the shell command may only detect an external device triggered a "present" event, but cannot detect its absence. In such cases, when theShellPresenceSensor is "present" it needs to be automatically reset to "absent" after some time. For this you can set to autoReset property to true:

{
  "id": "presence",
  "name": "NGINX Server",
  "class": "ShellPresenceSensor",
  "command": "pgrep nginx >/dev/null && echo 1 || echo 0",
  "autoReset": false,
  "resetTime": 10000
}

For device configuration options see the device-config-schema file.

Plugin Config Options

shell execute config options
OptionDescriptionDefault
sequential
boolean
Run all shell commands sequential (not in parallel). Enable this if you have commands that should not be execute in parallel
false
shell
string
Shell to execute a command with. Default: '/bin/sh' on UNIX, 'cmd.exe' on Windows
cwd
string
Current working directory of the child process

Device Config Options

pimatic-shell-execute device config schemas

ShellSwitch

ShellSwitch config options
OptionDescriptionDefault
onCommand
string
the command to execute for switching on
offCommand
string
the command to execute for switching off
getStateCommand
string
the command to execute to get current state. Can return on/off, true/false or 1/0 as string
interval
integer
the time in ms, the command gets executed to get the actual state. If 0 then the state will not updated automatically.
0
forceExecution
boolean
always execute command even if switch already is set to the requested state
false

ShellButtons

ShellButtons config options
OptionDescriptionDefault
buttons
array of objects
Buttons and their actions once they are pressed
[]
Elements

ShellSensor

ShellSensor config options
OptionDescriptionDefault
attributeName
string
the name of the attribute the sensor is monitoring
attributeType
string
the type of the attribute the sensor is monitoring
"string"
attributeUnit
string
this unit of the attribute the sensor is monitoring
""
attributeAcronym
string
this acronym of the attribute the sensor is monitoring
""
discrete
boolean
Should be set to true if the value does not change continuously over time.
command
string
the command to execute and read the attribute value from stdout
"echo value"
interval
integer
the time in ms, the command gets executed to get a new sensor value
5000

ShellPresenceSensor

ShellPresenceSensor config options
OptionDescriptionDefault
command
string
the command to execute to get the presence state. Can return on/off, true/false or 1/0 as string
"echo false"
interval
integer
the time in ms, the command gets executed to get the actual state. If 0 then the state will not updated automatically.
0
autoReset
boolean
if true and the the device is present, reset the state to absent after resetTime has been reached.
false
resetTime
integer
Time in milliseconds after that the presence value is reset to absent.
10000

ShellShutterController

ShellShutterController config options
OptionDescriptionDefault
upCommand
string
the command to execute to move the shutter up
downCommand
string
the command to execute to move the shutter down
stopCommand
string
the command to execute to stop the shutter
getPositionCommand
string
the command to execute to get current position. Can return up/on, down/off or stopped/stop as string
interval
integer
the time in ms, the command gets executed to get the actual state. If 0 then the state will not updated automatically.
0
pimatic-shell-execute is written by Oliver Schneider (sweetpi)