[pushbullet] Pushbullet Binding initial contribution

CODEOWNERS

@@ -122,6 +122,7 @@
 /bundles/org.openhab.binding.plugwise/ @wborn
 /bundles/org.openhab.binding.powermax/ @lolodomo
 /bundles/org.openhab.binding.pulseaudio/ @peuter
+/bundles/org.openhab.binding.pushbullet/ @hakan42
 /bundles/org.openhab.binding.regoheatpump/ @crnjan
 /bundles/org.openhab.binding.rfxcom/ @martinvw @paulianttila
 /bundles/org.openhab.binding.rme/ @kgoderis

bom/openhab-addons/pom.xml

@@ -600,6 +600,11 @@
       <artifactId>org.openhab.binding.pulseaudio</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.pushbullet</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.regoheatpump</artifactId>

bundles/org.openhab.binding.pushbullet/.classpath

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" output="target/classes" path="src/main/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry excluding="**" kind="src" output="target/classes" path="src/main/resources">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="src" output="target/test-classes" path="src/test/java">
+		<attributes>
+			<attribute name="optional" value="true"/>
+			<attribute name="maven.pomderived" value="true"/>
+			<attribute name="test" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="con" path="org.eclipse.m2e.MAVEN2_CLASSPATH_CONTAINER">
+		<attributes>
+			<attribute name="maven.pomderived" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="output" path="target/classes"/>
+</classpath>

bundles/org.openhab.binding.pushbullet/.project

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>org.openhab.binding.pushbullet</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.m2e.core.maven2Builder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+		<nature>org.eclipse.m2e.core.maven2Nature</nature>
+	</natures>
+</projectDescription>

bundles/org.openhab.binding.pushbullet/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab2-addons

bundles/org.openhab.binding.pushbullet/README.md

