Skip to content

Commit

Permalink
Finish readme
Browse files Browse the repository at this point in the history
Signed-off-by: Connor Petty <[email protected]>
  • Loading branch information
Connor Petty committed Nov 28, 2020
1 parent 9fddbb7 commit 87176b9
Show file tree
Hide file tree
Showing 3 changed files with 153 additions and 22 deletions.
53 changes: 33 additions & 20 deletions bundles/org.openhab.binding.bluetooth.govee/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,47 +4,60 @@ This extension adds support for [Govee](https://www.govee.com/) Bluetooth Device

## Supported Things

Only two thing types are supported by this extension at the moment. More may be added later.
Only two thing types are supported by this extension at the moment.

| Thing Type ID | Description |
|---------------|-------------------------------------------------|
| govee_h5051 | Govee Wi-Fi Temperature Humidity Monitor |
| govee_h5052 | Govee Temperature Humidity Monitor |
| govee_h5071 | Govee Temperature Humidity Monitor |
| govee_h5072 | Govee Temperature Humidity Monitor |
| govee_h5074 | Govee Mini Temperature Humidity Monitor |
| govee_h5075 | Govee Temperature Humidity Monitor |
| Thing Type ID | Description | Supported Models |
|------------------------|-------------------------------------------|-------------------------------------------------------------|
| goveeHygrometer | Govee Thermo-Hygrometer | H5051,H5071 |
| goveeHygrometerMonitor | Govee Thermo-Hygrometer w/ Warning Alarms | H5052,H5072,H5074,H5075,H5101,H5102,H5177,H5179,B5175,B5178 |

## Discovery

As any other Bluetooth device, Govee devices are discovered automatically by the corresponding bridge.

## Thing Configuration

There is only a single configuration parameter `address`, which corresponds to the Bluetooth address of the device (in format "XX:XX:XX:XX:XX:XX").
Govee things have the following configuration parameters:

| Thing | Parameter | Required | Default | Description |
|------------------------|-------------------------|----------|-------------|---------------------------------------------------------------------------|
| all | address | yes | | The Bluetooth address of the device (in format "XX:XX:XX:XX:XX:XX") |
| all | refreshInterval | | 300 | How often, in seconds, the sensor data of the device should be refreshed |
| goveeHygrometer* | temperatureCalibration | no | | Offset to apply to temperature sensor readings |
| goveeHygrometer* | humidityCalibration | no | | Offset to apply to humidity sensor readings |
| goveeHygrometerMonitor | temperatureWarningAlarm | | false | Enables warning alarms to be broadcast when temperature is out of range |
| goveeHygrometerMonitor | temperatureWarningMin | | 0 | The lower safe temperature threshold (only applies if alarm is enabled) |
| goveeHygrometerMonitor | temperatureWarningMax | | 0 | The upper safe temperature threshold (only applies if alarm is enabled) |
| goveeHygrometerMonitor | humidityWarningAlarm | | false | Enables warning alarms to be broadcast when humidity is out of range |
| goveeHygrometerMonitor | humidityWarningMin | | 0 | The lower safe humidity threshold (only applies if alarm is enabled) |
| goveeHygrometerMonitor | humidityWarningMax | | 0 | The upper safe humidity threshold (only applies if alarm is enabled) |

## Channels

A Govee Bluetooth device has the following channels:
Govee things have the following channels in addition to the default bluetooth channels:

| Channel ID | Item Type | Description |
|---------------|------------------------|------------------------------------|
| temperature | Number:Temperature | The measured temperature |
| humidity | Number:Dimensionless | The measured humidity |
| battery | Number:Dimensionless | The measured battery |
| Thing | Channel ID | Item Type | Description |
|------------------------|------------------|------------------------|-------------------------------------------------------|
| goveeHygrometer* | temperature | Number:Temperature | The measured temperature |
| goveeHygrometer* | humidity | Number:Dimensionless | The measured relative humidity |
| goveeHygrometer* | battery | Number:Dimensionless | The measured battery percentage |
| goveeHygrometerMonitor | temperatureAlarm | Switch | Indicates if current temperature is out of range. (1) |
| goveeHygrometerMonitor | humidityAlarm | Switch | Indicates if current humidity is out of range. (1) |

1) Only applies if warning alarms are enabled in the configuration.

## Example

demo.things:

```
bluetooth:govee_h5074:hci0:beacon "Govee Temperature Humidity Monitor" (bluetooth:bluez:hci0) [ address="12:34:56:78:9A:BC" ]
bluetooth:goveeHygrometer:hci0:beacon "Govee Temperature Humidity Monitor" (bluetooth:bluez:hci0) [ address="12:34:56:78:9A:BC" ]
```

demo.items:

