pw_software_update: Guide#
Pigweed AI summary: The pw_software_update guide provides suggestions for updating software on an embedded system, with common patterns for each scenario. The guide outlines high-level steps for setting up an end-to-end software delivery system, including getting familiar with pw_software_update, enabling local and remote updates, preparing for launching, and ensuring a smooth rollout. The guide also includes sections on integrating with verified boot, A/B updates, managing delta updates, revoking bad releases, and stepping-stone releases.
How you update software on an embedded system is specific to the project. However, there are common patterns. This section provides suggestions for each scenario, which you can then adjust to fit your specific needs.
High-level steps#
Pigweed AI summary: Setting up an end-to-end software delivery system involves several high-level steps, including getting familiar with pw_software_update, enabling local and remote updates for development and internal testing, preparing for launching, and ensuring a smooth rollout. Each step involves various tasks, such as producing update bundles, supporting remote updates, preparing for test-key signing, validating and endorsing builds, and producing well-secured updates. Additional topics to document include integrating with verified boot, doing A/B updates, managing delta updates, revoking
Setting up an end-to-end software delivery system can seem overwhelming, but generally involves the following high-level steps.
Get familiar with
pw_software_update.Enable local updates for development.
Enable remote updates for internal testing.
Prepare for launching.
Ensure smooth landing.
1. Get familiar with pw_software_update.#
Pigweed AI summary: The pw_software_update is not yet a fully managed service like Google Play Store, so to use it effectively, you need to have a basic understanding of how it works. The Getting started and Design sections can help you with this.
pw_software_update is not yet a fully managed service like Google Play
Store. To use it effectively, you need to have at least a basic understanding
of how it works. The
Getting started and
Design sections can help you with
this.
2. Enable local updates for development.#
Pigweed AI summary: This section explains how to enable local updates for development, which allows developers to quickly see the results of their changes on a connected device. The process involves using the pw_software_update CLI and Python APIs to generate and check in dev keys, assemble build artifacts into a bundle, and locally sign the bundle. Developers can then use pw_rpc to connect to the BundledUpdate service and progress through an update session, using pw_transfer to transfer the bundle's bytes. Finally, device software must implement the Bund
This step allows developers to update a device that is connected to their development computer. This achieves a low-latency feedback loop for developers, so they can see the results of their changes quickly.
Component |
Task |
Description |
|---|---|---|
Build System |
Produce update bundles |
Use |
Dev Tools |
Send update bundles |
Use |
Device software |
Implement |
Respond to framework callings. Supply root metadata. |
3. Enable remote updates for internal testing.#
Pigweed AI summary: This section discusses the process of enabling remote updates for internal testing. This allows developers and testers to receive software updates over an internal network from a release repository, making it easier to stay up-to-date with the latest software and fixes. The section also provides a table outlining the tasks involved in the process, including uploading unsigned bundles to an internal build artifacts repository, supporting remote updates, preparing for test-key signing, and producing internal releases.
This step builds upon the previous step and allows developers as well as internal testers to receive software updates over an internal network from an internal release repository. This makes it easy for them to stay up-to-date with the latest software and fixes.
Component |
Task |
Description |
|---|---|---|
Build System |
Upload unsigned bundles |
Assemble and generate dev-key signed bundles for local consumption as before. Upload the unsigned bundle to an internal build artifacts repository. |
Dev Tools |
Support remote update |
In addition to local update as before, optionally support updating a device with a build pulled from the build server. |
Signing service |
Prepare for test-key signing |
Set up root and targets test keys and their corresponding ACLs. Monitor incoming signing requests and and automatically sign incoming builds with the test key. |
Release system |
Produce internal releases |
Trigger builds. Run tests. Request test-key remote signing. Publish internal releases. |
4. Prepare for launching.#
Pigweed AI summary: This section discusses the fourth step in the development process, which is preparing for launching. The focus of this step is on improving security at key points in the process, rather than adding new features for users. The section includes a table outlining specific tasks for the build system, signing service, and release system, such as validating and endorsing builds, setting up production keys, and running builds through tests before production-signing them. The goal is to produce well-secured releases and ensure that only qualified, user
The goal of this step is not to add new features for users, but to improve security at key points in the development process in preparation for launch.
Component |
Task |
Description |
|---|---|---|
Build System |
Validate and endorse builds |
In addition to previous responsibilities, validate builds to make sure the builds are configured and built properly per their build type (e.g. no debug features in user builds), and then endorse the validated builds by signing the builds with the build server’s private key and uploading both the builds and signatures. |
Signing service |
Prepare for prod-key signing |
Set up root and targets production keys and their corresponding ACLs. Monitor incoming signing requests and only sign qualified, user builds with the production key. Verify builder identity and validate build content just before signing. |
Release system |
Produce well-secured releases |
Run builds through daily, internal tests, and production release candidates. Only production-sign a build after all other qualifications have passed. |
5. Ensure smooth rollout.#
Pigweed AI summary: This step focuses on ensuring that updates are delivered to users reliably and quickly, especially in cases of recoverable security bugs, throughout the supported lifetime of a product. The release system must produce well-secured updates, carefully control new features, keep all dependencies up to date, and be ready for emergency updates. The section also includes a to-do list for documenting topics such as integrating with verified boot, managing delta updates, and revoking bad releases.
This step ensures updates are delivered to users reliably and with speed in cases of recoverable security bugs, over the supported lifetime of a product.
Component |
Task |
Description |
|---|---|---|
Release system |
Produce well-secured updates |
Carefully control new features. Keep all dependencies up to date. Always ready for emergency updates. |