micropython – MicroPython internals

Access and control MicroPython internals.

const(value: int) int

Declares the value as a constant. This value will be substituted wherever it is used, which makes your code more efficient.

To reduce memory usage further, prefix its name with an underscore (_ORANGES). This constant can only be used within the same file.

If you want to import the value from another module, use a name without an underscore (APPLES). This uses a bit more memory.

opt_level() int
opt_level(level: int) None

Sets the optimization level for code compiled on the hub:

  1. Assertion statements are enabled. The built-in __debug__ variable is True. Script line numbers are saved, so they can be reported when an Exception occurs.

  2. Assertions are ignored and __debug__ is False. Script line numbers are saved.

  3. Assertions are ignored and __debug__ is False. Script line numbers are saved.

  4. Assertions are ignored and __debug__ is False. Script line numbers are not saved.

This applies only to code that you run in the REPL, because regular scripts are already compiled before they are sent to the hub.

If no argument is given, this function returns the current optimization level.

mem_info() None
mem_info(verbose: Any) None

Prints information about stack and heap memory usage.

If the verbose argument is given, it also prints out the entire heap, indicating which blocks are used and which are free.

qstr_info() None
qstr_info(verbose: Any) None

Prints how many strings are interned and how much RAM they use.

MicroPython uses string interning to save both RAM and ROM. This avoids having to store duplicate copies of the same string.

If the verbose argument is given it also prints out the names of all RAM-interned strings.

stack_use() int

Returns the amount of stack that is being used. This can be used to compute differences in stack usage at different points in a script.

kbd_intr(chr: int) None

Set the character that will raise a KeyboardInterrupt exception. By default this is set to 3 during script execution, corresponding to Ctrl-C. Passing -1 to this function will disable capture of Ctrl-C, and passing 3 will restore it.

This function can be used to prevent the capturing of Ctrl-C on the incoming stream of characters that is usually used for the REPL, in case that stream is used for other purposes.

Examples

Using constants for efficiency

from micropython import const

# This value can be used here. Other files can import it too.
APPLES = const(123)

# These values can only be used within this file.
_ORANGES = const(1 << 8)
_BANANAS = const(789 + _ORANGES)

# You can read the constants as normal values. The compiler
# will just insert the numeric values for you.
fruit = APPLES + _ORANGES + _BANANAS
print(fruit)

Checking free RAM

from micropython import mem_info

# Print memory usage.
mem_info()

This prints information in the format shown below. In this example for the SPIKE Prime Hub, there are 257696 bytes (251 KB) worth of memory remaining for the variables in your code.

stack: 372 out of 40184
GC: total: 258048, used: 352, free: 257696
No. of 1-blocks: 4, 2-blocks: 2, max blk sz: 8, max free sz: 16103

Getting more memory statistics

from micropython import const, opt_level, mem_info, qstr_info, stack_use

# Get stack at start.
stack_start = stack_use()

# Print REPL compiler optimization level.
print("level", opt_level())

# Print memory usage.
mem_info()

# Print memory usage and a memory map.
mem_info(True)

# Print interned string information.
qstr_info()

# Print interned string information and their names.
APPLES = const(123)
_ORANGES = const(456)
qstr_info(True)


def test_stack():
    return stack_use()


# Check the stack.
print("Stack diff: ", test_stack() - stack_start)