Getting Started: What components are involved?

Plugins & Plugin Development openHAB MiOS Binding
#1

So I’ve been following along this thread for quite some time and really love what I’m seeing. After waiting a bit, I am to the point where I’d like to jump in and try this.

However, combing through this whole thread seems difficult at best, especially as there have been lots of changes since it all started.

Is there any place to get a good start? I was going to just grab OH and install it, but when I read about the MIOS bindings, I get the impression (and that is the key word) that any such bindings I find in any standard places are out of date and that there are different places you need to go to either get newer bindings and/or newer OH + MIOS downloads.

I suspect I’m not the only one interested as the OH momentum seems to keep building.

Is there a place that ties all the “most current” parts you need for OH+MIOS together? Ideally, along with current recommended best practices (setting up MIOS, what files need to be configured, what backing stores, if any, are best, caveats, etc)?

Just a ‘quick & dirty’ bootstrap reference (a paragraph and a few links – given to point the direction, googling and reading things over should fill in the rest).

Anything like this would be very much appreciated!

Gerry

#2

I suggest you start here:

  • Garrett
#3

Thanks Garret! I had been reading those over in the recent past and they are pretty helpful.

I just felt there were differences in what I was reading there and here (some of that was about 6+ weeks ago, and things here get superseded with later posts too).

I think one thing that was leaving me uncertain was where to get the most current MIOS binding for OH. I’ve seen mention what appear to be several discrete download sites listed outside of the “normal” channels over the life of this thread and knowing the binding was going through it’s growth period, expected there was likely a “more current than standard” version available.

Gerry

#4

Hey Gerry,
I put a request into Marc and Florin to promote 7 different Plugin threads to have their own sub-forum, since they’ve all reached their 400-post requirement.

The openHAB - MiOS Binding was in that list, but I only submitted the request to promote on Thursday. Once executed, it’ll be possible to structure this a little more.

From an openHAB standpoint, when you install it you only get a core set of “Bindings” installed by default. This list is [deliberately] tiny, and things like the MiOS Binding need to be added afterwards anyhow, so go ahead and get the “Runtime core” of openHAB installed and running.

This provides a reasonable set of instructions for that:

http://www.openhab.org/gettingstarted.html

NOTE: I only configure by command-line/text-file so I don’t have the Designer components installed. I used to have the Demo component installed, and that was handy to keep around in order to see the syntax in the various files (although, that syntax is online also)

Once you have the basics up and running, you can then install the Addons for MiOS:

[ul][li]MiOS Bridge Binding (required) - Download[/li]
[li]MiOS Action Binding (optional) - Download[/li][/ul]

These are the latest versions, and contain everything in my “build” environment, but not yet approved for the openHAB release environment. They’ll work in any recent version of openHAB, they were built against a 1.6.x env.

NOTE: There’s a README.md file in openHAB for the MiOS Binding. The version that @garrettwp pointed to is the latest-released-version. There are others, but they’re in varying states of flux:

[ul][li]Release (stable), Downloads, MiOS Bridge Binding Documentation[/li]
[li]Nightly (in-progress), Downloads, Documentation[/li]
[li]Untested (off-the-presses) - GitHub - mrguessed/openhab: Source code of the open Home Automation Bus (openHAB) (dig around, I work in a branch, not “master”)[/li][/ul]

There’s a lot more, but this will get you started (as well as provide me a template for the first sticky post once we get broken out in the forum)

#5

Couple of questions:

  1. The download links are for 1.7 version. I’m assuming that will only work if you are also running the 1.7 OH and not the 1.6 OH?

  2. If so, are there enough changes to the MIOS 1.7 bindings that it’s worth starting there (1.7 vs 1.6)?

  3. What is the difference between the mios binding and the mios action? What do you gain/lose from installing or not installing the actions (as they are labeled as optional)?

  4. There appear to be a number of files that you have to download from the git repositiory and install in addition to the .jar
    a) Is it only the transformations or are there other files too that should be downloaded?
    b) Is there a way the build process could bundle those files into a .tgz or .zip so end users had only one additional download?

I suspect #3 might be more obvious once I’m more familiar with OH overall, but figured it couldn’t hurt to ask.

Thanks!

Gerry

#6

He Gerry,
The 1.7 versions of the MiOS Bridge Bundle file(s) will work fine against the 1.6.x versions of openHAB. It’s just a build labeling process, and 1.6/1.7 openHAB Runtime core is mostly just bug fixes so either can be used there also (I run a prerelease of 1.6.0 openHAB Runtime core)

