1.. _module-pw_software_update-guides: 2 3------------------------- 4pw_software_update: Guide 5------------------------- 6.. pigweed-module-subpage:: 7 :name: pw_software_update 8 9How you update software on an embedded system is specific to the project. 10However, there are common patterns. This section provides suggestions for 11each scenario, which you can then adjust to fit your specific needs. 12 13High-level steps 14---------------- 15 16Setting up an end-to-end software delivery system can seem overwhelming, but 17generally involves the following high-level steps. 18 19#. Get familiar with ``pw_software_update``. 20#. Enable local updates for development. 21#. Enable remote updates for internal testing. 22#. Prepare for launching. 23#. Ensure smooth landing. 24 251. Get familiar with ``pw_software_update``. 26~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 27 28``pw_software_update`` is not yet a fully managed service like Google Play 29Store. To use it effectively, you need to have at least a basic understanding 30of how it works. The 31:ref:`Getting started <module-pw_software_update-get-started>` and 32:ref:`Design <module-pw_software_update-design>` sections can help you with 33this. 34 352. Enable local updates for development. 36~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 37 38This step allows developers to update a device that is connected to their 39development computer. This achieves a low-latency feedback loop for developers, 40so they can see the results of their changes quickly. 41 42.. csv-table:: 43 :header: "Component", "Task", "Description" 44 :widths: 20, 20, 60 45 :align: left 46 47 *Build System*, Produce update bundles, "Use ``pw_software_update``'s CLI and 48 Python APIs to generate and check in dev keys, assemble build artifacts into 49 a bundle, and locally sign the bundle." 50 51 *Dev Tools*, Send update bundles, "Use ``pw_rpc`` to connect to the 52 :cpp:type:`BundledUpdate` service to start and progress through an update 53 session. Use ``pw_transfer`` to transfer the bundle's bytes." 54 55 *Device software*, "Implement :cpp:type:`BundledUpdateBackend`", "Respond to 56 framework callings. Supply root metadata." 57 583. Enable remote updates for internal testing. 59~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 61This step builds upon the previous step and allows developers as well as 62internal testers to receive software updates over an internal network from an 63internal release repository. This makes it easy for them to stay up-to-date with 64the latest software and fixes. 65 66.. csv-table:: 67 :header: "Component", "Task", "Description" 68 :widths: 20, 20, 60 69 :align: left 70 71 *Build System*, Upload unsigned bundles, "Assemble and generate dev-key signed 72 bundles for local consumption as before. Upload the unsigned bundle to an 73 internal build artifacts repository." 74 75 *Dev Tools*, Support remote update, "In addition to local update as before, 76 optionally support updating a device with a build pulled from the build 77 server." 78 79 *Signing service*, Prepare for test-key signing, "Set up *root* and *targets* 80 test keys and their corresponding ACLs. Monitor incoming signing requests and 81 and automatically sign incoming builds with the test key." 82 83 *Release system*, Produce internal releases, "Trigger builds. Run tests. 84 Request test-key remote signing. Publish internal releases." 85 864. Prepare for launching. 87~~~~~~~~~~~~~~~~~~~~~~~~~ 88 89The goal of this step is not to add new features for users, but to improve 90security at key points in the development process in preparation for launch. 91 92.. csv-table:: 93 :header: "Component", "Task", "Description" 94 :widths: 20, 20, 60 95 :align: left 96 97 *Build System*, Validate and endorse builds, "In addition to previous 98 responsibilities, validate builds to make sure the builds are configured 99 and built properly per their build type (e.g. no debug features in user 100 builds), and then endorse the validated builds by signing the builds with 101 the build server's private key and uploading both the builds and signatures." 102 103 *Signing service*, Prepare for prod-key signing, "Set up *root* and *targets* 104 production keys and their corresponding ACLs. Monitor incoming signing 105 requests and only sign qualified, user builds with the production key. Verify 106 builder identity and validate build content just before signing." 107 108 *Release system*, Produce well-secured releases, "Run builds through 109 daily, internal tests, and production release candidates. Only production-sign 110 a build after all other qualifications have passed." 111 1125. Ensure smooth rollout. 113~~~~~~~~~~~~~~~~~~~~~~~~~ 114 115This step ensures updates are delivered to users reliably and with speed in 116cases of recoverable security bugs, over the supported lifetime of a product. 117 118.. csv-table:: 119 :header: "Component", "Task", "Description" 120 :widths: 20, 20, 60 121 :align: left 122 123 *Release system*, Produce well-secured updates, "Carefully control new 124 features. Keep all dependencies up to date. Always ready for emergency 125 updates." 126 127.. 128 TODO: b/273583461 - Document these topics. 129 * How to integrate with verified boot 130 * How to do A/B updates 131 * How to manage delta updates 132 * How to revoke a bad release 133 * How to do stepping-stone releases 134