docs/reference/glossary.rst: Add new terms and reduce complexity of old.
Jim Mussared
Damien George
parent
e0befd9e04
commit
a93495b66d
|
|
@ -4,152 +4,197 @@ Glossary
|
|||
.. glossary::
|
||||
|
||||
baremetal
|
||||
A system without a (full-fledged) OS, for example an
|
||||
A system without a (full-fledged) operating system, for example an
|
||||
:term:`MCU`-based system. When running on a baremetal system,
|
||||
MicroPython effectively becomes its user-facing OS with a command
|
||||
interpreter (REPL).
|
||||
MicroPython effectively functions like a small operating system,
|
||||
running user programs and providing a command interpreter
|
||||
(:term:`REPL`).
|
||||
|
||||
buffer protocol
|
||||
Any Python object that can be automatically converted into bytes, such
|
||||
as ``bytes``, ``bytearray``, ``memoryview`` and ``str`` objects, which
|
||||
all implement the "buffer protocol".
|
||||
|
||||
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 <MicroPython Unix port>`).
|
||||
Typically this refers to a printed circuit board (PCB) containing a
|
||||
:term:`microcontroller <MCU>` and supporting components.
|
||||
MicroPython firmware is typically provided per-board, as the firmware
|
||||
contains both MCU-specific functionality but also board-level
|
||||
functionality such as drivers or pin names.
|
||||
|
||||
bytecode
|
||||
A compact representation of a Python program that generated by
|
||||
compiling the Python source code. This is what the VM actually
|
||||
executes. Bytecode is typically generated automatically at runtime and
|
||||
is invisible to the user. Note that while :term:`CPython` and
|
||||
MicroPython both use bytecode, the format is different. You can also
|
||||
pre-compile source code offline using the :term:`cross-compiler`.
|
||||
|
||||
callee-owned tuple
|
||||
A tuple returned by some builtin function/method, containing data
|
||||
which is valid for a limited time, usually until next call to the
|
||||
same function (or a group of related functions). After next call,
|
||||
data in the tuple may be changed. This leads to the following
|
||||
restriction on the usage of callee-owned tuples - references to
|
||||
them cannot be stored. The only valid operation is extracting
|
||||
values from them (including making a copy). Callee-owned tuples
|
||||
is a MicroPython-specific construct (not available in the general
|
||||
Python language), introduced for memory allocation optimization.
|
||||
The idea is that callee-owned tuple is allocated once and stored
|
||||
on the callee side. Subsequent calls don't require allocation,
|
||||
allowing to return multiple values when allocation is not possible
|
||||
(e.g. in interrupt context) or not desirable (because allocation
|
||||
inherently leads to memory fragmentation). Note that callee-owned
|
||||
tuples are effectively mutable tuples, making an exception to
|
||||
Python's rule that tuples are immutable. (It may be interesting
|
||||
why tuples were used for such a purpose then, instead of mutable
|
||||
lists - the reason for that is that lists are mutable from user
|
||||
application side too, so a user could do things to a callee-owned
|
||||
list which the callee doesn't expect and could lead to problems;
|
||||
a tuple is protected from this.)
|
||||
This is a MicroPython-specific construct where, for efficiency
|
||||
reasons, some built-in functions or methods may re-use the same
|
||||
underlying tuple object to return data. This avoids having to allocate
|
||||
a new tuple for every call, and reduces heap fragmentation. Programs
|
||||
should not hold references to callee-owned tuples and instead only
|
||||
extract data from them (or make a copy).
|
||||
|
||||
CircuitPython
|
||||
A variant of MicroPython developed by `Adafruit Industries
|
||||
<https://circuitpython.org>`_.
|
||||
|
||||
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.
|
||||
CPython is the reference implementation of the Python programming
|
||||
language, and the most well-known one. It is, however, one of many
|
||||
implementations (including Jython, IronPython, PyPy, and MicroPython).
|
||||
While MicroPython's implementation differs substantially from CPython,
|
||||
it aims to maintain as much compatibility as possible.
|
||||
|
||||
cross-compiler
|
||||
Also known as ``mpy-cross``. This tool runs on your PC and converts a
|
||||
:term:`.py file` containing MicroPython code into a :term:`.mpy file`
|
||||
containing MicroPython bytecode. This means it loads faster (the board
|
||||
doesn't have to compile the code), and uses less space on flash (the
|
||||
bytecode is more space efficient).
|
||||
|
||||
driver
|
||||
A MicroPython library that implements support for a particular
|
||||
component, such as a sensor or display.
|
||||
|
||||
FFI
|
||||
Acronym for Foreign Function Interface. A mechanism used by the
|
||||
:term:`MicroPython Unix port` to access operating system functionality.
|
||||
This is not available on :term:`baremetal` ports.
|
||||
|
||||
filesystem
|
||||
Most MicroPython ports and boards provide a filesystem stored in flash
|
||||
that is available to user code via the standard Python file APIs such
|
||||
as ``open()``. Some boards also make this internal filesystem
|
||||
accessible to the host via USB mass-storage.
|
||||
|
||||
frozen module
|
||||
A Python module that has been cross compiled and bundled into the
|
||||
firmware image. This reduces RAM requirements as the code is executed
|
||||
directly from flash.
|
||||
|
||||
Garbage Collector
|
||||
A background process that runs in Python (and MicroPython) to reclaim
|
||||
unused memory in the :term:`heap`.
|
||||
|
||||
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`
|
||||
General-purpose input/output. The simplest means to control electrical
|
||||
signals (commonly referred to as "pins") on a microcontroller. GPIO
|
||||
typically allows pins to be either input or output, and to set or get
|
||||
their digital value (logical "0" or "1"). MicroPython abstracts GPIO
|
||||
access using the :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).
|
||||
A group of :term:`GPIO` pins, usually based on hardware properties of
|
||||
these pins (e.g. controllable by the same register).
|
||||
|
||||
heap
|
||||
A region of RAM where MicroPython stores dynamic data. It is managed
|
||||
automatically by the :term:`Garbage Collector`. Different MCUs and
|
||||
boards have vastly different amounts of RAM available for the heap, so
|
||||
this will affect how complex your program can be.
|
||||
|
||||
interned string
|
||||
A string referenced by its (unique) identity rather than its
|
||||
address. Interned strings are thus can be quickly compared just
|
||||
by their identifiers, instead of comparing by content. The
|
||||
drawbacks of interned strings are that interning operation takes
|
||||
time (proportional to the number of existing interned strings,
|
||||
i.e. becoming slower and slower over time) and that the space
|
||||
used for interned strings is not reclaimable. String interning
|
||||
is done automatically by MicroPython compiler and runtimer when
|
||||
it's either required by the implementation (e.g. function keyword
|
||||
arguments are represented by interned string id's) or deemed
|
||||
beneficial (e.g. for short enough strings, which have a chance
|
||||
to be repeated, and thus interning them would save memory on
|
||||
copies). Most of string and I/O operations don't produce interned
|
||||
strings due to drawbacks described above.
|
||||
An optimisation used by MicroPython to improve the efficiency of
|
||||
working with strings. An interned string is referenced by its (unique)
|
||||
identity rather than its address and can therefore be quickly compared
|
||||
just by its identifier. It also means that identical strings can be
|
||||
de-duplicated in memory. String interning is almost always invisible to
|
||||
the user.
|
||||
|
||||
MCU
|
||||
Microcontroller. Microcontrollers usually have much less resources
|
||||
than a full-fledged computing system, but smaller, cheaper and
|
||||
than a desktop, laptop, or phone, but are 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 <https://github.com/micropython/micropython-lib>`_
|
||||
which provides implementations for many modules from CPython's
|
||||
standard library. However, large subset of these modules require
|
||||
POSIX-like environment (Linux, FreeBSD, MacOS, etc.; Windows may be
|
||||
partially supported), and thus would work or make sense only with
|
||||
`MicroPython Unix port`. Some subset of modules is however usable
|
||||
for `baremetal` ports too.
|
||||
library comparable with :term:`CPython`'s. Instead, there is a related,
|
||||
but separate project `micropython-lib
|
||||
<https://github.com/micropython/micropython-lib>`_ which provides
|
||||
implementations for many modules from CPython's standard library.
|
||||
|
||||
Unlike monolithic :term:`CPython` stdlib, micropython-lib modules
|
||||
are intended to be installed individually - either using manual
|
||||
copying or using :term:`upip`.
|
||||
Some of the modules are are implemented in pure Python, and are able to
|
||||
be used on all ports. However, the majority of these modules use
|
||||
:term:`FFI` to access operating system functionality, and as such can
|
||||
only be used on the :term:`MicroPython Unix port` (with limited support
|
||||
for Windows).
|
||||
|
||||
Unlike the :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 <board>`, 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. 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 supports different :term:`boards <board>`, 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. 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 the 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 <MicroPython port>`.
|
||||
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 <board>`, 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.
|
||||
The unix port is one of the major :term:`MicroPython ports
|
||||
<MicroPython port>`. 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 Unix port is very useful for
|
||||
quick development and testing of the MicroPython language and
|
||||
machine-independent features. It can also function in a similar way to
|
||||
:term:`CPython`'s ``python`` executable.
|
||||
|
||||
.mpy file
|
||||
The output of the :term:`cross-compiler`. A compiled form of a
|
||||
:term:`.py file` that contains MicroPython bytecode instead of Python
|
||||
source code.
|
||||
|
||||
native
|
||||
Usually refers to "native code", i.e. machine code for the target
|
||||
microcontroller (such as ARM Thumb, Xtensa, x86/x64). The ``@native``
|
||||
decorator can be applied to a MicroPython function to generate native
|
||||
code instead of bytecode for that function, which will likely be
|
||||
faster but use more RAM.
|
||||
|
||||
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.
|
||||
Usually short for :term:`MicroPython port`, but could also refer to
|
||||
:term:`GPIO port`.
|
||||
|
||||
.py file
|
||||
A file containing Python source code.
|
||||
|
||||
REPL
|
||||
An acronym for "Read, Eval, Print, Loop". This is the interactive
|
||||
Python prompt, useful for debugging or testing short snippets of code.
|
||||
Most MicroPython boards make a REPL available over a UART, and this is
|
||||
typically accessible on a host PC via USB.
|
||||
|
||||
stream
|
||||
Also known as a "file-like object". An object which provides sequential
|
||||
read-write access to the underlying data. A stream object implements
|
||||
a corresponding interface, which consists of methods like ``read()``,
|
||||
``write()``, ``readinto()``, ``seek()``, ``flush()``, ``close()``, etc.
|
||||
A stream is an important concept in MicroPython, many I/O objects
|
||||
implement the stream interface, and thus can be used consistently and
|
||||
interchangeably in different contexts. For more information on
|
||||
streams in MicroPython, see `uio` module.
|
||||
Also known as a "file-like object". An Python object which provides
|
||||
sequential read-write access to the underlying data. A stream object
|
||||
implements a corresponding interface, which consists of methods like
|
||||
``read()``, ``write()``, ``readinto()``, ``seek()``, ``flush()``,
|
||||
``close()``, etc. A stream is an important concept in MicroPython;
|
||||
many I/O objects implement the stream interface, and thus can be used
|
||||
consistently and interchangeably in different contexts. For more
|
||||
information on streams in MicroPython, see the `uio` module.
|
||||
|
||||
UART
|
||||
Acronym for "Universal Asynchronous Receiver/Transmitter". This is a
|
||||
peripheral that sends data over a pair of pins (TX & RX). Many boards
|
||||
include a way to make at least one of the UARTs available to a host PC
|
||||
as a serial port over USB.
|
||||
|
||||
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 <MicroPython Unix port>` and on
|
||||
:term:`baremetal` ports (those which offer filesystem and networking
|
||||
support).
|
||||
(Literally, "micro pip"). A package manager for MicroPython, inspired
|
||||
by :term:`CPython`'s pip, but much smaller and with reduced
|
||||
functionality.
|
||||
upip runs both on the :term:`Unix port <MicroPython Unix port>` and on
|
||||
:term:`baremetal` ports which offer filesystem and networking support.
|
||||
|
|
|
|||
Loading…
Reference in New Issue