Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
175 lines (110 sloc) 9.02 KB

Groovy Script Examples for M2X

AT&T M2X is a cloud-based fully managed time-series data storage service for network connected machine-to-machine (M2M) devices and the Internet of Things (IoT). The AT&T M2X API provides all the needed operations and methods to connect your devices to AT&T's M2X service.

This repository provides an easy to use set of Groovy script examples that enable you to use Groovy script with the M2X Java client library.

In order to learn more about the APIs used in the Groovy Script examples, please consult the M2X Java client documentation. Refer to the M2X Glossary of Terms to understand the nomenclature used throughout this documentation.

Getting Started

  1. Signup for an M2X Account.
  2. Obtain your Master Key from the Master Keys tab of your Account Settings screen.
  3. Create your first Device and copy its Device ID.
  4. Review the M2X API Documentation.
  5. Review the M2X Java client documentation.

Setting up your first M2X Device

In order to be able to use these Groovy script examples, you will need an AT&T M2X API key and a Device ID. If you don't have an API key, create an account and, once registered and with your account activated, create a new Device, and set aside the Device ID and API Key values for later use.

Leveraging the M2X Java library

Because Groovy scripts can call Java code freely, these Groovy script examples rely on the M2X Java client library. As a result, this repository only contains Groovy examples that connect to M2X using the Java client library.

For more detail on using the M2X Java client library, please refer to its README file.

Requirements and Dependencies

There are five primary dependencies, which are explained in greater detail below:

  1. Install Groovy
  2. Install the Java Development Kit (JDK)
  3. Install Maven
  4. Download the M2X Java Client library
  5. Download the M2X example Groovy scripts

To run the example scripts, both Groovy and the JDK (Java Development Kit) must be installed on your system. Please refer to the documentation for Groovy and JDK for instructions. You should also download the M2X Java client library.

There are two ways to run the example scripts:

  1. The examples were developed with IntelliJ IDEA, a full-featured Java/Groovy IDE. If you also use IntelliJ IDEA, you can launch the scripts right in the IDE. The steps for running those scripts in IntelliJ IDEA are listed below.

  2. If you use another editor, you can run the examples in your command-line environment using the steps listed below.

In addition, Maven must be installed. Maven is a Java project and dependency management tool. While Groovy scripts can run outside of the Maven environment, the M2X Java client library is organized using Maven. We will use Maven to fetch dependencies for the Groovy scripts. To install Maven, please refer to the official Maven documentation.

Configure Java SDK and Groovy SDK in IntelliJ IDEA

If this is the first time that you have used IntelliJ IDEA, you will need to configure IntelliJ IDEA to use the Java SDK and/or Groovy SDK installed on your system.

Note that this is only required if you want to develop Groovy using IntelliJ IDEA. Running Groovy scripts using the command-line does not require following these steps.

First, you need to setup the Java SDK.

  1. Click File, then select Project Structure.

  2. Click on the + sign, and select JDK as shown in the screenshot below:

![Add Java SDK] (screenshots/1-add-java-sdk.png)

  1. Navigate to the folder where JDK is installed on your system. Depending on your Operating System this step might be slightly different. For example, on Mac OS X 10.9, the system-provided JDK can be found at /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home.

  2. Click Apply or OK to save the changes.

Then, you need to setup the Groovy SDK.

  1. Right click on the project name, select Add Framework Support... as shown in the next screenshot:

![Add Framework Support] (screenshots/2-add-framework-support.png)

NOTE: If you can't find this item in the menu, then it is likely that you already setup the Groovy framework.

  1. In the dialog menu that pops up, first click the checkbox next to Groovy on the left, then select the Groovy library in the dropdown menu. If nothing is shown in the dropdown menu, you may want to add one first: click the Create button and navigate to the libexec folder in your Groovy installation path. On Mac OS X 10.9, you may refer to the following screenshot:

![Navigate Groovy] (screenshots/3-navigate-groovy.png)

  1. Click OK on all the dialogs to save changes.

Now that you've setup the Java SDK and Groovy SDK, you are ready to run the examples!

How to Run Examples in IntelliJ IDEA

A. Clone the m2x-java library:

   $ git clone https://github.com/attm2x/m2x-java

B. Build the Java library and install it to the local Maven repository:

   $ cd m2x-java
   $ mvn package install

C. Clone the m2x-groovy examples:

   $ git clone https://github.com/attm2x/m2x-groovy

D. Launch IntelliJ, open the m2x-groovy project.

E. Right click on pom.xml file, select Maven, Reimport.

F. Open the Groovy script file you want to run as shown in the next screenshot:

![Navigate Source] (screenshots/navigate-source.png)

Replace the following variables with values from your M2X account (API Key + Device ID) or based on the data you want to store (stream name + value):

  • <key>: Your M2X API key
  • <device id>: ID of device to push
  • <stream name>: Name of stream to push
  • <value to push>: Value to push

G. Right-click it and select Run.

If you run into problems, please make sure to double check that you are using the correct correct key and Device ID as outlined in Step F above.

How to Run Examples in the Command Line

A. Clone the m2x-java library:

   $ git clone https://github.com/attm2x/m2x-java

B. Build the Java client library as one jar file without external dependencies:

   $ cd m2x-java
   $ mvn package -P one-jar

C. There will be a file named something similar to m2x-java-client-0.2-SNAPSHOT-one-jar.jar (notice the one-jar suffix of the filename) in the target folder under the current path. Record the full path to this jar file aside for future use.

D. Clone the m2x-groovy examples:

   $ git clone https://github.com/attm2x/m2x-groovy

E. Open the Groovy script file that you want to run. The source files can be located in the src/main/groovy/com/att/m2x/client/examples folder (in order to satisfy Java packet requirements).

Replace the following variables with correct values from your M2X account (in the case of Key and Device ID) and the data you want to store (stream name + value):

  • <key>: Your M2X API key
  • <device id>: ID of device to push
  • <stream name>: Name of stream to push
  • <value to push>: Value to push

F. Use the following command to launch the Groovy script (suppose the script you want to run is push_data.groovy):

   $ cd m2x-groovy
   $ groovy -cp <path to the generated jar file> src/main/groovy/com/att/m2x/client/examples/push_data.groovy

Remember to fill in the jar file path obtained in Step C and ensure that you adjusted the script to fill in the correct Key and Device ID as outlined in Step E above.

License

These examples are provided under the MIT license. See LICENSE for applicable terms.