MMM-Serial-Navigator

This is a module for the MagicMirror project, which provides the possibility to navigate through a menu and send notifications based on input trough a serial interface of the server. It can be used to connect input devices (like a rotary encoder and buttons) through a device with serial interface (like an Arduino or other Microcontrollers).

The menu can be permanently hidden, to simply provide a simple interface between serial and notifications. The module can also receive notifications to send serial data to the client.

The communication protocol is line based. Every command from the serial interface should be a seperate line. It does not matter, what line ending you use (line feed, carriage return or both). When you use the WRITE_TO_SERIAL notification, a line feed character ("\n") is appended to the data.

For providing the menu I started with the MMM-Navigate module of Ax-LED (https://github.com/Ax-LED/MMM-Navigate). I copied the code and changed it, until it suited my needs.

Images

Installation

Run these command at the root of your magic mirror install.

cd modules
git clone https://github.com/lucullusTheOnly/MMM-Serial-Navigator.git
cd MMM-Serial-Navigator
npm install

Using the module

To use this module, add the following configuration block to the modules array in the config/config.js file:

var config = {
  modules: [
    {
      module: 'MMM-Serial-Navigator',
      position: 'bottom_right', // choose your desired position of the shown menu from the options provided by MagicMirror^2
      config: {
        // See below for configurable options
      }
    }
  ]
}

The standard configuration (as below) is written for an Arduino and a rotary encoder (with integrated switch) an an extra button. The menu navigation is done with the rotary encoder, whose action will emit the serial commands "CW", "CCW" and "SW". When a menu entry is locked, the rotary encoder can be rotated to control a module (for example scroll through the profiles of the MMM-Carousel module). To also provide an OK button for the module, an extra button with the serial command "BTN1" is used. You can find the corresponding Arduino sketch in the docs folder.

For further information about how the parameters for the serial interface can be configured, please refer to the nodejs module serialport, since the corresponding parameters of this module are just handed over to it.

Standard Configuration:

config: {
  hideMenu: false,
  menuTimeout: 5000,
  serialDev: '/dev/ttyUSB0',
  baudrate: 9600,
  dataBits: 8,
  parity: 'none',
  stopBits: 1,
  flowControl: false,
  serialCodes:[ "CW", "CCW", "SW", "BTN1" ],
  states: [
    'Change Profile',
    'News Feed',
    'Test notification',
    'Restart MagicMirror (PM2)',
    'Restart',
    'Shutdown'
  ],
  actions: [
    {
      serialCode: "CW",
      menuAction: "next",
      notifications: [
        {
          state: 'Change Profile',
          notification: 'CAROUSEL_NEXT',
          payload: ''
        },
        {
          state: 'News Feed',
          notification: 'ARTICLE_NEXT',
          payload: ''
        }
      ]
    },
    {
      serialCode: "CCW",
      menuAction: "previous",
      notifications: [
        {
          state: 'Change Profile',
          notification: 'CAROUSEL_PREVIOUS',
          payload: ''
        },
        {
          state: 'News Feed',
          notification: 'ARTICLE_PREVIOUS',
          payload: ''
        }
      ]
    },
    {
      serialCode: "SW",
      menuAction: "lock",
      notifications: [
        {
          state: 'Test notification',
          notification: 'SHOW_ALERT',
          payload: { type: "notification", message: "This is a test message."}
        },
        {
          state: 'Restart MagicMirror (PM2)',
          notification: 'REMOTE_ACTION',
          payload: {action: "RESTART"}
        },
        {
          state: 'Restart',
          notification: 'REMOTE_ACTION',
          payload: {action: "REBOOT"}
        },
        {
          state: 'Shutdown',
          notification: 'REMOTE_ACTION',
          payload: {action: "SHUTDOWN"}
        }
      ]
    },
    {
      serialCode: "BTN1",
      notifications: [
        {
          state: 'News Feed',
          notification: 'ARTICLE_TOGGLE_FULL',
          payload: ''
        }
      ]
    }
  ]
}

Configuration options

The following properties can be set for this module:

Option	Description
hideMenu	Hides the visual output of the module for making it work only in background. This value is OPTIONAL Possible values: true or false Default value: false
menuTimeout	Time in milliseconds, when the menu will be hidden after the last activity This value is OPTIONAL Possible values: any positive, valid integer Default value: 5000
serialDev	Serial device to open. This value is OPTIONAL Possible values: any valid path (String) to a readable serial device Default value: '/dev/ttyUSB0'
baudrate	The baudrate to use with the serial device. This value is OPTIONAL Possible values: any valid baudrate (int) Default value: 9600
dataBits	The number of databits to use with the serial device. This value is OPTIONAL Possible values: any vaild number of databits (int) Default value: 8
parity	The parity mode, in which the serial device should operate. This value is OPTIONAL Possible values: any valid parity mode (String) Default value: 'none'
stopBits	The number of stopbits to use with the serial device. This value is OPTIONAL Possible values: any valid number of stopBits (int) Default value: 1
flowControl	If flow control should be used on the serial interface. This value is OPTIONAL Possible values: true or false Default value: false
serialCodes	A list of serial codes (strings), that should be used as input. Any code, that is not in this list, will be ignored. This value is OPTIONAL Possible values: String array Default value: [ "CW", "CCW", "SW", "BTN1" ]
states	A list of states/menu entries, that will be displayed in the menu. This value is OPTIONAL Possible values: String array Default value: [ 'Change Profile', 'News Feed', 'Test notification', 'Restart MagicMirror (PM2)', 'Restart', 'Shutdown' ]
serialCodes	A list of actions, that will be executed on serial commands (see below). This value is OPTIONAL Possible values: Any valid actions as defined below Default value: (see the standard configuration above)

Action Configuration

This is the logic core of the module. An actions defines, which notifications will be send and which menu navigations will be executed due to which serial command and in which situation.

Each action must have a unique serialCode, which is the corresponding command, that will be receive through the serial interface. An action can have the menuAction parameter. It defines the commands role in navigating through the menu and can have one the values "next", "previous" and "lock".

The notifications that will be emitted from a serial command, are listed in the notifications array. Each notification can have a state, in which it should be active. If the state is test, the notification will only be send, if test menu entry is currently locked. If you don't specify a state (omitting this parameter), the notification can be send from every state, except for the once, where a better fit is listed for this action. For example you can specify two notifications for an action:

{
  serialCode: "BTN1",
  notifications: [
    {
      notification: "GENERAL_NOTIFICATION",
      payload: ''
    },
    {
      state: "Specific state",
      notification: "SPECIFIC_NOTIFICATION",
      payload: ''
    }
  ]
}

The serial command BTN1 will emit the GENERAL_NOTIFICATION from everywhere, except when being in the state/locked menu entry Specific state, in which case it will emit the SPECIFIC_NOTIFICATION, since it is a better fit for the situation. Furthermore you have to specify the notification and it's payload (optional).

The action with menuAction: "lock" cannot be used for controlling other modules, since it has to unlock the entry, when necessary. So it can only contain notifications for unlockable menu entries.

Option	Description
serialCode	Command string, that should trigger the following actions, when received through the serial interface. This value is NOT OPTIONAL Possible values: any String (not containing line feed or carriage return characters)
menuAction	If included, this will set the menu action, that will be executed on receiving the serial command, when in menu state. If you use the value `lock`, you should not include notifications for lockable menu entries. This value is OPTIONAL Possible values: String, one of `'next'`, `'previous'` or `'lock'`
notifications	A list of notifications, that can be triggered by this serial command. This value is NOT OPTIONAL Possible values: notifications as defined below

Notification configuration options

Option	Description
state	State/Menu entry, for which the notification should be emitted. If omitted, the notification will be used for every state, for which no better fit is listed. This value is OPTIONAL Possible values: String, one of the previously defined states
notification	Notification, that should be emitted to the MagicMirror System for other modules to receive. This value is NOT OPTIONAL Possible values: any valid String
payload	Payload for the notification. This value is OPTIONAL Possible values: Any valid JSON object Default value: ''

Notifications

The module can receive the following notifications.

Option	Description
WRITE_TO_SERIAL	Sends data over the serial interface to the client. The payload has to contain the key data (String)