Update README
Change-Id: I1ed4344c7c39d90348c10406d354c475dc9de84c
diff --git a/README.md b/README.md
index c5ae3d3..5975a12 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,32 @@
-Pigweed Open Source Template Repository
-=======================================
+# Pico Pico: Hardware In the Loop (HIL) test harness
-This repository is a template that we will use when creating new open source
-repositories for Pigweed.
+Pico Pico simplifies large scale Harware-In-the-Loop (HIL) testing of Pico
+embedded software. Each Pico Pico consists of two Picos, wired up such that one
+acts as a Pico Debug Probe, and the other acts as a Device Under Test (DUT).
+
+Pico Pico is part of the Pigweed project. Nevertheless, Pico Pico is suitable
+for non-Pigweed projects since there is nothing Pigweed specific about the
+hardware.
+
+The Pico Debug Probe requires [modified debug probe
+firmware](https://github.com/konkers/debugprobe/tree/picopico), since the
+pinout differs from the official probe.
+
+## Why is the Pico Pico necessary?
+Hardware In the Loop automated testing of software requires flashing new
+software, running tests against that software, then checking if the tests
+passed or failed. Unlike with unit tests on your desktop computer, when an
+embedded device crashes as part of a test it may not be in a state where you
+can update the software (e.g. it becomes bricked). By attaching a 2nd Pico as
+a Pico Debug Probe, un-sticking a crashed Pico to re-flash is possible.
+
+## Won't you burn out the flash?
+Using the Pico Pico by re-flashing the same physical addresses regularly can
+burn out the flash. This could happen if hundreds of tests are run for each
+full test suite run, and full test suites are run nearly continuously. There
+isn't an easy solution for this. One solution is to link the firmware for RAM,
+load the image via the debug probe, and run the code there (eliminating the
+flash cycle). However, that limits the image size to the SRAM on the Pico,
+which is too small for many applications.
+
+However, since the Pico boards are cheap they can be replaced easily.
