all: Update READMEs.

jimmo · jimmo · commit af3e1aff9e4d · 2021-05-27T15:41:08.000+10:00
diff --git a/LICENSE b/LICENSE
@@ -1,8 +1,8 @@
 micropython-lib consists of multiple modules from different sources and
-authors. Each module comes under its own licensing terms. Short name of
-a license can be found in a file within a module directory (usually
-metadata.txt or setup.py). Complete text of each license used is provided
-below. Files not belonging to a particular module a provided under MIT
+authors. Each module comes under its own licensing terms. The short name of
+a license can be found in a file within the module directory (usually
+metadata.txt or setup.py). The complete text of each license used is provided
+below. Files not belonging to a particular module are provided under the MIT
 license, unless explicitly stated otherwise.
 
 =============== MIT License ===============
diff --git a/README.md b/README.md
@@ -1,73 +1,48 @@
 micropython-lib
 ===============
-micropython-lib is a project to develop a non-monolothic standard library
-for "advanced" MicroPython fork (https://github.com/pfalcon/micropython).
-Each module or package is available as a separate distribution package from
-PyPI. Each module comes from one of the following sources (and thus each
-module has its own licensing terms):
 
-* written from scratch specifically for MicroPython
-* ported from CPython
-* ported from some other Python implementation, e.g. PyPy
-* some modules actually aren't implemented yet and are dummy
+This is a repository of libraries designed to be useful for writing
+MicroPython applications.
 
-Note that the main target of micropython-lib is a "Unix" port of the
-aforementioned fork of MicroPython. Actual system requirements vary per
-module. Majority of modules are compatible with the upstream MicroPython,
-though some may require additional functionality/optimizations present in
-the "advanced" fork. Modules not related to I/O may also work without
-problems on bare-metal ports, not just on "Unix" port (e.g. pyboard).
+The libraries here fall into roughly four categories:
 
+ * Compatible ports of CPython standard libraries. These should be drop-in replacements for the CPython libraries, although many have reduced functionality or missing methods or classes (which may not be an issue for many use cases).
 
-Usage
------
-micropython-lib packages are published on PyPI (Python Package Index),
-the standard Python community package repository: https://pypi.org/ .
-On PyPI, you can search for MicroPython related packages and read
-additional package information. By convention, all micropython-lib package
-names are prefixed with "micropython-" (the reverse is not true - some
-package starting with "micropython-" aren't part of micropython-lib and
-were released by 3rd parties).
-
-Browse available packages [via this
-URL](https://pypi.org/search/?q=&o=&c=Programming+Language+%3A%3A+Python+%3A%3A+Implementation+%3A%3A+MicroPython).
-
-To install packages from PyPI for usage on your local system, use the
-`upip` tool, which is MicroPython's native package manager, similar to
-`pip`, which is used to install packages for CPython. `upip` is bundled
-with MicroPython "Unix" port (i.e. if you build "Unix" port, you
-automatically have `upip` tool). Following examples assume that
-`micropython` binary is available on your `PATH`:
-
-~~~~
-$ micropython -m upip install micropython-pystone
-...
-$ micropython
->>> import pystone
->>> pystone.main()
-Pystone(1.2) time for 50000 passes = 0.534
-This machine benchmarks at 93633 pystones/second
-~~~~
+ * "Micro" versions of CPython standard libraries with limited compatibility. These can often provide the same functionality, but might require some code changes compared to the CPython version.
 
-Run `micropython -m upip --help` for more information about `upip`.
+ * MicroPython-specific libraries. These include drivers and other libraries targeted at running Python on hardware or embedded systems.
 
+ * MicroPython-on-Unix-specific libraries. These extend the functionality of the Unix port to allow access to operating-system level functionality (which allows more CPython compatibility).
 
-Development
------------
-To install modules during development, use `make install`. By default, all
-available packages will be installed. To install a specific module, add the
-`MOD=<module>` parameter to the end of the `make install` command.
-
-
-Links
+Usage
 -----
-If you would like to trace evolution of MicroPython packaging support,
-you may find following links useful (note that they may contain outdated
-information):
 
- * https://github.com/micropython/micropython/issues/405
- * http://forum.micropython.org/viewtopic.php?f=5&t=70
+Many libraries are self contained modules, and you can quickly get started by
+copying the relevant Python file to your device. For example, to add the
+`base64` library, you can directly copy `base64/base64.py` to the `lib`
+directory on your device.
 
-Guidelines for packaging MicroPython modules for PyPI:
+Other libraries are packages, in which case you'll need to copy the directory instead. For example, to add `collections.defaultdict`, copy `collections/collections/__init__.py` and `collections.defaultdict/collections/defaultdict.py` to a directory named `lib/collections` on your device.
 
- * https://github.com/micropython/micropython/issues/413
+For devices that have network connectivity (e.g. PYBD, ESP8266, ESP32), they
+will have the `upip` module installed.
+
+```
+>>> import upip
+>>> upip.install('micropython-base64')
+>>> upip.install('micropython-collections.defaultdict')
+...
+>>> import base64
+>>> base64.b64decode('aGVsbG8sIG1pY3JvcHl0aG9u')
+b'hello, micropython'
+>>> from collections import defaultdict
+>>> d = defaultdict(int)
+>>> d[a] += 1
+```
+
+Future plans (and new contributor ideas)
+----------------------------------------
+
+* Provide compiled .mpy distributions.
+* Develop a set of example programs using these libraries.
+* Develop more MicroPython libraries for common tasks.
diff --git a/micropython/README.md b/micropython/README.md
@@ -0,0 +1,13 @@
+MicroPython-specific libraries
+==============================
+
+These are libraries that have been written specifically for use on MicroPython.
+
+In some cases, the libraries are inspired by or based on equivalent CPython standard libraries, but compatibility varies. The libraries are often named with a "u" prefix.
+
+Other libraries have been written specifically for MicroPython use cases.
+
+Future plans
+------------
+
+* More organised directory structure based on library purpose (e.g. drivers, network, etc).
diff --git a/python-stdlib/README.md b/python-stdlib/README.md
@@ -0,0 +1,30 @@
+CPython standard libraries
+==========================
+
+The libraries in this directory aim to provide compatible implementations of
+standard libraries to allow existing Python code to run un-modified on
+MicroPython.
+
+Compatibility ranges from:
+
+ * Many commonly-used methods and classes are provided with identical runtime semantics.
+ * A subset of methods and classes, with identical semantics for most use cases.
+ * Additional constants not provided in the main firmware (to keep size down).
+ * Stub methods and classes required to make code load without error, but may lead to runtime errors.
+
+
+Implementation
+--------------
+
+Many libraries are implemented in pure Python, often based on the original
+CPython implementation. (e.g. `collections.defaultdict`)
+
+Some libraries are based on or extend from the built-in "micro" modules in the
+MicroPython firmware, providing additional functionality that didn't need to
+be written in C. (e.g. `socket`, `struct`)
+
+
+Future plans (ideas for contributors):
+--------------------------------------
+
+* Add README.md to each library explaining compatibility and limitations.
diff --git a/unix-ffi/README.md b/unix-ffi/README.md
@@ -0,0 +1,17 @@
+Unix-specific libraries
+=======================
+
+These are libraries that will only run on the Unix port of MicroPython. There is some limited support for the Windows port too.
+
+**Note:** This directory is largely unmaintained, although large breaking changes are not expected.
+
+Background
+----------
+
+The libraries in this directory provide additional CPython compatibility using
+the host operating system's native libraries.
+
+This is implemented either by accessing the libraries directly via libffi, or by using built-in modules that are only available on the Unix port.
+
+In theory, this allows you to use MicroPython as a more complete drop-in
+replacement for CPython.
