@tslfe/tacos-sdk v2.0.3

@tslfe/tacos-sdk

支持 nodejs 、browser；支持自定义扩展 SDK 模块；支持拦截和处理网络请求

功能

扩展

开始

安装

npm install @tslfe/tacos-sdk --save
or
yarn add @tslfe/tacos-sdk -S

接入示例

一般通过@tslfe/tacos-sdk接入 tacos 平台需要三个步骤：

1. 通过 tacos 实例 ID 和对应的 signature 签名与平台建立互信连接（完成请求的 token 签名）
2. 建立连接后可创建对应功能的实例化对象，例如：空间或者设备
3. 通过实例化对象的方法，获取需要信息或者进行指令下发

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: 签名
• 返回值: 异步获取 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

• 示例：

1. 自定义 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 };
  }
});

2. 使用自定义的 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();
});