设备接入SDK API
更新时间：2018-08-03 14:15:20
C语言版本
#ifndef __LINKEDGE_DEVICE_ACCESS__
#define __LINKEDGE_DEVICE_ACCESS__
#ifdef __cplusplus /* If this is a C++ compiler, use C linkage */
extern "C"
{
#endif
#define LEDA_TAG_NAME "LINKEDGE_DEVICE_ACCESS"
#define LEDA_ERROR_SUCCESS (0) /* 执行成功 */
#define LEDA_ERROR_INVAILD_PARAM (-1) /* 无效参数 */
#define LEDA_ERROR_NO_MEM (-2) /* 没有内存 */
#define LEDA_ERROR_FAILED (-3) /* 执行失败 */
#define LEDA_ERROR_TIME_OUT (-4) /* 超时 */
#define LEDA_ERROR_NOT_SUPPORT (-5) /* 不支持 */
typedef int dev_handle_t; /* linkedge本地连接设备唯一标识符类型 */
#define INVALID_DEVICE_ID -1 /* 不合法的device_id */
#define MAX_PARAM_NAME_LENGTH 64 /* 属性或事件名的最大长度*/
#define MAX_PARAM_VALUE_LENGTH 1024 /* 属性值或事件参数的最大长度*/
typedef enum tag_leda_data_type
{
LEDA_TYPE_INT = 0, /* 整型 */
LEDA_TYPE_BOOL, /* 布尔型 对应值为true or false*/
LEDA_TYPE_FLOAT, /* 浮点型 */
LEDA_TYPE_TEXT, /* 字符串型 */
LEDA_TYPE_DATE, /* 日期型 */
LEDA_TYPE_ENUM, /* 枚举型 */
LEDA_TYPE_STRUCT, /* 结构型 */
LEDA_TYPE_ARRAY, /* 数组型 */
LEDA_TYPE_BUTT
} leda_data_type_e;
typedef struct tag_leda_dev_data
{
leda_data_type_e type; /* 值类型, 需要跟设备 tsl 中保持一致 */
char key[MAX_PARAM_NAME_LENGTH]; /* 属性或事件名 */
char value[MAX_PARAM_VALUE_LENGTH]; /* 属性值 */
} leda_dev_data_t;
/*
* 获取属性的回调函数, LinkEdge 需要获取某个设备的属性时, SDK 会调用该接口间接获取到数据并封装成固定格式后回传给 LinkEdge.
* 开发者需要根据设备id和属性名找到设备, 将属性值获取并以@device_data_t格式返回.
*
* @dev_handle: LinkEdge 需要获取属性的具体某个设备.
* @properties: 开发者需要将属性值更新到properties中.
* @properties_count: 属性个数.
* @usr_data: 注册设备时, 用户传递的私有数据.
*
* 若获取成功则返回LEDA_ERROR_SUCCESS, 失败则返回错误码（参考错误码宏定义）.
* */
typedef int (*get_properties_callback)(dev_handle_t dev_handle,
leda_dev_data_t properties[],
int properties_count,
void *usr_data);
/*
* 设置属性的回调函数, LinkEdge 需要设置某个设备的属性时, SDK 会调用该接口将具体的属性值传递给应用程序, 开发者需要在本回调
* 函数里将属性设置到设备.
*
* @dev_handle: LinkEdge 需要设置属性的具体某个设备.
* @properties: LinkEdge 需要设置的设备的属性名和值.
* @properties_count: 属性个数.
* @usr_data: 注册设备时, 用户传递的私有数据.
*
* 若获取成功则返回LEDA_ERROR_SUCCESS, 失败则返回错误码（参考错误码宏定义).
* */
typedef int (*set_properties_callback)(dev_handle_t dev_handle,
const leda_dev_data_t properties[],
int properties_count,
void *usr_data);
/*
* 服务调用的回调函数, LinkEdge 需要调用某个设备的服务时, SDK 会调用该接口将具体的服务参数传递给应用程序, 开发者需要在本回调
* 函数里调用具体的服务, 并将服务返回值按照设备 tsl 里指定的格式返回.
*
* @dev_handle: LinkEdge 需要调用服务的具体某个设备.
* @service_name: LinkEdge 需要调用的设备的具体某个服务名.
* @data: LinkEdge 需要调用的设备的具体某个服务参数, 参数与设备 tsl 中保持一致.
* @data_count: LinkEdge 需要调用的设备的具体某个服务参数个数.
* @output_data: 开发者需要将服务调用的返回值, 按照设备 tsl 中规定的服务格式返回到output中.
* @usr_data: 注册设备时, 用户传递的私有数据.
*
* 若获取成功则返回LEDA_ERROR_SUCCESS, 失败则返回错误码（参考错误码宏定义).
* */
typedef int (*invoke_service_callback)(dev_handle_t dev_handle,
const char *service_name,
const leda_dev_data_t data[],
int data_count,
leda_dev_data_t output_data[],
void *usr_data);
/*
* 产品信息结构
*/
typedef struct tag_leda_product_def
{
char *product_key; /* 产品唯一描述信息, 由阿里提供, 在设备 tsl 里也可以查得到. */
char *product_tsl; /* 设备tsl, 由阿里提供描述规范, 描述了设备的能力 */
get_properties_callback get_properties_cb; /* 设备属性获取回调 */
set_properties_callback set_properties_cb; /* 设备属性设置回调 */
invoke_service_callback invoke_service_cb; /* 设备服务回调 */
int service_output_data_count; /* 设备服务回调结果数组最大长度 */
} leda_product_def_t;
/*
* 上报属性, 设备具有的属性在设备能力描述 tsl 里有规定.
*
* 上报属性, 可以上报一个, 也可以多个一起上报.
*
* dev_handle: 设备在linkedge本地唯一标识.
* properties: @leda_dev_data_t, 属性数组.
* properties_count: 本次上报属性个数.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*
*/
int leda_device_report_properties(dev_handle_t dev_handle, const leda_dev_data_t properties[], int properties_count);
/*
* 上报事件, 设备具有的事件上报能力在设备 tsl 里有约定.
*
*
* dev_handle: 设备在linkedge本地唯一标识.
* event_name: 事件名称.
* data: @leda_dev_data_t, 事件参数数组.
* data_count: 事件参数数组长度.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*
*/
int leda_device_report_event(dev_handle_t dev_handle, const char *event_name, const leda_dev_data_t data[], int data_count);
/*
* 下线设备, 假如设备工作在不正常的状态或设备退出前, 可以先下线设备, 这样LinkEdge就不会继续下发消息到设备侧.
*
* dev_handle: 设备在linkedge本地唯一标识.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*
*/
int leda_device_offline(dev_handle_t dev_handle);
/*
* 上线设备, 设备只有上线后, 才能被 LinkEdge 识别.
*
* dev_handle: 设备在linkedge本地唯一标识.
*
* 阻塞接口,成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*/
int leda_device_online(dev_handle_t dev_handle);
/*
* 注册设备并上线设备, 申请设备唯一标识符, 若需要注册多个设备, 则多次调用该接口即可.
*
* 设备默认注册后即上线
*
* pd: 参考@leda_product_def_t.
* device_name: 由设备特征值组成的唯一描述信息, 必须保证每个待接入设备名称不同.
* usr_data: 设备注册时传入私有数据, 在回调中会传给设备.
*
* 阻塞接口, 返回值设备在linkedge本地唯一标识, >= 0表示有效, < 0 表示无效.
*
*/
dev_handle_t leda_device_register_and_online(const leda_product_def_t *pd, const char *device_name, void *usr_data);
/*
* 注销设备, 解除设备和LinkEdge关联.
*
* dev_handle: 设备在linkedge本地唯一标识.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*
*/
int leda_device_unregister(dev_handle_t dev_handle);
/*
* 模块初始化, 模块内部会创建工作线程池, 异步执行云端下发的指令, 工作线程数目通过worker_thread_nums配置.
*
* module_name: 模块名称.
* worker_thread_nums : 线程池工作线程数.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*/
int leda_module_init(const char *module_name, int worker_thread_nums);
/*
* 模块退出.
*
* 模块退出前, 释放资源.
*
* 阻塞接口.
*/
void leda_module_exit(void);
typedef enum tag_leda_info_type
{
INFO_TYPE_DEVICE_CONFIG = 0, /* 设备配置信息, 获取时key对应module_name*/
INFO_TYPE_PRODUCT_TSL, /* 产品tsl, 获取时key对应product_key*/
INFO_TYPE_BUTT
} leda_data_info_e;
/*
* 获取配置相关信息长度.
*
* type: 获取信息类型, 参见leda_data_info_e.
* key: type对应的key值, 参见leda_data_info_e.
*
* 阻塞接口, 成功返回key对应的info长度, 失败返回错误码.
*/
int leda_get_pd_info_size(leda_data_info_e type, const char *key);
/*
* 获取配置相关信息.
*
* type: 获取信息类型, 参见leda_data_info_e.
* key: type对应的key值, 参见leda_data_info_e.
* info: 输出信息内容, 需要提前申请好内存传入.
* size: info长度, 该长度通过leda_get_pd_info_size接口获取, 如果传入info比实际配置内容长度短, 会返回LEDA_ERROR_INVAILD_PARAM.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*/
int leda_get_pd_info(leda_data_info_e type, const char *key, char *info, int size);
/*
* 设备配置变更回调.
*
* module_name: 模块名称.
* device_config: 设备配置信息.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*/
typedef int (*onchanged_device_config_callback)(const char *module_name, const char *device_config);
/*
* 注册设备配置变更回调.
*
* module_name: 模块名称.
* device_config_cb: 设备变更通知回调接口.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS,失败返回错误码.
*/
int leda_register_device_config_callback(const char *module_name, onchanged_device_config_callback device_config_cb);
/*
* 喂看门狗.
*
* module_name: 模块名称.
* thread_name: 需要保活的线程名称.
* count_down_seconds : 倒计时时间, -1表示停止保活, 单位:秒.
*
* 阻塞接口, 成功返回LEDA_ERROR_SUCCESS, 失败返回错误码.
*/
int leda_feed_watchdog(const char *module_name, const char *thread_name, int count_down_seconds);
/*
* 获取设备id.
*
* product_key: 产品pk.
* device_name: 设备名称.
*
* 阻塞接口, 成功返回device_id, 失败返回小于0数值.
*/
dev_handle_t leda_get_device_id(const char *product_key, const char *device_name);
#ifdef __cplusplus /* If this is a C++ compiler, use C linkage */
}
#endif
#endif
Python版本
LedaModule 类
# 模块初始化
# @param moduleName[string] 驱动名称
#
# @return
#
def moduleInit(self, moduleName):
# 驱动释放
#
def moduleRelease(self):
# 注册设备并上线设备(设备默认注册后即上线)
#
#@param deviceName[string] 由设备特征值组成的唯一描述信息, 必须保证每个待接入设备名称不同.
#@param productKey[string]: 产品唯一描述信息, 由阿里提供, 在设备 tsl 里也可以查得到.
#@param productTsl[string]: 设备tsl, 由阿里提供描述规范, 描述了设备的能力
#@param param deviceCallBack[obj]: 设备回调方法
#
#return ledaSubDev[obj]
#
def deviceRegister(self, deviceName, productKey, productTsl, deviceCallBack):
# 喂狗
#
#@param thread_name 需要保活的线程名称.
#@param count_down_seconds 倒计时时间, -1表示停止保活, 单位:秒.
#
def feedDog(self, thread_name, count_down_seconds):
# 获取配置相关信息
#
#@param product_key[string] 如果为空，则默认获取lead module 的配置信息
#
#@return info[string] 输出信息内容
#
def getPdInfo(self, productKey = ''):
# 注册设备配置变更回调.
#
#@param callbackObj: 设备变更通知回调接口对象
#
def registerDeviceConfigCallback(self, callbackObj):
SubDevice类
# 上线设备, 设备只有上线后，才能被云端识别.
#
def online(self):
# 下线设备
#
def offline(self):
# 上报属性
#
#@param propertiesDict[dict]: 格式如下：
# {
# "propertyName1": xxx,
# "propertyName2": yyy,
# ...
# }
#
def reportProperties(self, propertiesDict):
# 上报事件
#
#param eventName[string] 事件名称
#@param eventDict[dict] 格式如下：
# {
# "eventArgs1":xxx,
# "eventArgs2":yyy,
# "eventArgs3":zzz
# ...
# }
#
def reportEvent(self, eventName, eventDict):
BaseDeviceCallback 类
# 设备服务调用
#
#@param name[string]: method name
#param input[dict]: , eg:
# {
# "args1": xxx,
# "args2": yyy
# ...
# }
#
#@return code[int]: 若获取成功则返回LEDA_ERROR_SUCCESS, 失败则返回错误码（参考错误码定义:ledaException.py）
#@return output[dict]: , eg:
{
"key1": xxx,
"key2": yyy,
...
}
#
def invokeService(self, name, input):
# 获取设备属性
#
#@parma input[list]: ,eg:[property1,property2 ...]
#
#@return code[int]: 若获取成功则返回LEDA_ERROR_SUCCESS, 失败则返回错误码（参考错误码定义:ledaException.py）
#@return output[dict]: , eg:
{
'property1':xxx,
'property2':yyy,
...
}
#
def getProperties(self, input):
# 设置设备属性
#
#@parma param input[dict]:, eg:
# {
# 'property1':xxx,
# 'property2':yyy,
# ...
# }
#
#@return code[int]: 若获取成功则返回LEDA_ERROR_SUCCESS, 失败则返回错误码（参考错误码定义:ledaException.py）
#@return output[dict]: 数据内容自定义，若无返回数据，则值空:{}
#
def setProperties(self, input):
LedaConfigCallback类
# 配置回调
#
#@param moduleName 驱动名称
#@param moduleConfig 配置信息
#
def deviceConfigCB(self, moduleName, moduleConfig):
错误码
#/*返回状态*/
LEDA_ERROR_SUCCESS = 0 # 执行成功
LEDA_ERROR_INVAILD_PARAM = -1 # 无效参数
LEDA_ERROR_FAILED = -3 # 执行失败
LEDA_ERROR_TIME_OUT = -4 # 超时
LEDA_ERROR_NOT_SUPPORT = -5 # 不支持
exception（异常处理）
class LedaException(Exception):
'''
base leda exception
'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''
Initialize the exception
:param value: the err code
:param msg: the err msg
'''
self.value = value
self.msg = msg
def __str__(self):
'''
return the exception message
:return str:
'''
return "Err: %s ErrCode: %s" % (str(self.msg), self.value)
__repr__ = __str__
class LedaParamsException(LedaException):
''' leda params error'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''Initialize the exception
:param value: the err code
:param msg: the err msg
'''
message = "[LedaParams] %s" % (str(msg))
LedaException.__init__(self, message, value)
class LedaRPCMethodException(LedaException):
''' leda rpc method error'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''Initialize the exception
:param value: the err code
:param msg: the err msg
'''
message = "[LedaRPCMethod] %s" % (str(msg))
LedaException.__init__(self, message, value)
class LedaBusHandleException(LedaException):
''' leda busHandle error'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''Initialize the exception
:param value: the err code
:param msg: the err msg
'''
message = "[LedaBusHandle] %s" % (str(msg))
LedaException.__init__(self, message, value)
class LedaFeedDogException(LedaException):
''' leda feed dog error'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''Initialize the exception
:param value: the err code
:param msg: the err msg
'''
message = "[LedaFeedDog] %s" % (str(msg))
LedaException.__init__(self, message, value)
class LedaCallBackException(LedaException):
''' leda call back error'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''Initialize the exception
:param value: the err code
:param msg: the err msg
'''
message = "[LedaCallBack] %s" % (str(msg))
LedaException.__init__(self, message, value)
class LedaReportPropertyException(LedaException):
''' leda report property error'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''Initialize the exception
:param value: the err code
:param msg: the err msg
'''
message = "[LedaReportProperty] %s" % (str(msg))
LedaException.__init__(self, message, value)
class LedaReportEventException(LedaException):
''' leda report event error'''
def __init__(self, msg = "", value = LEDA_ERROR_FAILED):
'''Initialize the exception
:param value: the err code
:param msg: the err msg
'''
message = "[LedaReportEvent] %s" % (str(msg))
LedaException.__init__(self, message, value)