Skip to content

Commit dc01676

Browse files
tannewttannewt
committed
Add back glossary to fix docs build
1 parent 8b8944a commit dc01676

File tree

3 files changed

+215
-1
lines changed

3 files changed

+215
-1
lines changed

‎conf.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,8 @@ def autoapi_prepare_jinja_env(jinja_env):
202202
"ports/cxd56/spresense-exported-sdk",
203203
"ports/espressif/certificates",
204204
"ports/espressif/esp-idf",
205-
"ports/espressif/esp32-camera",
205+
"ports/espressif/esp-camera",
206+
"ports/espressif/esp-protocols",
206207
"ports/espressif/.idf_tools",
207208
"ports/espressif/peripherals",
208209
"ports/litex/hw",

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Full Table of Contents
3333
design_guide
3434
porting
3535
common_hal
36+
reference/glossary.rst
3637

3738
.. toctree::
3839
:maxdepth: 2

‎docs/reference/glossary.rst

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
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 :term:`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-lib
116+
MicroPython is (usually) distributed as a single executable/binary
117+
file with just few builtin modules. There is no extensive standard
118+
library comparable with :term:`CPython`'s. Instead, there is a related,
119+
but separate project `micropython-lib
120+
<https://github.com/micropython/micropython-lib>`_ which provides
121+
implementations for many modules from CPython's standard library.
122+
123+
Some of the modules are are implemented in pure Python, and are able to
124+
be used on all ports. However, the majority of these modules use
125+
:term:`FFI` to access operating system functionality, and as such can
126+
only be used on the :term:`MicroPython Unix port` (with limited support
127+
for Windows).
128+
129+
Unlike the :term:`CPython` stdlib, micropython-lib modules are
130+
intended to be installed individually - either using manual copying or
131+
using :term:`mip`.
132+
133+
MicroPython port
134+
MicroPython supports different :term:`boards <board>`, RTOSes, and
135+
OSes, and can be relatively easily adapted to new systems. MicroPython
136+
with support for a particular system is called a "port" to that
137+
system. Different ports may have widely different functionality. This
138+
documentation is intended to be a reference of the generic APIs
139+
available across different ports ("MicroPython core"). Note that some
140+
ports may still omit some APIs described here (e.g. due to resource
141+
constraints). Any such differences, and port-specific extensions
142+
beyond the MicroPython core functionality, would be described in the
143+
separate port-specific documentation.
144+
145+
MicroPython Unix port
146+
The unix port is one of the major :term:`MicroPython ports
147+
<MicroPython port>`. It is intended to run on POSIX-compatible
148+
operating systems, like Linux, MacOS, FreeBSD, Solaris, etc. It also
149+
serves as the basis of Windows port. The Unix port is very useful for
150+
quick development and testing of the MicroPython language and
151+
machine-independent features. It can also function in a similar way to
152+
:term:`CPython`'s ``python`` executable.
153+
154+
mip
155+
A package installer for MicroPython (mip - "mip installs packages"). It
156+
installs MicroPython packages either from :term:`micropython-lib`,
157+
GitHub, or arbitrary URLs. mip can be used on-device on
158+
network-capable boards, and internally by tools such
159+
as :term:`mpremote`.
160+
161+
mpremote
162+
A tool for interacting with a MicroPython device.
163+
164+
.mpy file
165+
The output of the :term:`cross-compiler`. A compiled form of a
166+
:term:`.py file` that contains MicroPython :term:`bytecode` instead of
167+
Python source code.
168+
169+
native
170+
Usually refers to "native code", i.e. machine code for the target
171+
microcontroller (such as ARM Thumb, Xtensa, x86/x64). The ``@native``
172+
decorator can be applied to a MicroPython function to generate native
173+
code instead of :term:`bytecode` for that function, which will likely be
174+
faster but use more RAM.
175+
176+
port
177+
Usually short for :term:`MicroPython port`, but could also refer to
178+
:term:`GPIO port`.
179+
180+
.py file
181+
A file containing Python source code.
182+
183+
REPL
184+
An acronym for "Read, Eval, Print, Loop". This is the interactive
185+
Python prompt, useful for debugging or testing short snippets of code.
186+
Most MicroPython boards make a REPL available over a UART, and this is
187+
typically accessible on a host PC via USB.
188+
189+
stream
190+
Also known as a "file-like object". A Python object which provides
191+
sequential read-write access to the underlying data. A stream object
192+
implements a corresponding interface, which consists of methods like
193+
``read()``, ``write()``, ``readinto()``, ``seek()``, ``flush()``,
194+
``close()``, etc. A stream is an important concept in MicroPython;
195+
many I/O objects implement the stream interface, and thus can be used
196+
consistently and interchangeably in different contexts. For more
197+
information on streams in MicroPython, see the `io` module.
198+
199+
UART
200+
Acronym for "Universal Asynchronous Receiver/Transmitter". This is a
201+
peripheral that sends data over a pair of pins (TX & RX). Many boards
202+
include a way to make at least one of the UARTs available to a host PC
203+
as a serial port over USB.
204+
205+
upip
206+
A now-obsolete package manager for MicroPython, inspired
207+
by :term:`CPython`'s pip, but much smaller and with reduced
208+
functionality. See its replacement, :term:`mip`.
209+
210+
webrepl
211+
A way of connecting to the REPL (and transferring files) on a device
212+
over the internet from a browser. See https://micropython.org/webrepl

0 commit comments

Comments
 (0)