Skip to main content

Java Edge SDK Manual

October 21, 2024

Environment

EdgeAgent

Constructor (EdgeAgentOptions options)​

New EdgeAgent object

EdgeAgentOptions options = new EdgeAgentOptions();

options.ConnectType = ConnectType.DCCS;				// Connection type (DCCS, MQTT). The default setting is DCCS.
// If connectType is DCCS, the following options must be input:
options.DCCS = new DCCSOptions("", "");
If connectType is MQTT, the following options must be input:
options.MQTT = new MQTTOptions("127.0.0.1", 1883, "admin", "pwd", Protocol.TCP);

options.UseSecure = false;
options.AutoReconnect = true;
options.NodeID = ""; 	// Obtain from portal
options.Type = EdgeType.Gateway;				// Configure the edge as a Gateway or Device. The default setting is Gateway.
options.DeviceID = "SmartDevice1";				// If the Type is Device, the DeviceID must be input.
options.Heartbeat = 60000;					// The default is 60 seconds.
options.DataRecover = true;					// Whether to recover data when disconnected
 // If connectType is AzureIoTHub, the following options must be input:
 // EdgeLink
options.AzureIoTHub.ConnectionString = "" ;
 // SCADA
options.AzureIoTHub.HostName = "";
options.AzureIoTHub.SASToken = "";
EdgeAgent edgeAgent = new EdgeAgent(options, agentListener);

Azure IoT Hub​

Due to the limitations of the Azure IoT Hub SDK, the Java SDK supports connecting to the Azure IoT Hub either via a connection string or SAS token. Therefore, when using an EdgeLink device, the connection is established through the connection string. On the other hand, when using a SCADA device, the connection is made using the hostname and SAS token

Event​

EdgeAgent has three subscription events.

  • Connected: When EdgeAgent is connected to the IoTHub.
  • Disconnected: When EdgeAgent is disconnected from the IoTHub.
  • MessageReceived: When EdgeAgent receives an MQTT message from the cloud. The message types are as follows:
    • WriteValue: Change the tag value from the cloud.
    • TimeSync: Returns the current time from the cloud.
    • ConfigAck: Response to config uploads from the edge to the cloud.
EdgeAgentListener agentListener = new EdgeAgentListener() {
    @Override
    public void Connected(EdgeAgent agent, EdgeAgentConnectedEventArgs args) {
        System.out.println("Connected");
    }

    @Override
    public void Disconnected(EdgeAgent agent, DisconnectedEventArgs args) {
        System.out.println("Disconnected");
    }

    @Override
    public void MessageReceived(EdgeAgent agent, MessageReceivedEventArgs e) {
        System.out.println("MessageReceived");
        switch (e.Type) {
            case Const.MessageType.WriteValue:
                WriteValueCommand wvcMsg = (WriteValueCommand) e.Message;
                for (WriteValueCommand.Device device: wvcMsg.DeviceList) {
                    System.out.println("DeviceID:" + device.ID);
                    for (WriteValueCommand.Tag tag: device.TagList) {
                        System.out.printf("TagName: %s, Value: %s\n", tag.Name, tag.Value.toString());
                    }
                }
                break;
            case Const.MessageType.TimeSync:
                TimeSyncCommand tscMsg = (TimeSyncCommand) e.Message;
                System.out.println("UTC Time:" + tscMsg.UTCTime.toString());
                break;
            case Const.MessageType.ConfigAck:
                ConfigAck cfgAckMsg = (ConfigAck) e.Message;
                String result = cfgAckMsg.Result.toString();
                break;
        }
    }
};

EdgeAgent edgeAgent = new EdgeAgent(options, agentListener);

Connect()​

Connect to the IoTHub. When successfully connected, a connected event will be triggered.

edgeAgent.Connect();

Disconnect()​

Disconnect from the IoTHub. When successfully disconnected, a disconnected event will be triggered.

edgeAgent.Disconnect();

UploadConfig(ActionType action, EdgeConfig edgeConfig)​

Upload Node/Device/Tag Config with Action Type (Create/Update/Delete).

EdgeConfig config = new EdgeConfig();
// set node config
// set device config
// set tag config
Boolean result = agent.UploadConfig(Const.ActionType.Create, config);

Node Config:

config.Node = new EdgeConfig.NodeConfig();

Device Config:

EdgeConfig.DeviceConfig device = new EdgeConfig.DeviceConfig();

device.ID = "Device1";
device.Name = "Device1";
device.Type = "Smart Device 1";
device.Description = "Device1";

Analog Tag Config:

EdgeConfig.AnalogTagConfig analogTag = new EdgeConfig.AnalogTagConfig();

analogTag.Name = "Volt";
analogTag.Description = "Volt";
analogTag.ReadOnly = false;
analogTag.ArraySize = 0;
analogTag.SpanHigh = 1000.0;
analogTag.SpanLow = 0.0;
analogTag.EngineerUnit = "V";
analogTag.IntegerDisplayFormat = 4;
analogTag.FractionDisplayFormat = 2;

Discrete Tag Config:

EdgeConfig.DiscreteTagConfig discreteTag = new EdgeConfig.DiscreteTagConfig();

discreteTag.Name = "DTag";
discreteTag.Description = "DTag";
discreteTag.ReadOnly = false;
discreteTag.ArraySize = 0;
discreteTag.State0 = "0";
discreteTag.State1 = "1";
discreteTag.State2 = "";
discreteTag.State3 = "";
discreteTag.State4 = "";
discreteTag.State5 = "";
discreteTag.State6 = "";
discreteTag.State7 = "";

