This guide will guide you how to use Sensecap Java SDK

Overview


Prerequisite

If you do not have an account, please register for the SenseCAP Portal.

Get an Access Key

  1. Login the SenseCAP Portal.
  2. Navigate to “Security/Access API keys”
  3. Click “Create Access Key”
  4. Click “API ID”, and get the “API ID” and “Access API keys” after entering the password.

Maven coordinates

<dependency>
    <groupId>cc.seeed.sensecap-sdk</groupId>
    <artifactId>sensecap-java-sdk</artifactId>
    <version>1.0-RELEASE</version>
</dependency>

SenseCAPClient initialization

//client Configure
{
    String accessId = " ";
    String accessKey = "";
    int region = RegionType.SENSECAP_CC.getRegion();
  //SenseCAPClient senseCAPClient = new SenseCAPClientBuilder().buildConfig(accessId, accessKey, region);
    OpenApiConfig openApiConfig = new OpenApiConfig(accessId, accessKey, region);
    SenseCAPClient senseCAPClient = new SenseCAPClientBuilder().buildConfig(openApiConfig);
}

Organization


Get organizationId

public long getOrganizationId() throws BaseException;

Request parameters

None

Return values

Type Description
long organizationId

Request Example

public static void getOrganizationId() throws BaseException{
    long organizationId = senseCAPClient.getOrganizationManager()
            .getOrganizationId();
    System.out.println(organizationId);
}

Group


Create Group

 public GroupInfo create(String groupName) throws BaseException;

Request parameters

Name Type Description
groupName String Group name

Return values

Type Description
GroupInfo Group information

Request Example

public static void createGroup() throws BaseException {
    GroupInfo result = senseCAPClient.getGroupManager().create("SDk-TEST");
    System.out.println(result);
}

Rename group

 public void rename(String groupUUID, String groupName) throws BaseException;

Request parameters

Name Type Description
groupUUID String GroupUUID
groupName String Group name

Return values

None

Request Example

public static void renameGroup() throws BaseException {
        senseCAPClient.getGroupManager().rename("groupUUID", "SDk-TEST");
    }

Remove group

public void remove(String groupUUID) throws BaseException;

Request parameters

Name Type Description
groupUUID String GroupUUID

Return values

None

Request Example

public static void renameGroup() throws BaseException {
        senseCAPClient.getGroupManager().remove("GroupUUID");
    }

Get all group

public List<GroupInfo> getGroupList() throws BaseException;

Request parameters

None

Return values

Type Description
list Group information list

Request Example

public static void getGroupList() throws BaseException {
    GroupResult groupResult = senseCAPClient.getGroupManager().createGroupQuery()
            .build()
            .execute();
    List<GroupInfo> groupInfos = groupResult.toList();
    System.out.println(groupInfos.toString());
}

Device


Move device

public  void moveDevices(String groupUUID, List<String> deviceEuis) throws BaseException;

Request parameters

Name Type Description
groupUUID String GroupUUID
deviceEuis array Device eui list

Return values

None

Request Example

public static void moveDeivces() throws BaseException {
    List<String> deviceEuis = Lists.newArrayList();
    deviceEuis.add(deviceEui);
    senseCAPClient.getDeviceManager().moveDevices("groupUUID", deviceEuis);
}

Get all devices under the group

public List<DeviceBaseInfo> getDeviceList(int deviceType, String groupUUID) throws BaseException;

Request parameters

Name Type Description
groupUUID String GroupUUID
deviceType int Device type 1:gateway ,2:node(default)

Return values

Type Description
list device base information list

Request Example

public static void getDeviceList() throws BaseException {
    DeviceResult deviceResult = senseCAPClient.getDeviceManager().createDeviceQuery()
            .deviceType(2)
            .groupUUID("")
            .build()
            .execute();
    List list = deviceResult.deviceList();
    System.out.println(list.toString());
}

Get device information

public List<DeviceInfo> getDeviceInfo(List<String> deviceEuis, int deviceType)  throws BaseException;

Request parameters

Name Type Description
deviceEuis String Device eui list
deviceType int Device type 1:gateway ,2:node(default)

Return values

Type Description
list Device information list

Request Example

public static void getDeviceInfoList() throws BaseException {
    List<String> deviceEuis = Lists.newArrayList();
    deviceEuis.add(deviceEui);
    DeviceResult deviceResult = senseCAPClient.getDeviceManager().createDeviceQuery()
            .deviceEuis(deviceEuis)
            .deviceType(2)
            .build()
            .execute();
    List<DeviceInfo> deviceInfos = deviceResult.deviceInfos();
    System.out.println(deviceInfos.toString());

}

Get device channel information

public List<DeviceChannelInfo> getDeviceChannelList(List<String> deviceEuis)  throws BaseException;

Request parameters

Name Type Description
deviceEuis String device eui list

Return values

Type Description
list Device channel information list

Request Example

public static void getDeviceChannelList() throws BaseException {
    List<String> deviceEuis = Lists.newArrayList();
    deviceEuis.add(deviceEui);
    DeviceResult deviceResult = senseCAPClient.getDeviceManager().createDeviceQuery()
            .deviceEuis(deviceEuis)
            .build()
            .execute();
    List<DeviceChannelInfo> deviceChannelInfos = deviceResult.channelList();
    System.out.println(deviceChannelInfos.toString());
}

Get device running status

public List<DeviceStatusInfo> getDeviceRunningStatusList(List<String> deviceEuis)  throws BaseException;

Request parameters

Name Type Description
deviceEuis String device eui list

Return values

Type Description
list device running status list

Request Example

