device

README

Go Device Service SDK

Overview

This repository is a set of Go packages which can be used to build a Go-based EdgeX Foundry Device Service.

Usage

Developers could make their own Device Service by implementing the ProtocolDriver interface for the specific IoT protocol and main function to start the Device Service. To implement the main function, the startup package could be optional leveraged, or developers could write the customized bootstrap code by themselves. Please see the build-in Simple Device Service as an example.

Float value encodeing

In EdgeX, float value has two kinds of encoding, Base64, and eNotation.

When EdgeX is given (or returns) a float32 or float64 value as a string, the format of the string is by default a base64 encoded little-endian of the float32 or float64 value, but the “floatEncoding” attribute relating to the value may instead specify “eNotation” in which case the representation is a decimal with exponent (eg “1.234e-5”)

https://docs.google.com/document/d/1aMIQ0kb46VE5eeCpDlaTg8PP29-DBSBTlgeWrv6LuYk/edit

base64

The SDK should convert the float value to little-endian binary and then encode the binary as base64 string. Currently, C SDK converts float value to little-endian binary. GO SDK encodes convert float value to big-endian binary because SDK spec changed in fuji release, we will modify GO SDK to make the behavior consistent in the future.

Usage:

-
  name: "Temperature"
  description: "Temperature value"
  properties:
    value:
      { type: "FLOAT64", readWrite: "RW", floatEncoding: "Base64"}
    units:
      { type: "String", readWrite: "R", defaultValue: "degrees Celsius"}

eNoation

The SDK should convert the float value to string with eNotaion representation.

Usage:

-
  name: "Temperature"
  description: "Temperature value"
  properties:
    value:
      { type: "FLOAT64", readWrite: "RW", floatEncoding: "eNotation"}
    units:
      { type: "String", readWrite: "R", defaultValue: "degrees Celsius"}

Community

• Chat: https://edgexfoundry.slack.com
• Mailing lists: https://lists.edgexfoundry.org/mailman/listinfo

License

Apache-2.0

Documentation

Overview

This package provides a basic EdgeX Foundry device service implementation meant to be embedded in an application, similar in approach to the builtin net/http package.

Index

• Variables
• func DriverConfigs() map[string]string
• func SetOverwriteConfig(oc bool)
• type Service
  • func NewService(serviceName string, serviceVersion string, confProfile string, confDir string, ...) (*Service, error)
  • func RunningService() *Service
  • func (s *Service) AddDevice(device contract.Device) (id string, err error)
  • func (s *Service) AddDeviceProfile(profile contract.DeviceProfile) (id string, err error)
  • func (s *Service) AddProvisionWatcher(watcher contract.ProvisionWatcher) (id string, err error)
  • func (s *Service) AddRoute(route string, handler func(http.ResponseWriter, *http.Request), ...) error
  • func (s *Service) AsyncReadings() bool
  • func (s *Service) DeviceProfiles() []contract.DeviceProfile
  • func (*Service) DeviceResource(deviceName string, deviceResource string, method string) (contract.DeviceResource, bool)
  • func (s *Service) Devices() []contract.Device
  • func (s *Service) Discovery() dsModels.ProtocolDiscovery
  • func (s *Service) GetDeviceByName(name string) (contract.Device, error)
  • func (s *Service) GetProvisionWatcherByName(name string) (contract.ProvisionWatcher, error)
  • func (s *Service) Name() string
  • func (s *Service) ProvisionWatchers() []contract.ProvisionWatcher
  • func (s *Service) RemoveDevice(id string) error
  • func (s *Service) RemoveDeviceByName(name string) error
  • func (s *Service) RemoveDeviceProfile(id string) error
  • func (*Service) RemoveDeviceProfileByName(name string) error
  • func (s *Service) RemoveProvisionWatcher(id string) error
  • func (*Service) ResourceOperation(deviceName string, deviceResource string, method string) (contract.ResourceOperation, bool)
  • func (s *Service) Start(errChan chan error) (err error)
  • func (s *Service) Stop(force bool) error
  • func (s *Service) UpdateDevice(device contract.Device) error
  • func (*Service) UpdateDeviceProfile(profile contract.DeviceProfile) error
  • func (s *Service) UpdateProvisionWatcher(watcher contract.ProvisionWatcher) error
  • func (s *Service) Version() string

Variables

var Version string = "to be replaced by makefile"

Global version for device-sdk-go

Functions

func DriverConfigs

func DriverConfigs() map[string]string

DriverConfigs retrieves the driver specific configuration

func SetOverwriteConfig

func SetOverwriteConfig(oc bool)

SetOverwriteConfig sets whether or not configuration will be unconditionally loaded from file to the registry. NOTE this will be removed in the next release and made a parameter to NewService

Types

type Service

type Service struct {
	// contains filtered or unexported fields
}

A Service listens for requests and routes them to the right command

func NewService

func NewService(serviceName string, serviceVersion string, confProfile string, confDir string, useRegistry string, proto dsModels.ProtocolDriver) (*Service, error)

