UUGear Witty Pi 4 User manual

Copyright © 2023 Dun Cat B.V., All rights reserved.
UUGear is a trade name of Dun Cat B.V.
Witty Pi 4:
Realtime Clock and Power Management for Raspberry Pi
User Manual (revision 1.02)

Copyright © 2023 Dun Cat B.V., All rights reserved.
UUGear is a trade name of Dun Cat B.V.
Table of Contents
1. Product Overview..............................................................................................................1
1.1 Accurate Realtime Clock and ON/OFF Scheduling................................................1
1.2 Temperature Controlled Device..............................................................................2
1.3 DC/DC Converter and e-Latching Power Switch....................................................3
1.4 Interface Introduction.............................................................................................4
2. Specification / Technical Details.........................................................................................5
3. Package Content...............................................................................................................5
4. How Does Witty Pi Work?..................................................................................................6
5. Software Installation, Updating and Uninstallation.............................................................7
5.1 Install Software......................................................................................................7
5.2 Update Software....................................................................................................7
5.3 Uninstall Software..................................................................................................7
6. Mounting Witty Pi 4 on Raspberry Pi.................................................................................8
7. Software Usage...............................................................................................................11
7.1 Write system time to RTC....................................................................................11
7.2 Write RTC time to system ....................................................................................12
7.3 Synchronize time.................................................................................................12
7.4 Schedule next shutdown......................................................................................12
7.5 Schedule next startup..........................................................................................12
7.6 Choose Schedule Script ......................................................................................12
7.7 Set low voltage threshold.....................................................................................13
7.8 Set recovery voltage threshold.............................................................................13
7.9 Set over temperature action.................................................................................14
7.10 Set below temperature action ..............................................................................14

Copyright © 2023 Dun Cat B.V., All rights reserved.
UUGear is a trade name of Dun Cat B.V.
7.11 View/change other settings..................................................................................14
7.12 Reset Data… .......................................................................................................15
7.13 Exit ......................................................................................................................16
8. Using UWI (UUGear Web Interface)................................................................................17
9. About Schedule Script.....................................................................................................18
9.1 How does Schedule Script Work?........................................................................18
9.2 Make Your Own Schedule Script..........................................................................20
9.3 Using Schedule Script Generator.........................................................................22
9.4 Advanced Usage of Schedule Script....................................................................23
10. Know More about the Realtime Clock..........................................................................24
10.1 CR2032 Battery and Time Keeping......................................................................24
10.2 Alarms and Alarm Output.....................................................................................24
10.3 Temperature Compensation.................................................................................24
11. Additional Interfaces....................................................................................................26
11.1 The Unpopulated 3-Pin Header (P2)....................................................................26
11.2 The Unpopulated 7-Pin Header on the Top (P3) ..................................................26
11.3 The Unpopulated 2 x 3 Pin Headers (P4).............................................................28
11.4 The Unpopulated 7-Pin Header on the Left (P5)..................................................29
11.5 The Unpopulated 2-Pin Header (P6)....................................................................30
12. Integrate with Other Programs.....................................................................................31
13. Migrating from Witty Pi 3 to Witty Pi 4..........................................................................33
14. Witty Pi Log Files.........................................................................................................35
15. Frequently Asked Questions (FAQ) .............................................................................36
15.1 What I2C address is used by Witty Pi 4? Can I change it?...................................36
15.2 What I2C Registers are provided by Witty Pi 4? ...................................................37
15.3 What GPIO Pins Are Used by Witty Pi4? .............................................................44
15.4 Is Witty Pi 4 Compatible with “Other Hardware”? .................................................45

Copyright © 2023 Dun Cat B.V., All rights reserved.
UUGear is a trade name of Dun Cat B.V.
15.5 Witty Pi 4 does not boot?.....................................................................................45
15.6 Why Raspberry Pi Immediately Turns On after Shutdown?..................................48
16. Revision History...........................................................................................................49

