1.. _showcase-sense-tutorial-flash: 2 3================== 47. Flash your Pico 5================== 6Enough with the simulations. Let's work with some real hardware! 7You'll need a physical Raspberry Pi Pico for the rest of the tutorial. 8You can use either the Pico 1 or Pico 2; we support both. 9 10If you don't have a Pico, you can just skim the remaining pages of 11the tutorial without actually doing the workflows, or skip ahead to 12:ref:`showcase-sense-tutorial-outro`. 13 14.. _showcase-sense-tutorial-hardware: 15 16-------------------- 17Set up your hardware 18-------------------- 19You can use any of the following hardware setups. 20 21.. _Pico W: https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w-and-pico-wh 22 23.. caution:: 24 25 **The Pico W is untested**. We are still in the process of verifying that 26 all parts of the tutorial work with the `Pico W`_. You are welcome to try 27 the tutorial with a Pico W, but please remember that some things may not 28 work yet. 29 30.. _showcase-sense-tutorial-basic: 31 32Option: Basic setup 33=================== 34You can connect your development host directly to a Pico via a 35USB cable. 36 37.. figure:: https://storage.googleapis.com/pigweed-media/airmaranth/basic_setup.jpg 38 :alt: USB connected to Pico, no Enviro+ Pack involved 39 40If you have an Enviro+ Pack, you connect the Enviro+ Pack to 41the headers of your Pico. The Pico is still connected to your 42development host over USB, same as before. 43 44.. figure:: https://storage.googleapis.com/pigweed-media/airmaranth/basic_setup_enviro.jpg 45 :alt: USB connected to Pico, with Pico connected to Enviro+ 46 47.. _showcase-sense-tutorial-full: 48 49Option: Full setup 50================== 51.. _Pico Omnibus: https://shop.pimoroni.com/products/pico-omnibus 52 53.. Don't link to Raspberry Pi Debug Probe here because some dogfooders 54.. went to the product's homepage and thought they had to set up 55.. OpenOCD and other painful stuff like that. 56 57For the most robust long-term setup, use a Raspberry Pi Debug Probe 58and `Pico Omnibus`_ in combination with your Pico and Enviro+ Pack: 59 60.. _Update the firmware on the Debug Probe: https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html#updating-the-firmware-on-the-debug-probe 61 62#. Connect the Debug Probe to your host over USB. 63 64#. `Update the firmware on the Debug Probe`_. You just need to 65 download the latest release and drag-and-drop the UF2 file 66 onto your Debug Probe. You want the ``debugprobe.uf2`` file 67 from the releases page. It only takes a minute or two. 68 69#. Connect the Enviro+ to **DECK 1** on the Omnibus. 70 71#. Connect the Pico to the middle landing area on the Omnibus. 72 Make sure that the USB port on your Pico is lined up with the 73 USB label on the Omnibus. 74 75#. Connect the Pico and Debug Probe together with the 76 3-pin debug to 0.1-inch header female cable (the yellow, black, 77 and orange cable). On deck 2 connect the yellow wire to pin 0 78 (Pico TX, Debug Probe RX), the orange wire to pin 1 (Pico RX, 79 Debug Probe TX), and the black wire to **-** (GND). 80 See the next image. 81 82#. Connect the Pico and Debug Probe together with the 3-pin 83 debug to 3-pin debug cable (the grey and red cable). See the 84 image below. 85 86#. Connect the Pico's micro USB port to a power supply. 87 88 You can supply power to the Pico by connecting it to a USB port 89 on your host. Later on this will make your flashing process a little 90 more complex. So it's simpler to provide power to the Pico separately, 91 if you can. 92 93 94.. figure:: https://storage.googleapis.com/pigweed-media/airmaranth/full_setup.jpg 95 :alt: Full hardware setup with Debug Probe, Pico, Omnibus, and Enviro+ Pack 96 97 The full hardware setup 98 99.. _showcase-sense-tutorial-udev: 100 101----------------- 102Set up udev rules 103----------------- 104Configure your host to properly detect Raspberry Pi hardware. 105 106.. tab-set:: 107 108 .. tab-item:: Linux 109 110 #. Add the following rules to ``/etc/udev/rules.d/49-pico.rules`` or 111 ``/usr/lib/udev/rules.d/49-pico.rules``. Create the file if it doesn't 112 exist. 113 114 .. literalinclude:: /targets/rp2040/49-pico.rules 115 :language: linuxconfig 116 :start-at: # Raspberry 117 118 #. Reload the rules: 119 120 .. code-block:: console 121 122 sudo udevadm control --reload-rules 123 sudo udevadm trigger 124 125 #. If your Pico is already connected to your host, unplug it and plug 126 it back in again. 127 128 .. tab-item:: macOS 129 130 No extra setup needed. 131 132.. _showcase-sense-tutorial-flash-blinky: 133 134---------------------------------------- 135Flash an application binary to your Pico 136---------------------------------------- 137.. _Your First Binaries: https://www.raspberrypi.com/documentation/microcontrollers/c_sdk.html#your-first-binaries 138 139#. If your Pico's firmware is **not** in good working order, put 140 your Pico into **BOOTSEL** mode. See `Your First Binaries`_. 141 If your Pico is in working order (i.e. you have functioning 142 app running correctly on your Pico) you can skip this step. 143 144#. Flash the blinky binary to your Pico. 145 146 .. tab-set:: 147 148 .. tab-item:: VS Code 149 :sync: vsc 150 151 In **Bazel Build Targets** expand **//apps/blinky**, then right-click 152 **:flash (alias)**, then select **Run target**. 153 154 A successful flash looks similar to this: 155 156 .. figure:: https://storage.googleapis.com/pigweed-media/sense/20240802/flash.png 157 158 .. tab-item:: CLI 159 :sync: cli 160 161 .. code-block:: console 162 163 $ bazelisk run //apps/blinky:flash 164 INFO: Analyzed target //apps/blinky:flash (0 packages loaded, 0 targets configured). 165 INFO: Found 1 target... 166 Target //apps/blinky:flash_rp2040 up-to-date: 167 bazel-bin/apps/blinky/flash_rp2040.exe 168 INFO: Elapsed time: 0.129s, Critical Path: 0.00s 169 INFO: 1 process: 1 internal. 170 INFO: Build completed successfully, 1 total action 171 INFO: Running command line: bazel-bin/apps/blinky/flash_rp2040.exe apps/blinky/rp2040_blinky.elf 172 20240806 18:16:58 INF Only one device detected. 173 20240806 18:16:58 INF Flashing bus 3 port 6 174 175If you see an interactive prompt asking you to select a device, see 176:ref:`showcase-sense-tutorial-flash-prompt`. 177 178You should see your Raspberry Pi Pico's LED start blinking on and off at a 1791-second interval. 180 181.. admonition:: Troubleshooting 182 183 If you see ``A connected device has an inaccessible serial number: The 184 device has no langid (permission issue, no string descriptors supported or 185 device error)`` it probably means you need to update your udev rules. See 186 :ref:`showcase-sense-tutorial-udev`. 187 188.. _showcase-sense-tutorial-flash-summary: 189 190------- 191Summary 192------- 193.. _target: https://bazel.build/concepts/build-ref#targets 194 195In a Bazel-based project like Sense there is no separate flashing 196tool or command that you need to memorize; flashing is a Bazel 197`target`_ just like everything else. 198 199As mentioned in :ref:`showcase-sense-tutorial-build-summary`, 200you actually don't need to build binaries before running flashing 201targets like this. You can just skip straight to running the flash 202target and Bazel will figure out what binaries to build before 203attempting to flash. 204 205Next, head over to :ref:`showcase-sense-tutorial-devicetests` to 206try out on-device unit tests. 207 208.. _showcase-sense-tutorial-flash-prompt: 209 210-------------------------------------- 211Appendix: Interactive prompt selection 212-------------------------------------- 213If you're using the :ref:`full setup <showcase-sense-tutorial-full>` you'll 214see an interactive prompt asking you to select a device. Choose 215``Raspberry Pi - Debug Probe (CMSIS-DAP)``, *not* ``Raspberry Pi - Pico``. 216When the Debug Probe receives the flashing command, it knows that the command 217is intended for the Pico it's connected to, not itself. 218 219.. code-block:: console 220 221 INFO: Running command line: bazel-bin/apps/blinky/flash_rp2040.exe apps/blinky/rp2040_blinky.elf 222 Multiple devices detected. Please select one: 223 1 - bus 3, port 1 (Raspberry Pi - Pico) 224 2 - bus 3, port 6 (Raspberry Pi - Debug Probe (CMSIS-DAP)) 225 226 Enter an item index or press up/down (Ctrl-C to cancel) 227 > 2 228 20240729 16:29:46 INF Flashing bus 3 port 6 229
