/MMM-PushBulletNotifications

Module that displays phone notifications via the PushBullet API

Primary LanguageJavaScriptMIT LicenseMIT

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

MagicMirror Notifications

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.
  • mm:shutdown
  • mm:hide all modules
  • mm:hide module:<modulename>
  • mm:show all modules
  • mm:show module:<modulename>
  • mm:display off
  • mm:display on
  • mm:play sound
  • mm:say:Hello World (this requires that the MMM-TTS is installed)

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