This article describes how to use the advanced features of the generic-protocol SDK. The advanced features allow you to specify the configuration file paths, configure dynamic bridge registrations, and call the data reporting interfaces that are encapsulated in the generic-protocol SDK to report properties, report events, and update tags.

Specify the path of configuration files

By default, the configuration file of a bridge device is read from the application.conf file, and the configuration file of the device certificate mapping is read from the devices.conf file. The generic-protocol SDK allows you to specify paths. Before you call the bootstrap() method, you must call the ConfigFactory.init() method to specify the path of a configuration file. You can also create an instance and implement the corresponding interface.

Sample code:

//Define config
//You can specify the location path of config files 
//or you can create an instance and implement the corresponding interface
//Config.init() must be called before bridgeBootstrap.bootstrap()
ConfigFactory.init(
    ConfigFactory.getBridgeConfigManager("application-self-define.conf"),
    selfDefineDeviceConfigManager);
bridgeBootstrap.bootstrap();

private static DeviceConfigManager selfDefineDeviceConfigManager = new DeviceConfigManager() {
    @Override
    public DeviceIdentity getDeviceIdentity(String originalIdentity) {
        //Suppose you dynamically get deviceInfo in other ways
        return devicesMap.get(originalIdentity);
    }

    @Override
    public String getOriginalIdentity(String productKey, String deviceName) {
        //you can ignore this
        return null;
    }
};

Dynamically register a bridge device

When you need to deploy a bridge on a large number of servers, the process can be more 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 generic-protocol SDK calls the IoT Platform API 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 the sample code, see Use the basic features.
  • If the bridge configuration file already includes the information of a bridge device, the bridge device is not registered again. The generic-protocol SDK calls the IoT Platform API to register a bridge device only if the configuration file meets the following conditions: The deviceName and deviceSecret parameters are left empty, and all the parameters in popClientprofile are specified. If a device is already registered by using a MAC address, the device is used as the bridge device without registering a new device.
  • We recommend that you do not use the bridge configuration file of the production environment to debug the bridge servers. When you use the bridge configuration file of the production environment for debugging, the bridge servers that are specified by the MAC addresses are registered as the bridge and associated with all devices in the devices.conf file. We recommend that you use test devices for debugging to avoid negative impacts on the production environment.
Table 1. Parameters
Parameter Required Description
productKey Yes The key of the product to which the bridge device belongs.
http2Endpoint Yes The endpoint of the HTTP/2 gateway. The bridge device and IoT Platform establish a persistent connection over the HTTP/2 protocol.
  • For the public instance, the endpoint of the HTTP/2 gateway is in the format of https://${productKey}.iot-as-http2.${RegionId}.aliyuncs.com:443.

    Replace ${productKey} with the key 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 more information, see Regions and zones.

    For example, if the product key of the bridge device is alabcab**** and the IoT Platform service is purchased in the China (Shanghai) region, the endpoint of the HTTP/2 gateway is https://alabcab****.iot-as-http2.cn-shanghai.aliyuncs.com:443.

  • For a purchased instance, the endpoint of the HTTP /2 gateway is in the format of 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 of the HTTP/2 gateway is https://iot-cn-g06kwb****.http2.iothub.aliyuncs.com:443.

authEndpoint Yes The endpoint of the device authentication server.
  • For the public instance, the endpoint of the device authentication server is in the format of https://iot-auth.${RegionId}.aliyuncs.com/auth/bridge.

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

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

  • For a purchased instance, the endpoint of the device authentication server is in the format of 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 of the device authentication server is https://iot-cn-g06kwb****.auth.iothub.aliyuncs.com/auth/bridge.

popClientProfile Yes If you specify this parameter, the generic-protocol SDK calls the IoT Platform API to automatically 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 Alibaba Cloud Management Console, move the pointer overyour profile picture, and then click AccessKey Management. On the Security Management page, you can create or view an AccessKey pair.

accessSecret Yes The AccessKey secret of your Alibaba Cloud account.
name Yes The name of the region where you purchased the IoT Platform service and to which the bridge device connects. The product that is identified by productKey belongs to this region.

For more information, see Regions and zones.

region Yes The ID of region where you purchased the IoT Platform service and to which the bridge device connects. The product that is identified by productKey belongs to this region.

For information about region IDs, see the topic that is provided in the name row.

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

Replace ${RegionId} with the region ID. For more information, see Regions and zones.

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

The following example shows how to configure a bridge device to be dynamically registered when you use the public instance.

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

# Gateway device info
# You can also specify productKey only, and dynamic register deviceName & deviceSecret in runtime
productKey = ${YourProductKey}

# If you dynamic register gateway device using your mac address, you have to specify 'popClientProfile'
# otherwise you can ignore it
popClientProfile = {
    accessKey = ${YourAliyunAccessKey}
    accessSecret = ${YourAliyunAccessSecret}
    name = cn-shanghai
    region = cn-shanghai
    product = Iot
    endpoint = iot.cn-shanghai.aliyuncs.com
}

Call the methods to report Thing Specification Language (TSL) data

To simplify the usage of the generic-protocol SDK, the SDK provides three data reporting methods: reportProperty(), fireEvent(), and updateDeviceTag(). The device can use these methods to report properties, report events, and update device tags.

Prerequisites and instructions:

  • Properties and events are defined in the IoT Platform console. Before you call the reportProperty() and fireEvent() methods to report properties and events, log on to the IoT Platform console and go to the Product Details page of the required product. Then, click the Define Feature tab to define properties and events. For more information, see Add a TSL feature.
  • Tags are created and updated. Before you call the updateDeviceTag() method to update a device tag, check whether the tag is displayed in the IoT Platform console. If the tag is displayed on the Product Details page of the required devices, update the value of the tag. If the tag is not displayed, create a new tag.

Sample code:

TslUplinkHandler tslUplinkHandler = new TslUplinkHandler();
//report property
//Property 'testProp' is defined in IoT Platform Web Console
String requestId = String.valueOf(random.nextInt(1000));
tslUplinkHandler.reportProperty(requestId, originalIdentity, "testProp", random.nextInt(100));

//fire event
//Event 'testEvent' is defined in IoT Platform Web Console
requestId = String.valueOf(random.nextInt(1000));
HashMap<String, Object> params = new HashMap<String, Object>();
params.put("testEventParam", 123);
tslUplinkHandler.fireEvent(originalIdentity, "testEvent", ThingEventTypes.INFO, params);

//update device tag
//'testDeviceTag' is a tag key defined in IoT Platform Web Console
requestId = String.valueOf(random.nextInt(1000));
tslUplinkHandler.updateDeviceTag(requestId, originalIdentity, "testDeviceTag", String.valueOf(random.nextInt(1000)));

The following table describes the parameters that are used in this example.

Parameter Description
requestId The request ID.
originalIdentity The original identifier of the device.
testProp The identifier of the property. In this example, a property whose identifier is testProp is created in the IoT Platform console before the reportProperty() method is called to report the value of the property.
random.nextInt(100) The property value to be reported. The value range of the property is also defined in the IoT Platform console. In this example, the value is a random integer that is generated by random.nextInt(100). The value is less than 100.
testEvent The identifier of the event. In this example, an event whose identifier is testEvent is created in the IoT Platform console before the fireEvent() method is called to report the event.
ThingEventTypes.INFO The event type. The ThingEventTypes parameter specifies the event type. INFO indicates that the event type is information.

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

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

params The output parameters of the event. The identifier, data type, and value range of the output parameters are also defined in the IoT Platform console. In this example, the identifier of the event 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 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, the value is a random number that is generated by String.valueOf(random.nextInt(1000)). The number is less than 1000. Set the value of the tag as instructed based on your requirements. For more information, see Device tags.