MMM-PushBulletNotifications
This MagicMirror² module displays phone notifications via the PushBullet API. Use this module to display notifications, send (some) commands to your Magic Mirror or make your Magic Mirror speak out loud.
Inspired by the PushBulletNotes module created by GitHub user maliciousbanjo and the Phone Notification Mirror module created by GitHub user ronny3050
Dependencies / Requirements
PushBullet
This module uses PushBullet (https://www.npmjs.com/package/pushbullet). PushBullet can be installed on your phone or computer. This module uses the Realtime Event Stream with normal pushes and ephemerals.
From the Pushbullet API documentation:
You can send arbitrary JSON messages, called "ephemerals", to all devices on your account. Ephemerals are stored for a short period of time (if at all) and are sent directly to devices.
Mirrored notifications are notifications sent from android devices (currently the only source of mirrored notifications) to other devices
Note:
- if SMS mirroring is configured in Pushbullet always the last received SMS on the phone will be shown on the Magic Mirror. Earlier received SMS messages are automatically dismissed by PushBullet.
- Limitation: on iOS/iPhone only pushes (messages) can be send using the PushBullet App, mirrored notifications only work on android devices.
The PushBullet API documentation can be found here (https://docs.pushbullet.com/). To use the API you need an API Access Token. This Access Token can be created in your PushBullet account under settings. The PushBullet API Access Token has to be set in the configuration for this module to work (see configuration options).
Magic Mirror device
The following step is optional and can be used for filtering purposes. Create 'Magic Mirror' as a device in PushBullet to be able to send messages to your Magic Mirror using this curl command:
curl --header 'Access-Token: <your_access_token_here>' \
--header 'Content-Type: application/json' \
--data-binary '{"app_version":1,"manufacturer":"<your_name>","model":"Magic Mirror","nickname":"Magic Mirror","push_token":"","icon":"system"}' \
--request POST https://api.pushbullet.com/v2/devices
Replace <your_access_token_here> with the Access Token created in PushBullet en replace <your_name> with your name. This curl command can be executed from your raspberry pi terminal and a device will be added in PushBullet.
This device can be set as filter (see configuration options) to show only notifications send to this device.
Other
- Play-sound package is used to play a sound when a notification is received.
- The module MMM-TTS of GitHub user fewieden is used for offline Text-To-Speech. See installation instructions here
Installation
In your terminal, go to your MagicMirror's Module folder:
cd ~/MagicMirror/modules
Clone this repository:
git clone https://github.com/basknol/MMM-PushBulletNotifications.git
Go to the MMM-PushBulletNotifications folder:
cd MMM-PushBulletNotifications
Install necessary dependencies:
npm install
Using the module
To use this module, add it to the modules array in the config/config.js
file:
Only the AccessToken is required, other config properties can be left out and the defaults will be used.
modules: [
{
module: 'MMM-PushBulletNotifications',
header: 'Notifications',
position: 'bottom_right', // This can be any of the regions.
config: {
// See 'Configuration options' for more information.
accessToken: "", //PushBullet API Access Token
endToEndPassword: null,
numberOfNotifications: 3,
filterTargetDeviceName: "",
showPushesSentToAllDevices: true,
onlyAllowCommandsFromSourceDevices: [],
fetchLimitPushBullet: 50,
showPushes: true,
showPushesOnLoad: true,
showDismissedPushes: true,
showMirroredNotifications: true,
onlyShowLastNotificationFromApplication: false,
showIndividualNotifications: false,
showSMS: true,
showMessage: true,
showIcons: true,
showDateTime: true,
localesDateTime: 'nl-NL',
playSoundOnNotificationReceived: true,
soundFile: 'modules/MMM-PushBulletNotifications/sounds/new-message.mp3',
maxMsgCharacters: 50,
maxHeaderCharacters: 32,
showModuleIfNoNotifications: true,
noNotificationsMessage: "No new notifications",
debugMode: false,
}
}
]
Configuration options
Some configuration properties changed from v1.0.1 to v1.1.0
- showNotificationsSentToAllDevices is renamed to showPushesSentToAllDevices
- showNotificationsOnLoad is renamed to showPushesOnLoad
The following properties can be configured:
Option | Description |
---|---|
accessToken |
PushBullet API Access Token. This Access Token can be created in your PushBullet account under [settings](https://www.pushbullet.com/#settings) This value is REQUIRED |
endToEndPassword |
PushBullet End-To-End encryption password. This must be the same as on the sender device. This value is OPTIONAL |
numberOfNotifications |
Integer value, the number of notifications to show on the Magic Mirror. This includes pushes and ephemerals (mirrored notifications and SMS) Example: 5
Default value: 3
This value is OPTIONAL |
filterTargetDeviceName |
String value, only show pushes that are send to this PushBullet device. Example: Magic Mirror
Default value: empty string
This value is OPTIONAL |
showPushesSentToAllDevices |
Boolean value, show pushes to all devices in PushBullet (=true). This option is only used if the option 'filterTargetDeviceName' is filled in. Possible values: true or false
Default value: true
This value is OPTIONAL |
onlyAllowCommandsFromSourceDevices |
Array value containing strings. If this array is empty commands (=pushes start with mm:) from every device is allowed. Each string should be the nickname of a PushBullet device. To get a list of devices from the API run the curl command: curl --header 'Access-Token: ' https://api.pushbullet.com/v2/devices Commands should be prefixed with 'mm:'. A list of command currently supported.
Example: ['MY-PC', 'My iPhone']
Default value: empty array []
This value is OPTIONAL |
fetchLimitPushBullet |
Integer value, option to limit the number of pushes are fetched from PushBullet Example: 20
Default value: 50
This value is OPTIONAL |
showPushes |
Boolean value, show normal pushes that are sent using Pushbullet app on phone or computer Possible values: true or false
Default value: true
This value is OPTIONAL |
showPushesOnLoad |
Boolean value, load pushes from PushBullet when this module is loaded (=true). Otherwise pushes are loaded when the first push was sent with PushBullet after starting up the Magic Mirror Possible values: true or false
Default value: true
This value is OPTIONAL |
showDismissedPushes |
Boolean value, pushes and ephemerals (mirrored notifications and SMS) can be dimissed. Ephemerals are always gone when dismissed. Pushes can be dismissed but are still available in history. Set this option to true if you want to load dismissed pushes. If this option is set to false dismissed pushes are not shown. Possible values: true or false
Default value: true
This value is OPTIONAL |
showMirroredNotifications |
Boolean value, show notifications that are mirrored from android devices (phone). Mirror Notifications are currently only supported on android devices by Pushbullet. Using mirrored notifications you can show e.g. e-mail, WhatsApp, Hangouts (etc.) notifications on your mirror (and notifications of many more apps that you enable mirrored notifications for) Possible values: true or false
Default value: true
This value is OPTIONAL |
onlyShowLastNotificationFromApplication |
Boolean value, only show the last notification from an application (=true). For example: only show the last received notification from WhatsApp regardless of the sender. If this setting is set to true the setting showIndividualNotifications is ignored.Possible values: true or false
Default value: false
This value is OPTIONAL |
showIndividualNotifications |
Boolean value, show all received notifications from an application (=true). For example: show all notifications from WhatsApp, also from the same sender. Set onlyShowLastNotificationFromApplication and this setting to false if you only want to show the last notification of a sender.Possible values: true or false
Default value: false
This value is OPTIONAL |
showSMS |
Boolean value, show SMS messages that are mirrored from your phone on the Magic Mirror (=true). Possible values: true or false
Default value: true
This value is OPTIONAL |
showMessage |
Boolean value, show the PushBullet notification content Possible values: true or false
Default value: true
This value is OPTIONAL |
showIcons |
Boolean value, show icon based on source device (desktop, phone, system icon) Possible values: true or false
Default value: true
This value is OPTIONAL |
showDateTime |
Boolean value, show date and time of when notification was created Possible values: true or false
Default value: true
This value is OPTIONAL |
localesDateTime |
String value, specify the language whose formatting conventions for date and time should be used. (See [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString) for details. Example: en-US
Default value: nl-NL
This value is OPTIONAL |
playSoundOnNotificationReceived |
Boolean value, play a sound when a notification is received. Possible values: true or false
Default value: true
This value is OPTIONAL |
soundFile |
String value, path to the sound file that has to be played when a notification is received. Example: 'modules/MMM-PushBulletNotifications/sounds/new-message.mp3'
Default value: 'modules/MMM-PushBulletNotifications/sounds/new-message.mp3'
This value is OPTIONAL |
maxMsgCharacters |
String value, the maximum number of characters to show from the notification body. Example: 75
Default value: 50
This value is OPTIONAL |
maxHeaderCharacters |
String value, the maximum number of characters to show from the notification header. The header shows the sender's name. Example: 20
Default value: 32
This value is OPTIONAL |
showModuleIfNoNotifications |
Boolean value, show (=true) or hide (=false) the module if there are no notifications to show. Possible values: true or false
Default value: true
This value is OPTIONAL |
noNotificationsMessage |
String value, the message to show if there are no new notifications and `showModuleIfNoNotifications` is set to true Example: You didn't miss a thing!
Default value: No new notifications
This value is OPTIONAL |
debugMode |
Boolean value, shows additional logging messages if set to true (e.g. when started with `npm start dev` or `node serveronly`). Possible values: true or false
Default value: false
This value is OPTIONAL |