01 / Installation
Pi 5 + Raspberry Pi OS
The reference configuration is Raspberry Pi 5, Raspberry Pi OS / Debian 13, kernel 6.18.34+rpt-rpi-2712, and native I²C at 100 kHz. The RNG90 module is project software and needs installation; a stock kernel should not be assumed to include it. Other kernels and Pi models need verification.
Mount with power disconnected
Align pin 1 on the 40-pin header and fit spacers that match the connector and cooler clearance. Disconnect all external power before installing or removing the HAT. The HAT uses the Pi’s 3.3 V supply. The CR1220 backs the RTC only; the RNG90 needs host power. Follow the holder’s polarity marking and keep coin cells away from children.
Install the source and overlay
Download the Linux source kit · SHA-256 checksum. It includes source, license notices, a file manifest and these instructions for offline use. The reference configuration above is tested; other kernels need verification. A clean-image installation qualification remains open.
Extract the kit and run the following from its factory-random90 directory. First install matching kernel headers, build-essential, dkms, device-tree-compiler and util-linux-extra through the OS package manager. Header package names vary by kernel.
test -d /lib/modules/$(uname -r)/build
dkms status
sudo install -d /usr/src/rng90-0.1
sudo install -m 0644 linux/rng90.c linux/Makefile linux/dkms.conf /usr/src/rng90-0.1/
sudo dkms add -m rng90 -v 0.1
sudo dkms build -m rng90 -v 0.1
sudo dkms install -m rng90 -v 0.1
dtc -@ -I dts -O dtb -o /tmp/tudor-r90-hat.dtbo hat/tudor-r90-hat-overlay.dts
sudo install -m 0644 /tmp/tudor-r90-hat.dtbo /boot/firmware/overlays/
sudo install -m 0755 hat/r90-hat-select-rng /usr/local/sbin/
sudo install -m 0644 hat/90-r90-hat.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
If rng90/0.1 already appears in DKMS, review that installation before replacing files or repeating dkms add. Keep the source release and build log. The programmed HAT EEPROM names the overlay; firmware loads the installed file at boot. Do not add a second RTC overlay for the same device.
Reboot cleanly after installation, then perform the checks below. RTC boot-clock selection on Pi 5 is a separate choice described under Keep time.
02 / Verify
Identify the selected source
sudo vclog --msg | grep tudor-r90-hat
dkms status
cat /sys/class/misc/hw_random/rng_available
cat /sys/class/misc/hw_random/rng_current
cat /sys/class/misc/hw_random/rng_quality
ls -l /dev/rtc-r90
sudo hwclock --show --rtc /dev/rtc-r90 --utc
The reference Pi reports rng90-1-0040 and quality 1. Bus numbers may differ. Confirm that rng_current names the RNG90 before treating /dev/hwrng output as board data. The installed helper selects only a device-tree RNG90 on an identified R90-HAT.
Read directly from the RNG90
cat /sys/class/misc/hw_random/rng_current
sudo timeout 5 dd if=/dev/hwrng bs=32 count=1 iflag=fullblock status=none | od -An -tx1
cat /sys/class/misc/hw_random/rng_current
A successful read yields 32 bytes. This is a quick interface check; use the supplied hwrng_soak.py for bounded reads, source checks and a retained sample. Do not run forced raw I²C probes while the kernel driver owns the chip.
Applications should normally use the OS random API, such as Linux getrandom(). The device interface is useful for validation and integration. Quality 1 is a conservative credit policy, nominally one bit per 1024 returned bits; it is not a measured entropy density. Passing stream tests does not justify raising it.
03 / Keep time
Set UTC. Retain it on the cell.
After confirming the system clock is correct, write it to the HAT RTC. Checking synchronization first avoids storing an incorrect system time.
timedatectl show -p NTPSynchronized
# Continue only after verifying system UTC is correct.
sudo hwclock --systohc --rtc /dev/rtc-r90 --utc
sudo hwclock --show --rtc /dev/rtc-r90 --utc
Use the HAT as the Pi 5 boot clock
Pi 5 has its own RTC. If that clock has no backup battery and the HAT should supply boot time, first set valid UTC in the HAT. Back up /boot/firmware/config.txt, then add the supplied hat/pi5-rtc-config.txt content once:
[pi5]
dtparam=rtc=off
[all]
This disables the onboard RTC, including its wake facility. Choose it only when that matches the installation. After reboot, verify that /sys/class/rtc/rtc0/name identifies the HAT’s rtc-ds1307 instance at 0x68, hctosys is 1, and the boot log records setting system time from it. The /dev/rtc-r90 symlink avoids relying on an RTC number for later reads.
Test the backup cell
Record RTC time and independent wall time, shut down cleanly, remove all external power and possible USB back-power, and leave the cell fitted. Restore power after at least five minutes. Read the RTC before writing it, compare elapsed time and inspect any oscillator-stop warning. A warm reboot does not test battery retention. Preserve existing NTP configuration.
04 / Troubleshoot
Follow the missing interface
No HAT overlay
Check the firmware log, overlay filename and powered-off header alignment. The EEPROM stores the overlay name, not the overlay binary. Leave its write-protect link absent; EEPROM rewriting is not a routine installation step.
No RNG90 in rng_available
Check dkms status, modinfo rng90 and the kernel journal. A kernel update may require matching headers and a successful DKMS rebuild. Verify the device-tree node and 100 kHz bus configuration. Do not force an I²C address into a busy driver as a workaround.
Another RNG is selected
Check that the udev rule and helper were installed and the EEPROM identifies R90-HAT. Save rng_available, rng_current and the driver log. Reading /dev/hwrng alone does not identify its physical source.
Wrong time after power removal
Read /dev/rtc-r90 directly. Check cell type, polarity, contact and voltage with power safely disconnected. An oscillator-stop flag is evidence to investigate. If the HAT keeps time but early boot time is wrong, check which RTC is rtc0 and used by hctosys.
I²C errors or a stalled read
Retain the exact error and kernel messages. Check seating, bus conflicts and the installed source version. Repeated device health failures latch the driver and need investigation before recovery. Do not mask failures by repeatedly resetting the board or clearing status flags.
05 / Test evidence
What has been measured
On one assembled HAT, Pi 5 commissioning verified the programmed EEPROM and its identity, RTC calendar boundaries and alarm interrupt, direct RNG90 identity and self-tests, CRC-checked responses, Linux binding, module reload, concurrent reads and deliberate sleep-state recovery.
A clean one-hour Linux run delivered 120,888 blocks, or 3,868,416 bytes, at approximately 1.07 kB/s. Driver tracing recorded no Random errors, startup failures or device-error statuses, and no trace loss. The RTC retained time across an owner-reported four-minute removal of external power and subsequently supplied boot time before network synchronization.
These are engineering results on the stated configuration, not a guarantee for every board or host. RTC supply hold-up, backup current, temperature-dependent drift and broader environmental behavior still need bench measurements.
Statistics and physical entropy
The RNG90 contains a physical noise source feeding a SHA-256 Hash_DRBG. Host reads expose the DRBG output, not unconditioned noise measurements. Statistical batteries look for detectable patterns in those delivered bytes. A deterministic generator with a known seed can also pass such tests, despite being entirely predictable to someone who knows the seed.
A second one-hour capture on 2026-11-05 delivered 3,873,056 bytes with no driver errors, repeated 32-byte blocks or trace loss. ENT analyzed the whole file; PractRand 0.96 reported no flags on its first 2 MiB. NIST STS 2.1.2 tested 30 consecutive million-bit sequences: all passing-proportion checks met its criterion, while three uniformity flags used only 17 eligible excursion sequences, below the required sample size for interpreting those scores. The earlier capture had one PractRand warning and two STS proportion flags; those cases did not reproduce in the second capture and remain in the engineering record.
Equal-length controls were tested too. Public-seed SHAKE256 looked statistically ordinary despite being reproducible; repeated 0x55 was rejected despite having exactly balanced bits. This is limited-sample output testing, not a blanket NIST pass or entropy certification.
That is what “tests do not establish physical entropy density” means: a good-looking stream does not reveal how much unpredictable information entered the chip from its noise source. It does not mean the physical source is absent. See NIST SP 800-22 for stream tests and SP 800-90B for entropy-source assessment.
06 / Get help
Send the useful details
Include the board revision, Pi model, OS and uname -r, installation source version, dkms status, selected RNG, RTC name and the relevant kernel error. Mention whether the problem follows a kernel update, cold boot or physical installation change. Share board serials privately when needed; never send SSH keys, credentials or random data used as secrets.
ptudor@ptudor.net ↗
