M2M Bridge

Functionality

• Configurable edge intelligence
• Bridges standard and proprietary protocols to AMTech IoT DAP.
• Device-to-device or device-to-cloud communications.
  • MQTT, LLRP, CoAP, STOMP, SmartM2M, LWM2M, PLC, Zigbee and others
• Allow remote and centralized control of IoT devices and gateways.
  • SNMP/MIB/TRAP, Reader Management and other
• Configurable auto-discover
• Implements common functionality and orchestrates the execution of the protocols
• Network failure detection and recovery
• Get centralized configuration information at startup and real time modifications
• Access control policies to manage observation production and consumption

Edge Configuration

• Edge/Device(s) site configuration bridgeConfig.json

   {
   //text to label bridge instance
   "description": "AMTech M2M Bridge", 
       "dap":{
           //amtech IoT DAP ur
           "dapUrl": "https://dap.amtech.mx",     
           //userid for the m2mBridge instance 
           "userId": "xxxxxxx@amtech.mx",
           // tenant where bridge been configured       
           "tenant" : "xxxxxxx",  
           //m2mBridge userId password  
           "password" :"xxxxxxxx",
           //topic to get crud (observationresourcecrud) and command observations (See CRUD observations Send command ) 
           "crudCommandUrl" :"/xx/xx/"		
       },
       //access control information add to send observations
       "guestSecurity":{
           //add guest tenants to observations send from bridge
           "guesttenants":["progressnext2016"],    
           //add guest users to observations send from bridge
           "guestusers":[]		       
       },
       //network failed configuration
       "networkFailed" :{
           //re-connection delay after an instance of plug in failed 
           "reconnectWait" : 60000	       
       },
       //bridge startup configuration
       "pluginLoad" :{			         
            //send observations error when errors occurred at bridge layer 
            "sendM2mBridgeError" : true		
       },
       //network failed configuration
       "logger" :{
           //network failed configuration
           "colorize" : true, //colorize log console messages
           //network failed configuration
           "level": "debug"			//log level
       },
       //Address use to geo locate m2mBridge instance
       "address" :{				 
           "country" : "usa",
           "city": "Las Vegas",
           "road": "Las Vegas Boulevard South",
           "number":"3960"
       },
       //Id to uniquely identify a M2MBridge instance, in absence of this property a unique identifier gets created
       "bridgeId":"m2mBridgeProgressNext",       
       //auto discover configuration
       "autoDiscover":{
           //create things type instances at startup time
           "execute" : false,                         
           //Jsonld instances of the thing to be created 
           "instances":{
           //SNMPDeveice jsonld instance
          "SNMPDevice":[
               {
                   "setOIDs": "[{\"oid\":\".1.3.6.1.2.1.1.6.0\", \"type\":\"OctetString\", \"value\":\"Irvine California\"}]",
                   "_lastmodified": 1450988442414,
                   "guestusers": [],
                   "@type": "/amtech/linkeddata/types/composite/entity/SNMPDevice",
                   "_resourcestatus": "valid",
                   "_name": "snmpClientM2mBridge",
                   "getOIDs": "[{\"name\":\"memoryTotal\", \"oid\":\".1.3.6.1.4.1.2021.4.5.0\"},  {\"name\":\"memoryAvailable\", \"oid\":\".1.3.6.1.4.1.2021.4.6.0\"}]",
                   "ipaddress": "localhost",
                   "communityString": "private",
                   "emaillist": "",
                   "instanceobservationconfig": "{}",
                   "creationDate": "2015-12-24T20:20:42.407Z",
                   "readFrequency": "PT10M",
                   "guesttenants": [
                       "follower_m2mcreator@@amtech.mx"
                   ],
                   "description": "An SNMPDevice instance acting as SNMP manager/client proxying snmp commands (get/set/trups) to manager a ubuntu box hosting m2mbridge",
                   "phonelist": "",
                   "@id": "/amtech/things/entities/snmpClientM2mBridge",
                   "snmpVersion": "2c",
                   "_user": "m2mcreator@amtech.mx"
               }
           ], …
       }
   }

Cloud Configuration

• Create an "m2mBridge" actor (See Actors)
  • Add the things type polices the bridge needs access to
  • Police must have user check; enabling instance access control by m2mBridge instance
  • Include in the polices the thing types the bridge instantiates
• Register a follower (See Roles)
  • Assign to follower actor "m2mBridge" access
  • Uniquely identify each m2mBridge
• Activity observation configuration (See Observation production configuration)
  • Add the Things types the bridge will use (See Thing types)
    • Add the observations types from selected thing type the bridge will produce or consume (See Observations and observation types CRUD observations)
  • Configure the topic that m2mBridge will listen for crud and command observations has to matched with bridgeConfig.json property (See Edge Configuration Topics)

//topic to get crud and command observations                             
"dap":{
       "crudCommandUrl" :"/xx/xx/"			
   }

• Things instance creation
  • Using amtech creator experience (See Thing types)
  • Configuring autoDiscover entry at bridgeConfig.json (See Edge Configuration)

Implementation notes

• M2MBridge is an open source nodes stack developed by the AMTEch team; it discovers, loads nodes modules implementing "M2MBridge plugin interface" and creates thing types instances (See Thing types) tacking into account the observation production configuration (See Observation production configuration) and M2MBridge credentials (See Actors and Edge Configuration).
  • It leverages AMTech IoT DAP integration guidelines to implement its functionality (See Integration Guideline)
    • Gets observation production configuration (See Observation production configuration API)
    • Gets thing types instances (See Observation instances API)
    • Creates a web socket to receive asynchronous commands and thing instances changes (crud operations) (See CRUD and Commands API)
      • Dispatch command observations to unique instance
      • Restart instance when supported properties change by calling stop and star plugin interface
    • Creates configuration information for Thing type leveraging configuration information and client side M2MBridge placeholders
    • Load plugin nodes modules if required by configuration
    • Creates an instance of plugin for each type from observation production configuration
    • Creates a dispatcher observation with persistence to warranty the deliver of the message when network failed occurred.
      • Injects sendObservation functionality to each plugin instance

How to implement a new plugin

• Clone git repository (https://github.com/AMTechMX/M2MBridge.git)
  • at /.../M2MBridge/plugins create a directory that matched with the Thing type name to bridge example SNMPDevice (See Thing types)
• Implement a nodejs module with the following interface

   function SNMPDevice() {
   }
   SNMPDevice.prototype.start = function ( context, complete) {
       try {
           complete(null);
       } catch (e) {
           complete(e);
       }
   };
   SNMPDevice.prototype.stop = function (complete) {
       try {
           complete(null);
       } catch (e) {
           complete(e);
       }
   };
   SNMPDevice.prototype.command = function (observation, complete) {
       try {
           complete(null);
       } catch (e) {
           complete(e);
       }
   };
   module.exports.SNMPDevice = SNMPDevice;

How to install it

• Clone git repository (https://github.com/AMTechMX/M2MBridge.git)
• Install nodejs https://nodejs.org/en/download/package-manager/
• Install npm (http://blog.npmjs.org/post/85484771375/how-to-install-npm)
• Delete at /.../M2MBridge/plugins/xxx unneeded plug-ins
• Install packages for m2mBridge core and plug-ins (https://docs.npmjs.com/cli/install:)
• Execute npm install at:
  • M2MBridge directory
  • each plug-in directory