summaryrefslogtreecommitdiff
path: root/docs/reference
AgeCommit message (Collapse)Author
2024-07-05docs: Update docs to replace ifconfig with ipconfig.Felix Dörre
Follow up to 1c6012b0b5c62f18130217f30e73ad3ce4c8c9e6 Signed-off-by: Felix Dörre <felix@dogcraft.de>
2024-06-21mpy-cross: Add RISC-V RV32IMC support in MPY files.Alessandro Gatti
MPY files can now hold generated RV32IMC native code. This can be accomplished by passing the `-march=rv32imc` flag to mpy-cross. Signed-off-by: Alessandro Gatti <a.gatti@frob.it>
2024-05-15docs/reference: Document how to mip install packages from GitLab.Olivier Lenoir
Signed-off-by: Olivier Lenoir <olivier.len02@gmail.com>
2024-03-28docs/reference/mpyfiles: Document change in .mpy sub-version.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2024-02-08tools/manifestfile.py: Change library search to use a list of paths.Damien George
This commit changes how library packages are searched for when a manifest file is loaded: there is now simply a list of library paths that is searched in order for the given package. This list defaults to the main directories in micropython-lib, but can be added to -- either appended or prepended -- by using `add_library()`. In particular the way unix-ffi library packages are searched has changed, because the `unix_ffi` argument to `require()` is now removed. Instead, if a build wants to include packages from micropython-lib/unix-ffi, then it must explicitly add this to the list of paths to search using: add_library("unix-ffi", "$(MPY_LIB_DIR)/unix-ffi") Work done in collaboration with Jim Mussared. Signed-off-by: Damien George <damien@micropython.org>
2024-02-07docs: Use vfs module instead of os.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2024-02-07docs/reference/micropython2_migration.rst: Add info about os and vfs.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2024-02-07docs/library: Move vfs functions and classes from os to vfs module docs.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2024-01-05all: Fix "reuse" and "overridden" spelling mistakes.Damien George
Codespell doesn't pick up "re-used" or "re-uses", and ignores the tests/ directory, so fix these manually. Signed-off-by: Damien George <damien@micropython.org>
2023-10-27docs/reference/micropython2_migration: Add migration guide.Jim Mussared
This is just scaffolding for now, but the idea is that there should be an addition to this file for every commit that uses the `MICROPY_PREVIEW_VERSION_2` macro. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-10-16docs/reference/mpyfiles: Document change in .mpy sub-version.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2023-10-03all: Fix various spelling mistakes found by codespell 2.2.6.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2023-09-29tools/mpremote: Add support for rfc2217, serial over TCP.Jos Verlinde
Signed-off-by: Jos Verlinde <jos_verlinde@hotmail.com>
2023-06-19docs: Rename uasyncio to asyncio.Jim Mussared
This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-06-02docs/reference/mpremote.rst: Extend the mpremote guide.Jim Mussared
Changes in this commit: - Add a extra detail to each of the commands. - Add more about handling options and arguments. - Include shortcut commands that behave like real commands to the command list (e.g. bootloader, rtc). - Add extra information and reword to address common misconceptions, in particular how commands chain together. - Add additional examples showing some more interesting combinations. - Add descriptions to each of the examples. - Add pipx installation instructions. - Describe how user-configuration works. This work was sponsored by Google Season of Docs. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-06-02docs/reference/packages: Add GitHub repo to package example dependency.Jonas Scharpf
Signed-off-by: Jonas Scharpf <jonas@brainelectronics.de>
2023-05-23docs/reference/speed_python: Remove 4-arg limit for viper.Jim Mussared
This limit was removed in a676b5acf6ee9c17926cf9786370d30a077d99c0. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-05-22tools/mpremote: Add repl option to escape non-printable characters.Damien George
This commit adds the "--escape-non-printable" option to the repl command. When specified the REPL console will escape non-printable characters, printing them as their hex value in square brackets. This escaping behaviour was previously the default and only behaviour, but it is now opt-in. As part of this change, the speed of echoing device data to the console is improved by by reading and writing in chunks. Signed-off-by: Damien George <damien@micropython.org>
2023-05-11docs/reference/mpyfiles: Add release info on v6.1.David Lechner
This documents when MPY v6.1 was released. Also add some clarification on how the version is encoded in the header. Signed-off-by: David Lechner <david@pybricks.com>
2023-05-01docs/reference: Remove double 'are' in glossary.algonell
2023-04-27all: Fix spelling mistakes based on codespell check.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2023-01-19docs/reference/constrained: Add missing heap-dump symbols to mem_info().Chris Overgaauw
2022-12-07docs/library/neopixel: Update GitHub URL for neopixel.py link.Jim Mussared
Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2022-11-25tools/mpremote: Only auto connect to serial device with USB VID/PID.Michael Mogenson
On MacOS and Windows there are a few default serial devices that are returned by `serial.tools.list_ports.comports()`. For example on MacOS: ``` {'description': 'n/a', 'device': '/dev/cu.Bluetooth-Incoming-Port', 'hwid': 'n/a', 'interface': None, 'location': None, 'manufacturer': None, 'name': 'cu.Bluetooth-Incoming-Port', 'pid': None, 'product': None, 'serial_number': None, 'vid': None} {'description': 'n/a', 'device': '/dev/cu.wlan-debug', 'hwid': 'n/a', 'interface': None, 'location': None, 'manufacturer': None, 'name': 'cu.wlan-debug', 'pid': None, 'product': None, 'serial_number': None, 'vid': None} ``` Users of mpremote most likely do not want to connect to these ports. It would be desirable if mpremote did not select this ports when using the auto connect behavior. These serial ports do not have USB VID or PID values and serial ports for Micropython boards with FTDI/serial-to-USB adapter or native USB CDC/ACM support do. Check for the presence of a USB VID / PID int value when selecting a serial port to auto connect to. All serial ports will still be listed by the `list` command and can still be selected by name when connecting. Signed-off-by: Michael Mogenson <michael.mogenson@gmail.com>
2022-10-01tools/mpremote: Add `mpremote mip install` to install packages.Jim Mussared
This supports the same package sources as the new `mip` tool. - micropython-lib (by name) - http(s) & github packages with json description - directly downloading a .py/.mpy file The version is specified with an optional `@version` on the end of the package name. The target dir, index, and mpy/no-mpy can be set through command line args. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2022-09-30top: Replace upip with mip everywhere.Jim Mussared
Updates all README.md and docs, and manifests to `require("mip")`. Also extend and improve the documentation on freezing and packaging. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2022-09-19py/persistentcode: Introduce .mpy sub-version.Jim Mussared
The intent is to allow us to make breaking changes to the native ABI (e.g. changes to dynruntime.h) without needing the bytecode version to increment. With this commit the two bits previously used for the feature flags (but now unused as of .mpy version 6) encode a sub-version. A bytecode-only .mpy file can be loaded as long as MPY_VERSION matches, but a native .mpy (i.e. one with an arch set) must also match MPY_SUB_VERSION. This allows 3 additional updates to the native ABI per bytecode revision. The sub-version is set to 1 because the previous commits that changed the layout of mp_obj_type_t have changed the native ABI. Signed-off-by: Jim Mussared <jim.mussared@gmail.com> Signed-off-by: Damien George <damien@micropython.org>
2022-09-06drivers/display: Don't include tests by default.Damien George
The tests can be copied to the board if needed. Also update the docs to reflect this change. Signed-off-by: Damien George <damien@micropython.org>
2022-08-26tools/mpremote: Print nicer errors for unsupported 'cp -r' arguments.Damien George
Also document support for 'cp :a :b'. Signed-off-by: Damien George <damien@micropython.org>
2022-08-18tools/mpremote: Add "edit" command.Jim Mussared
This allows a remote file to be edited locally by copying it over, running the local editor, then copying it back. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2022-08-18tools/pyboard.py: Add "touch" filesystem command.Jim Mussared
Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2022-08-18tools/mpremote: Allow + terminator for fs commands.Jim Mussared
Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2022-06-10docs/reference/mpyfiles: Update .mpy description to match latest format.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2022-05-27docs/reference/manifest: Add link to details about opt-level for freeze.Andrew Leech
2022-05-18py/parse: Allow all constant objects to be used in "X = const(o)".Damien George
Now that constant tuples are supported in the parser, eg (1, True, "str"), it's a small step to allow anything that is a constant to be used with the pattern: from micropython import const X = const(obj) This commit makes the required changes to allow the following types of constants: from micropython import const _INT = const(123) _FLOAT = const(1.2) _COMPLEX = const(3.4j) _STR = const("str") _BYTES = const(b"bytes") _TUPLE = const((_INT, _STR, _BYTES)) _TUPLE2 = const((None, False, True, ..., (), _TUPLE)) Prior to this, only integers could be used in const(...). Signed-off-by: Damien George <damien@micropython.org>
2022-05-17docs/reference/mpyfiles: Remove docs about mpy flags and qstr win size.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2022-04-28py/modsys: Rename sys.implementation.mpy to sys.implementation._mpy.Damien George
Per CPython docs, non-standard attributes must begin with an underscore. Signed-off-by: Damien George <damien@micropython.org>
2022-04-15docs/reference: Update constrained docs now that tuples can be const.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2022-04-11tools/mpremote: Add option to mount cmd to allow "unsafe" symlinks.Rob Knegjens
Specifying the option `--unsafe-links` (or `-l`) to `mpremote mount` will allow symlinks to be followed in the local directory that point outside of the base directory path. For the unsafe case the `path_check()` method of `PyboardCommand` still checks for a common path but without expanding symlinks. While this check is currently redundant, it makes the purpose of the method clearer for possible future uses or extensions.
2022-04-04docs/reference/mpremote: Add details about mount usage over soft reboot.Andrew Leech
2022-02-25tools/mpremote: Add "umount" command.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2022-02-25tools/mpremote: Add "resume" and "soft-reset" commands.Damien George
This makes the auto soft-reset behaviour of mpremote more logical, and now configurable via these new commands. Signed-off-by: Damien George <damien@micropython.org>
2022-02-04docs/reference/isr_rules.rst: Describe uasyncio-IRQ interface.Peter Hinch
2022-02-04docs/reference/isr_rules.rst: Fix inconsistent variable name in example.Luiz Brandao
Fixed to be conistent with the code example above it.
2021-12-15docs: Remove trailing spaces and convert tabs to spaces.Damien George
Signed-off-by: Damien George <damien@micropython.org>
2021-11-19docs/reference/filesystem.rst: Add detail on how to use littlefs fuse.Damien George
Without the --block_count option the fuse will fail. Signed-off-by: Damien George <damien@micropython.org>
2021-10-14docs/reference/manifest.rst: Add docs for manifest.py files.NitiKaur
2021-10-14docs/reference/mpremote.rst: Add docs for mpremote.NitiKaur
2021-09-16all: Remove MICROPY_OPT_CACHE_MAP_LOOKUP_IN_BYTECODE.Jim Mussared
This commit removes all parts of code associated with the existing MICROPY_OPT_CACHE_MAP_LOOKUP_IN_BYTECODE optimisation option, including the -mcache-lookup-bc option to mpy-cross. This feature originally provided a significant performance boost for Unix, but wasn't able to be enabled for MCU targets (due to frozen bytecode), and added significant extra complexity to generating and distributing .mpy files. The equivalent performance gain is now provided by the combination of MICROPY_OPT_LOAD_ATTR_FAST_PATH and MICROPY_OPT_MAP_LOOKUP_CACHE (which has been enabled on the unix port in the previous commit). It's hard to provide precise performance numbers, but tests have been run on a wide variety of architectures (x86-64, ARM Cortex, Aarch64, RISC-V, xtensa) and they all generally agree on the qualitative improvements seen by the combination of MICROPY_OPT_LOAD_ATTR_FAST_PATH and MICROPY_OPT_MAP_LOOKUP_CACHE. For example, on a "quiet" Linux x64 environment (i3-5010U @ 2.10GHz) the change from CACHE_MAP_LOOKUP_IN_BYTECODE, to LOAD_ATTR_FAST_PATH combined with MAP_LOOKUP_CACHE is: diff of scores (higher is better) N=2000 M=2000 bccache -> attrmapcache diff diff% (error%) bm_chaos.py 13742.56 -> 13905.67 : +163.11 = +1.187% (+/-3.75%) bm_fannkuch.py 60.13 -> 61.34 : +1.21 = +2.012% (+/-2.11%) bm_fft.py 113083.20 -> 114793.68 : +1710.48 = +1.513% (+/-1.57%) bm_float.py 256552.80 -> 243908.29 : -12644.51 = -4.929% (+/-1.90%) bm_hexiom.py 521.93 -> 625.41 : +103.48 = +19.826% (+/-0.40%) bm_nqueens.py 197544.25 -> 217713.12 : +20168.87 = +10.210% (+/-3.01%) bm_pidigits.py 8072.98 -> 8198.75 : +125.77 = +1.558% (+/-3.22%) misc_aes.py 17283.45 -> 16480.52 : -802.93 = -4.646% (+/-0.82%) misc_mandel.py 99083.99 -> 128939.84 : +29855.85 = +30.132% (+/-5.88%) misc_pystone.py 83860.10 -> 82592.56 : -1267.54 = -1.511% (+/-2.27%) misc_raytrace.py 21490.40 -> 22227.23 : +736.83 = +3.429% (+/-1.88%) This shows that the new optimisations are at least as good as the existing inline-bytecode-caching, and are sometimes much better (because the new ones apply caching to a wider variety of map lookups). The new optimisations can also benefit code generated by the native emitter, because they apply to the runtime rather than the generated code. The improvement for the native emitter when LOAD_ATTR_FAST_PATH and MAP_LOOKUP_CACHE are enabled is (same Linux environment as above): diff of scores (higher is better) N=2000 M=2000 native -> nat-attrmapcache diff diff% (error%) bm_chaos.py 14130.62 -> 15464.68 : +1334.06 = +9.441% (+/-7.11%) bm_fannkuch.py 74.96 -> 76.16 : +1.20 = +1.601% (+/-1.80%) bm_fft.py 166682.99 -> 168221.86 : +1538.87 = +0.923% (+/-4.20%) bm_float.py 233415.23 -> 265524.90 : +32109.67 = +13.756% (+/-2.57%) bm_hexiom.py 628.59 -> 734.17 : +105.58 = +16.796% (+/-1.39%) bm_nqueens.py 225418.44 -> 232926.45 : +7508.01 = +3.331% (+/-3.10%) bm_pidigits.py 6322.00 -> 6379.52 : +57.52 = +0.910% (+/-5.62%) misc_aes.py 20670.10 -> 27223.18 : +6553.08 = +31.703% (+/-1.56%) misc_mandel.py 138221.11 -> 152014.01 : +13792.90 = +9.979% (+/-2.46%) misc_pystone.py 85032.14 -> 105681.44 : +20649.30 = +24.284% (+/-2.25%) misc_raytrace.py 19800.01 -> 23350.73 : +3550.72 = +17.933% (+/-2.79%) In summary, compared to MICROPY_OPT_CACHE_MAP_LOOKUP_IN_BYTECODE, the new MICROPY_OPT_LOAD_ATTR_FAST_PATH and MICROPY_OPT_MAP_LOOKUP_CACHE options: - are simpler; - take less code size; - are faster (generally); - work with code generated by the native emitter; - can be used on embedded targets with a small and constant RAM overhead; - allow the same .mpy bytecode to run on all targets. See #7680 for further discussion. And see also #7653 for a discussion about simplifying mpy-cross options. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-30docs/reference: Mention that slicing a memoryview causes allocation.Peter Hinch