```
Number:Temperature temperature "Room Temperature [%.1f %unit%]" { channel="bluetooth:govee_h5074:hci0:beacon:temperature" }
Number:Dimensionless humidity "Humidity [%.0f %unit%]" { channel="bluetooth:govee_h5074:hci0:beacon:humidity" }
Number:Dimensionless battery "Battery [%.0f %unit%]" { channel="bluetooth:govee_h5074:hci0:beacon:battery" }
Number:Temperature temperature "Room Temperature [%.1f %unit%]" { channel="bluetooth:goveeHygrometer:hci0:beacon:temperature" }
Number:Dimensionless humidity "Humidity [%.0f %unit%]" { channel="bluetooth:goveeHygrometer:hci0:beacon:humidity" }
Number:Dimensionless battery "Battery [%.0f %unit%]" { channel="bluetooth:goveeHygrometer:hci0:beacon:battery" }
```
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
</supported-bridge-type-refs>

<label>Govee Hygrometer</label>
<description>A Govee Temperature Humidity Monitor</description>
<description>Govee Thermo-Hygrometer</description>

<channels>
<channel id="rssi" typeId="rssi"/>
Expand Down Expand Up @@ -67,7 +67,7 @@
</supported-bridge-type-refs>

<label>Govee Monitoring Hygrometer</label>
<description>A Govee Temperature Humidity Monitor</description>
<description>Govee Thermo-Hygrometer w/ Warning Alarms</description>

<channels>
<channel id="rssi" typeId="rssi"/>
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
/**
* Copyright (c) 2010-2020 Contributors to the openHAB project
*
* See the NOTICE file(s) distributed with this work for additional
* information.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0
*
* SPDX-License-Identifier: EPL-2.0
*/
package org.openhab.binding.bluetooth.govee.internal.readme;

import java.io.FileInputStream;
import java.io.StringWriter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathConstants;
import javax.xml.xpath.XPathExpression;
import javax.xml.xpath.XPathFactory;

import org.apache.commons.lang.StringUtils;
import org.openhab.binding.bluetooth.govee.internal.GoveeModel;
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

/**
* @author Connor Petty - Initial contribution
*
*/
public class ThingTypeTableGenerator {

public static void main(String[] args) throws Exception {

FileInputStream fileIS = new FileInputStream("src/main/resources/OH-INF/thing/thing-types.xml");
DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = builderFactory.newDocumentBuilder();
Document xmlDocument = builder.parse(fileIS);
XPath xPath = XPathFactory.newInstance().newXPath();
String expression = "/*[local-name()='thing-descriptions']/thing-type";
XPathExpression labelExpression = xPath.compile("label/text()");
XPathExpression descriptionExpression = xPath.compile("description/text()");

NodeList nodeList = (NodeList) xPath.compile(expression).evaluate(xmlDocument, XPathConstants.NODESET);

List<ThingTypeData> thingTypeDataList = new ArrayList<>();

for (int i = 0; i < nodeList.getLength(); i++) {
Node node = nodeList.item(i);
ThingTypeData data = new ThingTypeData();

data.id = node.getAttributes().getNamedItem("id").getTextContent();
data.label = (String) labelExpression.evaluate(node, XPathConstants.STRING);
data.description = (String) descriptionExpression.evaluate(node, XPathConstants.STRING);

thingTypeDataList.add(data);
}

String[] headerRow = new String[] { "Thing Type ID", "Description", "Supported Models" };

List<String[]> rows = new ArrayList<>();
rows.add(headerRow);
rows.addAll(thingTypeDataList.stream().map(ThingTypeTableGenerator::toRow).collect(Collectors.toList()));

int[] maxColumns = { maxColumnSize(rows, 0), maxColumnSize(rows, 1), maxColumnSize(rows, 2) };

StringWriter writer = new StringWriter();

// write actual rows
rows.forEach(row -> {
writer.append(writeRow(maxColumns, row, ' ')).append('\n');
if (row == headerRow) {
writer.append(writeRow(maxColumns, new String[] { "", "", "" }, '-')).append('\n');
}
});

System.out.println(writer.toString());
}

private static String writeRow(int[] maxColumns, String[] row, char paddingChar) {
String prefix = "|" + paddingChar;
String infix = paddingChar + "|" + paddingChar;
String suffix = paddingChar + "|";

return Stream.of(0, 1, 2).map(i -> StringUtils.rightPad(row[i], maxColumns[i], paddingChar))
.collect(Collectors.joining(infix, prefix, suffix));
}

private static int maxColumnSize(List<String[]> rows, int column) {
return rows.stream().map(row -> row[column].length()).max(Integer::compare).get();
}

private static class ThingTypeData {
private String id;
private String label;
private String description;
}

private static String[] toRow(ThingTypeData data) {
return new String[] { data.id, //
data.description, //
modelsForType(data.id).stream().map(model -> model.name()).collect(Collectors.joining(",")) };
}

private static List<GoveeModel> modelsForType(String typeUID) {
return Arrays.stream(GoveeModel.values()).filter(model -> model.getThingTypeUID().getId().equals(typeUID))
.collect(Collectors.toList());
}
}

0 comments on commit 87176b9

Please sign in to comment.