This article describes how to configure the IoT as Bridge SDK to use the advanced features. You can specify configuration file paths and dynamically register bridge devices. You can also call the specified operations that are encapsulated in the IoT as Bridge SDK to submit properties or events, set properties, and call services.

Specify configuration file paths

By default, the configuration file of a bridge device is application.conf, and the configuration file of the device certificate mapping is devices.conf.

The IoT as Bridge SDK allows you to customize setting. Before you call the bootstrap() method, you can call the ConfigFactory.init() method to specify the path of a configuration file. You can also create an instance and configure the API operations as needed.

Sample code:

ConfigFactory.init(
    ConfigFactory.getBridgeConfigManager("application-self-define.conf"),
    selfDefineDeviceConfigManager);
bridgeBootstrap.bootstrap();

private static DeviceConfigManager selfDefineDeviceConfigManager = new DeviceConfigManager() {
    @Override
    public DeviceIdentity getDeviceIdentity(String originalIdentity) {
        return devicesMap.get(originalIdentity);
    }

    @Override
    public String getOriginalIdentity(String productKey, String deviceName) {
        return null;
    }
};

Dynamically register bridge devices

When you need to deploy bridges on a large number of servers, the deployment process is complex if you specify different bridge devices for different bridge servers. You can edit the bridge configuration file application.conf to dynamically register the bridge devices.

You must specify the productKey and popClientProfile parameters of each bridge device in the configuration file. Then, the IoT as Bridge SDK calls an IoT Platform operation to register the bridge devices and uses the MAC addresses of the servers as the device names.

Note
  • To dynamically register the bridge devices, you only need to edit the bridge configuration file. For information about the sample code, see Use the basic features.
  • All parameters in the popClientprofile file must be specified. If a MAC address is used by an existing device, the device is used as a bridge device.
  • The deviceName parameter and deviceSecret parameters must be left empty. If you have specified the information about a bridge device, the device cannot be dynamically registered.
  • We recommend that you use dedicated test devices for debugging. Do not debug programs on local machines to prevent possible impacts on production environment.

    If you debug the programs on the local machines, the MAC addresses of the machines are registered as bridge names. The bridges are associated with all devices in the devices.conf file.

Table 1. Parameters
Parameter Required Description
productKey Yes The ProductKey of the product to which the bridge device belongs.
subDeviceConnectMode No The type of the bridge device.
  • If this parameter is set to 3, a large-size bridge is created. A maximum of 500,000 devices can connect with the bridge.
  • If this parameter is not specified, a small-size bridge is created. A maximum of 15,00 devices can connect with the bridge.

Large-size bridges and small-size bridges use different policies to disconnect devices. For more information, see Disconnect a device from IoT Platform.

http2Endpoint Yes The endpoint of the HTTP/2 gateway. The bridge and IoT Platform establish a persistent connection over the HTTP/2 protocol.

Endpoint format:

  • Public instance: https://${productKey}.iot-as-http2. ${RegionId}.aliyuncs.com:443.

    Replace ${productKey} with the ProductKey of the product to which your bridge device belongs.

    Replace ${RegionId} with the ID of the region where you purchased the IoT Platform service. For information about region IDs, see Regions and zones.

    For example, if the ProductKey of a bridge device is a1abcab**** and the IoT Platform service is purchased in the China (Shanghai) region, the endpoint is https://a1abcab****.iot-as-http2.cn-shanghai.aliyuncs.com:443.

  • Enterprise Edition instance: https://${IotInstanceId}.http2.iothub.aliyuncs.com:443.

    Replace ${IotInstanceId} with the ID of the purchased instance.

    For example, if the instance ID is iot-cn-g06kwb****, the endpoint is https://iot-cn-g06kwb****.http2.iothub.aliyuncs.com:443.

authEndpoint Yes The endpoint of the device authentication server.

Endpoint format:

  • Public instance: https://iot-auth. .${RegionId}.aliyuncs.com/auth/bridge.

    Replace ${RegionId} with the ID of the region where you purchased the IoT Platform service. For information about region IDs, see Regions and zones.

    For example, if the IoT Platform service is purchased in the China (Shanghai) region, the endpoint is https://iot-auth.cn-shanghai.aliyuncs.com/auth/bridge.

  • Enterprise Edition instance: https://${IotInstanceId}.auth.iothub.aliyuncs.com/auth/bridge.

    Replace ${IotInstanceId} with the ID of the purchased instance.

    For example, if the instance ID is iot-cn-g06kwb****, the endpoint is https://iot-cn-g06kwb****.auth.iothub.aliyuncs.com/auth/bridge.

