智汀家庭云-开发指南Golang： 插件模块

插件模块

• 当前所说的插件仅指设备类插件，插件为SA提供额外的设备发现和控制功能；
• 插件通过实现定义的grpc接口，以grpc服务的形式运行，提供接口给SA调用
• 插件同时需要http服务提供h5页面及静态文件

1. SA中插件的工作流程

1.1 插件部署流程

1. 插件开发者将开发好的插件服务编译成docker镜像提供给SA
2. SA根据插件的镜像地址判断本地是否已经拉取或更新
3. 用户安装插件后，SA根据镜像运行起容器，插件往注册中心注册服务
4. SA通过服务发现发现新的插件服务

1.2 插件使用流程

1. 用户在界面上发现设备时对所有插件服务调用Discover接口，插件根据实现的接口返回所发现的设备
2. 用户添加设备并标记设备对应的插件
3. 用户请求设备的H5地址，进去插件自定义页面
4. 通过交互发起自定义指令给SA，SA将指令转发给对应的插件服务

2. 接口

• 文件http服务 sdk提供了方便的方法进行静态文件挂载和自定义api接口实现

  package main
  
  import "github.com/zhiting-tech/smartassistant/pkg/plugin/sdk/server"
  
  func main() {
      ps := server.NewPluginServer("yeelight")
      ps.HtmlRouter.Static("", "./html")
  
      apiGroup := ps.Router.Group("/api/")
      apiGroup.GET("")
  }
  

• grpc服务， 通过实现protobuf定义的grpc接口来实现插件服务：

  syntax = "proto3";
  package proto;
  
  service Plugin {
      rpc Discover (empty) returns (stream device);
      rpc StateChange (empty) returns (stream state);
      rpc GetAttributes (GetAttributesReq) returns (GetAttributesResp);
      rpc SetAttributes (SetAttributesReq) returns (SetAttributesResp);
  }
  
  message ExecuteReq {
      string identity = 1;
      string cmd = 2;
      bytes data = 3;
  }
  message ExecuteResp {
      bool success = 1;
      string error = 2;
      bytes data = 3;
  }
  message GetAttributesReq {
      string identity = 1;
  }
  
  message GetAttributesResp {
      bool success = 1;
      string error = 2;
      repeated Instance instances = 3;
  }
  message Instance {
      string identity = 1;
      int32 instance_id = 2;
      bytes attributes = 3;
      string type = 4;
  }
  
  message SetAttributesReq {
      string identity = 1;
      bytes data = 2;
  }
  
  message SetAttributesResp {
      bool success = 1;
      string error = 2;
  }
  
  message Action {
      string identity = 1;
      int32 instance_id = 2;
      bytes attributes = 3;
  }
  
  message device {
      string identity = 1;
      string model = 2;
      string manufacturer = 3;
  }
  
  message empty {
  }
  
  message state {
      string identity = 1;
      int32 instance_id = 2;
      bytes attributes = 3;
  }
  

注：grpc接口是通用的定义，SDK对接口实现了封装，开发者使用SDK时不需要关心，仅需要实现设备类型即可。

3. sdk

为了方便开发者快速开发插件以及统一接口，我们提供sdk规范了接口以及预定义了设备模型，以下为sdk实现功能：

• 插件服务注册
• http服务
• grpc服务以及接口封装（包括设备属性获取、属性设置、消息通知等）
• 预定义模型

4. 设备模型设计

云对云接入时，需要对第三方云的命令进行解析，并通过SA对插件发起命令。

这就要求插件实现的命令必须要有统一的规范和标准，这样第三方就可以通过这个标准来控制SA的所有支持的设备。

同时也能方便SA更好的通过统一的接口以及命令来管理设备。

4.1 模型设计

SDK预定义设备类型以及属性，开发者通过引入设备类型实现相关功能。

SDK通过反射获取设备的所有属性，将属性与命令做好对应关系，这样可以使得无论设备是什么形态，都能有统一的接口以及命令进行控制。

4.1.1 插件模型定义

字段解释

• instance 实例
• attribute 属性
• val_type 值类型
• val 值

val_type

对于int型，属性可设置最小和最大值

模型

• light_bulb 灯

attribute	description	val_type	required
power	开关	string	true

• switch 开关

attribute	description	val_type	required
power	开关	string	true

• outlet 插座

attribute	description	val_type	required
power	开关	string	true

• info 设备详情

attribute	description	val_type	required
identity	id	string	true
model	型号	string	true
manufacturer	厂商	string	true
version	版本	string	true
name	名字	string	false

4.2 模型示例

操作某个属性时，根据属性的tag对命令中的值进行解析和校验 模型例子如下：

package plugin

import "github.com/zhiting-tech/smartassistant/pkg/plugin/sdk/instance"

type Device struct {
  Light instance.LightBulb
  Info0 instance.Info
  // 根据实际设备功能组合定义
}

func NewDevice() *Device {
  return &Device{
    Light: instance.NewLightBulb(),
    Info0: instance.NewInfo(),
  }
}

5. 示例项目

• demo-plugin