Child pages
  • IoT Reference
Skip to end of metadata
Go to start of metadata

Register on Apstrata for IoT

In order to register on apstrata for IoT, you will need to go to the apstrata IoT registration page, and submit your personal information. Then, you will need to follow the instructions in order to complete and confirm your registration. An apstrata application will be created for you automatically. In order to get the key and secret of this application, you will have to login to the website using the email and password that you used upon registration. 

The following is a snapshot of the apstrata IoT registration page:

The following is a snapshot of the applications view that you get after logging in:

In order to view the secret of an application, you will have to click on its associated "View Secret" link. 

By clicking on the "Developer Workbench" link, you will be redirected to the developer tool that allows you to invoke all of apstrata's APIs. It also contains an admin space that allows you to manage all your apstrata assets, such as data, users, groups, devices, push notifications, queries, and more.

Using the Developer Workbench

In order to use the developer workbench, you do not have to login to the website each time and invoke it from there. Instead, you can browse to the following link http://workbench.apstrata.com and you will be presented with a login form.

Click on the "Preferences" link in order to configure the endpoint which in fact should be "https://wot.apstrata.com/apsdb/rest". You will need to do this only once and save it for other times.

Then, you will have to enter your application key and secret in the login form and press the "Login" button. This would take you to the following page which allows you to manage your application:

 

Managing your devices

Once you login to the workbench, you can click on the "Devices" menu item under the "Manage App" section in order to create a new device, view a list of your devices, edit a particular device and get its token, and more. Documentation on the Devices API can be found here.

 

Editing a device:

 

Use wot.io as your IoT message bus for Kinoma Create devices

You can simply invoke the wot.io bus from within your Apstrata server-side scripts, using the WotIO class. This class handles saving/reusing Wot.io account configurations and push, read messages to and from wot.io. Instances of this class can be created by requiring the "iot/wotio" system script (module) from your own Apstrata scripts

Overview

Definitions

  • A sink is a destination on wot.io where you can push messages. Messages on the sink will be forwarded to sources bound to the sink. You can see it like a "send mail".
  • A source is a recipient that receives messages sent by sinks it is bound to. You can see it like a "mailbox" from where you can read messages.
  • A binding is a link made between a sink and a source. It allows messages pushed to the sink to be forwarded to the sources it is bound to.
  • If many sources are bound to the same sink, any message pushed to that sink is forwarded to all the linked sources.

Steps

From your Apstrata server-side scripts, you need to execute the following steps in order to push messages to and read messages from wot.io

  1. Create an instance of the Apstrata WotIO object, passing it the needed configuration (basically, your username and wot.io feed token) to connect to wot.io.
  2. (optional) Create the configuration of a sink and persist it into Apstrata to reuse it later (skip this step if you do not need to reuse the sink configuration)
  3. (optional) Create the configuration of a source and persist this configuration into Apstrata to reuse it later (skip this step if you do not need to reuse the source configuration)
  4. Create a binding between the sink and the source. You only need to do this once (doing it multiple times for the same sink/source does not have any side effect)
  5. Push a message to a sink (the sink needs to be bound to at least one source)
  6. Read a message from a source (the source needs to be bound to a sink)

Step 1. Create a WotIO instance

From within an Apstrata script:

Create a WotIO instance with a new configuration to persist for further reuse
var wotioModule = apsdb.require("iot/wotio");
var accountConfig = {
	"params": {
		"id": "myWotio" // The id of your account configuration document. Replace with an identifier that suits you better
		"token": "AZxFE45s-WBSx45" // Replace with your wot.io feed token
	}
}
// this creates an instance of WotIO and persists the account configuration
var wotio = new wotioModule.WotIO(apsdb, accountConfig, "MyStore");
// in the above, note that "MyStore" is the name of the Apstrata store where you are persisting the configuration.
// it is only needed if your have more than one Apstrata store.
Create an instance of WotIO asking to load an existing account configuration
var wotioModule = apsdb.require("iot/wotio");
var accountConfig = {
	"id": "myWotio"
}
// this creates an instance of WotIO and loads the "myWotio" configuration
var wotio = new wotioModule.WotIO(apsdb, accountConfig, "MyStore");
// in the above, note that "MyStore" is the name of the Apstrata store where you are persisting the configuration.
// it is only needed if your have more than one Apstrata store.
Create an instance of WotIO with a one-time configuration
var wotioModule = apsdb.require("iot/wotio");
var accountConfig = {
	"params": {		
		"token": "AZxFE45s-WBSx45", // Replace with your wot.io feed token
		"persist": false // this indicates to the WotIO instance that it should not persist this configuration
	}
}
// this creates an instance of WotIO but does not persist the account configuration
var wotio = new wotioModule.WotIO(apsdb, accountConfig);

