diff --git a/.github/markdownStyle.rb b/.github/markdownStyle.rb index 9acdcc413..0da7c1e86 100644 --- a/.github/markdownStyle.rb +++ b/.github/markdownStyle.rb @@ -9,6 +9,9 @@ exclude_rule 'MD009' # Allow long line lengths exclude_rule 'MD013' +# Allow duplicate headers for different nesting +rule 'MD024', :allow_different_nesting => true + # Allow Multiple top level headers in the same document exclude_rule 'MD025' diff --git a/.markdownlint.json b/.markdownlint.json index ac8218e76..00cdd9d98 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -2,7 +2,10 @@ "default": true, "MD004": { "style": "dash" }, "MD013": false, + "MD024": {"allow_different_nesting": true}, "MD025": false, "MD029": { "style": "one" }, - "MD041": false + "MD033": false, + "MD041": false, + "MD046": { "style": "fenced" } } \ No newline at end of file diff --git a/addons/actions.md b/addons/actions.md index 13ae56a9a..02de7b8b7 100644 --- a/addons/actions.md +++ b/addons/actions.md @@ -198,7 +198,7 @@ The parameters for these actions have the following meaning: - `icon`: String containing the icon name (as described in [Items]({{base}}/configuration/items.html#icons)) - `severity`: String containing a description of the severity of the incident -**Example** +### Example ```javascript rule "Front Door Notification" @@ -341,9 +341,9 @@ Feel free to extent this list by providing additional language support files. To enable localization, -* copy the file for your language to your OH setup. - * again a folder in `$OH_CONF` folder, such as `$OH_CONF/services` is proposed. -* use function 'Ephemeris.getHolidayDescription' to convert the name according to your localization file. +- copy the file for your language to your OH setup. + - again a folder in `$OH_CONF` folder, such as `$OH_CONF/services` is proposed. +- use function 'Ephemeris.getHolidayDescription' to convert the name according to your localization file. ## Installable Actions diff --git a/administration/console.md b/administration/console.md index e58314134..74b653f3d 100644 --- a/administration/console.md +++ b/administration/console.md @@ -9,16 +9,16 @@ title: The Console The console offers the ability to: -* Monitor the [log](logging.html#karaf-console) in realtime -* Manage [bundles](bundles.html) -* Execute [runtime commands](runtime.html) +- Monitor the [log](logging.html#karaf-console) in realtime +- Manage [bundles](bundles.html) +- Execute [runtime commands](runtime.html) ## Accessing the Console The method used to access the console depends on how openHAB was started. -* When started in interactive mode using the provided command line scripts (e.g. `start.sh` or `start.bat`), openHAB naturally transitions directly to the console prompt. -* When started as a service (i.e. when openHAB is running as a background process), access to the console is given by running the `$OPENHAB_RUNTIME/bin/client` (`client.bat` for Windows) script or by [connecting via SSH](#connecting-via-ssh). +- When started in interactive mode using the provided command line scripts (e.g. `start.sh` or `start.bat`), openHAB naturally transitions directly to the console prompt. +- When started as a service (i.e. when openHAB is running as a background process), access to the console is given by running the `$OPENHAB_RUNTIME/bin/client` (`client.bat` for Windows) script or by [connecting via SSH](#connecting-via-ssh). Linux package based installations can also use the command `openhab-cli console`. The default username/password is **openhab:habopen**, so enter `habopen` at the password prompt. @@ -194,6 +194,6 @@ Depending on your system, you may have to substitute [the directory](#console-se sudo sed -i -e "s/sshPort = .*/sshPort = 1234/g" /var/lib/openhab/etc/org.apache.karaf.shell.cfg ``` ----- +--- Please check the [Apache Karaf reference](https://karaf.apache.org/manual/latest/) for more details. diff --git a/administration/jsondb.md b/administration/jsondb.md index 2024a6cbe..403b3a444 100644 --- a/administration/jsondb.md +++ b/administration/jsondb.md @@ -40,7 +40,7 @@ Most data stored in the database is written in a way that should be understandab As stated above, the files are only read during system startup - therefore if you change a file you will need to stop openHAB, make your changes and restart the system for the changes to take effect. ----- +--- openHAB stores configuration information in JSON (JavaScript Object Notation) formatted (structured) text files located in the `OPENHAB_USERDATA/jsondb/` directory. @@ -69,7 +69,7 @@ The system employs two write mechanisms to improve performance where there are m The parameters for the two mechanisms may be modified in UI :arrow_right: Settings :arrow_right: Json Storage 1. _Write delay_ (defaults to 500 ms): Sets the time to wait before writing changes to disk. -This can reduce the number of writes when many changes are being introduced within a short period, and + This can reduce the number of writes when many changes are being introduced within a short period, and 1. _Maximum write delay_ (defaults to 30000 ms): Sets the maximum period the service will wait to write data in cases where changes are happening continually. The service keeps up to five backups of each table. @@ -194,6 +194,7 @@ Step 3. Using UI :arrow_right: Settings :arrow_right: Things, edit the new `ISP_ - Location (from unset to `MyHome`) - Retry (from 1 to 3) - Timeout (from 5000 to 10000) + and save: ![Edit_Thing_UI](./images/ui_edit_thing.png) diff --git a/administration/runtime.md b/administration/runtime.md index 6eb38aa3a..0eabcd60d 100644 --- a/administration/runtime.md +++ b/administration/runtime.md @@ -11,7 +11,7 @@ It is possible to query and even change the state of entities like items or thin {::options toc_levels="3..4"/} -* TOC +- TOC {:toc} ::: tip Note @@ -22,21 +22,21 @@ Some of the described commands are executed on the internal database and could b Query an item's state: -``` +```shell openhab> openhab:status Heating_GF_Corridor OFF ``` Changing an item's state: -``` +```shell openhab> openhab:send Heating_GF_Corridor ON Command has been sent successfully. ``` Get help for a command: -``` +```shell openhab> help openhab:send Usage: openhab:send - sends a command for an item ``` diff --git a/administration/serial.md b/administration/serial.md index ee9b3e061..ff508d9e0 100644 --- a/administration/serial.md +++ b/administration/serial.md @@ -23,18 +23,18 @@ openHABian comes with a menu option to configure the serial ports automatically. If you can see issues related to opening the serial port with Linux, and you are using **non standard serial ports** (e.g. `/dev/ttyAMA0`) you might have to configure openHAB to detect and access the port correctly: -* Adapt Java command line arguments to include `-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0` (where `/dev/ttyAMA0` is the serial port). If you have multiple serial ports to configure, separate them with colon (`:`). Depending on openHAB installation method, you should modify `start.sh`, `start_debug.sh`, `start.bat`, or `start_debug.bat` (standalone/manual installation) or `EXTRA_JAVA_OPTS` in `/etc/default/openhab` (Debian installation) -* Depending on Linux distribution, you might need to add the user running openHAB to `dialout` user group.With Debian openHAB installation: `sudo usermod -a -G dialout openhab`. The user will need to logout from all login instances and log back in to see their new group added. If the user added to this group still cannot get permission, rebooting the box to ensure the new group permission is attached to the user is suggested. -* When using more than one USB-Serial converters, it may happen that the `/dev/ttyUSB0` device is named `/dev/ttyUSB1` after a reboot. To prevent this problem, alias names can be assigned to serial devices by adding them to `/etc/udev/rules.d/99-com.rules`. Example: +- Adapt Java command line arguments to include `-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0` (where `/dev/ttyAMA0` is the serial port). If you have multiple serial ports to configure, separate them with colon (`:`). Depending on openHAB installation method, you should modify `start.sh`, `start_debug.sh`, `start.bat`, or `start_debug.bat` (standalone/manual installation) or `EXTRA_JAVA_OPTS` in `/etc/default/openhab` (Debian installation) +- Depending on Linux distribution, you might need to add the user running openHAB to `dialout` user group.With Debian openHAB installation: `sudo usermod -a -G dialout openhab`. The user will need to logout from all login instances and log back in to see their new group added. If the user added to this group still cannot get permission, rebooting the box to ensure the new group permission is attached to the user is suggested. +- When using more than one USB-Serial converters, it may happen that the `/dev/ttyUSB0` device is named `/dev/ttyUSB1` after a reboot. To prevent this problem, alias names can be assigned to serial devices by adding them to `/etc/udev/rules.d/99-com.rules`. Example: -```bash +```shell SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="AE01F0PD", SYMLINK+="ttyMySensors" SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", ATTRS{serial}=="0001", SYMLINK+="ttyCulStick" ``` You need to find relevant pieces of information using e.g. `udevadm` command line utility: -``` +```shell udevadm info -a -p $(udevadm info -q path -n /dev/ttyACM0) ``` diff --git a/appendix/contributing.md b/appendix/contributing.md index e01fecf44..a4910bd73 100644 --- a/appendix/contributing.md +++ b/appendix/contributing.md @@ -36,20 +36,20 @@ We want to keep the openHAB community awesome, growing and collaborative. We need your help to keep it that way. To help with this we've come up with some general guidelines for the community as a whole: -* **Be nice:** Be courteous, respectful and polite to fellow community members: no +- **Be nice:** Be courteous, respectful and polite to fellow community members: no regional, racial, gender, or other abuse will be tolerated. We like nice people way better than mean ones! -* **Encourage diversity and participation:** Make everyone in our community +- **Encourage diversity and participation:** Make everyone in our community feel welcome, regardless of their background and the extent of their contributions, and do everything possible to encourage participation in our community. -* **Keep it legal:** Basically, don't get us in trouble. Share only content that +- **Keep it legal:** Basically, don't get us in trouble. Share only content that you own, do not share private or sensitive information, and don't break the law. -* **Stay on topic:** Make sure that you are posting to the correct channel +- **Stay on topic:** Make sure that you are posting to the correct channel and avoid off-topic discussions. Remember when you update an issue or respond to an email you are potentially sending to a large number of people. Please consider this before you update. Also remember that diff --git a/appendix/help.md b/appendix/help.md index 37c8b431e..9763e8c4c 100644 --- a/appendix/help.md +++ b/appendix/help.md @@ -10,13 +10,13 @@ title: Finding Help and FAQs openHAB is surrounding by an amazing community helping new users, discussing problems and providing tutorials and examples. Join today and find answers for all details of openHAB: -* [community.openhab.org](https://community.openhab.org) +- [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. Check there before posting your own questions and feel free to add questions and answers: -* [openHAB 2 FAQs at community.openhab.org](https://community.openhab.org/t/frequently-asked-questions/17727) +- [openHAB 2 FAQs at community.openhab.org](https://community.openhab.org/t/frequently-asked-questions/17727) {% include contribution-wanted.html %} diff --git a/concepts/audio.md b/concepts/audio.md index 040a9a4b9..b23d03e6f 100644 --- a/concepts/audio.md +++ b/concepts/audio.md @@ -13,26 +13,26 @@ 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*. -![](images/audio.png) +![audio](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. + 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. -Typical audio source services are microphones. Typically, a continuous stream is expected from them. + 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. 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. -Each voice supports exactly one locale. + 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. -They provide information about supported formats and locales. + 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) +![hli](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. diff --git a/concepts/categories.md b/concepts/categories.md index ee1f4e969..c2be2950d 100644 --- a/concepts/categories.md +++ b/concepts/categories.md @@ -23,34 +23,34 @@ The list of all predefined categories can be found in our categories overview: | Category | Description | Icon Example | |------------------|------------------------------------------------------------------------------------------------------|-----------------| -| Battery | Batteries, Energy Storages | ![](/iconsets/classic/battery.png) | -| Blinds | Roller shutters, window blinds, etc. | ![](/iconsets/classic/blinds.png) | -| Camera | All kinds of cameras | ![](/iconsets/classic/camera.png) | +| Battery | Batteries, Energy Storages | ![battery](/iconsets/classic/battery.png) | +| Blinds | Roller shutters, window blinds, etc. | ![blinds](/iconsets/classic/blinds.png) | +| Camera | All kinds of cameras | ![camera](/iconsets/classic/camera.png) | | Car | Smart Cars | | | CleaningRobot | Vacuum robots, mopping robots, etc. | | -| Door | Door | ![](/iconsets/classic/door.png) | -| FrontDoor | Front Door | ![](/iconsets/classic/frontdoor.png) | -| GarageDoor | Garage Door | ![](/iconsets/classic/garagedoor.png) | +| Door | Door | ![door](/iconsets/classic/door.png) | +| FrontDoor | Front Door | ![frontdoor](/iconsets/classic/frontdoor.png) | +| GarageDoor | Garage Door | ![garagedoor](/iconsets/classic/garagedoor.png) | | HVAC | Air condition devices, Fans | | | Inverter | Power inverter, such as solar inverters etc. | | -| LawnMower | Lawn mowing robots, etc. | ![](/iconsets/classic/lawnmower.png) | -| Lightbulb | Devices that illuminate something, such as bulbs, etc. | ![](/iconsets/classic/lightbulb.png) | -| Lock | Devices whose primary pupose is locking something | ![](/iconsets/classic/lock.png) | +| LawnMower | Lawn mowing robots, etc. | ![lawnmower](/iconsets/classic/lawnmower.png) | +| Lightbulb | Devices that illuminate something, such as bulbs, etc. | ![lightbulb](/iconsets/classic/lightbulb.png) | +| Lock | Devices whose primary pupose is locking something | ![lock](/iconsets/classic/lock.png) | | MotionDetector | Motion sensors/detectors | | | NetworkAppliance | Bridges/Gateway need to access other devices like used by Philips Hue for example, Routers, Switches | | -| PowerOutlet | Small devices to be plugged into a power socket in a wall which stick there | ![](/iconsets/classic/poweroutlet.png) | -| Projector | Devices that project a picture somewhere | ![](/iconsets/classic/projector.png) | +| PowerOutlet | Small devices to be plugged into a power socket in a wall which stick there | ![poweroutlet](/iconsets/classic/poweroutlet.png) | +| Projector | Devices that project a picture somewhere | ![projector](/iconsets/classic/projector.png) | | RadiatorControl | Controls on radiators used to heat up rooms | | -| Receiver | Audio/Video receivers, i.e. radio receivers, satelite or cable receivers, recorders, etc. | ![](/iconsets/classic/receiver.png) | -| Screen | Devices that are able to show a picture | ![](/iconsets/classic/screen.png) | +| Receiver | Audio/Video receivers, i.e. radio receivers, satelite or cable receivers, recorders, etc. | ![receiver](/iconsets/classic/receiver.png) | +| Screen | Devices that are able to show a picture | ![screen](/iconsets/classic/screen.png) | | Sensor | Device used to measure something | | -| Siren | Siren used by Alarm systems | ![](/iconsets/classic/siren.png) | +| Siren | Siren used by Alarm systems | ![siren](/iconsets/classic/siren.png) | | SmokeDetector | Smoke detectors | | | Speaker | Devices that are able to play sounds | | -| WallSwitch | Any device attached to the wall that controls a binary status of something, for ex. a light switch | ![](/iconsets/classic/wallswitch.png) | +| WallSwitch | Any device attached to the wall that controls a binary status of something, for ex. a light switch | ![wallswitch](/iconsets/classic/wallswitch.png) | | WebService | Account with credentials for a website | | -| Window | Window | ![](/iconsets/classic/window.png) | -| WhiteGood | Devices that look like Waschingmachines, Dishwashers, Dryers, Fridges, Ovens, etc. | ![](/iconsets/classic/whitegood.png) | +| Window | Window | ![window](/iconsets/classic/window.png) | +| WhiteGood | Devices that look like Waschingmachines, Dishwashers, Dryers, Fridges, Ovens, etc. | ![whitegood](/iconsets/classic/whitegood.png) | ### Channel Group Categories @@ -62,72 +62,72 @@ The Channel type definition allows to specify a category. A Binding should classify each Channel into one of the existing categories or leave the category blank, if there is no good match. There are different types of categories for Channels, which are listed below. -#### Widgets +### Widgets | Category | Icon Example | |---------------|------------------------------------------| -| Colorpicker | ![](/iconsets/classic/colorpicker.png) | -| Number | ![](/iconsets/classic/number.png) | -| Rollershutter | ![](/iconsets/classic/rollershutter.png) | -| Slider | ![](/iconsets/classic/slider.png) | -| Switch | ![](/iconsets/classic/switch.png) | -| Text | ![](/iconsets/classic/text.png) | -| Group | ![](/iconsets/classic/group.png) | +| Colorpicker | ![colorpicker](/iconsets/classic/colorpicker.png) | +| Number | ![number](/iconsets/classic/number.png) | +| Rollershutter | ![rollershutter](/iconsets/classic/rollershutter.png) | +| Slider | ![slider](/iconsets/classic/slider.png) | +| Switch | ![switch](/iconsets/classic/switch.png) | +| Text | ![text](/iconsets/classic/text.png) | +| Group | ![group](/iconsets/classic/group.png) | #### Weather | Category | Icon Example | |-------------|----------------------------------------| -| Sun | ![](/iconsets/classic/sun.png) | -| Moon | ![](/iconsets/classic/moon.png) | -| Clouds | ![](/iconsets/classic/clouds.png) | -| Sun_Clouds | ![](/iconsets/classic/sun_clouds.png) | -| Rain | ![](/iconsets/classic/rain.png) | -| Snow | ![](/iconsets/classic/snow.png) | -| Wind | ![](/iconsets/classic/wind.png) | -| Humidity | ![](/iconsets/classic/humidity.png) | -| Temperature | ![](/iconsets/classic/temperature.png) | +| Sun | ![sun](/iconsets/classic/sun.png) | +| Moon | ![moon](/iconsets/classic/moon.png) | +| Clouds | ![clouds](/iconsets/classic/clouds.png) | +| Sun_Clouds | ![sun_clouds](/iconsets/classic/sun_clouds.png) | +| Rain | ![rain](/iconsets/classic/rain.png) | +| Snow | ![snow](/iconsets/classic/snow.png) | +| Wind | ![wind](/iconsets/classic/wind.png) | +| Humidity | ![humidity](/iconsets/classic/humidity.png) | +| Temperature | ![temperature](/iconsets/classic/temperature.png) | #### Properties | Category | Icon Example | |------------------|---------------------------------------------| -| BatteryLevel | ![](/iconsets/classic/batterylevel.png) | -| LowBattery | ![](/iconsets/classic/lowbattery.png) | -| CarbonDioxide | ![](/iconsets/classic/carbondioxide.png) | -| Energy | ![](/iconsets/classic/energy.png) | -| Gas | ![](/iconsets/classic/gas.png) | -| Oil | ![](/iconsets/classic/oil.png) | -| Water | ![](/iconsets/classic/water.png) | -| Light | ![](/iconsets/classic/light.png) | -| ColorLight | ![](/iconsets/classic/colorlight.png) | -| Temperature | ![](/iconsets/classic/temperature.png) | -| Smoke | ![](/iconsets/classic/smoke.png) | -| SoundVolume | ![](/iconsets/classic/soundvolume.png) | -| Pressure | ![](/iconsets/classic/pressure.png) | -| Fire | ![](/iconsets/classic/fire.png) | -| Motion | ![](/iconsets/classic/motion.png) | -| QualityOfService | ![](/iconsets/classic/qualityofservice.png) | -| Moisture | ![](/iconsets/classic/moisture.png) | -| Noise | ![](/iconsets/classic/noise.png) | -| Flow | ![](/iconsets/classic/flow.png) | -| Price | ![](/iconsets/classic/price.png) | -| Time | ![](/iconsets/classic/time.png) | +| BatteryLevel | ![batterylevel](/iconsets/classic/batterylevel.png) | +| LowBattery | ![lowbattery](/iconsets/classic/lowbattery.png) | +| CarbonDioxide | ![carbondioxide](/iconsets/classic/carbondioxide.png) | +| Energy | ![energy](/iconsets/classic/energy.png) | +| Gas | ![gas](/iconsets/classic/gas.png) | +| Oil | ![oil](/iconsets/classic/oil.png) | +| Water | ![water](/iconsets/classic/water.png) | +| Light | ![light](/iconsets/classic/light.png) | +| ColorLight | ![colorlight](/iconsets/classic/colorlight.png) | +| Temperature | ![temperature](/iconsets/classic/temperature.png) | +| Smoke | ![smoke](/iconsets/classic/smoke.png) | +| SoundVolume | ![soundvolume](/iconsets/classic/soundvolume.png) | +| Pressure | ![pressure](/iconsets/classic/pressure.png) | +| Fire | ![fire](/iconsets/classic/fire.png) | +| Motion | ![motion](/iconsets/classic/motion.png) | +| QualityOfService | ![qualityofservice](/iconsets/classic/qualityofservice.png) | +| Moisture | ![moisture](/iconsets/classic/moisture.png) | +| Noise | ![noise](/iconsets/classic/noise.png) | +| Flow | ![flow](/iconsets/classic/flow.png) | +| Price | ![price](/iconsets/classic/price.png) | +| Time | ![time](/iconsets/classic/time.png) | #### Control | Category | Icon Example | |--------------|-----------------------------------------| -| Heating | ![](/iconsets/classic/heating.png) | -| MediaControl | ![](/iconsets/classic/mediacontrol.png) | -| MoveControl | ![](/iconsets/classic/movecontrol.png) | -| Zoom | ![](/iconsets/classic/zoom.png) | +| Heating | ![heating](/iconsets/classic/heating.png) | +| MediaControl | ![mediacontrol](/iconsets/classic/mediacontrol.png) | +| MoveControl | ![movecontrol](/iconsets/classic/movecontrol.png) | +| Zoom | ![zoom](/iconsets/classic/zoom.png) | #### Purpose | Category | Icon Example | |----------|-------------------------------------| -| Alarm | ![](/iconsets/classic/alarm.png) | -| Presence | ![](/iconsets/classic/presence.png) | -| Vacation | ![](/iconsets/classic/vacation.png) | -| Party | ![](/iconsets/classic/party.png) | +| Alarm | ![alarm](/iconsets/classic/alarm.png) | +| Presence | ![presence](/iconsets/classic/presence.png) | +| Vacation | ![vacation](/iconsets/classic/vacation.png) | +| Party | ![party](/iconsets/classic/party.png) | diff --git a/concepts/discovery.md b/concepts/discovery.md index 974811e9e..a6fec28dc 100644 --- a/concepts/discovery.md +++ b/concepts/discovery.md @@ -11,7 +11,7 @@ Many devices, technologies and systems can be automatically discovered on the ne openHAB bindings therefore implement _Discovery Services_ for Things, which provide _Discovery Results_. All _Discovery Results_ are regarded as suggestions to the user and are put into the _inbox_. -### Background Discovery +## Background Discovery Some discovery services support automatic discovery in the background, while for others a scan needs to be triggered manually. Services that support background discovery usually have it enabled by default. diff --git a/concepts/profiles.md b/concepts/profiles.md index 0bafc2c1f..71a76a27e 100644 --- a/concepts/profiles.md +++ b/concepts/profiles.md @@ -17,12 +17,12 @@ With this, it is possible to take into account the temporal dimension when calcu There exist two different kinds of profiles: state and trigger profiles. -### State Profiles +## State Profiles 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 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. diff --git a/concepts/things.md b/concepts/things.md index 3c80d8a72..9145e3409 100644 --- a/concepts/things.md +++ b/concepts/things.md @@ -12,7 +12,7 @@ From a user perspective, they are relevant for the setup and configuration proce Things can have configuration properties, which can be optional or mandatory. Such properties can be basic information like an IP address, an access token for a web service or a device specific configuration that alters its behavior. -### Channels +## Channels Things provide "Channels", which represent the different functions the Thing provides. Where the Thing is the physical entity or source of information, the Channel is a concrete function from this Thing. @@ -23,13 +23,13 @@ Channels are linked to Items, where such links are the glue between the virtual Once such a link is established, a Thing reacts to events sent for an item that is linked to one of its Channels. Likewise, it actively sends out events for Items linked to its Channels. -### Bridges +## Bridges A special type of Thing is a "bridge". Bridges are Things that need to be added to the system in order to gain access to other Things. A typical example of a bridge is an IP gateway for some non-IP based home automation system or a web service configuration with authentication information which every Thing from this web service might need. -### Discovery +## Discovery As many Things can be automatically discovered, there are special mechanisms available that deal with the handling of [automatically discovered Things](discovery.html). diff --git a/concepts/units-of-measurement.md b/concepts/units-of-measurement.md index 6ac902ffa..9683e5d6d 100644 --- a/concepts/units-of-measurement.md +++ b/concepts/units-of-measurement.md @@ -41,28 +41,30 @@ The unit given in the state description is parsed and then used for conversion ( The framework assumes that the unit to parse is always the last token in the state description. If the parsing failed the locale-based default conversion takes place. - Number:Temperature temperature "Outside [%.2f °F]" { channel="...:current#temperature" } +`Number:Temperature temperature "Outside [%.2f °F]" { channel="...:current#temperature" }` In the example the `NumberItem` is specified to bind to Channels which offer values from the dimension `Temperature`. Without the dimension information the `NumberItem` only will receive updates of type `DecimalType` without a unit and any conversion. The state description defines two decimal places for the value and the fix unit °F. In case the state description should display the unit the binding delivers or the framework calculates through locale-based conversion the pattern will look like this: - "Outside [%.2f %unit%]" +`"Outside [%.2f %unit%]"` The special placeholder `%unit%` will then be replaced by the actual unit symbol. The placeholder `%unit%` can be placed anywhere in the state description. -#### Defining ChannelTypes +### Defining ChannelTypes 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 - - Current temperature - - +```xml + + Number:Temperature + + Current temperature + + +``` The state description pattern "%.1f %unit%" describes the value format as floating point with one decimal place and also the special placeholder for the unit. @@ -212,7 +214,7 @@ Binary Prefixes: To use the prefixes simply add the prefix to the unit symbol - for example: -* milliAmpere - `mA` -* centiMetre - `cm` -* kiloWatt - `kW` -* KibiByte - `KiB` +- milliAmpere - `mA` +- centiMetre - `cm` +- kiloWatt - `kW` +- KibiByte - `KiB` diff --git a/configuration/editors.md b/configuration/editors.md index 3f35b573c..f573008e9 100644 --- a/configuration/editors.md +++ b/configuration/editors.md @@ -15,7 +15,7 @@ This documentation page can give you some guidance in choosing the right one for - TOC {:toc} -### Network Preparations +## Network Preparations Any editors used to configure openHAB need to be able to access the configuration files on the remote openHAB host. @@ -38,8 +38,9 @@ You can find it in the [Microsoft Visual Studio Marketplace](https://marketplace ### Installation 1. Install [Visual Studio Code](https://code.visualstudio.com/Download) on your desktop computer (not on the openHAB host) -2. Open the extension sidebar.
![openHAB VS Code Extension alternative installation](images/vscode_extensiontab_icon.png) -3. Search for openHAB and install the extension. +1. Open the extension sidebar. + ![openHAB VS Code Extension alternative installation](images/vscode_extensiontab_icon.png) +1. Search for openHAB and install the extension. [Visit the Extensions GitHub Page for further Informations](https://github.com/openhab/openhab-vscode/blob/master/README.md "GitHub Repo for the VS Code Extension") diff --git a/configuration/habpanel.md b/configuration/habpanel.md index 3939b40a9..9706c9965 100644 --- a/configuration/habpanel.md +++ b/configuration/habpanel.md @@ -35,7 +35,7 @@ Even when there is an active panel configuration, HABPanel uses the browser's st HABPanel uses service configuration variables to store its data on the openHAB server. They can be accessed using Paper UI (_Configuration > Services > UI > HABPanel > Configure_) or in the openHAB Karaf console: -``` +```shell openhab> config:edit org.openhab.habpanel openhab> config:property-get ``` @@ -60,13 +60,13 @@ Use the gears icon in the top-right corner to switch between the two modes. 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; -* Drag the arrow icons in the top-left corner of each tile to move it; -* Resize tiles with the chevron (triangle) in the bottom-right corner of each tile; -* Configure the tiles and the dashboards themselves with the gears icons in the top-right corner of each tile; -* Enter the dashboard designer by clicking inside a tile. +- 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; +- Drag the arrow icons in the top-left corner of each tile to move it; +- Resize tiles with the chevron (triangle) in the bottom-right corner of each tile; +- Configure the tiles and the dashboards themselves with the gears icons in the top-right corner of each tile; +- Enter the dashboard designer by clicking inside a tile. The configuration dialog when clicking on a tile's gear icon contains the following settings: @@ -93,8 +93,8 @@ The side drawer can be accessed from any screen by a swipe or drag to the right It is comprised of three parts: 1. A **header** - clicking on it returns to the main menu. Note: if defined, the title of the panel is displayed instead of the default "HABPanel" label, it is configured in the settings (see below); -2. A **list of dashboards** for quick switching between dashboards without going back to the main menu - they are presented in the order of the menu (sorted by row, then by column); -3. A **footer** displaying the current date & time and featuring a link to the settings screen (if available). +1. A **list of dashboards** for quick switching between dashboards without going back to the main menu - they are presented in the order of the menu (sorted by row, then by column); +1. A **footer** displaying the current date & time and featuring a link to the settings screen (if available). ### The dashboard designer diff --git a/configuration/index.md b/configuration/index.md index dc6a52488..947a1a301 100644 --- a/configuration/index.md +++ b/configuration/index.md @@ -157,14 +157,14 @@ All text files must be created with UTF-8 encoding. When using Visual Studio Cod Here are some hints to avoid some common pitfalls when starting out. -* Start by modelling your house using a Semantic Model in Main UI. +- Start by modelling your house using a Semantic Model in Main UI. Use it to create groups for rooms and apply proper semantic tags right away. This will ultimately save a lot of setup work, as it will allow for group functions such as "switch off lights in _kitchen_" or _ground floor_ or _house_" and also enable voice assistants to properly execute your instructions. Be careful to apply a consistent naming scheme right in the beginning. -* Use Main UI to manage Things. Remember that once initially configured, their configuration will not change much over time. -* Run autodiscovery for _Things_ wherever offered so that you don't have to enter all of them manually -* Also use Main UI to manage Items. +- Use Main UI to manage Things. Remember that once initially configured, their configuration will not change much over time. +- Run autodiscovery for _Things_ wherever offered so that you don't have to enter all of them manually +- Also use Main UI to manage Items. 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). +- 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 734e0e164..d24b595a7 100644 --- a/configuration/items.md +++ b/configuration/items.md @@ -34,7 +34,7 @@ There are two methods for defining Items: 1. Through UI -2. Through text `.items` files located in the `$OPENHAB_CONF/items` folder. +1. 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. @@ -192,7 +192,7 @@ Two naming schemes are established in the community for Group names: 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) +1. Prepend a lowercase "g" to the name (e.g. gBattery) | Group Name | Interpretation | |-------------------------------------------|-----------------------------------------------------------------------| @@ -651,7 +651,7 @@ Any future expiring update or command is cancelled, if the item receives an upda The parameter accepts a duration of time that can be a combination of hours, minutes and seconds in the format -``` +```shell expire="1h 30m 45s" expire="1h05s" expire="55h 59m 12s" @@ -663,7 +663,7 @@ Whitespaces are allowed between the sections. This duration can optionally be followed by a comma and the state or command to post, when the timer expires. If this optional section is not present, it defaults to the Undefined (`UnDefType.UNDEF`) state. -``` +```shell Player MyPlayer { expire="1h,command=STOP" } // send STOP command after one hour Number MyChannel { expire="5m,state=0" } // update state to 0 after five minutes String MyMessage { expire="3m12s,Hello" } // update state to Hello after three minutes and 12 seconds diff --git a/configuration/jsr223.md b/configuration/jsr223.md index dc5296d73..daaffda84 100644 --- a/configuration/jsr223.md +++ b/configuration/jsr223.md @@ -138,8 +138,6 @@ For example, with the following scripts and directory structure... ... the load order will be: `/001_script.py`, `/dir1/001_script.py`, `/dir2/002_script.py`, `/script.py`, `/dir1/script.py`, `/dir2/script.py`. - - ### `ScriptExtension` Objects (all JSR223 languages) To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined within `ScriptExtension` presets. @@ -151,8 +149,6 @@ The `default` preset is preloaded, so it does not require importing. - [`RuleSupport`](#rulesupport_presets) - [`RuleFactories`](#rulefactories_presets) - - #### Default Preset (`importPreset` not required) | Variable | Description | @@ -217,8 +213,6 @@ The `default` preset is preloaded, so it does not require importing. | `scriptExtension` | (internal) For loading script presets. | | `se` | Alias for `scriptExtension` | - - ##### `events` operations - `events.postUpdate(String, String)` @@ -232,8 +226,6 @@ The `default` preset is preloaded, so it does not require importing. - `events.storeStates(Item...)` - `events.restoreStates(Map)` - - #### RuleSimple Preset These variables and classes are loaded using: @@ -257,8 +249,6 @@ See language-specific documentation for examples. | TriggerType | `org.openhab.core.automation.type.TriggerType` | | Visibility | `org.openhab.core.automation.Visibility` enum | - - #### `RuleSupport` Preset These variables and classes are loaded using: @@ -281,8 +271,6 @@ scriptExtension.importPreset("RuleSupport") | automationManager | Instance for managing rules and other openHAB module instances. (e.g., `addRule`) | | ruleRegistry | `org.openhab.core.automation.Rule` | - - #### `RuleFactories` Preset >Note: Advanced usage @@ -297,73 +285,58 @@ scriptExtension.importPreset("RuleFactories") | `ConditionHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedConditionHandlerFactory` | | `TriggerHandlerFactory` | `org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory` | - - ### `TriggerType` Objects (all JSR223 languages) The following trigger types are defined by openHAB (custom triggers can also be defined) and take the specified configuration parameters. All parameters are Strings. Read the JSR223 language specific documentation for examples of using these `TriggerType` objects. -
- timer.GenericCronTrigger +::: details timer.GenericCronTrigger | Parameter | Description | |-----------|-------------| | `cronExpression` | The cron expression | -
- -
- timer.TimeOfDayTrigger +::: +::: details timer.TimeOfDayTrigger | Parameter | Description | |-----------|-------------| | `time` | The time in "hh:mm" format | -
- -
- core.ItemCommandTrigger +::: +::: details core.ItemCommandTrigger | Parameter | Description | |-----------|-------------| | `itemName` | The name of the `Item` | | `command` | The `Command` (optional) | -
- -
- core.ItemStateUpdateTrigger +::: +::: details core.ItemStateUpdateTrigger | Parameter | Description | |-----------|-------------| | `itemName` | The name of the `Item` | | `state` | The `State` (optional) | -
- -
- core.ItemStateChangeTrigger +::: +::: details core.ItemStateChangeTrigger | Parameter | Description | |-----------|-------------| | `itemName` | The name of the `Item` | | `previousState` | The previous `State` (optional) | | `state` | The `State` (optional) | -
- -
- core.ChannelEventTrigger +::: +::: details core.ChannelEventTrigger | Parameter | Description | |-----------|-------------| | `channelUID` | The `ChannelUID` of the `Channel` | | `event` | The `Channel` trigger `Event` (optional) | -
- -
- core.GenericEventTrigger +::: +::: details core.GenericEventTrigger | Parameter | Description | |-----------|-------------| | `eventTopic` | Default: "openhab/\*"

Events can also be filtered, e.g.
Item events: "openhab/items/\*/"
Channel events: "openhab/channels/\*/triggered"
Thing events: "openhab/things/\*/" | | `eventSource` | `Item` name, `ChannelUID`, `ThingUID`, etc. | | `eventTypes` | `ItemCommandEvent`, `ItemStateEvent`, `ItemStateChangedEvent`, `GroupItemStateChangedEvent`, `ItemAddedEvent`, `ItemRemovedEvent`, `ThingAddedEvent`, `ThingRemovedEvent`, `ThingStatusInfoChangedEvent`, `ThingStatusInfoEvent`, `ThingUpdatedEvent`, etc. | -
+::: diff --git a/configuration/paperui.md b/configuration/paperui.md deleted file mode 100644 index 68d193468..000000000 --- a/configuration/paperui.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: documentation -title: Configuration though Paper UI ---- - -{% include base.html %} - -# 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: - Easily install or uninstall openHAB add-ons - ![extensions](images/paperui1.png) - -- Thing discovery: - See devices and services found on your network and add them to your setup. - ![discovery](images/paperui2.png) - -- 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) - -Note that you still need to define your items, sitemaps, persistence configurations and rules in the according config files (as done in openHAB 1). Such functionality will be added bit by bit to the Paper UI only. - -Here you can find a small screencast about the Paper UI: - -[![Paper UI](https://img.youtube.com/vi/MV2a5qwtmRE/0.jpg)](https://www.youtube.com/watch?v=MV2a5qwtmRE) - -{% include contribution-wanted.html %} diff --git a/configuration/persistence.md b/configuration/persistence.md index 1fc03f6a3..3c2128136 100644 --- a/configuration/persistence.md +++ b/configuration/persistence.md @@ -194,7 +194,7 @@ These extensions use the default persistence service. (Refer to 'Default Persistence Service' above to configure this.) You may specify a different persistence service by appending a String as an optional additional parameter at the end of the extension. -#### Examples +### Examples To persist an Item called `Lights` in an rrd4j database, you would enter the following: `Lights.persist("rrd4j")` diff --git a/configuration/restdocs.md b/configuration/restdocs.md index 3432e6490..1042614e6 100644 --- a/configuration/restdocs.md +++ b/configuration/restdocs.md @@ -92,7 +92,7 @@ You can manage all access tokens in your profile settings in the Main UI. It is possible to disable authentication. Stop openhab and add this part to ```$OPENHAB_USERDATA/etc/org.apache.karaf.features.xml``` before ``````: -``` +```xml openhab-*-auth diff --git a/configuration/rules-dsl.md b/configuration/rules-dsl.md index be18f0118..5d3a66087 100644 --- a/configuration/rules-dsl.md +++ b/configuration/rules-dsl.md @@ -189,12 +189,12 @@ Time cron "" A cron expression takes the form of six or optionally seven fields: 1. Seconds -2. Minutes -3. Hours -4. Day-of-Month -5. Month -6. Day-of-Week -7. Year (optional field) +1. Minutes +1. Hours +1. Day-of-Month +1. Month +1. Day-of-Week +1. Year (optional field) 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. @@ -357,8 +357,8 @@ 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)`. +- the following command ***will fail***: ~~sendCommand(MyItem, new_state)~~. +- However, the following command **will work**: `MyItem.sendCommand(new_state)`. Using `MyItem.postUpdate(new_state)` or `MyItem.sendCommand(new_state)` will create the most stable code. It provides by far the best option for avoiding most problems. @@ -569,7 +569,7 @@ DecimalType and QuantityType are also java.lang.Number so all the conversions li Here some other commonly needed conversions: -* For DecimalType states: +- For DecimalType states: ```java // convert integer_number to string containing hex_code @@ -584,7 +584,7 @@ var myNumber = Long.parseLong(hex, 16) as Number var DecimalType parsedResult = new DecimalType(Long.parseLong(hex_code, 16)) ``` -* For QuantityType states: +- For QuantityType states: ```java // define a QuantityType variable @@ -649,7 +649,7 @@ val stateAsString = MyStringItem.state.toString In case an item returns a string containing a value as a hexadecimal number, it can be converted to an integer by using -``` +```shell //Loading hexvalue from string val itemvalue = new java.math.BigDecimal(Integer::parseInt(myHexValue, 16)) ``` diff --git a/configuration/rules-ng.md b/configuration/rules-ng.md index 4f55530fe..298a72674 100644 --- a/configuration/rules-ng.md +++ b/configuration/rules-ng.md @@ -53,42 +53,50 @@ Those use predefined configurations and/or modified module input/output objects. A given **Module type** has the following elements: - uid - unique id - label - localizable text - description - localizable text - configDescriptions - list of meta data for the configuration properties - input variables - list of meta data for the supported input objects - output variables - list of meta data for the supported output objects +```text +uid - unique id +label - localizable text +description - localizable text +configDescriptions - list of meta data for the configuration properties +input variables - list of meta data for the supported input objects +output variables - list of meta data for the supported output objects +``` **configDescriptions** has the following metadata defined for each property: - name - type - one of the following "text", "integer", "decimal", "boolean" - label - localizable text - description - localizable text - required - boolean flag indicating if this configuration property can be optional and thus it can be ommited in the rule, by default required is false - defaultValue - default value for the configuration property when not specified in the rule +```text +name +type - one of the following "text", "integer", "decimal", "boolean" +label - localizable text +description - localizable text +required - boolean flag indicating if this configuration property can be optional and thus it can be ommited in the rule, by default required is false +defaultValue - default value for the configuration property when not specified in the rule +``` **Input property** has the following metadata: - name - type - fully qualified name of Java class ("java.lang.Integer") - label - localizable text - description - localizable text - 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 +```text +name +type - fully qualified name of Java class ("java.lang.Integer") +label - localizable text +description - localizable text +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 - type - fully qualified name of Java class ("java.lang.Integer") - label - localizable text - description - localizable text - defaultValue - default value for the configuration property when not specified in the rule - reference - which means the property value can be specified as a reference to configuration parameter or input parameter - tags - shows how a given value should be considered (e.g. as a Temperature) +```text +name +type - fully qualified name of Java class ("java.lang.Integer") +label - localizable text +description - localizable text +defaultValue - default value for the configuration property when not specified in the rule +reference - which means the property value can be specified as a reference to configuration parameter or input parameter +tags - shows how a given value should be considered (e.g. as a Temperature) +``` -**Supported Types** +### Supported Types The types supported in the **input/output** objects can be any string and the following validation is performed: @@ -107,15 +115,15 @@ 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:** -``` +```json { "uid":"sample.rule1", "name":"SampleRule", @@ -155,9 +163,9 @@ The types in the **Configuration** object are restricted to the following: } ``` -* **Sample module types:** +- **Sample module types:** -``` +```json "triggers":[ { "uid":"SampleTrigger", @@ -197,7 +205,7 @@ The types in the **Configuration** object are restricted to the following: ] ``` -``` +```json "conditions":[ { "uid":"SampleCondition", @@ -230,7 +238,7 @@ The types in the **Configuration** object are restricted to the following: ] ``` -``` +```json "actions":[ { "uid":"SampleAction", @@ -294,30 +302,30 @@ 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/rules - lists rule instances. +- http:///rest/module-types - lists module types. +- http:///rest/templates" - lists rule templates. +- http:///rest/rules - lists rule instances. -#### /rest/templates +### /rest/templates - 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 +### /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. -#### /rest/rules +### /rest/rules - GET /rest/rules - returns all registered rule instances. - POST /rest/rules - adds new rule instance to the rule registry. @@ -394,9 +402,9 @@ 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:** -``` +```json { "uid": "sample.rulebytemplate", "name": "RuleByTemplate", @@ -412,9 +420,9 @@ This will not have any impact on the already imported rules. } ``` -* **Sample rule template:** +- **Sample rule template:** -``` +```json { "uid":"SampleRuleTemplate", "description":"Sample Rule Template", @@ -486,89 +494,93 @@ The above example uses two rule configuration properties: GenericEventTrigger has 3 configuration paramters: `eventTopic`,`eventSource` and `eventTypes` and one output: 'event'. +```json +{ + "uid":"GenericEventTrigger", + "label":"Basic Event Trigger", + "description":"Triggers Rules on Events", + "configDescriptions":[ { - "uid":"GenericEventTrigger", - "label":"Basic Event Trigger", - "description":"Triggers Rules on Events", - "configDescriptions":[ - { - "name":"eventTopic", - "type":"TEXT", - "label":"Topic", - "description":"This is the topic, the trigger will listen to: >>openhab/*<<", - "required":true, - "defaultValue":"openhab/*" - }, - { - "name":"eventSource", - "type":"TEXT", - "label":"Source", - "description":"This is the source of the event (eg. item name)", - "required":true, - "defaultValue":"" - }, - { - "name":"eventTypes", - "type":"TEXT", - "label":"Event Type", - "description":"the event type, the trigger should listen to. Multiple types can be specified comma-separated", - "required":true, - "defaultValue":"" - } - ], - "outputs":[ - { - "name":"event", - "type":"org.openhab.core.events.Event", - "label":"Event", - "description":"The events which was sent.", - "reference":"event" - } - ] + "name":"eventTopic", + "type":"TEXT", + "label":"Topic", + "description":"This is the topic, the trigger will listen to: >>openhab/*<<", + "required":true, + "defaultValue":"openhab/*" + }, + { + "name":"eventSource", + "type":"TEXT", + "label":"Source", + "description":"This is the source of the event (eg. item name)", + "required":true, + "defaultValue":"" + }, + { + "name":"eventTypes", + "type":"TEXT", + "label":"Event Type", + "description":"the event type, the trigger should listen to. Multiple types can be specified comma-separated", + "required":true, + "defaultValue":"" } + ], + "outputs":[ + { + "name":"event", + "type":"org.openhab.core.events.Event", + "label":"Event", + "description":"The events which was sent.", + "reference":"event" + } + ] +} +``` ### GenericCompareCondition This module type is used to compare a value against a configuration property using an operator like `<, >, =`. The value to be compared can be specified either as an input or as a configuration property. - { - "uid":"GenericCompareCondition", - "label":"CompareCondition", - "description":"configurable compare condition", - "configDescriptions":[ - { - "name":"inputproperty", - "label":"Input property", - "type":"TEXT", - "description":"property of the input to be compared", - "required":false - }, - { - "name":"right", - "type":"TEXT", - "label":"compare with", - "description":"the value to be compared with the input", - "required":true - }, - { - "name":"operator", - "type":"TEXT", - "description":"the compare operator, allowed are <, >, =", - "required":true, - "defaultValue":"=" - } - ], - "inputs": [ - { - "name":"input", - "type": "java.lang.Object", - "label": "input", - "description": "The input which will be compared.", - "required":true - } - ] - } +```json +{ + "uid":"GenericCompareCondition", + "label":"CompareCondition", + "description":"configurable compare condition", + "configDescriptions":[ + { + "name":"inputproperty", + "label":"Input property", + "type":"TEXT", + "description":"property of the input to be compared", + "required":false + }, + { + "name":"right", + "type":"TEXT", + "label":"compare with", + "description":"the value to be compared with the input", + "required":true + }, + { + "name":"operator", + "type":"TEXT", + "description":"the compare operator, allowed are <, >, =", + "required":true, + "defaultValue":"=" + } + ], + "inputs": [ + { + "name":"input", + "type": "java.lang.Object", + "label": "input", + "description": "The input which will be compared.", + "required":true + } + ] +} +``` ## Providing new Module Types @@ -586,41 +598,43 @@ 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. +```json +{ + "uid":"ItemStateChangeTrigger", + "label":"Item State Trigger", + "description":"This triggers a rule if an items state changed", + "configDescriptions":[ { - "uid":"ItemStateChangeTrigger", - "label":"Item State Trigger", - "description":"This triggers a rule if an items state changed", - "configDescriptions":[ - { - "name":"itemName", - "type":"TEXT", - "context":"item", - "label":"item name", - "description":"the name of the item which's state change should be observed", - "required":true - } - ], - "children":[ - { - "id":"itemStateChangeTriggerID", - "type":"GenericEventTrigger", - "configuration":{ - "eventSource":"$itemName", - "eventTopic":"openhab/items/*", - "eventTypes":"ItemStateEvent" - } - } - ], - "outputs":[ - { - "name":"event", - "type":"org.openhab.core.events.Event", - "description":"the event of the item state change", - "label":"event", - "reference":"itemStateChangeTriggerID.event" - } - ] + "name":"itemName", + "type":"TEXT", + "context":"item", + "label":"item name", + "description":"the name of the item which's state change should be observed", + "required":true } + ], + "children":[ + { + "id":"itemStateChangeTriggerID", + "type":"GenericEventTrigger", + "configuration":{ + "eventSource":"$itemName", + "eventTopic":"openhab/items/*", + "eventTypes":"ItemStateEvent" + } + } + ], + "outputs":[ + { + "name":"event", + "type":"org.openhab.core.events.Event", + "description":"the event of the item state change", + "label":"event", + "reference":"itemStateChangeTriggerID.event" + } + ] +} +``` 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*. diff --git a/configuration/sitemaps.md b/configuration/sitemaps.md index 328ad0ec9..d2787a69e 100644 --- a/configuration/sitemaps.md +++ b/configuration/sitemaps.md @@ -680,76 +680,3 @@ Explanation: 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. - - diff --git a/configuration/things.md b/configuration/things.md index 3e2cd24a3..06fb1be68 100644 --- a/configuration/things.md +++ b/configuration/things.md @@ -33,11 +33,11 @@ From then on, everything else is configured at the application layer for that en From start to finish, the process for fully configuring a physical entity represented by a Thing looks like this: 1. Identify the binding required for the Thing -2. Install the binding if it has not already been installed -3. Define and configure the Thing -4. Identify the Channels provided by the Thing -5. [Add Items]({{base}}/configuration/items.html) and link them to the Thing's Channels -6. At this point Items can be used to control the Thing or consume its information in e.g. [Sitemaps]({{base}}/configuration/sitemaps.html) or [Rules]({{base}}/configuration/rules-dsl.html) +1. Install the binding if it has not already been installed +1. Define and configure the Thing +1. Identify the Channels provided by the Thing +1. [Add Items]({{base}}/configuration/items.html) and link them to the Thing's Channels +1. At this point Items can be used to control the Thing or consume its information in e.g. [Sitemaps]({{base}}/configuration/sitemaps.html) or [Rules]({{base}}/configuration/rules-dsl.html) There are two methods for defining Things provided by the various bindings: through [discovery]({{base}}/concepts/discovery.html) or by manual definition in configuration text files.