Environment variables are set in a settings.toml file. They can provide a CircuitPython program information, such as WiFi SSID and password, access to Adafruit IO, and much more.
Documentation on this file are on Read the Docs.
There are some environment variables which work or are specific to DVI displays, such as the ones below.
The variables are read on a power-up or restart. They are not reread on a reload (control-D) from the REPL.
Here is a typical example of a settings.toml file that is placed in the CIRCUITPY root directory of the board you are using. The WiFi and Adafruit IO credentials are not needed if you are not using those services. This script sets the screen to 640x480 resolution at an 8 bit color depth and uses a specific font in the CircuitPython Terminal.
CIRCUITPY_WIFI_SSID = "your-wifi-ssid-here" CIRCUITPY_WIFI_PASSWORD = "your-wifi-password-here" aio_username = "your-Adafruit-IO-username-here" aio_key = "your-Adafruit-IO-key-here" CIRCUITPY_DISPLAY_WIDTH = 640 CIRCUITPY_DISPLAY_HEIGHT = 480 CIRCUITPY_DISPLAY_COLOR_DEPTH = 8 CIRCUITPY_TERMINAL_FONT = "/fonts/CP437_12h.bin"
CIRCUITPY_DISPLAY_ROTATION
Selects the correct screen rotation (0, 90, 180 or 270) for the particular board variant. If the CIRCUITPY_DISPLAY_ROTATION parameter is set the display will be initialized during power up with the selected rotation, otherwise the display will be initialized with a rotation of 0. Attempting to initialize the screen with a rotation other than 0, 90, 180 or 270 is not supported and will result in an unexpected screen rotation.
CIRCUITPY_PICODVI_ENABLE
Whether to configure the display at board initialization time, one of the following:
="detect" # when EDID EEPROM is detected (default) ="always" ="never"
A display configured in this manner is available at supervisor.runtime.display until it is released by displayio.release_displays(). It does not appear at board.DISPLAY.
CIRCUITPY_DISPLAY_WIDTH, CIRCUITPY_DISPLAY_HEIGHT, and CIRCUITPY_DISPLAY_COLOR_DEPTH (RP2350 boards with DVI or HSTX connector)
Selects the desired resolution and color depth.
Supported resolutions are:
-
640x480 with color depth 1, 2, 4 or 8 bits per pixel
-
320x240 with pixel doubling and color depth 8, 16, or 32 bits per pixel
-
360x200 with pixel doubling and color depth 8, 16, or 32 bits per pixel
See picodvi.Framebuffer for more details.
The default value, if unspecified, is 360x200 16 bits per pixel if the connected display is 1920x1080 or a multiple of it, otherwise 320x240 with 16 bits per pixel.
If height is unspecified, it is set from the width. For example, a width of 640 implies a height of 480.
Example: Configure the display to 640x480 black and white (1 bit per pixel), add these lines to your settings.toml file.
CIRCUITPY_DISPLAY_WIDTH=640 CIRCUITPY_DISPLAY_COLOR_DEPTH=1
New to CircuitPython 10 and later is the ability to change the font of the CircuitPython Terminal. Per the documentation on Read the Docs:
CIRCUITPY_TERMINAL_FONT
Specifies a custom font file path to use for the terminalio console instead of the default /fonts/terminal.lvfontbin. This allows users to create and use custom fonts for the CircuitPython console.
This feature requires both CIRCUITPY_OS_GETENV and CIRCUITPY_LVFONTIO to be enabled.
Example:
CIRCUITPY_TERMINAL_FONT="/fonts/myfont.lvfontbin"
Page last edited August 29, 2025
Text editor powered by tinymce.
