diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 542461de4..f70b08df8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,12 @@ # Contribution Guidelines -### Pull requests are always welcome +## Pull requests are always welcome We are always thrilled to receive pull requests, and do our best to process them as fast as possible. Not sure if that typo is worth a pull request? Do it! We will appreciate it. -### Conventions +## Conventions Fork the repo and make changes on your fork in a feature branch. @@ -28,7 +28,7 @@ comment. Commits that fix or close an issue should include a reference like `Closes #XXX` or `Fixes #XXX`, which will automatically close the issue when merged. -### Sign your work +## Sign your work The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to @@ -36,7 +36,7 @@ pass it on as an open-source patch. The rules are pretty simple: if you can certify the below (from [developercertificate.org](https://developercertificate.org/)): -``` +```text Developer Certificate of Origin Version 1.1 @@ -77,19 +77,19 @@ By making a contribution to this project, I certify that: then you just add a line to every git commit message: - Signed-off-by: Joe Smith +`Signed-off-by: Joe Smith ` using your real name (sorry, no pseudonyms or anonymous contributions.) and an e-mail address under which you can be reached (sorry, no github noreply e-mail addresses (such as username@users.noreply.github.com) or other non-reachable addresses are allowed). -#### Small patch exception +### Small patch exception There are several exceptions to the signing requirement. Currently these are: -* Your patch fixes spelling or grammar errors. -* Your patch is a single line change to documentation. +- Your patch fixes spelling or grammar errors. +- Your patch is a single line change to documentation. ## Community Guidelines @@ -97,22 +97,21 @@ 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 nobody likes spam. - diff --git a/README.md b/README.md index 5752eca19..63b4990bb 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ We will read about them later. Correct, this is done in the original repository of the add-on. You may want to know how to find the right file in all of those repos? This is fairly easy: -on most of the documentation pages on https://openhab.org/, +on most of the documentation pages on , you will find the following link at the bottom, which will point you directly to the file you want to improve. ![Contribution link to a specific page](./images/contribution_link.png) @@ -96,4 +96,4 @@ In short, the following has to be considered: - Versions like "2.1.0" are marked by git tags. - Based on tags branches like "2.1-patch" are created, to include later discovered changes (like fixed links). -When a version is tagged (or updated), a static version of the website has to be generated and copied into the correct sub-folder, this is currently a manual operation described succinctly here: https://github.com/openhab/website/issues/72 +When a version is tagged (or updated), a static version of the website has to be generated and copied into the correct sub-folder, this is currently a manual operation described succinctly here: diff --git a/addons/actions.md b/addons/actions.md index 02de7b8b7..704e2b8d7 100644 --- a/addons/actions.md +++ b/addons/actions.md @@ -59,8 +59,8 @@ One can configure whether specific log entries are logged out and where they get You have different options to execute a command through an action. -- `executeCommandLine(String commandLine)`: Executes a command on the command line without waiting for the command to complete -For example you could run `executeCommandLine("path/to/my/script.sh")` which then would be executed and the rule would continue processing. +- `executeCommandLine(String commandLine)`: Executes a command on the command line without waiting for the command to complete. + For example you could run `executeCommandLine("path/to/my/script.sh")` which then would be executed and the rule would continue processing. - `executeCommandLine(Duration.ofSeconds(timeout), String commandLine)`: Executes a command on the command and waits `timeout` seconds for the command to complete, returning the output from the command as a String For example you could run `var ScriptResponse = executeCommandLine(Duration.ofSeconds(60), "path/to/my/script.sh");` would get executed and wait 1 minute for the output to be responded back and write it into the `ScriptResponse` variable. diff --git a/administration/console.md b/administration/console.md index 74b653f3d..0743a9c1a 100644 --- a/administration/console.md +++ b/administration/console.md @@ -19,7 +19,7 @@ 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). -Linux package based installations can also use the command `openhab-cli console`. + 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. diff --git a/configuration/habpanel.md b/configuration/habpanel.md index 9706c9965..1d6ab2bd3 100644 --- a/configuration/habpanel.md +++ b/configuration/habpanel.md @@ -276,9 +276,10 @@ Upon clicking on a custom widget definition, the widget designer opens. It conta - **Code:** This tab is an editor for the template's code. You can use the Ctrl-S (or Cmd-S) keyboard shortcut to save the widget while editing the code; - **Settings:** This tab hosts the widget's general settings and configuration settings structure to be defined. -Click on the **Add setting** to add a new configuration setting. Each configuration setting must have a type, a technical ID, and other optional attributes. Each type of setting determines the UI element presented in the dashboard designer when configuring instances of the custom widget. -Use the arrow buttons to move configuration settings up or down, and the trash bin icon to remove them. -When instantiated, the value of configuration settings are set in the template's scope as `config.` (except those of type Icon which define an additional value, the iconset name, as `config._iconset`); + Click on the **Add setting** to add a new configuration setting. Each configuration setting must have a type, a technical ID, and other optional attributes. + Each type of setting determines the UI element presented in the dashboard designer when configuring instances of the custom widget. + Use the arrow buttons to move configuration settings up or down, and the trash bin icon to remove them. + When instantiated, the value of configuration settings are set in the template's scope as `config.` (except those of type Icon which define an additional value, the iconset name, as `config._iconset`); - **Preview:** Upon switching to this tab, a test instance of the widget is rendered in an otherwise blank testbed dashboard. Use the sliders to resize the widget in order to preview it at different sizes. If it defines configuration settings, they must likely be set for this preview using the gears icon: this will bring up the widget instance's configuration dialog as it would appear in the dashboard designer. diff --git a/configuration/migration/index.md b/configuration/migration/index.md index 4828aa06f..ca99d73db 100644 --- a/configuration/migration/index.md +++ b/configuration/migration/index.md @@ -9,9 +9,9 @@ description: Description of Beaking Changes and needed steps for a proper Migrat There are different approaches to get your openHAB 2 Environment upgraded to openHAB 3. You could start with a fresh install and migrate your environment step-by-step or you can upgrade your running environment and change your configuration where needed. -Since this is a major version release you have to pay attention to some `Breaking Changes` that may affect your environment too. -You can find a general note on the `Breaking Changes` here: -https://github.com/openhab/openhab-distro/wiki/Breaking-Changes-in-openHAB-3 +Since this is a major version release you have to pay attention to some **Breaking Changes** that may affect your environment too. +You can find a general note on the **Breaking Changes** here: + Please read them carefully and check if you are affected by some of the changes, like the changes to some rules namespaces and the handling of time functions. @@ -25,8 +25,8 @@ Please be aware of possible changes needed for your specific environment in case If you are working with an [openHABian](https://www.openhab.org/docs/installation/openhabian.html) setup, the upgrade is quite easy. Regardless of if you are currently using the openHAB 2.5 stable release or one of the latest 3.0.0 SNAPSHOT or milestone builds, switching to openHAB 3.0.0 stable is done in just a few steps: 1. Connect to the SSH command line and execute: `sudo openhabian-config` -2. When being asked, answer that you want to update. -3. Select the menu entry"03 - Install openHAB" option. +1. When being asked, answer that you want to update. +1. Select the menu entry"03 - Install openHAB" option. ### Package-based Installations @@ -46,13 +46,13 @@ You must also be on the relevant repository for openHAB, this hasn't changed for For DEB based installers (apt), your `.list` file should contain the line: -``` +```shell deb https://dl.bintray.com/openhab/apt-repo2 stable main ``` For RPM based installers (yum), your `.repo` file should contain: -``` +```shell [openHAB-Stable] name=openHAB Stable baseurl=https://dl.bintray.com/openhab/rpm-repo2/stable @@ -71,7 +71,7 @@ With `openhab2` still installed: ##### APT (Debian / Ubuntu and derivatives) -``` +```shell sudo apt update sudo apt install openhab ``` @@ -80,14 +80,14 @@ The system will ask you if you want to remove `openhab2` as part of this, and yo You can get rid of openHAB2 leftover configuration files by using the `sudo apt purge openhab2` command, but this also gets rid of the `openhab` user, to fix this issue you should follow this with: -``` +```shell sudo apt install --reinstall openhab sudo openhab-cli reset-ownership ``` ##### DNF (RedHat, CentOS, Fedora, etc.) -``` +```shell sudo dnf --allowerasing install openhab ``` @@ -96,7 +96,8 @@ DNF does not replace configuration files for you by default, have a look at the ##### YUM (Older RedHat, CentOS, Fedora, etc.) The equivalent command should be: -``` + +```shell sudo yum swap openhab2 openhab ``` @@ -114,7 +115,7 @@ After a successful install, you can use commands like `sudo systemctl start open ##### APT (Debian / Ubuntu and derivatives) -```sh +```shell sudo apt purge openhab2 sudo apt update sudo apt install openhab @@ -122,12 +123,12 @@ sudo apt install openhab ##### YUM or DNF (RedHat, CentOS, Fedora, etc) -```sh +```shell sudo dnf remove openhab2 sudo dnf install openhab ``` + Replace "dnf" with "yum" for older Red Hat based OSes. - ### Manual Installations @@ -138,20 +139,20 @@ Official update scripts are available that let you update your 2.x installation #### Linux/MacOS 1. Change to your openHAB root directory (e.g. `cd /opt/openhab`) -2. Create a backup by calling `sudo ./runtime/bin/backup`. -2. Run the update command: +1. Create a backup by calling `sudo ./runtime/bin/backup`. +1. Run the update command: - ``` + ```shell sudo ./runtime/bin/update 3.0.0 ``` #### Windows 1. Make a backup of your openHAB installation folder. -2. Run PowerShell as an administrator and change to your openHAB root directory (e.g. `cd C:\openHAB`) -3. Run the update command: +1. Run PowerShell as an administrator and change to your openHAB root directory (e.g. `cd C:\openHAB`) +1. Run the update command: - ``` -. .\runtime\bin\update.ps1 -Update-openHAB -OHVersion 3.0.0 + ```shell + . .\runtime\bin\update.ps1 + Update-openHAB -OHVersion 3.0.0 ``` diff --git a/configuration/persistence.md b/configuration/persistence.md index 3c2128136..171bb1753 100644 --- a/configuration/persistence.md +++ b/configuration/persistence.md @@ -89,8 +89,9 @@ where `` is a comma-separated list consisting of one or more of the fo - `*` - this line should apply to all items in the system - `` a single Item identified by its name. This Item can be a group Item. But note that only the group value will be persisted. The value of the individual group members will not be persisted using this option. -- `*` - all members of this group will be persisted, but not the group itself. If no strategies are provided, the default strategies that are declared in the first section are applied. Optionally, an alias may be provided if the persistence service requires special names (e.g. a table to be used in a database, a feed id for an IoT service, etc.) -Note that * is NOT a wildcard match character in this context. +- `*` - all members of this group will be persisted, but not the group itself. If no strategies are provided, the default strategies that are declared in the first section are applied. + Optionally, an alias may be provided if the persistence service requires special names (e.g. a table to be used in a database, a feed id for an IoT service, etc.) + Note that `*` is NOT a wildcard match character in this context. The example `Items` section below takes advantage of a `default` entry in the `Strategies` section. Assume the `Strategies` section contains the line: diff --git a/configuration/sitemaps.md b/configuration/sitemaps.md index d2787a69e..33c0496c9 100644 --- a/configuration/sitemaps.md +++ b/configuration/sitemaps.md @@ -143,8 +143,8 @@ This provides the flexibility to present Items in the way desired in your home a - `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. -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. + 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. It has to be considered that if the label defined in a Channel or an Item contains text and state, these representations have to be overwritten separately in the Sitemap. In the following example a Item which has a label and state defined is overwritten. @@ -446,13 +446,13 @@ Adds a time-series chart object for the display of logged data. - `refresh` defines the refresh period of the Image (in milliseconds). - `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. + 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`. - `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). + 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. Valid values are `true` (always show the legend) and `false` (never show the legend). diff --git a/developers/bindings/binding-xml.md b/developers/bindings/binding-xml.md index 36deeeb1c..02ee57ea4 100644 --- a/developers/bindings/binding-xml.md +++ b/developers/bindings/binding-xml.md @@ -3,7 +3,7 @@ layout: developersguide title: Binding Descriptions --- -## Binding Definitions +# Binding Definitions Every binding has to provide meta information such as binding id or name. @@ -16,7 +16,7 @@ The full Java API for binding definitions can be found in the Java package `org. For the declarative way, you add your binding information in form of a `binding.xml` file to the bundle's folder `/src/main/resources/OH-INF/binding/binding.xml`. -### XML Structure for Binding Definitions +## XML Structure for Binding Definitions ```xml @@ -57,9 +57,9 @@ The full XML schema for binding definitions is specified in the [Binding XSD](ht - The attribute `uri` in the section `config-description` is optional, it *should not* be specified in binding definition files because it's an embedded configuration. If the `uri` is *not* specified, the configuration description is registered as `binding:bindingID`, otherwise the given `uri` is used. - If a configuration description is already specified somewhere else and the binding wants to (re-)use it, a `config-description-ref` should be used instead. - Normally the service id must not be defined, because it is implicitly set to "binding.<binding.id>". -A binding can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g."binding.hue" to receive the configuration. + A binding can register an OSGi service which implements the ManagedService interface and define the service.pid as e.g."binding.hue" to receive the configuration. -### Example +## Example The following code gives an example for a binding definition. diff --git a/developers/bindings/config-xml.md b/developers/bindings/config-xml.md index 47ded54c5..8396b347f 100644 --- a/developers/bindings/config-xml.md +++ b/developers/bindings/config-xml.md @@ -31,7 +31,7 @@ The description can include limited HTML to enhance the display of this informat The following HTML tags are allowed -: ```,
, ,