1
1. Product Overview
Witty Pi is an add-on board that adds realtime clock and power management to your Raspberry Pi. It
can define your Raspberry Pi’s ON/OFF sequence, and significantly reduce the energy usage. Witty
Pi 4 is the fourth generation of Witty Pi and it has these hardware resources onboard:
Factory calibrated and temperature compensated realtime clock with ±2ppm accuracy.
Dedicated temperature sensor with 0.125 °C resolution.
On-board DC/DC converter that accepts up to 30V DC.
AVR 8-bit microcontroller (MCU) with 8 KB programmable flash.
1.1 Accurate Realtime Clock and ON/OFF Scheduling
The realtime clock (RTC) on Witty Pi 4 has been calibrated in the factory and Witty Pi 4’s firmware
also makes temperature compensation for the crystal. This makes the RTC very accurate and the
actual annual error is limited within ±2ppm (about 1 minute per year). When your Raspberry Pi boots
up, the time stored in the RTC will overwrite the system time. As a result, your Raspberry Pi knows
the correct time even without accessing the Internet.
You can schedule the startup and/or shutdown of your Raspberry Pi, and make it a time-controlled

2
device. You can even define a schedule script to schedule complicated ON/OFF sequence for your
Raspberry Pi.
Scheduling the ON/OFF sequence for Raspberry Pi is the most popular feature of Witty Pi, and it is
extremely useful for systems that powered by battery. By only turning on Raspberry Pi when
necessary, the battery can work much longer with Witty Pi installed.
1.2 Temperature Controlled Device
The temperature sensor on Witty Pi 4 has 0.125 °C resolution. The temperature data is used for
compensating the crystal and make the RTC more accurate.
You can also specific the action (startup or shutdown) when temperature goes above or below the
preset threshold. Which means you can also make your Raspberry Pi a temperature-controlled
device.

3
1.3 DC/DC Converter and e-Latching Power Switch
Witty Pi 4 comes with a DC/DC converter on board, which allows you to power your device with
6~30V power supply. You can also power your device with 5V via the USB type C connector.
Witty Pi 4 also implements an e-Latching power switch, which is very similar to the power switch on
your PC/Laptop computer. You can gracefully turn on/off your Raspberry Pi with a single tap on the
button. The software running in background will execute the shutdown command before the power
gets cut, and it avoids the data corruption caused by “hard”shutdown.

4
1.4 Interface Introduction
Witty Pi 4 supports all Raspberry Pi models that has the 40-pin GPIO header, including A+, B+, 2B,
Zero, Zero W, Zero 2W, 3B, 3B+, 3A+ and 4B. You will need to solder the 40-pin header to Zero/Zero
W/Zero 2 W model beforehand, so they can make reliable connection with Witty Pi.
The picture below shows the available interfaces of Witty Pi 4.
1. USB type C connector for 5V power input (5V)
2. XH2.54 connector for higher voltage input (VIN)
3. Unpopulated power header with VIN, 5V and GND
4. White LED as status indicator
5. On/off switch
6. 2x20 pin stacking header for connecting to Raspberry Pi
7. ICSP header for uploading firmware
8. 3V (CR2032) battery holder
9. Unpopulated external 3V battery connector
10. Unpopulated 7-pin header for internal I2C bus and extra signals
11. Unpopulated 7-pin header for extension or integration

5
2. Specification / Technical Details
Dimension
65mm x 56mm x 19mm
Weight
23g (net weight without accessories)
Microcontroller
ATtiny841 (datasheet)
Realtime Clock
PCF85063A (datasheet), calibrated in factory.
Temperature Sensor
LM75B (datasheet)
DC/DC Converter
MP4462 (datasheet)
MOSFET Switch
AO4616 (datasheet)
Battery
CR2032 (for time keeping only, when no power supply is connected)
Power In
DC 5V (via USB type C connector) or DC 6V~30V (via XH2.54 connector)
Output Current
Up to 3Afor Raspberry Pi and its peripherals
Standby Current
~0.5mA
Operating
Environment
Temperature -30°C~80°C (-22°F~176°F)
Humidity 0~80%RH, no condensing, no corrosive gas
3. Package Content
Each package of Witty Pi 4 contains:
Witty Pi 4 board x 1
30cm 22AWG XH2.54 cable x 1
M2.5x11 copper standoff x 4
M2.5 screws x 8
* Since February 2023, the CR2032 battery is replaced by the 30 cm XH2.54 cable.