public static void getDeviceRunningStatusList() throws BaseException {
    List<String> deviceEuis = Lists.newArrayList();
    deviceEuis.add(deviceEui);
    DeviceResult deviceResult = senseCAPClient.getDeviceManager().createDeviceQuery()
            .deviceEuis(deviceEuis)
            .build()
            .execute();
    List<DeviceStatusInfo> deviceStatusInfos = deviceResult.runningStatusList();
    System.out.println(deviceStatusInfos);
}

Bind device

public boolean bindDevice(String eui, String code, String deviceName, String groupUUID, String longitude, String latitude) throws BaseException;

Request parameters

Name Type Description
eui String device eui
code String device code
deviceName String device name
groupUUID String groupUUID
longitude String longitude
latitude String latitude

Return values

None

Request Example

public static void bindDevice() throws BaseException {
    senseCAPClient.getDeviceManager().createBinder()
            .eui("")
            .code("")
            .deviceName("")
            .groupUUID("")
            .longitude("")
            .latitude("")
            .build()
            .bind();
}

Delete device

public boolean deleteDevices(List<String> deviceEuis) throws BaseException;

Request parameters

Name Type Description
deviceEuis String device eui list

Return values

Type Description
boolean success or not

Request Example

public static void deleteDevices() throws BaseException {
    List<String> deviceEuis = Lists.newArrayList();
    deviceEuis.add(deviceEui);
    boolean b = senseCAPClient.getDeviceManager().deleteDevices(deviceEuis);
}

Telemetry data


Get latest telemetry data

List<LatestTelemetryDataInfo> getLatestTelemetryData(String deviceEui, int channelIndex, int measurementId) throws BaseException;

Request parameters

Name Type Description
deviceEui String device eui
channelIndex int channel
measurementId int measurement id

Return values

Type Description
list latest telemetry data list

Request Example

public static void getLatestTelemetryData() throws BaseException {
    DataResult dataResult = senseCAPClient.getDataManager().createDataQuery()
            .deviceEui(deviceEui)
            .channelIndex(1)
            .measurementId(4099)
            .build()
            .execute();
    List<LatestTelemetryDataInfo> latestTelemetryDataInfos = dataResult.latestData();
    System.out.println(latestTelemetryDataInfos.toString());
}

Get historical telemetry data

List<TelemetryDataInfo> getTelemetryDataListCallback(String deviceEui, int channelIndex, int measurementId, int limit, long startTime, long endTime, TelemetryDataCallback var) throws BaseException;

Request parameters

Name Type Description
deviceEui String device eui
channelIndex int channel
measurementId int measurement id
limit int Number of queries
startTime long start time
endTime long end time
var TelemetryDataCallback Callback function

Parameter description

  • [startTime>0,endTime>0] Get the historical data of the specified time range [-30d,now]
  • (startTime=0,endTime>0] Get the default one day old to endTime historical data [-1d,endTime]
  • [startTime>0,endTime=0) Get the historical data of the start time and subscribe to the latest news [startTime,–]
  • (startTime=0,endTime=0) Subscribe to the latest news only [now,–]
  • Service restart requires user to handle reconnection subscription by self

Return values

Type Description
list historical telemetry data list

Request Example

public static void getTelemetryDataListCallBack() throws BaseException {
        DataResult dataResult = senseCAPClient.getDataManager().createDataQuery()
            .deviceEui(deviceEui)
            .channelIndex(1)
            //.measurementId(4100)
            .startTime(1605385871000L)
            //.endTime(1605496271000L)
            .limit(100)
            .callback(new TelemetryDataCallback() {
                @Override
                public void messageArrived(TelemetryDataResult var) throws BaseException {
                    System.out.println("Test get mqtt messages: " + var.toString());
                }
            })
            .build()
            .execute();
    List<TelemetryDataInfo> list = dataResult.dataList();
    System.out.println(JSON.toJSONString(list));


}

Get device Line chart data(openAPI)

List<ChartPointDataInfo> getChartPointData(String deviceEui, int channelIndex, int measurementId, int interval, long startTime, long endTime) throws BaseException;

Explain

  • Divide the large data segment into small data segments, then output the average value of each segment.
  • The return data is up to one year and 250 points each measurement at most.If more than 250 points, it will automatically re-divide the time period to return 250 points.

Request parameters

Name Type Description
deviceEui String device eui
channelIndex int channel
measurementId int measurement id
interval int Interval minutes
startTime long start time Timestamp MS
endTime long end time Timestamp MS

Return values

Type Description
list device Line chart data list

Request Example

public static void getLatestTelemetryData() throws BaseException {
    DataResult dataResult = senseCAPClient.getDataManager().createDataQuery()
            .startTime(1605600000000L)
            .deviceEui(deviceEui)
            .build()
            .execute();
    List<ChartPointDataInfo> chartPointDataInfos = dataResult.chartPointData();
    System.out.println(JSON.toJSONString(chartPointDataInfos));
}

Get device Line chart data

List<ChartDataListInfo> getChartDataList(String deviceEui, int channelIndex, int measurementId, int interval, long startTime, long endTime) throws BaseException;

Explain

  • Return all data points within one day (inclusive)
  • If the time is greater than one day, the average value of data points in the interval range is returned
  • interval should not be less than the minimum interval of data reporting

Request parameters

Name Type Description
deviceEui String device eui
channelIndex int channel
measurementId int measurement id
interval int Interval minutes
startTime long start time Timestamp MS
endTime long end time Timestamp MS

Return values

Type Description
list device Line chart data list

Request Example

public static void getLatestTelemetryData() throws BaseException {
    DataResult dataResult1 = senseCAPClient.getDataManager().createDataQuery()
            .startTime(1605600000000L)
            .deviceEui(deviceEui)
            .interval(30)
            .build()
            .execute();
    List<ChartDataListInfo> listInfoList = dataResult1.chartData();
    System.out.println(JSON.toJSONString(listInfoList));
}