diff options
Diffstat (limited to 'docs/blog/01-kudzu.rst')
| -rw-r--r-- | docs/blog/01-kudzu.rst | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/docs/blog/01-kudzu.rst b/docs/blog/01-kudzu.rst new file mode 100644 index 000000000..5eb13391b --- /dev/null +++ b/docs/blog/01-kudzu.rst @@ -0,0 +1,256 @@ +.. _docs-blog-01-kudzu: + +========================== +Pigweed Eng Blog #1: Kudzu +========================== +.. 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:: |