Text Tag Config:

EdgeConfig.TextTagConfig textTag = new EdgeConfig.TextTagConfig();

textTag.Name = "TTag";
textTag.Description = "TTag";
textTag.ReadOnly = false;
textTag.ArraySize = 0;

Block Config​

Create block config:

EdgeConfig.BlockConfig blockConfig = new EdgeConfig.BlockConfig();
blockConfig.BlockType = "Pump";
blockConfig.AnalogTagList = new ArrayList();
blockConfig.DiscreteTagList = new ArrayList();
blockConfig.TextTagList = new ArrayList();

int ATagCount = 1;
int DTagCount = 1;
int TTagCount = 1;

for (int j = 1; j , T is defined according to the tag type (Analog: double, Discrete: int, Text: string).

```java
// analog array tag
HashMap mapVal = new HashMap();
mapVal.put("0", 0.5);	// The tag index is 0 and the value is 0.5.
mapVal.put("1", 1.42);	// The tag index is 1 and the value is 1.42.
mapVal.put("2", 2.89);	// The tag index is 2 and the value is 2.89.
EdgeData.Tag aTag = new EdgeData.Tag();
aTag.DeviceID = "Device1";
aTag.TagName = "ATag1";
aTag.Value = mapVal;

// discrete array tag
HashMap mapVal = new HashMap();
mapVal.put("0", 0);	// The tag index is 0 and the value is 0.
mapVal.put("1", 1);	// The tag index is 1 and the value is 1.
mapVal.put("2", 2);	// The tag index is 2 and the value is 2.
EdgeData.Tag dTag = new EdgeData.Tag();
dTag.DeviceID = "Device1";
dTag.TagName = "DTag";
dTag.Value = mapVal;

// text array tag
HashMap mapVal = new HashMap();
mapVal.put("0", "zero");    // The tag index is 0 and the value is "zero".
mapVal.put("1", "one");	    // The tag index is 1 and the value is "one".
mapVal.put("2", "two");     // The tag index is 2 and the value is "two".
EdgeData.Tag tTag = new EdgeData.Tag();
tTag.DeviceID = "Device1";
tTag.TagName = "TTag";
tTag.Value = mapVal;

SendDeviceStatus(EdgeDeviceStatus deviceStatus)​

Send the device status to the cloud when the status is changed.

EdgeDeviceStatus deviceStatus = new EdgeDeviceStatus();

for (int i = 1; i <= deviceCount; i++) {
    EdgeDeviceStatus.Device device = new EdgeDeviceStatus.Device();
    device.ID = "Device" + i;
    device.Status = Const.Status.Online;

    deviceStatus.DeviceList.add(device);
}

deviceStatus.Timestamp = new Date();
Boolean result = agent.SendDeviceStatus(deviceStatus);

IsConnected()​

Connection status

Boolean status = IsConnected();

Data Recovery on Android​

  • Users must specify the AndroidPackageName of the constructor to use dataRecover on Android. Because the Datahub SDK is a JavaSE project, getPackageName() cannot be used.
  • If in a non-Android environment, the dataRecover function can be used without other settings.
EdgeAgentOptions options = new EdgeAgentOptions();
// ...
options.AndroidPackageName = getPackageName();
EdgeAgent edgeAgent = new EdgeAgent(options, agentListener);

Sample Code

Release Note

  • [1.0.2] - 2024-10-21
    • Add
      • Support Azure IoT Hub device connection which is created from EdgeHub
  • [1.0.1] - 2024-09-09
    • Add
      • Support BlockType that is defined in WISE-PaaS MQTT v1.0.16
  • [1.0.0] - 2024-08-08
    • Add
      • EdgeSync360 EdgeHub EdgeSDK Project initialized, derived from WISE-PaaS DataHub EdgeSDK

Release Note (Archived: WISE-PaaS DataHub EdgeSDK)

  • [1.0.6] - 2021-09-11
    • Updated
      • Remove the strategy of splitting a huge data message into several smaller packets.
  • [1.0.4] - 2020-06-12
    • Updated
      • When calling SendData(), if a tag does not exist in the config, the default config of tag will be used for conversion.
  • [1.0.3] - 2020-06-12
    • Added
      • tag value data type checking, including Array Tag
      • Added parameter “options.OS”, need to specify the OS when developing. If OS is Android, then the parameter “pkg name” is required; if OS is not Android, “options.OS” don’t need to be set.
      • Added parameter “MaxInflight” that is the number of publishing threads at the same time, the default value is 10000.
    • Updated
      • After UploadConfig(), Config will be saved as a cache for data converting.
      • Remove “PrimaryIP”, “BackupIP”, “PrimaryPort” and “BackupPort” properties from EdgeConfig.NodeConfig.
      • Remove “ComPortNumber”, “IP”, and “Port” properties from EdgeConfig.DeviceConfig.
  • [1.0.2] - 2020-03-25
    • Added
      • When the same configuration is reuploaded, EdgeAgent will ignore this action
      • Add the “RetentionPolicyName” property to DeviceConfig
      • Automatic rounding down of the tag value via the AnalogTagConfig property “FractionDisplayFormat”
    • Updated
      • Remove deprecation properties of NodeConfig: “ID”, “Name”, and “Description”
      • Support “Delsert” action of UploadConfig
    • Fixed
      • Fix the data recovery issue
  • [1.0.1] - 2019-10-17
    • Updated
      • Downgrade to Java 7 and rewrite the syntax and usage of Java 8. The aim is to support from Android SDK 22 upwards.
  • [1.0.0] - 2019-10-07

On this page ...

Is this helpful?