|
|
(180 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 |
− | # [[Edge Configuration]] | + | # [[M2MBridge Functionality|Functionality]] |
| + | # [[Configuration example]] |
| + | # [[M2MBridge network]] |
| + | #: [[Aggregation]] |
| + | #: [[Edge reasoners]] |
| + | #: [[Mesh network]] |
| + | # [[Intelligence at the Edge]] |
| + | #: [[WhatIsAPlugin|What is a plugin?]] |
| + | #: [[EPC (Electronic product code)]] |
| + | #: [[Smoothing observations]] |
| + | # [[Observations production and consumption]] |
| # [[Cloud Configuration]] | | # [[Cloud Configuration]] |
| + | #: [[Observation production config]] |
| + | #: [[Validation]] |
| + | #: [[Sample configuration for beacons]] |
| + | # [[Automatic updates on bridge instance delete]] |
| # [[Implementation notes]] | | # [[Implementation notes]] |
| # [[How to implement a new plugin]] | | # [[How to implement a new plugin]] |
− | == How to install ==
| + | # [[Set up a new Raspberry PI]] |
− | *Clone git repository (https://github.com/AMTechMX/M2MBridge.git)
| + | # [[Edge Configuration|M2MBridge Edge Configuration]] |
− | *Install nodejs https://nodejs.org/en/download/package-manager/
| + | # [[M2MBridge updates]] |
− | *Install npm (http://blog.npmjs.org/post/85484771375/how-to-install-npm)
| + | # [[How to install & execute]] |
− | *Delete at /.../M2MBridge/plugins/xxx unneeded plug-ins (optional)
| + | # [[HelloWorld plugin]] |
− | *Install packages for m2mBridge core and plug-ins (https://docs.npmjs.com/cli/install:)
| + | # Supported plugins |
− | *Execute npm install at:
| + | ## [[File:wi-fi.svg|35px]] [[File:tcp-ip.svg|35px]] [https://en.wikipedia.org/wiki/Ethernet Wifi or RJ45 Ethernet] |
− | **M2MBridge directory
| + | ##: [[File:SNMPDevice.svg|35px]] [[SNMPDevice]] |
− | **each plug-in directory
| + | ##: [[File:LLRPReader.svg|35px]] [[LLRPReader]] |
− | | + | ##:: [[File:LLRPAntenna.svg|35px]] [[LLRPAntenna]] |
− | == HelloWorld plugin ==
| + | ##: [[File:thing-magic.svg|35px]] [[ThingMagicEPCReader]] |
− | === Create thing type HelloWorld ===
| + | ##:: [[File:LLRPAntenna.svg|35px]] [[LLRPAntenna]] |
− | *add supported property type string hwgreetingLabel (See [[Activities#Thing types|Thing types]])
| + | ##: [[File:plc-icon.svg|35px]] [[OPCUADevice]] |
− | **string without space validation regexp ^[^\s]+$
| + | ##: [[File:modbus.svg|45px]] [[ModbusDevice]] |
− | *add supported property type integer hwSayHelloFrequency
| + | ##: [[File:wioGeneric.png|45px]] [[Wio Devices]] (troubleshooting inside) |
− | | + | ##:: [[File:wioNode.svg.svg|35px]] [[wioNode]] |
− | === Create observation type obsrvHelloWorld ===
| + | ##:: [[File:wioLink.svg|35px]] [[wioLink]] |
− | *add supported property type string hwgreetingLabel (See [[Sensor's network#Observations and observation types|Observations and observation types]])
| + | ## [[File:bt.svg|35px]] [https://en.wikipedia.org/wiki/Bluetooth_Low_Energy BLE 4.0] |
− | *clone obsrvHelloWorld with name commandHelloWorld
| + | ##: [[File:BLEbeaconsScanner.svg|35px]] [[BLEbeaconsScanner]] |
− | | + | ##: [[File:bleOBDScanner.svg|35px]] [[BLEODB2Scanner]] |
− | === Define observation types produce or consume by the Thing ===
| + | ##: [[File:BLEPeripheralsScanner.svg|35px]] [[BLEPeripheralsScanner]] |
− | *add obsrvHelloWorldobservation to Observation Production configuration list (See [[Activities#Thing types|Thing types]])
| + | ##: [[File:BluvisioniBEEK.jpg|65px]] [[BLEBluvisionBeeksScanner]] |
− | *add commandHelloWorldobservation to Observation Production configuration list
| + | ##: [[File:BLEGattCentral.svg|35px]] [[BLEGattCentral]] |
− | *add observationresourcecrud to Observation Production configuration list
| + | ## [[File:i2c.svg|35px]] [https://en.wikipedia.org/wiki/I%C2%B2C I2C] |
− | | + | ##: [[File:watersensor.svg|35px]] [[PCA9536I2CWaterDetectionWithBuzzer]] |
− | === Implement plugin HelloWorld interface ===
| + | ##: [[File:TSL2561Light.svg|65px]] [[TSL2561I2CLight]] |
− | *create a directory with the thing type name HelloWorld at (See [https://github.com/AMTechMX/M2MBridge/tree/master/plugins plugin directory] )
| + | ##: [[File:soundvibration.svg|35px]] [[ADC121C021I2CSoundVibrationShock]] |
− | *at the directory HelloWorld create a javascript file HelloWorld.js
| + | ##: [[File:ncd-i2c.png|65px]] [https://store.ncd.io/shop/?fwp_interface=i2c-interface NCD I2C devices] |
− | *implement the interface (See [[M2MBridge# How to implement a new plugin| How to implement a new plugin]])
| + | ##: [[File:grove-log.png|65px]] [https://www.seeedstudio.com/category/Grove-c-1003%7C%7C24.html?p=0 Grove devices via I2C] |
− | <syntaxhighlight lang="javascript">
| + | ## [[File:usb-logo.svg|35px]] [https://en.wikipedia.org/wiki/USB USB 2.0] |
− | function HelloWorld() {
| + | ##: [[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] |
− | HelloWorld.prototype.start = function (complete) {
| + | <!--##:[[File:modbus.svg|45px]] [[ModbusDevice]]--> |
− | try {
| + | ## [[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] |
− | complete(null);
| + | ##: [[File:relay-home-automation.svg|35px]] [[NCDXbee900Relay]] |
− | } catch (e) {
| + | ##: [[File:energy-monitor.svg|35px]] [[NCDXbee900EnergyMonitor]] |
− | complete(e);
| + | ##: [[File:ncd-i2c.png|65px]] [https://store.ncd.io/shop/?fwp_interface=900hp-s3b NCD devices supporting XBee-Pro 900HP communication] |
− | }
| + | <!-- ## [[File:libelium.svg|45px]] [[waspmoteBLECentral]]--> |
− | };
| + | ##: [[File:libelium.svg|65px]] [http://www.libelium.com/libeliumworld/waspmote/ Libelium waspmote] |
− | | + | ##:: [[File:SmartEnvironment.jpg|65px]] [[Smart environment PRO]] |
− | HelloWorld.prototype.stop = function (complete) {
| + | ##:: [[File:SmartAgriculture.png|65px]] [[Smart Agriculture]] |
− | try {
| + | ##:: [[File:SmartWater.jpg|65px]] [[Smart Water]] |
− | complete(null);
| + | ##:: [[File:SmartWaterIons.png|65px]] [[Smart Water Ions]] |
− | } catch (e) {
| + | ##:: [[File:SmartCities.jpg|65px]] [[Smart Cities]] |
− | complete(e);
| + | ##:: [[File:SmartParking.jpg|65px]] [[Smart Parking]] |
− | }
| + | ##:: [[File:SmartSecurity.jpg|65px]] [[Smart Security]] |
− | };
| + | ##:: [[File:Radiation.png|65px]] [[Radiation]] |
− | | + | ##:: [[File:AmbientControl.png|65px]] [[Ambient Control]] |
− | HelloWorld.prototype.command = function (observation, complete) {
| + | |
− | try {
| + | |
− | complete(null);
| + | |
− | } catch (e) {
| + | |
− | complete(e);
| + | |
− | }
| + | |
− | };
| + | |
− | | + | |
− | module.exports.HelloWorld = HelloWorld;
| + | |
− | </syntaxhighlight>
| + | |
− | | + | |
− | === Functionality ===
| + | |
− | *send an observation obsrvHelloWorldobservation with the frequency set by the property hwSayHelloFrequency
| + | |
− | *change hwgreetingLabel value when receive command obsrvHelloWorld observation
| + | |
− | *implement placeholder #{greetingLabel}
| + | |
− | *start method
| + | |
− | **create an observation type obsrvHelloWorld at /amtech/things/observations (See [[Simulator|Simulator]])
| + | |
− | **copy observation instance jsonld
| + | |
− | <syntaxhighlight lang="javascript">
| + | |
− | var clone = require('clone');
| + | |
− | var util = require('util');
| + | |
− | | + | |
− | function HelloWorld() {
| + | |
− | }
| + | |
− | | + | |
− | HelloWorld.prototype.start = function (complete) {
| + | |
− | var self = this;
| + | |
− | try {
| + | |
− | self.sayHelloInterval = setInterval(function(){
| + | |
− | var obsrvHelloWorld = clone({
| + | |
− | "proximityarea": "",
| + | |
− | "topic": "",
| + | |
− | "guestusers": [],
| + | |
− | "targetthings": "[]",
| + | |
− | "location": "",
| + | |
− | "@type": "/amtech/linkeddata/types/composite/observation/obsrvHelloWorld",
| + | |
− | "hwgreetingLabel": "",
| + | |
− | "creationDate": "2016-04-20T03:24:54.099Z",
| + | |
− | "guesttenants": [],
| + | |
− | "description": "",
| + | |
− | "producer": ""
| + | |
− | });
| + | |
− | obsrvHelloWorld.hwgreetingLabel = self.hwgreetingLabel;
| + | |
− | var ph = {'greetingLabel': self.hwgreetingLabel};
| + | |
− | self.sendObservation(self,obsrvHelloWorld, ph );
| + | |
− | }, self.hwSayHelloFrequency);
| + | |
− | complete(null);
| + | |
− | } catch (e) {
| + | |
− | complete(e);
| + | |
− | }
| + | |
− | };
| + | |
− | | + | |
− | HelloWorld.prototype.stop = function (complete) {
| + | |
− | try {
| + | |
− | if (this.sayHelloInterval) {
| + | |
− | clearInterval(this.sayHelloInterval);
| + | |
− | }
| + | |
− | complete(null);
| + | |
− | } catch (e) {
| + | |
− | complete(e);
| + | |
− | }
| + | |
− | };
| + | |
− | | + | |
− | HelloWorld.prototype.command = function (observation, complete) {
| + | |
− | try {
| + | |
− | if(observation['@type'] === "/amtech/linkeddata/types/composite/observation/commandHelloWorld"){
| + | |
− | this.hwgreetingLabel = observation.hwgreetingLabel;
| + | |
− | complete(null);
| + | |
− | }else{
| + | |
− | complete(new Error(util.format("HelloWorld %s support commands of observations type commandHelloWorld", this._name)));
| + | |
− | }
| + | |
− | } catch (e) {
| + | |
− | complete(e);
| + | |
− | }
| + | |
− | };
| + | |
− | | + | |
− | module.exports.HelloWorld = HelloWorld;
| + | |
− | </syntaxhighlight>
| + | |
− | | + | |
− | === Configure amtechM2MBridge template ===
| + | |
− | *(See [[M2M Bridge#Cloud Configuration|Cloud Configuration]])
| + | |
− | *create activity helloWorld (See [[Activities|Activities]])
| + | |
− | *create helloWord notification (See [[Notifications|Notifications]])
| + | |
− | **add subject with placeholder #{label}
| + | |
− | **add subject with placeholder #{producer} and #{label}
| + | |
− | *create helloWorld actor with access polices (See [[Access control#Actors|Actors]])
| + | |
− | **amtechM2MBridge thing type
| + | |
− | **HelloWord thing type
| + | |
− | **helloWord notification
| + | |
− | **associate helloWorld actor with helloWorld activity
| + | |
− | *configure observation production (See [[Activities#Observation production configuration|Observation production configuration]])
| + | |
− | ** thing type HelloWorld
| + | |
− | ***observation type obsrvHelloWorld
| + | |
− | ****topic /helloWorld/#{greetingLabel}
| + | |
− | ****producer #{thingId}
| + | |
− | ****guestTeants add m2mcreator to shared the observation
| + | |
− | ***observation type observationresourcecrud
| + | |
− | ****topic /helloWorld/asynch
| + | |
− | ****producer #{thingId}
| + | |
− | ** thing type amtechM2mBridge
| + | |
− | ***observation type observationresourcecrud
| + | |
− | ****topic /helloWorld/asynch
| + | |
− | ****producer #{thingId}
| + | |
− | *create observation simulation for observation type obsrvHelloWorld (to be used in observers)
| + | |
− | *create helloWorld observer (See [[Observers|Observers]])
| + | |
− | **type observation obsrvHelloWorld
| + | |
− | **test observer
| + | |
− | *create helloWorld reazoner (See [[Reasoners|Reasoners]])
| + | |
− | **add action send notification type helloWorld
| + | |
− | **add action send command
| + | |
− | **test and validate reasoner
| + | |
− | *publishing activity (See [[Publishing|Publishing]])
| + | |
− | **validate activity
| + | |
− | **deploy activity
| + | |
− | *invite a user as helloWorld actor (See [[Access control#Actors|Invite user]])
| + | |
− | **user id smartsensor@amtech.mx
| + | |
− | *configure helloWorld m2mBridge template
| + | |
− | ** create amtechM2MBridge instance with name helloWorld (See [[IoT Semantics|Instances]])
| + | |
− | ***it will be the value of templateId at bridgeConfig.json (See [[M2M Bridge#Edge Configuration|Edge Configuration]])
| + | |
− | **create HelloWorld type instace with name helloWorld
| + | |
− | **associate HelloWorld instance to amtechM2MBridge instance
| + | |
− | **give guest access to helloWorld M2MBridge instance to tenant m2mfollower and user smartsensor@amtech.mx
| + | |
− | *add new action send Command to reasoner helloWorld
| + | |
− | **thing type HelloWorld
| + | |
− | **observation type commandHelloWorld
| + | |
− | **set topic to /helloWorld/asynch
| + | |
− | **set target uri to observation producer (See [[Sensor's network#Observations and observation types|targetthings]])
| + | |
− | **set hwgreetingLabel holaFromCommand
| + | |
− | | + | |
− | === bridgeConfig.json ===
| + | |
− | *(See [[M2M Bridge#Edge Configuration|Edge Configuration]])
| + | |
− | <syntaxhighlight lang="jsonld">
| + | |
− | {
| + | |
− | "description": "AMTech M2M Bridge Helloworld demo",
| + | |
− | "description:children" : true,
| + | |
− | "dap":{
| + | |
− | "dapUrl": "https://dapdev.amtech.mx",
| + | |
− | "userId": "smartsensor@amtech.mx",
| + | |
− | "tenant" : "m2mfollower",
| + | |
− | "password" :"xxxxxxxx"
| + | |
− | },
| + | |
− | "templateId":"helloWorld",
| + | |
− | "bridgeIdPrefix":"helloWorldDemo",
| + | |
− | "location:children" : true,
| + | |
− | "address" :{
| + | |
− | "country" : "USA",
| + | |
− | "city": "New York City",
| + | |
− | "road" : "97th street transverse"
| + | |
− | }
| + | |
− | }
| + | |
− | </syntaxhighlight>
| + | |
− | | + | |
− | === Debug a plugin ===
| + | |
− | *node-inspector &
| + | |
− | **[https://greenido.wordpress.com/2013/08/27/debug-nodejs-like-a-pro/ Debug NodeJS Like A Pro]
| + | |
− | **[https://mattdesl.svbtle.com/debugging-nodejs-in-chrome-devtools Debugging Node.js in Chrome DevTools]
| + | |
− | *visit http://127.0.0.1:8080/?ws=127.0.0.1:8080&port=5858
| + | |
− | | + | |
− | == Example 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
| + | |