Step 2. (optional) Create a sink

You can invoke the createSink() method on an instance of the WotIO class. This results in persisting the configuration of the sink in Apstrata. As a consequence, you will be able to push to that sink by only passing a message body and the sinkId to the push() method (see "push a message to a sink on wot.io")

try {
	var sinkDTO = {
 		"alias": "sink4", // the identifier of your sink configuration
    	"userId": "john_doe", // your user id on wot.io    	
    	"appId": "echo" // one of "echo", "bipio" or "apstrata"
 	};
 	wotio.createSink(sinkDTO);
}catch(exception) {
	// createSink throws an exception if the sink was already created
}

Note that currently, you can only create sinks for the following applications on wot.io: "echo", "bipio" and "apstrata".

  • Use "echo" to push/read messages among your applications
  • Use "bipio" if you need to push/read messages on a bipio channel
  • You should normally not use "apstrata" from within a server-side script

Step 3. (optional) Create a source

You can invoke the createSource() method on an instance of the WotIO class. This results in persisting the configuration of the source in Apstrata. As a consequence, you will be able to read from that source by only passing the sourceId to the read() method

try {
	sourceDTO = {
    	"alias": "source4", // the identifier of your source configuration
    	"userId": "john_doe", // your user id on wot.io
    	"deviceId": "dev001", // the device that will consume the messages published on the related sink
    	"appId": "echo" // one of "echo", "bipio" or "apstrata"
	};    
	wotio.createSource(sourceDTO);
}catch(exception) {
	// createSource throws an exception if the source was already created
}

Note that currently, you can only create sources for the following applications on wot.io: "echo", "bipio" and "apstrata".

  • Use "echo" to push/read messages among your applications
  • Use "bipio" if you need to push/read messages on a bipio channel
  • You should normally not use "apstrata" from within a server-side script

Step 4. Bind a sink to a source

From within an Apstata server-side script (in the below we assume that we already have created an instance of the WotIO class), you have two options:

  • First example below shows how to bind a sink to a source by providing their configuration (i.e. it they were not initially saved to Apstrata by invoking wotio.createSink/wotio.createSource) 
  • Second example shows how to to bind a sink to a source reusing their persisted configuration
Bind a sink to a source while providing the sink and source configuration
// Define the configuration of the sink
var sinkDTO = {        
	"userId": "john_doe", // your user id on wot.io
    "appId": "echo" // one of "echo", "bipio" or "apstrata"
};    
// Define the configuration of the source
var sourceDTO = {
	"userId": "john_doe", // your user id on wot.io
	"deviceId": "dev001",
	"appId": "echo" // one of "echo", "bipio" or "apstrata". Should be the same as the sink you are binding to
};
var result = wotio.bind(sinkDTO, sourceDTO);
Bind a sink to a source by reusing their persisted configuration
var result = wotio.bind(sink4, source4); // sink4 and source4 are respectively persisted configurations of a sink and a source

Step 5. Push a message to a sink on Wot.io

From within an Apstata server-side script (in the below we assume that we already have created an instance of the WotIO class), you have two options:

  • First example below shows how to push to a sink by providing its configuration (i.e. it was not saved to Apstrata by invoking wotio.createSink) 
  • Second example shows how to push to a sink, reusing a persisted configuration
Push a message to a sink while providing the sink configuration
var messageDTO = {
	"sink": {
		"userId": "john_doe", // your user id on wot.io
		"deviceId": "dev001", // the device that will consume the messages published on the related sink
		"appId": "echo"
	},
	"body": {"msg": "You have a new msg"}
}
var result = wotio.push(messageDTO);
Push a message to a sink, reusing a persisted sink configuration
var messageDTO = {
	"body": {"msg": "You have a new msg"}
} 
// This asks the WotIO instance to reuse the persisted "sink4" sink configuration 
var result = wotio.push(messageDTO, "sink4");

Read a message from a source on Wot.io

From within an Apstrata server-side script (in the below we assume that we already have created an instance of the WotIO class), you have two options:

  • First example below shows how to read from a a source by providing its configuration (i.e. it was not saved to Apstrata by invoking wotio.createSource) 
  • Second example shows how to push from a source , reusing a persisted configuration
Read from a source while providing the source configuration
var sourceDTO = {
	"userId": "Jim", 
	"deviceId": "dev001",
	"appId": "echo"	
} 
var result = wotio.read(sourceDTO);
Read from a source, reusing a persisted source configuration
// This asks the WotIO instance to reuse the persisted rJimS5 source configuration 
var result = wotio.read("source4");

All methods of the WotIO class can throw exceptions. Exceptions have the following structure:

{

"errorCode": "some_error_code",

"errorDetail": "some_error_message

}

  • No labels