Cloud configuration for M2MBridge

In order to set up a new bridge or network of bridges, a configuration needs to be done in the cloud (PaaS and SaaS experiences). This process involves several steps that will be broken down in the following sections. We will assume you have the following situation to illustrate each step and follow a guiding thread that can actually be a real use case:

• You will have several bridges in a Bridge Network (communicating using the standard protocol over a XBee Network) that will cooperate between them to determine the movement of people inside a given space. You will use a network of bridges because only one of the bridges will have network connectivity and the others will be located in spots where no network connection is available. To detect these people, we will assume that you have provided each one of them with an beacon that contains personal information. To be more specific about the situation we will assume that you will be located inside a mine and each person is a miner.

• You will create one or more reasoners that will allow you to represent each detected person and update their positions as they move around the mine. The location of the bridges will be used as an approximation (proximity-based location) of the person's location.

Conception of required things inside the AMTech platform

To represent all this scenario you will have several actors implied:

• Bridge instances (instances of amtechM2mBridge core type) to represent each bridge that is deployed.
• BLE detectors (instances of BLEbeaconsScanner core type) to represent the configuration of each BLE detector inside the bridge network.
• A new type to represent a miner. You will be able to add customized properties to this miner in addition to the core properties that it already inherit from a generic thing inside AMTech platform.
• One or more topics to store the messages generated by the bridge.
• Reasoners for the tracking of miners (update of locations)

Creator tasks

All the actions in this section will be performed by a creator. As such, you will go to The AMTech Platform and login as a creator.

Create thing types for representation

You will start by creating a miner type inside the PaaS. A miner will be a thing that has an ID (provided by the beacon) and a location. You will be able to add other custom properties later but so far, we will be reusing the "name" and "location" properties that all things already inherit.

• You go to Activities => Thing Types and you click on the plus (+) button to create a new thing type.
• You name it as you want (we will use DemoMiner for the example) and click on the "check" icon.
• Here you can customize some general options like description, icon, etc and then go to "Properties" and configure additional properties. For the example you will only add a description and accept all the other settings with default values by clicking on the "save" icon.

Set up an actor (necessarily inside an activity)

Now, you will be setting up an actor to represent the permissions that you will give to the followers of this activity. This actor will allow the execution of a bridge with the previously mentioned components and give access to the just created DemoMiner.

Create an activity

We will start by going to the Activities menu and clicking the "plus" icon to create a new activity. We will give it a name 'MineActivity' and start making some changes:

• Set a description for the activity
• Save changes

Add actor and permissions

Inside the activity you will go to "Actors" and click on the "plus" icon to add a new actor:

• You give it the name "MineThingsAccess"
• Navigate to "Policies" setting
• Add a new policy:
  • Select the "box" icon that represents a thing type and add the thing type DemoMiner
  • Click on the "check" icon to accept the policy
  • Be sure that the allowed operations property contains at least the "GET" operation. It allows visibility to things of type DemoMiner. The other operations ("POST", "PUT" and "DELETE") will be added as well in this case to allow creation, modification and deletion respectively.
  • Accept the changes by saving if any was done.
• Go back to the policies list and repeat the steps for adding a new policy for amtechM2mBridge and BLEbeaconsScanner thing types. If at the time of adding the type, you don't see it listed, it is because you need to uncheck the lock that only shows you the types owned by you.

Now it's time for publishing the activity

Publish the activity

• Go back to the activity main configuration page and hit the button for publishing (the one with a vertical arrow inside a cloud)
• The new page allows you to configure the service that will be published to the followers. Go to the Guest Tenants setting and be sure to add the follower tenants who you want to share this service with. One of these follower tenants will be used later to subscribe to the activity and start the bridge. Let's named it minefollower.
• Publish the activity by hitting the button of publish at the top.
• A warning may appear saying that the DemoMiner thing type is not shared with the service guest tenants. Accept the share and continue with the publishing action. If you want to get a fine-grained control over what's happening, you can also "Cancel" and get back to the DemoMiner thing type definition and add/remove guest tenants based on your own policies.

Configure templates

Now, that the policies are established, it's time to configure the templates for the bridge and its plugins.

Create bridge template(s)

Go to Things menu and find the amtechM2mBridge type. If it not appears just uncheck the lock of visibility. Follow this steps:

• Click on the add button
• Create a name for the bridge template. We will use "MineDemoBridge"
• Set a description for the bridge and hit the "save" button.
• Navigate to Bridge Error Observation configuration settings
  • Configure a producer. We will use #{bridgeId} which is a placeholder that gets replaced by the bridge ID.
  • Configure the topic. Use a topic that you own or create a new one if needed by going to the Sensors/Topics menu. We will use minedemobridge/errors but you will need to ensure that minedemobridge is an existing topic.
• Now you can get back to the bridge and configure other settings like the Bridge Started Observation or the Bridge Stopped Observation but we will not use them in this example. Now we will have to create the plugin templates and later we will return to the bridge configuration to add those instances as bridge instances and configure the observation production of those components.

Create plugin templates

Now it's time for creating the plugin template for the BLEbeaconsScanner.

• Navitate to the things menu again and find the BLEbeaconsScanner collection:
• Hit the "add" button to create a new instance
• Select a name for the instance like "MineDemoBeaconScanner"
• Add a description and check the sendSmoothingNew option to make the plugin react when a new beacon is discovered. We will let all the other settings with the default values for now.

Add plugin templates to bridge(s) as bridge instances

• Go back to the bridge instance MineDemoBridge that you just created
• Go to the bridge instances collection and add the MineDemoBeaconScanner
• Save the bridge

Configure observation production configuration

Now it's time for adding a configuration for observations of type

