diff --git a/.markdownlint.json b/.markdownlint.json index ac8f3076b..ac8218e76 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -3,5 +3,6 @@ "MD004": { "style": "dash" }, "MD013": false, "MD025": false, - "MD029": { "style": "one" } + "MD029": { "style": "one" }, + "MD041": false } \ No newline at end of file diff --git a/addons/actions.md b/addons/actions.md index 7623df406..13ae56a9a 100644 --- a/addons/actions.md +++ b/addons/actions.md @@ -106,6 +106,7 @@ All HTTP Actions can have a last `timeout` parameter added in ms. eg. `sendHttpP ::: For example: + ```javascript val headers = newHashMap("Cache-control" -> "no-cache") val output = sendHttpGetRequest("https://example.com/?id=1", headers, 1000) @@ -158,6 +159,7 @@ if ((thingStatusInfo !== null) && (thingStatusInfo.getStatus().toString() == "ON ``` ### openHAB Subsystem Actions + openHAB has several subsystems that can be accessed from Rules. These include persistence, see [Persistence Extensions in Scripts and Rules]({{base}}/configuration/persistence.html#persistence-extensions-in-scripts-and-rules), transformations, scripts. - `callScript(String scriptName)`: Calls a script which must be located in the `$OPENHAB_CONF/scripts` folder. @@ -182,6 +184,7 @@ Three different actions are available: - `sendLogNotification(message)`: Sends a log notification to the `notifications` list at your openHAB Cloud instance. Notifications are NOT sent to any registered devices For each of the three actions, there's another variant accepting an icon name and a severity: + - `sendNotification(emailAddress, message, icon, severity)` - `sendBroadcastNotification(message, icon, severity)` - `sendLogNotification(message, icon, severity)` @@ -189,6 +192,7 @@ For each of the three actions, there's another variant accepting an icon name an Icon and severity can potentially be used by cloud instance clients (such as the openHAB apps for Android or iOS) to be displayed in the list of notifications. The parameters for these actions have the following meaning: + - `emailAddress`: String containing the email address the target user is registered with in the cloud instance - `message`: String containing the notification message text - `icon`: String containing the icon name (as described in [Items]({{base}}/configuration/items.html#icons)) @@ -294,6 +298,7 @@ dayset-workday=[MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY] dayset-weekend=[SATURDAY,SUNDAY] dayset-trash=[MONDAY] ``` + #### Custom Bank Holidays In addition to the ability to define custom daysets, one can define a custom list of holidays or other important days. @@ -314,6 +319,7 @@ The following is an example listing a few custom days. ``` + For further examples and to find the list of elements to reference holidays that require more complicated calculations (e.g. holidays based on a lunar calendar, Easter, etc.) see the [XSD that defines the structures of the XML](https://github.com/svendiedrichsen/jollyday/blob/b78fa20e75d48bdf14e3fa8107befe44e3bacf3a/src/main/xsd/Holiday.xsd) or the XML file for your country or others. You can place these XML files anywhere on your file system that openHAB has permission to read. diff --git a/addons/bindings.md b/addons/bindings.md index 40b263b5e..9a5b2a6c4 100644 --- a/addons/bindings.md +++ b/addons/bindings.md @@ -36,7 +36,7 @@ Bindings connect your smart home's devices and technologies to openHAB.

Most bindings developed for openHAB 1 can also be used in openHAB 2. - These bindings are connected directly to items by editing text files. + These bindings are connected directly to items by editing text files.

diff --git a/addons/index.md b/addons/index.md index 98828f7d6..ccace5b41 100644 --- a/addons/index.md +++ b/addons/index.md @@ -8,7 +8,7 @@ layout: documentation All add-ons for openHAB 2 are part of the distribution. This includes all 2.x Bindings as well as all 1.x add-ons that were reported to be compatible. -There are several ways you can install an add-on. +There are several ways you can install an add-on. These are described under *Installation of Add-ons* below | Add-on Type | Description | @@ -99,7 +99,6 @@ binding = astro,mqtt1,network After saving the file, the add-on will be installed. - ### Through manually provided add-ons > Attention: diff --git a/addons/persistence.md b/addons/persistence.md index 5de4be517..69287bc99 100644 --- a/addons/persistence.md +++ b/addons/persistence.md @@ -21,7 +21,7 @@ Persistence services enable the storage of item states over time.

Some openHAB 1 persistence services have not yet completed validation for inclusion in the distribution; however, they may indeed work properly under openHAB 2. - All openHAB 1 add-ons can be downloaded in a zip file. + All openHAB 1 add-ons can be downloaded in a zip file. We need your help testing them so that they may be easily installed in a future distribution. Please see the compatibility layer documentation and also search the openHAB community forum for the latest information and steps for manual installation. diff --git a/addons/transformations.md b/addons/transformations.md index 4aaba28e6..d960062db 100644 --- a/addons/transformations.md +++ b/addons/transformations.md @@ -23,7 +23,7 @@ The relevant transformation service needs to be installed via the paperUI before Be aware, that some Transformation services rely on transformation files, while others work by directly providing the transformation logic. Transformation files need to be placed in the directory `$OPENHAB_CONF/transform`. -1. Item and Sitemap Labels +1. Item and Sitemap Labels Transformations used in the [state/value part]({{base}}/configuration/items.html#state-transformations) of labels are applied **on the fly**. While the **transformed value** will (for example) be visible on a Sitemap, the **original value** is stored in the Item. diff --git a/administration/bundles.md b/administration/bundles.md index 3b2d5f3ab..74c27d1b1 100644 --- a/administration/bundles.md +++ b/administration/bundles.md @@ -64,7 +64,7 @@ Bundles are named according to the following convention: where - **prefix** is the first element to categorize the bundle. - For addons this is `org.openhab`. + For addons this is `org.openhab`. - **type** is the add-on type, e.g. "binding", "persistence", or "ui" - **id** is the identifier for this bundle diff --git a/administration/console.md b/administration/console.md index f31a9a519..e58314134 100644 --- a/administration/console.md +++ b/administration/console.md @@ -148,7 +148,7 @@ To add custom parameters or overwrite the default values, you can change the con ### Changing the Password The password is stored in the file `users.properties`, located in the `etc` directory as [mentioned above](#console-settings-files-and-directories). -By default, the line with the password contains the text `openhab = `, followed by the current password (e.g. `habopen`) or a password hash (e.g. `{CRYPT}4AE1A0FD...{CRYPT}`). +By default, the line with the password contains the text `openhab =`, followed by the current password (e.g. `habopen`) or a password hash (e.g. `{CRYPT}4AE1A0FD...{CRYPT}`). To change the authentication password edit the file manually, replacing the password or password hash (including `{CRYPT}`) with your new password in clear text. Alternately, run the following Linux shell command, which will perform the replacement for you. @@ -180,7 +180,6 @@ To enable binding to all interfaces, uncomment the line in `services/runtime.cfg`. - ### Change the Port Number The SSH port configuration is done through the file `org.apache.karaf.shell.cfg`, located in the `etc` directory as [mentioned above](#console-settings-files-and-directories). diff --git a/administration/runtime.md b/administration/runtime.md index ed13fa0bf..6eb38aa3a 100644 --- a/administration/runtime.md +++ b/administration/runtime.md @@ -18,7 +18,6 @@ It is possible to query and even change the state of entities like items or thin Some of the described commands are executed on the internal database and could break your installation. Please use this functionality only if you know what you are doing! ::: - ## Examples Query an item's state: diff --git a/appendix/help.md b/appendix/help.md index 6abc08c4c..37c8b431e 100644 --- a/appendix/help.md +++ b/appendix/help.md @@ -12,7 +12,6 @@ Join today and find answers for all details of openHAB: * [community.openhab.org](https://community.openhab.org) - # FAQs - Frequently Asked Questions In the community forum you'll also find a list of recurring questions with short answers, commonly known as FAQs. diff --git a/concepts/audio.md b/concepts/audio.md index 13ff28178..040a9a4b9 100644 --- a/concepts/audio.md +++ b/concepts/audio.md @@ -10,33 +10,33 @@ title: Audio & Voice Audio and voice features are an important aspect of any smart home solution as it is a very natural way to interact with the user. openHAB has a very modular architecture that enables many different use cases. -At its core, there is the notion of an *audio stream*. -Audio streams are provided by *audio sources* and consumed by *audio sinks*. +At its core, there is the notion of an *audio stream*. +Audio streams are provided by *audio sources* and consumed by *audio sinks*. ![](images/audio.png) - *Audio Streams* are essentially byte streams with a given *audio format*. They do not need to be limited in size, i.e. it is allowed to have continuous streams, e.g. the input from a microphone or from an Internet radio station. - *Audio Formats* define the container (e.g. WAV), encoding, bit rate, sample frequency and depth and the bit order (little or big endian). -- *Audio Sources* are services that are capable of producing audio streams. -They can support different formats and provide a stream in a requested format upon request. +- *Audio Sources* are services that are capable of producing audio streams. +They can support different formats and provide a stream in a requested format upon request. Typical audio source services are microphones. Typically, a continuous stream is expected from them. -- *Audio Sinks* are services that accept audio streams of certain formats. +- *Audio Sinks* are services that accept audio streams of certain formats. Typically, these are expected to play the audio stream, i.e. they are some kind of speaker or media device. -- *Text-to-Speech* (TTS) services are similar to audio sources with respect to the ability to create audio streams. -The difference is that they take a string as an input and will synthesize this string to a spoken text using a given voice. -TTS services can provide information about the voices that they support and the locale that those voices are associated with. +- *Text-to-Speech* (TTS) services are similar to audio sources with respect to the ability to create audio streams. +The difference is that they take a string as an input and will synthesize this string to a spoken text using a given voice. +TTS services can provide information about the voices that they support and the locale that those voices are associated with. Each voice supports exactly one locale. -- *Speech-to-Text* (STT) services are similar to audio sinks, but they do not simply play back the stream, but convert it to a plain string. +- *Speech-to-Text* (STT) services are similar to audio sinks, but they do not simply play back the stream, but convert it to a plain string. They provide information about supported formats and locales. As plain text from an STT service is often not very useful, there is additionally the concept of a *human language interpreter*: ![](images/hli.png) -A *Human Language Interpreter* takes a string as an input. -It then derives actions from it (like sending commands to devices) and/or replies with a string, which opens the possibility to realize conversations. -As such an interpreter is not directly linked to audio streams, but operates on strings only, this can be the basis for any kind of assistant, e.g. for chat bots using the console, XMPP, Twitter or other messaging services. +A *Human Language Interpreter* takes a string as an input. +It then derives actions from it (like sending commands to devices) and/or replies with a string, which opens the possibility to realize conversations. +As such an interpreter is not directly linked to audio streams, but operates on strings only, this can be the basis for any kind of assistant, e.g. for chat bots using the console, XMPP, Twitter or other messaging services. -Applications can dynamically choose which services to use, so that different sinks can be used for different use cases. +Applications can dynamically choose which services to use, so that different sinks can be used for different use cases. Defaults can be set as a configuration for all those services in case an application does not ask for any specific service. diff --git a/concepts/profiles.md b/concepts/profiles.md index 5fa9efda5..0bafc2c1f 100644 --- a/concepts/profiles.md +++ b/concepts/profiles.md @@ -5,30 +5,30 @@ title: Profiles # Profiles -The communication between the framework and the Thing handlers is managed by the "Communication Manager", which in turn uses "Profiles" to determined what exactly needs to be done. +The communication between the framework and the Thing handlers is managed by the "Communication Manager", which in turn uses "Profiles" to determined what exactly needs to be done. This provides some flexibility to influence these communication paths. -By their nature, profiles are correlated to links between Items and Channels (i.e. `ItemChannelLinks`). So if one Channel is linked to several Items it also will have several profile instances, each handling the communication to exactly one of these Items. -The same applies for the situation where one Item is linked to multiple Channels. +By their nature, profiles are correlated to links between Items and Channels (i.e. `ItemChannelLinks`). So if one Channel is linked to several Items it also will have several profile instances, each handling the communication to exactly one of these Items. +The same applies for the situation where one Item is linked to multiple Channels. -Profiles are created by ProfileFactories and are retained for the lifetime of their link. -This means that they are allowed to retain a transient state, like e.g. the timestamp of the the last event or the last state. +Profiles are created by ProfileFactories and are retained for the lifetime of their link. +This means that they are allowed to retain a transient state, like e.g. the timestamp of the the last event or the last state. With this, it is possible to take into account the temporal dimension when calculating the appropriate action in any situation. There exist two different kinds of profiles: state and trigger profiles. ### State Profiles -State profiles are responsible for communication between Items and their corresponding state Channels (`ChannelKind.STATE`). +State profiles are responsible for communication between Items and their corresponding state Channels (`ChannelKind.STATE`). Their purpose is to forward state updates and commands to and from the Thing handlers. ### Trigger Profiles -Trigger Channels (`ChannelKind.TRIGGER`) by themselves do not maintain a state (as by their nature they only fire events). -With the help of trigger profiles they can be linked to Items anyway. -Hence the main purpose of a trigger profile is to calculate a state based on the fired events. -This state then is forwarded to the linked Item by sending `ItemStateEvents`. +Trigger Channels (`ChannelKind.TRIGGER`) by themselves do not maintain a state (as by their nature they only fire events). +With the help of trigger profiles they can be linked to Items anyway. +Hence the main purpose of a trigger profile is to calculate a state based on the fired events. +This state then is forwarded to the linked Item by sending `ItemStateEvents`. -Trigger profiles are powerful means to implement some immediate, straight-forward logic without the need to write any rules. +Trigger profiles are powerful means to implement some immediate, straight-forward logic without the need to write any rules. Apart from that, they do not pass any commands or state updates to and from the Thing handler as by their nature trigger Channels are not capable of handling these. diff --git a/concepts/things.md b/concepts/things.md index 2114a4f85..3c80d8a72 100644 --- a/concepts/things.md +++ b/concepts/things.md @@ -33,7 +33,6 @@ A typical example of a bridge is an IP gateway for some non-IP based home automa As many Things can be automatically discovered, there are special mechanisms available that deal with the handling of [automatically discovered Things](discovery.html). - ## Thing Status Each Thing has a status object, which helps to identify possible problems with the device or service. @@ -93,4 +92,3 @@ The following table lists the different status details for each status: REMOVING NONENo further status details available. REMOVED NONENo further status details available. - diff --git a/concepts/units-of-measurement.md b/concepts/units-of-measurement.md index e8e011b60..6ac902ffa 100644 --- a/concepts/units-of-measurement.md +++ b/concepts/units-of-measurement.md @@ -57,7 +57,6 @@ The placeholder `%unit%` can be placed anywhere in the state description. In order to match `NumberItems` and Channels and define a default state description with unit placeholder the Channel also has to provide an Item type which includes the dimension information: - Number:Temperature @@ -80,7 +79,6 @@ The `org.openhab.core.library.dimension` and `javax.measure.quantity` packages p All units which are currently supported by default are listed in the tables below. - Imperial (base unit symbols): | Type | Unit | Symbol | @@ -213,6 +211,7 @@ Binary Prefixes: | Yobi | Yi | 2⁸⁰ | To use the prefixes simply add the prefix to the unit symbol - for example: + * milliAmpere - `mA` * centiMetre - `cm` * kiloWatt - `kW` diff --git a/configuration/addons.md b/configuration/addons.md index 68f5aef72..7a8ceeabd 100644 --- a/configuration/addons.md +++ b/configuration/addons.md @@ -72,7 +72,6 @@ binding = astro,network After saving the file, the add-on will be installed. - ## Through manually provided add-ons ::: warning Attention diff --git a/configuration/editors.md b/configuration/editors.md index 7cbbd100e..3f35b573c 100644 --- a/configuration/editors.md +++ b/configuration/editors.md @@ -27,6 +27,7 @@ If you are using [openHABian]({{base}}/installation/openhabian.html), the networ *Attention Windows users:* Directly accessing network shares (UNC paths) is often not supported. Please be sure to mount the network share to a drive letter. {: #openhab-vscode} + ## openHAB VS Code Extension openHAB VS Code is an extension for the [Visual Studio Code](https://code.visualstudio.com) editor. @@ -50,6 +51,7 @@ The validation needs a running openHAB installation in your environment and can You can find all important information in the extensions [readme file](https://github.com/openhab/openhab-vscode#validating-the-rules). {: #others} + ## Other Editor Integrations The here summarized projects provide syntax highlighting for different text editors, but have no _on top_ functionality. @@ -60,6 +62,7 @@ mcedit is an editor which comes with mc (Midnight Commander). You can find the syntax files and installation instructions on [openhab-mcedit](https://github.com/CWempe/openhab-mcedit). {: #notepadpp} + ### Notepad++ Notepad++ is a free source code editor for Windows. @@ -85,4 +88,3 @@ You can find the syntax file and installation instructions on [openhab-syntax-te BBEdit is a text and code editor for macOS and the offical successor of TextWrangler. You can find the syntax file and installation instructions on [BBEdit-openHAB-language](https://github.com/mjmeijer/BBEdit-openHAB-language). - diff --git a/configuration/habpanel.md b/configuration/habpanel.md index d69146608..3939b40a9 100644 --- a/configuration/habpanel.md +++ b/configuration/habpanel.md @@ -39,6 +39,7 @@ HABPanel uses service configuration variables to store its data on the openHAB s openhab> config:edit org.openhab.habpanel openhab> config:property-get ``` + The following properties are defined: - `panelsRegistry`: contains the entire registry serialized in JSON, it is maintained by the application and shouldn't be modified directly (editing it by hand, while possible, is strongly discouraged); @@ -58,6 +59,7 @@ Use the gears icon in the top-right corner to switch between the two modes. ![Main menu - edit mode](images/habpanel_main-menu-edit.png) When in edit mode, several features are available: + * Add a new empty dashboard with the **Add new dashboard** link; * Go to the settings screen (for instance, to switch from local storage to a server-managed panel configuration) by clicking on the **Advanced settings** link; * Adjust the number of columns for the grid of main menu tiles with the slider, from 1 (the default) to 6; @@ -126,6 +128,7 @@ Modifications to the dashboard are not saved automatically, use the **Save** but When a dashboard is running, widgets can be interacted with, and server-sent events are received when items' states are updated, so widgets update automatically in HABPanel. The icons in the top-right corner perform the following: + - the **speech balloon** activates the speech recognition feature and send the results as text to openHAB's default human language interpreter. This implies [some configuration on the server]({{base}}/configuration/multimedia.html#human-language-interpreter), and this icon might not be displayed if the browser doesn't support voice recognition ([mainly only in Chrome and other webkit variants currently](https://caniuse.com/#feat=speech-recognition){:target="_blank"}). It can also be configured in the panel configuration to appear on the bottom of the screen; - the **refresh** button forces HABPanel to retrieve the current state of all items; - the **fullscreen** button tells the browser to go fullscreen, if supported. @@ -136,7 +139,6 @@ Tip: while running a dasboard, append `?kiosk=on` to the URL in the web browser Apart from the storage configuration discussed above, the settings screen contains several settings kept as part of the panel configuration (meaning they are set separately): - | Setting | Description | |------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Panel name | An user-friendly name for the panel. It will be displayed in the header of the side drawer. | @@ -157,7 +159,6 @@ Apart from the storage configuration discussed above, the settings screen contai *Note: the text-to-speech functionality featured in HABPanel is unrelated to the [TTS services]({{base}}/configuration/multimedia.html#text-to-speech) defined on the openHAB server, and they are not compatible (this is why a String item is required and the `say()` function cannot be used). However, HABPanel will play audio streamed through the ['webaudio' sink]({{base}}/configuration/multimedia.html#audio), including spoken text. - ## Widgets ### Standard widgets diff --git a/configuration/index.md b/configuration/index.md index 6eb1f95c7..dc6a52488 100644 --- a/configuration/index.md +++ b/configuration/index.md @@ -86,7 +86,7 @@ _Note there is an option in Main UI to bulk create Items where you can copy'n'pa ✔️ ❌ ❌ - transform/*.map *.js files + transform/*.map*.js files Define Persistence @@ -168,4 +168,3 @@ Here are some hints to avoid some common pitfalls when starting out. You can use the import function to import `.items` files or snippets taken from other sources like the openHAB community forum. * Use VS code extensions to [edit rules, items and sitemap files](editors.html). You can also use any text editor or cloud based tool, but VS code extensions will work locally and help you by highlighting and cross-checking the file syntax. - diff --git a/configuration/items.md b/configuration/items.md index 769588715..734e0e164 100644 --- a/configuration/items.md +++ b/configuration/items.md @@ -32,9 +32,9 @@ For example, an Item bound to a sensor receives updated sensor readings and an I There are two methods for defining Items: -1. Through UI +1. Through UI -2. Through text `.items` files located in the `$OPENHAB_CONF/items` folder. +2. Through text `.items` files located in the `$OPENHAB_CONF/items` folder. Files here must have the extension `.items`; you may create as many `.items` files as needed. However, each Item must be unique across all `.items` files. Refer to the [installation docs]({{base}}/installation/index.html) to determine your specific installation's folder structure. @@ -51,6 +51,7 @@ It's recommended to edit `.items` files using one of the [openHAB supporting edi Doing so will provide you with full IDE support including features such as syntax checking, and context assistance. {: #syntax} + ## Item Definition and Syntax Items are defined using the following syntax: @@ -89,6 +90,7 @@ The last example above defines an Item with the following fields: The remainder of this article provides additional information regarding Item definition fields. {: #type} + ### Type The Item type defines what kind of state can be stored in that Item and which commands the Item will accept. @@ -145,6 +147,7 @@ In the example above, if you move the Slider widget to 60%, move the Switch to O --> {: #name} + ### Name The Item name is used to uniquely identify an Item. @@ -164,13 +167,13 @@ An Item naming scheme with a physical or logical top-down will ensure you can ea The following naming style guide is recommended: -- Words build a physical or logical hierarchy +- Words build a physical or logical hierarchy -- Every word of the Item name starts with an uppercase letter +- Every word of the Item name starts with an uppercase letter -- Words should be separated by an underscore character, except for words that logically belong together +- Words should be separated by an underscore character, except for words that logically belong together -- Names that reoccur frequently, such as the names of rooms or appliances, may be abbreviated to reduce overall name length. +- Names that reoccur frequently, such as the names of rooms or appliances, may be abbreviated to reduce overall name length. (Example: Bathroom = BR) Examples: @@ -187,9 +190,9 @@ Examples: Users are encouraged to apply the style guide above to group names as well as Item names. Two naming schemes are established in the community for Group names: -1. Use a plural word form (e.g. Batteries) where possible. +1. Use a plural word form (e.g. Batteries) where possible. Otherwise the word "Group" may be appended for clarity. -2. Prepend a lowercase "g" to the name (e.g. gBattery) +2. Prepend a lowercase "g" to the name (e.g. gBattery) | Group Name | Interpretation | |-------------------------------------------|-----------------------------------------------------------------------| @@ -199,6 +202,7 @@ Two naming schemes are established in the community for Group names: | "`Livingroom`" or "`gLR`" | Group for *all* Items (including lights) belonging to the living room | {: #label} + ### Label Label text is used to describe an Item in a human-readable way. @@ -215,28 +219,31 @@ Number Livingroom_Temperature "Temperature [%.1f °C]" Channel labels can be overwritten by Item definitions and Item labels can be overwritten in [Sitemaps]({{base}}/configuration/sitemaps.html#element-types). {: #state} + ### State The state of an Item depends on the Item type, the Channel bound to the Item, and internal or external events. A analogy can be drawn between the state of an Item and the value of a variable in a computer program. {: #item-state} + #### Item State This section provides information about what a user can expect regarding the behavior of the state of an Item. -- Items are created with a state of `NULL` +- Items are created with a state of `NULL` -- Operations in openHAB such as a user interacting with the Item using the Basic UI, or a Binding updating the state of an Item will change the state of the Item +- Operations in openHAB such as a user interacting with the Item using the Basic UI, or a Binding updating the state of an Item will change the state of the Item -- An Item's state may also be set through a Binding which may be reacting to changes in the real world +- An Item's state may also be set through a Binding which may be reacting to changes in the real world -- A Binding may set the state of an Item to `UNDEF` if it looses communications with a Thing (for example, a Z-wave doorbell with a dead battery). +- A Binding may set the state of an Item to `UNDEF` if it looses communications with a Thing (for example, a Z-wave doorbell with a dead battery). The Binding may also set the state to `UNDEF` if an error exists in the binding configuration, or under other conditions *N.B.* Many openHAB users find that it can be very useful to use [Persistence](/addons/#persistence) and [System started]({{base}}/configuration/rules-dsl.html#system-based-triggers) rules so that their systems behaves in a predictable way after an openHAB restart. {: #command-vs-status} + #### Command vs. Status Users should bear in mind the difference between an Item used to send a command to a Thing, and an Item that reflects the status of a real-world Thing in the UI. @@ -258,6 +265,7 @@ Then you add the light-level Item to your UI. Now when you send the Switch Item command, and you see a corresponding increase in light level in the room, you know for sure that your command has been received and acted upon, because you have a return status Item in your UI. {: #state-presentation} + #### State Presentation The Item definition determines the Item's textual state presentation, e.g., regarding formatting, decimal places, unit display and more. @@ -286,6 +294,7 @@ Location My_Location "My Location [%2$s°N %3$s°E %1$sm]" // e.g. ``` {: #state-transformation} + #### State Transformation Transformations can be used in the state part of an Item, to translate the raw state of an Item into another language, or to convert technical values into human readable information. @@ -299,6 +308,7 @@ Contact Livingroom_Window "Ventana del salón [MAP(window_esp.map):%s]" Please refer to the article on [Transformations](/docs/configuration/transformations.html) for more usage details and a list of available transformation services. {: #icons} + ### Icons The icon name is used by openHAB to select the image to display next to an Item name when using one of openHAB's UIs, e.g. Basic UI. @@ -332,6 +342,7 @@ Note that image files with the wrong file ending will be ignored. Users may substitute their own icon for an icon from the default icon set by placing a file in the `$OPENHAB_CONF/icons/classic/` folder with the same filename as the name of the icon being substituted. {: #icons-dynamic} + #### Dynamic Icons Some icons are dynamically selected by openHAB depending on the Item's state. @@ -353,15 +364,15 @@ Dynamic icon filenames follow the pattern below: Dynamic icon sets may consist of as many state-specific icon files as needed. Each set must meet the following criteria: -- A default icon is mandatory. +- A default icon is mandatory. The default icon filename is the name of the icon without a hyphen or state (e.g. `switch.svg`) -- Icon filenames must follow the naming restrictions given for [icons](#icons) above +- Icon filenames must follow the naming restrictions given for [icons](#icons) above -- The state name must reflect the Item's raw state. +- The state name must reflect the Item's raw state. [Transformations](#state-transformation) applied in the state presentation definition of the Item have no influence on icon selection. -- The state portion of the icon name must be in lowercase letters +- The state portion of the icon name must be in lowercase letters **Example:** @@ -403,6 +414,7 @@ For a dimmable light (0-100%), you might provide icons as in the example: Just as with regular icons, user-defined dynamic icon sets may be configured via the custom icons folder `$OPENHAB_CONF/icons/classic/`. {: #groups} + ### Groups The Group is a special Item type that can be used to define a category or collection into which you can combine other Items or Groups. @@ -416,12 +428,12 @@ Group groupname ["labeltext"] [] [(group1, group2, ...)] The Group item is commonly used to define hierarchies of Items from different perspectives. For example: -- Location-oriented or physical perspective: - - Floors in your house → Rooms on that floor → An appliance in that room... +- Location-oriented or physical perspective: + - Floors in your house → Rooms on that floor → An appliance in that room... -- Functional or logical perspective: - - Maintenance Group → All battery states → Individual battery states in percentage - - Further examples: all lights, all room temperatures, combined power consumption +- Functional or logical perspective: + - Maintenance Group → All battery states → Individual battery states in percentage + - Further examples: all lights, all room temperatures, combined power consumption These relationships can be exploited in [Sitemaps]({{base}}/configuration/sitemaps.html) or in [automation rules]({{base}}/configuration/rules-dsl.html) to navigate through the hierarchically organized Items or to perform computations and updates on subsets of similar Items. @@ -455,6 +467,7 @@ Because of the hierarchical structure of your group items, the rule will be clea Additionally, the rule will not need to be modified when a new Item is added to the `Temperatures` group. {: #group-type} + ### Derive Group State from Member Items As you are now aware, an Item can have a state (e.g. "ON", "OFF"). @@ -492,13 +505,13 @@ Incompatible Item types within a Group may result in the invalid aggregation res Examples for derived states on Group Items when declared in the Item DSL: ```java -Group:Number Lights "Active Lights [%d]" // e.g. "2" -Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2" -Group:Switch:AND(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2" -Group:Number:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C" -Group:DateTime:EARLIEST LatestUpdate "Latest Update [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]" -Group:DateTime:LATEST LastSeen "Last Seen [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]" -Group:String:COUNT("OFFLINE") OfflineDevices "Offline Devices [%d]" // e.g. "2" +Group:Number Lights "Active Lights [%d]" // e.g. "2" +Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2" +Group:Switch:AND(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2" +Group:Number:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C" +Group:DateTime:EARLIEST LatestUpdate "Latest Update [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]" +Group:DateTime:LATEST LastSeen "Last Seen [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]" +Group:String:COUNT("OFFLINE") OfflineDevices "Offline Devices [%d]" // e.g. "2" ``` The first three examples above compute the number of active lights and store them as group state. @@ -518,6 +531,7 @@ The `EARLIEST` function returns `now().minusDays(10)`, the `LATEST` function ret The last Group counts all members of it matching the given regular expression, here any character or state (simply counts all members). {: #tags} + ### Tags Tags added to an Item definition allow a user to characterize the specific nature of the Item beyond its basic Item type. @@ -538,6 +552,7 @@ Tags will be ignored if no Items in the openHAB installation support it. See the [Hue Emulation Service](/addons/integrations/hueemulation/) or [HomeKit Add-on](/addons/integrations/homekit/) documentation for more details. {: #binding} + ### Binding Configuration One of the greatest strengths of an openHAB automation system is the sheer number of devices you can interact with. @@ -609,8 +624,8 @@ Switch Office_PC {channel="lgwebos:WebOSTV:01dd3ac4-62f4-7505-208b-12345679", ch The first example shows a symbiosis of the LG webOS Binding and the Wake-on-LAN Binding to interact with a TV. - {: #autoupdate} + #### Parameter `autoupdate` When left as default, openHAB's `autoupdate` function attempts to predict the outcome of a *command* on the Item *state*. @@ -626,6 +641,7 @@ Switch Garage_Gate {channel="xxx", autoupdate="false"} ``` {: #expire} + #### Parameter `expire` This parameter allows to post an update or command to an item after a period of time has passed. @@ -702,6 +718,7 @@ You have an Item called `Bedroom_Light` that is connected to a Hue lamp ```java Color Bedroom_Light { channel="hue:0210:1:bulb1:color" } ``` + and a [Rule]({{base}}/configuration/rules-dsl.html) to toggle this light with a serial button: ```java diff --git a/configuration/jsr223.md b/configuration/jsr223.md index c6cbb24b9..dc5296d73 100644 --- a/configuration/jsr223.md +++ b/configuration/jsr223.md @@ -30,6 +30,7 @@ New APIs are planned to be implemented in the future, which will provide standar :::: tabs ::: tab JavaScript + ```js 'use strict'; @@ -54,10 +55,11 @@ sRule.setTriggers([ automationManager.addRule(sRule); ``` + ::: - ::: tab Jython + ```python scriptExtension.importPreset("RuleSupport") scriptExtension.importPreset("RuleSimple") @@ -79,9 +81,11 @@ sRule.setTriggers([ automationManager.addRule(sRule) ``` + ::: ::: tab Groovy + ```groovy import org.openhab.core.automation.* import org.openhab.core.automation.module.script.rulesupport.shared.simple.* @@ -105,6 +109,7 @@ sRule.setTriggers([ automationManager.addRule(sRule) ``` + ::: :::: diff --git a/configuration/multimedia.md b/configuration/multimedia.md index 70aa773c1..762305c5f 100644 --- a/configuration/multimedia.md +++ b/configuration/multimedia.md @@ -60,13 +60,13 @@ openhab> openhab:audio stream example.com Alternatively the [`playSound()`](https://openhab.org/javadoc/latest/org/openhab/core/model/script/actions/audio#playSound(java.lang.String)) or [`playStream()`](https://openhab.org/javadoc/latest/org/openhab/core/model/script/actions/audio#playStream(java.lang.String)) functions can be used in DSL rules: -- `playSound(String filename)` : plays a sound from the sounds folder to the default sink -- `playSound(String filename, PercentType volume)` : plays a sound with the given volume from the sounds folder to the default sink -- `playSound(String sink, String filename)` : plays a sound from the sounds folder to the given sink(s) -- `playSound(String sink, String filename, PercentType volume)` : plays a sound with the given volume from the sounds folder to the given sink(s) +- `playSound(String filename)` : plays a sound from the sounds folder to the default sink +- `playSound(String filename, PercentType volume)` : plays a sound with the given volume from the sounds folder to the default sink +- `playSound(String sink, String filename)` : plays a sound from the sounds folder to the given sink(s) +- `playSound(String sink, String filename, PercentType volume)` : plays a sound with the given volume from the sounds folder to the given sink(s) -- `playStream(String url)` : plays an audio stream from an url to the default sink (set url to `null` if streaming should be stopped) -- `playStream(String sink, String url)` : plays an audio stream from an url to the given sink(s) (set url to `null` if streaming should be stopped) +- `playStream(String url)` : plays an audio stream from an url to the default sink (set url to `null` if streaming should be stopped) +- `playStream(String sink, String url)` : plays an audio stream from an url to the given sink(s) (set url to `null` if streaming should be stopped) #### Examples diff --git a/configuration/paperui.md b/configuration/paperui.md index 025b15a6e..68d193468 100644 --- a/configuration/paperui.md +++ b/configuration/paperui.md @@ -10,15 +10,15 @@ title: Configuration though Paper UI The Paper UI is a new interface that helps setting up and configuring your openHAB instance. It does not (yet) cover all aspects, so you still need to resort to textual configuration files, but it already offers the following: -- Add-on management: +- Add-on management: Easily install or uninstall openHAB add-ons ![extensions](images/paperui1.png) -- Thing discovery: +- Thing discovery: See devices and services found on your network and add them to your setup. ![discovery](images/paperui2.png) -- Linking items to channels: +- Linking items to channels: Instead of adding a binding configuration to your item file, you can directly link Thing channels to your items. ![links](images/paperui3.png) diff --git a/configuration/persistence.md b/configuration/persistence.md index 00d5f47eb..1fc03f6a3 100644 --- a/configuration/persistence.md +++ b/configuration/persistence.md @@ -67,6 +67,7 @@ The following strategies are defined internally and may be used in place of `str - `restoreOnStartup`: load and initialize the last persisted state of the Item on openHAB startup (if the Item state is undefined (`UNDEF`)). #### Cron Persistence Triggers + openHAB uses [Quartz](https://www.quartz-scheduler.org/documentation) for time-related cron events. See the [Rules article]({{base}}/configuration/rules-dsl.html#time-based-triggers) for more information. @@ -151,8 +152,8 @@ Items { item1, item2 : strategy = everyChange, restoreOnStartup } ``` -It is usually not necessary to restore all Items since there is a good chance that they are no longer accurate (switches may have been toggled, sensor values are likely to have changed), and the restoration may result in unwanted rule actions. +It is usually not necessary to restore all Items since there is a good chance that they are no longer accurate (switches may have been toggled, sensor values are likely to have changed), and the restoration may result in unwanted rule actions. ## Persistence Extensions in Scripts and Rules diff --git a/configuration/restdocs.md b/configuration/restdocs.md index 62e5a166d..3432e6490 100644 --- a/configuration/restdocs.md +++ b/configuration/restdocs.md @@ -97,6 +97,7 @@ Stop openhab and add this part to ```$OPENHAB_USERDATA/etc/org.apache.karaf.feat openhab-*-auth ``` + Once openhab is restarted authentication will be disabled. ## Additional Considerations diff --git a/configuration/rules-dsl.md b/configuration/rules-dsl.md index f709740e9..be18f0118 100644 --- a/configuration/rules-dsl.md +++ b/configuration/rules-dsl.md @@ -120,6 +120,7 @@ end - `` - Contains the logic that should be executed when a trigger condition is met, see the [script](#scripts) section for details on its syntax. {: #rule-triggers} + ### Rule Triggers Before a rule starts working, it has to be triggered. @@ -135,6 +136,7 @@ There are different categories of rule triggers: Here are the details for each category: {: #event-based-triggers} + ### Event-based Triggers You can listen to commands for a specific item, on status updates or on status changes (an update might leave the status unchanged). @@ -153,6 +155,7 @@ When using the `received command` trigger, the Rule might trigger **before** the Therefore, if the Rule needs to know what the command was, use the [implicit variable]({{base}}/configuration/rules-dsl.html#implicit-variables-inside-the-execution-block) `receivedCommand` instead of `.state`. {: #member-of-triggers} + ### Member of Triggers As with Item based event-based triggers discussed above, you can listen for commands, status updates, or status changes on the members of a given Group. @@ -172,6 +175,7 @@ Also, as with Item event-based triggers, when using `received command`, the Rule So in Rules where the Rule needs to know what the command was, use the `receivedCommand` implicit variable instead of `triggeringItem.state`. {: #time-based-triggers} + ### Time-based Triggers You can either use some pre-defined expressions for timers or use a [cron expression](https:////www.quartz-scheduler.org/documentation/quartz-2.2.2/tutorials/tutorial-lesson-06.html) instead: @@ -195,6 +199,7 @@ A cron expression takes the form of six or optionally seven fields: You may use [CronMaker](https://www.cronmaker.com/) or the generator at [FreeFormatter.com](https://www.freeformatter.com/cron-expression-generator-quartz.html) to generate cron expressions. {: #system-based-triggers} + ### System-based Triggers Two system-based triggers are provided as described in the table below: @@ -219,6 +224,7 @@ end ``` {: #thing-based-triggers} + ### Thing-based Triggers Your rules can take actions based upon status updates or status changes generated by Things. @@ -243,6 +249,7 @@ You need to use quotes around `thingUID` if it contains special characters such ::: {: #channel-based-triggers} + ### Channel-based Triggers Some add-ons provide trigger channels. @@ -279,6 +286,7 @@ end ``` {: #scripts} + ## Scripts The expression language used within scripts is the same that is used in the Xtend language - see the [documentation of expressions](https://www.eclipse.org/xtend/documentation/203_xtend_expressions.html) on the Xtend homepage. @@ -302,6 +310,7 @@ if (Temperature.state < 20) { ``` {: #manipulating-item-states} + ### Manipulating Item States Rules are often used to manipulate the state of an Item, for example switching lights on and off under certain conditions. @@ -321,12 +330,14 @@ The following table summarizes the impact of the two manipulator commands on the **Beware:** In most cases, a rule with a trigger of `received update` will fire following the command `sendCommand` as: + - openHAB auto-updates the status of Items for which the item definition does not contain `autoupdate="false"` - the Thing sends a status update to the Item. Besides the specific manipulator command methods `MyItem.sendCommand()` and `MyItem.postUpdate()`, generic manipulators in the form of `sendCommand(MyItem, )` and `postUpdate(MyItem, )` are available. The specific versions is normally recommended. {: #sendcommand-method-vs-action} + #### MyItem.sendCommand("new state") versus sendCommand(MyItem, "new state") Using the methods `MyItem.sendCommand()` and `MyItem.postUpdate()` is often preferable. @@ -345,6 +356,7 @@ Using `Myitem.sendCommand(new_state)` or `Myitem.postUpdate(new_state)` will, in The Action `sendCommand(MyItem, new_state)` does not provide the same flexibilty. For example, if `new_state` is typed as a primitive (e.g., `var int new_state = 3`) and myItem is of the Object type Dimmer: + * the following command ***will fail***: ~~sendCommand(MyItem, new_state)~~. * However, the following command **will work**: `MyItem.sendCommand(new_state)`. @@ -362,6 +374,7 @@ sendCommand("My_Lamp_" + index, ON) ``` {: #using-state-of-items-in-rules} + ### Using the States of Items in Rules Often it is desired to calculate other values from Item states or to compare Item states against other values @@ -376,6 +389,7 @@ This section differentiates between command type and state type. For ease of reading, it is possible to simply add “type” to the end of a command type thereby obtaining the state type. For example, a Color Item can receive an OnOffType, IncreaseDecreaseType, PercentType, or HSBType. Therefore the following are all valid commands one can send to a Color Item: + - `MyColorItem.sendCommand(ON)` - `MyColorItem.sendCommand(INCREASE)` - `MyColorItem.sendCommand(new PercentType(50))` @@ -400,6 +414,7 @@ These methods can be called in Rules-DSL without the "get" part in name as in `( They retrieve the state of MyColorItem and then casts it as HSBType to be able to use the methods associated with the HSBType. {: #conversions} + #### Working with Item States: Conversions *Reminder: For a complete and up-to-date list of what item types are currently allowed in openHAB and the command types each item can accept refer to the section on [items in the openHAB documentation]({{base}}/concepts/items.html).* @@ -649,7 +664,6 @@ One can convert from ON and OFF to 1 and 0 with code similar to: val SwitchNum = if (MySwitchItem.state == ON) 1 else 0 ``` - #### Deeper Dive While interacting with Item states, care must be taken to understand the difference between Objects and primitives. @@ -688,6 +702,7 @@ Each of these separate methods is individually written to handle all of these di MyItem will automatically apply the method that corresponds to the argument type. {: #implicit-variables} + ### Implicit Variables inside the Execution Block Besides the implicitly available variables for items and commands/states, rules can have additional pre-defined variables, depending on their triggers: @@ -700,13 +715,14 @@ Besides the implicitly available variables for items and commands/states, rules - `receivedEvent` - implicitly available in every rule that has a channel-based trigger. {: #return} + ### Early returns It is possible to return early from a rule, not executing the rest of the statements like this: ```java if (Temperature.state > 20) { - return; + return; } Heating.sendCommand(ON) ``` @@ -714,6 +730,7 @@ Heating.sendCommand(ON) Caveat: Please note the semicolon after the return statement which terminates the command without an additional argument. {: #concurrency-guard} + ### Concurrency Guard If a rule triggers on UI events it may be necessary to guard against concurrency. @@ -737,6 +754,7 @@ end ``` {: #transformations} + ### Transformations openHAB [Transformation services](/addons/#transform) can be used in rules to transform/translate/convert data. @@ -782,8 +800,8 @@ finally { For all available Transformation services please refer to the list of [Transformation Add-ons](/addons/#transform). - {: #logging} + ### Logging You can emit log messages from your rules to aid debugging. diff --git a/configuration/rules-ng.md b/configuration/rules-ng.md index 3d1fa0b07..4f55530fe 100644 --- a/configuration/rules-ng.md +++ b/configuration/rules-ng.md @@ -11,7 +11,6 @@ title: Next-Gen Rules Since openHAB 2.4 another Rule Engine has been added. It works fundamentally different than what you find with our current [Rules](https://www.openhab.org/docs/configuration/rules-dsl.html). It allows Rules to be edited in a graphical fashion and to interact with [JSR223 Scripts (Javascript, Jypthon, etc)](https://www.openhab.org/docs/configuration/jsr223.html). - ## Installation Install the rule engine from Add-ons → Misc → Rule Engine (Experimental). @@ -27,7 +26,7 @@ When you now refresh your browser, you will see a `Rules` menu appearing in the In general this rule engine aims to support rules defined with syntax similar to: ```text -ON item_id state changed IF item_id.state == desired_value THEN item_id2.state = desired_value2 +ON item_id state changed IF item_id.state == desired_value THEN item_id2.state = desired_value2 ``` A rule consists of basic information like name, tags and a description. The main building blocks of rules are modules however, and each rule consists of one or more instances of each of the following modules: @@ -79,7 +78,6 @@ A given **Module type** has the following elements: defaultValue - default value for the configuration property when not specified in the rule tags - shows how to be considered a given value. For example, as a Temperature - **Output property** has the following metadata: name @@ -109,13 +107,13 @@ The types in the **Configuration** object are restricted to the following: **JSON schemas for:** - * [module types](../../schemas/ModuleTypes_schema.json) - * [rule templates](../../schemas/Templates_schema.json) - * [rule instances](../../schemas/Rules_schema.json) +* [module types](../../schemas/ModuleTypes_schema.json) +* [rule templates](../../schemas/Templates_schema.json) +* [rule instances](../../schemas/Rules_schema.json) ### Sample Rules - * **Sample rule instance referencing module types:** +* **Sample rule instance referencing module types:** ``` { @@ -157,16 +155,16 @@ The types in the **Configuration** object are restricted to the following: } ``` - * **Sample module types:** +* **Sample module types:** ``` -"triggers":[ - { +"triggers":[ + { "uid":"SampleTrigger", "label":"SampleTrigger label", "description":"Sample Trigger description.", - "outputs":[ - { + "outputs":[ + { "name":"triggerOutput", "type":"java.lang.String", "label":"TriggerOutput label", @@ -176,12 +174,12 @@ The types in the **Configuration** object are restricted to the following: } ] }, - { + { "uid":"CompositeSampleTrigger", "label":"CompositeTrigger label", "description":"Composite Trigger description.", - "outputs":[ - { + "outputs":[ + { "name":"compositeTriggerOutput", "type":"java.lang.String", "label":"compositeTriggerOutput label", @@ -189,8 +187,8 @@ The types in the **Configuration** object are restricted to the following: "reference":"compositeChildTrigger1.triggerOutput" } ], - "children":[ - { + "children":[ + { "id":"compositeChildTrigger1", "type":"SampleTrigger" } @@ -200,27 +198,27 @@ The types in the **Configuration** object are restricted to the following: ``` ``` - "conditions":[ - { + "conditions":[ + { "uid":"SampleCondition", "label":"SampleCondition label", "description":"Sample Condition description", - "configDescriptions":[ - { + "configDescriptions":[ + { "name":"operator", "type":"TEXT", "description":"Valid operators are =,>,<,!=", "required":true }, - { + { "name":"constraint", "type":"TEXT", "description":"Right operand which is compared with the input.", "required":true } ], - "inputs":[ - { + "inputs":[ + { "name":"conditionInput", "type":"java.lang.String", "label":"ConditionInput label", @@ -233,13 +231,13 @@ The types in the **Configuration** object are restricted to the following: ``` ``` -"actions":[ - { +"actions":[ + { "uid":"SampleAction", "label":"SampleAction label", "description":"Sample Action description.", - "configDescriptions":[ - { + "configDescriptions":[ + { "name":"message", "type":"TEXT", "label":"message label", @@ -249,12 +247,12 @@ The types in the **Configuration** object are restricted to the following: } ] }, - { + { "uid":"CompositeSampleAction", "label":"CompositeAction label", "description":"Composite Action description.", - "configDescriptions":[ - { + "configDescriptions":[ + { "name":"compositeMessage", "type":"TEXT", "label":"custom message label", @@ -263,8 +261,8 @@ The types in the **Configuration** object are restricted to the following: "required":false } ], - "inputs":[ - { + "inputs":[ + { "name":"compositeActionInput", "type":"java.lang.String", "label":"ActionInput label", @@ -272,18 +270,18 @@ The types in the **Configuration** object are restricted to the following: "required":true } ], - "children":[ - { + "children":[ + { "id":"SampleAction1", "type":"SampleAction", - "configuration":{ + "configuration":{ "message":"$compositeMessage" } }, - { + { "id":"SampleAction2", "type":"SampleAction", - "configuration":{ + "configuration":{ "message":"$compositeActionInput" } } @@ -296,46 +294,46 @@ The types in the **Configuration** object are restricted to the following: There are several ways to add new rules: - * using **JAVA API** from package: **org.openhab.automation.api**; - * using **text console commands: openhab:automation**; - * using **resource bundles** that provide moduletypes, rules and rule templates stored in **.json** files; - * using **REST API** - see the next chapter bellow. +* using **JAVA API** from package: **org.openhab.automation.api**; +* using **text console commands: openhab:automation**; +* using **resource bundles** that provide moduletypes, rules and rule templates stored in **.json** files; +* using **REST API** - see the next chapter bellow. ## REST API * http:///rest/module-types - lists module types. -* http:///rest/templates" - lists rule templates. +* http:///rest/templates" - lists rule templates. * http:///rest/rules - lists rule instances. #### /rest/templates - - GET /rest/templates - returns all registered rule templates. - - GET /rest/templates/{templateUID} - returned response includes only the content of the specified template. +- GET /rest/templates - returns all registered rule templates. +- GET /rest/templates/{templateUID} - returned response includes only the content of the specified template. #### /rest/module-types - - GET /rest/module-types - returns all registered module types. - - optional parameter 'type' with possible values: 'trigger', 'condition' or 'action' - filters the response to include only module definitions of specified type. - - optional parameter 'tags' - filters the response to include only module types which have specified tags. - - GET /rest/module-types/{moduleTypeUID} - returned response includes only the content of the specified module type. - +- GET /rest/module-types - returns all registered module types. +- optional parameter 'type' with possible values: 'trigger', 'condition' or 'action' - filters the response to include only module definitions of specified type. +- optional parameter 'tags' - filters the response to include only module types which have specified tags. +- GET /rest/module-types/{moduleTypeUID} - returned response includes only the content of the specified module type. + #### /rest/rules - - GET /rest/rules - returns all registered rule instances. - - POST /rest/rules - adds new rule instance to the rule registry. - - DELETE /rest/rules/{ruleUID} - deletes the specified rule instance. - - PUT /rest/rules/{ruleUID} - updates the specified rule instance. - - PUT /rest/rules/{ruleUID}/enable - enable/disable specified rule instance. - - PUT /rest/rules/{ruleUID}/runnow - executes actions of specified rule instance. - - GET /rest/rules/{ruleUID}/config - returns the configuration of the specified rule instance. - - PUT /rest/rules/{ruleUID}/config - updates the configuration of the specified rule instance. - - GET /rest/rules/{ruleUID}/triggers - returns the triggers defined for the specified rule instance. - - GET /rest/rules/{ruleUID}/conditions - returns the conditions defined for the specified rule instance. - - GET /rest/rules/{ruleUID}/actions - returns the actions defined for the specified rule instance. - - GET /rest/rules/{ruleUID}/{moduleCategory}/{id} - returns module instance with specified id and category {triggers/conditions/actions} of the specified rule. - - GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config - returns the configuration of the specified module instance. - - GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - returns the value of specified module configuration parameter (media type is text/plain). - - PUT /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - updates the value of specified module configuration parameter (media type is text/plain). +- GET /rest/rules - returns all registered rule instances. +- POST /rest/rules - adds new rule instance to the rule registry. +- DELETE /rest/rules/{ruleUID} - deletes the specified rule instance. +- PUT /rest/rules/{ruleUID} - updates the specified rule instance. +- PUT /rest/rules/{ruleUID}/enable - enable/disable specified rule instance. +- PUT /rest/rules/{ruleUID}/runnow - executes actions of specified rule instance. +- GET /rest/rules/{ruleUID}/config - returns the configuration of the specified rule instance. +- PUT /rest/rules/{ruleUID}/config - updates the configuration of the specified rule instance. +- GET /rest/rules/{ruleUID}/triggers - returns the triggers defined for the specified rule instance. +- GET /rest/rules/{ruleUID}/conditions - returns the conditions defined for the specified rule instance. +- GET /rest/rules/{ruleUID}/actions - returns the actions defined for the specified rule instance. +- GET /rest/rules/{ruleUID}/{moduleCategory}/{id} - returns module instance with specified id and category {triggers/conditions/actions} of the specified rule. +- GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config - returns the configuration of the specified module instance. +- GET /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - returns the value of specified module configuration parameter (media type is text/plain). +- PUT /rest/rules/{ruleUID}/{moduleCategory}/{id}/config/{param} - updates the value of specified module configuration parameter (media type is text/plain). ## JAVA API @@ -346,36 +344,35 @@ There are several ways to add new rules: `org.openhab.automation.template.TemplateRegistry` - provides functionality to get templates from the Rule Engine. - ## Text console commands -`automation listModuleTypes [-st] ` - lists all Module Types. If filter is present, lists only matching Module Types. +`automation listModuleTypes [-st] ` - lists all Module Types. If filter is present, lists only matching Module Types. -`automation listTemplates [-st] ` - lists all Templates. If filter is present, lists only matching Templates. +`automation listTemplates [-st] ` - lists all Templates. If filter is present, lists only matching Templates. -`automation listRules [-st] `- lists all Rules. If filter is present, lists only matching Rules. +`automation listRules [-st] `- lists all Rules. If filter is present, lists only matching Rules. -`automation removeModuleTypes [-st] ` - Removes the Module Types, loaded from the given url. +`automation removeModuleTypes [-st] ` - Removes the Module Types, loaded from the given url. -`automation removeTemplates [-st] ` - Removes the rule, specified by given UID. +`automation removeRule [-st] ` - Removes the rule, specified by given UID. -`automation removeRules [-st] `- Removes the rules. If filter is present, removes only matching Rules. +`automation removeRules [-st] `- Removes the rules. If filter is present, removes only matching Rules. -`automation importModuleTypes [-p] [-st] ` - Imports Module Types from given url. If parser type missing, "json" parser will be set as default. +`automation importModuleTypes [-p] [-st] ` - Imports Module Types from given url. If parser type missing, "json" parser will be set as default. -`automation importTemplates [-p] [-st] ` - Imports Templates from given url. If parser type missing, "json" parser will be set as default. +`automation importTemplates [-p] [-st] ` - Imports Templates from given url. If parser type missing, "json" parser will be set as default. -`automation importRules [-p] [-st] ` - Imports Rules from given url. If parser type missing, "json" parser will be set as default. +`automation importRules [-p] [-st] ` - Imports Rules from given url. If parser type missing, "json" parser will be set as default. -`automation exportModuleTypes [-p] [-st] ` - Exports Module Types in a file. If parser type missing, "json" parser will be set as default. +`automation exportModuleTypes [-p] [-st] ` - Exports Module Types in a file. If parser type missing, "json" parser will be set as default. -`automation exportTemplates [-p] [-st] ` - Exports Templates in a file. If parser type missing, "json" parser will be set as default. +`automation exportTemplates [-p] [-st] ` - Exports Templates in a file. If parser type missing, "json" parser will be set as default. -`automation exportRules [-p] [-st] ` - Exports Rules in a file. If parser type missing, "json" parser will be set as default. +`automation exportRules [-p] [-st] ` - Exports Rules in a file. If parser type missing, "json" parser will be set as default. -`automation enableRule [-st] ` - Enables the Rule, specified by given UID. +`automation enableRule [-st] ` - Enables the Rule, specified by given UID. The use of the 'enable' argument is optional, and will accept a boolean value. If used, the command will enable (true) or disable (false) the Rule. If it is not used, the command will return the current status of the Rule. @@ -397,51 +394,51 @@ The rule template is used only once when the rule is imported in the Rule Engine After that the reference from the rule instance to the rule template is removed and a given rule may exist even if the rule template is removed or modified. This will not have any impact on the already imported rules. - * **Sample rule instance referencing rule template:** +* **Sample rule instance referencing rule template:** ``` - { + { "uid": "sample.rulebytemplate", "name": "RuleByTemplate", "templateUID": "SampleRuleTemplate", - "tags": [ + "tags": [ "rule", "template" ], - "configuration": { + "configuration": { "condition_operator": "!=", "condition_constraint": "template" } } ``` - * **Sample rule template:** +* **Sample rule template:** ``` - { + { "uid":"SampleRuleTemplate", "description":"Sample Rule Template", - "tags":[ + "tags":[ "sample", "rule", "template" ], - "configDescriptions":[ + "configDescriptions":[ { - "name":"condition_operator", + "name":"condition_operator", "type": "TEXT", "description": "Valid operators are =,>,<,!=", "required": true }, { - "name":"condition_constraint", + "name":"condition_constraint", "type": "TEXT", "description": "Right operand which is compared with the input.", "required": true } ], - "triggers": [ - { + "triggers": [ + { "id": "CompositeSampleTriggerTemplateID", "type": "CompositeSampleTrigger", "label": "Sample Trigger", @@ -464,7 +461,7 @@ This will not have any impact on the already imported rules. } ], "actions": [ - { + { "id": "CompositeActionTemplateID", "type": "CompositeSampleAction", "label": "Sample Action", @@ -472,7 +469,7 @@ This will not have any impact on the already imported rules. "configuration": { "compositeMessage": "Hello World!!!" }, - "inputs": { + "inputs": { "compositeActionInput": "CompositeSampleTriggerTemplateID.compositeTriggerOutput" } } @@ -487,13 +484,13 @@ The above example uses two rule configuration properties: ### GenericEventTrigger -GenericEventTrigger has 3 configuration paramters: `eventTopic`,` eventSource` and `eventTypes` and one output: 'event'. +GenericEventTrigger has 3 configuration paramters: `eventTopic`,`eventSource` and `eventTypes` and one output: 'event'. { "uid":"GenericEventTrigger", "label":"Basic Event Trigger", "description":"Triggers Rules on Events", - "configDescriptions":[ + "configDescriptions":[ { "name":"eventTopic", "type":"TEXT", @@ -530,7 +527,6 @@ GenericEventTrigger has 3 configuration paramters: `eventTopic`,` eventSource` a ] } - ### GenericCompareCondition This module type is used to compare a value against a configuration property using an operator like `<, >, =`. @@ -576,9 +572,9 @@ The value to be compared can be specified either as an input or as a configurati ## Providing new Module Types -The rule engine is pluggable - any OSGi bundle can provide implementation for triggers, actions and condition module types and their corresponding metatype definition in JSON format. +The rule engine is pluggable - any OSGi bundle can provide implementation for triggers, actions and condition module types and their corresponding metatype definition in JSON format. -The extension bundle should register the service ModuleHandlerFactory (`org.openhab.automation.handler.ModuleHandlerFactory`) +The extension bundle should register the service ModuleHandlerFactory (`org.openhab.automation.handler.ModuleHandlerFactory`) and implement the necessary methods for creation of instances of the supported module handlers: - `org.openhab.automation.handler.TriggerHandler` @@ -590,12 +586,11 @@ and implement the necessary methods for creation of instances of the supported m Another way to extend the supported module types is by defining composite module types as an extension of the system module types. The composite module type wraps one or more instances of a system module type and defines new configuration parameters, inputs and outputs. - { "uid":"ItemStateChangeTrigger", "label":"Item State Trigger", "description":"This triggers a rule if an items state changed", - "configDescriptions":[ + "configDescriptions":[ { "name":"itemName", "type":"TEXT", @@ -609,7 +604,7 @@ The composite module type wraps one or more instances of a system module type an { "id":"itemStateChangeTriggerID", "type":"GenericEventTrigger", - "configuration":{ + "configuration":{ "eventSource":"$itemName", "eventTopic":"openhab/items/*", "eventTypes":"ItemStateEvent" @@ -630,4 +625,4 @@ The composite module type wraps one or more instances of a system module type an This example demonstrates a new module type *ItemStateChangeTrigger* which wraps the system module type *GenericEventTrigger*. It defines the new configuration property `itemName` which is used as the `eventSource` property of the *GenericEventTrigger*. The other config parameters `eventTopic` and `eventTypes` are staticly defined. -The composite module type can also have inputs and outputs and can use a reference to map them to inputs and outputs of the nested system module type(s). +The composite module type can also have inputs and outputs and can use a reference to map them to inputs and outputs of the nested system module type(s). diff --git a/configuration/sitemaps.md b/configuration/sitemaps.md index 7a43e0824..328ad0ec9 100644 --- a/configuration/sitemaps.md +++ b/configuration/sitemaps.md @@ -133,16 +133,16 @@ This provides the flexibility to present Items in the way desired in your home a **General remarks on parameters:** -- In the following definitions, parameters in `[square brackets]` are optional. +- In the following definitions, parameters in `[square brackets]` are optional. -- Parameters must be supplied in the order shown. +- Parameters must be supplied in the order shown. -- Common parameters, also known from [items definition](items.html#item-syntax): - - `item` defines the name of the Item you want to present (e.g. `Temperature`), [more details](items.html#item-name). - - `label` sets the textual description displayed next to the preprocessed Item data (e.g. "`Now [%s °C]`"), [more details](items.html#item-label). - - `icon` chooses the name of the icon file to show next to the element, [more details](items.html#icons). +- Common parameters, also known from [items definition](items.html#item-syntax): + - `item` defines the name of the Item you want to present (e.g. `Temperature`), [more details](items.html#item-name). + - `label` sets the textual description displayed next to the preprocessed Item data (e.g. "`Now [%s °C]`"), [more details](items.html#item-label). + - `icon` chooses the name of the icon file to show next to the element, [more details](items.html#icons). -- When an [Item]({{base}}/configuration/items.html) is defined, you have the opportunity to assign a label and/or an icon at that point. +- When an [Item]({{base}}/configuration/items.html) is defined, you have the opportunity to assign a label and/or an icon at that point. If no label or icon are specified in the Sitemap, then the label and/or icon you assigned to the Item will be displayed. Setting a value for `label` or `icon` of a Sitemap element will override the values defined for the linked Item. @@ -163,9 +163,10 @@ sitemap demo label="My home automation" { } } ``` + UoM = [Units of Measurment]({{base}}/concepts/units-of-measurement.html) -- Additional parameters such as `mappings` and `valuecolor` are described below. +- Additional parameters such as `mappings` and `valuecolor` are described below. ### Element Type 'Frame' @@ -197,7 +198,6 @@ Default item= [label=""] [icon=""] Presents an Item using the default UI representation specified by the type of the given Item. E.g., a `Dimmer` Item will be represented as a [Slider](#element-type-slider) element while a `Player` Item will be rendered with player button controls (Previous/Pause/Play/Next). - ### Element Type 'Text' ```perl @@ -307,16 +307,16 @@ Slider item= [label=""] [icon=""] [sendFrequency= This type presents a value as a user-adjustable control which slides from left (0) to right (100). -- `sendFrequency` is used to distinguish between long and short button presses in the classic (web) frontend. +- `sendFrequency` is used to distinguish between long and short button presses in the classic (web) frontend. This parameter defines the interval in milliseconds for sending increase/decrease requests. -- `switchSupport` is a parameter without an assignment. - - Classic UI: If specified, a short press on the "up" or "down" button switches the item "on" or "off" (0 or 100) respectively. - - Android app: If specified, a short press on the item row (except the slider itself) switches the item "on" or "off". - - This parameter has no effect in other UIs. +- `switchSupport` is a parameter without an assignment. + - Classic UI: If specified, a short press on the "up" or "down" button switches the item "on" or "off" (0 or 100) respectively. + - Android app: If specified, a short press on the item row (except the slider itself) switches the item "on" or "off". + - This parameter has no effect in other UIs. -- `minValue` (defaults to 0) and `maxValue` (defaults to 100) limit the possible range of the value (both included in the range). -- `step` (defaults to 1) defines the distance between two possible/selectable datapoints on the slider. +- `minValue` (defaults to 0) and `maxValue` (defaults to 100) limit the possible range of the value (both included in the range). +- `step` (defaults to 1) defines the distance between two possible/selectable datapoints on the slider. **Example:** @@ -336,7 +336,6 @@ This element is a combined control for something like a rgb or rgbw light where The down-button decreases brightness to zero and switches the light off. The up-button sets brightness to full but keeps the previous color (hue). The middle button opens an overlay to finetune your color. A color wheel let you pick the hue and a slider allows to set the brightness. - - `sendFrequency` is used to distinguish between long and short button presses in the classic (web) frontend. This parameter defines the interval in milliseconds for sending increase/decrease requests. @@ -393,7 +392,7 @@ Image [item=] [icon=""] url="" [label=":8080/static/YourImageFile.png. +Alternatively, the image file (e.g. YourImageFile.png) may be stored locally in the $OPENHAB_CONF/html folder, and will be accessible through the static route, `https://:8080/static/YourImageFile.png`. - `item` can refer to either an Image Item whose state is the raw data of the image, or a String Item whose state is an URL that points to an image. Some clients may not (yet) consider `item`. - `url` is the default URL from which to retrieve the image, if there is no associated Item or if the associated item's state is not a URL. @@ -444,18 +443,18 @@ Chart [item=] [icon=""] [label=""] [refresh=xxxx] Adds a time-series chart object for the display of logged data. -- `refresh` defines the refresh period of the Image (in milliseconds). +- `refresh` defines the refresh period of the Image (in milliseconds). -- `service` sets the persistence service to use. +- `service` sets the persistence service to use. If no service is specified, openHAB will use the first queryable persistence service it finds. Therefore, for an installation with only a single persistence service, this is not required. -- `period` is the scale of the time axis. Valid values are `h, 4h, 8h, 12h, D, 2D, 3D, W, 2W, M, 2M, 4M or Y`. +- `period` is the scale of the time axis. Valid values are `h, 4h, 8h, 12h, D, 2D, 3D, W, 2W, M, 2M, 4M or Y`. -- `begin` / `end` sets the beginning and end of the time axis. +- `begin` / `end` sets the beginning and end of the time axis. Valid values are in the format: "yyyyMMddHHmm" (yyyy = year, MM = month, dd = day, HH = hour (0-23), mm = minutes). -- `legend` is used to show or to hide the chart legend. +- `legend` is used to show or to hide the chart legend. Valid values are `true` (always show the legend) and `false` (never show the legend). If this parameter is not set, the legend is hidden if there is only one chart series. @@ -499,7 +498,6 @@ Its power state is represented by a binary Switch Item. Its channel number is a discrete number Item that may only be set to one of three states. By using a Switch or Selection element with a mappings array, you can replace these meaningless values with user-friendly descriptions for display on the user interface. - This mapping changes the displayed power state of the TV from "ON" and "OFF" to the more accurate terms, "on" and "standby". Similarly, mapping above changes the numbers "1", "2", and "3" to "DasErste", "BBC One", and "Cartoon Network" respectively. @@ -654,34 +652,34 @@ sitemap demo label="My home automation" { Explanation: -- The Sitemap "demo" with the shown title "My home automation" is defined. +- The Sitemap "demo" with the shown title "My home automation" is defined. -- One first Frame with a date stamp is shown. +- One first Frame with a date stamp is shown. -- Another Frame with a visual label "Demo" is presented, containing: +- Another Frame with a visual label "Demo" is presented, containing: - - A Switch for the Item "Lights" + - A Switch for the Item "Lights" - - A Text element showing a temperature in a given format + - A Text element showing a temperature in a given format - - A Group element. Upon clicking the element, a new view containing all "Heating" Items will be shown. + - A Group element. Upon clicking the element, a new view containing all "Heating" Items will be shown. - - Another Text element showing a "Multimedia" summary, e.g. "Currently playing". + - Another Text element showing a "Multimedia" summary, e.g. "Currently playing". The element is additionally the host for a nested block. By clicking in the element, a new view with two elements is presented: - - A Selection presenting four options in a modal dialog prompt - - A Slider to set the volume (e.g. 0-100%) + - A Selection presenting four options in a modal dialog prompt + - A Slider to set the volume (e.g. 0-100%) ## Further notes and comparison details -- String comparisons are case sensitive, so `==ON` is not the same as `==on`. +- String comparisons are case sensitive, so `==ON` is not the same as `==on`. -- DateTime comparisons are relative to the current time and specified in seconds. +- DateTime comparisons are relative to the current time and specified in seconds. So the expression `Lights_On_Time > 300` will return true if the DateTime Item is set to a value that's newer than the past 5 minutes (300 seconds). -- Further examples for defining Sitemaps can be found in our [openHAB-Samples](https://github.com/openhab/openhab/wiki/Samples-Sitemap-Definitions) section. +- Further examples for defining Sitemaps can be found in our [openHAB-Samples](https://github.com/openhab/openhab/wiki/Samples-Sitemap-Definitions) section.