@@ -0,0 +1,158 @@
+# Pushbullet Binding
+
+The Pushbullet binding allows you to notify iOS, Android & Windows 10 Phone & Desktop devices of a message using the Pushbullet API web service.
+
+## Supported Things
+
+This binding supports a generic "bot" which is a representation of the client.
+
+## Discovery
+
+This binding provides no discovery.
+The desired bots must be configured manually or via a things file.
+
+## Binding Configuration
+
+The binding has no configuration options itself, all configuration is done at 'Things' level.
+
+## Thing Configuration
+
+### Bot (`bot`)
+
+The bot thing is used to send messages to other recipients.
+It has the following parameters:
+
+| Config     |  Description                                                     | Required | Advanced |
+|------------|------------------------------------------------------------------|----------|----------|
+| token      | Pushbullet [API token](#obtaining-an-api-key) to send to devices | Yes      | False    |
+| name       | Explicit Name, for later use when the bot can receive messages   | No       | True     |
+| apiUrlBase | Address of own Pushbullet server, for testing purposes           | No       | True     |
+
+```java
+Thing pushbullet:bot:r2d2 "R2D2" @ "Somewhere" [ token = "verysecretwonttellyou" ]
+
+```
+
+## Channels
+
+| Channel ID | Channel Description                             | Supported item type  | Advanced |
+|------------|-------------------------------------------------|----------------------|----------|
+| recipient  | for later use when the bot can receive messages | String               | False    |
+| title      | for later use when the bot can receive messages | String               | False    |
+| message    | for later use when the bot can receive messages | String               | False    |
+
+## Rule Action
+
+This binding includes rule actions for sending notes.
+Two different actions available:
+
+* `sendPushbulletNote(String recipient, String messsage)`
+* `sendPushbulletNote(String recipient, String title, String messsage)`
+
+Since there is a separate rule action instance for each `bot` thing, this needs to be retrieved through `getActions(scope, thingUID)`.
+The first parameter always has to be `pushbullet` and the second is the full Thing UID of the bot that should be used. 
+Once this action instance is retrieved, you can invoke the action method on it.
+
+Examples:
+
+```
+val actions = getActions("pushbullet", "pushbullet:bot:r2d2")
+val result = actions.sendPushbulletNote("someone@example.com", "R2D2 talks here...", "This is the pushed note.")
+```
+
+## Full Example
+
+_Provide a full usage example based on textual configuration files (*.things, *.items, *.sitemap)._
+
+pushbullet.things:
+
+```java
+Thing pushbullet:bot:r2d2 "R2D2" @ "Somewhere" [ token = "verysecretwonttellyou" ]
+
+```
+
+pushbullet.items
+
+```java
+Switch Pushbullet_R2D2_Button  "Pushbullet Action bot R2D2"
+```
+
+pushbullet.sitemap
+
+```java
+sitemap pushbullet label="Pushbullet"
+{
+    Switch item=Pushbullet_R2D2_Button
+}
+```
+
+pushbullet.rules
+
+```java
+rule "Pushbullet R2D2 changed"
+when
+    Item Pushbullet_R2D2_Button changed
+then
+    logInfo(filename, "Button R2D2 changed - OH2...")
+
+    if (Pushbullet_R2D2_Button.state == ON)
+    {
+        sendCommand(Pushbullet_R2D2_Button, OFF)
+
+        val actions = getActions("pushbullet", "pushbullet:bot:r2d2")
+        logInfo(filename, "Actions for 'R2D2' are: " + actions)
+
+        if (actions != null)
+        {
+            val result = actions.sendPushbulletNote("someone@example.com", "Title R2D2 OH2", "This has been sent by the new R2D2 bot")
+            logInfo(filename, "Result of send action is: " + result)
+        }
+    }
+end
+```
+
+## Creating an account for your bot(s)
+
+The pushbullet accounts are bound to either Google or Facebook accounts.
+
+- Create a bot account with either Facebook or Google
+- Go to "<https://www.pushbullet.com/>"
+- Chose to either "Sign up with Google" or "Sign up with Facebook".
+- Complete the signup process as guided by the pushbullet web site.
+- Continue with "Obtaining an API key".
+
+## Obtaining an API key
+
+The API keys are bound to the pushbullet account.
+
+- Go to the pushbullet site.
+- Log in with either your personal account or the one you created for your bot.
+- Go to "<https://www.pushbullet.com/#settings/account>"
+- Click on "Create Access Token".
+- Copy the token created on the site.
+
+You must at least provide an API token (Private or Alias Key from Pushbullet.com) and a message in some manner before a message can be pushed.
+All other parameters are optional.
+If you use an alias key, the parameters (device, icon, sound, vibration) are overwritten by the alias setting on pushbullet.
+
+## Rate limits
+
+As of 2019, free accounts have a limit of 100 pushes per month.
+This action does not evaluate the rate limiting headers though.
+
+## Translation
+
+This project is being translated on transifex.
+If you want to help, please join the project at the URL:
+
+- https://www.transifex.com/hakan42/openhab-binding-pushbullet/dashboard/
+
+## Libraries
+
+This action has been written without using libraries as jpushbullet or jpushbullet2.
+Both of those libraries use various libraries themselves which makes integrating them into openHAB a challenge.
+
+## pushbullet API
+
+- <https://docs.pushbullet.com/>
+- <https://docs.pushbullet.com/#push-limit>

bundles/org.openhab.binding.pushbullet/pom.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>2.5.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.pushbullet</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Pushbullet Binding</name>
+
+  <dependencies>
+    <dependency>
+      <groupId>javax.mail</groupId>
+      <artifactId>mail</artifactId>
+      <version>1.4.7</version>
+      <scope>provided</scope>
+    </dependency>
+  </dependencies>
+
+</project>

bundles/org.openhab.binding.pushbullet/src/main/feature/feature.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.pushbullet-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+    <repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${project.version}/xml/features</repository>
+
+    <feature name="openhab-binding-pushbullet" description="Pushbullet Binding" version="${project.version}">
+        <feature>openhab-runtime-base</feature>
+        <bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.pushbullet/${project.version}</bundle>
+    </feature>
+</features>

bundles/org.openhab.binding.pushbullet/src/main/java/org/openhab/binding/pushbullet/internal/PushbulletBindingConstants.java

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2010-2019 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.pushbullet.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.smarthome.core.thing.ThingTypeUID;
+
+import java.util.Collections;
+import java.util.Set;
+
+/**
+ * The {@link PushbulletBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Hakan Tandogan - Initial contribution
+ */
+@NonNullByDefault
+public class PushbulletBindingConstants {
+
+    private static final String BINDING_ID = "pushbullet";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_BOT = new ThingTypeUID(BINDING_ID, "bot");
+
+    public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Collections.singleton(THING_TYPE_BOT);
+
+    // List of all Channel ids
+    public static final String RECIPIENT = "recipient";
+    public static final String TITLE = "title";
+    public static final String MESSAGE = "message";
+
+    // Binding logic constants
+    public static final String API_METHOD_PUSHES = "pushes";
+
+    public static final int TIMEOUT = 30 * 1000; // 30 seconds
+}

bundles/org.openhab.binding.pushbullet/src/main/java/org/openhab/binding/pushbullet/internal/PushbulletConfiguration.java

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2010-2019 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.pushbullet.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+/**
+ * The {@link PushbulletConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Hakan Tandogan - Initial contribution
+ */
+@NonNullByDefault
+public class PushbulletConfiguration {
+
+    private @Nullable String name;
+
+    private String token = "invalid";
+
+    private String apiUrlBase = "invalid";
+
+    public @Nullable String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public String getToken() {
+        return token;
+    }
+
+    public void setToken(String token) {
+        this.token = token;
+    }
+
+    public String getApiUrlBase() {
+        return apiUrlBase;
+    }
+
+    public void setApiUrlBase(String apiUrlBase) {
+        this.apiUrlBase = apiUrlBase;
+    }
+}