1.. _showcase-sense-tutorial-prod: 2 3=================================== 414. Run the air quality monitor app 5=================================== 6.. caution:: 7 8 This section and the ones after it require a Pimoroni Enviro+ Pack. See 9 :ref:`showcase-sense-tutorial-hardware` for a review of the hardware 10 setup options. If you don't have an Enviro+, skip ahead to 11 :ref:`showcase-sense-tutorial-outro` to wrap up your tutorial experience. 12 13Your tour of Pigweed is almost done. Before you go, let's get you 14familiar with the application described at 15:ref:`showcase-sense-product-concept`. Within the Sense codebase this app 16is called ``production``. The purpose of the ``production`` app is to 17demonstrate what a medium-complexity application built on top of Pigweed's 18software abstractions looks like. We're still perfecting the codebase 19structure, but this application can begin to give you an idea of how the 20Pigweed team thinks Pigweed-based projects should be structured. 21 22First, let's get the app running on your Pico. Then we'll provide 23an overview of the code. 24 25.. warning:: 26 27 This is just a sample application. It is not suitable for real 28 air quality monitoring. 29 30.. _showcase-sense-tutorial-prod-hardware: 31 32-------------------- 33Set up your hardware 34-------------------- 35This part of the tutorial requires the 36:ref:`full setup <showcase-sense-tutorial-full>`. 37 38.. _showcase-sense-tutorial-prod-flash: 39 40-------------- 41Flash the Pico 42-------------- 43Flash the ``production`` app to your Pico: 44 45.. tab-set:: 46 47 .. tab-item:: VS Code 48 :sync: vsc 49 50 In **Bazel Build Targets** expand **//apps/production**, then 51 right-click **:flash (alias)**, then select **Run target**. 52 53 .. tab-item:: CLI 54 :sync: cli 55 56 .. code-block:: console 57 58 $ bazelisk run //apps/production:flash 59 60You should see output like this: 61 62.. code-block:: console 63 64 INFO: Analyzed target //apps/production:flash (2 packages loaded, 84 targets configured). 65 INFO: Found 1 target... 66 Target //apps/production:flash_rp2040 up-to-date: 67 bazel-bin/apps/production/flash_rp2040.exe 68 INFO: Elapsed time: 0.311s, Critical Path: 0.04s 69 INFO: 1 process: 1 internal. 70 INFO: Build completed successfully, 1 total action 71 INFO: Running command line: bazel-bin/apps/production/flash_rp2040.exe apps/production/rp2040.elf 72 20240805 18:35:58 INF Only one device detected. 73 20240805 18:35:58 INF Flashing bus 3 port 6 74 75.. _showcase-sense-tutorial-prod-logs: 76 77---------------------- 78Monitor the app's logs 79---------------------- 80The app prints out a lot of informational logs. These logs can 81help you grok how the app works. Fire up ``pw_console`` again now: 82 83.. tab-set:: 84 85 .. tab-item:: VS Code 86 :sync: vsc 87 88 In **Bazel Build Targets** expand **//apps/production**, then 89 right-click **:rp2040_console (native binary)** (if you want to run 90 the terminal-based console) or **:rp2040_webconsole (native_binary)** 91 (if you want to run the web-based console), then select **Run target**. 92 93 .. tab-item:: CLI 94 :sync: cli 95 96 Run the terminal-based console: 97 98 .. code-block:: console 99 100 $ bazelisk run //apps/production:rp2040_console 101 102 Or the web-based console: 103 104 .. code-block:: console 105 106 $ bazelisk run //apps/production:rp2040_webconsole 107 108See :ref:`showcase-sense-tutorial-sim` if you need a refresher 109on how to use ``pw_console``. 110 111.. _showcase-sense-tutorial-prod-alarm: 112 113---------------------------- 114Trigger an air quality alarm 115---------------------------- 116The default mode of the app is to continuously monitor air quality. 117You should see the LED on your Enviro+ in one of the following 118states: 119 120* Blue/green: Excellent air quality 121* Green: Good air quality 122* Orange: Meh air quality 123* Red: Bad air quality 124 125.. admonition:: Troubleshooting 126 127 **The LCD screen is blank**. This is expected because we haven't 128 implemented display support in the app yet. Stay tuned! 129 130Try triggering an air quality alarm now: 131 132#. Hold a strong chemical such as rubbing alcohol close to the 133 **BME688** sensor on your Enviro+ Pack. 134 135 The LED on the Enviro+ Pack should change to orange (meh air quality) or 136 red (bad air quality). 137 138The next video is an example of what you should see. 139 140.. raw:: html 141 142 <video preload="metadata" style="width: 100%; height: auto;" controls muted> 143 <source type="video/webm" 144 src="https://storage.googleapis.com/pigweed-media/sense/20240802/production.mp4#t=0.5"/> 145 </video> 146 147.. _showcase-sense-tutorial-prod-thresholds: 148 149---------------------------- 150Adjust the alarm sensitivity 151---------------------------- 152You can adjust the sensitivity i.e. thresholds of the alarm with 153the **A** and **B** buttons on your Enviro+ Pack: 154 155* Press the **A** button repeatedly to increase the sensitivity 156 of the alarm. In other words, with only a slight change in 157 air quality the LED will shift to orange (meh air quality) or 158 red (bad air quality). 159* Press the **B** button repeatedly to decrease the sensitivity 160 of the alarm. In other words, it takes a bigger change in 161 air quality for the LED to shift to orange or red. 162 163.. note:: 164 165 The "threshold adjustment" mode that you enter after pressing 166 **A** or **B** will automatically exit after 3 seconds of 167 inactivity. 168 169In the **Device Logs** of ``pw_console`` you should see the 170air quality thresholds change as you press **A** and **B**. 171For example, if you quickly press **A** twice (i.e. in less 172than a second) you should see a log like this: 173 174.. code-block:: text 175 176 19:38:23 INF 00:00:25.758 STATE Air quality thresholds set: alarm at 384, silence at 512 177 178That log is telling you that the LED will change to red and start 179blinking when the air quality value is less than ``384``. 180 181.. _showcase-sense-tutorial-prod-morse: 182 183---------------------------------------- 184Print air quality messages in Morse code 185---------------------------------------- 186.. _Morse code: https://en.wikipedia.org/wiki/Morse_code 187 188Press the **Y** button to put the app in `Morse code`_ mode. 189In this mode, the LED on the Enviro+ prints out air quality 190messages like ``AQ EXCELLENT 872`` as Morse code messages, 191in addition to changing color as previously described. 192 193.. _showcase-sense-tutorial-prod-code: 194 195------------- 196Code overview 197------------- 198.. _Sense codebase: https://cs.opensource.google/pigweed/showcase/sense 199 200As mentioned in the intro of this page, the ``production`` app 201provides a good start for figuring out how to structure your 202Pigweed-based project. It's not perfect yet, but it's a solid 203start. We'll leave it up to you to study the code in-depth, but 204here are some pointers on the relevant parts of the `Sense codebase`_: 205 206* ``//apps/production/*``: The app's entrypoint code. 207* ``//modules/*``: Portable business logic, algorithms, state handling, etc. 208 Look at the header includes in ``//apps/production/main.cc`` to figure out 209 what modules to study. 210* ``//system/*``: System global accesors. Gives access to pre-created instances 211 of portable system interfaces. For example, ``am::system::RpcServer()`` 212 returns the RPC server instance. 213 214.. _showcase-sense-tutorial-prod-summary: 215 216------- 217Summary 218------- 219You now have a rudimentary but working air quality monitor. More 220importantly, the code that powers your new air quality monitor is 221a solid (but not perfect) starting point for learning how to structure 222your own Pigweed-powered products. 223 224Next, head over to :ref:`showcase-sense-tutorial-crash-handler` to learn about 225the pigweed crash handler and crash snapshots. 226