Jerome Luckenbach
GitHub
parent
c1903fed52
commit
a3260307b0
|
|
@ -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 <joe.smith@email.com>
|
||||
`Signed-off-by: Joe Smith <joe.smith@email.com>`
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <https://openhab.org/>,
|
||||
you will find the following link at the bottom, which will point you directly to the file you want to improve.
|
||||
|
||||
|
||||
|
|
@ -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: <https://github.com/openhab/website/issues/72>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ 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
|
||||
- `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
|
||||
|
|
|
|||
|
|
@ -276,7 +276,8 @@ 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.
|
||||
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.<setting_id>` (except those of type Icon which define an additional value, the iconset name, as `config.<setting_id>_iconset`);
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
<https://github.com/openhab/openhab-distro/wiki/Breaking-Changes-in-openHAB-3>
|
||||
|
||||
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.
|
||||
<a name="manual-installations">
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
```shell
|
||||
. .\runtime\bin\update.ps1
|
||||
Update-openHAB -OHVersion 3.0.0
|
||||
```
|
||||
|
|
|
|||
|
|
@ -89,8 +89,9 @@ where `<itemlist>` is a comma-separated list consisting of one or more of the fo
|
|||
|
||||
- `*` - this line should apply to all items in the system
|
||||
- `<itemName>` 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.
|
||||
- `<groupName>*` - 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.
|
||||
- `<groupName>*` - 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:
|
||||
|
|
|
|||
|
|
@ -452,7 +452,7 @@ Therefore, for an installation with only a single persistence service, this is n
|
|||
- `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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
|
@ -59,7 +59,7 @@ The full XML schema for binding definitions is specified in the [Binding XSD](ht
|
|||
- 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.
|
||||
|
||||
### Example
|
||||
## Example
|
||||
|
||||
The following code gives an example for a binding definition.
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ The description can include limited HTML to enhance the display of this informat
|
|||
|
||||
The following HTML tags are allowed -: ```<b>, <br>, <em>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <i>, <p>, <small>, <strong>, <sub>, <sup>, <ul>, <ol>, <li>```.
|
||||
These must be inside the XML escape sequence - eg.
|
||||
```<description><![CDATA[ HTML marked up text here ]]></description>```.
|
||||
`<description><![CDATA[ HTML marked up text here ]]></description>`.
|
||||
|
||||
## 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 <strong>Channel</strong> context can contain criteria to filter channels based on <strong>kind</strong> field.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -121,7 +121,7 @@ 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`.
|
||||
|
||||
2. Handler is initialized: `ThingHandler.initialize()` is called by the framework in order to initialize the handler.
|
||||
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).
|
||||
|
||||
|
|
@ -157,7 +157,7 @@ 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.
|
||||
|
||||
2. Handler is disposed: `ThingHandler.disposed()` method is called.
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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,7 +55,7 @@ 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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
```text
|
||||
Signed-off-by: Joe Smith <joe.smith@email.com>
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```text
|
||||
Also-by: Ted Nerd <ted.nerd@email.com>
|
||||
Also-by: Sue Walker <sue.walker@email.com>
|
||||
Signed-off-by: Joe Smith <joe.smith@email.com>
|
||||
```
|
||||
|
||||
#### Small Patch Exception
|
||||
|
||||
|
|
|
|||
|
|
@ -150,13 +150,13 @@ See [Default libraries](#default-libraries) for more details.
|
|||
|
||||
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.
|
||||
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)).
|
||||
3. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning.
|
||||
1. Bundles need to cleanly start and stop without throwing exceptions or malfunctioning.
|
||||
This can be tested by manually starting and stopping the bundle from the console (```stop <bundle-id>``` resp. ```start <bundle-id>```).
|
||||
4. Bundles must not require any substantial CPU time.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -20,8 +20,10 @@ This article refers to the directory where you installed the distribution as `<D
|
|||
|
||||
1. fork and clone the [openhab addons repository](https://www.github.com/openhab/openhab-addons) into a new directory (Reference `<ADDON_DIR>` from now on for this arcticle)
|
||||
- `git clone https://github.com/<yourgitusername>/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 `<ADDON_DIR>`/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 `<ADDON_DIR>` 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 `<D
|
|||
|
||||
1. copy the addon JAR to Openhab distribution created before
|
||||
- `cp target/<ADDON_NAME>.jar <DISTRO_DIR>/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 `<D
|
|||
- click OK
|
||||
- start the debug configuration
|
||||
- the IntelliJ console should log: `Connected to the target VM, address: 'localhost:5005', transport: 'socket'`
|
||||
|
||||
|
||||
|
||||
You can now add breakpoints to your project now and your test distro should stop there.
|
||||
|
|
|
|||
|
|
@ -67,20 +67,16 @@ The following steps will show you how to setup a specific bundle for development
|
|||
|
||||
|
||||
|
||||
1. Edit launch.json and ...
|
||||
|
||||
1. Edit launch.json and ...<br>
|
||||
|
||||
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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,9 +235,9 @@ 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:
|
||||
1. Setup a session with the following parameters:
|
||||
- Host: 127.0.0.1
|
||||
- Port: 8101
|
||||
- Username: `openhab`
|
||||
|
|
|
|||
|
|
@ -61,9 +61,11 @@ 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.
|
||||
|
||||
|
||||
|
||||
1. Under System Settings, select Regional Settings.
|
||||
|
||||
|
||||
|
||||
1. Under Location, click the Map button to add your geographic coordinates.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
|
||||
Click on the blue "+" button and find JSONPath Transformation.
|
||||
Click on it, then click Install.
|
||||
|
||||
|
||||
|
||||
|
||||
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".
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
Click Done in the title bar to add the channel.
|
||||
It should now be added to the Channels tab.
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue