SDK for Node.js - - Alibaba Cloud Documentation Center

You can develop a driver by using the SDK for Node.js to connect a device to a gateway. Then connect the device to the IoT Platform.

For the source code of the SDK for Node.js, visit Open-source SDK for Node.js.

Installation and usage

Run the following command to install the SDK:
```
npm install linkedge-thing-access-sdk
```

After the SDK is installed, you can develop drivers based on the SDK interface.

Important If you run a driver directly after the driver development is completed, an error will occur. You must deploy the driver to the gateway on the IoT Platform console before you run the driver. For more information about how to deploy the driver to the gateway, see Driver Development.

The following is an example of how to use the SDK to develop a driver:

const {
  Config,
  ThingAccessClient
} = require('linkedge-thing-access-sdk');

const callbacks = {
  setProperties: function (properties) {
    // Set properties to the physical thing and return the result.
    // Return an object representing the result or the promise wrapper of the object.
    return {
      code: 0,
      message: 'success',
    };
  },
  getProperties: function (keys) {
    // Get properties from the physical thing and return the result.
    // Return an object representing the result or the promise wrapper of the object.
    return {
      code: 0,
      message: 'success',
      params: {
        key1: 'value1',
        key2: 'value2',
      }
    };
  },
  callService: function (name, args) {
    // Call services on the physical thing and return the result.
    // Return an object representing the result or the promise wrapper of the object.
    return new Promise((resolve) => {
      resolve({
        code: 0,
        message: 'success',
      });
    });
  }
};
Config.get()
  .then(config => {
    const thingInfos = config.getThingInfos();
    thingInfos.forEach(thingInfo => {
      const client = new ThingAccessClient(thingInfo, callbacks);
      client.registerAndOnline()
        .then(() => {
          return new Promise(() => {
            setInterval(() => {
              client.reportEvent('high_temperature', { temperature: 41 });
              client.reportProperties({ 'temperature': 41 });
            }, 2000);
          });
        })
        .catch(err => {
          console.log(err);
          client.cleanup();
        });
        .catch(err => {
          console.log(err);
        });
    });
  });

Constants

Parameter	Type	Description
PRODUCT_KEY	String	A key in the configuration object. The key is passed to the ThingAccessClient constructor. Set the value to the ProductKey that was allocated to you by IoT Platform.
DEVICE_NAME	String	A key in the configuration object. The key is passed to the ThingAccessClient constructor. Set the value to the DeviceName that was allocated to you by IoT Platform.
LOCAL_NAME	String	A key in the configuration object. The key is passed to the ThingAccessClient constructor. Set the value to the on-premises device name.
CALL_SERVICE	String	A key in the callback object. The key is passed to the ThingAccessClient constructor. Set the value to the callback function that is used to call device services. For more information about the function definition, see callbacks.callService().
GET_PROPERTIES	String	A key in the callback object. The key is passed to the ThingAccessClient constructor. Set the value to the callback function that is used to obtain device properties. For more information about the function definition, see callbacks.getProperties().
SET_PROPERTIES	String	A key in the callback object. The key is passed to the ThingAccessClient constructor. Set the value to the callback function that is used to set device properties. For more information about the function definition, see callbacks.setProperties().
RESULT_SUCCESS	Number	The operation was successful. It is a status code used by the callback functions.
RESULT_FAILURE	Number	The operation failed. It is a status code used by the callback functions.
ERROR_CLEANUP	String	The error code for the cleanup() function.
ERROR_CONNECT	String	The error code for the registerAndOnline() function.
ERROR_DISCONNECT	String	The error code for the offline() function.
ERROR_GET_CONFIG	String	The error code for the getConfig() function.
ERROR_GET_TSL	String	The error code for the getTsl() function.
ERROR_GET_TSL_EXT_INFO	String	The error code for the getTslExtInfo() function.
ERROR_UNREGISTER	String	The error code for the unregister() function.

Config

The information related to driver configurations.

static get()
Returns the global driver configuration object, which is generated by the system when the device is associated with the driver.
Note The difference between the Config.get() function and the getConfig() function is that getConfig() returns a configuration string whereas Config.get() returns a configuration object.
Response:
```
Promise<Config>
```
static registerChangedCallback(callback)
The callback function that is used to make configuration changes
Table 1. Request parameters
Parameter Type Description
callback Function The callback function that is called when a configuration change occurs.
static unregisterChangedCallback(callback)
The callback function that is used to revert configuration changes.
Table 2. Request parameters
Parameter Type Description
callback Function The callback function that is called when a configuration change occurs.
Config(string)
Constructs a new Config object based on a configuration string.
Table 3. Request parameters
Parameter Type Description
string String The JSON configuration string.
getThingInfos()
Returns all device-related information.
Response:
```
ThingInfo[]
```
getDriverInfo()
Returns the driver information.
Response:
```
Object
```

ThingInfo

