Skip to content

Commit 9a6258b

Browse files
florian-h05florian-h05
authored
[openhabcloud] Update README for new notification features (openhab#16941)
* [openhabcloud] Update README for new notification features Signed-off-by: Florian Hotze <[email protected]>
1 parent 95d1b6f commit 9a6258b

File tree

1 file changed

+176
-2
lines changed

1 file changed

+176
-2
lines changed

‎bundles/org.openhab.io.openhabcloud/README.md

+176-2
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ openHAB Cloud service hosted by the [openHAB Foundation](https://www.openhabfoun
88
The openHAB Cloud service (and thus the connector to it) is useful for different use cases:
99

1010
* It allows remote access to local openHAB instances without having to expose ports to the Internet or to require a complex VPN setup.
11-
* It serves as a connector to Google Cloud Messaging (GCM) and Apple Push Notifications (APN) for pushing notifications to mobile phone apps.
12-
* It provides integrations with 3rd party services that require OAuth2 authentication, such as Amazon Alexa or Google Home applications
11+
* It serves as a connector to Firebase Cloud Messaging (FCM) for pushing notifications to mobile phone apps.
12+
* It provides integrations with 3rd party services that require OAuth2 authentication, such as Amazon Alexa or Google Home applications.
1313

1414
## Installation via UI
1515

@@ -78,3 +78,177 @@ Alternatively, you can configure the settings in the file `conf/services/openhab
7878
```
7979

8080
Note: The optionally exposed items will show up after they receive an update to their state.
81+
82+
## Cloud Notification Actions
83+
84+
The openHAB Cloud Connector allows to send push notifications to apps on mobile devices registered with an [openHAB Cloud instance](https://github.com/openhab/openhab-cloud) such as [myopenHAB.org](https://www.myopenhab.org).
85+
86+
To send push notifications, the notification actions have to be used in rules.
87+
88+
### Basic Usage
89+
90+
Three different actions are available:
91+
92+
- `sendNotification(emailAddress, message)`: Send a notification to a _specific_ openHAB Cloud user.
93+
- `sendBroadcastNotification(message)`: Send a broadcast notification to _all_ devices of _all_ users.
94+
- `sendLogNotification(message)`: Send a log notification to the notifications list. Log notifications do not trigger a notification on the device.
95+
96+
For each of the three actions, there's another variant accepting an icon name and a severity:
97+
98+
- `sendNotification(emailAddress, message, icon, severity)`
99+
- `sendBroadcastNotification(message, icon, severity)`
100+
- `sendLogNotification(message, icon, severity)`
101+
102+
Icon and severity can potentially be used by cloud instance clients (such as the openHAB apps for Android or iOS) to be displayed in the notification itself and the list of notifications.
103+
104+
The parameters for these actions have the following meaning:
105+
106+
- `emailAddress`: String containing the email address the target user is registered with in the cloud instance.
107+
- `message`: String containing the notification message text.
108+
- `icon`: String containing the icon name (as described in [Items]({{base}}/configuration/items.html#icons)).
109+
- `severity`: String containing a description of the severity of the incident.
110+
111+
`null` may be used to skip the `icon` or `severity` parameter.
112+
113+
### Title, Media Attachments & Actions
114+
115+
The `sendNotification` and `sendBroadcastNotification` actions additionally support setting a title, media attachments and actions.
116+
117+
The title is displayed as the notification title on the device and defaults to "openHAB" for the Android and iOS apps.
118+
Media attachments are displayed together with the notification on the device and can be used to display images, e.g. a camera snapshot.
119+
Actions allow the user to interact with the notification, e.g. to open a specific page in the app or to send a command to an Item.
120+
121+
There are four different actions available:
122+
123+
- click action: Is performed when the user clicks on the notification.
124+
- action button 1, 2 or 3: Is performed when the user clicks on the first, second or third action button.
125+
126+
To specify media attachments and actions, there is another variant of the `sendNotification` and `sendBroadcastNotification` actions:
127+
128+
- `sendNotification(emailAddress, message, icon, severity, title, onClickAction, mediaAttachmentUrl, actionButton1, actionButton2, actionButton3)`
129+
- `sendBroadcastNotification(message, icon, severity, title, onClickAction, mediaAttachmentUrl, actionButton1, actionButton2, actionButton3)`
130+
131+
The additional parameter for these variants have the following meaning:
132+
133+
- `title`: The title of the notification. Defaults to "openHAB" inside the Android and iOS apps.
134+
- `onClickAction`: The action to be performed when the user clicks on the notification. Specified using the [action syntax](#action-syntax).
135+
- `mediaAttachmentUrl`: The URL of the media attachment to be displayed with the notification. This URL must be reachable by the push notification client.
136+
- `actionButton1`: The action to be performed when the user clicks on the first action button. Specified as `Titel=$action`, where `$action` follow the [action syntax](#action-syntax).
137+
- `actionButton2`: The action to be performed when the user clicks on the second action button. Specified as `Titel=$action`, where `$action` follow the [action syntax](#action-syntax).
138+
- `actionButton3`: The action to be performed when the user clicks on the third action button. Specified as `Titel=$action`, where `$action` follow the [action syntax](#action-syntax).
139+
140+
These parameters may be skipped by setting them to `null`.
141+
142+
#### Action Syntax
143+
144+
The action syntax is a string containing the action type and the action payload seperated by a colon.
145+
146+
There are two types of actions available:
147+
148+
- `command`: Sends a command to an Item by using the following syntax: `command:$itemName:$commandString` where `$itemName` is the name of the Item and `$commandString` is the command to be sent.
149+
- `ui`: Controls the UI in two possible ways:
150+
- `ui:$path` where `$path` is either `/basicui/app?...` for navigating sitemaps (using the native renderer) or `/some/absolute/path` for navigating (using the web view).
151+
- `ui:$commandItemSyntax` where `$commandItemSyntax` is the same syntax as used for the [UI Command Item]({{base}}/mainui/about.html#ui-command-item).
152+
153+
Examples:
154+
155+
- `command:KitchenLights:ON`
156+
- `command:KitchenBlinds:50`
157+
- `ui:/basicui/app?w=0000&sitemap=main` (use Basic UI to get sitemap URL locations)
158+
- `ui:/some/absolute/path`: Navigates to the absolut path `/some/absolute/path`.
159+
- `ui:navigate:/page/my_floorplan_page`: Navigates Main UI to the page with the ID `my_floorplan_page`.
160+
- `ui:popup:oh-clock-card`: Opens a popup with `oh-clock-card`.
161+
162+
### Examples
163+
164+
Notify the openHAB Cloud user with email address _[email protected]_ that the front door was opened:
165+
166+
:::: tabs
167+
168+
::: tab DSL
169+
170+
```java
171+
rule "Front Door Notification"
172+
when
173+
Item Apartment_FrontDoor changed to OPEN
174+
then
175+
sendNotification("[email protected]", "Front door was opened!")
176+
end
177+
```
178+
:::
179+
180+
::: tab JS
181+
182+
```javascript
183+
rules.when().item('Apartment_FrontDoor').changed().to('OPEN').then(() => {
184+
actions.notificationBuilder('Front door was opened!').addUserId('[email protected]').send();
185+
}).build('Front Door Notification');
186+
```
187+
188+
:::
189+
190+
::::
191+
192+
Notify all openHAB Cloud users that the window was opened:
193+
194+
:::: tabs
195+
196+
::: tab DSL
197+
198+
```java
199+
rule "Open Window Notification"
200+
when
201+
Item Apartment_Window changed to OPEN
202+
then
203+
sendBroadcastNotification("Apartment window was opened!", "window", "HIGH")
204+
end
205+
```
206+
207+
:::
208+
209+
::: tab JS
210+
211+
```javascript
212+
rules.when().item('Apartment_Window').changed().to('OPEN').then(() => {
213+
actions.notificationBuilder('Apartment window was opened!').withIcon('window').withSeverity('HIGH').send();
214+
}).build('Open Window Notification');
215+
```
216+
217+
:::
218+
219+
::::
220+
221+
Notify all openHAB Cloud users that motion was detected, attach a camera snapshot and add action button to turn on the light:
222+
223+
:::: tabs
224+
225+
::: tab DSL
226+
227+
```java
228+
rule "Motion Detected Notification"
229+
when
230+
Item Apartment_MotionSensor changed to ON
231+
then
232+
sendBroadcastNotification("Motion detected in the apartment!", "motion", "MEDIUM", "Motion Detected", null, "https://apartment.my/camera-snapshot.jpg", "command:Apartment_Light:ON", null, null)
233+
end
234+
```
235+
236+
:::
237+
238+
::: tab JS
239+
240+
```javascript
241+
rules.when().item('Apartment_MotionSensor').changed().to('ON').then(() => {
242+
actions.notificationBuilder('Motion detected in the apartment!')
243+
.withIcon('motion')
244+
.withSeverity('MEDIUM')
245+
.withTitle('Motion Detected')
246+
.withMediaAttachment('https://apartment.my/camera-snapshot.jpg')
247+
.addActionButton('Turn on the light=command:Apartment_Light:ON')
248+
.send();
249+
}).build('Motion Detected Notification');
250+
```
251+
252+
:::
253+
254+
::::

0 commit comments

Comments
 (0)