Skip to content

Commit

Permalink
[pushbullet] Remove unimplemented channels and thing parameters (open…
Browse files Browse the repository at this point in the history 
…hab#17482)

* [pushbullet] Remove unimplemented channels and thing parameters

Signed-off-by: jsetton <[email protected]>
  • Loading branch information
@jsetton
jsetton authored Oct 5, 2024
1 parent 6a6c7f6 commit e1c1e59
Show file tree
Hide file tree
Showing 8 changed files with 63 additions and 198 deletions.
149 changes: 33 additions & 116 deletions bundles/org.openhab.binding.pushbullet/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,25 @@
# 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.
The Pushbullet binding allows you to notify supported devices of a message using the [Pushbullet API](https://docs.pushbullet.com).
To get started you need to [create an account](#creating-an-account) and [obtain an access token](#obtaining-an-access-token).

## 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 | Type | Description |
| ----- | ----- | ------------------------- |
| bot | Thing | Bot to send messages with |

## Thing Configuration

### Bot (`bot`)

The bot thing is used to send messages to other recipients.
It has the following parameters:
### `bot`

| 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" ]

```
| Parameter | Required | Description |
| --------- | :------: | ---------------------------------------------------- |
| token | Yes | Access token obtained from the account settings page |

## 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 |
Currently the binding does not support any channels.

## Rule Action

Expand Down Expand Up @@ -71,110 +51,47 @@ For the `sendPushbulletNote` action, parameter `message` is required.
Likewise, for `sendPushbulletLink`, `url` and for `sendPushbulletFile`, `content` parameters are required.
Any other parameters for these actions are optional and can be set to `null`.

Examples:

```java
val actions = getActions("pushbullet", "pushbullet:bot:r2d2")
actions.sendPushbulletNote("[email protected]", "Note Example", "This is the pushed note.")
actions.sendPushbulletLink("[email protected]", "Link Example", "This is the pushed link", "https://example.com")
actions.sendPushbulletFile("[email protected]", "File Example", "This is the pushed file", "https://example.com/image.png")
actions.sendPushbulletFile("[email protected]", null, null, "/path/to/somefile.pdf", "document.pdf")
actions.sendPushbulletFile("[email protected]", ImageItem.state.toFullString)
```

## 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
demo.things:

```java
Switch Pushbullet_R2D2_Button "Pushbullet Action bot R2D2"
```

pushbullet.sitemap
Thing pushbullet:bot:r2d2 [ token="<ACCESS_TOKEN>" ]

```java
sitemap pushbullet label="Pushbullet"
{
Switch item=Pushbullet_R2D2_Button
}
```

pushbullet.rules
demo.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("[email protected]", "Title R2D2 OH2", "This has been sent by the new R2D2 bot")
logInfo(filename, "Result of send action is: " + result)
}
}
end
val actions = getActions("pushbullet", "pushbullet:bot:r2d2")
// push a note
actions.sendPushbulletNote("[email protected]", "Note Example", "This is the pushed note.")
// push a link
actions.sendPushbulletLink("[email protected]", "Link Example", "This is the pushed link", "https://example.com")
// push a file
actions.sendPushbulletFile("[email protected]", "File Example", "This is the pushed file", "https://example.com/image.png")
actions.sendPushbulletFile("[email protected]", null, null, "/path/to/somefile.pdf", "document.pdf")
// use toFullString method to push the content of an Image item
actions.sendPushbulletFile("[email protected]", ImageItem.state.toFullString)
```

## Creating an account for your bot(s)
## Creating an account

The pushbullet accounts are bound to either Google or Facebook accounts.
A Pushbullet account is linked to either a Google or Facebook account.

- 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".
- Go to the [Pushbullet](https://www.pushbullet.com) website.
- Select 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
## Obtaining an access token

The API keys are bound to the pushbullet account.
An access token is linked to a 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>"
- Go to your [Pushbullet account settings](https://www.pushbullet.com/#settings/account) page.
- 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.
- Copy the created access token.

## 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>
As of 2024, free accounts are [limited](https://docs.pushbullet.com/#limits) to 500 pushes per month.
Going over will result in a warning message being logged indicating when your account rate limit will reset.
9 changes: 4 additions & 5 deletions ...let/src/main/java/org/openhab/binding/pushbullet/internal/PushbulletBindingConstants.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,20 +34,19 @@ public class PushbulletBindingConstants {

public static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(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";

// Thing properties
public static final String PROPERTY_EMAIL = "email";
public static final String PROPERTY_NAME = "name";

// Binding logic constants
public static final String API_BASE_URL = "https://api.pushbullet.com/v2";

public static final String API_ENDPOINT_PUSHES = "/pushes";
public static final String API_ENDPOINT_UPLOAD_REQUEST = "/upload-request";
public static final String API_ENDPOINT_USERS_ME = "/users/me";

public static final String HEADER_RATELIMIT_RESET = "X-Ratelimit-Reset";

public static final String IMAGE_FILE_NAME = "image.jpg";

public static final int MAX_UPLOAD_SIZE = 26214400;
Expand Down
13 changes: 0 additions & 13 deletions ...bullet/src/main/java/org/openhab/binding/pushbullet/internal/PushbulletConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@
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.
Expand All @@ -24,21 +23,9 @@
@NonNullByDefault
public class PushbulletConfiguration {

private @Nullable String name;

private String token = "";

private String apiUrlBase = "https://api.pushbullet.com/v2";

public @Nullable String getName() {
return name;
}

public String getAccessToken() {
return token;
}

public String getApiUrlBase() {
return apiUrlBase;
}
}
11 changes: 6 additions & 5 deletions ...ushbullet/src/main/java/org/openhab/binding/pushbullet/internal/PushbulletHttpClient.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@
*/
package org.openhab.binding.pushbullet.internal;

import static org.openhab.binding.pushbullet.internal.PushbulletBindingConstants.*;

import java.time.Instant;
import java.util.Objects;
import java.util.concurrent.ExecutionException;
Expand Down Expand Up @@ -49,11 +51,10 @@
*/
@NonNullByDefault
public class PushbulletHttpClient {
private static final String AGENT = "openHAB/" + OpenHAB.getVersion();

private static final int TIMEOUT = 30; // in seconds
private static final String USER_AGENT = "openHAB/" + OpenHAB.getVersion();

private static final String HEADER_RATELIMIT_RESET = "X-Ratelimit-Reset";
private static final int TIMEOUT = 30; // in seconds

private final Logger logger = LoggerFactory.getLogger(PushbulletHttpClient.class);

Expand Down Expand Up @@ -95,7 +96,7 @@ public <T> T executeRequest(String apiEndpoint, Class<T> responseType) throws Pu
*/
public <T> T executeRequest(String apiEndpoint, @Nullable Object body, Class<T> responseType)
throws PushbulletApiException {
String url = config.getApiUrlBase() + apiEndpoint;
String url = API_BASE_URL + apiEndpoint;
String accessToken = config.getAccessToken();

Request request = newRequest(url).header("Access-Token", accessToken);
Expand Down Expand Up @@ -142,7 +143,7 @@ public void uploadFile(String url, RawType data) throws PushbulletApiException {
* @return the new Request object with default parameters
*/
private Request newRequest(String url) {
return httpClient.newRequest(url).agent(AGENT).timeout(TIMEOUT, TimeUnit.SECONDS);
return httpClient.newRequest(url).agent(USER_AGENT).timeout(TIMEOUT, TimeUnit.SECONDS);
}

/**
Expand Down
7 changes: 1 addition & 6 deletions ...llet/src/main/java/org/openhab/binding/pushbullet/internal/handler/PushbulletHandler.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,12 +78,7 @@ public PushbulletHandler(Thing thing, HttpClient httpClient) {

@Override
public void handleCommand(ChannelUID channelUID, Command command) {
logger.debug("About to handle {} on {}", command, channelUID);

// Future improvement: If recipient is already set, send a push on a command channel change
// check reconnect channel of the unifi binding for that

logger.debug("The Pushbullet binding is a read-only binding and cannot handle command '{}'.", command);
// do nothing
}

@Override
Expand Down
17 changes: 1 addition & 16 deletions bundles/org.openhab.binding.pushbullet/src/main/resources/OH-INF/i18n/pushbullet.properties
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,20 +7,8 @@ thing-type.pushbullet.bot.label = Pushbullet Bot
thing-type.pushbullet.bot.description = Bot to send messages with.

# thing types config
thing-type.config.pushbullet.bot.name.label = Name
thing-type.config.pushbullet.bot.name.description = Explicit Name of Bot, if wanted
thing-type.config.pushbullet.bot.token.label = Access Token
thing-type.config.pushbullet.bot.token.description = Access token obtained from the account settings page
thing-type.config.pushbullet.bot.apiUrlBase.label = API Server
thing-type.config.pushbullet.bot.apiUrlBase.description = The Pushbullet API Server to use, for local testing

# channel types
channel-type.pushbullet.recipient-channel.label = Recipient
channel-type.pushbullet.recipient-channel.description = Mail address or Channel Name
channel-type.pushbullet.title-channel.label = Title
channel-type.pushbullet.title-channel.description = Title of the message
channel-type.pushbullet.message-channel.label = Message
channel-type.pushbullet.message-channel.description = The text that is to be sent
thing-type.config.pushbullet.bot.token.description = Access token obtained from the account settings page.

# action
actionSendPushbulletNoteLabel = publish a Pushbullet message
Expand All @@ -42,6 +30,3 @@ actionSendPushbulletFileInputContent = File Content
actionSendPushbulletFileInputContentDesc = The File Content to publish
actionSendPushbulletFileInputName = File Name
actionSendPushbulletFileInputNameDesc = The File Name to publish

# error texts
offline.conf-error-httpresponseexception = The pushbullet server reported an error, possibly an expired token. Check on web site
41 changes: 4 additions & 37 deletions bundles/org.openhab.binding.pushbullet/src/main/resources/OH-INF/thing/thing-types.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,51 +8,18 @@
<label>Pushbullet Bot</label>
<description>Bot to send messages with.</description>

<channels>
<channel id="recipient" typeId="recipient-channel"/>
<channel id="title" typeId="title-channel"/>
<channel id="message" typeId="message-channel"/>
</channels>
<properties>
<property name="thingTypeVersion">1</property>
</properties>

<config-description>
<parameter name="name" type="text" required="false">
<label>Name</label>
<description>Explicit Name of Bot, if wanted</description>
<advanced>true</advanced>
</parameter>

<parameter name="token" type="text" required="true">
<label>Access Token</label>
<description>Access token obtained from the account settings page</description>
</parameter>

<parameter name="apiUrlBase" type="text" required="true">
<label>API Server</label>
<description>The Pushbullet API Server to use, for local testing</description>
<default>https://api.pushbullet.com/v2</default>
<advanced>true</advanced>
<description>Access token obtained from the account settings page.</description>
</parameter>

</config-description>

</thing-type>

<channel-type id="recipient-channel">
<item-type>String</item-type>
<label>Recipient</label>
<description>Mail address or Channel Name</description>
</channel-type>

<channel-type id="title-channel">
<item-type>String</item-type>
<label>Title</label>
<description>Title of the message</description>
</channel-type>

<channel-type id="message-channel">
<item-type>String</item-type>
<label>Message</label>
<description>The text that is to be sent</description>
</channel-type>

</thing:thing-descriptions>
14 changes: 14 additions & 0 deletions bundles/org.openhab.binding.pushbullet/src/main/resources/OH-INF/update/instructions.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<update:update-descriptions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:update="https://openhab.org/schemas/update-description/v1.0.0"
xsi:schemaLocation="https://openhab.org/schemas/update-description/v1.0.0 https://openhab.org/schemas/update-description-1.0.0.xsd">

<thing-type uid="pushbullet:bot">
<instruction-set targetVersion="1">
<remove-channel id="recipient"/>
<remove-channel id="title"/>
<remove-channel id="message"/>
</instruction-set>
</thing-type>

</update:update-descriptions>

0 comments on commit e1c1e59

Please sign in to comment.