Skip to content

Commit 29e59eb

Browse files
jeplerjepler
committed
Restore accidentally deleted 'glossary'
1 parent 4f47a5e commit 29e59eb

File tree

1 file changed

+175
-0
lines changed

1 file changed

+175
-0
lines changed

‎docs/reference/glossary.rst

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
Glossary
2+
========
3+
4+
.. glossary::
5+
6+
baremetal
7+
A system without a (full-fledged) operating system, for example an
8+
:term:`MCU`-based system. When running on a baremetal system,
9+
MicroPython effectively functions like a small operating system,
10+
running user programs and providing a command interpreter
11+
(:term:`REPL`).
12+
13+
buffer protocol
14+
Any Python object that can be automatically converted into bytes, such
15+
as ``bytes``, ``bytearray``, ``memoryview`` and ``str`` objects, which
16+
all implement the "buffer protocol".
17+
18+
board
19+
Typically this refers to a printed circuit board (PCB) containing a
20+
:term:`microcontroller <MCU>` and supporting components.
21+
MicroPython firmware is typically provided per-board, as the firmware
22+
contains both MCU-specific functionality but also board-level
23+
functionality such as drivers or pin names.
24+
25+
bytecode
26+
A compact representation of a Python program that generated by
27+
compiling the Python source code. This is what the VM actually
28+
executes. Bytecode is typically generated automatically at runtime and
29+
is invisible to the user. Note that while :term:`CPython` and
30+
MicroPython both use bytecode, the format is different. You can also
31+
pre-compile source code offline using the :term:`cross-compiler`.
32+
33+
callee-owned tuple
34+
This is a MicroPython-specific construct where, for efficiency
35+
reasons, some built-in functions or methods may re-use the same
36+
underlying tuple object to return data. This avoids having to allocate
37+
a new tuple for every call, and reduces heap fragmentation. Programs
38+
should not hold references to callee-owned tuples and instead only
39+
extract data from them (or make a copy).
40+
41+
CircuitPython
42+
A variant of MicroPython developed by `Adafruit Industries
43+
<https://circuitpython.org>`_.
44+
45+
CPython
46+
CPython is the reference implementation of the Python programming
47+
language, and the most well-known one. It is, however, one of many
48+
implementations (including Jython, IronPython, PyPy, and MicroPython).
49+
While MicroPython's implementation differs substantially from CPython,
50+
it aims to maintain as much compatibility as possible.
51+
52+
cross-compiler
53+
Also known as ``mpy-cross``. This tool runs on your PC and converts a
54+
:term:`.py file` containing MicroPython code into a :term:`.mpy file`
55+
containing MicroPython bytecode. This means it loads faster (the board
56+
doesn't have to compile the code), and uses less space on flash (the
57+
bytecode is more space efficient).
58+
59+
driver
60+
A MicroPython library that implements support for a particular
61+
component, such as a sensor or display.
62+
63+
FFI
64+
Acronym for Foreign Function Interface. A mechanism used by the
65+
:term:`MicroPython Unix port` to access operating system functionality.
66+
This is not available on :term:`baremetal` ports.
67+
68+
filesystem
69+
Most MicroPython ports and boards provide a filesystem stored in flash
70+
that is available to user code via the standard Python file APIs such
71+
as ``open()``. Some boards also make this internal filesystem
72+
accessible to the host via USB mass-storage.
73+
74+
frozen module
75+
A Python module that has been cross compiled and bundled into the
76+
firmware image. This reduces RAM requirements as the code is executed
77+
directly from flash.
78+
79+
Garbage Collector
80+
A background process that runs in Python (and MicroPython) to reclaim
81+
unused memory in the :term:`heap`.
82+
83+
GPIO
84+
General-purpose input/output. The simplest means to control electrical
85+
signals (commonly referred to as "pins") on a microcontroller. GPIO
86+
typically allows pins to be either input or output, and to set or get
87+
their digital value (logical "0" or "1"). MicroPython abstracts GPIO
88+
access using the :class:`machine.Pin` and :class:`machine.Signal`
89+
classes.
90+
91+
GPIO port
92+
A group of :term:`GPIO` pins, usually based on hardware properties of
93+
these pins (e.g. controllable by the same register).
94+
95+
heap
96+
A region of RAM where MicroPython stores dynamic data. It is managed
97+
automatically by the :term:`Garbage Collector`. Different MCUs and
98+
boards have vastly different amounts of RAM available for the heap, so
99+
this will affect how complex your program can be.
100+
101+
interned string
102+
An optimisation used by MicroPython to improve the efficiency of
103+
working with strings. An interned string is referenced by its (unique)
104+
identity rather than its address and can therefore be quickly compared
105+
just by its identifier. It also means that identical strings can be
106+
de-duplicated in memory. String interning is almost always invisible to
107+
the user.
108+
109+
MCU
110+
Microcontroller. Microcontrollers usually have much less resources
111+
than a desktop, laptop, or phone, but are smaller, cheaper and
112+
require much less power. MicroPython is designed to be small and
113+
optimized enough to run on an average modern microcontroller.
114+
115+
MicroPython port
116+
MicroPython supports different :term:`boards <board>`, RTOSes, and
117+
OSes, and can be relatively easily adapted to new systems. MicroPython
118+
with support for a particular system is called a "port" to that
119+
system. Different ports may have widely different functionality. This
120+
documentation is intended to be a reference of the generic APIs
121+
available across different ports ("MicroPython core"). Note that some
122+
ports may still omit some APIs described here (e.g. due to resource
123+
constraints). Any such differences, and port-specific extensions
124+
beyond the MicroPython core functionality, would be described in the
125+
separate port-specific documentation.
126+
127+
MicroPython Unix port
128+
The unix port is one of the major :term:`MicroPython ports
129+
<MicroPython port>`. It is intended to run on POSIX-compatible
130+
operating systems, like Linux, MacOS, FreeBSD, Solaris, etc. It also
131+
serves as the basis of Windows port. The Unix port is very useful for
132+
quick development and testing of the MicroPython language and
133+
machine-independent features. It can also function in a similar way to
134+
:term:`CPython`'s ``python`` executable.
135+
136+
.mpy file
137+
The output of the :term:`cross-compiler`. A compiled form of a
138+
:term:`.py file` that contains MicroPython bytecode instead of Python
139+
source code.
140+
141+
native
142+
Usually refers to "native code", i.e. machine code for the target
143+
microcontroller (such as ARM Thumb, Xtensa, x86/x64). The ``@native``
144+
decorator can be applied to a MicroPython function to generate native
145+
code instead of bytecode for that function, which will likely be
146+
faster but use more RAM.
147+
148+
port
149+
Usually short for :term:`MicroPython port`, but could also refer to
150+
:term:`GPIO port`.
151+
152+
.py file
153+
A file containing Python source code.
154+
155+
REPL
156+
An acronym for "Read, Eval, Print, Loop". This is the interactive
157+
Python prompt, useful for debugging or testing short snippets of code.
158+
Most MicroPython boards make a REPL available over a UART, and this is
159+
typically accessible on a host PC via USB.
160+
161+
stream
162+
Also known as a "file-like object". An Python object which provides
163+
sequential read-write access to the underlying data. A stream object
164+
implements a corresponding interface, which consists of methods like
165+
``read()``, ``write()``, ``readinto()``, ``seek()``, ``flush()``,
166+
``close()``, etc. A stream is an important concept in MicroPython;
167+
many I/O objects implement the stream interface, and thus can be used
168+
consistently and interchangeably in different contexts. For more
169+
information on streams in MicroPython, see the `io` module.
170+
171+
UART
172+
Acronym for "Universal Asynchronous Receiver/Transmitter". This is a
173+
peripheral that sends data over a pair of pins (TX & RX). Many boards
174+
include a way to make at least one of the UARTs available to a host PC
175+
as a serial port over USB.

0 commit comments

Comments
 (0)