Edge-X 设备服务开发

一，设备驱动(device driver) 核心接口

protocoldriver.go

/ ProtocolDriver is a low-level device-specific interface used by
// by other components of an EdgeX Device Service to interact with
// a specific class of devices.
type ProtocolDriver interface {
    // Initialize performs protocol-specific initialization for the device
    // service. The given *AsyncValues channel can be used to push asynchronous
    // events and readings to Core Data.
    Initialize(lc logger.LoggingClient, asyncCh chan<- *AsyncValues) error

    // HandleReadCommands passes a slice of CommandRequest struct each representing
    // a ResourceOperation for a specific device resource.
    HandleReadCommands(deviceName string, protocols map[string]contract.ProtocolProperties, reqs []CommandRequest) ([]*CommandValue, error)

    // HandleWriteCommands passes a slice of CommandRequest struct each representing
    // a ResourceOperation for a specific device resource.
    // Since the commands are actuation commands, params provide parameters for the individual
    // command.
    HandleWriteCommands(deviceName string, protocols map[string]contract.ProtocolProperties, reqs []CommandRequest, params []*CommandValue) error

    // Stop instructs the protocol-specific DS code to shutdown gracefully, or
    // if the force parameter is 'true', immediately. The driver is responsible
    // for closing any in-use channels, including the channel used to send async
    // readings (if supported).
    Stop(force bool) error

    // AddDevice is a callback function that is invoked
    // when a new Device associated with this Device Service is added
    AddDevice(deviceName string, protocols map[string]contract.ProtocolProperties, adminState contract.AdminState) error

    // UpdateDevice is a callback function that is invoked
    // when a Device associated with this Device Service is updated
    UpdateDevice(deviceName string, protocols map[string]contract.ProtocolProperties, adminState contract.AdminState) error

    // RemoveDevice is a callback function that is invoked
    // when a Device associated with this Device Service is removed
    RemoveDevice(deviceName string, protocols map[string]contract.ProtocolProperties) error
}

1、初始化函数：

// AsyncValues : 异步通道，用来做异步事件发送

Initialize(lc logger.LoggingClient, asyncCh chan<- *AsyncValues) error

2、写函数

HandleWriteCommands(deviceName string, protocols map[string]contract.ProtocolProperties, reqs []CommandRequest, params []*CommandValue) error

入参：

deviceName string: 设备名

protocols map[string]contract.ProtocolProperties：设备的连接信息

reqs []CommandRequest：指令请求，可以是多条

params []*CommandValue：指令值，可以是多个返回值，与reqs的数量通常是对应的

在这里有一个设计：在HandleWriteCommands时，reqs 与params 是分开的，本意是分别代别请求的资源和参数，其中的结构体成员有重复；

在另外一个工程：github.com/edgexfoundry/go-mod-core-contracts/models/device.go

// ProtocolProperties contains the device connection information in key/value pair
type ProtocolProperties map[string]string

// CommandRequest is the struct for requesting a command to ProtocolDrivers
type CommandRequest struct {
    // DeviceResourceName is the name of Device Resource for this command
    // 例如一个设备的功能项（资源项名称），例如可以是属性的名字
    DeviceResourceName string
    // Attributes is a key/value map to represent the attributes of the Device Resource
    // 这个看起来是非必须的，资源名可以唯一约束时，Attributes的补充看起来非必须
    Attributes map[string]string
    // Type is the data type of the Device Resource
    Type ValueType
}

// CommandValue is the struct to represent the reading value of a Get command coming
// from ProtocolDrivers or the parameter of a Put command sending to ProtocolDrivers.
type CommandValue struct {
    // DeviceResourceName is the name of Device Resource for this command
    DeviceResourceName string
    // Origin is an int64 value which indicates the time the reading
    // contained in the CommandValue was read by the ProtocolDriver
    // instance.
    // 当前值生成的时间
    Origin int64
    // Type is a ValueType value which indicates what type of
    // value was returned from the ProtocolDriver instance in
    // response to HandleCommand being called to handle a single
    // ResourceOperation.
    // 当前返回值的类型，指示从后续的那个结构体中去取值（NumericValue，stringValue，BinValue）
    Type ValueType
    // NumericValue is a byte slice with a maximum capacity of
    // 64 bytes, used to hold a numeric value returned by a
    // ProtocolDriver instance. The value can be converted to
    // its native type by referring to the the value of ResType.
    NumericValue []byte
    // stringValue is a string value returned as a value by a ProtocolDriver instance.
    stringValue string
    // BinValue is a CBOR encoded binary value with a maximum
    // capacity of 1MB, used to hold binary values returned
    // by a ProtocolDriver instance. Its decoded value is externally accessed
    // using BinaryValue() method
    BinValue []byte
}

3、读函数

// HandleReadCommands passes a slice of CommandRequest struct each representing
    // a ResourceOperation for a specific device resource.
    HandleReadCommands(deviceName string, protocols map[string]contract.ProtocolProperties, reqs []CommandRequest) ([]*CommandValue, error)

4、停止函数

// Stop instructs the protocol-specific DS code to shutdown gracefully, or
    // if the force parameter is 'true', immediately. The driver is responsible
    // for closing any in-use channels, including the channel used to send async
    // readings (if supported).
    Stop(force bool) error

5、添加设备回调函数

    // AddDevice is a callback function that is invoked
    // when a new Device associated with this Device Service is added
    AddDevice(deviceName string, protocols map[string]contract.ProtocolProperties, adminState contract.AdminState) error

6、更新设备回调函数

// UpdateDevice is a callback function that is invoked
    // when a Device associated with this Device Service is updated
    UpdateDevice(deviceName string, protocols map[string]contract.ProtocolProperties, adminState contract.AdminState) error

7、移除设备回调函数

// RemoveDevice is a callback function that is invoked
    // when a Device associated with this Device Service is removed
    RemoveDevice(deviceName string, protocols map[string]contract.ProtocolProperties) error