README

m2m

m2m is a lightweight real-time communication library for developing client-server or pub-sub applications using the machine-to-machine framework node-m2m. Your application will be composed of two or more independent service modules running on their own processes similar to microservices pattern.

It uses a FaaS (Function-as-a-Service) API also called serverless allowing anyone to easily create, prototype and test applications in IoT, telematics, data acquisition, process automation and a lot more.

You can deploy multiple private device servers on the fly from anywhere without the usual heavy infrastructure involved in provisioning an on-premise physical servers.

Your device servers will be instantly available and accessible through its user-assigned device id from your client applications.

You can set multiple Channel, HTTP and GPIO ( for Raspberry Pi devices ) resources on your remote devices for client consumption.

Access to clients and devices is restricted to authenticated and authorized users only. All communications traffic between clients and devices are fully encrypted using TLS.

To use this library, users will need to register with node-m2m.

Start your first m2m application using the quick tour guide.

Supported Platform
Node.js version requirement
Installation
Quick Tour
Using the Browser Interface
API

Supported Platform

Raspberry Pi Models: B+, 2, 3, Zero & Zero W, Compute Module 3, 3B+, 3A+, 4B (generally all 40-pin models)
Linux
Windows
Mac

Node.js version requirement

Node.js versions: 10.x, 11.x, 12.x, 14.x, 16.x. Ideally the latest LTS version.

Installation

$ npm install m2m

Raspberry Pi peripheral access (GPIO, I2C, SPI and PWM).

For projects requiring raspberry pi peripheral access such as GPIO, I2C, SPI and PWM, you will need to install array-gpio module.

$ npm install array-gpio

Device Orchestration

Remote Machine Monitoring

Install array-gpio for each remote machine.

$ npm install array-gpio

Server setup

Configure each remote machine's rpi microcontroller with the following GPIO input/output and channel data resources

const { Device } = require('m2m');
const { setInput, setOutput, watchInput } = require('array-gpio');

const sensor1 = setInput(11); // connected to switch sensor1
const sensor2 = setInput(13); // connected to switch sensor2

const actuator1 = setOutput(33); // connected to alarm actuator1
const actuator2 = setOutput(35); // connected to alarm actuator2

// assign 1001, 1002 and 1003 respectively for each remote machine
const device = new Device(1001);

let status = {};

// Local I/O machine control process
watchInput(() => {
  // monitor sensor1
  if(sensor1.isOn){
    actuator1.on();
  }
  else{
    actuator1.off();
  }
  // monitor sensor2
  if(sensor2.isOn){
    actuator2.on();
  }
  else{
    actuator2.off();
  }
});

// m2m device application
device.connect(() => {

  device.setData('machine-status', function(data){

    status.sensor1 = sensor1.state;
    status.sensor2 = sensor2.state;

    status.actuator1 = actuator1.state;
    status.actuator2 = actuator2.state;

    console.log('status', status);

    data.send(JSON.stringify(status));
  });
});

Client application to monitor the remote machines

In this example, the client will iterate over the remote machines once and start watching each machine's sensor and actuactor status. If one of the sensors and actuator's state changes, the status will be pushed to the client.

const { Client } = require('m2m');

const client = new Client();

client.connect(() => {

  client.accessDevice([100, 200, 300], function(devices){
    let t = 0;
    devices.forEach((device) => {
      t = t + 100;
      setTimeout(() => {
        // device watch interval is every 10 secs
        device.watch('machine-status', 10000, (data) => {
          console.log(device.id, 'machine-status', data); // 200 machine-status {"sensor1":false,"sensor2":false,"actuator1":false,"actuator2":true}
          /* If one of the machine's status has changed,
           * it will receive only the status from the affected machine
           *
           * Add logic to process the 'machine-status' channel data
           */
        });
      }, t);
    });
  });
});

Using the Browser Interface

Remote Application Code Editing

Using the browser interface, you can download, edit and upload your application code from your remote clients and devices from anywhere.

To allow the browser to communicate with your application, add the following m2mConfig property to your project's package.json.

"m2mConfig": {
  "code": {
    "allow": true,
    "filename": "device.js"
  }
}

Set the property allow to true and provide the filename of your application.

From the example above, the filename of the application is device.js. Replace it with the actual filename of your application.

Application Auto Restart

Using the browser interface, you may need to restart your application after a module update, code edit/update, or a remote restart command.

Node-m2m uses nodemon to restart your application.

$ npm install nodemon

You can add the following nodemonConfig and scripts properties in your project's npm package.json as auto-restart configuration.

"nodemonConfig": {
  "delay":"2000",
  "verbose": true,
  "restartable": "rs",
  "ignore": [".git", "public"],
  "ignoreRoot": [".git", "public"],
  "execMap": {"js": "node"},
  "watch": ["node_modules/m2m/mon"],
  "ext": "js,json"
}
"scripts": {
  "start": "nodemon device.js"
},

From the example above, the filename of the application is device.js. Replace it with the actual filename of your application when adding the scripts property. Then restart your node process using npm start command as shown below.

$ npm start

For other custom nodemon configuration, please read the nodemon documentation.

Code Edit and Auto Restart Automatic Configuration

Install nodemon.

$ npm install nodemon

To configure your package.json for code editing and auto-restart without manual editing of package.json, start your node process with -config flag.

m2m will attempt to configure your package.json by adding/creating the m2mConfig, nodemonConfig, and scripts properties to your existing project's package.json. If your m2m project does not have an existing package.json, it will create a new one.

Assuming your application filename is device.js, start your node application as shown below.

$ node device -config

Stop your node process using ctrl-c. Check and verify your package.json if it was properly configured.

If the configuration is correct, you can now run your node process using npm start command.

$ npm start

Your application should restart automatically after a remote code update, an npm module update, a remote restart command from the browser interface.

Naming your Client Application for Tracking Purposes

Unlike the device/server applications, users can create client applications without registering it with the server.

Node-m2m tracks all client applications through a dynamic client id from the browser. If you have multiple clients, tracking all your clients by its client id is not easy.

You can add a name, location and a description properties to your clients as shown below.

This will make it easy to track all your clients from the browser interface.

const m2m = require('m2m');

const client = new m2m.Client({name:'Main client', location:'Boston, MA', description:'Test client app'});

client.connect(() => {
  ...
});

m2m

Usage no npm install needed!