popClientProfile Yes If you specify this parameter, the IoT as Bridge SDK calls the related IoT Platform API operation to create a bridge device.

The following table describes the parameters of popClientProfile.

Table 2. popClientProfile
Parameter Required Description
accessKey Yes The AccessKey ID of your Alibaba Cloud account.

To create or view an AccessKey pair, log on to the IoT Platform console, move the pointer over your profile picture, and then click AccessKey Management. On the Security Management page, you can create or view AccessKey pairs.

accessSecret Yes The AccessKey secret of you Alibaba Cloud account.
name Yes The ID of the region to which the bridge device belongs.

For more information about region IDs, see Regions and zones.

region Yes
product Yes The name of the product. Set the value to Iot.
endpoint Yes The endpoint of the API in the specified region. Format: iot.${RegionId}.aliyuncs.com.

Replace ${RegionId} with the ID of the region where you purchased the IoT Platform service. For information about region IDs, see Regions and zones.

For example, if the region is China (Shanghai), the endpoint is iot.cn-shanghai.aliyuncs.com.

In this example, a public instance is used to dynamically register a small-size bridge device.

# The endpoint of the service.
http2Endpoint = "https://${YourProductKey}.iot-as-http2.cn-shanghai.aliyuncs.com:443"
authEndpoint = "https://iot-auth.cn-shanghai.aliyuncs.com/auth/bridge"

# The information of the bridge device.
productKey = ${YourProductKey}

popClientProfile = {
    accessKey = ${YourAliyunAccessKey}
    accessSecret = ${YourAliyunAccessSecret}
    name = cn-shanghai
    region = cn-shanghai
    product = Iot
    endpoint = iot.cn-shanghai.aliyuncs.com
}

Call operations to submit Thing Specification Language (TSL) data

The IoT as Bridge SDK encapsulates the operations to submit data. You can call the reportProperty operation to submit properties, call the fireEvent operation to submit events, and call the updateDeviceTag operation to update tags. The device can use these methods to report properties, events, and update device tags.

Note
  • Before you call the reportProperty() and fireEvent() operations, you must define properties and events in the IoT Platform console. Log on to the IoT Platform console and go to the Product Details page. Then, you can define properties and events on the Define Feature tab. For more information, see Add a TSL feature.

  • If a tag already exists when you call the updateDeviceTag operation, the tag value is updated. To view existing tags, go to the Device Details page of the IoT Platform console. If a tag does not exist, IoT Platform automatically creates the tag.

Sample code:

TslUplinkHandler tslUplinkHandler = new TslUplinkHandler();
// Submit a property. 
// The testProp property is defined. 
String requestId = String.valueOf(random.nextInt(1000));
// The timestamp is not included in the submitted property data. 
tslUplinkHandler.reportProperty(requestId, originalIdentity, "testProp", random.nextInt(100));
// The timestamp is included in the submitted property data. 
//tslUplinkHandler.reportProperty(requestId, originalIdentity, "testProp", random.nextInt(100), System.currentTimeMillis());

// Submit an event. 
// The testEvent event is defined. 
requestId = String.valueOf(random.nextInt(1000));
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("testEventParam", 123);
// The timestamp is not included in the submitted event data. 
tslUplinkHandler.fireEvent(originalIdentity, "testEvent", ThingEventTypes.INFO, params);
// The timestamp is included in the submitted event data.
//tslUplinkHandler.fireEvent(originalIdentity, "testEvent", ThingEventTypes.INFO, params, System.currentTimeMillis());

// Update a device tag. 
// The key of the tag is set to testDeviceTag. 
requestId = String.valueOf(random.nextInt(1000));
tslUplinkHandler.updateDeviceTag(requestId, originalIdentity, "testDeviceTag", String.valueOf(random.nextInt(1000)));

The following table describes the parameters.

Parameter Description
requestId The ID of the request.
originalIdentity The original identifier of the device.
testProp The identifier of the property. In this example, the identifier of the defined property is testProp. The testProp property is submitted to IoT Platform.
random.nextInt(100) The value of the property. When you define a property, you can set a value range. In this example, random.nextInt(100) indicates a random integer that is less than 100.
testEvent The identifier of the event. In this example, the identifier of a defined event is testEvent. In this example, the testEvent event is submitted to IoT Platform.
ThingEventTypes.INFO The type of the event. Valid values: ThingEventTypes specifies the event type. A value of INFO indicates that the event type is Info.

