This page is part of archived documentation for openHAB 3.3. Go to the current stable version
# JRuby Scripting
This add-on provides JRuby (opens new window) scripting language for automation rules.
# JRuby Scripting Configuration
After installing this add-on, you will find configuration options in the openHAB portal under Settings -> Other Services -> JRuby Scripting.
Alternatively, JRuby configuration parameters may be set by creating a jruby.cfg
file in conf/services/
Parameter | Default | Description |
---|---|---|
org.openhab.automation.jrubyscripting:gem_home | $OPENHAB_CONF/scripts/lib/ruby/gem_home | Location ruby gems will be installed and loaded, directory will be created if missing and gem installs are specified |
org.openhab.automation.jrubyscripting:rubylib | $OPENHAB_CONF/automation/lib/ruby/ | Search path for user libraries. Separate each path with a colon (semicolon in Windows). |
org.openhab.automation.jrubyscripting:local_context | singlethread | The local context holds Ruby runtime, name-value pairs for sharing variables between Java and Ruby. See this (opens new window) for options and details |
org.openhab.automation.jrubyscripting:local_variables | transient | Defines how variables are shared between Ruby and Java. See this (opens new window) for options and details |
org.openhab.automation.jrubyscripting:gems | A comma separated list of Ruby Gems (opens new window) to install. | |
org.openhab.automation.jrubyscripting:require | A comma separated list of script names to be required by the JRuby Scripting Engine at the beginning of user scripts. |
# Ruby Gems
This automation add-on will install user specified gems and make them available on the library search path. Gem versions may be specified using the standard ruby gem_name=version format. The version number follows the pessimistic version constraint (opens new window) syntax.
For example this configuration will install the latest version of the openHAB JRuby Scripting Library (opens new window), and instruct the scripting engine to automatically insert require 'openhab'
at the start of the script.
org.openhab.automation.jrubyscripting:gems=openhab-scripting
org.openhab.automation.jrubyscripting:require=openhab
# Creating JRuby Scripts
When this add-on is installed, you can select JRuby as a scripting language when creating a script action within the rule editor of the UI.
Alternatively, you can create scripts in the automation/jsr223/ruby/personal
configuration directory.
If you create an empty file called test.rb
, you will see a log line with information similar to:
... [INFO ] [.a.m.s.r.i.l.ScriptFileWatcher:150 ] - Loading script 'test.rb'
To enable debug logging, use the console logging commands to enable debug logging for the automation functionality:
log:set DEBUG org.openhab.core.automation
log:set DEBUG org.openhab.automation.jrubyscripting
# Imports
All ScriptExtensions are available in JRuby with the following exceptions/modifications:
- The
File
variable, referencingjava.io.File
is not available as it conflicts with Ruby's File class preventing Ruby from initializing - Globals
scriptExtension
,automationManager
,ruleRegistry
,items
,voice
,rules
,things
,events
,itemRegistry
,ir
,actions
,se
,audio
,lifecycleTracker
are prepended with a$
(e.g.$automationManager
) making them available as global objects in Ruby.
# Script Examples
JRuby scripts provide access to almost all the functionality in an openHAB runtime environment.
As a simple example, the following script logs "Hello, World!".
Note that puts
will usually not work since the output has no terminal to display the text.
The openHAB server uses the SLF4J (opens new window) library for logging.
require 'java'
java_import org.slf4j.LoggerFactory
LoggerFactory.getLogger("org.openhab.automation.examples").info("Hello world!")
JRuby can import Java classes (opens new window).
Depending on the openHAB logging configuration, you may need to prefix logger names with org.openhab.automation
for them to show up in the log file (or you modify the logging configuration).
Note: Installing the JRuby Scripting Library (opens new window) will provide enhanced capabilities with simpler rule syntax.