Azure
/
iot-plug-and-play-bridge
зеркало из https://github.com/Azure/iot-plug-and-play-bridge.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

Merge pull request #27 from Azure/usivagna-patch-1 

Updated README to match public repo
This commit is contained in:
Ugan Sivagnanenthirarajah 2019-08-27 13:13:43 -07:00 коммит произвёл GitHub
Родитель cc21fc5c92 d1c6e4970f
Коммит 3b49a5bf31
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
2 изменённых файлов: 39 добавлений и 36 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

43
pnpbridge/ReadMe.md
Просмотреть файл

@ -1,4 +1,4 @@
# Building, Deploying and Extending the Azure IoT PnP Bridge
# Building, Deploying and Extending the Azure IoT Plug and Play bridge
## Compile the Bridge
@ -7,14 +7,13 @@
| Windows | :heavy_check_mark: |
| Linux | :heavy_check_mark: |
### Development Pre-Requisites
* In order to build Private Preview Azure PnP Bridge, you need to join Microsoft Azure team: https://github.com/Azure
### Development Pre-Requisites (for Windows)
* Ensure CMake (https://cmake.org/download/) and Visual Studio 2017 are installed. **CMake should be in the search PATH.**
* Download Windows 17763 SDK: https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk
### Build the Azure IoT PnP Bridge
### Build the Azure IoT Plug and Play bridge
#### Step 1: Get the required dependencies for the Azure PnP Bridge
#### Step 1: Get the required dependencies for the Azure IoT Plug and Play bridge
After cloning the Azure PnP Bridge repo to your machine, open the "Developer Command Prompt for VS 2017" and navigate to the directory of the cloned repo:
```
%REPO_DIR%\> cd pnpbridge
@ -24,7 +23,7 @@ After cloning the Azure PnP Bridge repo to your machine, open the "Developer Com
At this step, if you confirmed you have access to the Azure repo but are not able to successfully clone the required repos, you might be hitting authentication issues. To resolve this, install the [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows/releases)
#### Step 2: Build the Azure PnP Bridge
#### Step 2: Build the Azure IoT Plug and Play bridge
```
%REPO_DIR%\pnpbridge\> cd scripts\windows
@ -44,12 +43,15 @@ This project used CMAKE for generating project files. Any modifications made to
## Quickstart
To try out Azure IoT PnP Bridge, follow the steps bellow:
To try out Azure IoT Plug and Play bridge, follow the steps bellow:
* Create an Azure IoT device using Microsoft Azure documentation online and obtain the connections string. If using DPS, the bridge supports symmetric (e.g. Shared Access Signature or SAS) key for securely connecting to the device.
>Note: If using Azure IoT Central to create a device, you must create a custom device template in your application and add an interface that corresponds with your device interface. Refer to [Azure IoT Central documentation on connecting a IoT Plug and Play device](https://docs.microsoft.com/en-us/azure/iot-central/quick-create-pnp-device-pnp?toc=/azure/iot-central-pnp/toc.json&bc=/azure/iot-central-pnp/breadcrumb/toc.json).
* Modify the folowing parameters under **pnp_bridge_parameters** node in the config file (config.json):
Using Connection string:
Using Connection string (Note: the symmetric_key must match the SAS key in the connection string):
```JSON
{
@ -63,6 +65,7 @@ To try out Azure IoT PnP Bridge, follow the steps bellow:
}
}
}
}
```
Or using DPS:
@ -76,12 +79,13 @@ To try out Azure IoT PnP Bridge, follow the steps bellow:
"symmetric_key" : "[DEVICE KEY]"
},
"dps_parameters" : {
"global_prov_uri" : "[GLOABL PROVISIONING URI]",
"global_prov_uri" : "[GLOBAL PROVISIONING URI]",
"id_scope": "[IOT HUB ID SCOPE]",
"device_id": "[DEVICE ID]"
}
}
}
}
```
> Note: If using Azure IoT Central, the primary connection fields you will need to change in the default config file are id_scope, device_id, symmetric_key, and device_capability_model_id. Refer to the [Azure IoT Central documentation on device connectivity](https://docs.microsoft.com/en-us/azure/iot-central/concepts-connectivity) for how to generate the id_scope, device_id, and symmetric_key for your device. The device_capability_model_uri is the "Id" that is listed for your device's Device Capability Model in Azure IoT Central.
@ -95,11 +99,11 @@ To try out Azure IoT PnP Bridge, follow the steps bellow:
> Note: If you have either a built-in camera or a USB camera connected to your PC running the PnpBridge, you can start an application that uses camera, such as the built-in "Camera" app. Once you started running the Camera app, PnpBridge console output window will show the monitoring stats and the framerate of the camera will be reported through Azure IoT PnP interface to Azure.
## PnP Bridge Components
## Azure IoT Plug and Play bridge Components
### Discovery Adapter
A discovery adapter is a device watcher that is capable of reporting devices back to PnP Bridge in the form of a json message. These messages are used by PnpBridge to match a device from the PnP Bridge configuration and call into a PnP adapter to publish a Azure IoT PnP interface.
A discovery adapter is a device watcher that is capable of reporting devices back to the Azure IoT Plug and Play Bridge (PnP Bridge) in the form of a json message. These messages are used by the bridge to match a device from the Azure IoT Plug and Play bridge configuration and call into a PnP adapter to publish a Azure IoT PnP interface.
The message format should conform to below template:
```JSON
@ -148,15 +152,15 @@ If there are any initial parameters that needs to be passed as part of the Disco
### PnP Adapter
A PnP Adapter implements the bindings of Azure IoT PnP interface. There are currently 3 PnP adapters in the PnP Bridge:
A PnP Adapter implements the bindings of Azure IoT PnP interface. There are currently 3 PnP adapters in the Azure IoT Plug and Play bridge:
* CoreDeviceHealth: Implements basic device health interface
* CameraPnP: Implements camera specific health interface
* SerialPnp: Implements interfaces associated with MCUs or other devices that are [SerialPnP protocol compliant](./../SerialPnP/Readme.md)
* SerialPnp: Implements interfaces associated with MCUs or other devices that are [SerialPnP protocol compliant](../serialpnp/Readme.md)
### Configuration file
PnpBridge uses a configuration file to get the IoT hub connection settings and to configure devices for which PnP interfaces will be published. In the future this configuration could come from cloud.
PnpBridge uses a configuration file to get the IoT Hub connection settings and to configure devices for which PnP interfaces will be published. In the future this configuration could come from cloud.
The schema for the conifguration file is located under:
**src\pnpbridge\src\pnpbridge_config_schema.json**.
@ -165,7 +169,7 @@ Use this with VS code while authoring a PnpBridge configuration file to get sche
## Authoring new PnP Bridge Adapters
To extend PnP Bridge in order to support new device discovery and implement new Azure IoT PnP interfaces, follow the steps below. All the API declarations are part of "PnpBridge.h".
To extend Azure IoT Plug and Play bridge in order to support new device discovery and implement new Azure IoT PnP interfaces, follow the steps below. All the API declarations are part of "PnpBridge.h".
* Create a Discovery Adapter
@ -228,7 +232,7 @@ To extend PnP Bridge in order to support new device discovery and implement new
}
```
* The discovery adapter will be started automatically. To publish an Azure PnP interface add a configuration entry in config.json. In the below example, the PnpAdapter identity used is "my-pnp-adapter".
* The discovery adapter will be started automatically. To publish an Azure PnP interface add a configuration entry in config.json. In the below example, the PnpAdapter identity used is "my-pnp-adapter". The "component_name" below can be thought of as an identifier for a particular instance of an interface.
```JSON
"devices": [
@ -240,7 +244,8 @@ To extend PnP Bridge in order to support new device discovery and implement new
"my_custom_identity": "my-sample-device"
}
},
"interface_id": "http://contoso.com/mypnpinterface/1.0.0",
"interface_id": "urn:contoso:com:mypnpinterface:1",
"component_name":"MyComponent1",
"pnp_parameters": {
"identity": "my-pnp-adapter"
}
@ -251,7 +256,7 @@ To extend PnP Bridge in order to support new device discovery and implement new
Note: PnpBridge adapter callbacks are invoked in a sequential fashion. An adapter shouldn't block a callback since this will prevent PnpBridge from making forward progress.
## Sample Camera Adapter
The following [readme](src/adapters/src/camera/readme.md) provides details on a sample camera adapter that can be enabled with this preview.
The following [readme](./src/adapters/src/Camera/readme.md) provides details on a sample camera adapter that can be enabled with this preview.
## Folder Structure
@ -273,4 +278,4 @@ Source code for various PnpBridge adapters
### Support
For any questions raise an issue or contact - [Azure IoT PnP Bridge](mailto:pnpbridge@microsoft.com)
For any questions raise an issue or contact - [Azure IoT Plug and Play bridge](mailto:pnpbridge@microsoft.com)

