Giter Site home page Giter Site logo

mmm-api's Introduction

Magic Mirror Module: Api

This module for the Magic Mirror² provides a somewhat RESTful(ish) API to control the behaviour of the mirror.

The code is based on the great MMM-Remote-Control module.

Routes

Modules

To send a notification to a module, just send a POST request to

MAGIG_MIRROR_IP:PORT/api/v1/modules/MODULE_NAME/ACTION?payload1key=payload1value&payload2key=payload2value

Example:

curl -X POST 'http://localhost:3001/api/v1/modules/mmm-glance/glance_on?name=news&time=1000'

Global

To send a global notification, use

MAGIG_MIRROR_IP:PORT/api/v1/notify/ACTION?payload1key=payload1value&payload2key=payload2value

Example:

curl -X POST 'http://localhost:3001/api/v1/notify/glance_on?name=news&time=1000'

Validation

The advantage of specifying a module is having some basic validation which helps with debugging and error handling.

Example:

curl -X POST 'http://localhost:3001/api/v1/modules/imaginary_module/do_stuff'

will return a 404 response with an error message:

{"success":"false","error":"Module not found"}

or

{"success":"false","error":"Action not found"}

Successful calls return

{"success":"true"}

Payload

The payload is passed as URL parameters. These are neither validated nor do they trigger an error message for invalid or missing keys or values.

Overview

api/v1

Routes request description
modules GET get a list of all installed modules and actions:
{"success": "true", "modules": {"alert": ["SHOW_ALERT","HIDE_ALERT"]}
modules/moduleName GET get a list of available actions for a module:
{"success":"true","actions":["SHOW_ALERT","HIDE_ALERT"]}
modules/moduleName/action POST send a notification to a module
notify/action POST send a global notification

Installation

Quick install

If you followed the default installation instructions for the Magic Mirror² project, you should be able to use the automatic installer. The following command will download the installer and execute it:

bash -c "$(curl -s https://raw.githubusercontent.com/juzim/MMM-Api/master/installer.sh)"

Manual install

  1. Clone this repository in your modules folder, and install dependencies:
cd ~/MagicMirror/modules # adapt directory if you are using a different one
git clone https://github.com/juzim/MMM-Api.git
cd MMM-Api
npm install
  1. Add the module to your config/config.js file, if you add a position, it will display the URL to the remote on the mirror.
{
    module: 'MMM-Api'
},
  1. Add the IP addresses of devices you want to use to access the Remote Control to the ipWhiteList in your config.js.

  2. Restart your Magic Mirror² (i.e. pm2 restart mm).

Update

Update this module by navigating into its folder on the command line and using git pull:

cd ~/MagicMirror/modules/MMM-Api # adapt directory if you are using a different one
git pull
npm install # install (new) dependencies

Alternatively you can run the installer.sh script again:

~/MagicMirror/modules/MMM-Api/installer.sh

Known limitations

  • the list of actions is generated by pulling some assumed action names from the files and should not be relied on
  • in addition the validation of modules and actions is purely cosmetic to help with debugging and error handling. Since every notification can be send with the notify command, it should not be seen as a security layer

Todo

  • Return available actions/modules on errors
  • Extract routes to separate files
  • Look for available actions only in notificationReceived block
  • (maybe) create a convention for modules to provide information about expected actions and payloads and raise errors for missing, invalid or extra data

mmm-api's People

Contributors

juzim avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.