6
4. How Does Witty Pi Work?
The diagram below shows the basic workflow of how Witty Pi turns on/off your Raspberry Pi.
After you tap the button on Witty Pi, it powers your Raspberry Pi via the GPIO header, and your
Raspberry Pi will boot. Witty Pi’s software will run automatically after boot, which will send the
SYS_UP signal (via GPIO-17) to Witty Pi. Witty Pi’s firmware receives the SYS_UP signal and starts
to listen to Raspberry Pi’s TXD pin (GPIO-14). If you shut down your Raspberry Pi (running shutdown
command or choose “Shutdown” in GUI), the TXD pin will go LOW and Witty Pi will cut the power
after some delay. If you tap the button again, that equals to shorting GPIO-4 to GND, and Witty Pi’s
software will run shutdown command for you.
Witty Pi has realtime clock (RTC) onboard and it always knows the time. You can schedule the
shutdown and startup of your Raspberry Pi, which are implemented with two alarms. When the alarm
is triggered, Witty Pi’s firmware will emulate a “button clicking”, which will turn on/off your Raspberry
Pi accordingly. You can either configure single alarm for shutdown and/or startup, or you can define a
simple script to plan a rather complex on/off sequence for your Raspberry Pi.
Witty Pi has Analogue to Digital Converter (ADC) in its microcontroller (MCU), which can measure
the input voltage (via the white XH2.54 connector). If the voltage is dropped below the preset
threshold, Witty Pi’s firmware will emulate a “button clicking” to turn off your Raspberry Pi. If the
voltage is raised above the preset threshold, Witty Pi’s firmware will emulate another “button clicking”
to turn on your Raspberry Pi again. This allows you to turn off/off your Raspberry Pi according to
input voltage.
Witty Pi also has temperature sensor onboard. If the temperature rises over the preset threshold,
Witty Pi’s firmware can emulate a “button clicking” to turn off or turn on your Raspberry Pi. If the
temperature drops below the preset threshold, Witty Pi can also turn on/off your Raspberry Pi. You
can define the complete logic according to your needs, and turn your Raspberry Pi to a
temperature-controlled device.

7
5. Software Installation, Updating and Uninstallation
Remarks: Witty Pi’s software is developed and tested under Raspberry Pi OS (the former
Raspbian). If you want to use Witty Pi on other Linux distributions, you may not be able to install the
software without error. This is due to the fact that different Linux distributions have different packages
installed by default, and their default users may have different privilege settings too. You may need to
modify the software installation script or even the software itself, however this will need you to have
some knowledge of BASH programing.
5.1 Install Software
To install the software, please run this command to download the installation script:
Then you can run the command below to install the software:
We use “sudo” here because install.sh needs to register the wittypi service (daemon.sh) to run
automatically after boot, which needs root privilege.
The install.sh will also run UWI installation script. If you already have UWI installed before, it will
compare the versions and update your UWI when needed.
5.2 Update Software
If there is a newer version of software and you want to install it, in most of the time you just need to
repeat the installation process and let it overwrite your current version.
If you prefer, you can also fully uninstall the software (please see below) and then install it again.
5.3 Uninstall Software
To uninstall the software, you need to remove the “wittypi” directory (the one that includes the
software files) and remove wittypi service from the auto-run list. Please use this command:
If you also want to uninstall UWI, you need to remove the “uwi” directory and remove uwi service
from the auto-run list. Please use this command:
pi@raspberrypi:~ $ wget https://www.uugear.com/repo/WittyPi4/install.sh
pi@raspberrypi:~ $ sudo sh install.sh
pi@raspberrypi:~ $ update-rc.d -f wittypi remove

