Software AG | Java reference agent

Overview

The Java agent provides a reference implementation for all device management features of Device Integration Platform plus drivers for various device kits. There are multiple ways of using the agent:

Use it as it is for managing your Java-enabled devices.
Use it as a base for your own implementation by adding drivers for additional hardware.
Use it as a reference for implementing device management features in other environments.

The Java agent supports Windows and Unix-based systems and contains the following functionality:

Discovery and hardware identification: Automatically registers a device, its supported functionality and its connected sensors and controls.
Availability management: Determine if a device connects as expected and notify the user if not.
Software management: Upgrade the software on the device and restart with the new software.
Modem support: Provides basic modem information and signal statistics (IMEI, ICCID, cell ID, signal strength, BER; depending on modem type).
Extensibility through driver concept.
Ready-made drivers for Raspberry Pi, PiFace Digital and Tinkerforge.

Prerequisites

An installation of Java SE 7 is required. To verify the availability of Java on your system, type

$ java -version
java version "1.7.0_45"

To install Java, please visit http://java.com.

Installing

Binary packages are available for the Raspberry Pi, the Kontron M2MSSDK, Mac OS X, Linux and Windows.

On a Linux OS (including Embedded Linux distributions such as Kontron Linux), please download the latest Linux Agent Archive.
For the Raspberry Pi and similar Embedded Linux devices, please check the Raspberry Pi guide.
On a Mac OS X, please download the latest Mac Agent Archive.
On a Windows OS, please download the latest Windows Agent Archive.

Unpack your respective package in a new folder. After unpacking, use the script "c8y-agent" to run the agent. If you need more debug information, run the script "c8y-agent-debug" or change the file cfg/logback.xml to use a more fine granular logging.

Configuration

All the configuration files are located in the cfg/ folder.

The .porperties file has the following example structure:
```
 host=<host>
 bootstrap.tenant = <bootstrap tenant>
 bootstrap.user = <bootstrap  username>
 bootstrap.password = <bootstrap password>
```
- The host is the http/https address of your Device Integration Platform instance.
- The bootstrap.* properties define the bootstrap user for your instance. Their default value is the default Device Integration Platform bootstrap user.
  
  If your tenant is <tenant>.customer.com you don't need to change anything here.

The device.properties file contains the credentials the device uses to connect to your tenant. They are automatically filled in once you register the device in Device Integration Platform. If you would like to move your device to a different tenant you have to delete the content of this file.
The config.properties persists the device specific configuration that can be set in the Device Integration Platform front-end. Here is an example configuration of a device that has one ThinkerForge temperature senesor connected to it:
```
 #Tue Apr 28 16:03:53 UTC 2015
 c8y_temperature.interval=5000
 c8y.log.eventLevel=INFO
 c8y.log.alarmLevel=ERROR
```
- The c8y_temperature.interval property defines the reporting rate of the TinkerForge temperature sensor. It is measured in milliseconds.
- The c8y.log. properties defines the severity of log entries to be reported by the device as events and alarms respectively. The possible values are TRACE, DEBUG, INFO, WARN and ERROR*
  
  This file is automatically created by the device.
The logback.xml and logback-debug.xml files define the logging for running the agent normally and in debug mode respectively.

On the Raspberry Pi the agent is implemented as a service. The configuration files are located in /usr/share/cumulocity-rpi-agent/cfg/.

Running

Registering the device

When the agent is successfully started, open Device Integration Platform in a web browser and go to the "Registration" page. Enter the device ID of the device that the agent is running on. The device ID depends on the type of device.

On a Raspberry Pi, it's the serial number of the Raspberry Pi (see the instructions).
On a Mac, it's the serial number of the Mac. Click on the Apple logo in the menu, "About This Mac", "More Info" to display the serial number.
On Windows, it's the serial number of your PC. To get it, run "wmic csproduct get identifyingnumber" from a command prompt.
On other Linux devices or as a fallback, the MAC address of the first network interface is used. Use "ifconfig" to print the network interfaces and check for the "HWaddr" entry. Keep in mind only the numbers are used, without any colons! Often, the MAC address is also printed on the board.

Monitoring the connection

By default, the agent is "always on", i.e., it maintains a connection to Device Integration Platform to receive operations in real-time. Hence, the agent is shown as "Connected" in the user interface. If the connection breaks down, the agent will be shown as "Offline" and an alarm will be sent.

Restarting

To restart the device that the agent is running on, go to the "Control" tab and click "Restart".

Tracing

The agent writes a log to Device Integration Platform. Low-severity log levels are sent to Device Integration Platform as events and are visible in the "Events" tab of the device. Higher-severity log levels are recorded as alarms and are visible in the "Alarms" tab of the device. To configure the verbosity of logging, go to the "Control" tab and edit the configuration.

"c8y.log.eventLevel" is the minimum level of log entries that are sent as events. Default is "INFO".
"c8y.log.alarmLevel" is the minimum level of log entries that are sent as alarms. Default is "ERROR".

Valid levels are "TRACE", "DEBUG", "INFO", "WARN" and "ERROR". Use "DEBUG" or "TRACE" only for troubleshooting purposes.

Building

Before building please ensure you have at least JDK 1.7 and Maven 3. You can check this by running:

mvn -version
javac -version

Your Maven "settings.xml" file needs to point to the Device Integration Platform repository as described here. Source code is available at https://bitbucket.org/m2m/cumulocity-examples in the folder java-agent. To build the agent simply run:

mvn clean install

Extending

Extending the agent with drivers for new hardware and new devices requires the following steps:

Create a Java class that implements the interface Driver.
Create a jar file with the class and an additional text file "META-INF/services/c8y.lx.driver.Driver". The text file needs to contain the fully-qualified class name of the Java class.
Deploy the jar file either by copying it to the "lib" folder of the agent or by deploying it through Device Integration Platform's software management.

The BitBucket repository contains numerous examples of drivers. Usage of the Java client library is described in Developing Java clients.

Server-side agents

The BitBucket repository also contains a complete example of a server-side agent for closed devices in the folder "tracker-agent". This example works with tracking devices from Telic and Queclink, see the Section "Devices". It demonstrates solutions to various challenges when developing server-side functionality for mobile devices.