In this example, the event type is set to INFO when the testEvent event is defined in the IoT Platform console.

If the event type is ERROR, set this parameter to ThingEventTypes.ERROR.

params The output parameters of the event. The identifiers, data types, and value ranges of the output parameters are defined in the IoT Platform console. In this example, the identifier of the output parameter is testEventParam, and the value is 123.
testDeviceTag The key of the tag. The data type is string. In this example, the key is testDeviceTag. Set the key of the tag as instructed based on your business requirements. For more information, see Device tags.
String.valueOf(random.nextInt(1000)) The value of the tag. The data type is string. In this example, String.valueOf(random.nextInt(1000)) indicates a random integer that is less than 1000. Set the value of the tag as instructed based on your business requirements. For more information, see Device tags.
System.currentTimeMillis() The current system time, in milliseconds.

Calls the operations to submit multiple properties and events at the same time

The IoT as Bridge SDK encapsulates the operations to submit multiple properties and events at the same time. You must create the BatchPostEventPropertyMessage object and call the addProperty() and addEvent() methods to add property and event data. Then, create the TslUplinkHandler object and call the BatchPostEventPropertyMessage() method to submit data.

Note

Before you call the reportProperty() and fireEvent() operations, you must define properties and events in the IoT Platform console. Log on to the IoT Platform console and go to the Product Details page. Then, you can define properties and events on the Define Feature tab. For more information, see Add a TSL feature.

Sample code:

TslUplinkHandler tslUplinkHandler = new TslUplinkHandler();
// Submit multiple properties and events at the same time.
String requestId = String.valueOf(random.nextInt(1000));
long startTime = System.currentTimeMillis() - 3000;

// Create a message to submit data.
BatchPostEventPropertyMessage batchPostEventPropertyMessage = new BatchPostEventPropertyMessage();
Map<String, Object> aiEventParams = new HashMap<>();
aiEventParams.put("EventContent", "hello world");
batchPostEventPropertyMessage
    .addProperty("PowerConsumption", 1000, startTime)
    .addProperty("PowerConsumption", 123, startTime + 1000)
    .addProperty("LightAdjustLevel", 23, startTime)
    .addProperty("LightAdjustLevel", 44, startTime + 1000)
    .addProperty("LightAdjustLevel", 47, startTime + 2000)
    .addEvent("AIEvent", aiEventParams, startTime);
batchPostEventPropertyMessage.setId(requestId);

// Submit the data.
tslUplinkHandler.batchPostEventPropertyMessage(originalIdentity, batchPostEventPropertyMessage);

The following table describes the parameters.

Parameter Description
requestId The ID of the request.
startTime The timestamps of the properties and events to be submitted. Unit: milliseconds. The time is displayed in UTC. You can customize this parameter based on your business requirements.
aiEventParams The information about the event.
PowerConsumption The identifiers of the properties. In this example, the identifiers of the defined properties include PowerConsumption and LightAdjustLevel. The values of the two properties at different time points are submitted.
LightAdjustLevel
AIEvent The identifier of the event. In this example, the identifier of the defined event is AIEvent. The AIEvent event is submitted.
originalIdentity The original identifier of the device.

Call operations to set properties and call services

The IoT as Bridge SDK encapsulates the PropertySetHandler operation to set properties and the ServiceInvokeHandler operation to call services. Devices can receive commands from IoT Platform and update data.

Sample code:

BridgeBootstrap bridgeBootstrap = new BridgeBootstrap();
// Set properties.
bridgeBootstrap.setPropertySetHandler(new PropertySetHandler() {
    @Override
    public void onPropertySet(PropertySetMessage msg) {
        log.info("on property set, {}", msg.getParams());
        // If you call the replySuccess() method, the SDK sends the /property/set_reply message to IoT Platform. The response code is 200.
        msg.replySuccess();
        // If you call the replyFail() method, the SDK sends the /property/set_reply message to IoT Platform. You can specify the response code as needed.
        //msg.replyFail(400);
    }
});

// Call services.
bridgeBootstrap.setServiceInvokeHandler(new ServiceInvokeHandler() {
    @Override
    public void onServiceInvoke(ServiceInvokeMessage message) {
        log.info("on service invoke, {}", message.getParams());
        // If you call the replySuccess() method, the SDK sends the /service/{service.identifier}_reply message to IoT Platform. The response code is 200.
        message.replySuccess();
        // If you call the replyFail() method, the SDK sends the /service/{service.identifier}_reply message to IoT Platform. You can specify the response code as needed.
        //msg.replyFail(400);
    }
});