8
6. Mounting Witty Pi 4 on Raspberry Pi
You can directly mount Witty Pi 4 on your Raspberry Pi’s 2x20pin header, and it will work. However, if
you wish, you can use the copper standoffs and screws in the package to firmly mount Witty Pi 4 on
your Raspberry Pi.
First, you can mount the four copper standoffs on your Raspberry Pi, using the screws.
Your Raspberry Pi should look like this after mounting the four standoffs:
pi@raspberrypi:~ $ update-rc.d -f uwi remove

9
Then you can mount Witty 4’s stacking header on Raspberry Pi’s 2x20 pin male header, and then
tighten the screws.
You can put the CR2032 button battery into the battery holder. With that battery, Witty Pi can
remember the time even after you fully cut its power. The RTC only draws about 4uAcurrent from the
battery to keep the time, and the battery can last for years. If your Witty Pi is always powered, you
may omit this battery and Witty Pi's functionalities will not get affected.
After mounting Witty Pi 4 on your Raspberry Pi, you can connect power supply to Witty Pi 4 (via the

10
USB Type C connector or via the XH2.54 connector). Please do not connect power supply to your
Raspberry Pi directly, because Witty Pi will power your Raspberry Pi via the GPIO header, and that
is how it performs the power management.
When your Witty Pi is powered, you can see the white LED blinks for every few seconds, which
means it is standing by.
Now your Witty Pi 4 is ready to go.

11
7. Software Usage
The main executable (wittyPi.sh) is a bash script, and you can run it like this:
This interactive script displays the status of the device, and accepts your input to make configuration
accordingly.
There are 13 options in the main menu, and you can input the number and press ENTER to confirm.
Every time you press ENTER, the script will re-print the device status so you can see if the change
has taken affect.
7.1 Write system time to RTC
This option will copy the time from your Raspberry Pi system to the Realtime Clock on Witty Pi. This
pi@raspberrypi:~/wittypi $ ./wittyPi.sh
pi@raspberrypi ~/wittypi $ ./wittyPi.sh
================================================================================
| |
| Witty Pi - Realtime Clock + Power Management for Raspberry Pi |
| |
| < Version 4.00 > by Dun Cat B.V. (UUGear) |
| |
================================================================================
>>> Current temperature: 35.625°C / 96.125°F
>>> Your system time is: 2022-05-15 11:14:18 CEST
>>> Your RTC time is: 2022-05-15 11:14:17 CEST
>>> Vout=5.00V, Iout=0.51A
Now you can:
1. Write system time to RTC
2. Write RTC time to system
3. Synchronize with network time
4. Schedule next shutdown
5. Schedule next startup
6. Choose schedule script
7. Set low voltage threshold
8. Set recovery voltage threshold
9. Set over temperature action
10. Set below temperature action
11. View/change other settings...
12. Reset data...
13. Exit
What do you want to do? (1~13)

12
option should be used when you find the Raspberry Pi system time is correct (may be synchronized
from the Internet) while the RTC time is not correct.
7.2 Write RTC time to system
This option will copy the time from the Realtime Clock on Witty Pi to your Raspberry Pi system. This
option should be used when you find the RTC time is correct while the system time is not correct.
7.3 Synchronize time
If you choose this option, it will check if Internet is accessible, and apply network time to Raspberry Pi
system and RTC when possible.
If your Raspberry Pi is not connected to Internet, choosing this option will do nothing.
7.4 Schedule next shutdown
This option allows you to specify when your Raspberry Pi should shutdown automatically.
Please notice the input format should be “DD HH:MM:SS”. DD means the day in the month, HH is the
hour, MM is the minute and SS is the second. All these should be 2 digits and 24-hour system should
be used.
Unlike the previous version of Witty Pi, the “??” wildcard is no longer supported. This is because
the alarms are now implemented by the micro controller, and the MCU does not have enough
resource to implement this wildcard. However, you can use schedule script to do what “??” wildcard
does. Please refer the Migrating from Witty Pi 3 to Witty Pi 4 chapter.
Schedule script can actually make much more complex schedule. You can find more details in
Schedule Script section.
7.5 Schedule next startup
This option allows you to specify when your Raspberry Pi should startup automatically.
Here you will need to input the startup time in the same “DD HH:MM:SS” format, and again the “??”
wildcard is not supported here. You can use schedule script to do the same and even better.
7.6 Choose Schedule Script
If you want to define a complex ON/OFF sequence for your Raspberry Pi, you should schedule
script.
A schedule script (.wpi file) defines a loop, with all states and their durations inside. After Raspberry
Pi is boot, the “runScript.sh” will be run automatically, which will schedule the next shutdown and next
startup for you, and hence a complex ON/OFF sequence could be achieved.

