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

Device Update for IoT Hub Public preview documentation (#4) 

* Device Update for IoT Hub Public preview documentation (#2)

* Updated branding for Public Preview + MIT license

Only for Agent docs that will move to the new Public GitHub repo: Updated branding for Public Preview + MIT license

* Updated TSG, Readme and added files for Security and Conduct

Updated TSG, Readme and added files for Security and Conduct

* Addressing comments for doc changes

Addressing comments for doc changes

* Deleted docs with ADU PM team

Deleted docs with ADU PM team

* Deleting docs/sample-artifacts/libcurl4-doc-ImportSteps*.txt:

Deleting docs/sample-artifacts/libcurl4-doc-ImportSteps*.txt:

* Public Preview changes for Device Update for IoT Hub

Public Preview changes for Device Update for IoT Hub

* Remove duplicate SECURITY.md and License file

* remove docs/agent-reference/images

* Modify README.md

Co-authored-by: Val <60334494+ValOlson@users.noreply.github.com>
This commit is contained in:
shiyi-peng 2021-02-26 14:40:14 -08:00 коммит произвёл GitHub
Родитель 8b3564072f
Коммит a97738ec83
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
75 изменённых файлов: 194 добавлений и 2564 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

2
CODE_OF_CONDUCT.md
Просмотреть файл

@ -6,4 +6,4 @@ Resources:
- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
- [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns
- Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns.

21
LICENSE
Просмотреть файл

@ -1,21 +0,0 @@
MIT License
Copyright (c) Microsoft Corporation.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE

74
LICENSE.md
Просмотреть файл

@ -1,61 +1,23 @@
MICROSOFT PREVIEW LICENSE TERMS
MICROSOFT Azure Device Update
________________________________________
These license terms are an agreement between you and Microsoft Corporation (or one of its affiliates). They apply to the software named above and any Microsoft services or software updates (except to the extent such services or updates are accompanied by new or additional terms, in which case those different terms apply prospectively and do not alter your or Microsoft’s rights relating to pre-updated software or services). IF YOU COMPLY WITH THESE LICENSE TERMS, YOU HAVE THE RIGHTS BELOW. BY USING THE SOFTWARE, YOU ACCEPT THESE TERMS.
# Device Update for IoT Hub
1. INSTALLATION AND USE RIGHTS.
a) General. You may install and use the software for internal use and evaluation purposes only. You may not use the software in a live operating environment unless Microsoft permits you to do so under another agreement. The software may only be stored on a privately accessible repository and Microsoft may require that you revoke access and usage privileges at any time.
b) Third Party Software. The software may include third party applications that are licensed to you under this agreement or under their own terms. License terms, notices, and acknowledgements, if any, for the third party applications may be accessible online at http://aka.ms/thirdpartynotices or in an accompanying notices file. Even if such applications are governed by other agreements, the disclaimer, limitations on, and exclusions of damages below also apply to the extent allowed by applicable law.
a) Microsoft Online Subscription Agreement. Some features of the software provide access to, or rely on, Microsoft Azure Services. The use of those services (but not the software) are governed by the separate terms and privacy policies associated with your Microsoft Azure subscription. The services may not be available in all regions. For more information see https://azure.microsoft.com/en-us/support/legal/.
Copyright (c) Microsoft Corporation
2. CONTRIBUTIONS. Microsoft welcomes contributions to this software. In the event that you make a contribution to this software you will be required to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant Microsoft the rights to use your contribution. For details, visit https://cla.microsoft.com.
MIT License
3. TIME-SENSITIVE SOFTWARE.
a) Period. This agreement is effective on your acceptance and terminates on the earlier of (i) 30 days following Microsoft’s public release of the software under an OSI-approved open source license or (ii) upon termination by Microsoft. Microsoft may extend this agreement in its discretion.
a) Notice. You may receive periodic reminder notices of this date through the software.
b) Access to data. You may not be able to access data used in the software when it stops running.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
4. PRE-RELEASE SOFTWARE. The software is a pre-release version (“Preview”). It may not operate correctly. It may be different from the commercially released version. Previews may employ lesser or different privacy and security measures than those typically present in Microsoft products and services which are a commercially released version. You should not use previews to process personal data or other data that is subject to legal or regulatory compliance requirements. Further, for the Azure Services the software provides access to or relies on, the following sections of the “Data Protection Terms” in the Online Services Terms do not apply: Processing of Personal Data; GDPR, Data Security, and HIPAA Business Associate.
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
5. CONFIDENTIAL INFORMATION. The software, including its user interface, features and documentation, is confidential and proprietary to Microsoft and its suppliers.
a) Use. For five years after installation of the software or its commercial release, whichever is first, you may not disclose confidential information to third parties. You may disclose confidential information only to your employees and consultants who need to know the information. You must have written agreements with them that protect the confidential information at least as much as this agreement.
b) Survival. Your duty to protect confidential information survives this agreement.
c) Exclusions. You may disclose confidential information in response to a judicial or governmental order. You must first give written notice to Microsoft to allow it to seek a protective order or otherwise protect the information. Confidential information does not include information that:
i. becomes publicly known through no wrongful act;
ii. you received from a third party who did not breach confidentiality obligations to Microsoft or its suppliers; or
iii. you developed independently.
6. FEEDBACK. If you give feedback about the software to Microsoft, you give to Microsoft, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires Microsoft to license its software or documentation to third parties because Microsoft includes your feedback in them. These rights survive this agreement.
7. DATA COLLECTION. The software may collect information about you and your use of the software and send that to Microsoft. Microsoft may use this information to provide services and improve Microsoft’s products and services. Your opt-out rights, if any, are described in the product documentation. Some features in the software may enable collection of data from users of your applications that access or use the software. If you use these features to enable data collection in your applications, you must comply with applicable law, including getting any required user consent, and maintain a prominent privacy policy that accurately informs users about how you use, collect, and share their data. You can learn more about Microsoft’s data collection and use in the product documentation and the Microsoft Privacy Statement at https://go.microsoft.com/fwlink/?LinkId=512132. You agree to comply with all applicable provisions of the Microsoft Privacy Statement.
8. SCOPE OF LICENSE. The software is licensed, not sold. Microsoft reserves all other rights. Unless applicable law gives you more rights despite this limitation, you will not (and have no right to):
a) work around any technical limitations in the software that only allow you to use it in certain ways;
b) reverse engineer, decompile, or disassemble the software, or attempt to do so, except and only to the extent permitted by licensing terms governing the use of open-source components that may be included with the software, or as otherwise permitted in Section 2;
c) remove, minimize, block, or modify any notices of Microsoft or its suppliers in the software;
d) use the software in any way that is against the law or to create or propagate malware; or
e) share, publish, distribute, or lend the software, provide the software as a stand-alone hosted solution for others to use, or transfer the software or this agreement to any third party.
9. EXPORT RESTRICTIONS. You must comply with all domestic and international export laws and regulations that apply to the software, which include restrictions on destinations, end users, and end use. For further information on export restrictions, visit http://aka.ms/exporting.
10. SUPPORT SERVICES. Microsoft is not obligated under this agreement to provide any support services for the software. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
11. UPDATES. The software may periodically check for updates, and download and install them for you. You may obtain updates only from Microsoft or authorized sources. Microsoft may need to update your system to provide you with updates. You agree to receive these automatic updates without any additional notice. Updates may not include or support all existing software features, services, or peripheral devices.
12. ENTIRE AGREEMENT. This agreement, and any other terms Microsoft may provide for supplements, updates, or third-party applications, is the entire agreement for the software.
13. APPLICABLE LAW AND PLACE TO RESOLVE DISPUTES. If you acquired the software in the United States or Canada, the laws of the state or province where you live (or, if a business, where your principal place of business is located) govern the interpretation of this agreement, claims for its breach, and all other claims (including consumer protection, unfair competition, and tort claims), regardless of conflict of laws principles. If you acquired the software in any other country, its laws apply. If U.S. federal jurisdiction exists, you and Microsoft consent to exclusive jurisdiction and venue in the federal court in King County, Washington for all disputes heard in court. If not, you and Microsoft consent to exclusive jurisdiction and venue in the Superior Court of King County, Washington for all disputes heard in court.
14. CONSUMER RIGHTS; REGIONAL VARIATIONS. This agreement describes certain legal rights. You may have other rights, including consumer rights, under the laws of your state or country. Separate and apart from your relationship with Microsoft, you may also have rights with respect to the party from which you acquired the software. This agreement does not change those other rights if the laws of your state or country do not permit it to do so. For example, if you acquired the software in one of the below regions, or mandatory country law applies, then the following provisions apply to you:
a) Australia. You have statutory guarantees under the Australian Consumer Law and nothing in this agreement is intended to affect those rights.
b) Canada. If you acquired this software in Canada, you may stop receiving updates by turning off the automatic update feature, disconnecting your device from the Internet (if and when you re-connect to the Internet, however, the software will resume checking for and installing updates), or uninstalling the software. The product documentation, if any, may also specify how to turn off updates for your specific device or software.
c) Germany and Austria.
i. Warranty. The properly licensed software will perform substantially as described in any Microsoft materials that accompany the software. However, Microsoft gives no contractual guarantee in relation to the licensed software.
ii. Limitation of Liability. In case of intentional conduct, gross negligence, claims based on the Product Liability Act, as well as, in case of death or personal or physical injury, Microsoft is liable according to the statutory law.
Subject to the foregoing clause ii., Microsoft will only be liable for slight negligence if Microsoft is in breach of such material contractual obligations, the fulfillment of which facilitate the due performance of this agreement, the breach of which would endanger the purpose of this agreement and the compliance with which a party may constantly trust in (so-called "cardinal obligations"). In other cases of slight negligence, Microsoft will not be liable for slight negligence.
15. DISCLAIMER OF WARRANTY. THE SOFTWARE IS LICENSED “AS IS.” YOU BEAR THE RISK OF USING IT. MICROSOFT GIVES NO EXPRESS WARRANTIES, GUARANTEES, OR CONDITIONS. TO THE EXTENT PERMITTED UNDER APPLICABLE LAWS, MICROSOFT EXCLUDES ALL IMPLIED WARRANTIES, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
16. LIMITATION ON AND EXCLUSION OF DAMAGES. IF YOU HAVE ANY BASIS FOR RECOVERING DAMAGES DESPITE THE PRECEDING DISCLAIMER OF WARRANTY, YOU CAN RECOVER FROM MICROSOFT AND ITS SUPPLIERS ONLY DIRECT DAMAGES UP TO U.S. $5.00. YOU CANNOT RECOVER ANY OTHER DAMAGES, INCLUDING CONSEQUENTIAL, LOST PROFITS, SPECIAL, INDIRECT, OR INCIDENTAL DAMAGES.
This limitation applies to (a) anything related to the software, services, content (including code) on third party Internet sites, or third party applications; and (b) claims for breach of contract, warranty, guarantee, or condition; strict liability, negligence, or other tort; or any other claim; in each case to the extent permitted by applicable law.
It also applies even if Microsoft knew or should have known about the possibility of the damages. The above limitation or exclusion may not apply to you because your state, province, or country may not allow the exclusion or limitation of incidental, consequential, or other damages.
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

65
README.md
Просмотреть файл

