1.. _showcase-sense: 2 3========================================= 4Sense: An interactive tour though Pigweed 5========================================= 6Welcome to Pigweed Sense: **a tour of key Pigweed components experienced through 7an imagined air quality monitor product**. Since Pigweed is intended for larger 8teams and higher-complexity products, it’s important to experience Pigweed in a 9medium-size project like Sense that shows a lot of Pigweed components working 10together. 11 12.. _showcase-sense-figure-1: 13 14.. figure:: https://storage.googleapis.com/pigweed-media/sense/20240802/hero.png 15 16 Figure 1. :ref:`showcase-sense-product-concept` 17 18**Bringing a consumer electronics product from concept to mass production requires 19more than just good firmware**. Shipping an electronics product also requires 20support software for other product phases like prototyping, bringup, 21manufacturing, integration testing & QA, hardware validation, and so on. Product 22development also includes authoring large amounts of non-firmware code that runs 23on developer, factory, and hardware engineer machines. Large scale products also 24need significant investment in testing to facilitate large teams collaborating 25and building towards a product vision. Sense illustrates a micro version of a 26consumer electronics lifecycle, from the perspective of the firmware team, 27leveraging many of the Pigweed components designed for large-scale projects. 28 29The components you will experience through the 30:ref:`Sense tutorial <showcase-sense-tutorial-intro>` have helped ship 31millions of products to millions of people, by teams who were able to focus on 32their core product value proposition instead of the low-level embedded plumbing 33concerns Pigweed solves like portable RTOS primitives, test frameworks, RPC 34comms from device to host, crash handling, interactive console, scripting 35solutions, etc. 36 37.. grid:: 2 38 39 .. grid-item-card:: :octicon:`rocket` Tutorial 40 :link: showcase-sense-tutorial-intro 41 :link-type: ref 42 :class-item: sales-pitch-cta-primary 43 44 Walk through the Sense tutorial to see all of Sense's features 45 in action, such as hermetic building, authoring in Visual Studio 46 Code, viewings logs and sending commands over RPC, and more. 47 48 .. grid-item-card:: :octicon:`code` Source code 49 :link: https://cs.opensource.google/pigweed/showcase/sense 50 :link-type: url 51 :class-item: sales-pitch-cta-secondary 52 53 Browse Sense's source code. If you like what you see, you are 54 welcome to use Sense as the starting point for your own products. 55 56.. _showcase-sense-overview: 57 58---------------------- 59What is Pigweed Sense? 60---------------------- 61Sense is three things: 62 63#. :ref:`showcase-sense-product-concept` - A simplistic air quality monitor, 64 described in more detail below. This is not a real product, but is instead a 65 subset of functionality from an imagined full air quality sensor product. 66 Despite not being real, it captures realistic flows such as integrating 67 multiple inputs (sensors, buttons) and outputs (RGB LED), state machine 68 management, and more. Sense will also soon include a web app, to 69 graphically display air quality. 70 71#. :ref:`showcase-sense-codebase` - A collection of C++ on-device firmware 72 code and tests, including a port to the developer host, and factory tooling to 73 illustrate how Pigweed’s tooling could help in manufacturing. This is a small 74 subset of what a large scale project using Pigweed might look like. 75 76#. :ref:`showcase-sense-tutorial` - An interactive tour through 77 Pigweed components in the context of a small-scale, semi-realistic product 78 that demonstrates how larger products might leverage Pigweed. This page 79 you're reading now is the start of the tutorial. 80 81.. note:: 82 83 Pigweed Sense, or Sense for short, is a fake product concept purely for 84 illustration purposes, and has no connection to any real products, from Google 85 or otherwise. 86 87.. _showcase-sense-product-concept: 88 89-------------------------- 90Sense, the product concept 91-------------------------- 92The Sense product is a basic air quality monitor that watches the levels of 93volatile organic compounds (VOCs) in the air, and alerts via the RGB LED if the 94VOCs are too high and the user should take an action like opening a window. 95The RGB LED also passively indicates air quality on a color spectrum. 96 97The core interactions for the product are to observe the RGB LED showing green 98(nominal, OK), observe the RGB LED blinking red (VOC alarm), adjust the VOC 99threshold up/down via button press, and silencing/snoozing an active alarm with 100a button press. Additionally, the RGB LED’s brightness is adjusted to match 101ambient light to avoid being too distracting in low light conditions. 102 103.. _Raspberry Pi Pico 1: https://www.raspberrypi.com/products/raspberry-pi-pico/ 104.. _Pimoroni Enviro+ Pack: https://shop.pimoroni.com/products/pico-enviro-pack 105.. _Raspberry Pi Debug Probe: https://www.raspberrypi.com/products/debug-probe/ 106.. _Pimoroni Pico Omnibus (Dual Expander): https://shop.pimoroni.com/products/pico-omnibus?variant=32369533321299 107 108While there is no real Pigweed Sense product, the imagined product can 109be assembled from a `Raspberry Pi Pico 1`_ (or the new Pico 2) and a 110`Pimoroni Enviro+ Pack`_. It is useful to also have a 111`Raspberry Pi Debug Probe`_ and a `Pimoroni Pico Omnibus (Dual Expander)`_. 112See :ref:`Figure 1 <showcase-sense-figure-1>`. 113 114.. note:: 115 116 While the Enviro+ pack has a display, at time of writing (August 2024) 117 Pigweed’s display subsystem isn’t ready yet, so there is no display use. 118 119.. _Pico W: https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w-and-pico-wh 120 121.. caution:: 122 123 **The Pico W is untested**. We are still in the process of verifying that 124 all parts of the tutorial work with the `Pico W`_. You are welcome to try 125 the tutorial with a Pico W, but please remember that some things may not 126 work yet. 127 128.. _showcase-sense-codebase: 129 130------------------- 131Sense, the codebase 132------------------- 133The Sense codebase covers different parts of a typical consumer electronics 134lifecycle: initial development, prototyping & bringup, manufacturing, and 135production. Since the software has multiple users across multiple teams (e.g. 136software engineering, quality assurance, product management, returned 137merchandise authorization, etc.) there is a fair amount of software beyond just 138the production image. 139 140On-device code 141============== 142* **Applications** (C++) - These are the various applications that exist to 143 support different phases of the product, including bringup (``blinky``), 144 development (``production``), and manufacturing (``factory``). Applications 145 are built by instantiating and leveraging portable instances of 146 :ref:`modules <docs-glossary-module>`. Applications are 147 like ``.exe`` files for normal computers, but instead run on our Sense hardware. 148 Only the ``production`` application would be used by end customers (if 149 this was a real product). 150 151* **Modules** (C++) - These are the portable, core abstractions that the 152 applications are composed of, such as the state manager, sensor filtering 153 code, and other hardware-agnostic functionality. 154 155* **Drivers & targets** (C++) - This code covers hardware-specific 156 resources like drivers that sample air quality or proximity. 157 158* **Unit tests & scaffolding** (C++) - The unit tests ensure that the Sense firmware 159 works as expected, even as further changes are made. The tests cover the core 160 functionality of Sense, such as the state manager that coordinates the LED in 161 response to sensor events. 162 163Host code (for developers only) 164=============================== 165 166* **Console** (Python) - Sense’s interactive console is built on top of 167 :ref:`module-pw_console`, but has project-custom extensions. The console 168 facilitates general development, debugging, and bringup. 169 170* **Flashing** (Python) - Flashing device firmware is often fairly custom, 171 necessitating project-specific scripts and associated build machinery. 172 This is still the case in Sense, but Sense does demonstrate a powerful 173 property of Bazel-based embedded projects: the ability to express flashing 174 as just another part of the build graph. In Sense it's possible to clone 175 the repo and jump immediately to flashing. When Bazel detects that the 176 flashing target's firmware has not yet been built, Bazel builds it 177 automatically and then proceeds to run the flashing script. 178 179* **Manufacturing** (Python) - Manufacturing typically requires a series 180 of custom scripts and programs for each step of the manufacturing flow. 181 Sense has a 1-station "fake factory" flow you can run at your desk. 182 183Web interface (for end customers) 184================================= 185.. _Web Serial API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Serial_API 186 187* **Sense web UI** (TypeScript) - The Sense web app lets you monitor 188 and control a connected Sense device from a web browser. The 189 web app and the Sense device communicate with each other via 190 :ref:`module-pw_rpc` and the `Web Serial API`_; the Sense device 191 does not run a web server. 192 193.. _showcase-sense-tutorial: 194 195------------------- 196Sense, the tutorial 197------------------- 198The :ref:`tutorial <showcase-sense-tutorial-intro>` provides a 199guided, hands-on walkthrough of everything we've discussed here, including: 200 201* Hermetic building, flashing and testing with Bazel, 202 :ref:`Pigweed's primary build system <seed-0111>`. 203 204* Authoring in Visual Studio Code with full C++ code intelligence 205 through :ref:`pw_ide <module-pw_ide>`. 206 207* Hooking into :ref:`pw_system <module-pw_system>`, Pigweed's application 208 framework. 209 210* Viewing device logs through :ref:`pw_console <module-pw_console>`. 211 212* Sending commands to the device over RPC with :ref:`pw_rpc <module-pw_rpc>`. 213 214* Running host-side and on-device unit tests with 215 :ref:`pw_unit_test <module-pw_unit_test>`. 216 217* Portable software abstractions built on top of Pigweed's 218 extensive collection of :ref:`modules <docs-glossary-module>`. 219 220.. _showcase-sense-complexity: 221 222------------------------------------------------------ 223A note on complexity, or, why is Sense so complicated? 224------------------------------------------------------ 225There is no getting around that the Sense codebase is complicated and large 226relative to the complexity of the imaginary Sense product. A straightforward 227implementation could have less code, potentially much less. So why then use 228something like Pigweed, which may appear kafkaesque in complexity to some 229engineers, compared to the simpler alternative? 230 231.. Use raw HTML for the next paragraph because it's not possible to bold, 232.. underline, and format a word in reStructuredText. 233 234.. raw:: html 235 236 <p> 237 The short answer is <b><i><u>scale</u></i></b>. Scale in number of 238 engineers, scale in number of subsystems, scale in risk to instability, 239 scale in security concerns, scale in number of units manufactured, scale 240 in brand risk to a bad product, scale of repeatability, and so on. 241 </p> 242 243Let’s explore some of the ways the Sense codebase is larger than a naive, 244straightforward implementation of a comparable product. 245 246* **Testing** - A key tenet of Pigweed is that automated testing is useful, and 247 rapidly pays for itself by enabling product delivery in less time and with 248 better reliability. While time-to-first-feature may be higher without a 249 testing-enabled codebase, the time-to-no-bugs is reduced. However, 250 structuring code for testing adds complexity. 251 252* **Security & robustness** - Making host-portable code enables running with modern 253 code analysis tooling like ASAN, TSAN, MSAN, fuzzers, and more that are unlikely 254 to run in the embedded context. Fun fact: We caught real bugs in Sense with this 255 tooling during development! 256 257* **Portability** - Code written with Pigweed abstractions can run on multiple 258 target platforms, including custom hardware as well as Mac and Linux. This 259 portability retains product optionality around hardware selection, and makes 260 reusing the same code across products easier. 261 262.. _hermetic: https://bazel.build/basics/hermeticity 263 264* **Fast and consistent developer setup** - Our Bazel-based development environment 265 enables engineers to become productive quickly. Furthermore, the fact that the 266 environment is repeatable and `hermetic`_ reduces the chance that local developer 267 machine settings will leak into developed code or processes. The product team's 268 infrastructure, e.g. continuous integration (CI) & commit queue (CQ), can 269 leverage the same machinery, reducing the delta between developer machines and 270 infra. 271 272With that said, we are still working on Sense, and hope to reduce the 273complexity and add more comments to make the code more approachable. 274 275---------- 276Next steps 277---------- 278.. _Sense source code: https://cs.opensource.google/pigweed/showcase/sense 279 280Start the :ref:`Sense tutorial <showcase-sense-tutorial-intro>` 281or browse the `Sense source code`_. 282 283.. toctree:: 284 :maxdepth: 1 285 :hidden: 286 287 self 288 Tutorial <tutorial/index> 289 Source code <https://pigweed.googlesource.com/pigweed/showcase/sense/> 290