13
After you select the “Choose schedule script”option, it will list all schedule scripts in the “schedules”
folder. You can choose one, and then Witty Pi will load and run it.
If you want to confirm what the script is doing, you can check the “schedule.log” file in the “~/wittypi”
directory, when your Raspberry Pi is running.
If you want to create your own schedule script, please read the “Making Schedule Script” section.
7.7 Set low voltage threshold
If you are powering your Witty Pi via the XH2.54 connector, and the input voltage is lower than the
low voltage threshold, Witty Pi will shut down your Raspberry Pi. Here you can specify the low
voltage threshold from 2.0V to 25.0V. If you want to disable the low voltage threshold, just set it to 0,
which is actually its default value.
7.8 Set recovery voltage threshold
If you are powering your Witty Pi via the XH2.54 connector, and the input voltage is higher than the
recovery voltage threshold, Witty Pi will turn on your Raspberry Pi if it was previously shut down due
to low input voltage. Here you can specify the recovery voltage threshold from 2.0V to 25.0V. If you
want to disable the recovery voltage threshold, just set it to 0, which is actually its default value.
Low
Voltage
Recovery
Voltage
Result
Not Set
Not Set
Witty Pi doesn’t care about the input voltage changing.
Set
Not Set
Witty Pi will shut down your Raspberry Pi if input voltage is too low. It will not turn on
Raspberry Pi unless you tap the button, or the scheduled startup comes (given input
voltage is higher than low voltage threshold).
Set
Set
Witty Pi will shut down your Raspberry Pi if input voltage is too low. Once this happens,
Witty Pi will monitor the input voltage during the sleep and will turn on your Raspberry Pi
when input voltage gets higher than recovery voltage threshold.
Not Set
Set
Witty Pi will wake up your Raspberry Pi when input voltage is higher than recovery
voltage threshold. Please mind that if input voltage is always higher than recovery voltage
threshold, you will not be able to turn off your Raspberry Pi with these settings, because it
always turns on Raspberry Pi again just after shutting it down.
The low voltage threshold and recovery voltage threshold can be set individually and their
combinations will make Witty Pi works differently, please see the table below for details.