,

,

,

,

,
, ,

, , , , ,

    ,
      ,
    1. ```. These must be inside the XML escape sequence - eg. -``````. +``. ## XML Structure for Configuration Descriptions @@ -150,7 +150,6 @@ The above filter is evaluated as follows: ```text (type=Switch OR type=Dimmer) AND (tag=Light OR tag=Heating) - ``` Similarly, the Channel context can contain criteria to filter channels based on kind field. diff --git a/developers/bindings/faq.md b/developers/bindings/faq.md index 7d6a49c2b..46e8d25a0 100644 --- a/developers/bindings/faq.md +++ b/developers/bindings/faq.md @@ -18,7 +18,7 @@ Shall I design this as one Thing or as a Bridge with multiple Things for the dif In general, both options are valid: 1. You have one Thing which has channels for all your actors, sensors and other functions - 2. You have one Bridge and an additional Thing for every actor and sensor and they would hold the channels + 1. You have one Bridge and an additional Thing for every actor and sensor and they would hold the channels The preferred architecture is the latter, if this is feasible. This means that the physical devices should be represented by a Thing each. @@ -27,14 +27,14 @@ Shall I design this as one Thing or as a Bridge with multiple Things for the dif If your system does not provide you any possibility to get hold of such information, but rather only shows you a "logical" view of it, then 1) is also a valid option to pursue. -2. _Do I have to create XML files in `OH-INF/thing` for all devices or is there any other option?_ +1. _Do I have to create XML files in `OH-INF/thing` for all devices or is there any other option?_ No, the XML files are only one way to describe your devices. Alternatively, you can implement your own [ThingTypeProvider](https://github.com/openhab/openhab-core/blob/master/bundles/org.openhab.core.thing/src/main/java/org/openhab/core/thing/binding/ThingTypeProvider.java), through which you can provide thing descriptions in a programmatic way. Nonetheless, the static XML descriptions of thing types can be picked up for documentation generation and other purposes. So whenever possible, static XML descriptions should be provided. -3. _For my system XY, there are so many different variants of devices. +1. _For my system XY, there are so many different variants of devices. Do I really need to define a thing type for every single one of them?_ Thing types are important if you have no chance to request any structural information about the devices from your system and if you need users to manually chose a thing to add or configure (i.e. there is also no automatic discovery). @@ -42,14 +42,14 @@ Do I really need to define a thing type for every single one of them?_ If your system supports auto-discovery and you can also dynamically construct things (and their channels) from structural information that you can access during runtime, there is in theory no need to provide any thing type description at all. Nonetheless, static descriptions of thing types have the advantage that the user knows which kind of devices are supported, no matter if he has a device at home or not - so you should at least have static XML descriptions for the devices that are known to you at implementation time. -4. _I have a device that can have different firmware versions with slightly different functionality. +1. _I have a device that can have different firmware versions with slightly different functionality. Should I create one or two thing types for it?_ If the firmware version makes a huge difference for the device (and can be seen as a different model of it), then it is ok to have different things defined. If the list of channels can be determined by knowing the firmware revision, this is good. If you can only determine the existing channels by querying the device itself, it might be the better option to have only one thing type and construct its channels upon first access. -5. _When creating a Thing through my ThingHanderFactory, does it exactly have to have the channels that are defined in the thing type description?_ +1. _When creating a Thing through my ThingHanderFactory, does it exactly have to have the channels that are defined in the thing type description?_ It must at least have the channels that are defined in its thing type (and they are already automatically added by the super() implementation). Nonetheless, you are free to add any number of additional channels to the thing. diff --git a/developers/bindings/index.md b/developers/bindings/index.md index 6243c9e7a..77f9fe5ef 100644 --- a/developers/bindings/index.md +++ b/developers/bindings/index.md @@ -119,16 +119,16 @@ For an example, our exemplary Weather binding starts and stops a scheduled job t The startup of a handler is divided in two essential steps: 1. Handler is registered: `ThingHandler` instance is created by a `ThingHandlerFactory` and tracked by the framework. -In addition, the handler can be registered as a service if required, e.g. as `FirmwareUpdateHandler` or `ConfigStatusProvider`. + In addition, the handler can be registered as a service if required, e.g. as `FirmwareUpdateHandler` or `ConfigStatusProvider`. -2. Handler is initialized: `ThingHandler.initialize()` is called by the framework in order to initialize the handler. -This method is only called if all 'required' configuration parameters of the Thing are present. -The handler is ready to work (methods like `handleCommand`, `handleUpdate` or `thingUpdated` can be called). +1. Handler is initialized: `ThingHandler.initialize()` is called by the framework in order to initialize the handler. + This method is only called if all 'required' configuration parameters of the Thing are present. + The handler is ready to work (methods like `handleCommand`, `handleUpdate` or `thingUpdated` can be called). -The diagram below illustrates the startup of a handler in more detail. -The life cycle is controlled by the `ThingManager`. + The diagram below illustrates the startup of a handler in more detail. + The life cycle is controlled by the `ThingManager`. -![thing_life_cycle_startup](images/thing_life_cycle_startup.png) + ![thing_life_cycle_startup](images/thing_life_cycle_startup.png) The `ThingManager` mediates the communication between a `Thing` and a `ThingHandler` from the binding. The `ThingManager` creates for each Thing a `ThingHandler` instance using a `ThingHandlerFactory`. @@ -155,11 +155,11 @@ After the handler is initialized, the handler must be ready to handle methods ca The shutdown of a handler is also divided in two essential steps: 1. Handler is unregistered: `ThingHandler` instance is no longer tracked by the framework. -The `ThingHandlerFactory` can unregister handler services (e.g. `FirmwareUpdateHandler` or `ConfigStatusProvider`) if registered, or release resources. + The `ThingHandlerFactory` can unregister handler services (e.g. `FirmwareUpdateHandler` or `ConfigStatusProvider`) if registered, or release resources. -2. Handler is disposed: `ThingHandler.disposed()` method is called. -The framework expects `dispose()` to be non-blocking and to return quickly. -For longer running disposals, the implementation has to take care of scheduling a separate job. +1. Handler is disposed: `ThingHandler.disposed()` method is called. + The framework expects `dispose()` to be non-blocking and to return quickly. + For longer running disposals, the implementation has to take care of scheduling a separate job. ![thing_life_cycle_shutdown](images/thing_life_cycle_shutdown.png) @@ -860,12 +860,12 @@ To facilitate the development, binding developers only need to implement a `Upnp Here the developer only needs to implement three simple methods: - `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports. -The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs. + The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs. - `getThingUID` - Creates a thing UID out of the UPnP result or returns `null` if this is not possible. -This method is called from the discovery service during result creation to provide a unique thing UID for the result. + This method is called from the discovery service during result creation to provide a unique thing UID for the result. - `createResult` - Creates the `DiscoveryResult` out of the UPnP result. -This method is called from the discovery service to create the actual discovery result. -It uses the `getThingUID` method to create the thing UID of the result. + This method is called from the discovery service to create the actual discovery result. + It uses the `getThingUID` method to create the thing UID of the result. The following example shows the implementation of the UPnP discovery participant for the Hue binding, the `HueBridgeDiscoveryParticipant`. @@ -920,12 +920,12 @@ Here the developer only needs to implement four simple methods: - `getServiceType` - Defines the [mDNS service type](https://www.dns-sd.org/ServiceTypes.html). - `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports. -The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs. + The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs. - `getThingUID` - Creates a thing UID out of the mDNS service info or returns `null` if this is not possible. -This method is called from the discovery service during result creation to provide a unique thing UID for the result. + This method is called from the discovery service during result creation to provide a unique thing UID for the result. - `createResult` - Creates the `DiscoveryResult` out of the mDNS result. -This method is called from the discovery service to create the actual discovery result. -It uses the `getThingUID` method to create the thing UID of the result. + This method is called from the discovery service to create the actual discovery result. + It uses the `getThingUID` method to create the thing UID of the result. ### Discovery that is bound to a Thing diff --git a/developers/bindings/thing-xml.md b/developers/bindings/thing-xml.md index 471f0e266..6ed235ed9 100644 --- a/developers/bindings/thing-xml.md +++ b/developers/bindings/thing-xml.md @@ -854,5 +854,5 @@ The full XML schema for Thing type descriptions is specified in the [https://ope - Any identifiers of the types are automatically mapped to unique identifiers: `bindingID:id`. - The attribute `uri` in the section `config-description` is optional, it *should not* be specified in bridge/*Thing*/channel type definition files because it's an embedded configuration. -If the `uri` is *not* specified, the configuration description is registered as `thing-type:bindingID:id` or `channel-type:bindingID:id` otherwise the given `uri` is used.s + If the `uri` is *not* specified, the configuration description is registered as `thing-type:bindingID:id` or `channel-type:bindingID:id` otherwise the given `uri` is used.s - If a configuration description is already specified somewhere else and the bridge/*Thing*/channel type wants to (re-)use it, a `config-description-ref` should be used instead. diff --git a/developers/buildsystem.md b/developers/buildsystem.md index 8115ac4bb..ea4321cbb 100644 --- a/developers/buildsystem.md +++ b/developers/buildsystem.md @@ -40,8 +40,8 @@ These dependencies are embedded in the resulting bundle automatically. There are two exceptions: -1) Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/2.5.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/2.5.0-SNAPSHOT`). -2) Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`). +1. Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/2.5.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/2.5.0-SNAPSHOT`). +1. Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`). Dependencies on other openHAB bundles should have the scope `provided`. To ensure that they are available at runtime they also need to be added to the `feature.xml`: @@ -55,10 +55,10 @@ To ensure that they are available at runtime they also need to be added to the ` In two cases libraries can be added to the `/lib` directory: 1. The bundle is not available for download -2. The bundle is not an OSGi bundle but needs to be used for integration tests. -Unlike Karaf, BND is not able to wrap bundles on its own. -In this case the binding works as wrapper. -You need add the library and export all needed packages manually. +1. The bundle is not an OSGi bundle but needs to be used for integration tests. + Unlike Karaf, BND is not able to wrap bundles on its own. + In this case the binding works as wrapper. + You need add the library and export all needed packages manually. The build system automatically picks up all JAR files in `/lib` and embeds them in the new bundle. In this case they must not be added to the feature. diff --git a/developers/contributing.md b/developers/contributing.md index 4eb1b485b..bf331e5b2 100644 --- a/developers/contributing.md +++ b/developers/contributing.md @@ -150,7 +150,9 @@ By making a contribution to this project, I certify that: then you just add a line to every git commit message: - Signed-off-by: Joe Smith + ```text + Signed-off-by: Joe Smith + ``` using your real name (sorry, no pseudonyms or anonymous contributions.) and an e-mail address under which you can be reached (sorry, no github noreply e-mail @@ -161,9 +163,11 @@ Additionally can also sign off commits automatically by adding the `-s` or `--si If your commit contains code from others as well, please ensure that they certify the DCO as well and add them with an "Also-By" line to your commit message: - Also-by: Ted Nerd - Also-by: Sue Walker - Signed-off-by: Joe Smith +```text + Also-by: Ted Nerd + Also-by: Sue Walker + Signed-off-by: Joe Smith +``` #### Small Patch Exception @@ -196,8 +200,8 @@ You don't even need to know Git. - You can preview your changes under the "Preview changes" tab. - Add a title and optional description for your proposed change at the bottom of the editor. - The [sign off rules](#sign-your-work) described above do apply to documentation contributions as well. -Simply add an empty line and the sign off statement "Signed-off-by: Joe Smith \" at the end of your change description at the bottom of the editor. -Note that as per the rules you have to provide your full name in the sign off and that full name has to match the name you configured in your GitHub profile for the DCO check to succeed. + Simply add an empty line and the sign off statement "Signed-off-by: Joe Smith \" at the end of your change description at the bottom of the editor. + Note that as per the rules you have to provide your full name in the sign off and that full name has to match the name you configured in your GitHub profile for the DCO check to succeed. - Click the "Propose file change" button at the bottom of the editor, then click "Create pull request" on the next page, and then on the summary page click "Create pull request" one more time. If you prefer to use Git you can of course use the code contribution process for documentation contributions as well. diff --git a/developers/guidelines.md b/developers/guidelines.md index 40a0a7763..590d0c1c2 100644 --- a/developers/guidelines.md +++ b/developers/guidelines.md @@ -149,15 +149,15 @@ See [Default libraries](#default-libraries) for more details. ## E. Runtime Behavior 1. Overridden methods from abstract classes or interfaces are expected to return fast unless otherwise stated in their JavaDoc. -Expensive operations should therefore rather be scheduled as a job. -2. Creation of threads must be avoided. -Instead, resort into using existing schedulers which use pre-configured thread pools. -If there is no suitable scheduler available, start a discussion in the forum about it rather than creating a thread by yourself. -For periodically executed jobs that do not require a fixed rate [scheduleWithFixedDelay](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleWithFixedDelay(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)) should be preferred over [scheduleAtFixedRate](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleAtFixedRate(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)). -3. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning. -This can be tested by manually starting and stopping the bundle from the console (```stop ``` resp. ```start ```). -4. Bundles must not require any substantial CPU time. -Test this e.g. using "top" or VisualVM and compare CPU utilization with your bundle stopped vs. started. + Expensive operations should therefore rather be scheduled as a job. +1. Creation of threads must be avoided. + Instead, resort into using existing schedulers which use pre-configured thread pools. + If there is no suitable scheduler available, start a discussion in the forum about it rather than creating a thread by yourself. + For periodically executed jobs that do not require a fixed rate [scheduleWithFixedDelay](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleWithFixedDelay(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)) should be preferred over [scheduleAtFixedRate](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html#scheduleAtFixedRate(java.lang.Runnable,long,long,java.util.concurrent.TimeUnit)). +1. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning. + This can be tested by manually starting and stopping the bundle from the console (```stop ``` resp. ```start ```). +1. Bundles must not require any substantial CPU time. + Test this e.g. using "top" or VisualVM and compare CPU utilization with your bundle stopped vs. started. ## F. Logging @@ -185,8 +185,8 @@ void myFun() { ``` - Exceptions with stacktraces in the log are considered to be bugs in your binding that should be reported and fixed. -If you add an exception as a last parameter to the logging, the stack trace will be printed. -Configuration errors by users should only print log messages about what's wrong. In that case you would use `e.getMessage()`. + If you add an exception as a last parameter to the logging, the stack trace will be printed. + Configuration errors by users should only print log messages about what's wrong. In that case you would use `e.getMessage()`. ```java void myFun() { diff --git a/developers/ide/eclipse.md b/developers/ide/eclipse.md index e222bc130..d6f61e3e6 100644 --- a/developers/ide/eclipse.md +++ b/developers/ide/eclipse.md @@ -83,7 +83,7 @@ If you already have Eclipse installed it is recommended to perform a separate Ec 1. After all tasks are finished you are ready to start developing. 1. If you need additional libraries see the [Build System](../buildsystem.html) documentation. -For other libraries supported out-of-the-box check the [Default Libraries](../guidelines.html#default-libraries) on the guidelines page. + For other libraries supported out-of-the-box check the [Default Libraries](../guidelines.html#default-libraries) on the guidelines page. ## Working with Add-ons @@ -107,7 +107,7 @@ The following files are of interest for the execution environment: ``` 1. To let the demo project know about the add-on, the add-on must be added to the demo project `pom.xml`. -Here is an example for the `astro` binding: + Here is an example for the `astro` binding: ```xml diff --git a/developers/ide/intellij.md b/developers/ide/intellij.md index 1bae9cb12..e324c433f 100644 --- a/developers/ide/intellij.md +++ b/developers/ide/intellij.md @@ -20,8 +20,10 @@ This article refers to the directory where you installed the distribution as `` from now on for this arcticle) - `git clone https://github.com//openhab-addons` (replace git user name accordingly) + 1. open IntelliJ and create a new Project from existing sources (File | New | Project from existing sources) and pick ``/pom.xml - IntelliJ will start importing, indexing and building, it will take while, wait until finished (see status bar) + 1. Use Maven to clean & install the addons project - mvn clean install in the root of `` using commandline Maven (or IntelliJ Maven view) - some of the addons might fail to build - if it's not the one, you're interested in that should not bother you @@ -31,8 +33,10 @@ This article refers to the directory where you installed the distribution as `.jar /addons` + 1. The running instance of the openhab distribution should pick up your new addon & start it - you can type `log:tail` in the openhab console to stream the openhab logs + 1. create a Remote Debug runtime configuration in IntelliJ: - Open menu Run | Edit configurations - click the + sign to add a "Remote" configuration @@ -40,6 +44,7 @@ This article refers to the directory where you installed the distribution as ` ![launch.json changes](./images/ide_setup_vscode_launch.png) - 1. Set the `port` to xxxx (from step 7). This can be skipped if xxxx was 5005 from step 7. 1. Set the `hostName` to the hostname running openHAB. This can be skipped if running locally (localhost) 1. Save and close launch.json 1. Verify that VSCode can build the system and connect to a debug instance of openHAB: - 1. Shutdown any instances of openHAB 1. Press `CTRL-SHIFT-P -> Tasks: Run Task -> Start openHAB (Debug)` to start an openHAB instance in debug mode. You should see openHAB startup in a new VSCode terminal. 1. Press F5 (or bring up debug in VSCode and choose the "Debug (Attach) - openHAB" configuration) and the following should occur in the VSCode terminal - 1. The maven compile occuring (successfully) 1. The resulting JAR is copied to the openHAB addons directory (`openhab_addons`) 1. Connecting to the openHAB instance (the debug call stack should show a bunch of openHAB type threads running) diff --git a/developers/osgi/equinox.md b/developers/osgi/equinox.md index 0c1cbd462..9f2bfec49 100644 --- a/developers/osgi/equinox.md +++ b/developers/osgi/equinox.md @@ -24,18 +24,18 @@ Knowledge about how to start the runtime and execute basic commands will help yo ## Start Equinox Runtime from Eclipse 1. Go to "Run" -> "Run Configurations". -2. From the list in the left panel choose "OSGi Framework". Right click on it and choose "New". -3. After you've been created a new configuration, select the bundles that you need from the workspace. -4. Then make sure that the following bundles from the target platform are selected, otherwise the OSGi console will not be available: +1. From the list in the left panel choose "OSGi Framework". Right click on it and choose "New". +1. After you've been created a new configuration, select the bundles that you need from the workspace. +1. Then make sure that the following bundles from the target platform are selected, otherwise the OSGi console will not be available: org.apache.felix.gogo.runtime org.apache.felix.gogo.shell org.apache.felix.gogo.command org.eclipse.equinox.console -5. Click on "Add Required Bundles". Eclipse will resolve all dependencies of the bundles listed above and include new bundles to the configuration. -6. Click on "Validate Bundles" and make sure that "No problems were detected" is displayed. -7. You can start Equinox with the "Run" button. +1. Click on "Add Required Bundles". Eclipse will resolve all dependencies of the bundles listed above and include new bundles to the configuration. +1. Click on "Validate Bundles" and make sure that "No problems were detected" is displayed. +1. You can start Equinox with the "Run" button. ![Run Configurations dialog window](images/runconfiguration.png) @@ -47,9 +47,9 @@ If you have compiled openHAB once either via command line (`mvn install`) or the Find it in your maven cache directory (linux `~/.m2/repository/org/eclipse/platform/org.eclipse.osgi/3.15.0/org.eclipse.osgi-3.15.0.jar` and windows `C:\Users\your.name\.m2\..`). - 1. Create `configuration` folder in that directory. - 1. Inside the `configuration` folder create a file `config.ini`. - 1. Save the following content in the `config.ini` file: +1. Create `configuration` folder in that directory. +1. Inside the `configuration` folder create a file `config.ini`. +1. Save the following content in the `config.ini` file: ```ini osgi.bundles=\ @@ -69,7 +69,7 @@ and windows `C:\Users\your.name\.m2\..`). eclipse.consoleLog=true ``` - 1. Use the following command line to run Equinox: +1. Use the following command line to run Equinox: ```shell java -jar org.eclipse.osgi-3.x.x.jar -console -configuration configuration diff --git a/developers/utils/events.md b/developers/utils/events.md index 99ba61877..1944ef5d8 100644 --- a/developers/utils/events.md +++ b/developers/utils/events.md @@ -173,19 +173,19 @@ Each event subscriber must be registered via OSGi Declarative Services (DS) unde The listing below summarizes some best practices in order to implement event subscribers: - To subscribe to only one event type openHAB provides the `org.openhab.core.events.AbstractTypedEventSubscriber` implementation. -To receive an already cast event the `receiveTypedEvent(T)` method must be implemented. -To provide an event filter the method `getEventFilter()` can be overridden. + To receive an already cast event the `receiveTypedEvent(T)` method must be implemented. + To provide an event filter the method `getEventFilter()` can be overridden. - openHAB provides an `AbstractItemEventSubscriber` class in order to receive `ItemStateEvents` and `ItemCommandEvents` (more information can be obtained in the next chapter). - To filter events based on a topic the `org.openhab.core.events.TopicEventFilter` implementation from the openHAB core bundle can be used. -The filtering is based on [Java regular expression](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html). + The filtering is based on [Java regular expression](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html). - The subscribed event types and the filter should be stored as class members (see example above) due to performance reasons. - If the subscribed event types are sufficient in order to receive all interested events, do not return any filter (in that case the method getFilter() returns null) due to performance reasons. - Avoid the creation of too many event subscribers. -Similar event types can be received in one event subscriber. + Similar event types can be received in one event subscriber. - Handle exceptions in event subscriber implementation and throw only serious exceptions. -Thrown exceptions will be handled in the framework by logging an error message with the cause. + Thrown exceptions will be handled in the framework by logging an error message with the cause. - The receive method should terminate quickly, since it blocks other event subscribers. -Create a thread for long running operations. + Create a thread for long running operations. ### Receive ItemStateEvents and ItemCommandEvents diff --git a/installation/rasppi.md b/installation/rasppi.md index 99a114049..68b57e0ce 100644 --- a/installation/rasppi.md +++ b/installation/rasppi.md @@ -244,7 +244,7 @@ sudo systemctl enable openhab.service You are all set. -## What next? +## What next ? You can: diff --git a/installation/windows.md b/installation/windows.md index 7801cc1e5..55db62fa7 100644 --- a/installation/windows.md +++ b/installation/windows.md @@ -82,8 +82,8 @@ By installing the openHAB process as a service in Windows, you can: 1. Update the newly created `C:\openHAB\userdata\etc\openHAB-wrapper.conf` to include all necessary parameters: - - Copy all the config text from the below section and paste it in your `openHAB-wrapper.conf`, replacing all existing content. - - Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory. + 1. Copy all the config text from the below section and paste it in your `openHAB-wrapper.conf`, replacing all existing content. + 1. Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory. ```conf #******************************************************* @@ -235,13 +235,13 @@ C:\openHAB\userdata\bin\openHAB-service.bat remove You can connect to openHAB's console using the the `C:\openHAB\runtime\bin\client.bat` script on the local machine. Alternatively, you can use a standard SSH client: -- Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html) +1. Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html) -- Setup a session with the following parameters: - - Host: 127.0.0.1 - - Port: 8101 - - Username: `openhab` - - Password: `habopen` +1. Setup a session with the following parameters: + - Host: 127.0.0.1 + - Port: 8101 + - Username: `openhab` + - Password: `habopen` ![SSH Connection 1](images/SSH_Connection_1.jpg) diff --git a/tutorials/getting_started/first_steps.md b/tutorials/getting_started/first_steps.md index b1c6c3404..e00c76f1b 100644 --- a/tutorials/getting_started/first_steps.md +++ b/tutorials/getting_started/first_steps.md @@ -61,16 +61,18 @@ You can also set your preferred measurement system (openHAB defaults to the Metr ### Set your geographic location (latitude and longitude) and measurement system 1. In the left-hand menu under Administration, select Settings to open the Settings page. -![initial settings](images/initial_settings.png) + + ![initial settings](images/initial_settings.png) 1. Under System Settings, select Regional Settings. -![regional settings](images/regional_settings.png) + + ![regional settings](images/regional_settings.png) 1. Under Location, click the Map button to add your geographic coordinates. 1. If you also want to set your measurement system, click "Show advanced" and choose between Metric and Imperial. -![unit settings](images/units_settings.png) + ![unit settings](images/units_settings.png) ## Additional Settings diff --git a/tutorials/getting_started/things_advanced.md b/tutorials/getting_started/things_advanced.md index caf2cb519..4dcdbb2a4 100644 --- a/tutorials/getting_started/things_advanced.md +++ b/tutorials/getting_started/things_advanced.md @@ -41,12 +41,12 @@ A Transformation takes incoming data and transformes is somehow. In this case it will extract certain fields from the JSON. From Settings, click on Transformations under Add-ons. -![](images/choose_transformation.png) +![choose transformation](images/choose_transformation.png) Click on the blue "+" button and find JSONPath Transformation. Click on it, then click Install. -![](images/install_jsonpath.png) +![install_jsonpath](images/install_jsonpath.png) Wait for it to disappear from the list, then click back twice to go back to Settings. @@ -63,13 +63,13 @@ Click on the blue "+" button. Choose "MQTT Binding", then choose "MQTT Broker". -![](images/mqtt_things.png) +![mqtt things](images/mqtt_things.png) Fill in the details to connect to the broker. You may also alter its ID and name. If you need credentials to connect to the broker, click on "Show advanced" to reveal additional options, including Username and Password. -![](images/mqtt_bridge_config.png) +![mqtt bridge config](images/mqtt_bridge_config.png) ## Create the Generic MQTT Thing @@ -91,7 +91,7 @@ Back on the Things page, choose the Thing you created. It should be marked online, but it will not have any Channels on the Channel tab. You have to configure them yourself. -![](images/mqtt_generic_thing.png) +![mqtt generic thing](images/mqtt_generic_thing.png) Click on Add Channel. @@ -107,16 +107,16 @@ Click on "Show advanced" above MQTT State Topic to reveal more settings. Scroll down, find the "Incoming Value Transformations" setting, and specify the transformation to apply there: -``` +```json JSONPATH:$.temperature ``` -![](images/mqtt_temp_channel.png) +![mqtt temp channel](images/mqtt_temp_channel.png) Click Done in the title bar to add the channel. It should now be added to the Channels tab. -![](images/mqtt_temp_channel_created.png) +![mqtt temp channel created](images/mqtt_temp_channel_created.png) Repeat the procedure for the other channels: @@ -131,7 +131,7 @@ All channels should specify the MQTT topic where the JSON message is published. If you want to check the configuration for a channel, or if you made a mistake while adding it, open the channel details by clicking on it, and choose Configure Channel. -![](images/mqtt_config_channel.png) +![mqtt config channel](images/mqtt_config_channel.png) Note that you cannot change the channel type if you picked the wrong one. In that case, remove the channel by clicking on Remove Channel and then add it again.