Merge branch 'master' into master

docs_src/design/legacy-requirements/README.md

@@ -1 +1,8 @@
 # Legacy Requirements
+
+| Name/Link                                          | Short Description                            |
+| -------------------------------------------------- | -------------------------------------------- |
+| [Device Service](device-service.md)                | Device Service SDK required functionality    |
+|                                                    |                                              |
+|                                                    |                                              |
+

docs_src/design/legacy-requirements/device-service.md

@@ -0,0 +1,161 @@
+# Device SDK Required Functionality
+
+## Overview
+
+This document sets out the required functionality of a Device SDK other
+than the implementation of its REST API (see [ADR 0011](../adr/device-service/0011-DeviceService-Rest-API.md))
+and the Dynamic Discovery mechanism (see [Discovery](../legacy-design/device-service/discovery.md)).
+
+This functionality is categorised into three areas - actions required at
+startup, configuration options to be supported, and support for push-style
+event generation.
+
+## Startup
+
+When the device service is started, in addition to any actions required to
+support functionality defined elsewhere, the SDK must:
+
+* Manage the device service's registration in metadata
+* Provide initialization information to the protocol-specific implementation
+
+### Registration
+
+The core-metadata service maintains an extent of device service registrations
+so that it may route requests relating to particular devices to the correct
+device service. The SDK should create (on first run) or update its record
+appropriately.
+Device service registrations contain the following fields:
+
+* `Name` - the name of the device service
+* `Description` - an optional brief description of the service
+* `Labels` - optional string labels
+* `BaseAddress` - URL of the base of the service's REST API
+
+The default device service `Name` is to be hardcoded into every device service
+implementation. A suffix may be added to this name at runtime by means of
+commandline option or environment variable. Service names must be unique in a
+particular EdgeX instance; the suffix mechanism allows for running multiple
+instances of a given device service.
+
+The `Description` and `Labels` are configured in the `[Service]` section of the
+device service configuration.
+
+`BaseAddress` may be constructed using the `[Service]/Host` and `[Service]/Port`
+entries in the device service configuration.
+
+### Initialization
+
+During startup the SDK must supply to the implementation that part of the
+service configuration which is specific to the implementation. This
+configuration is held in the `Driver` section of the configuration file or
+registry.
+
+The SDK must also supply a logging facility at this stage. This facility should
+by default emit logs locally (configurable to file or to stdout) but instead
+should use the optional logging service if the configuration element
+`Logging/EnableRemote` is set `true`. *Note: the logging service is deprecated
+and support for it will be removed in EdgeX v2.0*
+
+The implementation on receipt of its configuration should perform any
+necessary initialization of its own. It may return an error in the event of
+unrecoverable problems, this should cause the service startup itself to fail.
+
+## Configuration
+
+Configuration should be supported by the SDK, in accordance with [ADR 0005](../adr/0005-Service-Self-Config.md)
+
+### Commandline processing
+
+The SDK should handle commandline processing on behalf of the device service.
+In addition to the common EdgeX service options, the `--instance` / `-i` flag
+should be supported. This specifies a suffix to append to the device service
+name.
+
+### Environment variables
+
+The SDK should also handle environment variables. In addition to the common
+EdgeX variables, `EDGEX_INSTANCE_NAME` should if set override the `--instance`
+setting.
+
+### Configuration file and Registry
+
+The SDK should use (or for non-Go implementations, re-implement) the standard
+mechanisms for obtaining configuration from a file or registry.
+
+The configuration parameters to be supported are:
+
+#### Service section
+
+Option | Type | Notes
+:--- | :--- | :---
+Host | String | This is the hostname to use when registering the service in core-metadata. As such it is used by other services to connect to the device service, and therefore must be resolvable by other services in the EdgeX deployment.
+Port | Int | Port on which to accept the device service's REST API. The assigned port for experimental / in-development device services is 49999.
+Timeout | Int | Time (in milliseconds) to wait between attempts to contact core-data and core-metadata when starting up.
+ConnectRetries | Int | Number of times to attempt to contact core-data and core-metadata when starting up.
+StartupMsg | String | Message to log on successful startup.
+CheckInterval | String | The checking interval to request if registering with Consul. Consul will ping the service at this interval to monitor its liveliness.
+ServerBindAddr | String | The interface on which the service's REST server should listen. By default the server is to listen on the interface to which the `Host` option resolves. A value of `0.0.0.0` means listen on all available interfaces.
+
+#### Clients section
+
+Defines the endpoints for other microservices in an EdgeX system.
+Not required when using Registry.
+
+##### Data
+Option | Type | Notes
+:--- | :--- | :---
+Host | String | Hostname on which to contact the core-data service.
+Port | Int | Port on which to contact the core-data service.
+
+##### Metadata
+
+Option | Type | Notes
+:--- | :--- | :---
+Host | String | Hostname on which to contact the core-metadata service.
+Port | Int | Port on which to contact the core-metadata service.
+
+#### Device section
+
+Option | Type | Notes
+:--- | :--- | :---
+DataTransform | Bool | For enabling/disabling transformations on data between the device and EdgeX. Defaults to true (enabled).
+Discovery/Enabled | Bool | For enabling/disabling device discovery. Defaults to true (enabled).
+Discovery/Interval | Int | Time between automatic discovery runs, in seconds. Defaults to zero (do not run discovery automatically).
+MaxCmdOps | Int | Defines the maximum number of resource operations that can be sent to the driver in a single command.
+MaxCmdResultLen | Int | Maximum string length for command results returned from the driver.
+UpdateLastConnected | Bool | If true, update the LastConnected attribute of a device whenever it is successfully accessed (read or write). Defaults to false.
+
+#### Logging section
+
+Option | Type | Notes
+:--- | :--- | :---
+LogLevel | String | Sets the logging level. Available settings in order of increasing severity are: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`.
+
+#### Driver section
+
+This section is for options specific to the protocol driver. Any configuration specified here will be passed to the driver implementation during initialization.
+
+## Push Events
+
+The SDK should implement methods for generating Events other than on
+receipt of device GET requests. The AutoEvent mechanism provides for
+generating Events at fixed intervals. The asynchronous event queue
+enables the device service to generate events at arbitrary times,
+according to implementation-specific logic.
+
+### AutoEvents
+
+Each device may have as part of its definition in Metadata a number of `AutoEvents` associated with it. An `AutoEvent` has the following fields:
+
+* **resource**: the name of a deviceResource or deviceCommand indicating what to read.
+* **frequency**: a string indicating the time to wait between reading events, expressed
+as an integer followed by units of ms, s, m or h.
+* **onchange**: a boolean: if set to true, only generate new events if one or more of the
+contained readings has changed since the last event.
+
+The device SDK should schedule device readings from the implementation according to these `AutoEvent` defininitions. It should use the same logic as it would if the readings were being requested via REST.
+
+### Asynchronous Event Queue
+
+The SDK should provide a mechanism whereby the implementation may submit device readings at any time without blocking. This may be done in a manner appropriate to the implementation language, eg the Go SDK provides a channel on which readings may be pushed, the C SDK provides a function which submits readings to a workqueue.
+

docs_src/examples/AppServiceExamples.md

@@ -1,7 +1,7 @@
 # App Service Examples
 
 The following is a list of examples we currently have available that demonstrate various ways that the Application Functions SDK can be used. All of the examples
-can be found in [https://github.com/edgexfoundry-holding/app-service-examples](https://github.com/edgexfoundry-holding/app-service-examples). They focus on how to leverage various built in
+can be found in [https://github.com/edgexfoundry/edgex-examples/tree/master/application-services](https://github.com/edgexfoundry/edgex-examples/tree/master/application-services). They focus on how to leverage various built in
 provided functions as mentioned above as well as how to write your own in the case that the SDK does not provide what is needed.
 
 | Example Name | Description |

docs_src/examples/LinuxTutorial/LinuxTutorial.md

@@ -0,0 +1,24 @@
+# EdgeX Foundry Hands On Tutorial
+
+Provided by Jonas Werner, Cloud Solutions Architect, CTO, Dell Technologies
+
+## Download
+
+**[Tutorial (in PDF format)](EdgeX-Foundry-tutorial-ver1.0.pdf)**
+
+## Scope and Format
+This is meant to be a beginners guide to EdgeX Foundry it assumes nothing but some basic Linux command line experience. While the level of detail is aimed to support new Linux users, the content will be applicable also to experienced users who wish to get into open source IoT and perhaps who want to learn more about technologies such as docker-compose, etc.
+
+## Topics Covered
+
+
+- Installation of EdgeX Foundry
+- Starting / stopping micro services
+- How to add / enable services
+- Interacting with EdgeX using Postman, cURL and Python
+- Creating devices (sources of sensor data)
+- Sending data to EdgeX using REST
+- Exporting a stream of data using MQTT
+- How to issue commands from EdgeX to devices
+- Creating rules
+- Debug flags and container logs

docs_src/general/ContainerNames.md

@@ -0,0 +1,43 @@
+# EdgeX Container Names
+The following table provides the list of the default EdgeX Docker image names to the Docker container name and Docker Compose names.
+
+=== "Core"
+    |Docker image name|Docker container name|Docker Compose service name|
+    |---|---|---|
+    |docker-core-data-go|edgex-core-data|data|
+    |docker-core-metadata-go|edgex-core-metadata|metadata|
+    |docker-core-command-go|edgex-core-command|command|
+=== "Supporting"
+    |Docker image name|Docker container name|Docker Compose service name|
+    |---|---|---|
+    |docker-support-notifications-go|edgex-support-notifications|notifications|
+    |docker-support-logging-go|edgex-support-logging|logging|
+    |docker-support-scheduler-go|edgex-support-scheduler|scheduler|
+=== "Application & Analytics"
+    |Docker image name|Docker container name|Docker Compose service name|
+    |---|---|---|
+    |docker-app-service-configurable|edgex-app-service-configurable-rules|app-service-rules|
+    |emqx/kuiper|edgex-kuiper|rulesengine|
+=== "Device"
+    |Docker image name|Docker container name|Docker Compose service name|
+    |---|---|---|
+    |docker-device-virtual-go|edgex-device-virtual|device-virtual|
+    |docker-device-random-go|edgex-device-random|device-random|
+    |docker-device-mqtt-go|edgex-device-mqtt|device-mqtt|
+    |docker-device-rest-go|edgex-device-rest|device-rest|
+    |docker-device-modbus-go|edgex-device-modbus|device-modbus|
+    |docker-device-snmp-go|edgex-device-snmp|device-snmp|
+=== "Security"
+    |Docker image name|Docker container name|Docker Compose service name|
+    |---|---|---|
+    |vault|edgex-vault|vault|
+    |postgress|kong-db|kong-db|
+    |kong|kong|kong|
+    |docker-edgex-security-proxy-setup-go|edgex-proxy|edgex-proxy|
+=== "Miscellaneous"
+    |Docker image name|Docker container name|Docker Compose service name|
+    |---|---|---|
+    |docker-edgex-consul|edgex-core-consul|consul|
+    |mongo|edgex-mongo|mongo|
+    |redis|edgex-redis|redis|
+    |docker-sys-mgmt-agent-go|edgex-sys-mgmt-agent|system|

docs_src/general/Definitions.md

@@ -1,15 +1,25 @@
 # Definitions
 The following glossary provides terms used in EdgeX Foundry.  The definition are based on how EdgeX and its community use the term versus any strict technical or industry definition.
 
+## Actuate
+To cause a machine or device to operate.  In EdgeX terms, to command a device or sensor under management of EdgeX to do something (example: stop a motor) or to reconfigure itself (example: set a thermostat's cooling point).
+
 ## Brownfield and Greenfield
 Brownfield refers to older legacy equipment (nodes, devices, sensors) in an edge/IoT deployment, which typically uses older protocols.  Greenfield refers to, typically, new equipment with modern protocols.
 
 ## Containerized
-EdgeX micro services and infrastrucutre (i.e. databases, registry, etc.) are built as executable programs, put into Docker images, and made available via Docker Hub (and Nexus repository for nightly builds).  A service (or infrastructure element) that is available in Docker Hub (or Nexus) is said to be containerized.  Docker images can be quickly downloaded and new Docker containers created from the images.
+EdgeX micro services and infrastructure (i.e. databases, registry, etc.) are built as executable programs, put into Docker images, and made available via Docker Hub (and Nexus repository for nightly builds).  A service (or infrastructure element) that is available in Docker Hub (or Nexus) is said to be containerized.  Docker images can be quickly downloaded and new Docker containers created from the images.
 
 ## Contributor/Developer
 If you want to change, add to or at least build the existing EdgeX code base, then you are a "Developer". "Contributors" are developers that further wish to contribute their code back into the EdgeX open source effort.
 
+## Created time stamp
+The Created time stamp is the time the data was created in the database and is unchangeable. The Origin time stamp is the time the data is created on the device, device services, sensor, or object that collected the data before the data was sent to EdgeX Foundry and the database.
+
+Usually, the Origin and Created time stamps are the same, or very close to being the same. On occasion the sensor may be a long way from the gateway or even in a different time zone, and the Origin and Created time stamps may be quite different.
+
+If persistence is disable in core-data, the time stamp will default to 0.
+
 ## Device
 In EdgeX parlance, "device" is used to refer to a sensor, actuator, or IoT "thing".  A sensor generally collects information from the physical world - like a temperature or vibration sensor.  Actuators are machines that can be told to do something.  Actuators move or otherwise control a mechanism or system - like a value on a pump.  While there may be some technical differences, for the purposes of EdgeX documentation, device will refer to a sensor, actuator or "thing".
 
@@ -42,9 +52,25 @@ Benefits of micro service architectures include:
 - Allow services to be distributed across host compute platforms - allowing better utilization of available compute resources
 - Allow for more scalable solutions by adding copies of services when needed
 
+## Origin time stamp
+The Origin time stamp is the time the data is created on the device, device services, sensor, or object that collected the data before the data is sent to EdgeX Foundry and the database. The Created time stamp is the time the data was created in the database.
+
+Usually, the Origin and Created time stamps are the same or very close to the same. On occasion the sensor may be a long way from the gateway or even in a different time zone, and the Origin and Created time stamps may be quite different.
+
 ## Reference Implementation
 Default and example implementation(s) offered by the EdgeX community.  Other implementations may be offered by 3rd parties or for specialization.
 
+## Rules Engine
+Rules engines are important to the IoT edge system.
+
+A rules engine is a software system that is connected to a collection of data (either database or data stream). The rules engine examines various elements of the data and monitors the data, and then triggers some action based on the results of the monitoring of the data it. 
+
+A rules engine is a collection of "If-Then" conditional statements. The "If" informs the rules engine what data to look at and what ranges or values of data must match in order to trigger the "Then" part of the statement, which then informs the rules engine what action to take or what external resource to call on, when the data is a match to the "If" statement. 
+
+Most rules engines can be dynamically programmed meaning that new "If-Then" statements or rules, can be provided while the engine is running. The rules are often defined by some type of rule language with simple syntax to enable non-Developers to provide the new rules.
+
+Rules engines are one of the simplest forms of "edge analytics" provided in IoT systems. Rules engines enable data picked up by IoT sensors to be monitored and acted upon (actuated). Typically, the actuation is accomplished on another IoT device or sensor. For example, a temperature sensor in an equipment enclosure may be monitored by a rules engine to detect when the temperature is getting too warm (or too cold) for safe or optimum operation of the equipment. The rules engine, upon detecting temperatures outside of the acceptable range, shuts off the equipment in the enclosure.
+
 ## Software Development Kit
 In EdgeX, a software development kit (or SDK) is a library or module to be incorporated into a new micro service.  It provides a lot of the boilerplate code and scaffolding associated with the type of service being created.  The SDK allows the developer to focus on the details of the service functionality and not have to worry about the mundane tasks associated with EdgeX services.
 
@@ -62,5 +88,8 @@ of the network that communicates with the cloud, is referred to as the
 EdgeX enables data to be sent "north, " "south, " or laterally as
 needed and as directed.
 
+## "Snappy" / Ubuntu Core & Snaps
+A Linux-based Operating System provided by Ubuntu - formally called [Ubuntu Core](https://ubuntu.com/core) but often referred to as "Snappy". The packages are called 'snaps' and the tool for using them 'snapd', and works for phone, cloud, internet of things, and desktop computers. The "Snap" packages are self-contained and have no dependency on external stores. "Snaps" can be used to create command line tools, background services, and desktop applications.
+
 ## User
 If you want to get the EdgeX platform and run it (but do not intend to change or add to the existing code base now) then you are considered a "User".