Merge pull request #42 from Azure/iot-edge-module-support

Edge Module Documentation & Telemetry Validation

pnpbridge/quickstart.md

@@ -172,9 +172,9 @@ Similarly on Linux run the following:
  Start the IoT Plug and Play bridge sample for Environmental sensors by running it in a command prompt:
 
     ```
-    %REPO_DIR%\pnpbridge\> cd cmake\pnpbridge_x86\src\adaptors\samples\environmental_sensor
+    %REPO_DIR%\pnpbridge\> cd cmake\pnpbridge_x86\src\adapters\samples\environmental_sensor
 
-    %REPO_DIR%\pnpbridge\cmake\pnpbridge_x86\src\adaptors\samples\environmental_sensor>  Debug\pnpbridge_environmentalsensor.exe
+    %REPO_DIR%\pnpbridge\cmake\pnpbridge_x86\src\adapters\samples\environmental_sensor>  Debug\pnpbridge_environmentalsensor.exe
     ```
 ## View Telemetry in Azure IoT explorer 
 The bridge will start to display informational messages indicating a successful connection and messaging with an Azure IoT Hub. Data should briefly start to appear in the dashboard that was created in "Setting up Azure IoT Central".

pnpbridge/src/adapters/src/mqtt_pnp/mqtt_pnp.cpp