@ -1,36 +1,29 @@
# 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. As part of running its service, Azure Device
Update will provide download URLs and APIs to customers which contain the account and instance
name. Because the Azure Device Update service relies on publicly discoverable DNS endpoints,
be sure to avoid entering any sensitive or personally identifiable information.
# Azure Device Update Preview Documentation and Reference Client
| Build | Status |
|------------------- |--------|
| Ubuntu 18.04 AMD64 | [![Ubuntu 18.04 Build Status](https://dev.azure.com/azure-device-update/adu-linux-client/_apis/build/status/Azure.adu-private-preview?branchName=master)](https://dev.azure.com/azure-device-update/adu-linux-client/_build/latest?definitionId=13&branchName=master) |
| Yocto Warrior Raspberry Pi 3 B+ | [![Raspberry Pi Yocto Build Status](https://dev.azure.com/azure-device-update/adu-linux-client/_apis/build/status/adu-yocto-build?branchName=master)](https://dev.azure.com/azure-device-update/adu-linux-client/_build/latest?definitionId=4&branchName=master) |
This repository contains the following:
* Overview of Azure Device Update.
* API reference for publishing to Azure Device Update.
* API reference for managing updates through Azure Device Update.
* Reference Azure Device Update Agent code.
## What is Azure Device Update?
Azure Device Update is a managed service, that enables you to enable over the air updates
(OTA) for your IoT devices. ADU lets you focus on your solution, by ensuring your devices
are up to date with the latest security fixes or application updates without having to
build and maintain your own update solution. ADU is a reliable and scalable solution that
is based on the Windows Update platform, and integrated with Azure IoT Hub to support devices
globally. ADU also provides controls on how to manage the deployment updates so you are always
in control of when and how devices are updated. ADU also provides reporting capabilities so you
are always up to date on the state of your devices via integration with IoT Hub.
## Getting Started
[Getting Started with Azure Device Update](docs/adu-overview.md)
# What is Device Update for IoT Hub?
Device Update for IoT Hub is a service that enables you to deploy over-the-air updates (OTA) for your IoT devices.
Device Update for IoT Hub is an end-to-end platform that customers can use to publish, distribute, and manage over-the-air updates for everything from tiny sensors to gateway-level devices.
Device Update for IoT Hub also provides controls on how to manage the deployment updates so you are always in control of when and how devices are updated. Device Update for IoT Hub also provides reporting capabilities so you are always up to date on the state of your devices via integration with IoT Hub.
Device Update for IoT Hub features provide a powerful and flexible experience, including:
* Update management UX integrated with Azure IoT Hub
* Gradual update rollout through device grouping and update scheduling controls
* Programmatic APIs to enable automation and custom portal experiences
* At-a-glance update compliance and status views across heterogenous device fleets
* Support for resilient device updates (A/B) to deliver seamless rollback
* Subscription and role-based access controls available through the Azure.com portal
* On-premise content cache and Nested Edge support to enable updating cloud disconnected devices
* Detailed update management and reporting tools
## Reference agent
| Build | Status |
|------------------- |--------|
| Ubuntu 18.04 AMD64 | [![Ubuntu 18.04 Build Status](https://dev.azure.com/azure-device-update/adu-linux-client/_apis/build/status/Azure.iot-hub-device-update?branchName=main)](https://dev.azure.com/azure-device-update/adu-linux-client/_build/latest?definitionId=27&branchName=main)|
## Getting started
* [Device Update for IoT Hub](https://aka.ms/iot-hub-device-update-docs)
* [Getting Started with Device Update Agent](https://github.com/Azure/iot-hub-device-update/tree/main/docs/agent-reference)

22
SECURITY.md → Security.md
Просмотреть файл

@ -1,6 +1,4 @@
<!-- BEGIN MICROSOFT SECURITY.MD V0.0.5 BLOCK -->
## Security
# Security
Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
@ -14,17 +12,17 @@ Instead, please report them to the Microsoft Security Response Center (MSRC) at
If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
* Full paths of source file(s) related to the manifestation of the issue
* The location of the affected source code (tag/branch/commit or direct URL)
* Any special configuration required to reproduce the issue
* Step-by-step instructions to reproduce the issue
* Proof-of-concept or exploit code (if possible)
* Impact of the issue, including how an attacker might exploit the issue
* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
* Full paths of source file(s) related to the manifestation of the issue
* The location of the affected source code (tag/branch/commit or direct URL)
* Any special configuration required to reproduce the issue
* Step-by-step instructions to reproduce the issue
* Proof-of-concept or exploit code (if possible)
* Impact of the issue, including how an attacker might exploit the issue
This information will help us triage your report more quickly.
@ -37,5 +35,3 @@ We prefer all communications to be in English.
## Policy
Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).
<!-- END MICROSOFT SECURITY.MD BLOCK -->

41
docs/adu-aad-integration.md
Просмотреть файл

@ -1,41 +0,0 @@
# Azure RBAC and ADU
ADU utilizes Azure RBAC to to provide authentication and authorization for users and service Apis.
## Configure access control roles
In order for other users and applications to have access to Device Update, users or applications must be granted access to this resource. Here are the roles that are supported by Device Update
| Role Name | Description |
| :--------- | :---- |
| Device Update Administrator | Has access to all device update resources |
| Device Update Reader| Can view all updates and deployments |
| Device Update Content Administrator | Can view, import, and delete updates |
| Device Update Content Reader | Can view updates |
| Device Update Deployments Administrator | Can manage deployment of updates to devices|
| Device Update Deployments Reader| Can view deployments of updates to devices |
A combination of roles can be used to provide the right level of access, for example a developer can import and manage updates using the Device Update Content Administrator role, but can view the progress of an update using the Device Update Deployments Reader role. Conversely, a solution operator can have the Device Update Reader role to view all updates, but can use the Device Update Deployments Administrator role to deploy a specific update to devices.
### To set the Access Control Policy
1. Go to Access control (IAM)
2. Click "Add" within "Add a role assignment"
3. For "Select a Role", select "Device Update Administrator"
4. Assign access to a user or Azure AD group
5. Click Save
6. You can now go to IoT Hub and go to Device Update
## Authenticate to ADU REST APIs for Publishing and Management
ADU also utilizes Azure AD for authentication to publish and manage content via service APIs. To get started you need to create and configure a client application.
### Create client Azure AD App
To integrate an application or service with Azure AD, [first register](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) an application with Azure AD. Client application setup varies depending on the authorization flow used. Configuration below is for guidance when using the ADU REST APIs.
* Set client authentication: 'redirect URIs for native or web client'.
* Set API Permissions - Azure Device Update exposes:
* Delegated permissions: 'user_impersonation'
* **Optional**, grant admin consent

46
docs/adu-compliance.md
Просмотреть файл

@ -1,46 +0,0 @@
# Device Update Compliance
In Device Update, compliance measures how many devices have installed the highest version compatible update. A device
is considered compliant if it has installed the highest version update published to its instance of ADU that is
compatible for that device.
For example, consider an instance of ADU with the following updates:
|Update Name|Update Version|Compatible Device Model|
|-----------|--------------|-----------------------|
|Update1 |1.0 |Model1|
|Update2 |1.0 |Model2|
|Update3 |2.0 |Model1|
Let’s say the following deployments have been created:
|Deployment Name |Update Name |Targeted Group|
|-----------|--------------|-------------------|
|Deployment1 |Update1 |Group1|
|Deployment2 |Update2 |Group2|
|Deployment3 |Update3 |Group3|
Now, consider the following devices, with their group memberships and installed versions:
|DeviceId |Device Model |Installed Update Version|Group |Compliance|
|-----------|--------------|-----------------------|-----|---------|
|Device1 |Model1 |1.0 |Group1 |New updates available</span>|
|Device2 |Model1 |2.0 |Group3 |On latest update|
|Device3 |Model2 |1.0 |Group2 |On latest update|
|Device4 |Model1 |1.0 |Group3 |Update in progress|
Note that Device1 and Device4 are not compliant because they have version 1.0 installed even
though there’s a higher version update compatible for their model in the ADU instance (Update3). Device2 and
Device3 are both compliant because they have the highest version updates compatible for their models installed.
Compliance does not consider whether an update is deployed to a device’s group or not; it looks at any updates
published to ADU. So in the example above, Device1 is not compliant even though there is not a deployment for Update3
that targets that device’s group. So although Device1 has installed the highest version update that has been targeted to it,
it is still considered non-compliant. This can help you identify whether new deployments are needed.
As shown above, there are three compliance states in ADU:
* **On latest update** – the device has installed the highest version compatible update published to ADU.
* **Update in progress** – an active deployment is in the process of delivering the highest version compatible update to the device.
* **New updates available** – a device has not yet installed the highest version compatible update and is not in an active deployment for that update.

124
docs/adu-overview.md
Просмотреть файл

@ -1,124 +0,0 @@
# Azure Device Update (ADU) Overview
## What is Azure Device Update
Azure Device Update is a service that enables you to deploy over-the-air
updates (OTA) for your IoT devices. ADU lets you focus on your solution,
ensuring your devices are up-to-date with the latest security fixes or
application updates without having to build and maintain your own update
solution. ADU is a reliable and scalable solution that is based on the Windows
Update platform and integrated with Azure IoT Hub to support devices globally.
ADU provides controls on how to manage the deployment of updates, so you are
always in control of when and how devices are updated. Finally, ADU also
provides reporting capabilities so you can always see the state of your devices.
### Support for a wide range of IoT devices
Azure Device Update integrates with the Azure IoT device SDK to enable your
devices to receive updates. For Private Preview, an ADU Agent Simulator binary and Raspberry Pi reference Yocto image images are provided.
Azure Device Update also supports updating Azure IoT Edge devices. For Private
Preview, an ADU Agent will be provided for Ubuntu Server 18.04 amd64
platform. Azure Device Update will also provide open source code if you are not
running one of the above platforms so you can port it to the distribution you
are running.
ADU works with IoT Plug and Play (PnP) and can manage any device that supports
the required PnP interfaces. For more information, see [Azure Device Update and
IoT Plug and Play](how-adu-uses-iot-pnp.md).
### Support for a wide range of update artifacts
Azure Device Update supports two forms of updates – image-based
and package-based.
Package-based updates are targeted updates that alter only a specific component
or application on the device. Thus, this leads to lower consumption of
bandwidth and helps reduce the time to download and install the update. Package
updates typically allow for less downtime of devices when applying an update and
avoid the overhead of creating images.
Image updates provide a higher level of confidence in the end-state
of the device. It is typically easier to replicate the results of an
image-update between a pre-production environment and a production environment,
since it doesn’t pose the same challenges as packages and their dependencies.
Due to their atomic nature, one can also adopt a A/B failover model easily.
There is no one right answer, and you might choose differently based on
your specific use cases. Azure Device Update supports both image and package
form of updating, and empowers you to choose the right updating model
for your device environment.
### Secure updates
Once updates are published to ADU, they are then scanned for malware (coming
later during Private Preview) and additional metadata is generated that allows
the device to verify the integrity of the updates it receives. ADU uses IoT Hub
to securely communicate to the device to initiate an update. The device
then downloads the update from an ADU-specified location or a Gateway (coming
later during Private Preview.)
## ADU workflows
ADU functionality can be broken down into 3 areas: Agent Integration,
Importing, and Management. Below is a quick overview of the various areas of
functionality.
### ADU Agent
When an update command is received on a device, it will execute the requested
phase of updating, (either Download, Install and Apply). During each phase,
status is returned to ADU via IoT Hub so you can view the current status of a
deployment. If there are no updates in progress the status is returned as “Idle”
. A deployment can be canceled at any time.
![Client Agent Workflow](images/client-agent-workflow.png)
[Learn More](agent-reference/agent-overview.md)
### Importing
Importing is the ability to import your update into ADU. For Private Preview,
ADU supports rolling out a single update per device, making it ideal for
full-image updates that update an entire OS partition at once, or a
apt Manifest that describes all the packages you might want to update
on your device. To import updates into ADU, you first create an import manifest
describing the update, then upload both the update file(s) and the import
manifest to an Internet-accessible location. After that, you can use the Azure portal or call the ADU Import
REST API to initiate the asynchronous process where ADU uploads the files, processes
them, and makes them available for distribution to IoT devices.
**NOTE:** For sensitive content, protect the download using a shared access
signature (SAS), such as an ad-hoc SAS for Azure Blob Storage.
[Learn more about
SAS](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview)
![Import an Update](images/import-an-update.png)
[Learn More](publish-api-reference/import-api-overview.md)
### Management
When content is imported, ADU automatically adds the device into a **Device
Class** of devices with the same compatibility. ADU uses these device classes to
match devices to available content that is compatible with them. After importing
content into ADU, you can view compatible updates for your devices and device
classes.
ADU supports the concept of **Groups** via tags in IoT Hub. Deploying an update
out to a test group first is a good way to reduce the risk of issues during a
production rollout.
In ADU, deployments are called **Deployments**, which are a way of connecting the
right content to the a specific set of compatible devices. ADU orchestrates the
process of sending commands to each device, instructing them to download and
install the updates and getting status back.
![Manage and Deploy Updates](images/manage-deploy-updates.png)
[Learn More](management-api-reference/management-api-overview.md)
## Azure Device Update Quickstart
[Getting Started With Azure Device Update](quickstarts/overview-quickstart.md)

15
docs/adu-ports.md
Просмотреть файл

@ -1,15 +0,0 @@
# Ports Used With Azure Device Update (ADU)
## Ports
ADU uses a variety of network ports for different purposes.
Purpose|Port Number |
---|---
Download from Networks/CDNs | 80 (HTTP Protocol)
Download from MCC/CDNs | 80 (HTTP Protocol)
ADU Agent Connection to Azure IoT Hub | 8883 (MQTT Protocol)
**NOTE**: The ADU agent can be modified to use any of the supported Azure IoT
Hub protocols.
[Learn more](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-protocols#:~:text=Table%202%20%20%20,%201%20more%20rows) about the current list of supported protocols.

38
docs/agent-reference/adu-conf.md
Просмотреть файл

@ -1,38 +0,0 @@
# ADU Configuration File
The "adu-conf.txt" is an **optional** file that can be created to manage the following configurations.
* AzureDeviceUpdateCore:4.ClientMetadata:4.deviceProperties["manufacturer"]
* AzureDeviceUpdateCore:4.ClientMetadata:4.deviceProperties["model"]
* DeviceInformation.manufacturer
* DeviceInformation.model
* Device Connection String (if it is not known by the ADU Agent).
The ADU Agent will first try to get the `manufacturer` and `model` values from the device, for both the `AzureDeviceUpdateCore` and `DeviceInformation` interfaces. Secondly, if that fails, the ADU Agent will look for the "adu-conf.txt" and
use the values defined there. Lastly, if both attempts are not successful, the ADU Agent
will use default values.
### File location
Within Linux system, in the partition or disk called `adu`, create a text file called "adu-conf.txt" with
the following fields.
### List of ADU Configurations
|Name|Description|
|-----------|--------------------|
|connection_string|Pre-provisioned connection string the device can use to connect to the IoT Hub.|
|aduc_manufacturer|Reported by the `AzureDeviceUpdateCore:4.ClientMetadata:4` interface to classify the device for targeting the update deployment.|
|aduc_model|Reported by the `AzureDeviceUpdateCore:4.ClientMetadata:4` interface to classify the device for targeting the update deployment.|
|manufacturer|Reported by the ADU Agent as part of the `DeviceInformation` interface.|
|model|Reported by the ADU Agent as part of the `DeviceInformation` interface.|
[Learn more](./../how-adu-uses-iot-pnp.md) about the `DeviceInformation` and `AzureDeviceUpdate:4` interfaces.
#### Example "adu-conf.txt" file contents
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;connection_string = `HostName=<yourIoTHubName>;DeviceId=<yourDeviceId>;SharedAccessKey=<yourSharedAccessKey>`</br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;aduc_manufacturer = <value to send through `AzureDeviceUpdateCore:4.ClientMetadata:4.deviceProperties["manufacturer"]`></br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;aduc_model = <value to send through `AzureDeviceUpdateCore:4.ClientMetadata:4.deviceProperties["model"]`></br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;manufacturer = <value to send through `DeviceInformation.manufacturer`></br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;model = <value to send through `DeviceInformation.manufacturer`></br>

123
docs/agent-reference/agent-overview.md
Просмотреть файл

@ -1,123 +0,0 @@
# Azure Device Update (ADU) Agent Overview
The ADU Agent consists of two conceptual layers:
* The Interface Layer which builds on top of [Azure IoT Plug and Play
(PnP)](https://docs.microsoft.com/en-us/azure/iot-pnp/overview-iot-plug-and-play)
allowing for messaging to flow between the ADU Agent and ADU Services.
* The Platform Layer is responsible for the high-level update actions of Download, Install, and Apply that may be platform, or device specific.
![ADU Agent Implementations
Implementations](images/client-agent-reference-implementations.png)
## The Interface Layer
The Azure IoT PnP interfaces are implemented in `src/agent`. To see how this is
done, look at `AzureDeviceUpdateCore` in
[`src/agent/adu_core_interface/inc/aduc/adu_core_interface.h`](./../../src\agent\adu_core_interface\inc\aduc\adu_core_interface.h) and
[`src/agent/adu_core_interface/src/adu_core_interface.c`](./../../src/agent/adu_core_interface/src/adu_core_interface.c) and `DeviceInformation` in
[`src/agent/device_info_interface/inc/aduc/device_info_interface.h`](./../../src/agent/device_info_interface/inc/aduc/device_info_interface.h) and
[`src/agent/device_info_interface/src/device_info_interface.c`](./../../src/agent/device_info_interface/src/device_info_interface.c). ADU requires that
an ADU enabled device implement both `AzureDeviceUpdateCore` and `DeviceInformation`
Azure IoT PnP interfaces. [Learn More](../how-adu-uses-iot-pnp.md) about the Azure IoT PnP interfaces.
#### AzureDeviceUpdateCore
The `AzureDeviceUpdateCore` interface is the primary communication channel between
ADU Agent and Services. [Learn More](../how-adu-uses-iot-pnp.md) about this
interface.
#### DeviceInformation
The `DeviceInformation` interface is used implement the Azure IoT PnP
`DeviceInformation` interface. [Learn More](../how-adu-uses-iot-pnp.md) about this interface.
## The Platform Layer
There are two implementations of the Platform Layer. The Simulator Platform
Layer has a trivial implementation of the update actions and is used for quickly
testing and evaluating ADU services and setup. When the ADU Agent is built with
the Simulator Platform Layer, we refer to it as the ADU Simulator Agent or just
simulator. [Learn More](./how-to-run-agent.md) about how to use the simulator
agent. The Linux Platform Layer integrates with [Delivery Optimization](https://github.com/microsoft/do-client) for
downloads and is used in our Raspberry Pi reference image, and all clients which run on Linux systems.
#### Simulator Platform Layer
The Simulator Platform Layer implementation is in
`src/platform_layers/simulator_platform_layer`. This is an implementation for
testing and evaluating ADU. Many of the actions in the
"simulator" implementation are mocked so that you do not need to make any
physical changes to experiment with ADU. An end to end
"simulated" update can be performed using this Platform Layer. [Learn
More](how-to-run-agent.md) about running the simulator agent.
#### Linux Platform Layer
The Linux Platform Layer implementation is in
`src/platform_layers/linux_platform_layer`. This is an implementation that
integrates with the [Delivery Optimization Client](https://github.com/Azure/doclient-private-preview/releases) for downloads and is used in
our Raspberry Pi reference image, and all clients which run on Linux systems.
This layer can integrate with different Update Handlers to implement the
installer or content specific parts of the high-level update actions. For
instance the SWUpdate Update Handler invokes a shell script to call into the
SWUpdate executable to perform an update.
## Update Handlers
Update Handlers are components that handle content or installer specific parts
of the update. Update Handler implementations are in `src/content_handlers`.
#### Simulator Update Handler
The Simulator Update Handler is used by the Simulator Platform Layer and can
also be used with the Linux Platform Layer to fake interactions with a Content
Handler. The Simulator Update Handler implements the Update Handler APIs with
mostly no-ops. The implementation of the Simulator Update Handler is in
src/content_handlers/simulator_content_handler The InstalledCriteria field in
the AzureDeviceUpdateCore PnP interface should be the sha256 hash of the
content. This is the same hash that is present in the [Import Manifest
Object](../publish-api-reference/import-content.md). [Learn
More](../how-adu-uses-iot-pnp.md) about `installedCriteria` and the `AzureDeviceUpdateCore` interface.
#### SWUpdate Update Handler
The SWUpdate Update Handler integrates with the SWUpdate command line
executable and other shell commands to implement A/B updates specifically for
the Raspberry Pi reference Yocto image. [Learn More](yocto-configuration.md)
about the Raspberry Pi reference Yocto image. The SWUpdate Update Handler is
implemented in src/content_handlers/swupdate_content_handler.
#### APT Update Handler
The APT Update Handler processes an APT-specific Update Manifest and invokes APT to
install or update the specified Debian package(s).
## Getting Started with the ADU Agent
### Try out pre-built images, binaries, and packages
We have uploaded pre-built Raspberry Pi reference images, ADU agent binaries,
and ADU agent packages as part of our GitHub releases. Download them to get
started right away!
If you downloaded our Raspberry Pi reference image, go
[here](../quickstarts/how-to-agent-eval-pi-quickstart.md) to learn how to get
started.
### [Build the agent](how-to-build-agent-code.md)
Follow the instructions to [build](how-to-build-agent-code.md) the ADU Agent
from source.
### [Run the agent](how-to-run-agent.md)
Once the agent is successfully building, it's time [run](how-to-run-agent.md)
the agent.
### [Modifying the agent](how-to-modify-the-agent-code.md)
At this point you'll have an idea for how the ADU Agent works. Now, make the
changes needed to incorporate the agent into your image. Look at how to
[modify](how-to-modify-the-agent-code.md) the ADU Agent for guidance.

171
docs/agent-reference/apt-manifest.md
Просмотреть файл

@ -1,171 +0,0 @@
# APT Manifest
## Overview
The APT Manifest is a JSON file that describes an update details required by APT Update Handler.
This file can be imported into ADU just like any other content.
[Learn More](../quickstarts/how-to-import-quickstart.md) about importing content into ADU.
When an APT manifest is delivered to an ADU Agent as an update, the agent will process the manifest and perform the necessary operations, such as, download, and install the packages specified in the APT Manifest file.
ADU supports APT UpdateType and Update Handler that allows the ADU Agent to evaluate the installed Debian packages and update the necessary packages.
## Schema
An APT Manifest file is a JSON file with a versioned schema.
```json
{
"name": "<name>",
"version": "<version>",
"packages": [
{
"name": "<package name>",
"version": "<version specifier>"
}
]
}
```
Example:
```json
{
"name": "contoso-iot-edge",
"version": "1.0.0.0",
"packages": [
{
"name" : "thermocontrol",
"version" : "1.0.1"
},
{
"name" : "tempreport",
"version" : "2.0.0"
}
]
}
```
### name
The name for this APT Manifest. This can be whatever name or ID is meaningful for your
scenarios. e.g. `contoso-iot-edge`.
### version
A version number for this APT Manifest. e.g. `1.0.0.0`.
#### packages
A list of objects containing package specific properties.
#### name
The name or ID of the package. e.g. `iotedge`.
#### version
The desired version criteria for the package. e.g. `1.0.8-2`.
Currently only exact version number is supported. The version number is the desired Debian package
version in format [epoch:]upstream_version[-debian_revision].
**epoch** is an unsigned int.
**upstream_version** can include alphanumerics . + - ~ and should start with a digit.
Note that '1.0.8' is equal to '1.0.8-0'
e.g. **"name":"iotedge" and "version":"1.0.8-2"** equivalent to installing a package using command "apt-get install **iotedge=1.0.8-2**"
(Note: version value doesn't contain an equal sign)
If version is omitted, the latest available version of specified package will be installed.
[Learn More](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-version) about how Debian packages are versioned.
**Note**: APT package manager ignores versioning requirements given by a package when the dependent packages to install are being automatically resolved.
Unless explicit versions of dependent packages are given they will use the latest, even though the package itself may specify a strict requirement (=) on a given
version. This can lead to errors regarding an unmet dependency.
[Learn More](https://unix.stackexchange.com/questions/350192/apt-get-not-properly-resolving-a-dependency-on-a-fixed-version-in-a-debian-ubunt)
If you're updating a specific version of the Azure IoT Edge security daemon then you should include in your APT Manifest both the given version of the iotedge package and its dependent libiothsm-std package.
[Learn More](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-update-iot-edge#update-the-security-daemon)
## Recommended value for installed Criteria
The Installed Criteria for a APT Manifest is `<name>-<version>` where `<name>` is the name of the APT Manifest and `<version>` is the version of the APT Manifest. e.g. `contoso-iot-edge-1.0.0.0`.
[Learn More](../how-adu-uses-iot-pnp.md) about Installed Criteria.
## Guidelines on creating a APT Manifest
-------------------------------------------------------------------------------
While creating the APT Manifest, there are some guidelines to
keep in mind:
- Always ensure that the APT Manifest is a well-formed json file
- Each APT Manifest should have a unique version. Try to come up with a standardized methodology to increment the version of the APT Manifest, so that it makes sense for your scenarios and can be easily followed
- When it comes to the desired state of each individual package, specify the exact name and version of the package that you would like to install on your device. Always validate the values against the package repository that you intend to use as the source for the package
- Ensure that the packages in the APT Manifest are listed in the order they should be installed
- Always validate the installation of packages on a test device to ensure the outcome is desired
- When installing a specific version of a package (e.g. iotedge 1.0.9-1) it is best practice to also have in the APT Manifest the explicit versions of the dependent packages to be installed (e.g. libiothsm 1.0.9-1).
- While it is not mandated, always ensure your APT Manifest is cumulative to avoid getting your device into an unknown state. This will ensure that your devices have the desired version of every package you care about even if the device has skipped a APT Update deployment due to failure in installation, or being taken offline
For example:
**Base APT Manfiest**
```JSON
{
"name": "contoso-iot-edge",
"version": "1.0",
"packages": [
{
"name": "foo",
"version": "1.0.1"
}
]
}
```
**BAD UPDATE**
This includes the bar package, but not the foo package.
```JSON
{
"name": "contoso-iot-edge",
"version": "2.0",
"packages": [
{
"name": "bar",
"version": "3.0.2"
}
]
}
```
**GOOD UPDATE**
This includes foo package, and also includes bar package.
```JSON
{
"name": "contoso-iot-edge",
"version": "2.0",
"packages": [
{
"name": "foo",
"version": "1.0.1"
},
{
"name": "bar",
"version": "3.0.2"
}
]
}
```
**[Next Step: Import New Update](../quickstarts/how-to-import-quickstart.md)**

29
docs/agent-reference/how-to-build-agent-code.md
Просмотреть файл

@ -1,6 +1,6 @@
# How To Build The Azure Device Update Agent
# How To Build the Device Update for IoT Hub Agent
## Dependencies of ADU Agent
## Dependencies of Device Update Agent
### Required Dependencies
@ -19,13 +19,12 @@ The [Delivery Optimization
SDK](https://github.com/microsoft/do-client)
SDK provides a robust way for the client to download an update.
## Building the ADU Agent for Linux
## Building the Device Update Agent for Linux
### Installing Dependencies
Use the [scripts/install-deps.sh](../../scripts/install-deps.sh) Linux shell
script for a convenient way to install the dependencies of the Azure Device
Update agent for most use cases.
script for a convenient way to install the dependencies of the Device Update for IoT Hub agent for most use cases.
**Note**: You may be prompted for sudo password or GitHub username and password
when running `install-deps.sh`. If your GitHub account has two factor auth
@ -52,10 +51,9 @@ dependencies. To see the usage info:
./scripts/install-deps.sh -h
```
### ADU Linux Build System
### Device Update Linux Build System
The Azure Device Update reference agent code utilizes CMake for building. An
example build script is provided at [scripts/build.sh](../../scripts/build.sh).
The Device Update for IoT Hub reference agent code utilizes CMake for building. An example build script is provided at [scripts/build.sh](../../scripts/build.sh).
#### Build Using build.sh
@ -105,9 +103,9 @@ cmake -G Ninja ..
ninja
```
## Install the ADU Agent
## Install the Device Update Agent
To install the ADU Agent after building:
To install the Device Update Agent after building:
```shell
sudo cmake --build out --target install
@ -121,13 +119,4 @@ sudo ninja install
popd > /dev/null
```
**Note** If the ADU Agent was built as a daemon, the install targets will
install and register the ADU Agent as a daemon.
## Adding the ADU Agent to a Yocto build
You will need to create a set of Yocto recipes to build the ADU reference agent
as part of your Yocto build. In addition, to create Yocto recipes for
dependencies that are not already part of the standard Open Embedded layers.
[Learn more](./yocto-configuration.md) about the sample Yocto recipes and the
configurations that are used for the ADU reference agent.
**Note** If the Device Update Agent was built as a daemon, the install targets will install and register the Device Update Agent as a daemon.

10
docs/agent-reference/how-to-modify-the-agent-code.md
Просмотреть файл

@ -1,13 +1,11 @@
# How To Modify The Azure Device Update Agent Code
# How To Modify the Device Update for IoT Hub Agent Code
Here are some cases where you might want to modify the ADU Agent code to fit
your scenarios and devices.
Here are some cases where you might want to modify the Device Update Agent code to fit your scenarios and devices.
## Adding additional IoT Plug and Play interfaces
You may want to implement your own Azure IoT PnP interfaces in addition to the
ones necessary for ADU. We recommend looking at how the Azure Device Update
Core and Device Information interfaces are implemented in
ones necessary for Device Update for IoT Hub. We recommend looking at how the ADU Core Interface and Device Information interfaces are implemented in
[src/agent/adu_core_interface](../../src/agent/adu_core_interface). Specifically
[adu_core_interface.h](../../src/agent/adu_core_interface/inc/aduc/adu_core_interface.h)
and
@ -22,4 +20,4 @@ in [src/content_handlers](../../src/content_handlers)
## Porting to a Different OS or Platform
If you want to use the ADU Agent on an OS or platform that isn't supported out-of-the box, you can provide your own [Platform Layer](../../src/platform_layers) implementation. You may also need to port the [Azure IoT C SDK](https://github.com/Azure/azure-c-shared-utility/blob/public-preview/devdoc/porting_guide.md) to your device.
If you want to use the Device Update Agent on an OS or platform that isn't supported out-of-the box, you can provide your own [Platform Layer](../../src/platform_layers) implementation. You may also need to port the [Azure IoT C SDK](https://github.com/Azure/azure-c-shared-utility/blob/public-preview/devdoc/porting_guide.md) to your device.

8
docs/agent-reference/how-to-run-agent.md
Просмотреть файл

@ -1,4 +1,4 @@
# Running the Azure Device Update Reference Agent
# Running the Device Update for IoT Hub Reference Agent
## Command Line
@ -21,7 +21,7 @@ These arguments are specific to the agent simulator.
#### --simulation_mode=\<mode>
Tells the agent where and if to force a failure. This is useful for evaluating
and testing how ADU reports errors.
and testing how Device Update for IoT Hub reports errors.
`mode` can be one of the following options:
@ -54,8 +54,8 @@ DeviceInformation Digital Twin interface.
## Daemon
When the ADU Agent has been installed as a daemon, it will automatically start
on boot. The ADU Agent daemon reads the IoT Hub device connection string from a
When the Device Update Agent has been installed as a daemon, it will automatically start
on boot. The Device Update Agent daemon reads the IoT Hub device connection string from a
configuration file. Place your device connection string in /adu/adu-conf.txt.
To manually start the daemon:

Двоичные данные
docs/agent-reference/images/client-agent-reference-implementations.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 107 KiB

Двоичные данные
docs/agent-reference/images/client-agent-reference-implementations_old.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 261 KiB

146
docs/agent-reference/update-manifest.md
Просмотреть файл

@ -1,146 +0,0 @@
# ADU Update Manifest
## Overview
ADU communicates actions and metadata supporting actions (a.k.a. the Update Manifest) through the
[AzureDeviceUpdateCore.OrchestratorMetadata:4](./../how-adu-uses-iot-pnp.md) interface properties.
This document describes the fundamentals of how the `updateManifest` property, in the
`AzureDeviceUpdateCore.OrchestratorMetadata:4` interface, is used by the ADU Agent. The
`AzureDeviceUpdateCore.OrchestratorMetadata:4` interface properties are sent from the ADU Service
to the ADU Agent. The `updateManifest` is a serialized JSON Object that is parsed by the ADU Agent.
### Example Update Manifest
```JSON
{
"manifestVersion": "1",
"updateId": {
"provider": "AduTest",
"name": "AduTestUser",
"version": "2020.611.534.16"
},
"updateType": "microsoft/swupdate:1",
"installedCriteria": "1.0",
"files": {
"00000": {
"fileName": "image.swu",
"sizeInBytes": 256000,
"hashes": {
"sha256": "IhIIxBJpLfazQOk/PVi6SzR7BM0jf4HDqw+6gdZ3vp8="
}
}
},
"createdDateTime": "2020-06-12T00:38:13.9350278"
}
```
The purpose of the Update Manifest is to describe the contents of an update, namely its identity, type,
installed criteria, and update file metadata. In addition, the Update Manifest is cryptographically signed to
allow the ADU Agent to verify its authenticity.
### Validating Update Manifest Security
The Update Manifest is validated through the use of two signatures. The signatures are created using a structure consisting of *signing* keys and *root* keys.
The ADU Agent has embedded public keys which are used for any ADU-compatible device. These are the *root* keys. The corresponding private keys are controlled by Microsoft.
Microsoft also generates a public/private key pair which is not included in the ADU Agent or stored on the device. This is the *signing* key.
When an update is imported into ADU and the Update Manifest is generated by the service, the service signs the manifest using the signing key, and includes the signing key itself which is signed by a root key. When the Update Manifest is sent to the device, the ADU Agent receives the following signature data:
1. The signature value itself.
2. The algorithm used for generating #1.
3. The public key information of the signing key used for generating #1.
4. The signature of the public signing key in #3.
5. The public key ID of the root key used for generating #3.
6. The algorithm used for generating #4.
The ADU Agent uses the information defined above to validate that signature of the public signing key is signed by the root key. The ADU Agent then validates that the Update Manifest signature is signed by the signing key. If all the signatures are correct, the Update Manifest is trusted by the ADU Agent. Since the Update Manifest includes the file hashes which correspond to the update files themselves, the update files can then also be trusted if the hashes match.
Having root and signing keys allows us to periodically roll the signing key, a security best practice.
### JSON Web Signature (JWS)
The `updateManifestSignature` is used to ensure that the information contained within the `updateManifest` has
not been tampered with. The `updateManifestSignature` is produced using a JSON Web Signature with JSON Web Keys, allowing for source verification. The signature is a Base64Url Encoded string with three sections delineated by ".". Refer to the [jws_util.h](../../src/utils/jws_utils/inc/jws_utils.h) helper methods for parsing and verifying JSON keys and tokens.
JSON Web Signature is a widely used [proposed IETF standard](https://tools.ietf.org/html/rfc7515) for signing
content using JSON-based data structures. It is a way of ensuring integrity of data by verifying the signature
of the data. Further information can be found in the JSON Web Signature (JWS) [RFC 7515](https://www.rfc-editor.org/info/rfc7515).
### JSON Web Token
JSON Web Tokens are an open, industry [standard](https://tools.ietf.org/html/rfc7519) method for representing
claims securely between two parties.
## Import Manifest vs Update Manifest
It is important to understand the differences between the Import Manifest and the Update Manifest concepts in ADU. The Import Manifest
is created by update creators to describe the contents of the update that will be imported into ADU. The Update Manifest
is created by the ADU Service, using some of the properties that were defined in the Import Manifest, to communicate
relevant information to the ADU Agent upon an update. Each manifest type has it's own schema and schema version.
This file is focused on the details of the Update Manifest. [Learn more](./../quickstarts/how-to-import-quickstart.md)
about the details of the Import Manifest.
## Update Manifest Properties
The high-level definitions of the Update Manifest properties can be found in the interface definitions found
[here](./../how-adu-uses-iot-pnp.md). To provide deeper context, let's take a closer look
at the properties and how they are used in the system.
### updateId
Contains the `provider`, `name`, and `version`, which represents the exact ADU update identity used
to determine compatible devices for the update.
### updateType
Represents the type of update which is handled by a specific type of update handler. It follows the form
of `microsoft/swupdate:1` for an image-based update and `microsoft/apt:1` for a package-based update (see `Update Handler Types` section below).
### installedCriteria
A string that contains information needed by ADU Agent's Update Handler to determine whether the update is
installed on the device. The `Update Handler Types` section documents the format of the `installedCriteria`,
for each update type supported by ADU.
### files
Tells the ADU Agent which files to download and the hash which will be used to use to verify the files were downloaded correctly.
Here's a closer look at the `files` property contents:
```json
"files":{
<FILE_ID_STRING>:{
"fileName":<STRING>,
"sizeInBytes":<INTEGER>,
"hashes":{
<HASH-TYPE>:<HASH-STRING>
}
}
}
```
Outside of the `updateManifest` is the `fileUrls` array of JSON Object.
```json
"fileUrls":{
<FILE_ID_STRING>: <URL-in-String-Format>
}
```
Both the `FILE_ID_STRING`, within `fileUrls`, and `files` are the same (e.g. "0000" in `files` has the url
at "0000" within `fileUrls`).
### manifestVersion
A string that represents the schema version.
## Update Handler Types
|Update Method|Update Handler Type|Update Type|Installed Criteria|Expected Files for Publishing|
|-------------|-------------------|----------|-----------------|--------------|
|Image-based|SWUpdate|"microsoft/swupdate:version"|`<ADU_SOFTWARE_VERSION>` (defined in the Yocto build configuration [here](./yocto-configuration.md))|.swu file which contains SWUpdate image|
|Package-based|APT|"microsoft/apt:version"|`<name>` + "-" + `<version>` (defined properties in the APT Manifest file|`<APT Update Manifest>`.json which contains the APT configuration and package list|
**Note**: The `ADU_SOFTWARE_VERSION` will be saved to the `/etc/adu-version` file.

704
docs/agent-reference/yocto-configuration.md
Просмотреть файл

@ -1,704 +0,0 @@
# Yocto Layers, Recipes, and Configuration
There are three main areas that will be covered:
* Yocto build configurations
* Meta-azure-device-update recipe
* Image install with A/B partitions
## Yocto build configurations
This section describes the most important files of the Yocto build, including
'bblayers.conf.sample' and 'local.conf.sample' as well as the Yocto layers that need to be used.
| Layer Name | Description |
| ------------- | ---------- |
| meta-azure-device-update | Provides the configuration and contains the recipes for installing both the ADU Agent and its dependencies as well as integrating them into the Yocto build layers.|
| meta-openembedded | Brings in the openembedded layer for strengthening the raspberrypi BSP. Implements some of the Core functionality. |
| meta-raspberrypi | Implements the BSP layer for the RaspberryPi. Without this layer Yocto cannot be built to work on the raspberry pi. |
| meta-swupdate | Adds support for a deployment mechanisms of Yocto's images based on swupdate project. |
#### bblayers.conf.sample
The 'bblayers.conf.sample' shows the complete list of Yocto layers included in
the build.
```shell
POKY_BBLAYERS_CONF_VERSION = "3"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
BBLAYERS ?= " \
##OEROOT##/meta \
##OEROOT##/meta-poky \
##OEROOT##/meta-yocto-bsp \
##OEROOT##/../meta-openembedded/meta-oe \
##OEROOT##/../meta-openembedded/meta-multimedia \
##OEROOT##/../meta-openembedded/meta-networking \
##OEROOT##/../meta-openembedded/meta-python \
##OEROOT##/../meta-raspberrypi \
##OEROOT##/../meta-swupdate \
##OEROOT##/../meta-azure-device-update \
"
```
#### local.conf.sample
Similarly, the 'local.conf.sample' handles the configuration for machine and
package information, architecture, image types, and more.
```shell
CONF_VERSION = "1"
MACHINE ?= "raspberrypi3"
DISTRO ?= "poky"
PACKAGE_CLASSES ?= "package_ipk"
SDKMACHINE = "x86_64"
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
PATCHRESOLVE = "noop"
SSTATE_DIR ?= "build/sstate-cache"
RPI_USE_U_BOOT = "1"
ENABLE_UART = "1"
IMAGE_FSTYPES += "wic wic.bmap"
# Set PREFERRED_PROVIDER_u-boot-fw-utils to prevent warning about
# having two providers of u-boot-fw-utils
PREFERRED_PROVIDER_u-boot-fw-utils = "libubootenv"
DISTRO_FEATURES_append = " systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED += "sysvinit"
VIRTUAL-RUNTIME_init_manager = "systemd"
VIRTUAL-RUNTIME_initscripts = "systemd-compat-units"
```
## Meta-azure-device-update layer
This meta-azure-device-update layer describes the Yocto recipes in the layer
that builds and installs the ADU Agent code.
#### layer.conf
It is in the layer.conf file where configuration variables are set for ADU
software version, SWUpdate, manufacturer, and model.
**NOTE:** For private preview, manufacturer and model defined in layer.conf will
define the PnP manufacturer and model properties. Manufacturer and model must
match the 'compatibility' in the import manifest of the [ADU Publishing
flow](../quickstarts/how-to-import-quickstart.md), with the specific format of
"manufacturer.model" (case-sensitive).
```shell
BBPATH .= ":${LAYERDIR}"
# We have a recipes directory containing .bb and .bbappend files, add to BBFILES
BBFILES += "${LAYERDIR}/recipes*/*/*.bb \
${LAYERDIR}/recipes*/*/*.bbappend"
BBFILE_COLLECTIONS += "azure-device-update"
BBFILE_PATTERN_azure-device-update := "^${LAYERDIR}/"
# Pri 16 ensures that our recipes are applied over other layers.
# This is applicable where we are using appends files to adjust other recipes.
BBFILE_PRIORITY_azure-device-update = "16"
LAYERDEPENDS_azure-device-update = "swupdate"
LAYERSERIES_COMPAT_azure-device-update = "warrior"
# Layer-specific configuration variables.
ADU_SOFTWARE_VERSION ?= "0.0.0.1"
HW_REV ?= "1.0"
MANUFACTURER ?= "Contoso"
MODEL ?= "ADU Raspberry Pi Example"
BBFILES += "${@' '.join('${LAYERDIR}/%s/recipes*/*/*.%s' % (layer, ext) \
for layer in '${BBFILE_COLLECTIONS}'.split() for ext in ['bb', 'bbappend'])}"
```
### Build ADU Agent into image
The ADU reference agent uses the
[CMake](../../cmake) build
system to build the source code binaries. Build options are listed within the
azure-device-update_git.bb recipe and 'ADUC_SRC_URI' points to the ADU
reference agent to pull it into the image.
#### azure-device-update_git.bb
At runtime, 'RDEPENDS' lists the components that are depended on at runtime.
```shell
RDEPENDS_${PN} += "azure-device-update deliveryoptimization-agent-service"
```
In addition, there is a compile time dependency list, for the Azure IoT SDK for C and the Delivery Optimization Agent SDK.
```shell
# ADUC depends on azure-iot-sdk-c and DO Agent SDK
DEPENDS = "azure-iot-sdk-c deliveryoptimization-agent"
```
#### adu-agent-service.bb
The adu-agent-service.bb recipe is used to install the adu-agent.service that
will auto start the ADU agent service on boot for the Raspberry Pi image,
passing in the IoT Hub connection string located at /adu/adu-conf.txt
There are also similar recipes for the 'deliveryoptimization-agent' found in the
azure-device-update_git.bb bundle.
```shell
# Installs the ADU Agent Service that will auto-start the ADU Agent
# and pass in the IoT Hub connection string located at /adu/adu-conf.txt.
LICENSE="CLOSED"
SRC_URI = "\
file://adu-agent.service \
"
SYSTEMD_SERVICE_${PN} = "adu-agent.service"
do_install_append() {
install -d ${D}${systemd_system_unitdir}
install -m 0644 ${WORKDIR}/adu-agent.service ${D}${systemd_system_unitdir}
}
FILES_${PN} += "${systemd_system_unitdir}/adu-agent.service"
REQUIRED_DISTRO_FEATURES = "systemd"
RDEPENDS_${PN} += "azure-device-update deliveryoptimization-agent-service"
inherit allarch systemd
```
#### adu-agent.service
The adu-agent.service is a systemd unit file that defines the ADU Agent service (adu-agent.service).
This file will be installed at /lib/systemd/system directory.
```shell
[Unit]
Description=ADU Client service.
After=network-online.target
Wants=deliveryoptimization-agent.service
[Service]
Type=simple
Restart=on-failure
RestartSec=1
User=root
# If /adu/adu-conf.txt does not exist, systemd will try to start the ADU executable
# 5 times and then give up.
# We can check logs with journalctl -f -u adu-agent.service
ExecStart=/usr/bin/AducIotAgent -l 0 -e
[Install]
WantedBy=multi-user.target
```
#### adu-device-info-files.bb
The adu-device-info-files.bb specifies files the ADU reference agent uses to
implement the Device Information PnP interface. This generates files with ADU
applicability info for manufacturer, model and version, which can be read by the
ADU reference agent.
```shell
# Generates a text file with the ADU applicability info
# for manufacturer and model and copies/installs that file into the image.
# Environment variables that can be used to configure the behaviour of this recipe.
# MANUFACTURER The manufacturer string that will be written to the manufacturer
# file and reported through the Device Information PnP Interface.
# MODEL The model string that wil be written to the model file and
# reported through the Device Information PnP Interface.
# ADU_SOFTWARE_VERSION The software version for the image/firmware. Will be written to
# the version file that is read by ADU Agent.
LICENSE="CLOSED"
# Generate the manufacturer, model, and version files
do_compile() {
echo "${MANUFACTURER}" > adu-manufacturer
echo "${MODEL}" > adu-model
echo "${ADU_SOFTWARE_VERSION}" > adu-version
}
# Install the files on the image in /etc
do_install() {
install -d ${D}${sysconfdir}
install -m ugo=r adu-manufacturer ${D}${sysconfdir}/adu-manufacturer
install -m ugo=r adu-model ${D}${sysconfdir}/adu-model
install -m ugo=r adu-version ${D}${sysconfdir}/adu-version
}
FILES_${PN} += "${sysconfdir}/adu-manufacturer"
FILES_${PN} += "${sysconfdir}/adu-model"
FILES_${PN} += "${sysconfdir}/adu-version"
inherit allarch
```
#### deliveryoptimization-agent_git.bb
The deliveryoptimization-agent_git.bb is a recipe for building one of ADU Agent dependencies,
Delivery Optimization Client service.
```shell
# Build and install Delivery Optimization Agent and SDK.
# Environment variables that can be used to configure the behavior of this recipe.
# DO_SRC_URI Changes the URI where the DO code is pulled from.
# This URI follows the Yocto Fetchers syntax.
# See https://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-SRC_URI
# BUILD_TYPE Changes the type of build produced by this recipe.
# Valid values are Debug, Release, RelWithDebInfo, and MinRelSize.
# These values are the same as the CMAKE_BUILD_TYPE variable.
LICENSE = "CLOSED"
DO_SRC_URI ?= "gitsm://github.com/microsoft/do-client;branch=main"
SRC_URI = "${DO_SRC_URI}"
# This code handles setting variables for either git or for a local file.
# This is only while we are using private repos, once our repos are public,
# we will just use git.
python () {
src_uri = d.getVar('DO_SRC_URI')
if src_uri.startswith('git'):
d.setVar('SRCREV', d.getVar('AUTOREV'))
d.setVar('PV', '1.0+git' + d.getVar('SRCPV'))
d.setVar('S', d.getVar('WORKDIR') + "/git")
elif src_uri.startswith('file'):
d.setVar('S', d.getVar('WORKDIR') + "/deliveryoptimization-agent")
}
DEPENDS = "boost cpprest libproxy msft-gsl"
inherit cmake
BUILD_TYPE ?= "Debug"
EXTRA_OECMAKE += "-DCMAKE_BUILD_TYPE=${BUILD_TYPE}"
# Don't build DO tests.
EXTRA_OECMAKE += "-DDO_BUILD_TESTS=OFF"
# cpprest installs its config.cmake file in a non-standard location.
# Tell cmake where to find it.
EXTRA_OECMAKE += "-Dcpprestsdk_DIR=${WORKDIR}/recipe-sysroot/usr/lib/cmake"
BBCLASSEXTEND = "native nativesdk"
do_install_append() {
install -d ${D}${includedir}
install -m 0755 ${S}/include/do_config.h ${D}${includedir}/
install -m 0755 ${S}/include/do_download.h ${D}${includedir}/
install -m 0755 ${S}/include/do_download_status.h ${D}${includedir}/
install -m 0755 ${S}/include/do_exceptions.h ${D}${includedir}/
}
```
#### deliveryoptimization-agent-service.bb
The deliveryoptimization-agent-service.bb file installs and configures the Delivery Optimization Client
service on the device.
```shell
# Installs and configures the DO Agent Service
LICENSE="CLOSED"
SRC_URI = "\
file://deliveryoptimization-agent.service \
"
SYSTEMD_SERVICE_${PN} = "deliveryoptimization-agent.service"
do_install_append() {
install -d ${D}${systemd_system_unitdir}
install -m 0644 ${WORKDIR}/deliveryoptimization-agent.service ${D}${systemd_system_unitdir}
}
FILES_${PN} += "${systemd_system_unitdir}/deliveryoptimization-agent.service"
REQUIRED_DISTRO_FEATURES = "systemd"
RDEPENDS_${PN} += "deliveryoptimization-agent"
inherit allarch systemd
```
#### deliveryoptimization-agent.service
The deliveryoptimization-agent-list.service is a systemd unit file that defines the Delivery Optimization Client service.
```shell
[Unit]
Description=deliveryoptimization-agent: Performs content delivery optimization tasks
After=network-online.target
[Service]
Type=simple
Restart=on-failure
User=root
ExecStart=/usr/bin/docs-daemon/docs
[Install]
WantedBy=multi-user.target
```
#### azure-iot-sdk-c_git.bb
The ADU Agent communicates with ADU services using a PnP supports provied by
an Azure IoT SDK for C. azure-iot-sdk-c_git.bb is the recipe for building the SDK used by ADU Agent.
```shell
# Build and install the azure-iot-sdk-c with PnP support.
DESCRIPTION = "Microsoft Azure IoT SDKs and libraries for C"
AUTHOR = "Microsoft Corporation"
HOMEPAGE = "https://github.com/Azure/azure-iot-sdk-c"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://LICENSE;md5=4283671594edec4c13aeb073c219237a"
# We pull from master branch in order to get PnP APIs
SRC_URI = "gitsm://github.com/Azure/azure-iot-sdk-c.git;branch=master"
SRCREV = "${AUTOREV}"
PV = "1.0+git${SRCPV}"
S = "${WORKDIR}/git"
# util-linux for uuid-dev
DEPENDS = "util-linux curl openssl boost cpprest libproxy msft-gsl"
inherit cmake
# Do not use amqp since it is deprecated.
# Do not build sample code to save build time.
EXTRA_OECMAKE += "-Duse_amqp:BOOL=OFF -Duse_http:BOOL=ON -Duse_mqtt:BOOL=ON -Dskip_samples:BOOL=ON -Dbuild_service_client:BOOL=OFF -Dbuild_provisioning_service_client:BOOL=OFF"
sysroot_stage_all_append () {
sysroot_stage_dir ${D}${exec_prefix}/cmake ${SYSROOT_DESTDIR}${exec_prefix}/cmake
}
FILES_${PN}-dev += "${exec_prefix}/cmake"
BBCLASSEXTEND = "native nativesdk"
```
#### adu-base-image.bb
The adu-base-image.bb file creates an image that can be flashed on an SD card
with the ADU Agent, DO Agent, and other useful features pre-installed.
```shell
# Creates the base image for ADU that can we used to flash an SD card.
# This image is also used to populate the ADU update image.
DESCRIPTION = "ADU base image"
SECTION = ""
LICENSE="CLOSED"
# .wks file is used to create partitions in image.
WKS_FILE_raspberrypi3 = "adu-raspberrypi.wks"
# wic* images our used to flash SD cards
# ext4.gz image is used to construct swupdate image.
IMAGE_FSTYPES += "wic wic.gz ext4.gz"
IMAGE_FEATURES += "splash debug-tweaks ssh-server-openssh tools-debug tools-profile"
# connman - provides network connectivity.
# parted - provides disk partitioning utility.
# fw-env-conf - installs fw_env.config file for fw utils. (fw_*)
IMAGE_INSTALL_append = " \
packagegroup-core-boot \
packagegroup-core-full-cmdline \
openssh connman connman-client \
parted fw-env-conf \
adu-agent-service \
"
export IMAGE_BASENAME = "adu-base-image"
# This must be at the bottom of this file.
inherit core-image
```
#### adu-raspberrypi.wks
The adu-raspberrypi.wks file creates the partition layout and populates files in
the final ADU base image that can be flashed onto an SD card. **Note** This file
would normally update the fstab file for the ADU base image, but it would not
update the fstab file for the ADU update image. To ensure the fstab files in
both the base and update images are correct, we specify our own fstab file.
```shell
# Wic Kickstart file that defines which partitions are present in wic images.
# See https://www.yoctoproject.org/docs/current/mega-manual/mega-manual.html#ref-kickstart
# NOTE: Wic will update the /etc/fstab file in the .wic* images,
# but this file needs to also be in sync with the base-files fstab file
# that gets provisioned in the rootfs. Otherwise, updates will install
# an incompatible fstab file.
# Boot partition containing bootloader. This must be the first entry.
part /boot --source bootimg-partition --ondisk mmcblk0 --fstype=vfat --label boot --active --align 4096 --size 20 --fsoptions "defaults,sync"
# Primary rootfs partition. This must be the second entry.
part / --source rootfs --ondisk mmcblk0 --fstype=ext4 --label rootA --align 4096 --extra-space 512
# Secondary rootfs partition used for A/B updating. Starts as a copy of the primary rootfs partition.
# This must be the third entry.
part --source rootfs --ondisk mmcblk0 --fstype=ext4 --label rootB --align 4096 --extra-space 512
# ADU parition for ADU specfic configuration and logs.
# This partition allows configuration and logs to persist across updates (similar to a user data partition).
# The vfat file type allows this partition to be viewed and written to from Linux or Windows.
part /adu --ondisk mmcblk0 --fstype=vfat --label adu --align 4096 --size 512
```
#### fstab
```shell
# The fstab (/etc/fstab) (or file systems table) file is a system configuration
# file on Debian systems. The fstab file typically lists all available disks and
# disk partitions, and indicates how they are to be initialized or otherwise
# integrated into the overall system's file system.
# See https://wiki.debian.org/fstab
# Default fstab entries
/dev/root / auto defaults 1 1
proc /proc proc defaults 0 0
devpts /dev/pts devpts mode=0620,gid=5 0 0
tmpfs /run tmpfs mode=0755,nodev,nosuid,strictatime 0 0
tmpfs /var/volatile tmpfs defaults 0 0
# Custom fstab entries for ADU raspberrypi3.
# NOTE: these entries must be kept in sync with the corresponding .wks file.
# Mount the boot partition that contains the bootloader.
/dev/mmcblk0p1 /boot vfat defaults,sync 0 0
# Mount the ADU specific partition for reading configuration and writing logs.
/dev/mmcblk0p4 /adu vfat defaults 0 0
```
### Build image for A/B partitions
Alongside the ADU reference agent, two types of reference images, specifically
for the Raspberry Pi 3 B+ device, are built. One is used as a base image
('rpi-u-boot-scr.bbappend', included in the raspberrypi bsp recipes) for the
initial flash of the device, installed on the "active partition" and an update
image, to be delivered by ADU, installed on the "inactive partition". After a
reboot the partitions will swap.
#### rpi-u-boot-scr.bbappend
The bootloader script needs to override the raspberrypi bsp layer, to handle A/B
updating. The rpi-u-boot-scr.bbappend file tells the recipe file to look in a
different directory for the bootloader.
```shell
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
```
#### boot.cmd.in
The 'rpi-u-boot-scr.bbappend' file installs a custom 'boot.cmd.in' instead of
the default one. This script allows the ADU Agent to change the root partition
on reboot.
```shell
saveenv
fdt addr ${fdt_addr} && fdt get value bootargs /chosen bootargs
fatload mmc 0:1 ${kernel_addr_r} @@KERNEL_IMAGETYPE@@
if env exists rpipart;then setenv bootargs ${bootargs} root=/dev/mmcblk0p${rpipart}; fi
@@KERNEL_BOOTCMD@@ ${kernel_addr_r} - ${fdt_addr}
```
#### u-boot-fw-utility_%.bbappend and u-boot-fw-utils_%.bbappend
```shell
FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
```
#### fw-env-conf.bb
Similarly, the u-boot recipe file needs to be overwritten to facilitate A/B
updates.
```shell
# Copy/install fw_env.config which is necessary for fw utils (fw_*)
# like fw_printenv and fw_setenv
LICENSE = "CLOSED"
SRC_URI = "file://fw_env.config"
do_install() {
install -d ${D}${sysconfdir}
install -m 644 ${WORKDIR}/fw_env.config ${D}${sysconfdir}/fw_env.config
}
FILES_${PN} += "${sysconfdir}/fw_env.config"
```
### SWUpdate support
The SWUpdate framework is used to build the base and update ADU Agent images.
It is also used to install the image on the Raspberry Pi device.
#### swupdate_%.bbappend
Point to the 'defconfig' file instead using 'swupdate_%.bbappend'.
```shell
FILESEXTRAPATHS_append := "${THISDIR}/${PN}:"
PACKAGECONFIG_CONFARGS = ""
```
#### defconfig
The 'defconfig' file is how ADU configures SWUpdate to build and install into
the image, which are applied at build time. The result is a custom
implementation of SWUpdate to suit the needs of the ADU reference agent.
```shell
CONFIG_HAVE_DOT_CONFIG=y
CONFIG_LUA=y
CONFIG_LUAPKG="lua"
CONFIG_HW_COMPATIBILITY=y
CONFIG_HW_COMPATIBILITY_FILE="/etc/adu-hw-compat"
CONFIG_CROSS_COMPILE=""
CONFIG_SYSROOT=""
CONFIG_EXTRA_CFLAGS=""
CONFIG_EXTRA_LDFLAGS=""
CONFIG_EXTRA_LDLIBS=""
CONFIG_UBOOT=y
CONFIG_UBOOT_NEWAPI=y
CONFIG_UBOOT_FWENV="/etc/fw_env.config"
CONFIG_HASH_VERIFY=y
CONFIG_SIGNED_IMAGES=y
CONFIG_SIGALG_RAWRSA=y
CONFIG_GUNZIP=y
CONFIG_LIBCONFIG=y
CONFIG_PARSERROOT=""
CONFIG_RAW=y
CONFIG_ARCHIVE=y
CONFIG_BOOTLOADERHANDLER=y
```
#### adu-update-image.bb
The adu-update-image.bb file builds the SWUpdate image.
```shell
DESCRIPTION = "ADU swupdate image"
SECTION = ""
LICENSE="CLOSED"
DEPENDS += "adu-base-image swupdate"
SRC_URI = " \
file://sw-description \
"
# images to build before building adu update image
IMAGE_DEPENDS = "adu-base-image"
# images and files that will be included in the .swu image
SWUPDATE_IMAGES = " \
adu-base-image \
"
SWUPDATE_IMAGES_FSTYPES[adu-base-image] = ".ext4.gz"
# Generated RSA key with password using command:
# openssl genrsa -aes256 -passout file:priv.pass -out priv.pem
SWUPDATE_SIGNING = "RSA"
SWUPDATE_PRIVATE_KEY = "${ADUC_PRIVATE_KEY}"
SWUPDATE_PASSWORD_FILE = "${ADUC_PRIVATE_KEY_PASSWORD}"
inherit swupdate
```
#### sw-description file
This configuration file defines meta data about the update and the primary bootloader location.
Two files are referenced in the file and which partition each goes to.
```shell
copy1 on the device = location for partition A
copy2 on the device = location for partition B
```
The script looks at what partition being used. If that partition is in use, it
will switch to using the other one. A reboot is required to switch partitions.
```shell
software =
{
version = "@@ADU_SOFTWARE_VERSION@@";
raspberrypi3 = {
hardware-compatibility: ["1.0"];
stable = {
copy1 : {
images: (
{
filename = "adu-base-image-raspberrypi3.ext4.gz";
sha256 = "@adu-base-image-raspberrypi3.ext4.gz";
type = "raw";
compressed = true;
device = "/dev/mmcblk0p2";
}
);
};
copy2 : {
images: (
{
filename = "adu-base-image-raspberrypi3.ext4.gz";
sha256 = "@adu-base-image-raspberrypi3.ext4.gz";
type = "raw";
compressed = true;
device = "/dev/mmcblk0p3";
}
);
};
}
}
}
```
## Install and apply image
#### src/adu-shell/scripts/adu-swupdate.sh
This is a shell script that provides install options.
```shell
# Call swupdate with the image file and the public key for signature validation
swupdate -v -i "${image_file}" -k /adukey/public.pem -e ${selection} &>> $LOG_DIR/swupdate.log
```
#### boot.cmd.in
The boot.cmd.in looks for the 'selection' variable to know which partition to boot.
```shell
saveenv
fdt addr ${fdt_addr} && fdt get value bootargs /chosen bootargs
fatload mmc 0:1 ${kernel_addr_r} @@KERNEL_IMAGETYPE@@
if env exists rpipart;then setenv bootargs ${bootargs} root=/dev/mmcblk0p${rpipart}; fi
@@KERNEL_BOOTCMD@@ ${kernel_addr_r} - ${fdt_addr}
```

97
docs/how-adu-uses-iot-pnp.md
Просмотреть файл

@ -1,97 +0,0 @@
# Azure Device Update and IoT Plug and Play
Azure Device Update uses [IoT Plug and
Play](https://docs.microsoft.com/en-us/azure/iot-pnp/) to discover and manage
devices that are over-the-air update capable. ADU services will send and receive
properties and messages to and from devices using PnP interfaces. ADU requires
devices/clients implement the following interfaces and model-id as described below.
## Device Information
The [DeviceInformation](https://github.com/Azure/iot-plugandplay-models/) interface is a concept used within
the [Azure IoT Plug and Play](https://docs.microsoft.com/en-us/azure/iot-pnp/overview-iot-plug-and-play)
which contains device to cloud properties that
provide information about the hardware and operating system of the device. ADU uses the DeviceInformation.manufacturer
and DeviceInformation.model properties for telemetry and diagnostics. Learn more from this
`DeviceInformation` [example](https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json).
|Name|Type|Schema|Direction|Description|Description|
|----|----|------|---------|-----------|-----------|
|manufacturer|Property|string|device to cloud|Company name of the device manufacturer. This could be the same as the name of the original equipment manufacturer (OEM).|Contoso|
|model|Property|string|device to cloud|Device model name or ID.|IoT Edge Device|
|swVersion|Property|string|device to cloud|Version of the software on your device. This could be the version of your firmware.|4.15.0-122|
|osName|Property|string|device to cloud|Name of the operating system on the device.|Ubuntu Server 18.04|
|processorArchitecture|Property|string|device to cloud|Architecture of the processor on the device.|ARM64|
|processorManufacturer|Property|string|device to cloud|Name of the manufacturer of the processor on the device.|Microsoft|
|totalStorage|Property|string|device to cloud|Total available storage on the device in kilobytes.|2048|
|totalMemory|Property|string|device to cloud|Total available memory on the device in kilobytes.|256|
## Azure Device Update Core
The Azure Device Update Core (ADU Core) interface is used to send update
actions and metadata to devices and receive update status from devices. The ADU
Core interface is split into two Object properties.
### Agent Metadata
Agent Metadata contains fields that the device or ADU agent uses to send
information and status to ADU services.
|Name|Schema|Direction|Description|Example|
|----|------|---------|-----------|-----------|
|resultCode|integer|device to cloud|A code that contains information about the result of the last update action. Can be populated for either success or failure and should follow [http status code specification](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).|500|
|extendedResultCode|integer|device to cloud|A code that contains additional information about the result. Can be populated for either success or failure.|0x80004005|
|state|integer|device to cloud|This is an integer that indicates the current state of the ADU Agent. Values listed below.|Idle|
|installedUpdateId|string|device to cloud|An ID of the update that is currently installed (through ADU). This value will be null for a device that has never taken an update through ADU.|Null|
|deviceProperties|Map|device to cloud|The set of properties that contain the manufacturer and model.|See below section for details
### deviceProperties
|Name|Schema|Direction|Description|
|----|------|---------|-----------|
|manufacturer|string|device to cloud|The device manufacturer of the device, reported through DeviceProperties. This property is read from one of two places, first, the AzureDeviceUpdateCore interface will attempt to read the 'aduc_manufacturer' value from the [adu-conf.txt](././agent-reference/adu-conf.md) file. Second, if the value is not populated in adu-conf.txt, it will default to reporting the compile time definition for ADUC_DEVICEPROPERTIES_MANUFACTURER. This property will only be reported at boot time.|
|model|string|device to cloud|The device model of the device, reported through DeviceProperties. This property is read from one of two places, first, the AzureDeviceUpdateCore interface will attempt to read the 'aduc_model' value from the [adu-conf.txt](././agent-reference/adu-conf.md) file. Second, if the value is not populated in adu-conf.txt, it will default to reporting the compile time definition for ADUC_DEVICEPROPERTIES_MODEL. This property will only be reported at boot time.|
### State
The following `State` below represent when the ADU Agent reports a given state, after receiving an action from the ADU Service.
See the [overview workflow](./../src/agent/adu_core_interface/src/agent_workflow.c) of requests that flow between the ADU Service
and Agent. `State` is reported in response to an `Action` (see `Actions` section below) sent
to the ADU Agent from the ADU Service.
|Name|Value|Description|
|---------|-----|-----------|
|Idle|0|The device is ready to receive an action from the ADU Service. After a successful update, state is returned to the `Idle` state.|
|DownloadSucceeded|2|A successful download.|
|InstallSucceeded|4|A successful install.|
|Failed|255|A failure occurred during updating.|
### Service Metadata
Service Metadata contains fields that the ADU services use to communicate
actions and metadata to the device or agent.
|Name|Schema|Direction|Description|
|----|------|---------|-----------|
|action|integer|cloud to device|This is an integer that corresponds to an action the agent should perform. Values listed below.|
|updateManifest|string|cloud to device|Used to describe the content of an update. [Learn more](https://github.com/Azure/adu-private-preview/blob/master/docs/agent-reference/update-manifest.md) about the details of the Update Manifest and how ADU uses it to ensure the identity of the update, sent to a device.|
|updateManifestSignature|JSON Object|cloud to device|A JSON Web Signature (JWS) with JSON Web Keys used for source verification.|
|fileUrls|Map|cloud to device|Map of `FileHash` to `DownloadUri`. Tells the agent which files to download and the hash to use to verify the files were downloaded correctly.|
#### Action
The following `Actions` below represent the actions taken by the ADU Agent as instructed by the ADU Service.
See the [overview workflow](https://github.com/Azure/adu-private-preview/blob/master/src/agent/adu_core_interface/src/agent_workflow.c)
of requests that flow between the ADU Service and Agent. `Action` is received by the ADU Agent as an action from the ADU Service.
The ADU Agent will report a `State` (see `State` section above) processing the `Action` received.
|Name|Value|Description|
|---------|-----|-----------|
|Download|0|Download published content or update and any additional content needed|
|Install|1|Install the content or update. Typically this means calling the installer for the content or update.|
|Apply|2|Finalize the update. This will signal the system to reboot if necessary.|
|Cancel|255|Stop processing the current action and go back to `Idle`. Will also be used to tell the agent in the `Failed` state to go back to `Idle`.|
## Model Id
Configure your IoT Plug and Play device to announce the model id as part of the device connection with the value **"dtmi:AzureDeviceUpdate;1"** by following this [example](https://docs.microsoft.com/azure/iot-pnp/concepts-developer-guide-device-c#model-id-announcement). To learn more on how to build smart devices with IoT Plug and Play that advertise their capabilities to Azure IoT applications visit [IoT Plug and Play device developer guide](https://docs.microsoft.com/en-us/azure/iot-pnp/concepts-developer-guide-device-c).

56
docs/how-to-troubleshoot-guide.md
Просмотреть файл

@ -1,14 +1,10 @@
# Azure Device Update Troubleshooting Guide
# Troubleshooting Guide
This document provides a list of tips and tricks to help remedy many possible
issues you may be having with Azure Device Update.
Please check the Troubleshooting documentation first at [Device Update for IoT Hub](Aka.ms/iot-hub-device-update-docs) all issues. This document provides additional articles to help investigate Device update for IoT Hub Agent related issues.
## ADU Agent
## Device Update for IoT Hub Agent
If you run into issues with the ADU Agent, you have a couple options to help
troubleshoot. Start by collecting the ADU logs and/or query
[getDevices](docs/../management-api-reference/get-devices.md) to check for
additional information in the payload response of the API.
If you run into issues with the Device Update Agent, you have a couple options to help troubleshoot. Start by collecting the Device Update logs as shown below
### Collect Logs
@ -40,9 +36,9 @@ additional information in the payload response of the API.
### ResultCode and ExtendedResultCode
The Azure Device Update Core PnP interface reports `ResultCode` and
The 'ADUCoreInterface' interface reports `ResultCode` and
`ExtendedResultCode` which can be used to diagnose failures. [Learn
More](how-adu-uses-iot-pnp.md) about the ADU Core PnP interface.
More in Device Update Plug and Play](https://docs.microsoft.com/azure/iot-hub-device-update-docs/concepts-device-update-plug-and-play) about the 'ADUCoreInterface' interface.
#### ResultCode
@ -57,17 +53,21 @@ status codes.
You will most likely see the `ExtendedResultCode` as a signed integer in the PnP
interface. To decode the `ExtendedResultCode`, convert the signed integer to
unsigned hex. Only the first 4 bytes of the `ExtendedResultCode` are used and
are of the form `F` `FFFFFFF` where the first nibble is the **Facility Code** and
the rest of the bits are the **Error Code**.
are of the form `F` `FFFFFFF` where the first nibble is the *Facility Code* and
the rest of the bits are the *Error Code*.
**Facility Codes**
### Error Codes explained
* [Device Update for IoT Hub](https://github.com/Azure/iot-hub-device-update/blob/main/src/inc/aduc/result.h)
* [Delivery Optimization](https://github.com/microsoft/do-client/blob/main/client-lite/src/include/do_error.h)
### Facility Codes explained
| Facility Code | Description |
|-------------------|--------------|
| D | Error raised from the DO SDK|
| E | Error code is an errno |
For example:
`ExtendedResultCode` is `-536870781`
@ -79,31 +79,3 @@ The unsigned hex representation of `-536870781` is `FFFFFFFF E0000083`.
| FFFFFFFF | E | 0000083 |
`0x83` in hex is `131` in decimal which is the errno value for `ENOLCK`.
### Use getDevices() API payload response
A useful management API,
[getDevices](docs/../management-api-reference/get-devices.md), returns a payload
containing information about the download and update state on a device.
**NOTE**: This API's payload contains publicly accessible URL locations.
## Publish Update
Any issues encountered while importing a new manifest file or in any part of the
publishing flow,please let us know! To help us narrow down the root cause,
we'll need to capture some information.
* Time frame of when the problem occurred
* Fiddler traces from UX
* Screenshot of the UX
## Deploy Update
For any problems related to the deployment process of an update, please let us
know! To help us narrow down the root cause, we'll need to capture some
information.
* Time frame of when the problem occurred
* Fiddler traces from UX
* Screenshot of the UX

Двоичные данные
docs/images/client-agent-workflow.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 90 KiB

Двоичные данные
docs/images/client-agent-workflow_old.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 146 KiB

Двоичные данные
docs/images/import-an-update.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 77 KiB

Двоичные данные
docs/images/manage-deploy-updates.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 135 KiB

112
docs/quickstarts/how-to-agent-eval-pi-quickstart.md
Просмотреть файл

@ -1,112 +0,0 @@
# Getting Started with Raspberry Pi 3 B+ Reference Yocto Image
## Download Yocto image
There are three Yocto images available as a part of the "Assets" in a given
[ADU GitHub release](https://github.com/Azure/adu-private-preview/releases). The base image (adu-base-image) and two update images (adu-update-image) are provided so you can try rollouts to different versions without needing to flash the SD card on the
device. To do so, you'll need to upload the update images to the Azure Device Update
Service, as a part of the import.
## Flash SD card with image
Using your favorite OS flashing tool, install the Yocto ADU base image
(adu-base-image) on the SD Card that will be used in the Raspberry Pi 3 B+
device.
### Using bmaptool to flash SD card
1. If you have not already, install the `bmaptool` utility.
```shell
sudo apt-get install bmap-tools
```
2. Locate the path for the SD card in `/dev`. The path should look something
like `/dev/sd*` or `/dev/mmcblk*`. You can use the `dmesg` utility to help
locate the correct path.
3. You will need to un-mount all mounted partitions before flashing.
```shell
sudo umount /dev/<device>
```
4. Make sure you have write permissions to the device.
```shell
sudo chmod a+rw /dev/<device>
```
5. Optional. For faster flashing download the bmap file along with the image
file and place them in the same directory.
6. Flash the SD card.
```shell
sudo bmaptool copy <path to image> /dev/<device>
```
## Create device in IoT Hub and get connection string
Now, the device needs to be added to the Azure IoT Hub. From within the Azure
IoT Hub a connection string will be generated for the device.
1. From the Azure portal, launch the ADU IoT Hub.
2. Create a new device.
3. On the left-hand side of the page, navigate to 'Explorers' > 'IoT Devices' >
Select "New".
4. Provide a name for the device under 'Device ID' -- Ensure that "Auto-generate
keys" is checkbox is selected.
5. Select 'Save'.
6. Now you will be returned to the 'Devices' page and the device you just
created should be in the list. Select that device.
7. In the device view, select the 'Copy' icon next to 'Primary Connection
String'.
8. Paste the copied characters somewhere for later use in the steps below.
**This is your device connection string**.
## Provision connection string on SD card
1. Remove the SD card from the Raspberry Pi3, put it in your PC, and open it in
'File Explorer'. **NOTE**: You may see multiple prompts that the card is
unformatted. **Cancel all of them (do not format the card)**
2. In the remaining window, verify you see a partition or disk called `adu`.
3. **Optional**. In the `adu` partition directory, create the ADU Configuration file "adu-conf.txt" and open it. [Learn more](././../agent-reference/adu-conf.md) about configuring "adu-conf.txt".
4. Paste your previously saved device connection string into the text file.
**Example**: (replace your IoT Hub name, DeviceId, and shared access key with
those from your device connection string)
```markdown
connection_string=HostName=<yourIoTHubName>;DeviceId=<yourDeviceId>;SharedAccessKey=<yourSharedAccessKey>
```
5. Save the text file and then remove the SD card from your PC.
6. Insert the SD card into the Raspberry Pi3 and use the power switch on the
cord which is plugged into the device to turn the device on.
**NOTE**: Wait 1-2 mins to ensure the device is fully booted up. If you have a
monitor connected to the Raspberry Pi3, it will boot to a login screen. This is
normal. The agent will be running in the background. There is no need for you
to log in.
## Connect to device in ADU IoT Hub
1. On the left-hand side of the page, select 'IoT Devices' under 'Explorers'.
2. Select the link with your device name.
3. At the top of the page, select 'Device Twin'.
4. Under the 'reported' section of the device twin properties, look for the Linux kernel version.
For a new device, which hasn't received an update from ADU, the
[DeviceManagement:DeviceInformation:1.swVersion](./../how-adu-uses-iot-pnp.md) value will represent
the firmware version running on the device. Once an update has been applied to a device, ADU will
use [AzureDeviceUpdateCore:ClientMetadata:4.installedUpdateId](./../how-adu-uses-iot-pnp.md) property
value to represent the firmware version running on the device.
5. The base and update image files have a version number in the filename.
```markdown
adu-<image type>-image-<machine>-<version number>.<extension>
```
Use that version number in the step below.
**[Next Step: Import New Update](./how-to-import-quickstart.md)**

109
docs/quickstarts/how-to-agent-eval-sim-quickstart.md
Просмотреть файл

@ -1,109 +0,0 @@
# Getting Started Using Ubuntu (18.04 x64) Simulator Reference Agent
## Simulator Prerequisites
### Download and install
* Az (Azure CLI) cmdlets for PowerShell:
* Open PowerShell > Install Azure CLI ("Y" for prompts to install from "untrusted" source)
```powershell
PS> Install-Module Az -Scope CurrentUser
```
### Create a software device using WSL (Windows Subsystem for Linux)
1.Open PowerShell as Administrator on your machine and run the following command (you might be asked to restart after each step; restart when asked):
```powershell
PS> Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
PS> Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
```
(*You may be prompted to restart after this step*)
2.Go to the Microsoft Store on the web and install [Ubuntu 18.04 LTS](https://www.microsoft.com/p/ubuntu-1804-lts/9n9tngvndl3q?activetab=pivot:overviewtab`).
3.Start "Ubuntu 18.04 LTS" and install.
4.When installed, you will be asked to set root name (username) and password. Be sure to use a memorable root name password.
5.In PowerShell, run the following command to set Ubuntu to be the default Linux distribution:
```powershell
PS> wsl --setdefault Ubuntu-18.04
```
6.List all Linux distributions, make sure that Ubuntu is the default one.
```powershell
PS> wsl --list
```
7.You should see: **Ubuntu-18.04 (Default)**
## Download Ubuntu update agent
The Ubuntu update image can be downloaded from the *Assets* section from release notes [here](https://github.com/Azure/adu-private-preview/releases).
There are two versions of the agent. If you are exercising image based scenario use AducIotAgentSim-microsoft-swupdate and if you are exercising package based scenario use AducIotAgentSim-microsoft-apt.
## Install ADU Agent simulator
1.Start Ubuntu WSL and enter the following command (note that extra space and dot at the end).
```shell
explorer.exe .
```
2.Copy AducIotAgentSim-microsoft-swupdate (or AducIotAgentSim-microsoft-apt) from your local folder where it was downloaded under /mnt to your home folder inside of WSL.
3.Run the following command to make the binaries executable.
```shell
sudo chmod u+x AducIotAgentSim-microsoft-swupdate
```
or
```shell
sudo chmod u+x AducIotAgentSim-microsoft-apt
```
## Add device to Azure IoT Hub
Once the ADU Agent is running on an IoT device, the device needs to be added to the Azure IoT Hub. From within the Azure IoT Hub a connection string will be generated for a particular device.
1. From the Azure portal, launch the ADU IoT Hub.
2. Create a new device.
3. On the left-hand side of the page,, navigate to 'Explorers' > 'IoT Devices' > Select "New".
4. Provide a name for the device under 'Device ID' -- Ensure that "Auto-generate keys" is checkbox is selected.
5. Select 'Save'.
6. Now, you will be returned to the 'Devices' page and the device you just created should be in the list. Select that device.
7. In the device view, select the 'Copy' icon next to 'Primary Connection String'.
8. Paste the copied characters somewhere for later use in the steps below. **This is your device connection string**.
## Add connection string to simulator
Start ADU Agent on your new Software Devices.
1. Start Ubuntu.
2. Run the ADU Agent and specify the device connection string from the previous section wrapped with apostrophes:
```shell
./AducIotAgentSim-microsoft-swupdate '{device connection string}'
```
or
```shell
./AducIotAgentSim-microsoft-apt '{device connection string}'
```
3.Scroll up and look for the string indicating that the device is in "Idle" state, which means it is ready for service commands:
```markdown
Agent running. [main]
```
**[Next Step: Import New Update](./how-to-import-quickstart.md)**

72
docs/quickstarts/how-to-create-an-account.md
Просмотреть файл

@ -1,72 +0,0 @@
# Azure Device Update Resource Management
To get started with Device Update you will need to create a Device Update account, instance and set access control roles. If you have already been participating in the Device Update Preview, you can skip ahead to the "Configure IoT hub" and "Configure access control roles" below.
## Device Update Account and Instances
A Device Update account is a resource that is created within your Azure subscription. At the Device Update account level, you can select the region where your Device Update account will be created and set permissions to authorize users that will have access to Device Update.
After an account has been created, a Device Update instance must be created. An instance is a logical container that contains updates and deployments associated with a specific IoT hub. Device Update uses IoT hub as a device directory, and a communication channel with devices. For Private Preview, a single Device update account can be created per subscription, and two device update instances can be created with an account.
### Create a Device Update Account - New Preview Customers
1. Go to [Device Update Accounts](https://portal.azure.com/?microsoft_azure_marketplace_ItemHideKey=Microsoft_Azure_ADUHidden#blade/HubsExtension/BrowseResource/resourceType/Microsoft.DeviceUpdate%2FAccounts) in Azure Resource Marketplace
2. Click Add
3. Specify the Azure Subscription to be associated with your Device Update Account and Resource Group
4. Specify a Name and Location for your Device Update Account
5. Review the details and then select "Create"
### Create a Device Update Instance - New Preview Customers
An instance of Device Update is associated with a single IoT hub. Select the IoT hub that will be used with Device Update. We will create a new Shared Access policy during this step to ensure Device Update uses only the required permissions to work with IoT Hub (registry write and service connect) and access is only limited to Device Update.
To create a Device Update instance after an account has been created.
1. Go to the Instance Management "Instances" page
2. Specify an instance name and select the IoT Hub
3. Click "Create"
### Configure IoT Hub - All Preview Customers
In order for Device Update to receive change notifications from IoT Hub, Device Update integrates with the "Built-In" Event Hub. Message routes will need to be configured if you are new to the preview or updated if you have been participating in the Device Update Private Preview. We will also update the Shared Access policy if this is not configured correctly.
To configure IoT Hub
1. Go to the Instance Management "Instances" page
2. Select the Instance that has been created for you and then click "Configure IoT Hub"
3. Select "I agree to make these changes"
4. Click "Update"
#### Message Routes that are configured
| Route Name | Routing Query | Description |
| :--------- | :---- |:---- |
| DeviceUpdate.DigitalTwinChanges | true |Listens for Digital Twin Changes Events |
| DeviceUpdate.DeviceLifeCycle | opType = 'deleteDeviceIdentity' | Listens for Devices that have been deleted |
| DeviceUpdate.TelemetryModelInformation | iothub-interface-id = "urn:azureiot:ModelDiscovery:ModelInformation:1 | Listens for new devices types |
| DeviceUpdate.DeviceTwinEvents| (opType = 'updateTwin' OR opType = 'replaceTwin') AND IS_DEFINED($body.tags.ADUGroup) | Listens for new Device Update Groups |
### Configure access control roles - All Preview Customers
In order for other users to have access to Device Update, users must be granted access to this resource. Here are the roles that are supported by Device Update
| Role Name | Description |
| :--------- | :---- |
| Device Update Administrator | Has access to all device update resources |
| Device Update Reader| Can view all updates and deployments |
| Device Update Content Administrator | Can view, import, and delete updates |
| Device Update Content Reader | Can view updates |
| Device Update Deployments Administrator | Can manage deployment of updates to devices|
| Device Update Deployments Reader| Can view deployments of updates to devices |
A combination of roles can be used to provide the right level of access, for example a developer can import and manage updates using the Device Update Content Administrator role, but can view the progress of an update using the Device Update Deployments Reader role. Conversely, a solution operator can have the Device Update Reader role to view all updates, but can use the Device Update Deployments Administrator role to deploy a specific update to devices.
#### To set the Access Control Policy
1. Go to Access control (IAM)
2. Click "Add" within "Add a role assignment"
3. For "Select a Role", select "Device Update Administrator"
4. Assign access to a user or Azure AD group
5. Click Save
6. You can now go to IoT Hub and go to Device Update

55
docs/quickstarts/how-to-deploy-quickstart.md
Просмотреть файл

@ -1,55 +0,0 @@
# Deploy Update
## Prerequisites
* Access to an IoT Hub with Azure Device Update (ADU) enabled.
* At least one update has been successfully imported for the provisioned device.
* An IoT device (or simulator) provisioned within the IoT Hub, running either Azure RTOS or Ubuntu 18.04 x64.
* A tag has been assigned to the IoT device you are trying to update, and it is part of at least one update group
## Deploy an update
1. Go to [Azure Portal](https://ms.portal.azure.com/?feature.canmodifystamps=true&Microsoft_Azure_Iothub=aduprod&microsoft_azure_marketplace_ItemHideKey=Microsoft_Azure_ADUHidden&feature.devicetwin=true#home)
2. Navigate to the Device Update blade your IoT Hub.
![IoT Hub](images/adu-iot-hub.PNG)
3. Select the Groups tab at the top of the page.
![Groups Tab](images/updated-view.PNG)
4. View the update compliance chart and groups list. You should see a new update available for your device group, with a link to the update under Pending Updates (you may need to Refresh once). [Learn More](../adu-compliance.md) about update compliance.
![Available Update](images/available-update.PNG)
5. Select the available update
6. Confirm the correct group is selected as the target group. Schedule your deployment, then select Deploy update.
![Select Update](images/select-update.PNG)
7. View the compliance chart. You should see the update is now in progress.
![Update in progress](images/update-in-progress.PNG)
8. After your device is successfully updated, you should see your compliance chart and deployment details update to reflect the same.
![Update succeeded](images/update-succeeded.PNG)
## Monitor an update deployment
1. Select the Deployments tab at the top of the page.
![Deployments Tab](images/deployments-tab.PNG)
2. Select the deployment you created to view the deployment details.
![Deployment Details](images/deployment-details.PNG)
3. Select Refresh to view the latest status details. Continue this process until the status changes to Succeeded.
## Retry an update deployment
If your deployment fails for some reason, you can retry the deployment for failed devices.
1. Go to the Deployments tab, and select the deployment that has failed.
![Deployment Details](images/deployment-details.PNG)
2. Click on the "Failed" Device Status in the detailed Deployment information pane.
3. Click on "Retry failed devices" and acknowledge the confirmation pop-up.

97
docs/quickstarts/how-to-group-quickstart.md
Просмотреть файл

@ -1,97 +0,0 @@
en Groups_tag_Device_twin and release/v0.3.0-private-preview and committing changes Groups_tag_Device_twin
# Create Groups
## Prerequisites
* Access to an IoT Hub with Azure Device Update (ADU) enabled.
* At least one update has been successfully imported for the provisioned device.
* An IoT device (or simulator) provisioned within the IoT Hub, running either Azure RTOS or Ubuntu 18.04 x64.
## Add a tag to your devices
**NOTE**: Tags can only be successfully added to your device after it has been connected to ADU
Azure Device Update allows deploying an update to a group of IoT devices. To create a group, the first step is to add a tag to the target set of devices in IoT Hub. The below documentation describes how to add and update a tag.
### 1. Programmatically update Device Twin
You can update the Device Twin with the appropriate Tag using RegistryManager after enrolling the device with ADU. [Learn More](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-csharp-csharp-twin-getstarted) about how to add tags using a sample .NET app. Learn more about [tag properties](https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-device-twins#tags-and-properties-format).
### Device Update Tag Format
```markdown
"tags": {
"ADUGroup": "<CustomTagValue>"
}
```
### 2. Using Jobs
It is possible to schedule a Job on multiple devices to add or update an Device Update tag following [these](https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-jobs) examples. [Learn more](https://docs.microsoft.com/azure/iot-hub/iot-hub-csharp-csharp-schedule-jobs).
**Note**: This action goes against your current IOT Hub messages quota and it is recommended to change only upto 50,000 device twin Tags at a time otherwise you may need to buy additional IoT Hub units if you exceed your daily IoT Hub message quota. Details can be found at [Quotas and throttling](https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-quotas-throttling#quotas-and-throttling).
### 3. Direct Twin Updates
Tags can also be added or updated in device twin directly.
1. Log into Azure Portal using [this](https://portal.azure.com/?feature.canmodifystamps=true&Microsoft_Azure_Iothub=aduprod) link and navigate to your IoT Hub.
2. From 'IoT Devices' or 'IoT Edge' on the left navigation pane find your IoT device and navigate to the Device Twin.
3. In the Device Twin, delete any existing ADU tag value by setting them to null.
4. Add a new ADU tag value as shown below. [Example](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins#device-twins) device twin JSON document with tags.
```JSON
"tags": {
"ADUGroup": "<CustomTagValue>"
}
```
### Limitations
* You can add any value to your tag except for ‘Uncategorized’ which is a reserved value.
* Tag value cannot exceed 255 characters.
* Tag value can contain alphanumeric characters and the following special characters ".","-","_","~".
* Tag and Group names are case sensitive.
* A device can only have one tag with the name ADUGroup, any subsequent additions of a tag with that name will override the existing value for tag name ADUGroup.
Groups_tag_Device_twin
=======
* One device can only belong to one Group.
## Create a group by selecting an existing IoT Hub tag
1. Go to the [Azure Portal](https://ms.portal.azure.com/?feature.canmodifystamps=true&Microsoft_Azure_Iothub=aduprod&microsoft_azure_marketplace_ItemHideKey=Microsoft_Azure_ADUHidden&feature.devicetwin=true#home).
2. Select the IoT Hub you previously connected to your ADU instance.
3. Select the Device Updates option under Automatic Device Management from the left-hand navigation bar.
4. Select the Groups tab at the top of the page. You will be able to see the number of devices connected to Device Update that are not grouped yet.
![Ungrouped Devices](images/ungrouped-devices.PNG)
5. Select the Add button to create a new group.
![Add Group](images/add-group.PNG)
6. Select an IoT Hub tag from the list and then select Create update group.
![Select Tag](images/select-tag.PNG)
7. Once the group is created you will see that the update compliance chart and groups list are updated. Update compliance chart shows the count of devices in various states of compliance: On latest update, New updates avaialable, Updates in Progress and Devices not yet Grouped. [Learn More](../adu-compliance.md) about update compliance.
![Updated View](images/updated-view.PNG)
8. You should see your newly created group and any available updates for the devices in the new group. You can deploy the update to the new group from this view by clicking on the update name. See Next Step: Deploy Update for more details.
## View Device details for the group you created
1. Navigate to your newly created group and click on the group name.
2. A list of devices that are part of the group will be shown along with their device update properties. In this view you can also see the update compliance information for all devices that are members of the group. Update compliance chart shows the count of devices in various states of compliance: On latest update, New updates available and Updates in Progress.
![Group Details View](images/group-details.PNG)
3. You can also click on each individual device within a group to be redirected to the device details page in IoT Hub.
![Device Details View](images/device-details.PNG)
[Next Step: Deploy Update](./how-to-deploy-quickstart.md)

137
docs/quickstarts/how-to-import-quickstart.md
Просмотреть файл

@ -1,137 +0,0 @@
# Import New Update
## Prerequisites
* Access to an IoT Hub with Azure Device Update (ADU) enabled.
* An IoT device (or [simulator](./how-to-agent-eval-sim-quickstart.md)) provisioned within the IoT Hub, running either Azure RTOS ThreadX or Ubuntu 18.04 x64.
* If using a real device, you’ll need an update image file (e.g. Yocto image) for image update, or [APT Manifest](../agent-reference/apt-manifest.md) file for package update.
* [PowerShell 5]((https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell)) or later.
* Supported browsers:
* The new [Microsoft Edge](https://www.microsoft.com/edge)
* Google Chrome
## Create ADU Import Manifest
1. Ensure that your update image file or APT Manifest file is located in a directory accessible from PowerShell.
2. Clone [Azure Device Update repository](https://github.com/Azure/adu-private-preview), or download it as a .zip file to
a location accessible from PowerShell (Once the zip file is downloaded, right click for `Properties` > `General` tab > check `Unblock` in the `Security` section to avoid PowerShell security warning prompts).
3. In PowerShell, navigate to `tools/AduCmdlets` directory and run:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
Import-Module .\AduUpdate.psm1
```
4. Run the following commands by replacing the sample parameter values to generate an import manifest, a JSON file that describes the update:
```powershell
$compat = New-AduUpdateCompatibility -DeviceManufacturer 'deviceManufacturer' -DeviceModel 'deviceModel'
$importManifest = New-AduImportManifest -Provider 'updateProvider' -Name 'updateName' -Version 'updateVersion' `
-UpdateType 'updateType' -InstalledCriteria 'installedCriteria' `
-Compatibility $compat -Files 'updateFilePath(s)'
$importManifest | Out-File '.\importManifest.json' -Encoding UTF8
```
For quick reference, the table below provides some example values for the above parameters. For full documentation, please refer to [Import Manifest Schema](../publish-api-reference/import-update.md#import-manifest-schema).
| Parameter | Description |
| --------- | ----------- |
| deviceManufacturer | Manufacturer of the device the update is compatible with, e.g. Contoso
| deviceModel | Model of the device the update is compatible with, e.g. Toaster
| updateProvider | Provider part of update identity, e.g. Fabrikam
| updateName | Name part of update identity, e.g. ImageUpdate
| updateVersion | Update version, e.g. 2.0
| updateType | <ul><li>Specify `microsoft/swupdate:1` for image update</li><li>Specify `microsoft/apt:1` for package update</li></ul>
| installedCriteria | <ul><li>Specify value of SWVersion for `microsoft/swupdate:1` update type</li><li>Specify [recommended value](../agent-reference/apt-manifest.md) for `microsoft/apt:1` update type.
| updateFilePath(s) | Path to the update file(s) on your PC
The update imported using import manifest generated above will be deployable to devices implementing [Azure Device Update PnP interface](../how-adu-uses-iot-pnp.md) `urn:azureiot:AzureDeviceUpdateCore:1` and `urn:azureiot:AzureDeviceUpdateCore:4`.
## Review Generated Import Manifest
Example:
```json
{
"updateId": {
"provider": "Microsoft",
"name": "Toaster",
"version": "2.0"
},
"updateType": "microsoft/swupdate:1",
"installedCriteria": "5",
"compatibility": [
{
"deviceManufacturer": "Fabrikam",
"deviceModel": "Toaster"
},
{
"deviceManufacturer": "Contoso",
"deviceModel": "Toaster"
}
],
"files": [
{
"filename": "file1.json",
"sizeInBytes": 7,
"hashes": {
"sha256": "K2mn97qWmKSaSaM9SFdhC0QIEJ/wluXV7CoTlM8zMUo="
}
},
{
"filename": "file2.zip",
"sizeInBytes": 11,
"hashes": {
"sha256": "gbG9pxCr9RMH2Pv57vBxKjm89uhUstD06wvQSioLMgU="
}
}
],
"createdDateTime": "2020-10-08T03:32:52.477Z",
"manifestVersion": "2.0"
}
```
## Import update
1. Log into Azure Portal using [this link](https://portal.azure.com/?feature.canmodifystamps=true&Microsoft_Azure_Iothub=aduprod) and navigate to your IoT Hub with ADU.
2. On the left-hand side of the page, select "Device Updates" under "Automatic Device Management".
![Import Updates](images/import-updates2.png)
3. You will see several tabs across the top of the screen. Select the Updates tab.
![Import New Updates](images/updates-tab.png)
4. Select "+ Import New Update" below the "Ready to Deploy" header.
![Import New Updates](images/import-new-update2.png)
5. Select the folder icon or text box under "Select an Import Manifest File". You will see a file picker dialog. Select the Import Manifest you created previously using the PowerShell cmdlet. Next, select the folder icon or text box under "Select one or more update files". You will see a file picker dialog. Select your update file(s).
![Select Update Files](images/select-update-files.png)
6. Select the folder icon or text box under "Select a storage container". Then select the appropriate storage account.
![Storage Account](images/storage-account.png)
7. If you’ve already created a container you can re-use it. (Otherwise, select "+ Container" to create a new storage container for updates.). Select the container you wish to use and click "Select".
![Container](images/container.png)
8. Select "Submit" to start the import process.
![Import Update](images/publish-update.png)
9. The import process begins, and the screen changes to the "Import History" section. Select "Refresh" to view progress until the import process completes (depending on the size of the update, this may complete in a few minutes but could take longer).
![Update Import Sequencing](images/update-publishing-sequence2.png)
10. When the Status column indicates the import has succeeded, select the "Ready to Deploy" header. You should see your imported update in the list now.
![Job Status](images/update-ready.png)
[Next Step: Create Groups](./how-to-group-quickstart.md)

70
docs/quickstarts/how-to-package-agent-quickstart.md
Просмотреть файл

@ -1,70 +0,0 @@
# Getting Started using Ubuntu Server 18.04 x64 Package agent
## Setting up update agents
### Download update agent packages
Download the latest .deb packages from the specified location and copy them to
your pre-provisioned Azure IoT Edge device running Ubuntu Server 18.04 x64.
Delivery Optimization Plugin: Download [here](https://github.com/microsoft/do-client/releases)
Delivery Optimization SDK: Download [here](https://github.com/microsoft/do-client/releases)
Delivery Optimization Agent: Download [here](https://github.com/microsoft/do-client/releases)
ADU Agent: Download [here](https://github.com/Azure/adu-private-preview/releases)
### Install ADU .deb agent packages
1. Copy over your downloaded .deb packages to your IoT Edge device from your host machine using Powershell.
```shell
PS> scp '<PATH_TO_DOWNLOADED_FILES>\*.deb' <USERNAME>@<EDGE IP ADDRESS>:~
```
2.Use apt-get to install the packages in the specified order
* Delivery Optimization Agent (deliveryoptimization-agent)
* Delivery Optimization SDK (libdeliveryoptimization)
* Delivery Optimization Plugin for APT (deliveryoptimization-plugin-apt)
* ADU Agent (adu-agent)
```shell
sudo apt-get -y install ./<NAME_OF_PACKAGE>.deb
```
### Configure ADU Agent
1. Open the ADU configuration file
```shell
sudo nano /etc/adu/adu-conf.txt
```
2.Provide your primary connection string in the configuration file. A device's connection string can be found in Azure Portal, in the IOT Edge device blade, in the device details page after clicking on the device.
3.Press Ctrl+X, Y, Enter to save and close the file
4.Restart the ADU Agent daemon
```shell
sudo systemctl restart adu-agent
```
5.Optionally, you can verify that the services are running by
```shell
sudo systemctl list-units --type=service | grep 'adu-agent\.service\|deliveryoptimization-agent\.service'
```
The output should read:
```markdown
adu-agent.service loaded active running Azure Device Update Agent daemon.
deliveryoptimization-agent.service loaded active running deliveryoptimization-agent.service: Performs content delivery optimization tasks `
```
**[Next Step: Import New Update](./how-to-import-quickstart.md)**

Двоичные данные
docs/quickstarts/images/add-group.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 45 KiB

Двоичные данные
docs/quickstarts/images/adu-iot-hub.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 87 KiB

Двоичные данные
docs/quickstarts/images/available-update.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 57 KiB

Двоичные данные
docs/quickstarts/images/confirm-swversion.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 99 KiB

Двоичные данные
docs/quickstarts/images/container.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 44 KiB

Двоичные данные
docs/quickstarts/images/content-listed.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 116 KiB

Двоичные данные
docs/quickstarts/images/create-new-group.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 98 KiB

Двоичные данные
docs/quickstarts/images/deployment-details.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 69 KiB

Двоичные данные
docs/quickstarts/images/deployments-tab.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 47 KiB

Двоичные данные
docs/quickstarts/images/device-details.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 134 KiB

Двоичные данные
docs/quickstarts/images/device-twin-summary.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 116 KiB

Двоичные данные
docs/quickstarts/images/group-details.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 78 KiB

Двоичные данные
docs/quickstarts/images/import-new-update.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 110 KiB

Двоичные данные
docs/quickstarts/images/import-new-update2.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 12 KiB

Двоичные данные
docs/quickstarts/images/import-updates.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 76 KiB

Двоичные данные
docs/quickstarts/images/import-updates2.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 59 KiB

Двоичные данные
docs/quickstarts/images/iot-hub-adu.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 157 KiB

Двоичные данные
docs/quickstarts/images/publish-update.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 91 KiB

Двоичные данные
docs/quickstarts/images/select-device.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 116 KiB

Двоичные данные
docs/quickstarts/images/select-new-group.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 84 KiB

Двоичные данные
docs/quickstarts/images/select-tag.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 51 KiB

Двоичные данные
docs/quickstarts/images/select-update-files.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 58 KiB

Двоичные данные
docs/quickstarts/images/select-update.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 31 KiB

Двоичные данные
docs/quickstarts/images/storage-account.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 40 KiB

Двоичные данные
docs/quickstarts/images/ungrouped-devices.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 162 KiB

Двоичные данные
docs/quickstarts/images/update-in-progress.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 57 KiB

Двоичные данные
docs/quickstarts/images/update-publishing-sequence.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 96 KiB

Двоичные данные
docs/quickstarts/images/update-publishing-sequence2.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 16 KiB

Двоичные данные
docs/quickstarts/images/update-ready.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 16 KiB

Двоичные данные
docs/quickstarts/images/update-succeeded.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 59 KiB

Двоичные данные
docs/quickstarts/images/updated-view.PNG
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 57 KiB

Двоичные данные
docs/quickstarts/images/updates-tab.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 15 KiB

23
docs/quickstarts/overview-quickstart.md
Просмотреть файл

@ -1,23 +0,0 @@
# Azure Device Update Documentation
Learn how to use Azure Device Update (ADU) to publish and manage update content to Internet of Things (IoT) devices. Tutorials, API references, videos and other documentation help you deploy reliable and secure updates between IoT devices and IoT Hub.
The following documentation will guide you through the three main areas in getting started Azure Device Update service.
## Getting Started - Image-based Updating
To get started using ADU you'll need to ensure your devices are running the ADU Agent. For simplicity, we have provided pre-built images and binaries for a quick and easy demonstration of the ADU product. You will need either a Raspberry Pi 3 B+ or Ubuntu 18.04 x64, depending on whether you'd prefer using a device or simulator.
* [**Getting Started Using Yocto with Raspberry Pi 3 B+ Reference Agent**](how-to-agent-eval-pi-quickstart.md)
* [**Getting Started Using Ubuntu 18.04 x64 Simulator Reference Agent**](how-to-agent-eval-sim-quickstart.md)
## Getting Started - Package-based Updating
To get started using ADU you'll need to ensure your devices are running the ADU Agent. We have provided a package-based agent that you can install on your device to exercise the end-to-end updating capabilities of ADU. You will need an IoT device or Azure IoT Edge device running Ubuntu Server 18.04 x64.
* [**Getting Started Using Ubuntu Server 18.04 x64 Package Agent**](how-to-package-agent-quickstart.md)
## Troubleshooting Guide
If you run into issues, please review the Azure Device Update [Troubleshooting Guide](../how-to-troubleshoot-guide.md) to help unblock any possible issues and/or collect necessary information to provide to Microsoft ADU team.

10
docs/sample-artifacts/libcurl4-doc-7.58-apt-manifest.json Normal file
Просмотреть файл

@ -0,0 +1,10 @@
{
"name": "Sample package update 2",
"version": "2.0.1",
"packages": [
{
"name": "libcurl4-doc",
"version": "7.58.0-2ubuntu3.12"
}
]
}

9
docs/sample-artifacts/libcurl4-doc-apt-manifest.json Normal file
Просмотреть файл

@ -0,0 +1,9 @@
{
"name": "Sample package update",
"version": "1.0.1",
"packages": [
{
"name": "libcurl4-doc"
}
]
}

9
docs/sample-artifacts/libcurl4-doc-remove-apt-manifest.json Normal file
Просмотреть файл

@ -0,0 +1,9 @@
{
"name": "Sample package update",
"version": "1.0.2",
"packages": [
{
"name": "libcurl4-doc-"
}
]
}

26
docs/sample-artifacts/sample-package-update-1.0.1-importManifest.json Normal file
Просмотреть файл

@ -0,0 +1,26 @@
{
"updateId": {
"provider": "Contoso",
"name": "SampleUpdate1",
"version": "1.0.1"
},
"updateType": "microsoft/apt:1",
"installedCriteria": "Sample package update-1.0.1",
"compatibility": [
{
"deviceManufacturer": "Contoso",
"deviceModel": "Video"
}
],
"files": [
{
"filename": "libcurl4-doc-apt-manifest.json",
"sizeInBytes": 154,
"hashes": {
"sha256": "G9gVz4WqTRu/cXfRjNMbpENxEuAXqlT0E1vLOgaMICw="
}
}
],
"createdDateTime": "2021-02-23T04:35:22.4375560Z",
"manifestVersion": "2.0"
}

26
docs/sample-artifacts/sample-package-update-1.0.2-importManifest.json Normal file
Просмотреть файл

@ -0,0 +1,26 @@
{
"updateId": {
"provider": "Contoso",
"name": "SampleUpdate",
"version": "1.0.2"
},
"updateType": "microsoft/apt:1",
"installedCriteria": "Sample package update-1.0.2",
"compatibility": [
{
"deviceManufacturer": "Contoso",
"deviceModel": "Video"
}
],
"files": [
{
"filename": "libcurl4-doc-remove-apt-manifest.json",
"sizeInBytes": 155,
"hashes": {
"sha256": "RL/OBnj5kQ/0VsQ1C+pb7NnUvYCpzFZEkb5buCLoJWU="
}
}
],
"createdDateTime": "2021-02-23T04:35:22.6533536Z",
"manifestVersion": "2.0"
}

26
docs/sample-artifacts/sample-package-update-2-2.0.1-importManifest.json Normal file
Просмотреть файл

@ -0,0 +1,26 @@
{
"updateId": {
"provider": "Contoso",
"name": "SampleUpdate2",
"version": "2.0.1"
},
"updateType": "microsoft/apt:1",
"installedCriteria": "Sample package update 2-2.0.1",
"compatibility": [
{
"deviceManufacturer": "Contoso",
"deviceModel": "Video"
}
],
"files": [
{
"filename": "libcurl4-doc-7.58-apt-manifest.json",
"sizeInBytes": 202,
"hashes": {
"sha256": "6B0XlSRRZiUxjTgEzFImEMd76VwlERbzdRSYU3PfpHY="
}
}
],
"createdDateTime": "2021-02-23T04:35:22.7946429Z",
"manifestVersion": "2.0"
}

59
tools/ServiceSDKs/Java/README.md
Просмотреть файл

@ -1,59 +0,0 @@
# Azure Device Update client library for Java
The library provides access to the Azure Device Update service that enables customers to publish updates for their IoT devices to the cloud, and then deploy these updates to their devices (approve updates to groups of devices managed and provisioned in IoT Hub).
## Getting started
The complete Microsoft Azure SDK can be downloaded from the [Microsoft Azure Downloads](https://azure.microsoft.com/en-us/downloads/?sdk=net) page and ships with support for building deployment packages, integrating with tooling, rich command line tooling, and more.
For the best development experience, developers should use the official Microsoft NuGet packages for libraries. NuGet packages are regularly updated with new functionality and hotfixes.
### Prerequisites
- Microsoft Azure Subscription: To call Microsoft Azure services, you need to create an [Azure subscription](https://azure.microsoft.com/free/)
- Azure Device Update instance
- Azure IoT Hub instance
### Authenticate the client
In order to interact with the Azure Device Update service, you will need to create an instance of a [TokenCredential class](https://docs.microsoft.com/en-us/dotnet/api/azure.core.tokencredential?view=azure-dotnet) and pass it to the constructor of your AzureDeviceUpdateClientBuilder class.
## Key concepts
Azure Device Update is a managed service that enables you to deploy over-the-air updates for your IoT devices. The client library has three main components:
- **Updates**: update management (import, enumerate, delete, etc.)
- **Devices**: device management (enumerate devices and retrieve device properties)
- **Deployments**: deployment management (start and monitor update deployments to a set of devices)
You can learn more about Azure Device Update by visiting [Azure Device Updates](https://github.com/Azure/adu-private-preview/tree/release/v0.2.0-private-preview).
## Troubleshooting
All Azure Device Update service operations will throw a ErrorResponseException on failure with helpful ErrorCodes.
For example, if you use the `getUpdateAsync` operation and the model you are looking for doesn't exist, you can catch that specific [HttpStatusCode](https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?view=netcore-3.1) to decide the operation that follows in that case.
```java
try {
Update update = client.getUpdates().getUpdateAsync(
"provider", "name", "1.0.0.0")
.block();
}
catch (HttpResponseException ex) {
if (ex.getResponse().getStatusCode() == 404) {
// Update does not exist.
}
}
```
## Next steps
Get started with our Azure Device Update Java [samples](https://github.com/Azure/adu-private-preview-sdk/tree/main/Java/Java%20Samples), [libraries](https://github.com/Azure/adu-private-preview-sdk/tree/main/Java/Library) and [swagger](https://github.com/Azure/adu-private-preview-sdk/tree/main/Swagger)
Please send an email to aduprivatepreviewsdk@microsoft.com to request access to these links.
## Contributing
If you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-net/issues) section of the project.

66
tools/ServiceSDKs/NET/README.md
Просмотреть файл

@ -1,66 +0,0 @@
# Azure Device Update client library for .NET
The library provides access to the Azure Device Update service that enables customers to publish updates for their IoT devices to the cloud, group their IoT devices and then deploy these updates to their device groups.
[Azure Device Update product documentation](https://github.com/Azure/adu-private-preview/blob/master/docs/adu-overview.md)
## Getting started
The complete Microsoft Azure SDK can be downloaded from the [Microsoft Azure Downloads](https://azure.microsoft.com/en-us/downloads/?sdk=net) page and ships with support for building deployment packages, integrating with tooling, rich command line tooling, and more.
For the best development experience, developers should use the official Microsoft NuGet packages for libraries. NuGet packages are regularly updated with new functionality and hotfixes.
### Prerequisites
- Microsoft Azure Subscription: To call Microsoft Azure services, you need to create an [Azure subscription](https://azure.microsoft.com/free/)
- Azure Device Update instance
- Azure IoT Hub instance
### Install the package
Install the Azure Device Update [client library for .NET](https://github.com/Azure/adu-private-preview-sdk/tree/main/NET/Library) by adding a reference to Azure.Iot.DeviceUpdate.dll assembly to your project.
### Authenticate the Client
In order to interact with the Azure Device Update service, you will need to create an instance of a [TokenCredential class](https://docs.microsoft.com/en-us/dotnet/api/azure.core.tokencredential?view=azure-dotnet) and pass it to the constructor of your UpdateClient, DeviceClient and DeploymentClient class.
## Key concepts
Azure Device Update is a managed service that enables you to deploy over-the-air updates for your IoT devices. The client library has three main components:
- **UpdatesClient**: update management (import, enumerate, delete, etc.)
- **DevicesClient**: device management (enumerate devices and retrieve device properties)
- **DeploymentsClient**: deployment management (start and monitor update deployments to a set of devices)
## Troubleshooting
All Azure Device Update service operations will throw a RequestFailedException on failure with helpful ErrorCodes.
For example, if you use the `GetUpdateAsync` operation and the model you are looking for doesn't exist, you can catch that specific [HttpStatusCode](https://docs.microsoft.com/en-us/dotnet/api/system.net.httpstatuscode?view=netcore-3.1) to decide the operation that follows in that case.
```csharp
try
{
Response<Update> update = await _updatesClient.GetUpdateAsync(
"provider", "name", "1.0.0.0")
.ConfigureAwait(false);
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
{
// Update does not exist.
}
```
## Examples and next steps
Get started with our Azure Device Update .NET [samples](https://github.com/Azure/adu-private-preview-sdk/tree/main/NET/NET%20Samples), [libraries](https://github.com/Azure/adu-private-preview-sdk/tree/main/NET/Library) and [swagger](https://github.com/Azure/adu-private-preview-sdk/tree/main/Swagger)
Please send an email to aduprivatepreviewsdk@microsoft.com to request access to these links.
## Contributing
If you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-net/issues) section of the project.

16
tools/ServiceSDKs/Overview.md
Просмотреть файл

@ -1,16 +0,0 @@
# Client Libraries for Azure Device Updates
We have various client libraries available for Azure Device Updates. These libraries provides access to the Azure Device Update service that enables customers to publish updates for their IoT devices to the cloud, group their IoT devices and then deploy these updates to their device groups. Please send an email to aduprivatepreviewsdk@microsoft.com to request access if you can't access the Swagger link below.
* [.NET](./NET/README.md)
* [Python](./Python/README.md)
* [Java](./Java/README.md)
* [Swagger](https://github.com/Azure/adu-private-preview-sdk/tree/main/Swagger)
## 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](https://opensource.microsoft.com/codeofconduct/). For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

44
tools/ServiceSDKs/Python/README.md
Просмотреть файл

@ -1,44 +0,0 @@
# Azure Device Update client library for Python
The library provides access to the Azure Device Update service that enables customers to publish updates for their IoT devices to the cloud, group their IoT devices and then deploy these updates to their device groups.
[Azure Device Update product documentation](https://github.com/Azure/adu-private-preview/blob/master/docs/adu-overview.md)
## Getting started
### Prerequisites
- Microsoft Azure Subscription: To call Microsoft Azure services, you need to create an [Azure subscription](https://azure.microsoft.com/free/)
- Azure Device Update instance
- Azure IoT Hub instance
- Python 2.7, or 3.5 or later is required to use this package.
### Install the package
Install the Azure Device Update client library for Python with [pip](https://pypi.org/project/pip/):
```
pip install {your_local_path_to}azure_deviceupdate-0.0.0.1-py2.py3-none-any.whl
pip install azure-identity
```
## Key concepts
Azure Device Update is a managed service that enables you to deploy over-the-air updates for your IoT devices. The client library has one main component named **AzureDeviceUpdateServiceDataPlane**. The component allows you to access all three main client services:
- **UpdatesOperations**: update management (import, enumerate, delete, etc.)
- **DevicesOperations**: device management (enumerate devices and retrieve device properties)
- **DeploymentsOperations**: deployment management (start and monitor update deployments to a set of devices)
## Troubleshooting
The Azure Device Update client will raise exceptions defined in [Azure Core][azure_core].
## Examples and next steps
Get started with our Azure Device Update Python [samples](https://github.com/Azure/adu-private-preview-sdk/tree/main/Python/Python%20Samples), [libraries](https://github.com/Azure/adu-private-preview-sdk/tree/main/Python/Libraries) and [swagger](https://github.com/Azure/adu-private-preview-sdk/tree/main/Swagger)
Please send an email to aduprivatepreviewsdk@microsoft.com to request access to these links.
## Contributing
If you encounter any bugs or have suggestions, please file an issue in the [Issues](https://github.com/Azure/azure-sdk-for-python/issues) section of the project.