settings.toml on the CIRCUITPY drive holds your WiFi network and Adafruit IO credentials and other info. This file can be created or edited with any simple text editor you prefer. It resides in the root directory of the CIRCUITPY drive, not inside a folder.

If you already have this file on your Matrix Portal from prior projects…great!

If not, it should resemble what’s below. Some items are strings (in single quotes), others are numbers (no quotes).

The format of this file is super persnickety, every space and comma counts! If creating it for the first time, best to copy-and-paste the text below exactly, then change any items of interest (preserving quotation marks and such).

CIRCUITPY_WIFI_SSID and CIRCUITPY_WIFI_PASSWORD are your WiFi network name and password.

ADAFRUIT_AIO_USERNAME and ADAFRUIT_AIO_KEY can be found by logging into your Adafruit IO account and clicking the yellow key icon near the top-right. If you don’t yet have an account, set one up, the basic service is free! This is used by the software to set the clock.

timezone is needed to distinguish your local time from UTC (aka Greenwich time). Here’s a list of valid time zone strings; find a city in your zone and copy/paste it here (in quotes).

latitude and longitude are optional but recommended. The clock can do IP geolocation (estimating your location using IP address), but having it here is more accurate. These values are floating-point numbers (in degrees and decimal fractions thereof) and should not be in quotes. For latitude, positive values are north, negative is south. For longitude, negative is west, positive is east.

You can easily get your decimal latitude and longitude from Google Maps. Zoom in on a location and right-click on the map. Information there includes latitude and longitude in exactly the format we need…click the coordinates to copy them to the clipboard, then paste into the settings.toml file and reformat the text as shown above.

The code will relaunch any time there’s a change on the CIRCUITPY drive…so, after editing settings.toml, the clock should start up on its own and you’ll see a splash screen after a few seconds.

If the clock does NOT start up, or shows the splash screen but then crashes: most likely the WiFi credentials are incorrect, or something is wrong with the settings.toml file syntax…make sure every quote, and equals sign is there and in the right place.