• Go to MineDemoBridge observation production configuration
• Add a new configuration
  • Click on the thing type selection (box icon) and select BLEbeaconsScanner
  • Hit the "check" icon
  • Go to the observations produced collection and add a new item:
    • Select eddystoneScan (we will assume here that we have eddystone beacons for the example)
    • Hit the "check" icon
    • Configure the Producer as #{thingId} that will be replaced for the ID of the BLEbeaconsScanner thing.
    • Configure the topic (and we will use the same topic we used before as base topic) as minedemobridge/eddystonescans

Share bridge with follower tenant

Now it's time to share this bridge with the follower tenant that will use it:

• Go to the bridge configuration
• In the guest tenants collection write the name of the follower tenant minefollower.
• Hit the "add to collection" button.
• Repeat the addition for any other follower who you want to share this bridge with.
• Click on the save button to save the bridge.

Follower admin tasks

Now it's time to allow a follower to subscribe to the service that we created and allow access to some guests. The M2MBridge raspberry PI will use one of them.

Make a login into the follower admin experience for the minefollower tenant.

Subscribe to activity as follower admin (SaaS admin)

• Go to menu Activities => Services.
• Find the activity whose name is serviceMineActivity and subscribe to it by hitting the "add to cart" icon

Add invited follower to your team and grant actor's permissions

• Go to the "Invite" option in the main menu
• Add the email address of all the users that you want to invite to your follower. We will need at least one for bridges that we're going to configure later. I will use demomine@example.com
• Add the actors that you want to give this user. The actor that you created in a previous step should be on this list and you should check it.
• Click on the "add user" icon.

Now the invitation has been sent

Invited follower tasks

Join the team and configure the bridge

Now it's time for the invited follower to join the team. An e-mail was sent to demomine@example.com with an invitation to join the team of the minefollower tenant. The user that received the e-mail should accept the invitation and create a new user inside the AMTECH Platform and joining the tenant's team or just joining the team if he is already registered.

Then he can use this credentials and the name of the bridge template that was created before to configure a new M2MBridge Raspberry Pi as it's also explained in this wiki.

Do something with the observation production of this bridge

Once configured and running this follower tenant will start to get observations in the configured topics each time a miner holding a beacon approaches a bridge. And now that we're getting these observations it's time to do what we planned to do since the beginning. Create a new miner or update its location.

In order to reach this goal we will have to "observe" all the eddystoneScan observations that arrive to the topic minedemobridge/eddystonescans and use them to create a DemoMiner instance or update its position if it already exists. So, let's start by creating an observer:

Create an observer

• Let's get back to the creator's interface (PaaS configurator) and open the activity DemoMineActivity
• Navigate to the Observers collection
• Add a new observer:
  • Write the name "ObserveAllEddystoneScans" and click the "check" icon
  • Include an observation filter for the observation type eddystoneScan
  • As we're not applying any filter, let's just save the observer

Create a reasoner

Go back to the activity DemoMineActivity, navigate to the Reasoner's collection and add a new reasoner:

• For the execution condition select "once analyzing only observations".
• Write the name "CreateOrUpdateMinerLocation" and click the "check" icon.
• Click on the binoculars icon to select an observer and find the observer that you just created in the previous step.
• Go to the topic selection icon and select the same topic that we used for the delivery of eddystoneScan observations in the bridge's observation production configuration (minedemobridge/eddystonescans). If at this point you're unable to select that topic you can temporarily save the reasoner (ignoring possible warning of incompleteness) and create a simulation to test the reasoner and generate topics
• Go to actions and select a "Create thing" action:
  • Click the thing type selection icon and select DemoMiner
  • Set a name for the action like CreateOrUpdateMiner
  • Click on the plus sign icon to start configuring the action
• In the menu that appears on the right navigate to Actions/CreateOrUpdateMiner
• Make sure that the option "Update if exists" is set to true
• Go to "New thing fields"
  • Select Entity Name and select the bind option (second option) to bind it to the eddystoneInstance property
  • Now, select location in the menu and also make a bind to the Location property
• Click on the reasoner's save icon

Now it's time to run a test of the reasoner and confirm that everything is working as expected:

• You hit the execution button and select the simulation that you created here
• You check the execution results and verify that everything is OK.
• You verify that the actions effectively did what they were supposed to do:
  • For this step you should preferably open a new tab in your browser and you navigate to the list of things to verify that a DemoMiner, with the name and location that you set in your simulation, was successfully created.
  • You get back to the tab where the execution was run and you close the execution dialog and click on the "check" icon to mark the reasoner as OK and then you save again the reasoner to store the ready state.
• Finally you navigate back to the activity
• You publish it to make this reasoner available to the followers subscribing to the service generated by this activity.

Create a simulation to test the reasoner and generate topics

The creation of a simulation while designing activity reasoners is required for two main reasons. Firstly, you need to generate the topics that will be used for the reasoners. Secondly, you need to test those reasoners and give your confirmation that they work as desired to be able to have the activity ready for deployment. Consequently let's see how to create a simulation of an eddystoneScan observation that creates the topic minedemobridge/eddystonescans and at the same time works as a simulation for the reasoner that we designed:

• Go to Sensors/Simulator in the main menu and create a simulation for an eddystoneScan observation.
• Configure a producer. It doesn't matter at this point the value that you choose but it's required so you cannot leave it blank.
• Set the topic to minedemobridge/eddystonescans
• Set the smoothingResult property to the value "new"
• Configure the eddystoneInstance to a name that will be used as a name for the creation of the DemoMiner in our testing execution. We will use "MyDemoMiner".
• Configure the Location to a valid geospatial location geometry like:

{"wkt": "POINT(0 0)"} 

• Set any other required property or fix any value that doesn't meet the validation requirements
• Save and click the action icon for creating topics (the one that looks like a paper plane)