32
readme.md
Просмотреть файл

@ -1,17 +1,13 @@
# This pre-release is confidential
Access to this pre-release software is confidential and should not be disclosed or shared with other parties per your NDA with Microsoft.
# Azure PnP Bridge
# Azure IoT Plug and Play bridge
## Introduction
Azure PnP Bridge is the open source effort from Microsoft that connects the PC sensor and peripheral ecosystem to Azure. It builds on top of [Azure IoT PnP](https://github.com/Azure/Azure-IoT-PnP-Preview/) so that with minimal to no code, developers can easily connect peripherals 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 Azure PnP Bridge accomplishes this without requiring peripherals to have direct Azure connectivity, enabling them to use a Windows host as a gateway to Azure instead. Because of this, it is particularly well suited for connecting cameras and environmental sensors to Azure.
Azure 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 [Azure IoT Plug and Play](https://azure.microsoft.com/en-us/blog/iot-plug-and-play-is-now-available-in-preview/) so that with minimal to no code, developers can easily connect peripherals 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 Azure 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 cameras and environmental sensors to Azure.
Azure PnP Bridge can be deployed as a standalone executable on any IoT device, PC, industrial PC, server, or gateway running Windows 10. It can also be compiled into your application code. A simple configuration file tells the Azure PnP Bridge which sensors and peripherals should be exposed up to Azure. Once configured, the Azure PnP Bridge uses the Azure IoT PnP SDK to dynamically publish Azure IoT 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.
Azure IoT Plug and Play bridge can be deployed as a standalone executable on any IoT device, PC, 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 Azure IoT Plug and Play bridge which sensors and peripherals should be exposed up to Azure. Once configured, the Azure IoT Plug and Play bridge uses the Azure IoT PnP SDK to dynamically publish Azure IoT 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.
## Pre-Requisites
- Windows 10 OS:
- For Windows 10 OS:
- For Camera health monitoring functionality, current Insider Preview OS version is required.
- All other functionality is available on all Windows 10 builds.
- All Windows SKUs are supported. For example:
@ -19,25 +15,24 @@ Azure PnP Bridge can be deployed as a standalone executable on any IoT device, P
- Windows Server
- Windows Desktop
- Windows IoT Core
- For Linux:
- Ubuntu is supported
- Hardware:
- Any hardware platform capable of supporting the above OS SKUs and versions.
- Serial, USB, and Camera peripherals are supported natively. The Azure PnP Bridge can be extended to support any custom peripheral ([see peripherals section below](#peripherals-supported-by-default))
- Serial, USB, and Camera peripherals are supported natively. The Azure IoT Plug and Play Bridge can be extended to support any custom peripheral ([see peripherals section below](#peripherals-supported-by-default))
- Private Preview of Azure IoT PnP: https://github.com/Azure/Azure-IoT-PnP-Preview/. The included build scripts will automatically clone the required Azure IoT PnP C SDK for you.
- Public Preview of [Azure IoT SDK for C](https://github.com/Azure/azure-iot-sdk-c/tree/public-preview). The included build scripts will automatically clone the required Azure IoT PnP C SDK for you.
- Private Preview of Azure IoT Central at https://aka.ms/iotc-demo (Optional, a fully-managed IoT SaaS solution with UI that can be used to monitor and manage your device from Azure)
- Public Preview of [Azure IoT Central](https://docs.microsoft.com/en-us/azure/iot-central/overview-iot-central-pnp) (Optional, a fully-managed IoT SaaS solution with UI that can be used to monitor and manage your device from Azure)
- Optional: [Azure IoT Edge](https://docs.microsoft.com/en-us/azure/iot-edge/) (can be used to help deploy, run, and manage software on the device)
- Optional: Private Preview of Azure IoT Device Agent https://github.com/ms-iot/azure-client-tools-pnp-preview (Pre-built client built on top of the Azure IoT PnP SDK that provides device provisioning and management capabilities out of the box. It also provides lifecycle management for the Azure connection and auto-discovery/loading/unloading of the PnP interfaces implemented by the Device Agent and its extensible plugins)
## Azure PnP Bridge Architecture
## Azure IoT Plug and Play bridge Architecture
![Architecture](./pnpbridge/docs/Pictures/AzurePnPBridge.png)
## Peripherals supported by default
Azure PnP Bridge supports the following types of peripherals by default. Developers can extend the Azure PnP Bridge to support additional peripherals via the instructions in the [PnP Bridge documentation](./pnpbridge/ReadMe.md).
Azure IoT Plug and Play bridge supports the following types of peripherals by default. Developers can extend the Azure PnP Bridge to support additional peripherals via the instructions in the [PnP Bridge documentation](./pnpbridge/ReadMe.md).
- Peripherals controlled by MCUs that are accessed over serial ports:
- Refer to the [SerialPnP documentation](./serialpnp/Readme.md) for information on how such devices should self-describe their interfaces to the PnP Bridge
- USB peripherals that can be discovered by Windows
@ -49,4 +44,7 @@ Follow [pnpbridge\Readme.md](./pnpbridge/ReadMe.md) to get started on building,
## Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com. When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
Microsoft collects performance and usage information which may be used to provide and improve Microsoft products and services and enhance your experience. To learn more, review the [privacy statement](https://go.microsoft.com/fwlink/?LinkId=521839&clcid=0x409).