|
|
(290 intermediate revisions by 4 users not shown) |
Line 1: |
Line 1: |
− | == Functionality ==
| + | [[File:AmtechM2mBridge.svg|40px]] M2MBridge is a software stack that implements M2M edge functionality leveraging AMTech IoT Protocol |
− | * Configurable edge intelligence
| + | # [[M2MBridge Functionality|Functionality]] |
− | * Bridges standard and proprietary protocols to AMTech IoT DAP.
| + | # [[Configuration example]] |
− | ** MQTT, LLRP, CoAP, STOMP, SmartM2M, LWM2M, PLC, Zigbee and others
| + | # [[M2MBridge network]] |
− | * Device-to-device or device-to-cloud communications.
| + | #: [[Aggregation]] |
− | * Allow remote and centralized administration of IoT devices and gateways.
| + | #: [[Edge reasoners]] |
− | ** SNMP/MIB/TRAP and other
| + | #: [[Mesh network]] |
− | * Configurable auto-discover
| + | # [[Intelligence at the Edge]] |
− | * Implements common functionality and orchestrates the execution of the protocols
| + | #: [[WhatIsAPlugin|What is a plugin?]] |
− | * Network failure detection and recovery
| + | #: [[EPC (Electronic product code)]] |
− | * Get centralized configuration information at startup and real time modifications
| + | #: [[Smoothing observations]] |
− | * Access control policies to manage observation production and consumption
| + | # [[Observations production and consumption]] |
− | *The following diagram illustrates a M2MBrdige configuration:
| + | # [[Cloud Configuration]] |
− | **Using LLRP protocol to get the data from EPC tags and send commands to the reader
| + | #: [[Observation production config]] |
− | **Using SNMP to monitor the health o the readers
| + | #: [[Validation]] |
− | **Implementing smoothing, decoding, grouping, access control and other edge intelligence
| + | #: [[Sample configuration for beacons]] |
− | [[File:Example.jpg]] | + | # [[Automatic updates on bridge instance delete]] |
− | | + | # [[Implementation notes]] |
− | == Edge Configuration ==
| + | # [[How to implement a new plugin]] |
− | *bridgeConfig.json located at M2MBridge.js directory
| + | # [[Set up a new Raspberry PI]] |
− | {
| + | # [[Edge Configuration|M2MBridge Edge Configuration]] |
− | <span style="color:red">//text to be assigned to M2MBridges description property</span>
| + | # [[M2MBridge updates]] |
− | "description": "AMTech M2M Bridge",
| + | # [[How to install & execute]] |
− | <span style="color:red">//if the description property will be assigned to M2MBridge's linked things</span>
| + | # [[HelloWorld plugin]] |
− | "description:children" : true,
| + | # Supported plugins |
− | "dap":{
| + | ## [[File:wi-fi.svg|35px]] [[File:tcp-ip.svg|35px]] [https://en.wikipedia.org/wiki/Ethernet Wifi or RJ45 Ethernet] |
− | <span style="color:red">//amtech IoT DAP ur</span>
| + | ##: [[File:SNMPDevice.svg|35px]] [[SNMPDevice]] |
− | "dapUrl": "https://dap.amtech.mx",
| + | ##: [[File:LLRPReader.svg|35px]] [[LLRPReader]] |
− | <span style="color:red">//userid for the m2mBridge instance bridgeId</span>
| + | ##:: [[File:LLRPAntenna.svg|35px]] [[LLRPAntenna]] |
− | "userId": "xxxxxxx@amtech.mx",
| + | ##: [[File:thing-magic.svg|35px]] [[ThingMagicEPCReader]] |
− | <span style="color:red">// tenant where bridge been configured</span>
| + | ##:: [[File:LLRPAntenna.svg|35px]] [[LLRPAntenna]] |
− | "tenant" : "xxxxxxx",
| + | ##: [[File:plc-icon.svg|35px]] [[OPCUADevice]] |
− | <span style="color:red">//m2mBridge userId password</span>
| + | ##: [[File:modbus.svg|45px]] [[ModbusDevice]] |
− | "password" :"xxxxxxxx"
| + | ##: [[File:wioGeneric.png|45px]] [[Wio Devices]] (troubleshooting inside) |
− | },
| + | ##:: [[File:wioNode.svg.svg|35px]] [[wioNode]] |
− | <span style="color:red">//M2MBridge instance id to be cloned</span>
| + | ##:: [[File:wioLink.svg|35px]] [[wioLink]] |
− | "templateId":"m2mCreator:m2mBridge",
| + | ## [[File:bt.svg|35px]] [https://en.wikipedia.org/wiki/Bluetooth_Low_Energy BLE 4.0] |
− | <span style="color:red">//Prefix to add to the unique M2MBridge identifier, the mac address of the device is use as unique id</span>
| + | ##: [[File:BLEbeaconsScanner.svg|35px]] [[BLEbeaconsScanner]] |
− | <span style="color:red">//In absence of the prefix just the mac address is used as identifier</span>
| + | ##: [[File:bleOBDScanner.svg|35px]] [[BLEODB2Scanner]] |
− | "bridgeIdPrefix":"tienda1",
| + | ##: [[File:BLEPeripheralsScanner.svg|35px]] [[BLEPeripheralsScanner]] |
− | <span style="color:red">//wkt location to set m2mBridge location overrides address</span>
| + | ##: [[File:BluvisioniBEEK.jpg|65px]] [[BLEBluvisionBeeksScanner]] |
− | "location": "{\"wkt\":\"POINT(-99.17125583 19.40501031)\",\"sContext\":\"geo\"}",
| + | ##: [[File:BLEGattCentral.svg|35px]] [[BLEGattCentral]] |
− | <span style="color:red">//if the location property will be assigned to M2MBridge's linked things</span>
| + | ## [[File:i2c.svg|35px]] [https://en.wikipedia.org/wiki/I%C2%B2C I2C] |
− | "location:children" : true,
| + | ##: [[File:watersensor.svg|35px]] [[PCA9536I2CWaterDetectionWithBuzzer]] |
− | <span style="color:red">//Address to be used to get m2mBridge's location</span>
| + | ##: [[File:TSL2561Light.svg|65px]] [[TSL2561I2CLight]] |
− | "address" :{
| + | ##: [[File:soundvibration.svg|35px]] [[ADC121C021I2CSoundVibrationShock]] |
− | "country" : "usa",
| + | ##: [[File:ncd-i2c.png|65px]] [https://store.ncd.io/shop/?fwp_interface=i2c-interface NCD I2C devices] |
− | "city": "Las Vegas",
| + | ##: [[File:grove-log.png|65px]] [https://www.seeedstudio.com/category/Grove-c-1003%7C%7C24.html?p=0 Grove devices via I2C] |
− | "road": "Las Vegas Boulevard South",
| + | ## [[File:usb-logo.svg|35px]] [https://en.wikipedia.org/wiki/USB USB 2.0] |
− | "number":"3960"
| + | ##: [[File:thing-magic.svg|35px]] [[ThingMagicEPCReader]] |
− | },
| + | ##:: [[File:LLRPAntenna.svg|35px]] [[LLRPAntenna]] |
− | }
| + | ##: [[File:Phidgets-Logo.png|65px]] [https://www.phidgets.com/?tier=0&catid=3&pcid=12 Phidgets USB sensors] |
− | | + | <!--##:[[File:modbus.svg|45px]] [[ModbusDevice]]--> |
− | == Cloud Configuration ==
| + | ## [[File:xbee-pro-900hp.svg|35px]] [https://www.digikey.com/catalog/en/partgroup/xbee-pro-900hp/33082?utm_adgroup=RF%20&%20RFID XBee-Pro 900HP] |
− | *Create an amtechM2mBridge instance (See "/amtech/linkeddata/types/composite/entity/amtechM2mBridge")
| + | ##: [[File:relay-home-automation.svg|35px]] [[NCDXbee900Relay]] |
− | * Create an actor actorX with the polices required by the activity(s) (See [[Access control#Actors|Actors]])
| + | ##: [[File:energy-monitor.svg|35px]] [[NCDXbee900EnergyMonitor]] |
− | ** Add the things type polices the bridge needs to the actor actorX
| + | ##: [[File:ncd-i2c.png|65px]] [https://store.ncd.io/shop/?fwp_interface=900hp-s3b NCD devices supporting XBee-Pro 900HP communication] |
− | *Register a follower (See [[Access control#Actors|Roles]])
| + | <!-- ## [[File:libelium.svg|45px]] [[waspmoteBLECentral]]--> |
− | ** Assign to follower actor actorX access
| + | ##: [[File:libelium.svg|65px]] [http://www.libelium.com/libeliumworld/waspmote/ Libelium waspmote] |
− | *Activity observation configuration (See [[Activities#Observation production configuration|Observation production configuration]])
| + | ##:: [[File:SmartEnvironment.jpg|65px]] [[Smart environment PRO]] |
− | ** Add the Things types the bridge will use (See [[Activities#Thing types|Thing types]])
| + | ##:: [[File:SmartAgriculture.png|65px]] [[Smart Agriculture]] |
− | *** Add the observations types from selected thing type the bridge will produce or consume (See [[Sensor's network#Observations and observation types|Observations and observation types]] [[Sensor's network#Crud observation|CRUD observations]])
| + | ##:: [[File:SmartWater.jpg|65px]] [[Smart Water]] |
− | ** Configure the topic that m2mBridge will listen for crud and command observations has to matched with others things' observation production configuration linked to this m2mBridge configuration (See [[Activities#Observation production configuration|Observation production configuration]] [[Sensor's network#Topics|Topics]])
| + | ##:: [[File:SmartWaterIons.png|65px]] [[Smart Water Ions]] |
− | *Things instance creation
| + | ##:: [[File:SmartCities.jpg|65px]] [[Smart Cities]] |
− | **Configuring autoDiscover (See [[M2M Bridge#Edge Configuration|Edge Configuration]])
| + | ##:: [[File:SmartParking.jpg|65px]] [[Smart Parking]] |
− | ***The bridge will request the DAP to clone templateId instance with the name convention bridgeIdPrefix:(device mac address) from bridgeConfig.json
| + | ##:: [[File:SmartSecurity.jpg|65px]] [[Smart Security]] |
− | ***the things instances linked to the templateId property bridgeInstances will be cloned with the name convention bridgeIdPrefix:(device mac address):thing._name from bridgeConfig.json
| + | ##:: [[File:Radiation.png|65px]] [[Radiation]] |
− | ***cloned instance will be giving the access control owner to the follower user id of the bridge that requested it.
| + | ##:: [[File:AmbientControl.png|65px]] [[Ambient Control]] |
− | *Monitoring M2MBridge status
| + | |
− | **Create an SNMPDevice instance and give access to your M2MBridge actor (See "/amtech/linkeddata/types/composite/entity/SNMPDevice")
| + | |
− | ***Send observations to /m2mBridge/snmp/read a core activity /amtech/activities/monitorM2MBridgeStatus will analyze the data and notify to the user and guestusers of the M2MBridge instance.
| + | |
− | ****This get done by setting at the observation production configuration /observationproductionconfig/SNMPDevice/observationsproducedconfig/snmpRead topic to value /m2mBridge/snmp/ (See [[Activities#Observation production configuration|Observation production configuration]])
| + | |
− | | + | |
− | == Implementation notes ==
| + | |
− | *M2MBridge is an open source stack developed by the AMTEch team; it discovers and loads nodes modules implementing "M2MBridge plugin interface"(See [[Activities#Thing types|Thing types]]) tacking into account thing instances, activity(s) observation production configuration (See [[Activities#Observation production configuration|Observation production configuration]]) and M2MBridge credentials (See [[Access control#Actors|Actors]] and [[M2M Bridge#Edge Configuration|Edge Configuration]]).
| + | |
− | **It leverages AMTech IoT DAP (See [[Integration Guideline|Integration Guideline]])
| + | |
− | ***Clone configuration from exiting M2MBridge template configuration (See [[M2M Bridge#Edge Configuration|Edge Configuration]])
| + | |
− | ***Gets observation production configuration (See [[Integration Guideline#DAP Restful API#Get observation production configuration|Observation production configuration API]])
| + | |
− | ***Gets thing types instances (See [[Integration Guideline#Get instances by thing type|Observation instances API]])
| + | |
− | ***Creates a web socket to receive asynchronous commands and thing instances changes (crud operations) (See [[Integration Guideline#Commands|CRUD and Commands API]])
| + | |
− | ****Dispatch command observations to plugin instance leveraging thing type instance @id (See [[Activities#Thing types|Thing types]])
| + | |
− | ****Restart instance when supported properties change by calling stop and star plugin interface
| + | |
− | ***Creates configuration information by Thing type leveraging configuration information and client side M2MBridge placeholders (See [[Activities#Observation production configuration|Observation production configuration]] and [[Observation enrichment#Placeholders substitution|Placeholders]])
| + | |
− | ***Load plugin nodes modules required by configuration
| + | |
− | ***Creates an instance of plugin for each thing type instance using instance @id as identifier (See [[Activities#Thing types|Thing types]])
| + | |
− | ****JavaScript object is extended with the properties values from the thing instance (See [https://github.com/AMTechMX/M2MBridge/blob/master/plugins/SNMPDevice/SNMPDevice.js plugin example] )
| + | |
− | ****Properties and methods are injected: (See [https://github.com/AMTechMX/M2MBridge/blob/master/plugins.js for details])
| + | |
− | *****common logger
| + | |
− | *****methods to send observations with and without enrichment
| + | |
− | *****methods for restarting plugin
| + | |
− | ***Creates a centralized observation dispatcher with persistence to ensure:
| + | |
− | ****Observations delivery in the order that observations occurred.
| + | |
− | ***Placeholders (See [[Observation enrichment#Placeholders substitution|Placeholders]])
| + | |
− | ****-#{deviceId} m2mBox Id set at bridgeConfig.json configuration file bridgeId property, or a unique id create in absence or this value
| + | |
− | ****-#{typeId} Unique id of the thingType that produces the event
| + | |
− | ****-#{thingId} Unique id of the instances that produces the event
| + | |
− | ****-#{tenantId} Tenant id used to authenticate the m2mBridge, defined at bridgeConfig.json tenant property
| + | |
− | ****-#{userId} User id used to authenticate the m2mBridge, defined at bridgeConfig.json userId property
| + | |
− | | + | |
− | == 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 [[Activities#Thing types|Thing types]])
| + | |
− | *Create a thing type XXXDevice (See [[Activities#Thing types|Thing types]])
| + | |
− | *Create the observations type the thing XXXDevice produces or consumes, example XXXDeviceObserv1 (See [[Sensor's network#Observations and observation types|Observations and observation types]])
| + | |
− | *Associate the observation XXXDeviceObserv1 type to the XXXDevice
| + | |
− | *Implement a nodejs module with the following interface
| + | |
− | function XXXThing() {
| + | |
− | }
| + | |
− | XXXThing.prototype.start = function ( complete) {
| + | |
− | try {
| + | |
− | complete(null);
| + | |
− | } catch (e) {
| + | |
− | complete(e);
| + | |
− | }
| + | |
− | };
| + | |
− | XXXThing.prototype.stop = function (complete) {
| + | |
− | try {
| + | |
− | complete(null);
| + | |
− | } catch (e) {
| + | |
− | complete(e);
| + | |
− | }
| + | |
− | };
| + | |
− | XXXThing.prototype.command = function (observation, complete) {
| + | |
− | try {
| + | |
− | complete(null);
| + | |
− | } catch (e) {
| + | |
− | complete(e);
| + | |
− | }
| + | |
− | };
| + | |
− | module.exports.XXXThing = XXXThing;
| + | |
− | | + | |
− | == 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 (optional)
| + | |
− | *Install packages for m2mBridge core and plug-ins (https://docs.npmjs.com/cli/install:)
| + | |
− | *Execute npm install at:
| + | |
− | **M2MBridge directory
| + | |
− | **each plug-in directory
| + | |
− | | + | |
− | == Existing plugins (See [https://github.com/AMTechMX/M2MBridge/tree/master/plugins exiting plugins])==
| + | |
− | | + | |
− | === LLRPReader ===
| + | |
− | Bridge EPC Low Level reader protocol to IoT DAP (See [https://github.com/AMTechMX/M2MBridge/tree/master/plugins/LLRPReader LLRPReader]) and /amtech/linkeddata/types/composite/entity/LLRPReader
| + | |
− | *Edge Intelligence
| + | |
− | **Implementing smoothing for new and lost tag
| + | |
− | **EPC decoding
| + | |
− | **Groups tags read by antennas groups
| + | |
− | **Groups tags by EPC decoding.
| + | |
− | *Placeholders (See [[Observation enrichment#Placeholders substitution|Placeholders]])
| + | |
− | **-#{antennaId} Llrp protocol antenna Id set at antennas supported property
| + | |
− | **-#{smoothingResult} if smoothing has been set to true LLRP reader observations can be sent to a topic depending of the smoothing process result [new|lost]
| + | |
− | **-#{llrpReaderProximity} Set the llrp reader proximity area supported property value to targetThing proximity value field
| + | |
− | **-#{antennaProximity} Set the llrp antenna proximity area supported property value to targetThing proximity value field
| + | |
− | **-#{tagEncoding} EPC encoding name
| + | |
− | **A component of decoded epc tag; helpful to organize epc observations; for example company-prefix to inform companies about products arrival or set access control.
| + | |
− | ***-#{epcUri|companyPrefix|itemReference|serialNumber|serialReference|locationReference|extension|assetType|individualAssetReference|serviceReference|documentType|managerNumber|objectClass|cAGEOrDODAAC}
| + | |
− | *Produced observations (see /amtech/linkeddata/types/composite/observation)
| + | |
− | **/amtech/linkeddata/types/composite/observation/observationresourcecrud
| + | |
− | **/amtech/linkeddata/types/composite/observation/graiEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/graiEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/decode96EPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/sgtinEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/dodEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/giaiEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/ssccEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/gdtiEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/llrpError
| + | |
− | **/amtech/linkeddata/types/composite/observation/dataEPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/encoded96EPC
| + | |
− | **/amtech/linkeddata/types/composite/observation/gidEPC
| + | |
− | *Commands (see /amtech/linkeddata/types/composite/observation)
| + | |
− | **/amtech/linkeddata/types/composite/observation/gpoWriteDataEPC
| + | |
− | | + | |
− | === BLEbeaconsScanner ===
| + | |
− | Bridge bluetooth low energy apple's ibecon and google's eddystone protocols to IoT DAP (See [https://github.com/AMTechMX/M2MBridge/tree/master/plugins/BLEbeaconsScanner BLEbeaconsScanner]) and /amtech/linkeddata/types/composite/entity/BLEbeaconsScanner
| + | |
− | *Edge Intelligence
| + | |
− | **Implementing smoothing for new, broadcast and lost tag
| + | |
− | *Placeholders (See [[Observation enrichment#Placeholders substitution|Placeholders]])
| + | |
− | **-#{smoothingResult} if smoothing has been set to true EddystoneScan observations can be sent to a topic depending of the smoothing process result [new|lost|broadcast]
| + | |
− | **-#{eddystoneType} Eddystone frame types, permissible values are uid, url and tlm
| + | |
− | ***uid broadcasts an opaque, unique 16-byte Beacon ID composed of a 10-byte namespace and a 6-byte instance.
| + | |
− | ***url broadcasts a URL using a compressed encoding format in order to fit more within the limited advertisement packet.
| + | |
− | ***tlm telemetrics
| + | |
− | **-#{eddystoneNamespace} 10-byte ID Namespace
| + | |
− | **-#{eddystoneInstance} 6-byte ID Instance
| + | |
− | **-#{proximityarea} Set the EddystoneHub proximity area supported property value to targetThing proximity value field
| + | |
− | **-#{bleProtocol} [eddystone|ibeacon]
| + | |
− | **-#{ibeaconUuid'} iBeacon advertised uuid
| + | |
− | **-#{'ibeaconMajor'} iBeacon advertised major
| + | |
− | **-#{'ibeaconMinor'} iBeacon advertised minor
| + | |
− | **-#{'ibeaconProximity} current proximity from sacanner [unknown|immediate|near|far]
| + | |
− | *Produced observations (see /amtech/linkeddata/types/composite/observation)
| + | |
− | **/amtech/linkeddata/types/composite/observation/observationresourcecrud
| + | |
− | **/amtech/linkeddata/types/composite/observation/ibeaconScan
| + | |
− | **/amtech/linkeddata/types/composite/observation/eddystoneBrodcast
| + | |
− | **/amtech/linkeddata/types/composite/observation/eddystoneScan
| + | |
− | **/amtech/linkeddata/types/composite/observation/eddystoneScan
| + | |
− | | + | |
− | === SNMPDevice ===
| + | |
− | Bridge simple network management protocol to IoT DAP (See [https://github.com/AMTechMX/M2MBridge/tree/master/plugins/SNMPDevice SNMPDevice]) and /amtech/linkeddata/types/composite/entity/SNMPDevice
| + | |
− | *Edge Intelligence
| + | |
− | **Groups multiple snmp reads and writes in a single call
| + | |
− | **Maps snmp oid into human readable names
| + | |
− | *Produced observations (see /amtech/linkeddata/types/composite/observation)
| + | |
− | **/amtech/linkeddata/types/composite/observation/observationresourcecrud
| + | |
− | **/amtech/linkeddata/types/composite/observation/snmpError
| + | |
− | **/amtech/linkeddata/types/composite/observation/snmpTrap
| + | |
− | *Commands (see /amtech/linkeddata/types/composite/observation)
| + | |
− | **/amtech/linkeddata/types/composite/observation/snmpSet
| + | |
− | | + | |
− | == HelloWorld plugin ==
| + | |
− | === Create thing type HelloWorld ===
| + | |
− | *add supported property type string hwgreetingLabel (See [[Activities#Thing types|Thing types]])
| + | |
− | === Create observation type obsrvHelloWorld ===
| + | |
− | *add supported property type string hwgreetingLabel (See [[Sensor's network#Observations and observation types|Observations and observation types]])
| + | |
− | === Define observation types produce or consume by the Thing ===
| + | |
− | *add obsrvHelloWorldobservation to Observation Production configuration list
| + | |
− | *add observationresourcecrud to Observation Production configuration list
| + | |