143 lines
6.8 KiB
Markdown
143 lines
6.8 KiB
Markdown
# Pigweed
|
||
|
||
Pigweed is an open source collection of embedded-targeted libraries--or as we
|
||
like to call them, modules. These modules are building blocks and infrastructure
|
||
that enable faster and more reliable development on small-footprint MMU-less
|
||
32-bit microcontrollers like the STMicroelectronics STM32L452 or the Nordic
|
||
nRF52832.
|
||
|
||
Pigweed is in the early stages of development, **and should be considered
|
||
experimental**. We’re continuing to evolve the platform and add new modules. We
|
||
value developer feedback along the way.
|
||
|
||
# Quick links
|
||
|
||
- [Getting started guide](docs/getting_started.md)
|
||
- [Documentation](https://pigweed.dev)
|
||
- [Source code](https://cs.opensource.google/pigweed/pigweed)
|
||
- [Code reviews](https://pigweed-review.googlesource.com/)
|
||
- [Issue tracker](https://bugs.pigweed.dev/)
|
||
- [Mailing list](https://groups.google.com/forum/#!forum/pigweed)
|
||
- [Chat room (Discord)](https://discord.gg/M9NSeTA)
|
||
- [Open Source blog post](https://opensource.googleblog.com/2020/03/pigweed-collection-of-embedded-libraries.html)
|
||
|
||
Get the code: `git clone https://pigweed.googlesource.com/pigweed/pigweed` (or
|
||
[fork us on GitHub](https://github.com/google/pigweed)).
|
||
|
||
# Getting Started
|
||
|
||
If you'd like to get set up with Pigweed, please visit the
|
||
[getting started guide](docs/getting_started.md).
|
||
|
||
# What does Pigweed offer?
|
||
|
||
There are many modules in Pigweed, and this section only showcases a small
|
||
selection that happen to produce visual output. For more information about the
|
||
different Pigweed module offerings, refer to "Module Guides" section in the full
|
||
documentation.
|
||
|
||
## `pw_watch` - Build, flash, run, & test on save
|
||
|
||
In the web development space, file system watchers are prevalent. These watchers
|
||
trigger a web server reload on source change, making development much faster. In
|
||
the embedded space, file system watchers are less prevalent; however, they are
|
||
no less useful! The Pigweed watcher module makes it easy to instantly compile,
|
||
flash, and run tests upon save. Combined with the GN-based build which expresses
|
||
the full dependency tree, only the exact tests affected by a file change are run
|
||
on saves.
|
||
|
||
The demo below shows `pw_watch` building for a STMicroelectronics
|
||
STM32F429I-DISC1 development board, flashing the board with the affected test,
|
||
and verifying the test runs as expected. Once this is set up, you can attach
|
||
multiple devices to run tests in a distributed manner to reduce the time it
|
||
takes to run tests.
|
||
|
||
|
||
|
||
## `pw_presubmit` - Vacuum code lint on every commit
|
||
|
||
Presubmit checks are essential tools, but they take work to set up, and projects
|
||
don’t always get around to it. The `pw_presubmit` module provides tools for
|
||
setting up high quality presubmit checks for any project. We use this framework
|
||
to run Pigweed’s presubmit on our workstations and in our automated building
|
||
tools.
|
||
|
||
The `pw_presubmit` module includes `pw format` command, a tool that provides a
|
||
unified interface for automatically formatting code in a variety of languages.
|
||
With `pw format`, you can format C, C++, Python, GN, and Go code according to
|
||
configurations defined by your project. `pw format` leverages existing tools
|
||
like `clang-format`, and it’s simple to add support for new languages.
|
||
|
||
|
||
|
||
## `pw_env_setup` - Cross platform embedded compiler setup
|
||
|
||
A classic problem in the embedded space is reducing the time from git clone to
|
||
having a binary executing on a device. The issue is that an entire suite of
|
||
tools is needed for non-trivial production embedded projects. For example:
|
||
|
||
- A C++ compiler for your target device, and also for your host
|
||
- A build system or three; for example, GN, Ninja, CMake, Bazel
|
||
- A code formatting program like clang-format
|
||
- A debugger like OpenOCD to flash and debug your embedded device
|
||
- A known Python version with known modules installed for scripting
|
||
- A Go compiler for the Go-based command line tools
|
||
- ... and so on
|
||
|
||
In the server space, container solutions like Docker or Podman solve this;
|
||
however, in our experience container solutions are a mixed bag for embedded
|
||
systems development where one frequently needs access to native system resources
|
||
like USB devices, or must operate on Windows.
|
||
|
||
`pw_env_setup` is our compromise solution for this problem that works on Mac,
|
||
Windows, and Linux. It leverages the Chrome packaging system CIPD to bootstrap a
|
||
Python installation, which in turn inflates a virtual environment. The tooling
|
||
is installed into your workspace, and makes no changes to your system. This
|
||
tooling is designed to be reused by any project.
|
||
|
||
|
||
|
||
## `pw_unit_test` - Embedded testing for MCUs
|
||
|
||
Unit testing is important, and Pigweed offers a portable library that’s broadly
|
||
compatible with [Google Test](https://github.com/google/googletest). Unlike
|
||
Google Test, `pw_unit_test` is built on top of embedded friendly primitives; for
|
||
example, it does not use dynamic memory allocation. Additionally, it is easy to
|
||
port to new target platforms by implementing the
|
||
[test event handler interface](https://pigweed.googlesource.com/pigweed/pigweed/+/refs/heads/master/pw_unit_test/public/pw_unit_test/event_handler.h).
|
||
|
||
Like other modules in Pigweed, `pw_unit_test` is designed for use in
|
||
established codebases with their own build system, without the rest of Pigweed
|
||
or the Pigweed integrated GN build. However, when combined with Pigweed's
|
||
build, the result is a flexible and powerful setup that enables easily
|
||
developing code on your desktop (with tests), then running the same tests
|
||
on-device.
|
||
|
||
|
||
|
||
## And more!
|
||
|
||
See the "Module Guides" in the documentation for the complete list and
|
||
documentation for each, but is a selection of some others:
|
||
|
||
- `pw_cpu_exception_cortex_m`: Robust low level hardware fault handler for ARM
|
||
Cortex-M; the handler even has unit tests written in assembly to verify
|
||
nested-hardware-fault handling!
|
||
|
||
- `pw_polyfill`: Similar to JavaScript “polyfill” libraries, this module
|
||
provides selected C++17 standard library components that are compatible with
|
||
C++11 and C++14.
|
||
|
||
- `pw_tokenizer`: Replace string literals from log statements with 32-bit
|
||
tokens, to reduce flash use, reduce logging bandwidth, and save formatting
|
||
cycles from log statements at runtime.
|
||
|
||
- `pw_kvs`: A key-value-store implementation for flash-backed persistent
|
||
storage with integrated wear levelling. This is a lightweight alternative to
|
||
a file system for embedded devices.
|
||
|
||
- `pw_protobuf`: An early preview of our wire-format-oriented protocol buffer
|
||
implementation. This protobuf compiler makes a different set of
|
||
implementation tradeoffs than the most popular protocol buffer library in
|
||
this space, nanopb.
|