Difference between revisions of "Datonis:Using the Datonis Java SDK"
m (Tag: Visual edit) |
m (Tag: Visual edit) |
||
| Line 15: | Line 15: | ||
=== Modifying the agent configuration file === | === 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 [http://www.json.org/ JSON] syntax. It is always a good idea to use a tool like [http://jsonlint.com/ JSONLint]. If the JSON syntax of this file is not valid, the Agent will throw parse errors. | 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 [http://www.json.org/ JSON] syntax. It is always a good idea to use a tool like [http://jsonlint.com/ JSONLint]. If the JSON syntax of this file is not valid, the Agent will throw parse errors. | ||
| + | {| class="wikitable" | ||
| + | !aliot.properties | ||
| + | |- | ||
| + | |{ | ||
| + | |||
| + | "access_key": "<Your access key here>", | ||
| + | |||
| + | "secret_key": "<Your secret key here>", | ||
| + | |||
| + | "bulk_transmit": false, | ||
| + | |||
| + | "protocol": "mqtts" | ||
| + | |||
| + | } | ||
| + | |} | ||
'''aliot.properties''' | '''aliot.properties''' | ||
Revision as of 09:10, 1 July 2017
Contents
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" } |
aliot.properties
{
|
- 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
|
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
|
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.
| options | description | Data type | Default value | Mandatory |
|---|---|---|---|---|
| access_key | Access key associated with a key pair. | String | None | Yes |
| secret_key | Secret key associated with the key pair. | String | None | Yes |
| protocol | Sets the protocol used to transmit data. This should be set to MQTTS. MQTT is a highly efficient bi-directional protocol suitable for IoT. MQTTS is MQTT over SSL. MQTTS is also bi-directional. The agent will use the 8883 port to communicate so please ensure that it is open.
You can also use HTTPS if you cannot use MQTTS. Valid values are HTTP/HTTPS/MQTT/MQTTS |
String | HTTPS | Yes |
| bulk_transmit | If set to true, the agent will keep collecting metrics and transmits them in bulk at the interval specified by the bulk_transmit_interval parameter. Metrics are batched up in batch sizes specified by the bulk_max_elements parameter. This is extremely useful in low bandwidth scenarios and is also very efficient if you have a lot of metrics to transmit. The agent will transmit metrics immediately if this is set to false. | Boolean | true | Yes |
bulk_transmit_interval |
The interval at which the metrics should be transmitted. Unit is in milliseconds. For instance, setting this value to 60000 means that the agent will transmit the collected metrics every 60 seconds. | Integer | 120000 | No |
bulk_max_elements |
How many events to batch before finally sending the batch. For instance, setting the value to 25 means that the agent will send metrics in batches of 25. | Integer | 25 | No |
proxy_host |
If your internet connection is through a proxy, you will need to set the proxy details by providing values for the proxy host. | String | No | No |
proxy_port |
The proxy server port | Integer | No | No |
proxy_username |
The proxy server username | String | No | No |
proxy_password |
The proxy server password | String | No | No |
request_timeout |
Timeout while connecting/receiving response from the platform. Usually defaults work very well but you can increase the value if you have a slow connection and need a larger request timeout. The value is in milliseconds. | Integer | 10000 | No |
thread_pool_size |
The agent uses a pool of transmitting threads. This is useful to achieve parallelism when you are transmitting a lot of data. Usually the default works well for most scenarios but you can increase the value if you are transmitting a lot of data. | Integer | 5 | No |
heartbeat_interval |
The agent transmits heartbeats at a periodic interval to indicate that the agent is alive. This way the Datonis platform knows that the agent is connected and functioning properly. The default value is a heartbeat every 60 seconds. You can override it if you wish. The value in in milliseconds. | Integer | 60000 | No |
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
Main Collapse source
// First make sure you create an aliot.properties file using your access and secret keys.
|
