xref: /aosp_15_r20/external/pigweed/docs/blog/01-kudzu.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985)

.. _docs-blog-01-kudzu:

==========================
Pigweed Eng Blog #1: Kudzu
==========================
.. raw:: html

   <script type="application/ld+json">
     {
       "@context": "https://schema.org",
       "@type": "NewsArticle",
       "headline": "Kudzu: Pigweed's whimsical take on a development board",
       "image": [
         "https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-diagonal.jpg"
       ],
       "datePublished": "2023-10-12T19:27:00+08:00",
       "dateModified": "2023-10-12T19:27:00+08:00",
       "author": [{
         "@type": "Person",
         "name": "Erik Gilling",
         "url": "https://github.com/konkers"
       }]
     }
   </script>

.. admonition:: A note from the Pigweed Eng Blog editors

   Welcome to the Pigweed Eng Blog! This is an informal blog where Pigweed
   teammates, contributors, and users can share ideas and projects related to
   Pigweed.

   Our first post comes from Erik Gilling, a software engineer on the
   Pigweed team. Today, Erik is going to tell you about Kudzu,
   "Pigweed's whimsical take on a development board"…

   Please note that **while Kudzu is open source, its hardware isn't publicly
   available**. Pigweed users may find the `Kudzu source
   code <https://pigweed.googlesource.com/pigweed/kudzu/+/refs/heads/main>`_
   to be a helpful example of a complex Pigweed integration.

.. card::
    :img-background: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-diagonal.jpg
    :link: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-diagonal.jpg
    :img-alt: A single Kudzu badge face-up on a table viewed at a diagonal.

----------------------------
It all started so innocently
----------------------------
The Pigweed team is taking a field trip to the
`Bay Area Maker Faire <https://makerfaire.com/bay-area/>`_ because
unsurprisingly, that's the kind of good time we're up for! While discussing
the plans at a team meeting I suggested: "We should make PCB badges that run
Pigweed and wear that to the Faire!" I've always wanted to make a PCB badge
and this seemed like the perfect opportunity to make a simple PCB that we could
do a little bit of hacking on.

--------
"Simple"
--------
The idea resonated with the team… perhaps too well. What started as
something simple in my head quickly started creeping features. Hence
the name `Kudzu <https://en.wikipedia.org/wiki/Kudzu>`_: a vine
considered invasive in many parts of the world. Pigweed's a weed.
Our RFCs are called "seeds". We're all about the plant puns…

Anyways, the conversation went something like this:

  "We should have some sort of sensor so it does something…"

  "How should we power it? Let's do LiPo charging…"

  "Let's add a display to highlight our recent
  :ref:`Display Support SEED <seed-0104>`!"

  "Touch screen?"

  "D-Pad and buttons?"

  "Speaker?"

  "Wireless?"

  "No!… but also yes…"

We quickly realized that what we wanted was more than a badge. We wanted a
showcase for Pigweed. We wanted a project we can point people at to show them
Pigweed running at it's best. And thus Kudzu was born. Part badge, part
development board, part handheld gaming system, and all Pigweed.

----------------
The laundry list
----------------
We settled on the following laundry list of features and components:

`RP2040 Microcontroller <https://www.raspberrypi.com/documentation/microcontrollers/rp2040.html>`_
  There's a lot to love about the RP2040: a reasonable amount of SRAM,
  support for large/cheap/execute-in-place external flash, a wicked cool
  programmable I/O block, and most importantly: easy and cheap to source!

`16 MB of Flash <https://www.winbond.com/resource-files/w25q128jv%20revf%2003272018%20plus.pdf>`_
  We're adding the maximum amount of flash that the RP2040 can support. This
  way we can pack as much awesome into the firmware as possible. Realistically
  16 MB is an embarrassingly large amount of space for an embedded project and I
  can't wait to see what cool stuff we fill it with!

USB-C Connector
  While we're not adding USB Power Delivery to the board, the USB C connector
  is robust and common. Many of us on the team are tired of digging micro
  (or even mini) USB cables out of our desk drawers to hook up brand new dev
  boards or JTAG programmers!

LiPo Battery with `charger <https://www.microchip.com/en-us/product/mcp73831>`_ and `fuel gauge <https://www.analog.com/en/products/max17048.html>`_
  Once we decided on a portable gaming form factor, we wanted to have a
  built-in, rechargeable battery. The battery is 900mA and is set to charge at 500mA
  from USB when the system is off and 250mA when the system is running. As an
  added bonus we threw in a fuel gauge chip. Partly because it's really nice to
  have an accurate view of the battery charge state and partly because it's
  a neat chip to write software for.

`3.2" IPS display with capacitive touch <https://www.buydisplay.com/3-2-inch-240x320-ips-tft-lcd-display-optl-capacitive-touchscreen-st7789>`_
  This display is 240x320 which presents two challenges. First, it's naturally
  portrait instead of landscape. We solve this by rotating the buffers once
  they're rendered. The second is that a single 16-bit x 320 x 240 frame buffer
  is ~150K which is over half of the 264K of SRAM in the RP2040. Instead, we're
  rendering at 160x120 and using the PIO module to `pixel double
  <https://github.com/32blit/32blit-sdk>`_ the buffer as we're sending it to the
  display. As an added bonus, the chunkier pixels gives Kudzu a nice retro feel.

Directional Pad and Buttons
  Here we're leaning on off-the-shelf buttons and silicone pads. Game
  controller design is a whole rabbit hole and we're going to rely on the
  collective wisdom of the retro modding community to give us nice-feeling
  controls.

`Six Axis IMU <https://invensense.tdk.com/products/motion-tracking/6-axis/icm-42670-p/>`_
  An IMU is a great general purpose peripheral to demonstrate Pigweed's HAL
  layer. Plus, there's all sorts of cool demos you can write with an IMU and
  a display.

