feat: Add Device Service System Events docs and update SDK APIs

also fix some broken links

Signed-off-by: Ginny Guan <ginny@iotechsys.com>

docs_src/V3TopLevelMigration.md

@@ -68,7 +68,7 @@ The following are where you can find the configuration migration specifics for i
 
 ### Customized Environment Overrides
 
-If you have custom [environment overrides](../microservices/configuration/CommonEnvironmentVariables/#environment-overrides) for configuration impacted by the V3 changes you will also need to migrate your overrides to use the new name or value depending on what has changed. Refer to the links above and/or below for details for migration of common and/or the service specific configuration to determine if your overrides require migrating.
+If you have custom [environment overrides](./microservices/configuration/CommonEnvironmentVariables.md) for configuration impacted by the V3 changes you will also need to migrate your overrides to use the new name or value depending on what has changed. Refer to the links above and/or below for details for migration of common and/or the service specific configuration to determine if your overrides require migrating.
 
 !!! note
     When using the Configuration Provider, the environment overrides for common configuration are applied to the **core-common-config-bootstrapper** service. They no longer work when applied to the individual services as the common configuration setting no longer exist in the private configuration.

docs_src/about.md

@@ -1,7 +1,7 @@
 # About
 
 EdgeX Foundry is an open source, vendor neutral, flexible, interoperable, software platform at the
-edge of the network, that interacts with the physical world of [devices](./general/Definitions.md#Device), sensors, actuators, and other IoT objects. In simple terms, EdgeX is edge middleware - serving  between physical sensing and actuating "things" and our information technology (IT) systems.
+edge of the network, that interacts with the physical world of [devices](./general/Definitions.md#device), sensors, actuators, and other IoT objects. In simple terms, EdgeX is edge middleware - serving  between physical sensing and actuating "things" and our information technology (IT) systems.
 ![image](./general/EdgeX_middleware.png)
 
 The EdgeX platform enables and encourages the rapidly growing community of
@@ -42,13 +42,13 @@ overall architecture:
     - Distribution
  (allowing for the distribution of functionality through micro services at the edge, on a gateway, in the fog, on cloud, etc.)
     - Deployment/orchestration (Docker, K8s, roll-your-own, ... )
-    - Protocols ([north or south](./general/Definitions.md#South-and-North-Side) side protocols)
+    - Protocols ([north or south](./general/Definitions.md#south-and-north-side) side protocols)
 
 - **EdgeX Foundry must be extremely flexible**
-    - Any part of the platform may be upgraded, replaced or augmented by other [micro services](./general/Definitions.md#Micro-service) or software components
+    - Any part of the platform may be upgraded, replaced or augmented by other [micro services](./general/Definitions.md#micro-service) or software components
     - Allow services to scale up and down based on device capability and use case 
 
-- **EdgeX Foundry should provide "[reference implementation](./general/Definitions.md#Reference-Implementation)" services but encourages best of breed solutions**
+- **EdgeX Foundry should provide "[reference implementation](./general/Definitions.md#reference-implementation)" services but encourages best of breed solutions**
 
 - **EdgeX Foundry must provide for store and forward capability**
     - To support disconnected/remote edge systems
@@ -59,12 +59,12 @@ overall architecture:
     - Bandwidth and storage concerns 
     - Operating remotely concerns
 
-- **EdgeX Foundry must support [brown and green](./general/Definitions.md#Brownfield-and-Greenfield) device/sensor field deployments**
+- **EdgeX Foundry must support [brown and green](./general/Definitions.md#brownfield-and-greenfield) device/sensor field deployments**
 
 - **EdgeX Foundry must be secure and easily managed**
 
 ## Deployments
-EdgeX was originally built by Dell to run on its IoT [gateways](./general/Definitions.md#Gateway). While EdgeX can and does run on gateways, its platform agnostic nature and micro service architecture enables tiered distributed deployments.  In other words, a single instance of EdgeX’s micro services can be distributed across several host platforms.  The host platform for one or many EdgeX micro services is called a node.  This allows EdgeX to leverage compute, storage, and network resources wherever they live on the edge.
+EdgeX was originally built by Dell to run on its IoT [gateways](./general/Definitions.md#gateway). While EdgeX can and does run on gateways, its platform agnostic nature and micro service architecture enables tiered distributed deployments.  In other words, a single instance of EdgeX’s micro services can be distributed across several host platforms.  The host platform for one or many EdgeX micro services is called a node.  This allows EdgeX to leverage compute, storage, and network resources wherever they live on the edge.
 
 Its loosely-coupled architecture enables distribution across nodes to enable tiered edge computing.  For example, thing communicating services could run on a programmable logic controller (PLC), a gateway, or be embedded in smarter sensors while other EdgeX services are deployed on networked servers. The scope of a deployment could therefore include embedded sensors, controllers, edge gateways, servers and cloud systems.
 
@@ -196,7 +196,7 @@ In edge computing, simply collecting sensor data is only part of the job of an e
 - Act quickly on that analysis
 Edge or local analytics is the processing that performs an assessment of the sensor data collected at the edge (“locally”) and triggers actuations or actions based on what it sees.
 
-Why [edge analytics](./general/Definitions.md#Edge-Analytics)?  Local analytics are important for two reasons:
+Why [edge analytics](./general/Definitions.md#edge-analytics)?  Local analytics are important for two reasons:
 
 - Some decisions cannot afford to wait for sensor collected data to be fed back to an enterprise or cloud system and have a response returned.
 - Additionally, some edge systems are not always connected to the enterprise or cloud – they have intermittent periods of connectivity.
@@ -224,8 +224,7 @@ The device service receives the request for actuation, translates that into a pr
 ## Project Release Cadence
 Typically, EdgeX releases twice a year; once in the spring and once in the fall.  Bug fix releases may occur more often.  Each EdgeX release has a code name.  The code name follows an alphabetic pattern similar to Android (code names sequentially follow the alphabet).
 
-The code name of each release is named after some geographical location in the world.  The honor of naming an EdgeX release is given to a community member deemed to have contributed significantly to the project.  A release also has a version number.  The release version follows sematic versioning to indicate the release is major or minor in scope.  Major releases typically contain significant new features and functionality and are not always backward compatible with prior releases.  Minor releases are backward compatible and usually contain bug fixes and fewer new features.  See the project Wiki for more information on [releases, versions and patches](https://wiki.edgexfoundry.org/pages/viewpage.action?pageId=21823969).
-
+The code name of each release is named after some geographical location in the world.  The honor of naming an EdgeX release is given to a community member deemed to have contributed significantly to the project.  A release also has a version number.  The release version follows sematic versioning to indicate the release is major or minor in scope.  Major releases typically contain significant new features and functionality and are not always backward compatible with prior releases.  Minor releases are backward compatible and usually contain bug fixes and fewer new features.  See the project Wiki for more information on [releases, versions and patches](https://lf-edgexfoundry.atlassian.net/wiki/spaces/FA/pages/11670494/Releases+Versions+Patches).
 | Release | Schedule | Version |
 | :------------- | :----------: | -----------: |
 |Barcelona |Oct 2017 | 0.5.0 |

docs_src/microservices/device/sdk/DeviceSystemEvents.md

@@ -0,0 +1,39 @@
+---
+title: Device Service SDK - Device System Events
+---
+
+# Device Service SDK - Device System Events
+
+The Device Service SDK offers [APIs](./api/GoDeviceSDK/GoDeviceSDKAPI.md) for publishing device system events, which provide updates on various device processes.
+A System Event DTO is published to the EdgeX MessageBus to provide updates on the status of the device (device discovery progress, profile scan progress, etc.).
+
+## System Event DTO
+
+!!! edgey - "Edgex 3.2"
+    System Event actions `discovery`, and `profilescan` are new in EdgeX 3.2
+
+The System Event DTO for the Device Service SDK APIs has the following properties:
+
+| Property  | Description                                                           | Value                                                                                |
+| --------- |-----------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| Type      | Type of System Event                                                  | `device`                                                                             |
+| Action    | System Event action                                                   | `discovery`, `profilescan`, or or any custom user-defined actions                    |
+| Source    | Source of the System Event                                            | the name of the device service                                                       |
+| Owner     | Owner of the data in the System Event                                 | the name of the device service that owns the device                                  |
+| Details   | The data object representing the device's status or the event details | the progress percentage (0 to 100) in this case. A value of `-1` indicates an error. |
+| Timestamp | Date and time of the System Event                                     | timestamp in nanoseconds                                                             |
+
+## Publish Topic
+
+The Device System Events is published to the topic specified by the `MessageQueue.PublishTopicPrefix` configuration setting above, which has a default of `edgex/system-events`, plus the following data items, which are added to allow receivers to filter by subscription.
+
+- source = [device service name]
+- type = device
+- action = discovery/profilescan
+- owner = [device service name which owns the device]
+
+!!! example - "Example Device System Event publish topics"
+    ```
+    edgex/system-events/device-simple/device/discovery/device-simple
+    edgex/system-events/device-simple/device/profilescan/device-simple
+    ```

docs_src/microservices/device/sdk/Purpose.md

@@ -4,7 +4,7 @@ title: Device Service SDK - Purpose
 
 # Device Service SDK - Purpose
 
-The EdgeX device service [software development kits](../../../general/Definitions.md#software-development-kit) (SDKs) help developers create new [device](../../../general/Definitions.md#Device) connectors for EdgeX.  An SDK provides the common scaffolding that each device service needs.  This allows developers to create new device/sensor connectors more quickly.
+The EdgeX device service [software development kits](../../../general/Definitions.md#software-development-kit) (SDKs) help developers create new [device](../../../general/Definitions.md#device) connectors for EdgeX.  An SDK provides the common scaffolding that each device service needs.  This allows developers to create new device/sensor connectors more quickly.
 
 ![image](EdgeX_SDKs.png)
 

docs_src/microservices/device/sdk/api/GoDeviceSDK/GoDeviceSDKAPI.md

@@ -45,6 +45,9 @@ type DeviceServiceSDK interface {
     LoggingClient() logger.LoggingClient
     SecretProvider() interfaces.SecretProvider
     MetricsManager() interfaces.MetricsManager
+    PublishDeviceDiscoveryProgressSystemEvent(progress, discoveredDeviceCount int, message string)
+    PublishProfileScanProgressSystemEvent(reqId string, progress int, message string)
+    PublishGenericSystemEvent(eventType, action string, details any)
 }
 ```
 
@@ -300,6 +303,24 @@ This API returns a channel to allow developer send asynchronous reading back to
 
 This API returns a channel to allow developer send discovered devices back to SDK.
 
+#### PublishDeviceDiscoveryProgressSystemEvent
+
+`PublishDeviceDiscoveryProgressSystemEvent(progress, discoveredDeviceCount int, message string)`
+
+This API publishes a device discovery progress system event through the EdgeX message bus.
+
+#### PublishProfileScanProgressSystemEvent
+
+`PublishProfileScanProgressSystemEvent(reqId string, progress int, message string)`
+
+This API publishes a profile scan progress system event through the EdgeX message bus.
+
+#### PublishGenericSystemEvent
+
+`PublishGenericSystemEvent(eventType, action string, details any)`
+
+This API publishes a generic system event through the EdgeX message bus
+
 ### Internal
 
 #### Run

docs_src/microservices/device/sdk/api/GoDeviceSDK/GoProtocolDriverAPI.md

@@ -122,3 +122,46 @@ This interface processes the collection of write requests passed in`reqs` for th
 It writes the data found in `params` to the device's resources specified in `reqs`.
 
 An example implementation can be found in the Device SDK's example [Simple Driver](https://github.com/edgexfoundry/device-sdk-go/blob/{{edgexversion}}/example/driver/simpledriver.go)
+
+## ExtendedProtocolDriver Interface
+
+This interface builds upon the existing `ProtocolDriver` interface to provide enhanced features and capabilities without disrupting or breaking existing implementations.
+
+```go
+type ExtendedProtocolDriver interface {
+	ProfileScan(req requests.ProfileScanRequest) (model.DeviceProfile, error)
+	StopDeviceDiscovery(options map[string]any)
+	StopProfileScan(deviceName string, options map[string]any)
+}
+```
+
+### Device
+
+The interfaces in this section deal with devices that the devices service manages
+
+#### ProfileScan
+
+`ProfileScan(req requests.ProfileScanRequest) (model.DeviceProfile, error)`
+
+This interface triggers protocol specific device to discover device profile.
+The resulting device profile will be added to the core-metadata and associated with the device.
+
+An example implementation can be found in the Device SDK's example [Simple Driver](https://github.com/edgexfoundry/device-sdk-go/blob/{{edgexversion}}/example/driver/simpledriver.go)
+
+#### StopDeviceDiscovery
+
+`StopDeviceDiscovery(options map[string]any)`
+
+This interface is called when there is a desire to stop the ongoing device discovery process.
+It accepts a `map[string]any` as options, which can be used to provide additional parameters for stopping the process.
+
+An example implementation can be found in the Device SDK's example [Simple Driver](https://github.com/edgexfoundry/device-sdk-go/blob/{{edgexversion}}/example/driver/simpledriver.go)
+
+#### StopProfileScan
+
+`StopProfileScan(deviceName string, options map[string]any)`
+
+This interface is called when there is a desire to stop the ongoing device profile scan process for a specific device.
+It accepts a `map[string]any` as options, which can be used to provide additional parameters for stopping the process.
+
+An example implementation can be found in the Device SDK's example [Simple Driver](https://github.com/edgexfoundry/device-sdk-go/blob/{{edgexversion}}/example/driver/simpledriver.go)

docs_src/walk-through/Ch-WalkthroughDeviceProfile.md

@@ -41,7 +41,7 @@ The device profile defines how to communicate with any device that abides by the
 
 #### Understanding Device Resources
 
-The device profile describes the elements of data that can be obtained from the device or sensor and how to change a setting on a device or sensor.  The data that can be obtained or the setting that can be changed are called **resources** or more precisely they are referred to as device [resources](../general/Definitions.md#Resource) in Edgex.  Learn more about `deviceReources` in the [Device Profile documentation](../microservices/core/metadata/details/DeviceProfile.md#deviceresources).
+The device profile describes the elements of data that can be obtained from the device or sensor and how to change a setting on a device or sensor.  The data that can be obtained or the setting that can be changed are called **resources** or more precisely they are referred to as device [resources](../general/Definitions.md#resource) in Edgex.  Learn more about `deviceReources` in the [Device Profile documentation](../microservices/core/metadata/details/DeviceProfile.md#deviceresources).
 
 In this walkthrough example, there are two pieces of data we want to be able to get or read from the camera:  dog and human counts.  Therefore, both are represented as device resources in the device profile.  Additionally, we want to be able to set two settings on the camera:  the scan depth and snapshot duration.  These are also represented as device resources in the device profile.
 

mkdocs.yml

@@ -152,6 +152,7 @@ nav:
             - Service Metrics: microservices/device/details/ServiceMetrics.md
         - Device Service SDK:
             - Purpose: microservices/device/sdk/Purpose.md
+            - Device System Events: microservices/device/sdk/DeviceSystemEvents.md
             - Getting Started:
                 - Go SDK: microservices/device/sdk/devicesdk-getting-started/GettingStartedSDK-Go.md
                 - C SDK: microservices/device/sdk/devicesdk-getting-started/GettingStartedSDK-C.md