14
7.9 Set over temperature action
Here you can specify what to do if temperature exceeds a preset threshold. It does nothing by default,
but you can choose to shut down or startup your Raspberry Pi when this event happens.
The action you chose will be triggered when the temperature is higher than the temperature you
input. For example, if you input 55C here, the action will be triggered when actual temperature is
56C or higher.
Remarks: shutdown can be triggered by temperature only after 2 minutes since Raspberry Pi is on.
7.10 Set below temperature action
Here you can specify what to do if temperature drops under a preset threshold. It does nothing by
default, but you can choose to shut down or startup your Raspberry Pi when this event happens.
The action you chose will be triggered when the temperature is lower than the temperature you input.
For example, if you input 55C here, the action will be triggered when actual temperature is 54C or
lower.
Remarks: shutdown can be triggered by temperature only after 2 minutes since Raspberry Pi is on.
7.11 View/change other settings...
Choosing this option will display a sub menu and allows you to set these parameters:
Default state when powered
It is “OFF” by default, which means your Raspberry Pi will not be turned on when power
supply is connected to Witty Pi, and you will need to tap the button on Witty Pi to start it. Here
you can set it to 1 (ON) or 0 (OFF).
Power cut delay after shutdown
Default value is 5.0 seconds, which means Witty Pi will fully cut the power after 5 seconds
since Raspberry Pi has been shut down. Here you can input a number between 0.0 to 25.0.
Pulsing interval during sleep
This parameter will decide how long Witty Pi’s micro controller will wake up and drive the
white LED and/or the dummy load. By default, this interval is 4 seconds. If you wish the white
LED blinks slower, or the dummy load draws current less frequently, you can choose a bigger
value. This value is in seconds.
White LED duration
This parameter will decide how long the white LED should stay on, when Witty Pi blinks it
during the sleep. The default value is 100, and you can use bigger value if you wish the white
LED to stay on for longer. Here you can input number from 0 to 255. If you input 0, the white
LED will not blink at all.

15
Dummy load duration
This parameter will decide how long the dummy load should draw current from the power
source.
What is (pulsing) dummy load? It is a trick to keep power bank alive, when Raspberry Pi is off.
If you are using power bank to power Witty Pi 4 + Raspberry Pi, after turning off Raspberry Pi
and cut the power, Witty Pi 4 only draws about 1mA from the power bank, which is way too
small to keep the power bank alive. If the power bank goes to sleep mode, it will not provide
any power to Witty Pi 4 and hence your Raspberry Pi will not wake up when scheduled
startup is due. Pulsing dummy load is such a trick, that it draws rather big current from the
power bank for a short duration and it does so with a fixed interval. That way the power bank
might be fooled and think the load is heavy enough, and avoid entering the sleep mode.
The default value of dummy load duration is 0, which means disabled (no dummy load at all).
You can set a value between 0 and 255 here. However, we suggest using smallest value
that could keep your power bank alive, usually 10 will do.
Vin adjustment
The voltage is measured by the 10-bit ADC in micro controller. Due to the inaccuracy of
internal voltage standard and error on divider resistors, the result could have up to 5% error.
You can configure this parameter to adjust the result of voltage measurement.
The default value is set to 0.20V, and you can input a value between -1.27 and 1.27 here.
Vout adjustment
You can configure this parameter to adjust the result of output voltage measurement.
The default value is set to 0.20V, and you can input a value between -1.27 and 1.27 here.
Iout adjustment
The output current is calculated by measuring the voltage drop on the 0.05 Ohm sampling
resistor. You can configure this parameter to adjust the result of output current calculation.
The default value is set to 0.00A, and you can input a value between -1.27 and 1.27 here.
7.12 Reset Data…
If you want to erase some data you previously set (scheduled startup time, scheduled shutdown time,
currently used schedule script, low voltage threshold, recovery voltage threshold), you can choose
this option.
Once you select this option, the software will display a sub menu, which allows you to:
Clear auto startup time:
The auto-startup time will be erased and Witty Pi will not auto-start your Raspberry Pi.
Clear auto shutdown time:
The auto-shutdown time will be erased and Witty Pi will not auto-shutdown your Raspberry Pi.
Stop using schedule script:
The “schedule.wpi”file will be deleted.

16
Clear low voltage threshold:
The low voltage threshold will be unset.
Clear recovery voltage threshold
The recovery voltage threshold will be unset.
Clear over temperature action
The over temperature action will be cleared.
Clear below temperature action
The below temperature action will be cleared.
Perform all actions above:
Clear all scheduled times, remove the “schedule.wpi”file, unset the low voltage and recovery
voltage thresholds, clear the over-temperature and below temperature actions. This is the
fastest option to clear everything and prevent your Raspberry Pi being shut down by Witty Pi.
7.13 Exit
Selecting this option will exit the software and return to the console.