CircuitPython works with WiFi-capable boards to enable you to make projects that have network connectivity. This means working with various passwords and API keys. As of CircuitPython 8, there is support for a settings.toml file. This is a file that is stored on your CIRCUITPY drive that contains all of your secret network information, such as your WiFi SSID and SSID password. It is designed to separate your sensitive information from your code.py file so you are able to share your code without sharing your credentials.

WiFi Credentials

The most minimal settings.toml file must contain your WiFi SSID and password, as that is the minimum required to connect to WiFi and sync the clock via NTP. Copy this example, paste it into your settings.toml, and update the values with your network credentials.

• CIRCUITPY_WIFI_SSID — Your WiFi network name
• CIRCUITPY_WIFI_PASSWORD — Your WiFi password

If these values are missing or blank, the clock will skip WiFi and enter the manual time-set mode on boot

Timezone and Daylight Saving Time

The clock uses your standard UTC offset along with automatic US Daylight Saving Time computation to keep the time accurate year-round. Add these lines to your settings.toml file.

• TZ_STD_OFFSET — Your standard UTC offset without daylight savings time (DST) applied. Common US values: -5 for Eastern, -6 for Central, -7 for Mountain, -8 for Pacific. Use 0 for GMT or +1 for CET.
• DST_AUTO — Set to "true" to automatically add +1 hour during US DST (second Sunday in March through first Sunday in November in much of the US). Set to "false" for non-US timezones or locations that do not observe DST.

Display Rotation

The display can be rotated to accommodate different mounting orientations. This sets the default rotation on boot.

• DISPLAY_ROTATION — The rotation angle in degrees. Accepted values are 0, 90, 180, and 270.

The rotation determines which direction the USB cable points when the clock is mounted.

• 0 — USB cable points left
• 90 — USB cable points down (recommended for wall mounting)
• 180 — USB cable points right
• 270 — USB cable points up

You can also cycle through rotations at run time with a long press on the UP button.

Complete settings.toml File

Here is the complete settings.toml file with all available options. Copy this into the root of your CIRCUITPY drive and update the values for your setup.

settings.toml Tips

All values in the settings.toml file must be enclosed in double quotes. This includes numeric values like TZ_STD_OFFSET and DISPLAY_ROTATION. The code converts them to the appropriate type internally.

If you run into connectivity issues, verify that the values in your settings.toml file match the variable names expected in code.py. The required names are: CIRCUITPY_WIFI_SSID, CIRCUITPY_WIFI_PASSWORD, TZ_STD_OFFSET, DST_AUTO, and DISPLAY_ROTATION.

You can leave out the WiFi credentials entirely to use the clock in offline mode with the manual time-set feature. The timezone and rotation settings still apply in offline mode if present.