@tslfe/tacos-sdk
v4.0.0-2
Published
tacos os
Downloads
68
Readme
@tslfe/tacos-sdk
支持 nodejs 、browser;支持自定义扩展 SDK 模块;支持拦截和处理网络请求
功能
| 序号 | 功能 | 描述 | 状态 | | ---- | ---- | ------------------------------------------------------------------ | ---- | | 1 | 空间 | 空间相关的管理和双向联动,包括规则、计划、情景等 | 0% | | 2 | 设备 | 设备相关的管理和双向联动,包括指令下发、状态变更、设备状态可视化等 | 70% | | 3 | 模型 | 物模型管理 | 50% |
扩展
| 序号 | 扩展 | 状态 | | ---- | ----------------- | ---- | | 1 | 扩展已有 SDK 模块 | 支持 | | 2 | 自定义 SDK 模块 | 支持 | | 3 | 网络拦截 | 支持 | | 4 | websocket | 支持 |
开始
安装
npm install @tslfe/tacos-sdk --save
oryarn add @tslfe/tacos-sdk -S
接入示例
一般通过@tslfe/tacos-sdk
接入 tacos 平台需要三个步骤:
- 通过 tacos 实例 ID 和对应的 signature 签名与平台建立互信连接(完成请求的 token 签名)
- 建立连接后可创建对应功能的实例化对象,例如:空间或者设备
- 通过实例化对象的方法,获取需要信息或者进行指令下发
eg: 通过 Space 获取空间下的所有设备和其它信息
import Tacos, { Space } from "@tslfe/tacos-sdk";
// 第一步:通过connect与tacos建立连接
Tacos.connect({ token: "" }).then((tacos) => {
// 第二步:建立连接后创建sdk实例对象
let space = tacos.createInstance(Space, { spaceId: "<空间实例ID>" });
// 第三步:通过实例对象可获取和管理对应的空间
let devices = space.getDevices();
//...其它逻辑
// 下发设备指令 eg: 新风回风阀开度设定为50
space
.getDevice("<deviceId>")
.buildDeviceExecutor()
.then((exe) => {
exe.command["fresh_valve_in_degree_value"]({ fresh_valve_in_degree: 50 });
});
});
eg: 通过 Device 直接下发指令
import Tacos, { Device } from "@tslfe/tacos-sdk";
// 第一步:通过connect与tacos建立连接
Tacos.connect({ token: "<token>" }).then((tacos) => {
// 第二步:建立连接后创建sdk实例对象
let device = tacos.createInstance(Device, { deviceId: "<设备ID>" });
// 第三步:下发指令
device.buildDeviceExecutor().then((exe) => {
exe.command["fresh_valve_in_degree_value"]({ fresh_valve_in_degree: 50 });
});
});
API
全局
version
当前 sdk 的版本号
- 示例:
Tacos.version
configRequest
设置全局 ajax 请求的配置
- 方法:
configRequest(config: AxiosRequestConfig & Required<{ baseURL: string }>): void
- 参数:
- config: ajax 请求配置
- 返回值:
无
- 示例:
import Tacos from "@tslfe/tacos-sdk";
Tacos.configRequest({
baseURL: "http://127.0.0.1",
timeout: 10 * 1000
});
注:AxiosRequestConfig 更多参数 点击
configSocket
设置全局 websocket 的配置
- 方法:
configSocket(config: SocketConfig): void
- 参数:
- config: websocket 请求配置
- 返回值:
无
- 示例:
import Tacos from "@tslfe/tacos-sdk";
Tacos.configSocket({
reconnectTimeout: 10 * 1000
});
注:SocketConfig 更多参数如下
type SocketConfig = {
url: string;
protocols: string | string[];
pingTimeout: number;
pongTimeout: number;
reconnectTimeout: number;
pingMsg: any;
repeatLimit: null | number;
};
connect
与 TacOS 建立链接
- 方法:
connect(options: { host?: string; request?: RequestConfig; socket?: SocketConfig; token: string }):Promise<Tacos>
- 参数:
- options: 连接参数
- tacosId: tacos 实例 id
- signature: 签名
- options: 连接参数
- 返回值: 异步获取 Tacos 实例
- 示例:
import Tacos from "@tslfe/tacos-sdk";
Tacos.connect({ token: "", host: "" }).then((tacos) => {
// 连接后的逻辑
});
tacos 实例
interceptor
拦截器
- 方法:
interceptor<T extends keyof 'websocket' | 'ajax'>(type: T): SocketInterceptor | RequestInterceptor
- 参数:
- type: 指定拦截器类型 'websocket' 或 'ajax'
- 返回值:获取
SocketInterceptor 或 RequestInterceptor
的实例 - 示例:
import Tacos from "@tslfe/tacos-sdk";
import { AxiosRequestConfig } from "axios";
Tacos.connect({ token: "" }).then((tacos) => {
let interceptor = tacos.interceptor("ajax");
interceptor.request(
(config: AxiosRequestConfig) => {
// 业务逻辑
},
(error: Error) => {
// 业务逻辑
}
);
});
注:点击以下链接查看更多信息 SocketInterceptor 、RequestInterceptor
createInstance
创建 sdk 模块实例
- 方法:
createInstance<M extends (...args: any) => any, P>(sdk: M, props?: P): ReturnType<M>
- 参数:
- sdk: 定义的 sdk 模块
- props: sdk 所需的参数
- 返回值:sdk 模型实例
- 示例:
import Tacos, { Device } from "@tslfe/tacos-sdk";
import { AxiosRequestConfig } from "axios";
Tacos.connect({ token: "" }).then((tacos) => {
let device = tacos.createInstance(Device, { deviceId: "" });
// 其它逻辑
});
destroy
销毁当前 tacos 实例
- 方法:
destroy(): void
- 参数:
- 无
- 返回值:无
- 示例:
import Tacos, { Device } from "@tslfe/tacos-sdk";
import { AxiosRequestConfig } from "axios";
Tacos.connect({ token: "" }).then((tacos) => {
// 其它逻辑
tacos.destroy();
});
扩展
defineSDK
定义 SDK 模块, defineSDK 是一个高阶函数
- 方法:
defineSDK<P, S>(sdkOptions: TacosOptions<P, S>): (context: Context, props?: P) => TacosSDK & S
- 参数:
- sdkOptions: SDK 模块逻辑代码
- 返回值:SDK 的构造器
- 示例:
import { defineSDK } from "@tslfe/tacos-sdk";
export default defineSDK({
setup() {
let getVersion = function () {
return "0.0.1";
};
return {
name: "自定义的SDK模块",
getVersion
};
}
});
定义 SDK 模块更多详情,点击查看
defineApi
定义 ajax 网络请求模块
- 方法:
defindAPI<T extends Record<string, Function>>(api: Api<T>): (request: Request)=>T & ThisType<Request>
- 参数:
- api: 网络请求逻辑代码
- 返回值:API 的构造器
- 实例:
import { defineApi } from "@tslfe/tacos-sdk";
export default defineApi({
getDeviceModel(deviceId: string) {
return this.get(`/device/model/${deviceId}`);
}
});
SDK 模块
space
空间模块
getSubSpaces
获取子空间
- 方法:
getSubSpaces()
- 参数
- 无
- 返回值:当前空间的子空间实例
- 示例
let subSpaces = space.getSubSpaces();
getDevices
获取空间下的所有设备列表
- 方法:
getDevices(type?: DeviceType, status?: DeviceStatus): Device[]
- 参数
- type?: 设备类型
- status?: 设备状态
- 返回值:空间下的设备列表实例
- 示例
let devices = space.getDevices();
getDevice
获取空间下的所有设备
- 参数
- deviceId: string (设备 ID)
- 返回值:
Device
- 示例
let devices = space.getDevice("<deviceId>");
getScenes
获取空间下的场景
- 参数
- 无
- 返回值:
Device
- 示例
let scenes = space.getScenes();
文档未完,待补充。。。
Device
设备模块
getModel
获取设备的产品物模型
- 参数
- 无
- 返回值:
Model
- 示例
let model = device.getModel();
getStates
主动查询获取设备状态
- 参数
- refresh: boolean = false
- 返回值:
Model
- 示例
let states = device.getStates(true);
execFunction
直接执行设备的功能
- 参数
- func: string
- params: Record<string, any>
- 返回值:
boolean
- 示例
let bool = device.execFunction("<funcName>", "<params>");
execFunctions
批量执行设备的功能
- 参数
- funcs: Array<{func: string, params: Record<string, any>}>
- 返回值:
boolean
- 示例
let bool = device.execFunctions([{ func: `<funcName>`, params: "<params>" }]);
addStateListener
监听设备变化,监听设备事件
- 参数
- callback: (ds?: DeviceState) => void
- 返回值:
boolean
- 示例
device.addStateListener((deviceState) => {
// 其它业务逻辑...
});
buildDeviceExecutor
创建设备快捷的控制器
- 参数
- 无
- 返回值:
Promise<{command: {}, functions: {}}>
- 示例
import { TacosResponse } from "./request";
device.buildDeviceExecutor().then((exe) => {
exe.command["fresh_valve_in_degree_value"](50).then((res: TacosResponse) => {
// 其它逻辑...
});
});
文档未完,待补充。。。
Model
物模型模块
exportModel
导出物模型结构
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getFunctions
获取功能集
- 参数
- 无
- 返回值:
- 示例
// 待完善...
addFunction
增加功能
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getFunction
获取单个功能
- 参数
- 无
- 返回值:
- 示例
// 待完善...
updateFunction
更新功能
- 参数
- 无
- 返回值:
- 示例
// 待完善...
deleteFunction
删除功能
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getCommands
获取指令集
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getCommand
查询指令
- 参数
- 无
- 返回值:
- 示例
// 待完善...
addCommand
新增指令
- 参数
- 无
- 返回值:
- 示例
// 待完善...
updateCommand
修改指令
- 参数
- 无
- 返回值:
- 示例
// 待完善...
deleteCommand
删除指令
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getProperties
获取属性集
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getProperty
获取属性
- 参数
- 无
- 返回值:
- 示例
// 待完善...
addProperty
新增属性
- 参数
- 无
- 返回值:
- 示例
// 待完善...
updateProperty
修改属性
- 参数
- 无
- 返回值:
- 示例
// 待完善...
deleteProperty
删除属性
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getEvents
获取事件集
- 参数
- 无
- 返回值:
- 示例
// 待完善...
getEvent
获取单个事件
- 参数
- 无
- 返回值:
- 示例
// 待完善...
addEvent
新增事件
- 参数
- 无
- 返回值:
- 示例
// 待完善...
updateEvent
修改事件
- 参数
- 无
- 返回值:
- 示例
// 待完善...
deleteEvent
删除事件
- 参数
- 无
- 返回值:
- 示例
// 待完善...
扩展 SDK 模块
通过@tslfe/tacos-sdk
提供的方法可封装更上层的 SDK 模块,或者封装自己的 IOT 库。
defineSDK
参数
- sdkOptions: TacosOptions
返回值:
(context: Context, props?: P) => TacosSDK
示例:
- 自定义 SDK 模块
light.ts
import { defineSDK, Device, Context } from "@tslfe/tacos-sdk";
export default defineSDK({
/**
* 参数说明
* @param props 当前模块需要的入参,需实例化时传入(数据类型根据需要自定定义)
* @param context 上下文,实例化时自动注入
* @param onDestroy 销毁的生命周期,实例化时自动注入
*/
setup({ props, context }: { props: any; context: Context }, { onDestroy }) {
// 实例化device的deviceId,可定义在props中通过外部传入
let device = this.createInstace(Device, { deviceId: props.id });
let turnOn = function () {
return device.buildDeviceExecutor().then((exe) => {
exe.command["light_open"]();
});
};
let turnOff = function () {
return device.buildDeviceExecutor().then((exe) => {
exe.command["light_close"]();
});
};
return { turnOn, turnOff };
}
});
- 使用自定义的 SDK 模块
import Tacos from "@tslfe/tacos-sdk";
import Light from "./light";
// 第一步:通过connect与tacos建立连接
Tacos.connect({ token: "" }).then((tacos) => {
// 第二步:建立连接后创建灯的实例对象
let device = tacos.createInstance(Light, { id: "<设备ID>" });
// 第三步:设备控制
// 开灯
device.turnOn();
// 关灯
device.turnOff();
});