From d0797fbc182b45194e6c15ffc145ed1c5e844ad6 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 2 Jul 2017 13:47:35 +0300 Subject: docs: Add glossary. We have enough terms or references throughout the docs which may be not immediately clear or have some important nuances. Referencing terms in gloassary is the best way to deal with that. --- docs/reference/glossary.rst | 99 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/reference/glossary.rst (limited to 'docs/reference/glossary.rst') diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst new file mode 100644 index 000000000..4099ae951 --- /dev/null +++ b/docs/reference/glossary.rst @@ -0,0 +1,99 @@ +Glossary +======== + +.. glossary:: + + baremetal + A system without (full-fledged) OS, like an :term:`MCU`. When + running on a baremetal system, MicroPython effectively becomes + its user-facing OS with a command interpreter (REPL). + + board + A PCB board. Oftentimes, the term is used to denote a particular + model of an :term:`MCU` system. Sometimes, it is used to actually + refer to :term:`MicroPython port` to a particular board (and then + may also refer to "boardless" ports like + :term:`Unix port `). + + CPython + CPython is the reference implementation of Python programming + language, and the most well-known one, which most of the people + run. It is however one of many implementations (among which + Jython, IronPython, PyPy, and many more, including MicroPython). + As there is no formal specification of the Python language, only + CPython documentation, it is not always easy to draw a line + between Python the language and CPython its particular + implementation. This however leaves more freedom for other + implementations. For example, MicroPython does a lot of things + differently than CPython, while still aspiring to be a Python + language implementation. + + GPIO + General-purpose input/output. The simplest means to control + electrical signals. With GPIO, user can configure hardware + signal pin to be either input or output, and set or get + its digital signal value (logical "0" or "1"). MicroPython + abstracts GPIO access using :class:`machine.Pin` and :class:`machine.Signal` + classes. + + GPIO port + A group of :term:`GPIO` pins, usually based on hardware + properties of these pins (e.g. controllable by the same + register). + + MCU + Microcontroller. Microcontrollers usually have much less resources + than a full-fledged computing system, but smaller, cheaper and + require much less power. MicroPython is designed to be small and + optimized enough to run on an average modern microcontroller. + + micropython-lib + MicroPython is (usually) distributed as a single executable/binary + file with just few builtin modules. There is no extensive standard + library comparable with :term:`CPython`. Instead, there is a related, but + separate project + `micropython-lib `_ + which provides implementations for many modules from CPython's + standard library. However, large subset of these modules required + POSIX-like environment (Linux, MacOS, Windows may be partially + supported), and thus would work or make sense only with MicroPython + Unix port. Some subset of modules however usable for baremetal ports + too. + + Unlike monolithic :term:`CPython` stdlib, micropython-lib modules + are intended to be installed individually - either using manual + copying or using :term:`upip`. + + MicroPython port + MicroPython supports different :term:`boards `, RTOSes, + and OSes, and can be relatively easily adapted to new systems. + MicroPython with support for a particular system is called a + "port" to that system. + + MicroPython Unix port + Unix port is one of the major :term:`MicroPython ports `. + It is intended to run on POSIX-compatible operating systems, like + Linux, MacOS, FreeBSD, Solaris, etc. It also serves as the basis + of Windows port. The importance of Unix port lies in the fact + that while there are many different :term:`boards `, so + two random users unlikely have the same board, almost all modern + OSes have some level of POSIX compatibility, so Unix port serves + as a kind of "common ground" to which any user can have access. + So, Unix port is used for initial prototyping, different kinds + of testing, development of machine-independent features, etc. + All users of MicroPython, even those which are interested only + in running MicroPython on :term:`MCU` systems, are recommended + to be familiar with Unix (or Windows) port, as it is important + productivity helper and a part of normal MicroPython workflow. + + port + Either :term:`MicroPython port` or :term:`GPIO port`. If not clear + from context, it's recommended to use full specification like one + of the above. + + upip + (Literally, "micro pip"). A package manage for MicroPython, inspired + by :term:`CPython`'s pip, but much smaller and with reduced functionality. + upip runs both on :term:`Unix port ` and on + :term:`baremetal` ports (those which offer filesystem and networking + support). -- cgit v1.2.3 From 46583e905771222d7b8395e4c33569e2624f1943 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 20 Aug 2017 10:11:44 +0300 Subject: docs/glossary: Elaborate on possible MicroPython port differences. State that this doc describes generic, "core" MicroPython functionality, any particular port may diverge in both directions, by both omitting some functionality, and adding more, both cases described outside the generic documentation. --- docs/reference/glossary.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/reference/glossary.rst') diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 4099ae951..0f93fff23 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -68,7 +68,13 @@ Glossary MicroPython supports different :term:`boards `, RTOSes, and OSes, and can be relatively easily adapted to new systems. MicroPython with support for a particular system is called a - "port" to that system. + "port" to that system. Different ports may have widely different + functionality. This documentation is intended to be a reference + of the generic APIs available across different ports ("MicroPython + core"). Note that some ports may still omit some APIs described + here (e.g. due to resource constraints). Any such differences, + and port-specific extensions beyond MicroPython core functionality, + would be described in the separate port-specific documentation. MicroPython Unix port Unix port is one of the major :term:`MicroPython ports `. -- cgit v1.2.3 From 387a8d26f9b54b37928aa08641b159334b669219 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 20 Aug 2017 10:44:02 +0300 Subject: docs/glossary: Fix typos in micropython-lib paragraph. --- docs/reference/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/reference/glossary.rst') diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 0f93fff23..98979afa9 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -54,10 +54,10 @@ Glossary separate project `micropython-lib `_ which provides implementations for many modules from CPython's - standard library. However, large subset of these modules required + standard library. However, large subset of these modules require POSIX-like environment (Linux, MacOS, Windows may be partially supported), and thus would work or make sense only with MicroPython - Unix port. Some subset of modules however usable for baremetal ports + Unix port. Some subset of modules is however usable for baremetal ports too. Unlike monolithic :term:`CPython` stdlib, micropython-lib modules -- cgit v1.2.3