README
(v 1.0 November 2025)
1 Overview
1.1 User functionality
z-iot-clock is a Zephyr application that shows current time and date. It runs on the RPi Pico2 W board with Pimoroni Pico Display 2.8. z-iot-clock reconnects to a WiFi access point and syncs wallclock time with a reference time at an SNTP server.
The application uses the colour of the "Time & Date" text to indicate the node status. There are three colours assigned to the states:
Peach — normal operation
Light Blue — the recent SNTP sync failed
Raspberry — the node was disconnected from a network
There is an option to hide the clockface when necessary. Button Y (bottom right) on the display switches between the logical screen with the clockface and preloaded pictures. Button B (bottom left) toggles the RGB LED through 8 colours.
Button X (top right) resets the device.
1.2 Admin features
The application enables a shell interface for the console. In the default application configuration, the following shells are available: WiFi shell, net shell, kernel shell, device shell, devmem shell, LVGL shell.
The project configures Zephyr to enable the UART console over USB Serial.
The application receives the node IP address and DNS servers' IPs using DHCPv4 available in the WiFi network.
2 Configurations
There are two configurations of the application:
default — uses the Pico Display to show time and date
non-display — does not initialize the display and outputs time and date to the console
3 Building the project
3.1 Patching
Before building the project, you must apply some patches to the Zephyr code (see directory patches). Two patches add Pimoroni Pico Display 2.8 support; Add-SNTP-sync-status-flag.patch makes a commit that's meaningful only for this project. You can use the script apply_patches.sh to apply all of them; the script requires a path to the Zephyr tree as a parameter.
Support of Pimoroni Pico Display 2.8 in Zephyr was developed by Dmitriy Korovkin. His work is based on the code for Waveshare 1.14 inch LCD Display Module for Raspberry Pi Pico created by TOKITA Hiroshi.
As of Nov 18, 2025, the patch 0004-shields-displays-pimoroni-Added-Pimoroni-Pico-Displa.patch has not been added to Zephyr.
3.2 Configuring
Customer-specific Zephyr configuration options are placed in the config file prj-private.conf. All the config parameters listed there are mandatory and don't have default values.
They include:
The application uses static WiFi credentials that should be available at compilation time. See "Running the Application" for information on using WiFi credentials at runtime.
Static WiFi credentials are embedded at build time. If you need to connect to another network at runtime, see the runtime reconnect instructions below.
3.3 Building and flashing
The project provides the build script build-zi-clock.sh. File Non-display-config.md contains a list of changes required to select the non-display configuration.
Flashing options are available in the documentation for the Pico Family by Raspberry Pi Ltd and on the Zephyr page for RPi Pico2 W.
4 Running the Application
If your board is plugged into a host computer with a micro-USB cable, you will see the following in the console: timestamps every clock tick, results of periodic SNTP syncs, and reconnection attempts to a WiFi network.
You can run the wifi disconnect shell command to trigger reconnection behavior.
For automatic reconnection, the application uses the static credentials. When you have access to the console, you can manually connect the node to another network. To allow more time for manual reconnection, set the network reconnection time CONFIG_WIFI_CONN_TIMEOUT_SEC to a longer period (default is 10s).
Notes:
In the current version, if the connection attempt fails, the auto-connection routine will fall back to the static credentials.
Auto-connection cannot be switched off in the current version.
Timestamp messages in the console interlace with shell command output and cannot be switched off.
Last updated