Difference between revisions of "Datonis:Using the Datonis Java SDK"

Revision as of 09:16, 1 July 2017

Installing the SDK

To get started with the Java SDK, you will first need to install the Apache Maven build tool. Please follow the installation instructions for your Operating System.

All our code samples are available in our GitHub repository. If you are familiar with Git, you can pull the repository to begin. If not, you can download the entire repository of code samples as a zip file by clicking on the clone or download link.

Extract the zip file in a folder. You now need to go into the java folders and execute the following Maven commands to install the Java SDK and all its dependent libraries.

mvn install:install-file -Dfile=lib/aliot-sdk-4.0.0.jar -DgroupId=io.datonis.sdk -DartifactId=aliot-sdk -Dversion=4.0.0 -Dpackaging=jar
mvn clean install

We recommend using the Eclipse IDE to program the SDK. The following command generates the necessary project and dependency files required for Eclipse.

mvn eclipse:eclipse

This command generates the necessary .project and .classpath files that Eclipse needs. You can now import this project into Eclipse by clicking on File → Import and selecting General → Existing Projects into Workspace. You will see a new project called Aliot SDK example added to your workspace.

Running the Agent for the first time

Modifying the agent configuration file

The SampleAgent.java file contains a reference implementation of a Java based Agent that pushes data to Datonis. To run this agent, you will need to edit the aliot.properties file. Your aliot.properties file should look like this. This file follows the JSON syntax. It is always a good idea to use a tool like JSONLint.  If the JSON syntax of this file is not valid, the Agent will throw parse errors.

aliot.properties

{
    "access_key": "<Your access key here>",
    "secret_key": "<Your secret key here>",
    "bulk_transmit": false,   
    "protocol": "mqtts"
}

• The access key and secret keys have been created by you earlier. Please refer to the documentation for this if you haven't. Copy the values for access_key and secret_key into the aliot.properties file. These keys are 40 character alphanumeric values. Please put the values in quotes. For example, "access_key": "ab12ab12ab12ab12ab12ab12ab12ab12"
• Additional configuration options in the file will be discussed in detail later. For now, you can keep the agent configuration file as specified above.

Setting the Thing keys in the agent

Now that your aliot configuration is done, you will need to configure the Thing for which the agent is transmitting data. You have already created a  LivingRoom Thing in Datonis earlier.  Look for the code snippet below and replace the "<Your Thing Key>" with the actual Thing key. This ensures that the Agent pushes data for your newly created Thing.

thing = new Thing("<Your Thing Key>", "LivingRoom", "The living room temperature and humidity device.");

Running the agent

You are now ready to run the agent for the first time. The agent needs to know where to find the aliot.properties and log4j.properties file. You will need to add JVM parameters for the same. In Eclipse, you will need to create a new Run Configuration for the SampleAgent. In the Arguments section, under VM Arguments, add the following settings

-Daliot.properties=src/main/resources/aliot.properties
-Dlog4j.properties=src/main/resources/log4j.properties

If you have used Log4J before, the log4j.properties file will be very familiar to you. The default setting is to log everything to the console and the aliot.log file. You can modify this based on your need.

Now run the agent. If everything has been set up properly, the agent will successfully connect and start transmitting data to Datonis. The you should see log messages indicating a successful agent transmit.

2017-04-06 12:25:55,448 INFO  [main] SampleAgent - Starting the Sample Aliot Agent
2017-04-06 12:25:55,457 INFO  [main] AliotGateway - Starting up the Aliot Gateway
2017-04-06 12:25:55,467 INFO  [main] AliotGateway - Agent will communicate using https
2017-04-06 12:25:55,907 INFO  [Handshake-Consumer] GatewayMessageConsumer - Handshake-Consumer is starting up
2017-04-06 12:25:55,907 INFO  [Alert-Consumer] GatewayMessageConsumer - Alert-Consumer is starting up
2017-04-06 12:25:55,907 INFO  [Data-Consumer] GatewayMessageConsumer - Data-Consumer is starting up
2017-04-06 12:25:55,908 INFO  [main] AliotGateway - Successfully started the Aliot Gateway
2017-04-06 12:25:55,908 INFO  [main] SampleAgent - Agent started Successfully, setting up bidirectional communication
2017-04-06 12:25:55,908 INFO  [Gateway-Monitor] GatewayMonitor - Gateway monitor starting up
2017-04-06 12:25:55,909 INFO  [Gateway-Monitor] GatewayMonitor - Sent heart beats for the Things
2017-04-06 12:25:55,909 INFO  [main] SampleAgent - Bidirectional communication is setup with Datonis
2017-04-06 12:25:55,910 INFO  [main] SampleAgent - Transmitting Demo Data
2017-04-06 12:25:57,975 INFO  [Handshake-Consumer-pool-thread-1] GatewayMessageConsumer - Transmitted Message in 2061 ms : {"timestamp":1491461755909,"thing_key":"your_thing_key"}
2017-04-06 12:25:57,975 INFO  [Data-Consumer-pool-thread-1] GatewayMessageConsumer - Transmitted Message in 2061 ms : {"timestamp":1491461755910,"data":{"humidity":66,"temperature":20},"thing_key":"your_thing_key"}
2017-04-06 12:26:06,774 INFO  [Data-Consumer-pool-thread-2] GatewayMessageConsumer - Transmitted Message in 859 ms : {"timestamp":1491461765914,"data":{"humidity":85,"temperature":4},"thing_key":"your_thing_key"}

Please ensure that you have a working internet connection so that the agent can transmit. If you are sitting behind a proxy, the section below will show you how to configure the proxy settings.

If there are any issues, the agent will print an appropriate error on the console. For instance, here's an error that's printed if the Thing key is invalid.

2017-04-06 11:53:57,755 ERROR [Data-Consumer-pool-thread-1] RESTCommunicator - Error 300025 : Invalid sensor key or thing key.

You can now verify that the Datonis platform has indeed recognised this Thing and is accepting data by clicking on Home and looking at the System Summary dashboard.

Here the Dashboard is indicating that your Thing LivingRoom has connected and is transmitting data. Please note that you are transmitting two metrics, temperature and humidity. Therefore the counts for the metrics in the Live Data Feed will reflect the actual counts of metrics received.

Additional Agent Configurations

You have already configured the aliot.configurations file. Here are some additional configuration settings that you can use.

Agent Code Walkthrough

The SampleAgent code is well documented so going through that code should give you a fair idea of how to transmit data to Datonis. You should start by looking at the main function. It shows you how to initialise the agent, transmit a few data points and alerts, transmitting waypoints and handling control instructions from the Datonis platform

// First make sure you create an aliot.properties file using your access and secret keys.
// A sample file should be available with this package
// The keys are available in the Datonis platform portal
logger.info("Starting the Sample Aliot Agent");

// Create and Initialize the agent
SampleAgent agent = new SampleAgent();

// Start the Gateway
if (!agent.startGateway())
{
    logger.info("Could not start the agent. Exiting");
    return;
}
logger.info("Agent started Successfully, setting up bidirectional communication");

// Setup bidirectional communication - Needs to use MQTTS/MQTT mode for communication.
// Ensure that the 'protocol' property is set to 'mqtts' in the aliot.properties file
agent.setupBiDirectionalCommunication();

// Send a few sample simulated data events
logger.info("Transmitting Data");
agent.transmitData();

// Transmit a set of sample alerts.
logger.info("Transmitting Alerts");
agent.transmitAlerts();

// Transmit a waypoint
logger.info("Transmitting a waypoint");
agent.transmitWaypoint();
logger.info("Exiting");
agent.stopGateway();