updated generated content

Signed-off-by: Kai Kreuzer <kai@openhab.org>

_data/bindings.csv

@@ -30,7 +30,7 @@ oh1,energenie,Energenie,"The openHAB Energenie binding allows you to send comman
 oh1,enocean,EnOcean,"[EnOcean](https://www.enocean.com/en/) provides reliable and self-powered wireless sensor solutions for the Internet of Things.  This binding allows openHAB to monitor and control EnOcean devices through the EnOcean USB 300 gateway."
 oh1,enphaseenergy,Enphase Energy,"This binding is for people with [Enphase Energy](http://enphase.com) microinverters used in their solar installation, which means every solar panel has its own inverter and can be monitored individually."
 oh1,epsonprojector,Epson Projector,"This binding should be compatible with Epson projectors which support ESC/VP21 protocol over serial port."
-oh1,exec,Exec,"If you want to enhance openHAB with a 'swiss-army-knife-binding' which executes given commands on the commandline, please place this bundle in the folder `${openhab_home}/addons` and add binding information to your configuration. See the following sections on how to do this."
+oh1,exec,Exec,"Execute commands as you would enter on the command line, returning the output (possibly transformed) as the bound item's state.  Also, execute command lines in response to commands sent to bound items."
 oh1,expire,Expire,"The Expire binding will post an update or command that you specify (the 'expire' update/command) to items it is bound to after a period of time has passed.  If you don't specify an update or command, the default is to post an Undefined (`UnDefType.UNDEF`) update to the item."
 oh1,fatekplc,Fatek PLC,"[Fatek PLC](http://fatek.com/en/prod.php?catId=1) is one kind of programmable logic controller.  This binding support native Fatek protocol to communicate with PLC.  For communication to PLC is used [JFatek library](http://www.simplify4u.org/jfatek/)."
 oh1,fht,FHT,"FHT is a range of devices produced by busware.de which allows to interact with various protocols and devices over radio frequencies. It's also possible to build one on your own."

addons/bindings/exec1/readme.md

@@ -9,20 +9,24 @@ source: external
 
 # Exec Binding
 
-If you want to enhance openHAB with a "swiss-army-knife-binding" which executes given commands on the commandline, please place this bundle in the folder `${openhab_home}/addons` and add binding information to your configuration. See the following sections on how to do this. 
+Execute commands as you would enter on the command line, returning the output (possibly transformed) as the bound item's state.  Also, execute command lines in response to commands sent to bound items.
 
