I use sitemaps because I find them to be the best way to interact with OpenHAB using my mobile devices. However, one thing that has always bothered me about Sitemaps is that they were really anti-DRY and were not dynamic.
I have just converted my sitemap to dynamic sitemap using the Jruby Openhab Rules System.
Ruby has a built in templating engine called ERB - which stands for embedded ruby, it is similar to Jinga2 in Python - but in my opinion more powerful because you have access to the full Ruby language within your templates.
I have recently been working on my whole home audio system - which was my breaking point with static sitemaps.
I had this:
Frame label="Music" {
Switch item=Nuvo_Z7_Power icon="player"
Selection item=Nuvo_Z7_Source visibility=[Nuvo_Z7_Power==ON] icon="player"
//Volume can be a Setpoint also
// Nuvo Controls
Slider item=Nuvo_Z7_Volume minValue=0 maxValue=100 step=1 visibility=[Nuvo_Z7_Power==ON] icon="soundvolume"
Switch item=Nuvo_Z7_Mute visibility=[Nuvo_Z7_Power==ON] icon="soundvolume_mute"
Default item=Nuvo_Z7_Control icon="player" visibility=[Nuvo_Z7_Source=="1", Nuvo_Z7_Source=="2", Nuvo_Z7_Source=="3", Nuvo_Z7_Source=="4"]
Text item=Nuvo_S5_Display_Line2 visibility=[Nuvo_Z7_Source=="1"] icon="zoom"
Text item=Nuvo_S5_Display_Line3 visibility=[Nuvo_Z7_Source=="1"] icon="zoom"
Text item=Nuvo_S5_Display_Line4 visibility=[Nuvo_Z7_Source=="1"] icon="zoom"
Text item=Nuvo_S5_Play_Mode visibility=[Nuvo_Z7_Source=="1"] icon="player"
// Spotify Controls (Chromecast)
Default item=SpotifyTrackPlayer icon="player" visibility=[Nuvo_Z7_Source=="5"]
Selection item=SpotifyPlaylists label="Playlist" icon="music" visibility=[Nuvo_Z7_Source=="5"]
Switch item=SpotifyDeviceShuffle label="Shuffle mode:" visibility=[Nuvo_Z7_Source=="5"]
Text item=ChromecastStatusArtist visibility=[Nuvo_Z7_Source=="5"] icon="zoom"
Text item=ChromecastStatusTitle visibility=[Nuvo_Z7_Source=="5"] icon="zoom"
Text item=ChromecastStatusAlbum visibility=[Nuvo_Z7_Source=="5"] icon="zoom"
Text item=SpotifyDurationProgress visibility=[Nuvo_Z7_Source=="5"] icon="progress_clock"
Image item=ChromecastStatusImage visibility=[Nuvo_Z7_Source=="5"] icon="none"
// SqueezeBox Controls
Default item=Squeeze_Home_Audio_A_Player icon="player" visibility=[Nuvo_Z7_Source=="6"]
Switch item=Squeeze_Home_Audio_A_Shuffle label="Shuffle []" icon="shuffle" mappings=[0=Off, 1=Songs, 2=Albums] visibility=[Nuvo_Z7_Source=="6"]
Selection item=Squeeze_Home_Audio_A_Favorites label="Playlist" icon="music" visibility=[Nuvo_Z7_Source=="6"]
Text item=Squeeze_Home_Audio_A_Track_Progress visibility=[Nuvo_Z7_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Artist visibility=[Nuvo_Z7_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Title visibility=[Nuvo_Z7_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Album visibility=[Nuvo_Z7_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Duration_Progress visibility=[Nuvo_Z7_Source=="6"] icon="progress_clock"
Image item=Squeeze_Home_Audio_A_Cover visibility=[Nuvo_Z7_Source=="6"] icon="none"
}
I had to repeat that for every room that has audio in the house with one minor change, replacing âZ7â everywhere with whatever zone it was. That is 33 times I had to change it for each zone. Also, the way I organize my sitemaps is by room and by control area (audio, lighting), so this was again duplicated twice for every zone.
Then if I wanted to make a change or made a mistake, I was updating this thing all over the sitemap.
Here is what it looks like now:
Frame label="Music" {
<%= render('music', zone: 7) %>
}
And for the kitchen:
Frame label="Music" {
<%= render('music', zone: 1) %>
}
So how does this work and what does it look like:
First I have a Jruby rules file:
require 'openhab'
require 'erb'
SITEMAP_DIR = __conf__/'sitemaps/'
# Render a template
# @param source template file in sitemap dir without the .erb extension
# @param variables optional list of bindings for template, if supplied template will not have access to openhab variables
def render(source, **variables)
template = ERB.new(File.read(File.join(SITEMAP_DIR, "#{source}.erb")), trim_mode: '-')
variables ? template.result_with_hash(variables) : template.result
end
# Format the sitemap
# by stripping the whitespace and properly indentint
def format(sitemap)
level = 0
sitemap.lines
.map {|line| line.strip}
.map do |line|
level-= line.count '}'
indent = ' ' * level
level+= line.count '{'
indent + line
end
.join("\n")
end
# Render the sitemap
def sitemap
sitemap = 'home.sitemap'
File.write(File.join(SITEMAP_DIR, sitemap), format(render(sitemap)))
logger.info "Rendered #{sitemap}"
end
rule 'Render Sitemap' do
on_start
watch SITEMAP_DIR/'home.sitemap.erb'
run { sitemap }
end
At a high level it has a rule with a trigger on startup that renders the sitemap and another trigger that fires whenever the template file changes.
The interesting methods are sitemap and render.
sitemap writes a new âhome.sitemapâ from the template âhome.sitemap.erbâ by calling the render method.
The render method is where the magic happens, the method takes the name of a template (without the .erb extension) and invokes the built in template engine and then returns the result. Here is the neat thing, during the templating process the template has full access to all openhab items, groups, etc.
One downside of the templating engine is that it doesnât maintain indentation. So I created the format method which just stripes all whitespace then indents the rendered sitemap based on curly brackets.
If you remember, in my example above my sitemap template just had:
Frame label="Music" {
<%= render('music', zone: 7) %>
}
So how is that working in the template? I mention that the template has access to all openhab items, groups, etc ? It also has access to all methods defined in the rules file, so it is just calling the render method defined above which looks for a template file named âmusicâ and passes in an optional variable of âzone is 7â. In Ruby this is called partial templates, where a template can include and render another template inside it self. This lets you decompose your sitemap/templates.
This is what music.erb looks like:
<%=%Q(Switch item=Nuvo_Z#{zone}_Power icon="player"
Selection item=Nuvo_Z#{zone}_Source visibility=[Nuvo_Z#{zone}_Power==ON] icon="player"
// Nuvo Controls
Setpoint item=Nuvo_Z#{zone}_Volume minValue=0 maxValue=100 step=1 visibility=[Nuvo_Z#{zone}_Power==ON] icon="soundvolume"
Switch item=Nuvo_Z#{zone}_Mute visibility=[Nuvo_Z#{zone}_Power==ON] icon="soundvolume_mute"
Default item=Nuvo_Z#{zone}_Control icon="player" visibility=[Nuvo_Z#{zone}_Source=="1", Nuvo_Z#{zone}_Source=="2", Nuvo_Z#{zone}_Source=="3", Nuvo_Z#{zone}_Source=="4"]
Text item=Nuvo_S5_Display_Line2 visibility=[Nuvo_Z#{zone}_Source=="1"] icon="zoom"
Text item=Nuvo_S5_Display_Line3 visibility=[Nuvo_Z#{zone}_Source=="1"] icon="zoom"
Text item=Nuvo_S5_Display_Line4 visibility=[Nuvo_Z#{zone}_Source=="1"] icon="zoom"
Text item=Nuvo_S5_Play_Mode visibility=[Nuvo_Z#{zone}_Source=="1"] icon="player"
// Spotify Controls (Chromecast)
Default item=SpotifyTrackPlayer icon="player" visibility=[Nuvo_Z#{zone}_Source=="5"]
Selection item=SpotifyPlaylists label="Playlist" icon="music" visibility=[Nuvo_Z#{zone}_Source=="5"]
Switch item=SpotifyDeviceShuffle label="Shuffle mode:" visibility=[Nuvo_Z#{zone}_Source=="5"]
Text item=ChromecastStatusArtist visibility=[Nuvo_Z#{zone}_Source=="5"] icon="zoom"
Text item=ChromecastStatusTitle visibility=[Nuvo_Z#{zone}_Source=="5"] icon="zoom"
Text item=ChromecastStatusAlbum visibility=[Nuvo_Z#{zone}_Source=="5"] icon="zoom"
Text item=SpotifyDurationProgress visibility=[Nuvo_Z#{zone}_Source=="5"] icon="progress_clock"
Image item=ChromecastStatusImage visibility=[Nuvo_Z#{zone}_Source=="5"] icon="none"
// SqueezeBox Controls
Default item=Squeeze_Home_Audio_A_Player icon="player" visibility=[Nuvo_Z#{zone}_Source=="6"]
Switch item=Squeeze_Home_Audio_A_Shuffle label="Shuffle []" icon="shuffle" mappings=[0=Off, 1=Songs, 2=Albums] visibility=[Nuvo_Z#{zone}_Source=="6"]
Selection item=Squeeze_Home_Audio_A_Favorites label="Playlist" icon="music" visibility=[Nuvo_Z#{zone}_Source=="6"]
Text item=Squeeze_Home_Audio_A_Track_Progress visibility=[Nuvo_Z#{zone}_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Artist visibility=[Nuvo_Z#{zone}_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Title visibility=[Nuvo_Z#{zone}_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Album visibility=[Nuvo_Z#{zone}_Source=="6"] icon="zoom"
Text item=Squeeze_Home_Audio_A_Duration_Progress visibility=[Nuvo_Z#{zone}_Source=="6"] icon="progress_clock"
Image item=Squeeze_Home_Audio_A_Cover visibility=[Nuvo_Z#{zone}_Source=="6"] icon="none")%>
Which is essentially what we had before except:
The <%= which have seen above is the ERB syntax for replace this the result of the code in this block
the %Q tells Ruby to interpolate the multi-line string that follows and the â#{zone]â is where ruby inserts the zone number passed above as the variable.
As I mentioned above, I have my sitemap setup by room and by control area. Which means I have a control area called âAudioâ that contains all my zones.
There are are two ways I could do that, I could do:
Frame label="Office" {
<%= render('music', zone: 7) %>
}
Frame label="Kitchen" {
<%= render('music', zone: 1) %>
}
etc
However, since you can execute arbitrary ruby in the templates, I did this:
<% ['Kitchen', "Anna's Office", 'Family Room',
'Primary Bathroom', 'Primary Bedroom', 'Covered Deck', 'Office'
].each.with_index(1) do |room, zone| %>
<%= %(Frame label="#{room}" { ) %>
<%= render('music', zone: zone) %>
<%= "}" %>
<% end %>
When using ERB, the thing to remember is that <% just executes code and <%= replaces what is there with the result of that code. That is why the loop controls and end donât have the â=â