NewService creates a new Device Service instance with the given version number, config profile, config directory, whether to use registry, and Driver, which cannot be nil. Note - this function is a singleton, if called more than once, it will always return an error.

func RunningService

func RunningService() *Service

RunningService returns the Service instance which is running

func (*Service) AddDevice

func (s *Service) AddDevice(device contract.Device) (id string, err error)

AddDevice adds a new Device to the Device Service and Core Metadata Returns new Device id or non-nil error.

func (*Service) AddDeviceProfile

func (s *Service) AddDeviceProfile(profile contract.DeviceProfile) (id string, err error)

AddDeviceProfile adds a new DeviceProfile to the Device Service and Core Metadata Returns new DeviceProfile id or non-nil error.

func (*Service) AddProvisionWatcher

func (s *Service) AddProvisionWatcher(watcher contract.ProvisionWatcher) (id string, err error)

AddProvisionWatcher adds a new Watcher to the cache and Core Metadata Returns new Watcher id or non-nil error.

func (*Service) AddRoute

func (s *Service) AddRoute(route string, handler func(http.ResponseWriter, *http.Request), methods ...string) error

AddRoute allows leveraging the existing internal webserver to add routes specific to Device Service.

func (*Service) AsyncReadings

func (s *Service) AsyncReadings() bool

AsyncReadings returns a bool value to indicate whether the asynchronous reading is enabled.

func (*Service) DeviceProfiles

func (s *Service) DeviceProfiles() []contract.DeviceProfile

DeviceProfiles return all managed DeviceProfiles from cache

func (*Service) DeviceResource

func (*Service) DeviceResource(deviceName string, deviceResource string, method string) (contract.DeviceResource, bool)

DeviceResource retrieves the specific DeviceResource instance from cache according to the Device name and Device Resource name

func (*Service) Devices

func (s *Service) Devices() []contract.Device

Devices return all managed Devices from cache

func (*Service) Discovery

func (s *Service) Discovery() dsModels.ProtocolDiscovery

func (*Service) GetDeviceByName

func (s *Service) GetDeviceByName(name string) (contract.Device, error)

GetDeviceByName returns the Device by its name if it exists in the cache, or returns an error.

func (*Service) GetProvisionWatcherByName

func (s *Service) GetProvisionWatcherByName(name string) (contract.ProvisionWatcher, error)

GetProvisionWatcherByName returns the Watcher by its name if it exists in the cache, or returns an error.

func (*Service) Name

func (s *Service) Name() string

Name returns the name of this Device Service

func (*Service) ProvisionWatchers

func (s *Service) ProvisionWatchers() []contract.ProvisionWatcher

ProvisionWatchers return all managed Watchers from cache

func (*Service) RemoveDevice

func (s *Service) RemoveDevice(id string) error

RemoveDevice removes the specified Device by id from the cache and ensures that the instance in Core Metadata is also removed.

func (*Service) RemoveDeviceByName

func (s *Service) RemoveDeviceByName(name string) error

RemoveDevice removes the specified Device by name from the cache and ensures that the instance in Core Metadata is also removed.

func (*Service) RemoveDeviceProfile

func (s *Service) RemoveDeviceProfile(id string) error

RemoveDeviceProfile removes the specified DeviceProfile by id from the cache and ensures that the instance in Core Metadata is also removed.

func (*Service) RemoveDeviceProfileByName

func (*Service) RemoveDeviceProfileByName(name string) error

RemoveDeviceProfileByName removes the specified DeviceProfile by name from the cache and ensures that the instance in Core Metadata is also removed.

func (*Service) RemoveProvisionWatcher

func (s *Service) RemoveProvisionWatcher(id string) error

RemoveProvisionWatcher removes the specified Watcher by id from the cache and ensures that the instance in Core Metadata is also removed.

func (*Service) ResourceOperation

func (*Service) ResourceOperation(deviceName string, deviceResource string, method string) (contract.ResourceOperation, bool)

ResourceOperation retrieves the first matched ResourceOpereation instance from cache according to the Device name, Device Resource name, and the method (get or set).

func (*Service) Start

func (s *Service) Start(errChan chan error) (err error)

Start the Device Service.

func (*Service) Stop

func (s *Service) Stop(force bool) error

Stop shuts down the Service

func (*Service) UpdateDevice

func (s *Service) UpdateDevice(device contract.Device) error

UpdateDevice updates the Device in the cache and ensures that the copy in Core Metadata is also updated.

func (*Service) UpdateDeviceProfile

func (*Service) UpdateDeviceProfile(profile contract.DeviceProfile) error

UpdateDeviceProfile updates the DeviceProfile in the cache and ensures that the copy in Core Metadata is also updated.

func (*Service) UpdateProvisionWatcher

func (s *Service) UpdateProvisionWatcher(watcher contract.ProvisionWatcher) error

UpdateProvisionWatcher updates the Watcher in the cache and ensures that the copy in Core Metadata is also updated.

func (*Service) Version

func (s *Service) Version() string

Version returns the version number of this Device Service