-The Exec binding could act as the opposite of WoL and sends a shutdown command to the servers. Or switches off WLAN connectivity if a scene "sleeping" is activated.
+See [examples](#examples) below.
 
-Note: when using 'ssh' you should use private key authorization since the password cannot be read from commandline. The given user should have the necessary permissions.
+## Considerations
 
-There is also a binding specifically for openHAB 2 [here](http://docs.openhab.org/addons/bindings/exec/readme.html).
+* The user under which you are running openHAB should have the necessary permissions in order to execute your command lines.
+* When using the `ssh` command, you should use private key authorization, since the password cannot be read from the command line.
+* There is also a binding specifically for openHAB 2 [here](http://docs.openhab.org/addons/bindings/exec/readme.html).
 
-## Binding Confguration
+## Binding Configuration
 
 This binding does not have a configuration.
 
 ## Item Configuration
 
+### Update item states
+
 When updating the states of items based on executing a command line (an "in" binding):
 
 ```
@@ -35,6 +39,14 @@ where:
 * `<refreshintervalinmilliseconds>` is the frequency at which to repeatedly execute the command line.
 * `<transformationrule>` is optional, and can be used to transform the string returned from the command before updating the state of the item.
 
+Example item:
+
+```
+Number Temperature "Ext. Temp. [%.1f°C]" { exec="<[curl -s http://weather.yahooapis.com/forecastrss?w=566473&u=c:60000:XSLT(demo_yahoo_weather.xsl)]" }
+```
+
+### Sending commands
+
 When executing a command line in response to the item receiving a command (an "out" binding):
 
 ```
@@ -46,6 +58,15 @@ where:
 * `<openHAB-command>` is the openHAB command that will trigger the execution of the command line.  Can be `ON`, `OFF`, `INCREASE`, etc., or the special wildcard command '`*`' which is called in cases where no direct match could be found
 * `<commandLine to execute>` is the command to execute.  See [Formatting](#formatting) and [Splitting](#splitting) sections below.
 
+Example item:
+
+```
+Number SoundEffect "Play Sound [%d]" { exec=">[1:open /mp3/gong.mp3] >[2:open /mp3/greeting.mp3] >[*:open /mp3/generic.mp3]" }
+
+```
+
+### Old Format
+
 Deprecated format (do not use; retained for backward compatibility only):
 
 ```
@@ -66,9 +87,25 @@ Sometimes the `<commandLine to execute>` isn't executed properly. In that case,
 
 ## Examples
 
+### Turn a Computer ON and OFF
+
+On possible useage is to turn a computer on or off.  The Wake-on-LAN binding could be bound to a Switch item, so that when the switch receives an ON command, A Wake-on-LAN message is sent to wake up the computer.  When the switch item receives an OFF command, it will call the Exec binding to connect via ssh and issue the shutdown command.  Here is the example item:
+
+```
+Switch MyLinuxPC "My Linux PC" { wol="192.168.1.255#00-1f-d0-93-f8-b7", exec=">[OFF:ssh user@host shutdown -p now]" }
+```
+
+### KNX Bus to Exec Command
+
+The example below combines three bindings to incorporate the following behavior: query the current state of the NAS with the given IP address. When receiving an OFF command over KNX or the user switches to OFF manually then send the given command line via the exec binding.
+
+```
+Switch Network_NAS	"NAS"	(Network, Status)	{ nh="192.168.1.100", knx="<2/0/0", exec=">[OFF:ssh user@host shutdown -p now]" }
+```
+
+### More Examples
+
 ```
-exec="OFF:ssh user@host shutdown -p now"
-exec="OFF:some command, ON:'some other\, more \'complex\' \\command\\ to execute', *:fallback command"
 exec=">[ON:/bin/sh@@-c@@echo on >> /tmp/sw_log] >[OFF:/bin/sh@@-c@@echo off >> /tmp/sw_log]"
 exec=">[1:open /mp3/gong.mp3] >[2:open /mp3/greeting.mp3] >[*:open /mp3/generic.mp3]"
 exec="<[curl -s http://weather.yahooapis.com/forecastrss?w=566473&u=c:60000:XSLT(demo_yahoo_weather.xsl)]"
@@ -76,18 +113,10 @@ exec="<[/bin/sh@@-c@@uptime | awk '{ print $10 }':60000:REGEX((.*?))]"
 exec="<[execute.bat %1$tY-%1$tm-%1$td %2$s %3$s:60000:REGEX((.*?))]"
 exec="<[php ./configurations/scripts/script.php:60000:REGEX((.*?))]"
 exec="<[/bin/sh@@-c@@uptime | awk '{ print $10 }':]"
+
+// deprecated format
+exec="OFF:ssh user@host shutdown -p now"
+exec="OFF:some command, ON:'some other\, more \'complex\' \\command\\ to execute', *:fallback command"
 exec="1:open /path/to/my/mp3/gong.mp3, 2:open /path/to/my/mp3/greeting.mp3, *:open /path/to/my/mp3/generic.mp3"
 ```
 
-### Items
-
-```
-Switch Network_NAS	"NAS"	(Network, Status)	{ nh="192.168.1.100", exec="OFF:ssh user@host shutdown -p now"}
-```
-
-```
-Switch Network_NAS	"NAS"	(Network, Status)	{ nh="192.168.1.100", knx="<2/0/0", exec="OFF:ssh user@host shutdown -p now"}
-```
-
-The example above combines three bindings to incorporate the following behavior: query the current state of the NAS with the given IP address. When receiving an OFF command over KNX or the user switches to OFF manually then send the given command line via the exec binding.
-

addons/bindings/sonos/readme.md

@@ -50,6 +50,8 @@ The devices support the following channels:
 | control | Player       | This channel supports controlling the zoneplayer, e.g. start/stop/next/previous | all |
 | coordinator | String | UDN of the coordinator for the current group | all |
 | currentalbum | String | Name of the album currently playing | all |
+| currentalbumart | Image | Cover art of the album currently playing | all |
+| currentalbumarturl | String | Cover art URL of the album currently playing | all |
 | currentartist | String | Name of the artist currently playing | all |
 | currenttitle | String | Title of the song currently playing | all |
 | currenttrack | String       | This channel indicates the name of the track or radio station currently playing | all |

addons/bindings/squeezebox/readme.md

@@ -70,3 +70,38 @@ All devices support some of the following channels:
 | coverartdata            | Image        | Image data of cover art of the current song|
 | ircode                  | String       | Received IR code|
 | numberPlaylistTracks    | Number       | Number of playlist tracks|
+| notificationSoundVolume | Dimmer       | Volume for playing notifications|
+
+## Notifications
+
+### How To Set Up
+
+Squeeze Players can be set up as audio sinks in openHAB.  Please follow the [openHAB multimedia documentation](http://docs.openhab.org/configuration/multimedia.html) for setup guidance. 
+
+You can create an item and sitemap entry in order to set the notification volume independently from the Squeeze Player's current volume setting. If the notification volume is not specified, it will use the Player's current volume setting.
+
+Item for setting notification volume.
+```
+Dimmer NotificationVolume "Notification Volume [%d %%]" {channel="squeezebox:squeezeboxplayer:5919BEA2-764B-4590-BC70-D74DCC15491B:20cfbf221510:notificationSoundVolume"}
+```
+
+Sitemap entry for setting notification volume.
+```
+Slider item=NotificationVolume label="Notification Volume"
+```
+
+You can play notifications from within rules.
+```
+rule "Garage Door Open Notification"
+when
+    Item GarageDoorOpenNotification received command ON
+then
+    say("The garage door is open!", "voicerss:enUS", "squeezebox:squeezeboxplayer:5919BEA2-764B-4590-BC70-D74DCC15491B:20cfbf221510")
+end
+```
+
+### Known Issues
+
+- There are some versions of squeezelite that will not correctly play very short duration mp3 files.  Versions of squeezelite after v1.7 and before v1.8.6 will not play very short duration mp3 files reliably.  For example, if you're using piCorePlayer (which uses squeezelite), please check your version of squeezelite if you're having trouble playing notifications. This bug has been reported on the squeezelite forum.
+
+- When streaming from a remote service (such as Pandora or Spotify), after the notification plays, the Squeezebox Server starts playing a new track, instead of picking up from where it left off on the currently playing track.

addons/bindings/weather1/readme.md

@@ -25,13 +25,14 @@ There is also a binding specifically openHAB 2 [here](http://docs.openhab.org/ad
 	- [Configuration Example](#configuration-example)
 - [Item Configuration](#item-configuration)
 	- [Number formatting](#number-formatting)
+	- [Units](#units)
 	- [Unit conversion](#unit-conversion)
 	- [Examples](#examples)
 	- [Forecast](#forecast)
 	- [Data accuracy](#data-accuracy)
 	- [Common Id](#common-id)
 - [Html Layouts](#html-layouts)
-	- [Html Layout Gallery](#html-layout-gallery)
+	- [HTML Layout Gallery](#html-layout-gallery)
 - [Debugging and Tracing](#debugging-and-tracing)
 - [Troubleshooting](#troubleshooting)
 - [Downloads](#downloads)
@@ -296,18 +297,21 @@ Number   Station_Latitude     "Station Latitude [%.6f]"  {weather="locationId=ho
 Number   Station_Longitude    "Station Longitude [%.6f]" {weather="locationId=home, type=station, property=longitude, scale=6"}
 
 ```
+
 ### Forecast
+
 All bindings can also be used for forecasts. You only have to add the forecast day in the item.  
 Display tomorrows min and max temperature forecast:
+
 ```
 Number   Temp_Min         "Temperature min [%.2f °C]"   {weather="locationId=home, forecast=1, type=temperature, property=min"}
 Number   Temp_Max         "Temperature max [%.2f °C]"   {weather="locationId=home, forecast=1, type=temperature, property=max"}
 ```
-0 = todays forecast  
-1 = tomorrows forecast  
-and so on  
+
+0 = todays forecast, 1 = tomorrows forecast, and so on.
 
 Each provider sends different forecast days. 
+
 - ForecastIo: 8 days (0-7)
 - OpenWeatherMap: 5 days (0-4)
 - WorldWeatherOnline: 5 days (0-4)
@@ -394,7 +398,7 @@ Webview url="/weather?locationId=home&layout=example&iconset=colorful" height=7
 
 (This does not work for OpenHAB2 and this page needs an update for how to use this on OH2)
 
-### Html Layout Gallery
+### HTML Layout Gallery
 
 I would like to create a weather layout gallery. If you have a great looking html weather layout you want it to share, just [send it to me](mailto:gerrieg.openhab@icloud.com) an i will put it on this wiki page.
 

addons/io/oh2/org.openhab.io.imperihome/README.md

@@ -5,14 +5,40 @@ It creates a REST service at _/imperihome/iss_ that implements the [ImperiHome S
 
 ## Installation
 
-The ImperiHome integration service can be installed through the Paper UI. Navigate to Extensions > Misc and click Install.
+The ImperiHome integration service can be installed through the Paper UI. Navigate to Add-ons > Misc and click Install.
+
+<a name="configuration"></a>
 
 ## Configuration
 
-The service itself has no configuration. ImperiHome on the other hand must be configured to connect to your openHAB instance.
+### openHAB Add-on
+
+To configure the ImperiHome integration add-on in openHAB, create a _imperihome.cfg_ file in the _conf/services_ directory. The following configuration options can be used:
+ 
+**System ID**
+
+The ImperiHome integration service identifies itself to ImperiHome using a system ID. By default the unique identifier of your openHAB installation is used. To override the ID, use the _system.id_ configuration option. 
+
+```
+system.id=my-openhab-123
+```
+
+*Warning*: the system ID can not contain the underscore character (_). 
+
+**Root URL**
+
+Root URL of your openHAB installation. Should point to the openHAB welcome page. This option is currently only required when using the custom icon tag. 
+
+```
+openhab.rootUrl=http://myserver.example.org:7070/
+```
+
+### ImperiHome
+
+ImperiHome must be configured to connect to your openHAB instance.
 
 Start ImperiHome, open the menu and go to My Systems. Add a new system (+) and choose 'ImperiHome Standard System' as the object type. Now enter the URL to your openHAB instance
- as Local URL, followed by _/imperihome/iss_. For example, if your OH instance is running at _http://192.168.1.10:8080/_, the Local URL would be _http://192.168.1.10:8080/imperihome/iss_. 
+ as Local URL, followed by _/imperihome/iss_. For example, if your openHAB instance is running at _http://192.168.1.10:8080/_, the Local URL would be _http://192.168.1.10:8080/imperihome/iss_. 
 
 If you have port forwarding or similar set up to access your OH form the internet, you can also fill the Remote URL in the same way. For example: 
 _http://my-openhab-url.dyndns.org:8080/imperihome/iss_. Please be aware that this service provides no authentication mechanism, so anyone could use the API to control your 
@@ -132,6 +158,19 @@ _Example_:
 iss:invert:true
 ```
 
+### Tag: _icon_
+
+Sets a custom icon to be shown in ImperiHome. You can use all icon names that are also available for use in your sitemaps, including custom icons.
+To use this tag you must set the openHAB root URL in your [configuration](#configuration).
+
+_Required_: no<br>
+_Default_: none<br>
+_Example_: 
+
+```
+iss:icon:sofa
+```
+
 <a name="deviceTypes"></a> 
 
 ## Device types

developers/development/guidelines.md

@@ -40,7 +40,7 @@ Note that this list also serves as a checklist for code reviews on pull requests
 
 1. Eclipse SmartHome requires at least JavaSE 7. Hence no features of Java 8 must be used within the code. To allow optimized JavaSE 8 runtimes, the set of Java packages to be used is furthermore restricted to [Compact Profile 2](http://www.oracle.com/technetwork/java/embedded/resources/tech/compact-profiles-overview-2157132.html).
 1. The minimum OSGi framework version supported is [OSGi R4.2](http://www.osgi.org/Download/Release4V42), no newer features must be used.
-1. For logging, slf4j (v1.7.2) is used with [non-static loggers](http://slf4j.org/faq.html#declared_static).
+1. For logging, slf4j (v1.7.2) is used.
 1. A few common utility libraries are available that every Eclipse SmartHome based solution has to provide and which can be used throughout the code (and which are made available in the target platform):
  - Apache Commons IO (v2.2)
  - Apache Commons Lang (v2.6)
@@ -48,7 +48,20 @@ Note that this list also serves as a checklist for code reviews on pull requests
 
 ## D. Runtime Behavior
 
-14. Overridden methods from abstract classes or interfaces are expected to return fast unless otherwise stated in their JavaDoc. Expensive operations should therefore rather be scheduled as a job.
-1. Creation of threads must be avoided. Instead, resort into using existing schedulers which use pre-configured thread pools. If there is no suitable scheduler available, start a discussion in the forum about it rather than creating a thread by yourself.
-1. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning. This can be tested by manually starting and stopping the bundle from the console (`stop <bundle-id>` resp. `start <bundle-id>`).
+1. Overridden methods from abstract classes or interfaces are expected to return fast unless otherwise stated in their JavaDoc. Expensive operations should therefore rather be scheduled as a job.
+1. Creation of threads must be avoided. Instead, resort into using existing schedulers which use pre-configured thread pools. If there is no suitable scheduler available, start a discussion in the forum about it rather than creating a thread by yourself. For periodically executed jobs that do not require a fixed rate [scheduleWithFixedDelay](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ScheduledExecutorService.html#scheduleWithFixedDelay(java.lang.Runnable,%20long,%20long,%20java.util.concurrent.TimeUnit)) should be preferred over [scheduleAtFixedRate](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ScheduledExecutorService.html#scheduleAtFixedRate(java.lang.Runnable,%20long,%20long,%20java.util.concurrent.TimeUnit)).
+1. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning. This can be tested by manually starting and stopping the bundle from the console (```stop <bundle-id>``` resp. ```start <bundle-id>```).
 1. Bundles must not require any substantial CPU time. Test this e.g. using "top" or VisualVM and compare CPU utilization with your bundle stopped vs. started.
+
+## E. Logging
+
+1. As we are in a dynamic OSGi environment, loggers should be [non-static](http://slf4j.org/faq.html#declared_static), when ever possible and have the name ```logger```.
+1. Parametrized logging must be used (instead of string concatenation).
+1. Where ever unchecked exceptions are caught and logged, the exception should be added as a last parameter to the logging. For checked exceptions, this is normally not recommended, unless it can be considered an error situation and the stacktrace would hold additional important information for the analysis.
+1. Logging levels should focus on the system itself and describe its state. As every bundle is only one out of many, logging should be done very scarce. It should be up to the user to increase the logging level for specific bundles, packages or classes if necessary. This means in detail:
+ - Most logging should be done in ```debug``` level. ```trace``` can be used for even more details, where necessary.
+ - Only few important things should be logged in ```info``` level, e.g. a newly started component or a user file that has been loaded.
+ - ```warn``` logging should only be used to inform the user that something seems to be wrong in his overall setup, but the system can nonetheless function as normal, while possibly ignoring some faulty configuration/situation. It can also be used in situations, where a code section is reached, which is not expected by the implementation under normal circumstances (while being able to automatically recover from it).
+ - ```error``` logging should only be used to inform the user that something is tremendously wrong in his setup, the system cannot function normally anymore, and there is a need for immediate action. It should also be used if some code fails irrecoverably and the user should report it as a severe bug.
+1. For bindings, you should NOT log errors, if e.g. connections are dropped - this is considered to be an external problem and from a system perspective to be a normal and expected situation. The correct way to inform users about such events is to update the Thing status accordingly. Note that all events (including Thing status events) are anyhow already logged.
+1. Likewise, bundles that accept external requests (such as servlets) must not log errors or warnings if incoming requests are incorrect. Instead, appropriate error responses should be returned to the caller.