README improvements

README.md

@@ -1,10 +1,15 @@
 # PD Buddy Sink Firmware
 
-This is the firmware for the PD Buddy project.  Currently, this specifically
-means the [PD Buddy Sink][].  The firmware is considered stable, and supports
-the most common use cases for the device.
+This is the firmware for the [PD Buddy Sink][], a smart power jack for USB
+Power Delivery.
+
+The firmware is written using [ChibiOS][] RT and HAL, and is comprised of a
+[library][] for USB Power Delivery and an application using that library to
+request a configured voltage and current.
 
 [PD Buddy Sink]: https://git.clayhobbs.com/pd-buddy/pd-buddy-sink
+[ChibiOS]: http://www.chibios.org/
+[library]: lib/README.md
 
 ## Features
 
@@ -26,15 +31,18 @@ the most common use cases for the device.
 * The amount of current the device requests can be set as a power or a
   resistance, as well as a current.  These values are taken as constant over
   the configured voltage range.
-* Setup mode implements a USB CDC-ACM command-line interface allowing
-  configuration to be loaded from and stored in flash.
+* Setup mode implements a USB CDC-ACM command-line interface, compatible with
+  Linux, Mac OS X, and Windows 10, allowing configuration to be loaded from and
+  stored in flash.
 * Setup mode allows real-time renegotiation of voltage and current, complete
   with the ability to control whether the output is enabled or disabled.
-* User can easily read a power supply's advertised capabilities while in Setup
-  mode.
-* Firmware upgrades are easily possible via Setup mode and the
+* Users can easily read a power supply's advertised capabilities while in Setup
+  mode using a [PD Buddy Wye][].
+* Firmware upgrades are easily possible via Setup mode in conjunction with the
   microcontroller's built-in DfuSe bootloader.
 
+[PD Buddy Wye]: https://git.clayhobbs.com/pd-buddy/pd-buddy-wye
+
 ## Prerequisites
 
 To compile the firmware, you must first install the [GNU ARM Embedded

lib/README.md

@@ -4,5 +4,10 @@ This library implements a subset of the USB Power Delivery Specification,
 Revision 2.0, Version 1.3, and Revision 3.0, Version 1.1, for microcontrollers
 running [ChibiOS][] and connected to an [FUSB302B][] USB Power Delivery PHY.
 
+The library's API is not yet considered stable, and is not documented outside
+of source code comments.  For an example of its use, see the [PD Buddy Sink
+Firmware][].
+
 [ChibiOS]: http://www.chibios.org/
 [FUSB302B]: http://www.onsemi.com/PowerSolutions/product.do?id=FUSB302B
+[PD Buddy Sink Firmware]: https://git.clayhobbs.com/pd-buddy/pd-buddy-firmware