supervisor – Supervisor settings
Available on these boards
- supervisor.runtime: Runtime
Runtime information, such as
runtime.serial_connected(USB serial connection status). This object is the sole instance ofsupervisor.Runtime.
- supervisor.status_bar: StatusBar
The status bar, shown on an attached display, and also sent to an attached terminal via OSC escape codes over the REPL serial connection. The status bar reports the current IP or BLE connection, what file is running, the last exception name and location, and firmware version information. This object is the sole instance of
supervisor.StatusBar.
- supervisor.reload() None
Reload the main Python code and run it (equivalent to hitting Ctrl-D at the REPL).
- supervisor.set_next_code_file(filename: str | None, *, reload_on_success: bool = False, reload_on_error: bool = False, sticky_on_success: bool = False, sticky_on_error: bool = False, sticky_on_reload: bool = False) None
Set what file to run on the next vm run.
When not
None, the givenfilenameis inserted at the front of the usual [‘code.py’, ‘main.py’] search sequence.The optional keyword arguments specify what happens after the specified file has run:
sticky_on_…determine whether the newly set filename and options stay in effect: If True, further runs will continue to run that file (unless it says otherwise by callingset_next_code_filename()itself). If False, the settings will only affect one run and revert to the standard code.py/main.py afterwards.reload_on_…determine how to continue: If False, wait in the usual “Code done running. Waiting for reload. / Press any key to enter the REPL. Use CTRL-D to reload.” state. If True, reload immediately as if CTRL-D was pressed.…_on_successtake effect when the program runs to completion or callssys.exit().…_on_errortake effect when the program exits with an exception, including the KeyboardInterrupt caused by CTRL-C.…_on_reloadtake effect when the program is interrupted by files being written to the USB drive (auto-reload) or when it callssupervisor.reload().These settings are stored in RAM, not in persistent memory, and will therefore only affect soft reloads. Powering off or resetting the device will always revert to standard settings.
When called multiple times in the same run, only the last call takes effect, replacing any settings made by previous ones. This is the main use of passing
Noneas a filename: to reset to the standard search sequence.
- supervisor.ticks_ms() int
Return the time in milliseconds since an unspecified reference point, wrapping after 2**29ms.
The value is initialized so that the first overflow occurs about 65 seconds after power-on, making it feasible to check that your program works properly around an overflow.
The wrap value was chosen so that it is always possible to add or subtract two
ticks_msvalues without overflow on a board without long ints (or without allocating any long integer objects, on boards with long ints).This ticks value comes from a low-accuracy clock internal to the microcontroller, just like
time.monotonic. Due to its low accuracy and the fact that it “wraps around” every few days, it is intended for working with short term events like advancing an LED animation, not for long term events like counting down the time until a holiday.Addition, subtraction, and comparison of ticks values can be done with routines like the following:
_TICKS_PERIOD = const(1<<29) _TICKS_MAX = const(_TICKS_PERIOD-1) _TICKS_HALFPERIOD = const(_TICKS_PERIOD//2) def ticks_add(ticks, delta): "Add a delta to a base number of ticks, performing wraparound at 2**29ms." return (ticks + delta) % _TICKS_PERIOD def ticks_diff(ticks1, ticks2): "Compute the signed difference between two ticks values, assuming that they are within 2**28 ticks" diff = (ticks1 - ticks2) & _TICKS_MAX diff = ((diff + _TICKS_HALFPERIOD) & _TICKS_MAX) - _TICKS_HALFPERIOD return diff def ticks_less(ticks1, ticks2): "Return true iff ticks1 is less than ticks2, assuming that they are within 2**28 ticks" return ticks_diff(ticks1, ticks2) < 0
- supervisor.get_previous_traceback() str | None
If the last vm run ended with an exception (including the KeyboardInterrupt caused by CTRL-C), returns the traceback as a string. Otherwise, returns
None.An exception traceback is only preserved over a soft reload, a hard reset clears it.
Only code (main or boot) runs are considered, not REPL runs.
- supervisor.reset_terminal(x_pixels: int, y_pixels: int) None
Reset the CircuitPython serial terminal with new dimensions.
- supervisor.set_usb_identification(manufacturer: str | None = None, product: str | None = None, vid: int = -1, pid: int = -1) None
Override identification constants in the USB Device Descriptor.
If passed,
manufacturerandproductmust be ASCII strings (or buffers) of at most 126 characters. Any omitted arguments will be left at their default values.This method must be called in boot.py to have any effect.
Not available on boards without native USB support.
- class supervisor.RunReason
The reason that CircuitPython started running.
- STARTUP: object
CircuitPython started the microcontroller started up. See
microcontroller.Processor.reset_reasonfor more detail on why the microcontroller was started.
- SUPERVISOR_RELOAD: object
CircuitPython restarted due to a call to
supervisor.reload().
- class supervisor.Runtime
Current status of runtime objects.
Usage:
import supervisor if supervisor.runtime.serial_connected: print("Hello World!")
You cannot create an instance of
supervisor.Runtime. Usesupervisor.runtimeto access the sole instance available.- serial_bytes_available: int
Returns the number of bytes are available to read on the console serial input. Multiple console serial inputs may be in use at once, including USB, web workflow, BLE workflow, and/or UART.
Allows for polling to see whether to call the built-in input() or wait. (read-only)
Limitations: On STM, UART (not USB) console input can only determine that at least one character is available, and so if only the UART console is in use, only
1or0will be returned.Changed in version 9.1.0: Previously returned only
TrueorFalse. Since0acts asFalse,if supervisor.runtime.serial_byes_available:will still work.
- safe_mode_reason: SafeModeReason
Why CircuitPython went into safe mode this particular time (read-only).
Limitations: Raises
NotImplementedErroron builds that do not implementsafemode.py.
- class supervisor.SafeModeReason
The reason that CircuitPython went into safe mode.
Limitations: Class not available on builds that do not implement
safemode.py.- GC_ALLOC_OUTSIDE_VM: object
CircuitPython tried to allocate storage when its virtual machine was not running.
- NLR_JUMP_FAIL: object
An error occurred during exception handling, possibly due to memory corruption.
- PROGRAMMATIC: object
The program entered safe mode using the
supervisormodule.
- USB_BOOT_DEVICE_NOT_INTERFACE_ZERO: object
The USB HID boot device was not set up to be the first device, on interface #0.
- class supervisor.StatusBar
Current status of runtime objects.
Usage:
import supervisor supervisor.status_bar.console = False
You cannot create an instance of
supervisor.StatusBar. Usesupervisor.status_barto access the sole instance available.- console: bool
Whether status bar information is sent over the console (REPL) serial connection, using OSC terminal escape codes that change the terminal’s title. Default is
True. If set toFalse, status bar will be cleared and then disabled. May be set inboot.pyor later. Persists across soft restarts.
- display: bool
Whether status bar information is displayed on the top line of the display. Default is
True. If set toFalse, status bar will be cleared and then disabled. May be set inboot.pyor later. Persists across soft restarts. Not available ifterminaliois not available.