@@ -127,7 +127,7 @@ MqttPnp_CreatePnpComponent(
     const char* mqtt_server = json_object_get_string(AdapterComponentConfig, PNP_CONFIG_ADAPTER_MQTT_SERVER);
     int mqtt_port = (int) json_object_get_number(AdapterComponentConfig, PNP_CONFIG_ADAPTER_MQTT_PORT);
     const char* protocol = json_object_get_string(AdapterComponentConfig, PNP_CONFIG_ADAPTER_MQTT_PROTOCOL);
-    const char* mqttConfigId = json_object_get_string(AdapterComponentConfig, PNP_CONFIG_ADAPTER_MQTT_SUPPORTED_CONFIG);
+    const char* mqttConfigId = json_object_get_string(AdapterComponentConfig, PNP_CONFIG_ADAPTER_MQTT_IDENTITY);
 
     MqttPnpAdapter* adapterContext = reinterpret_cast<MqttPnpAdapter*>(PnpAdapterHandleGetContext(AdapterHandle));
     if (adapterContext == NULL)

pnpbridge/src/pnpbridge/common/pnp_device_client.c

@@ -106,12 +106,12 @@ IOTHUB_DEVICE_CLIENT_HANDLE PnP_CreateDeviceClientHandle(const PNP_DEVICE_CONFIG
         LogError("Unable to set the trusted cert, error=%d", iothubResult);
         result = false;
     }
+#endif // SET_TRUSTED_CERT
     else if ((iothubResult = IoTHubDeviceClient_SetOption(deviceHandle, OPTION_PRODUCT_INFO, pnpDeviceConfiguration->UserAgentString)) != IOTHUB_CLIENT_OK)
     {
         LogError("Unable to set product info string option, error=%d", iothubResult);
         result = false;
     }
-#endif // SET_TRUSTED_CERT
     else
     {
         result = true;
@@ -209,12 +209,12 @@ IOTHUB_MODULE_CLIENT_HANDLE PnP_CreateModuleClientHandle(const PNP_DEVICE_CONFIG
         LogError("Unable to set the trusted cert for module client, error=%d", iothubResult);
         result = false;
     }
+#endif // SET_TRUSTED_CERT
     else if ((iothubResult = IoTHubModuleClient_SetOption(moduleClientHandle, OPTION_PRODUCT_INFO, pnpModuleConfiguration->UserAgentString)) != IOTHUB_CLIENT_OK)
     {
         LogError("Unable to set product info string option for module client, error=%d", iothubResult);
         result = false;
     }
-#endif // SET_TRUSTED_CERT
     else
     {
         result = true;

pnpbridge/src/pnpbridge/common/readme.md

@@ -4,13 +4,21 @@ This directory contains helper routines used by the bridge to implement PnP func
 
 For reference the files are:
 
-* `pnp_device_client` header and .c file implement a function to help create a `IOTHUB_DEVICE_CLIENT_HANDLE`.  The `IOTHUB_DEVICE_CLIENT_HANDLE` is an existing IoTHub Device SDK that can be used for device <=> IoTHub communication.
+* `pnp_device_client` header and .c file implement a function to help create a `IOTHUB_DEVICE_CLIENT_HANDLE` and `IOTHUB_MODULE_CLIENT_HANDLE`.  The `IOTHUB_DEVICE_CLIENT_HANDLE` and `IOTHUB_MODULE_CLIENT_HANDLE` are client handles for IoTHub device or module that can be used for device/module <=> IoTHub communication.
 
-    Creating a `IOTHUB_DEVICE_CLIENT_HANDLE` that works with PnP requires a few additional steps, most importantly defining the device's PnP ModelId, which is
+    For IoT devices, creating a `IOTHUB_DEVICE_CLIENT_HANDLE` that works with PnP requires a few additional steps, most importantly defining the device's PnP ModelId, which is
     defined by the PnP Bridge's Root Interface Model Id and retrieved from the configuration file.
 
+    For IoT edge modules, creating a `IOTHUB_MODULE_CLIENT_HANDLE` that works with PnP requires a few additional steps, including:
+    - Populating the device's PnP ModelId, which is
+    defined by the PnP Bridge's Root Interface Model Id and retrieved from the edge runtime's environment through an environment variable `PNP_BRIDGE_ROOT_MODEL_ID`.
+    - Populating the edge module's connection string retrieved from the edge runtime's environment through an environment variable `IOTHUB_DEVICE_CONNECTION_STRING`.
+    - Enabling or disabling IoT hub tracing by retrieving this information from the edge runtime's environment through an environment variable `PNP_BRIDGE_HUB_TRACING_ENABLED`.
+
 * `pnp_dps` header and .c file implement functions to help provision a device handle through the device provisioning service.
 
 * `pnp_protocol` header and .c file implement functions to help with serializing and de-serializing the PnP convention. As an example of their usefulness, PnP properties are sent between the device and IoTHub using a specific JSON convention over the device twin. Functions in this header perform some of the tedious parsing and JSON string generation that is offloaded from the PnP Bridge.
 
-    The functions are agnostic to the underlying transport handle used.  If you use `IOTHUB_DEVICE_CLIENT_LL_HANDLE`, `IOTHUB_MODULE_CLIENT_HANDLE` or `IOTHUB_MODULE_CLIENT_LL_HANDLE` instead of the sample's `IOTHUB_DEVICE_CLIENT_HANDLE`, the `pnp_protocol` logic does not need to change.
+    The functions are agnostic to the underlying transport handle used.   The `pnp_protocol` logic does not need to change for `IOTHUB_DEVICE_CLIENT_LL_HANDLE`, `IOTHUB_MODULE_CLIENT_HANDLE`, `IOTHUB_MODULE_CLIENT_LL_HANDLE` or `IOTHUB_DEVICE_CLIENT_HANDLE`
+
+* `pnp_bridge_client` header defines wrapper functions around IoTHub SDK APIs tp bifurcate device and module client calls at compilation. This also allows for easy development and maintenance of PnP Bridge adapters

pnpbridge/src/pnpbridge/samples/console/config.json

@@ -71,7 +71,7 @@
         "pnp_bridge_component_name": "mqttdevice1",
         "pnp_bridge_adapter_id": "mqtt-pnp-interface",
         "pnp_bridge_adapter_config": {
-            "mqtt_port": "1",
+            "mqtt_port": 1,
             "mqtt_server": "1.1.1.1",
             "mqtt_protocol": "json_rpc",
             "mqtt_identity": "json_rpc_1"

readme.md

@@ -5,7 +5,11 @@
 
 IoT Plug and Play bridge is the open source effort from Microsoft that connects the PC sensor and peripheral ecosystem to Azure. It builds on top of [IoT Plug and Play](https://www.aka.ms/iotpnp) so that with minimal to no code, developers can easily connect peripherals/sensors to Azure, remotely access their data, monitor them, and manage them. This allows developers to perform analytics and gain valuable insights on their IoT devices from either the edge or the cloud. The IoT Plug and Play bridge accomplishes this without requiring peripherals to have direct Azure connectivity, enabling them to use a Windows or Linux host as a gateway to Azure instead. Because of this, it is particularly well suited for connecting existing/constrained sensors to Azure.
 
-IoT Plug and Play bridge can be deployed as a standalone executable on any IoT device, industrial PC, server, or gateway running Windows 10 or Linux. It can also be compiled into your application code. A simple configuration file tells the IoT Plug and Play bridge which sensors and peripherals should be exposed up to Azure. Once configured, the IoT Plug and Play bridge uses the [Azure IoT Hub Device C SDK](https://github.com/Azure/azure-iot-sdk-c) to publish IoT Plug and Play (PnP) interfaces for the specified sensors and peripherals up to Azure. Developers can then use existing Azure services and solution accelerators to receive data from and send commands to their sensors and peripherals.
+IoT Plug and Play bridge can be deployed as a standalone executable on any IoT device, industrial PC, server, or gateway running Windows 10 or Linux. It can also be compiled into your application code. A simple configuration file tells the IoT Plug and Play bridge which sensors and peripherals should be exposed up to Azure. Once configured, the IoT Plug and Play bridge uses the [Azure IoT Hub Device C SDK](https://github.com/Azure/azure-iot-sdk-c) to create a single device client handle, corresponding to a top level interface with specific model ID (DTMI) and supported IoT Plug and Play (PnP) components as specified in the model,for the specified sensors and peripherals up to Azure.
+
+IoT Plug and Play bridge can also be deployed as an IoT edge module running on any IoT edge device from an edge runtime running Linux. When the IoT Plug and Play bridge starts running as an edge module, it creates a single module client handle, corresponding to a top level interface with specific model ID (DTMI). Plug and Play Bridge adapter and IoT Plug and Play (PnP) components are not created until a property update for component and adapter related configuration (same as the JSON payload in the confugration file for IoT device) is received by the module. The JSON payload for the configuration, which tells the IoT Plug and Play bridge which sensors and peripherals should be exposed up to Azure, must be sent from the cloud to the module in the form of a desired property update for `PnpBridgeConfig`. The Plug and Play bridge will wait for this property update from the module twin to begin adapter and component configuration. Once configured, the IoT Plug and Play bridge uses the [Azure IoT Hub Module C SDK](https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-module-client-h) to begin device <-> cloud communication corresponding to the sensors and peripherals configured. 
+
+Developers can then use existing Azure services and solution accelerators to receive data from and send commands to their sensors and peripherals.
 
 ## Get Started - Documentation
 
@@ -57,11 +61,12 @@ The following OS platforms and versions are supported:
 - [CMake](https://cmake.org/download/) - when you install CMake, select the option `Add CMake to the system PATH`.
 - If you are building on Windows, you will also need to download Windows 17763 SDK: [https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk)
 
-- [Azure IoT Hub Device C SDK](https://github.com/Azure/azure-iot-sdk-c). The included build scripts in this repo will automatically clone the required Azure IoT C SDK for you.
+- [Azure IoT Hub Device Client C SDK](https://github.com/Azure/azure-iot-sdk-c) and [Azure IoT Hub Module Client C SDK](https://docs.microsoft.com/en-us/azure/iot-hub/iot-c-sdk-ref/iothub-module-client-h) . The included build scripts in this repo will automatically clone the required Azure IoT C SDK for you.
 
 ### Azure IoT Products and Tools
 
 - **Azure IoT Hub** - You'll need an [Azure IoT Hub](https://docs.microsoft.com/en-us/azure/iot-hub/) in your Azure subscription to connect your device to. If you don't have an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin. If you don't have an IoT Hub, [follow these instructions to create one](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-using-cli).
+
 > Note: IoT Plug and Play support is not included in basic-tier IoT Hubs.
 
 - **[OPTIONAL]:** To interact with the your IoT Plug and Play device, you use the **Azure IoT explorer** tool. [Download and install the latest release of Azure IoT explorer](https://docs.microsoft.com/en-us/azure/iot-pnp/howto-use-iot-explorer) for your operating system.