This function can be used to identify the information of devices that are connected to Link IoT Edge. After a device is connected to Link IoT Edge, information such as the ProductKey, DeviceName, and custom configurations of the device can be identified by the function.

ThingInfo(productKey, deviceName, custom)

Constructs a new ThingInfo object.

Table 4. Request parameters
Parameter	Type	Description
productKey	String	The unique identifier of the product.
deviceName	String	The name of the device.
custom	Object	Custom device configurations.

ThingAccessClient

The client that allows devices to connect to IoT Platform. You can use the client to report properties and events. You can also use the client to send commands from the cloud to the devices.

ThingAccessClient(config, callbacks)

The constructor, which is initialized by specifying the config and callbacks parameters.

Table 5. Request parameters
Parameter	Type	Description
config	Object	The metadata that is used to configure the client. Format: `{ "productKey": "Your Product Key", "deviceName": "Your Device Name" }`
callbacks	Object	The callback function object. Format: `callbacks: { setProperties: function(properties) {}, getProperties: function(keys) {}, callService: function(name, args) {} }` For callback parameters of setting device properties, see the callbacks.setProperties section. For callback parameters of obtaining device properties, see the callbacks.getProperties section. For callback parameters of calling device services, see the callbacks.callService section.

callbacks.setProperties(properties)

The callback function that is used to set device properties. You can use the callback function to set device properties.

Table 6. Request parameters
Parameter	Type	Description
properties	Object	The property object. The format of the property value is as follows: `{ "key1": "value1", "key2": "value2" }`

Response:

{
  "code": 0,
  "message": "string",
  "params": {}
}

Table 7. Response Parameters
Parameter	Type	Description
code	Number	The status code. 0: indicates that the call was successful. Non-zero: indicates that the call failed and an error corresponding to the non-zero value was returned.
message	String	Optional. The status description information.
params	Object	Optional. This parameter can be used to return the configuration result of each property. The parameter contains the actual values of the properties.

callbacks.getProperties(keys)

The callback function that is used to obtain specified device properties. You can use the callback function to obtain the properties of the device.

Table 8. Request parameters
Parameter	Type	Description
keys	String[]	The names of the properties. The format is as follows: `['key1', 'key2']`

Response:

{
  "code": 0,
  "message": "string",
  "params": {}
}

Table 9. Response Parameters
Parameter	Type	Description
code	Number	The status code. 0: indicates that the call was successful. Non-zero: indicates that the call failed and an error corresponding to the non-zero value was returned.
message	String	Optional. The status description information.
params	Object	Optional. This parameter can be used to return the value of the specified properties if the request is successful.

callbacks.callService(name, args)

The callback function that is used to call device services. You can use a callback function to call the device service.

Table 10. Request parameters
Parameter	Type	Description
name	String	The name of the device service.
args	Object	The list of service input parameters. The format is as follows: `{ "key1": "value1", "key2": "value2" }`

Table 11. Response Parameters
Parameter	Type	Description
code	Number	The status code. 0: indicates that the call was successful. Non-zero: indicates that the call failed and an error corresponding to the non-zero value was returned.
message	String	Optional. The status description information.
params	Object	Optional. This parameter can be used to return additional information when the service is called.

registerAndOnline()
Registers the device on the gateway and notifies the gateway to connect the device to IoT Platform. You must register and connect the devices to IoT platform before they can receive commands from or send data to IoT platform.
Response:
```
Promise<Void>
```
online()
Notifies the gateway that the device is online. The function is used when the device is offline and then is online again.
Response:
```
Promise<Void>
```
offline()
Notifies the gateway that the device is offline.
Response:
```
Promise<Void>
```

reportEvent(eventName, args)

Reports device events to IoT Platform.

Table 12. Request parameters
Parameter	Type	Description
eventName	String	The event name, which is the same as the name of the event you specified in the product definition.
args	Object	The keys and values in the event. The format is as follows: `{ "key1": "value1", "key2": "value2" }`

reportProperties(properties)
Reports device properties to IoT Platform.
Table 13. Request parameters
Parameter Type Description
properties
Object
The keys and values in the properties. The format is as follows:
{ "key1": "value1", "key2": "value2" }
getTsl()
Returns the TSL string of the device. The data format is the same as in IoT Platform.
Response:
```
Promise<Void>
```
getTslExtInfo()
Returns the extended information of the TSL.
Response:
```
Promise<String>
```
cleanup()
Recycles resources. You can use this function to free up resources.
Response:
```
Promise<Void>
```
unregister()
Removes a device from the gateway. Use this function with caution.
Response:
```
Promise<Void>
```

getConfig()

Obtains the driver configuration string. which is generated by the system when the device is associated with the driver.

Note The difference between the static get() function (Config.get()) is that getConfig() returns a configuration string whereas Config.get() returns a configuration object.

Response:

Promise<String>

destroy()

Destroys all resources used by the SDK. You can call the destroy() function when you no longer want to use the SDK.

Response:

Promise<Void>