`I2S Audio DAC/Amplifier <https://www.analog.com/media/en/technical-documentation/data-sheets/max98357a-max98357b.pdf>`_ and Speaker
  Chip tunes are best tunes. A couple of us on the team would love to
  port/write a tracker or FM synthesis engine.

Gameboy Advance Link Port
  As a simple way of hooking two devices together, we added link port. Again
  we're using an existing link port and cable to avoid reinventing to wheel.
  Plus, there's something awful nostalgic about that port!

... and `One More Thing <https://www.espressif.com/en/products/socs/esp32-c3>`_
  I kinda snuck an ESP32-C3 module onto the board at the last minute. Having
  wireless is something we wanted but didn't want to burden the initial design
  and bring up with it. My thinking is that we'll leave the module un-populated
  for now. My hope is that adding it to the board now may keep these boards from
  becoming landfill when we decide to tackle wireless.

--------------------------
Design, build, and rollout
--------------------------
I used `KiCad <https://www.kicad.org/>`_ to design the board. It's an open
source PCB design package that has been making incredible strides in
functionality and usability in the past few years. It comes with a high-quality
library of symbols and footprint which is supplemented by community-maintained
open source libraries.

.. card::
   :img-top: https://storage.googleapis.com/pigweed-media/kudzu-schematic.png
   :link: https://storage.googleapis.com/pigweed-media/kudzu-schematic.png
   :img-alt: A screenshot of Kudzu's schematic.
   :text-align: center

   Kudzu schematic

After some careful design review from the team and a few friends of Pigweed we
sent off the board to get fabbed and "patiently" waited for it to be delivered.

An EE at a previous company I worked at had a saying: "If you haven't found
three problems with your board, you're not done looking". The three problems
we found in order from least to most crushing are:

.. card::
   :img-top: https://storage.googleapis.com/pigweed-media/kudzu-display-connector.jpeg
   :link: https://storage.googleapis.com/pigweed-media/kudzu-display-connector.jpeg
   :img-alt: The reworked display connector with many bodge wires.
   :text-align: center

   The reworked display connector and the unpopulated footprint for the "one more thing"
   that "we'll get to eventually"

#. **The BOOT and RESET labels were reversed.** This led to some initial
   confusion on why the boards would not come up in bootloader mode.

#. **One of the FETs (Q3) had the wrong pinout.** This caused the power
   switch to be stuck on and the charge rate switching to not work.

#. **The pins on the display FPC connector were swapped.** This one was really
   crushing. The connector was fairly fine-pitched and 40 pins!

We were able to bring up the whole board including the display by rotating the
connector. Sadly the display would not fit in the 3D printed parts
we'd designed when plugged into the rotated connection. To validate our 3D
printed parts, I painstakingly reworked on-board to get the connector oriented
correctly. However, that was too much work and too fragile for all the boards.
We had to do a re-spin and Maker Faire was approaching quickly! Time to lather,
rinse, and repeat.

Fast forward to Monday night before Maker Faire. The boards come in and I spent
the evening preparing for a build party. On Tuesday, with some
`robotic help <https://www.opulo.io/>`_, we managed to build and test 8 boards
and get them in team members' hands on Wednesday.

.. card::
   :img-top: https://storage.googleapis.com/pigweed-media/kudzu-pnp.jpg
   :link: https://storage.googleapis.com/pigweed-media/kudzu-pnp.jpg
   :img-alt: A photo of the Opulo LumenPnP
   :text-align: center

   Our robotic help (Opulo LumenPnP)

Thankfully, because Pigweed is modular and portable, we were able to get our
software working on it quickly, freeing us to spend the next couple days hacking
together some simple fun demos for Maker Faire!

------
Photos
------
.. grid:: 1 1 2 2

   .. grid-item-card::
      :img-background: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-diagonal.jpg
      :link: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-diagonal.jpg
      :img-alt: A single Kudzu badge face-up on a table viewed at a diagonal.

   .. grid-item-card::
      :img-background: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-back.jpg
      :link: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-back.jpg
      :img-alt: A single Kudzu badge face-down on a table viewed at a diagonal.

.. grid:: 1 1 2 2

   .. grid-item-card::
      :img-background: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-top-down.jpg
      :link: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-top-down.jpg
      :img-alt: A single Kudzu badge face-up on a table viewed from above.

   .. grid-item-card::
      :img-background: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-front-standing.jpg
      :link: https://storage.googleapis.com/pigweed-media/kudzu-finished-photo-front-standing.jpg
      :img-alt: A single Kudzu badge standing up on a table viewed from the front.

.. card::
   :img-top: https://storage.googleapis.com/pigweed-media/kudzu-badges.jpg
   :link: https://storage.googleapis.com/pigweed-media/kudzu-badges.jpg
   :img-alt: A photo of 6 of the Kudzu badges
   :text-align: center

   Six Kudzu badges for Maker Faire 2023

----------
Learn more
----------
We don't have any plans to distribute hardware outside of our team but are
excited to publish the living project to serve as an example of how to build
firmware integrated with Pigweed. Over the coming months we'll be publishing
more functionality to the repository.

Head over to the `Kudzu repo <https://pigweed.googlesource.com/pigweed/kudzu>`_
where you'll find:

* KiCad PCB Design
* Example firmware demonstrating:
   * :ref:`module-pw_system` integration
   * :ref:`module-pw_rpc` and :ref:`module-pw_log` support
   * Use of Pigweed's :ref:`module-pw_digital_io`, :ref:`module-pw_i2c`,
     and :ref:`module-pw_spi` hardware abstraction layers

.. pigweed-live::