djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/reference/glossary.rst: Add new terms and reduce complexity of old.

Browse Source
This commit is contained in:
Jim Mussared 2019-08-22 13:19:40 +10:00 committed by Damien George
parent e0befd9e04
commit a93495b66d
1 changed files with 160 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
docs/reference/glossary.rst
View File

@ -4,152 +4,197 @@ Glossary
.. glossary:: .. glossary::
baremetal 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, :term:`MCU`-based system. When running on a baremetal system,
MicroPython effectively becomes its user-facing OS with a command MicroPython effectively functions like a small operating system,
interpreter (REPL). 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 board
A PCB board. Oftentimes, the term is used to denote a particular Typically this refers to a printed circuit board (PCB) containing a
model of an :term:`MCU` system. Sometimes, it is used to actually :term:`microcontroller <MCU>` and supporting components.
refer to :term:`MicroPython port` to a particular board (and then MicroPython firmware is typically provided per-board, as the firmware
may also refer to "boardless" ports like contains both MCU-specific functionality but also board-level
:term:`Unix port <MicroPython Unix port>`). 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 callee-owned tuple
A tuple returned by some builtin function/method, containing data This is a MicroPython-specific construct where, for efficiency
which is valid for a limited time, usually until next call to the reasons, some built-in functions or methods may re-use the same
same function (or a group of related functions). After next call, underlying tuple object to return data. This avoids having to allocate
data in the tuple may be changed. This leads to the following a new tuple for every call, and reduces heap fragmentation. Programs
restriction on the usage of callee-owned tuples - references to should not hold references to callee-owned tuples and instead only
them cannot be stored. The only valid operation is extracting extract data from them (or make a copy).
values from them (including making a copy). Callee-owned tuples
is a MicroPython-specific construct (not available in the general CircuitPython
Python language), introduced for memory allocation optimization. A variant of MicroPython developed by `Adafruit Industries
The idea is that callee-owned tuple is allocated once and stored <https://circuitpython.org>`_.
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.)
CPython CPython
CPython is the reference implementation of Python programming CPython is the reference implementation of the Python programming
language, and the most well-known one, which most of the people language, and the most well-known one. It is, however, one of many
run. It is however one of many implementations (among which implementations (including Jython, IronPython, PyPy, and MicroPython).
Jython, IronPython, PyPy, and many more, including MicroPython). While MicroPython's implementation differs substantially from CPython,
As there is no formal specification of the Python language, only it aims to maintain as much compatibility as possible.
CPython documentation, it is not always easy to draw a line
between Python the language and CPython its particular cross-compiler
implementation. This however leaves more freedom for other Also known as ``mpy-cross``. This tool runs on your PC and converts a
implementations. For example, MicroPython does a lot of things :term:`.py file` containing MicroPython code into a :term:`.mpy file`
differently than CPython, while still aspiring to be a Python containing MicroPython bytecode. This means it loads faster (the board
language implementation. 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 GPIO
General-purpose input/output. The simplest means to control General-purpose input/output. The simplest means to control electrical
electrical signals. With GPIO, user can configure hardware signals (commonly referred to as "pins") on a microcontroller. GPIO
signal pin to be either input or output, and set or get typically allows pins to be either input or output, and to set or get
its digital signal value (logical "0" or "1"). MicroPython their digital value (logical "0" or "1"). MicroPython abstracts GPIO
abstracts GPIO access using :class:`machine.Pin` and :class:`machine.Signal` access using the :class:`machine.Pin` and :class:`machine.Signal`
classes. classes.
GPIO port GPIO port
A group of :term:`GPIO` pins, usually based on hardware A group of :term:`GPIO` pins, usually based on hardware properties of
properties of these pins (e.g. controllable by the same these pins (e.g. controllable by the same register).
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 interned string
A string referenced by its (unique) identity rather than its An optimisation used by MicroPython to improve the efficiency of
address. Interned strings are thus can be quickly compared just working with strings. An interned string is referenced by its (unique)
by their identifiers, instead of comparing by content. The identity rather than its address and can therefore be quickly compared
drawbacks of interned strings are that interning operation takes just by its identifier. It also means that identical strings can be
time (proportional to the number of existing interned strings, de-duplicated in memory. String interning is almost always invisible to
i.e. becoming slower and slower over time) and that the space the user.
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.
MCU MCU
Microcontroller. Microcontrollers usually have much less resources 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 require much less power. MicroPython is designed to be small and
optimized enough to run on an average modern microcontroller. optimized enough to run on an average modern microcontroller.
micropython-lib micropython-lib
MicroPython is (usually) distributed as a single executable/binary MicroPython is (usually) distributed as a single executable/binary
file with just few builtin modules. There is no extensive standard file with just few builtin modules. There is no extensive standard
library comparable with :term:`CPython`. Instead, there is a related, but library comparable with :term:`CPython`'s. Instead, there is a related,
separate project but separate project `micropython-lib
`micropython-lib <https://github.com/micropython/micropython-lib>`_ <https://github.com/micropython/micropython-lib>`_ which provides
which provides implementations for many modules from CPython's implementations for many modules from CPython's standard library.
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.
Unlike monolithic :term:`CPython` stdlib, micropython-lib modules Some of the modules are are implemented in pure Python, and are able to
are intended to be installed individually - either using manual be used on all ports. However, the majority of these modules use
copying or using :term:`upip`. :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 port
MicroPython supports different :term:`boards <board>`, RTOSes, MicroPython supports different :term:`boards <board>`, RTOSes, and
and OSes, and can be relatively easily adapted to new systems. OSes, and can be relatively easily adapted to new systems. MicroPython
MicroPython with support for a particular system is called a with support for a particular system is called a "port" to that
"port" to that system. Different ports may have widely different system. Different ports may have widely different functionality. This
functionality. This documentation is intended to be a reference documentation is intended to be a reference of the generic APIs
of the generic APIs available across different ports ("MicroPython available across different ports ("MicroPython core"). Note that some
core"). Note that some ports may still omit some APIs described ports may still omit some APIs described here (e.g. due to resource
here (e.g. due to resource constraints). Any such differences, constraints). Any such differences, and port-specific extensions
and port-specific extensions beyond MicroPython core functionality, beyond the MicroPython core functionality, would be described in the
would be described in the separate port-specific documentation. separate port-specific documentation.
MicroPython Unix port MicroPython Unix port
Unix port is one of the major :term:`MicroPython ports <MicroPython port>`. The unix port is one of the major :term:`MicroPython ports
It is intended to run on POSIX-compatible operating systems, like <MicroPython port>`. It is intended to run on POSIX-compatible
Linux, MacOS, FreeBSD, Solaris, etc. It also serves as the basis operating systems, like Linux, MacOS, FreeBSD, Solaris, etc. It also
of Windows port. The importance of Unix port lies in the fact serves as the basis of Windows port. The Unix port is very useful for
that while there are many different :term:`boards <board>`, so quick development and testing of the MicroPython language and
two random users unlikely have the same board, almost all modern machine-independent features. It can also function in a similar way to
OSes have some level of POSIX compatibility, so Unix port serves :term:`CPython`'s ``python`` executable.
as a kind of "common ground" to which any user can have access.
So, Unix port is used for initial prototyping, different kinds .mpy file
of testing, development of machine-independent features, etc. The output of the :term:`cross-compiler`. A compiled form of a
All users of MicroPython, even those which are interested only :term:`.py file` that contains MicroPython bytecode instead of Python
in running MicroPython on :term:`MCU` systems, are recommended source code.
to be familiar with Unix (or Windows) port, as it is important
productivity helper and a part of normal MicroPython workflow. 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 port
Either :term:`MicroPython port` or :term:`GPIO port`. If not clear Usually short for :term:`MicroPython port`, but could also refer to
from context, it's recommended to use full specification like one :term:`GPIO port`.
of the above.
.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 stream
Also known as a "file-like object". An object which provides sequential Also known as a "file-like object". An Python object which provides
read-write access to the underlying data. A stream object implements sequential read-write access to the underlying data. A stream object
a corresponding interface, which consists of methods like ``read()``, implements a corresponding interface, which consists of methods like
``write()``, ``readinto()``, ``seek()``, ``flush()``, ``close()``, etc. ``read()``, ``write()``, ``readinto()``, ``seek()``, ``flush()``,
A stream is an important concept in MicroPython, many I/O objects ``close()``, etc. A stream is an important concept in MicroPython;
implement the stream interface, and thus can be used consistently and many I/O objects implement the stream interface, and thus can be used
interchangeably in different contexts. For more information on consistently and interchangeably in different contexts. For more
streams in MicroPython, see `uio` module. 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 upip
(Literally, "micro pip"). A package manage for MicroPython, inspired (Literally, "micro pip"). A package manager for MicroPython, inspired
by :term:`CPython`'s pip, but much smaller and with reduced functionality. by :term:`CPython`'s pip, but much smaller and with reduced
upip runs both on :term:`Unix port <MicroPython Unix port>` and on functionality.
:term:`baremetal` ports (those which offer filesystem and networking upip runs both on the :term:`Unix port <MicroPython Unix port>` and on
support). :term:`baremetal` ports which offer filesystem and networking support.