[skeleton] Add Thing config table to readme; minor improvements (#2692)
* [skeleton] Add Thing config table to readme; minor improvements - put each sentence in a seperate line - add note that only PNG images are supported. See https://github.com/openhab/openhab-addons/pull/11116#discussion_r775838188 - add examples to "Supported Things" - add RW column to example Channel table - add advanced and default config value - add note that textual config examples are mandatory - make .sitemap example optional (see small internal discussion) - put emphasis on initialize() shall return quickly - add note about logging to INFO - fix compiler warning - Add default config value for initialization Signed-off-by: Fabian Wolter <github@fabian-wolter.de>pull/2705/head
Fabian Wolter
GitHub
parent
1fff165cb0
commit
f79d17f864
|
|
@ -2,21 +2,30 @@
|
|||
|
||||
_Give some details about what this binding is meant for - a protocol, system, specific device._
|
||||
|
||||
_If possible, provide some resources like pictures, a video, etc. to give an impression of what can be done with this binding. You can place such resources into a `doc` folder next to this README.md._
|
||||
_If possible, provide some resources like pictures (only PNG is supported currently), a video, etc. to give an impression of what can be done with this binding._
|
||||
_You can place such resources into a `doc` folder next to this README.md._
|
||||
|
||||
_Put each sentence in a separate line to improve readability of diffs._
|
||||
|
||||
#[[##]]# Supported Things
|
||||
|
||||
_Please describe the different supported things / devices within this section._
|
||||
_Please describe the different supported things / devices including their ThingTypeUID within this section._
|
||||
_Which different types are supported, which models were tested etc.?_
|
||||
_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
|
||||
|
||||
- `bridge`: Short description of the Bridge, if any
|
||||
- `sample`: Short description of the Thing with the ThingTypeUID `sample`
|
||||
|
||||
#[[##]]# Discovery
|
||||
|
||||
_Describe the available auto-discovery features here. Mention for what it works and what needs to be kept in mind when using it._
|
||||
_Describe the available auto-discovery features here._
|
||||
_Mention for what it works and what needs to be kept in mind when using it._
|
||||
|
||||
#[[##]]# Binding Configuration
|
||||
|
||||
_If your binding requires or supports general configuration settings, please create a folder ```cfg``` and place the configuration file ```<bindingId>.cfg``` inside it. In this section, you should link to this file and provide some information about the options. The file could e.g. look like:_
|
||||
_If your binding requires or supports general configuration settings, please create a folder ```cfg``` and place the configuration file ```<bindingId>.cfg``` inside it._
|
||||
_In this section, you should link to this file and provide some information about the options._
|
||||
_The file could e.g. look like:_
|
||||
|
||||
```
|
||||
# Configuration for the ${bindingIdCamelCase} Binding
|
||||
|
|
@ -33,23 +42,34 @@ _If your binding does not offer any generic configurations, you can remove this
|
|||
|
||||
#[[##]]# Thing Configuration
|
||||
|
||||
_Describe what is needed to manually configure a thing, either through the UI or via a thing-file. This should be mainly about its mandatory and optional configuration parameters. A short example entry for a thing file can help!_
|
||||
_Describe what is needed to manually configure a thing, either through the UI or via a thing-file._
|
||||
_This should be mainly about its mandatory and optional configuration parameters._
|
||||
|
||||
_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
|
||||
|
||||
#[[###]]# `sample` Thing Configuration
|
||||
|
||||
| Name | Type | Description | Default | Required | Advanced |
|
||||
|-----------------|---------|---------------------------------------|---------|----------|----------|
|
||||
| hostname | text | Hostname or IP address of the device | N/A | yes | no |
|
||||
| password | text | Password to access the device | N/A | yes | no |
|
||||
| refreshInterval | integer | Interval the device is polled in sec. | 600 | no | yes |
|
||||
|
||||
#[[##]]# Channels
|
||||
|
||||
_Here you should provide information about available channel types, what their meaning is and how they can be used._
|
||||
|
||||
_Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
|
||||
|
||||
| channel | type | description |
|
||||
|----------|--------|------------------------------|
|
||||
| control | Switch | This is the control channel |
|
||||
| Channel | Type | Read/Write | Description |
|
||||
|---------|--------|------------|-----------------------------|
|
||||
| control | Switch | RW | This is the control channel |
|
||||
|
||||
#[[##]]# Full Example
|
||||
|
||||
_Provide a full usage example based on textual configuration files (*.things, *.items, *.sitemap)._
|
||||
_Provide a full usage example based on textual configuration files._
|
||||
_*.things, *.items examples are mandatory as textual configuration is well used by many users._
|
||||
_*.sitemap examples are optional._
|
||||
|
||||
#[[##]]# Any custom content here!
|
||||
|
||||
|
|
|
|||
|
|
@ -15,17 +15,20 @@
|
|||
*/
|
||||
package ${package}.internal;
|
||||
|
||||
import org.eclipse.jdt.annotation.NonNullByDefault;
|
||||
|
||||
/**
|
||||
* The {@link ${bindingIdCamelCase}Configuration} class contains fields mapping thing configuration parameters.
|
||||
*
|
||||
* @author ${author} - Initial contribution
|
||||
*/
|
||||
@NonNullByDefault
|
||||
public class ${bindingIdCamelCase}Configuration {
|
||||
|
||||
/**
|
||||
* Sample configuration parameters. Replace with your own.
|
||||
*/
|
||||
public String hostname;
|
||||
public String password;
|
||||
public int refreshInterval;
|
||||
public String hostname = "";
|
||||
public String password = "";
|
||||
public int refreshInterval = 600;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -66,9 +66,10 @@ public class ${bindingIdCamelCase}Handler extends BaseThingHandler {
|
|||
config = getConfigAs(${bindingIdCamelCase}Configuration.class);
|
||||
|
||||
// TODO: Initialize the handler.
|
||||
// The framework requires you to return from this method quickly. Also, before leaving this method a thing
|
||||
// status from one of ONLINE, OFFLINE or UNKNOWN must be set. This might already be the real thing status in
|
||||
// case you can decide it directly.
|
||||
// The framework requires you to return from this method quickly, i.e. any network access must be done in
|
||||
// the background initialization below.
|
||||
// Also, before leaving this method a thing status from one of ONLINE, OFFLINE or UNKNOWN must be set. This
|
||||
// might already be the real thing status in case you can decide it directly.
|
||||
// In case you can not decide the thing status directly (e.g. for long running connection handshake using WAN
|
||||
// access or similar) you should set status UNKNOWN here and then decide the real status asynchronously in the
|
||||
// background.
|
||||
|
|
@ -93,6 +94,9 @@ public class ${bindingIdCamelCase}Handler extends BaseThingHandler {
|
|||
// logger.trace("Example trace message");
|
||||
// logger.debug("Example debug message");
|
||||
// logger.warn("Example warn message");
|
||||
//
|
||||
// Logging to INFO should be avoided normally.
|
||||
// See https://www.openhab.org/docs/developer/guidelines.html#f-logging
|
||||
|
||||
// Note: When initialization can NOT be done set the status with more details for further
|
||||
// analysis. See also class ThingStatusDetail for all available status details.
|
||||
|
|
|
|||
|
|
@ -28,11 +28,13 @@
|
|||
<parameter name="password" type="text" required="true">
|
||||
<context>password</context>
|
||||
<label>Password</label>
|
||||
<description>Passwort to access the device</description>
|
||||
<description>Password to access the device</description>
|
||||
</parameter>
|
||||
<parameter name="refreshInterval" type="integer" unit="s" min="1">
|
||||
<label>Refresh Interval</label>
|
||||
<description>Interval the device is polled in sec.</description>
|
||||
<default>600</default>
|
||||
<advanced>true</advanced>
|
||||
</parameter>
|
||||
</config-description>
|
||||
</thing-type>
|
||||
|
|
|
|||
Loading…
Reference in New Issue