The 1.7 MiOS Bridge Bundle files contain a number of significant improvements that are well worth picking up. They are going to be pulled back into a 1.6.2 OpenHAB Runtime core patch release, but that’s not GA yet.

Also, the MiOS Action binding (for writing complex openHAB Rules) will only be available in the 1.7.0 code line, but most people won’t need that, as its really needed for complex rules. If you’re not writing complex rules, then you can leave out the MiOS Action bundle… It can always be added later.

I’ll see if I can make a build target the bundles/zips the MiOS Transform files. Thiese files are required to be separately installed because the openHAB 1.x Runtime core doesn’t support having these load as Bundle-specific resources.

#7

Thanks so much! I seriously appreciate all this!

When I download the transformations – is there a better place than the master branch of the MiOS binding on github? In short, do I need a more current set of transformations than the ones under 1.6 on github for the 1.7 snapshot binding you included a link for?

Thanks!!

Gerry

#8

No new Transforms yet, so 1.6 or 1.7 will be the same.

I’m waiting for more feedback before adding additional ones (based upon need) but they can always be added manually also.

#9

Hopefully running out of questions. I have OH and the MiOS bindings running, but I’m not clear about the item definitions. Do I have to create them for all the devices I have or does the binding create them automatically?

Reading the wiki, I can’t quite tell if the part on items is for custom stuff or meant for absolutely every/any vera device (dimmer/.switch/thermostat/lock) you want to talk to.

Thanks!!
Gerry

#10

You need to manually populate the items config with the devices you want to show up or control in vera. They will not be automatically generated.

  • Garrett
#11

Thanks – i sort of feared that (over 100 devices to create). That said, the code at the MCV wiki on OH actually was a good starting place: [url=http://wiki.micasaverde.com/index.php/OpenHAB]http://wiki.micasaverde.com/index.php/OpenHAB[/url]

Instead of trying to mount a remote partition (per the wiki), I just redirected output to the /tmp/log/cmh space and dumped it, the xfered it over. I’ll have too hand tailor things, but it’s a great start!

Gerry

#12

OpenHAB does require some setting up, but once you have it going, it offers a lot of potential.

  • Garrett
#13

After getting the basics up and running, I figured I’d post my “quick” boostrap summary:

Fair Warning: It assumes your running under linux, are familiar with basic command line tools and editing text files without a GUI.

Quick Terms:

  • $OH - directory you install OpenHAB into
  • Binding - effectively a ‘driver’ or connector between OH and some device(s)
  • Items - discrete parts of each device (i.e temperature, dim level of a light, etc). Items have to be manually defined to connect a name with a binding.
  • Transformations - Translators between OH values/terms and MiOS values/terms.
  • Sitemap - a ‘template’ (sort of) that defines how your Items appear on a web page

Quick Start Steps:

[ol][li]If you haven’t already, insure your Vera has a fixed IP address and know it[/li]
[li]Install Java JDK (not just the runtime, but full SDK/JDK) 1.7 or higher[/li]
[li]Go to [url=http://www.openhab.org/downloads.html]http://www.openhab.org/downloads.html[/url] and download the Runtime core, Add Ons and Demo kit. For the moment, skip the designer[/li]
[li]Pick a clean directory for OpenHAB (OH) and unzip the core. We’ll call this $OH[/li]
[li]In a completely different directory (!), unzip the addons and demo zip files. Addons is optional bindings and demo is example items/sitemaps you may wish to look at, compare or use as reference.[/li]
[li]From your “completely different” directory, copy the files org.openhab..mios.jar into your $OH/addons[/li]
[li]Resist the urge to install other add-ons yet. You can do it later. Keep it Simple.[/li]
[li]Edit $OH/configurations/openhab.cfg. Go to the bottom of the file and append this line [tt]mios:house.host=192.168.1.99[/tt] Change the IP address (192.168.1.99 here) to that of your Vera. If you have multiple Veras, just set one up for now - you can add more here later. Save the file out.[/li]
[li]cd $OH[/li]
[li]chmod a+rx start.sh[/li]
[li]./start.sh[/li][/ol]

OH should now be running. Don’t expect much, but do check the log files and make sure there are no errors.

Next Steps:

[ol][li]Use @guessed scripts to create an initial set of items [url=http://forum.micasaverde.com/index.php/topic,30367.0.html]
http://forum.micasaverde.com/index.php/topic,30367.0.html[/url]. Note you might have to install ‘curl’ and ‘xsltproc’ if not on your system for this to work.[/li]
[li]Edit that items file, cleanup item names, etc. If not sure, leave it for now – you can change them later[/li]
[li]Copy the item file into the $OH/configurations/items directory.[/li]
[li]Copy the MiOS binding transforms into the $OH/configurations/transform. This is kinda of a pain right now – see below for my ‘best’ way of doing it today. Things will not work until this is done, so don’t skip it![/li]
[li]Consider auto-starting OH: [url=https://github.com/openhab/openhab/wiki/Samples-Tricks#how-to-configure-openhab-to-start-automatically-on-linux]Samples Tricks · openhab/openhab1-addons Wiki · GitHub
[li]Write a sample rule or two to test your items and understanding of rules[/li]
[li]Good time to read MiOS binding Wiki [url=https://github.com/openhab/openhab/wiki/MiOS-Binding]https://github.com/openhab/openhab/wiki/MiOS-Binding[/url][/li]
[li]Read the part of the MiOS binding on logging and just tack the logging additions into logback.xml (inside the … tags. It’ll create a logs/mios.log and it can be very helpful.[/li]
[li]Read about and configure a persistence engine. I use db4o and others use the rrd4j. Both are easy to setup.[/li][/ol]

There is still a lot for you to setup, between editing and updating items and considering creating a sitemap so you can use the web control interface (check the demo directory configurations/sitemaps to get a taste of how that works). I’d recommend you get a couple of rules working, tweak your item names/definitions a bit and make a rudimentary sitemap file before you try to take on any other bindings (the MiOS binding is complex and once you are semi-comfortable with it, you’ll be ready to for the rest of the OH bindings).

Installing Transformations:
There are a bunch of files you really need to install in order for OH and MiOS to talk to each other. These files, called ‘transformations’, map the OH terms, values and concepts into MiOS/Vera terms, values and concepts and are REQUIRED for the mios binding to be do much. Unfortunatly, there is no way for the MiOS binding to automatically include them, so you’ll have to download them and install them by hand. More unfortunatly, there are about 30 of them and no easy way to download them in a single file/zip.

Here’s what I found to be about the ‘quickest’ way for now:

[ol][li]Go to the OpenHAB repository at [url=https://github.com/openhab/openhab]https://github.com/openhab/openhab[/url][/li]
[li]On the right side, press the Download ZIP button[/li]
[li]In an empty scratch/temporary directory, unzip the file (usually called openhab-master.zip)
[/li][li]Copy the transforms to the OH directory[/li][/ol]

cp openhab-master/bundles/binding/org.openhab.binding.mios/examples/transform/* $OH/configurations/transform

When done, get out of that scratch/temporary directory and delete the temporary directory - you don’t need it anymore

#14

@gduprey, what a great write up. Thank you for getting me started so quickly.

Just one note, to download the Transforms in one Zip file, go to:

Choose the “Download Zip” button on right sidebar to get the entire project.

When downloaded, extract the files from openhab/bundles/binding/org.openhab.binding.mios/examples/transform to the directory @gduprey mentioend

Cheers!

#15

Good point! It’s one less step than the git approach and doesn’t require installing the git tool first. I have updated my post to use that technique instead.

Thanks!

Gerry

#16

Hi Gerry, thanks for your very useful steps. You said for the moment, skip the designer. I’m just trying to use it (Windows install), but unable to link it to my openHab running on Rasperry Pi, did you try it?
I put in location the IP of the RsbPi and in folder: /opt/openhab/configurations/openhab.cfg
Message from the designer: couldn’t find the file…

A nice day,

chris

#17

Hi Chris, I put the OpenHAB directory in my home directory on my Pi. I use Apple File Protocol, but you could also install Samba on the Pi so that you could attach the folder. I think there are several discussions on how to do this.

#18

[quote=“chris66, post:16, topic:185629”]Hi Gerry, thanks for your very useful steps. You said for the moment, skip the designer. I’m just trying to use it (Windows install), but unable to link it to my openHab running on Rasperry Pi, did you try it?
I put in location the IP of the RsbPi and in folder: /opt/openhab/configurations/openhab.cfg
Message from the designer: couldn’t find the file…

A nice day,

chris[/quote]

Besides mounting the network share, for some really strange reason, you need to have the original openhab_default.cfg file in the folder in order for the designer to recognize your environment.