UUGear Witty Pi 3 User manual

Copyright © 2019 UUGear s.r.o. All rights reserved.
Witty Pi 3
Realtime Clock and Power Management for Raspberry Pi
User Manual (revision 1.03)

Copyright © 2019 UUGear s.r.o. All rights reserved.
Table of Content
What is Witty Pi?................................................................................ 1
What is in the Package? ...................................................................... 3
Witty Pi 3 Specifications..................................................................... 4
Software Installation ........................................................................... 5
Software Update/Uninstallation.......................................................... 7
Mounting Witty Pi 3 on Raspberry Pi................................................. 8
Input Voltage..................................................................................... 10
Software Usage ................................................................................. 11
1. Write system time to RTC ...........................................................................................12
2. Write RTC time to system ...........................................................................................12
3. Synchronize time .........................................................................................................12
4. Schedule next shutdown ..............................................................................................13
5. Schedule next startup...................................................................................................13
6. Choose Schedule Script ...............................................................................................14
7. Set low voltage threshold.............................................................................................15
8. Set recovery voltage threshold.....................................................................................15
9. View/change other settings..........................................................................................16
10. Reset Data… ............................................................................................................17
11. Exit...........................................................................................................................17
How Schedule Script Works?........................................................... 18
Make Schedule Script ....................................................................... 20

Copyright © 2019 UUGear s.r.o. All rights reserved.
Using Schedule Script Generator...................................................... 22
Advanced Usage of Schedule Script................................................. 23
The Unpopulated 3-Pin Header (P2)................................................. 24
The Unpopulated 7-Pin Header (P3)................................................. 24
Frequently Asked Questions (FAQ) ................................................. 27
What I2C Address is Used by Witty Pi 3?...........................................................................27
What I2C Registers Are Provided by Witty Pi 3?................................................................28
What GPIO Pins Are Used by Witty Pi 3?..........................................................................31
Is Witty Pi 3 Compatible with “Other Hardware”? .............................................................32
Witty Pi 3 does not boot?.....................................................................................................32
Revision History................................................................................ 35

1
What is Witty Pi?
Witty Pi is small electronic circuit board that can add realtime clock and power management to your
Raspberry Pi. Witty Pi 3 is the third generation of Witty Pi. After installing Witty Pi 3 on your
Raspberry Pi, you get some amazing new features:
You can power your Raspberry Pi with higher voltage.
You can gracefully turn on/off Raspberry Pi with single tap on the switch.
After shutdown, Raspberry Pi and all its USB peripherals’ power are fully cut.
Raspberry Pi knows the correct time, even without accessing the Internet.
Raspberry Pi knows the temperature thanks to the sensor in RTC chip.
You can schedule the startup/shutdown of your Raspberry Pi.
You can even write a script to define complex ON/OFF sequence.
Shutdown Raspberry Pi when input voltage is lower than pre-set value.
Turn on Raspberry Pi when input voltage raise to pre-set value.
When the OS loses response, you can long hold the switch to force power cut.
Witty Pi 3 supports all Raspberry Pi models that has the 40-pin GPIO header, including A+, B+, 2B,
Zero, Zero W, 3B, 3B+, 3A+ and 4B.
Comparing to Witty Pi 2, Witty Pi 3 uses the same RTC chip (DS3231SN) and introduces a new
micro-controller (ATtiny841), which allows it to behave smarter and handle more complex

2
situations. Thanks to the new on-board LDO voltage regulator (LM29150), Witty Pi 3 can accept DC
voltage higher than 5V (up to 26V, depends on the load and heat sink).
Witty Pi 3 doesn't have any jumper, and all configurations are done via I2C interface. Witty Pi's
software can help you to make configuration very quickly.
The picture below shows how is Witty Pi 3 look like:
1) Micro USB connector as DC 5V power input
2) XH2.54 connector as higher voltage DC power input
3) Unpopulated 3-pin header/connector for VIN, GND and 5V
4) White LED as indicator
5) On/off switch
6) 2x20 pin stacking header (connects to Raspberry Pi)
7) Unpopulated 2x3 pin ICSP header for uploading firmware
8) Battery holder for CR2032 button cell lithium battery
9) Unpopulated 7-pin header for extension or integration

3
What is in the Package?
Each Witty Pi 3 package contains:
Witty Pi 3 board x 1
CR2032 battery x 1
M2.5 x 11mm Copper Standoff x 4
M2.5 screws x 8

4
Witty Pi 3 Specifications
Dimension:
65mm x 56mm x 19mm
Weight
20g (net weight without battery)
Micro Controller
ATtiny841(datasheet)
Realtime Clock
DS3231SN (datasheet)
LDO Voltage Regulator
LM29150 (datasheet)
Battery
CR2032 (for time keeping)
Power In
DC 5V (via micro USB) or DC5.3V~26V (via
XH2.54 connector, better no higher than 8V without
additional heat sink)
Output Current
Up to 3A for Raspberry Pi and its peripherals if input
via micro USB port. Up to 2A if input via XH2.54
connector.
Standby Current
~ 1mA
Operating Temperature
-30℃~80℃(-22F~176F)
Storage Temperature
-40℃~85℃(-40F~185F)
Humidity
0~80%RH, no condensing

5
Software Installation
It is recommended to install the software for Witty Pi 3 before physically mount Witty Pi 3 on your
Raspberry Pi.
Before installing the software, please check whether you have 1-Wire interface enabled. This is
important because 1-Wire interface uses GPIO-4 by default, which will conflict with Witty Pi. If you
need to use 1-Wire interface, please assign it to a different GPIO pin.
You can assign different GPIO pin to 1-Wire interface in /boot/config.txt file, find the
“dtoverlay=w1-gpio” text and replace it with:
dtoverlay=w1-gpio,gpiopin=18
If you don’t need 1-Wire interface for now, you can disable it:
#dtoverlay=w1-gpio
If you have 1-Wire interface enabled on GPIO-4 and installed Witty Pi’s software, you may not be
able to login to your Raspberry Pi because it always shuts itself down before you get the chance to
login. To solve this problem, you will need to take out the micro-SD card on your Raspberry Pi, and
access its file system via a card reader. You need to edit the config.txt file (as mentioned above) in the
"boot" volume to change the GPIO pin used by 1-Wire interface, or you can disable 1-Wire interface if
you don't need it for now. After saving the file and put the micro SD card back to Raspberry Pi, you
should be able to boot it again.
In order to install the software, you will need to have your Raspberry Pi connected to the Internet.
The installation will be very simple if you run our installing script.
First step is to run this command in your home directory:
If your Raspberry Pi has internet connection, it will immediately download the script from our
website, and you will then see the “install.sh”script in your home directory. Then you just need to
run it with sudo as follows:
Please notice that sudo is necessary to run this script. This script will automatically do these tasks
in sequence:
1. Enable I2C on your Raspberry Pi
2. Install i2c-tools, if it is not installed yet
pi@raspberrypi ~ $ wget http://www.uugear.com/repo/WittyPi3/install.sh
pi@raspberrypi ~ $ sudo sh install.sh

6
3. Configure Bluetooth to use mini-UART (Raspberry Pi 3 only)
4. Install wiringPi, if it is not installed yet (Raspberry Pi 4 needs version 2.52+)
5. Install Witty Pi programs, if they are not installed yet
You can also manually install these packages and make those configurations, if you prefer to. After
the installation, please remember to reboot your Raspberry Pi, so the Realtime clock I2C hardware
will be loaded correctly.
You will then see a new “wittypi”directory, and it contains 6 runnable files… viz.:
Although the daemon.sh is runnable, you should not run it manually. The installing script has
registered it into /etc/init.d and it will run automatically after the start up.
The syncTime.sh script is not supposed to be manually run either; it will run automatically after the
start up. It will copy the time from Raspberry Pi system to RTC if you have never set the RTC time
before. If RTC has the correct time and your Raspberry Pi has the wrong time –perhaps because of
the lack of Internet connection, it will copy the RTC time to your Raspberry Pi system.
The runScript.sh script is the one who takes charge of the schedule script running. Usually you
don’t need to run it manually, as it will be executed after the system is up. If there is a schedule script
in use, it will schedule the next shutdown and next startup, according to the schedule script.
The wittyPi.sh is the software that allows you to configure your Witty Pi interactively. You can use
it to copy time between Realtime clock and the system, and schedule the time for auto shutdown
and/or startup. Please see the “Software Usage”chapter for more information.
The afterStartup.sh script will be run automatically after system is up. You can execute your own
commands here if you wish them to be run after boot.
The beforeShutdown.sh script will be run automatically before system gets shut down by Witty Pi
3. You can also place your commands here. Please notice that, if the system is not shut down by
Witty Pi 3 (tapping button, schedule shutdown or auto-shutdown due to low input voltage), this script
will not be executed.
Now the software has been installed and you will need to physically mount/install Witty Pi 3 on your
Raspberry Pi and connect power supply to Witty Pi 3 only.
pi@raspberrypi ~ $ cd wittypi
pi@raspberrypi ~ /wittypi $ ls
afterStartup.sh daemon.sh runScript.sh schedules utilities.sh wittyPi.sh
beforeShutdown.sh init.sh schedule.log syncTime.sh wittyPi.log

7
Software Update/Uninstallation
If you want to update the software to newer version, you don’t have to uninstall it first. Just remove
or rename your “wittypi” directory and repeat the installing process, then you are all set.
If you prefer to completely remove the software, besides removing the “wittypi” directory, you
should also remove the “/etc/init.d/wittypi” file. There are some dependencies (such as wiringPi,
i2c-tools etc.), which may be installed during the software installation. In the majority of cases you
don’t have to remove them, but if you wish to you can check the content of “install.sh”script and do
the reverse.
pi@raspberrypi ~ $ mv wittypi wittypi.bak
pi@raspberrypi ~ $ wget http://www.uugear.com/repo/WittyPi3/install.sh
pi@raspberrypi ~ $ sudo sh install.sh

8
Mounting Witty Pi 3 on Raspberry Pi
You can simply plug Witty Pi 3 on your Raspberry Pi’s 2x20 pin header, and it can work just like
that. However, if you wish, you can use the copper standoffs and screws in the package to tightly
mount Witty Pi 3 on your Raspberry Pi.
First you can mount the 3 copper standoffs on your Raspberry Pi, using the screws.
Your Raspberry Pi should look like this after mounting the 4 standoffs:

9
Then you can mount Witty Pi 3’s stacking header on Raspberry Pi’s 2x20 pin male header, and then
tighten the screws.
Don’t forget to put the CR2032 button battery into the battery holder, with the battery Witty Pi 3 can
remember the time even after you cut its power. The RTC only draws about 4uA current from the
battery to keep the time, so the battery can last years.
After mounting Witty Pi 3 on your Raspberry Pi, and connect the power supply to Witty Pi 3 (via the
micro USB connector or XH2.54 connector), you can see the white LED blinks for every few
seconds, which means it is standing by.
Now your Witty Pi 3 is ready to go.

10
Input Voltage
Witty Pi 3 newly adds an on board LDO voltage regulator (LM29150) and hence it can accept
voltage higher than 5V (if you input power via the XH2.54 connector).
The LM29150 is 26V tolerated, but it doesn’t mean you can really use 26V to power your Witty Pi 3.
LM29150 is a linear regulator, which means the dropped voltage will be dissipated as heat and the
heating power can be calculated by:
Pheat = Vdrop * Iout
For example, when using only Raspberry Pi 4 and no other devices attached, the Iout is about 0.5A. If
we input 9V and let the regulator to regulate it to 5V and power Raspberry Pi, the thermal dissipation
power will be: (9 –5) * 0.5 = 2W
This is rather high power and it needs to be dissipated soon enough, otherwise the regulator will
become hotter and hotter until it eventually overheated and gets damaged. You will need to install
external heat sink to use higher voltage.
Also please consider the efficiency, which will drop significantly when input voltage increase. When
using 6V the efficiency is about 83%, while using 9V the efficiency will be lower than 56%.
Our suggestion is to use no higher than 8V, when no external heat sink is installed. These power
sources would be ideal to power Witty Pi 3:
6V Lead-acid battery
1.5V battery x 4 (in series as 6V)
7.4V Li-po battery (2S)
5~8V solar panel
0.00%
20.00%
40.00%
60.00%
80.00%
100.00%
5.3V 6V 7.4V 9V 12V
Efficiency
Efficiency

11
Software Usage
The wittyPi.sh is a bash script, and you can run it with:
Please notice that sudo is not necessary here (older version of Witty Pi software needs that). The
programme displays the current temperature, the system time, the RTC time, the input/output voltage
and output current:
The program gives you 11 options, and you can input the number and press ENTER to confirm.
pi@raspberrypi ~/wittypi $ ./wittyPi.sh
pi@raspberrypi ~/wittypi $ sudo ./wittyPi.sh
================================================================================
|
| Witty Pi - Realtime Clock + Power Management for Raspberry Pi
|
| < Version 3.00 > by UUGear s.r.o.
|
================================================================================
>>> Current temperature: 29.50° C / 85.1° F
>>> Your system time is: Mon 24 Jun 2019 14:45:09 BST
>>> Your RTC time is: Mon 24 Jun 2019 14:45:10 BST
>>> Vin=7.92V, Vout=4.96V, Iout=0.30A
Now you can:
1. Write system time to RTC
2. Write RTC time to system
3. Synchronize time
4. Schedule next shutdown
5. Schedule next startup
6. Choose schedule script
7. Set low voltage threshold
8. Set recovery voltage threshold
9. View/change other settings...
10. Reset data...
11. Exit
What do you want to do? (1~11)

12
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 option should be used when you find the Raspberry Pi system time is correct (may be
synchronized from the Internet) and yet the RTC time is not.
2. Write RTC time to system
This option will copy the time from the Realtime Clock on Witty Pi 3 to your Raspberry Pi system.
This option should be used when you find the RTC time is correct while the system time is not.
3. Synchronize time
If you choose this option, it will run the “syncTime.sh” script explicitly, which should have been
executed once after the system is up.
This script will detect if Internet is connected, and apply network time to both system and RTC. The
Start
RTC time
is good?
Y
N
Write RTC time
to system
Internet
connected?
Force network
time update to
system
Write system time
to RTC
System time
is newer than
RTC?
Y
Y
End
N
N

13
flow chart below shows what this script actually do:
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”. DD means the day in the month, HH is the
hour, MM is the minute. All these should be 2 digits and 24-hour system is used. Here you can not
specify the second. This is a hardware limitation on the RTC chip, and only day, hour and minute
could be specified for scheduled shutdown.
You can use “??”as wildcard, which gives you the possibility to make a repeatable schedule. Please
see the table below:
Repeatable Shutdown Schedule
Day
(dd)
Hour
(HH)
Minute
(MM)
Result
??
??
??
Minutely Schedule (DON’T USE IT!)
??
??
Number
Hourly Schedule
??
Number
Number
Daily Schedule
Please don’t use “?? ??:??” to schedule the next shutdown, or your Raspberry Pi will keep being
shutdown and you hardly have a chance to change this setting (unless you remove the battery and
force RTC to forget it).
According to the hardware limitation, not all patterns with wildcards are supported. The rule is:
wildcards have to show up from let to right, and there is no number between two wildcards. So “??
??:38”is OK, while “?? 16:??”is not supported.
Here are some examples of scheduling the shutdown:
15 21:45 means 9:45 at night, on 15th in this month.
?? 23:30 means 23:30 at night everyday (daily schedule)
?? ??:15 means the 15th minute every hour (hourly schedule)
5. Schedule next startup
This option allows you to specify when your Raspberry Pi should startup automatically.

14
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 is
used. Different than the shutdown scheduling, you can specify the second here.
You can also use “??”as wildcard, which gives you the possibility to make a repeatable schedule.
Please see the table below:
Repeatable Startup Schedule
Day
(dd)
Hour
(HH)
Minute
(MM)
Result
??
??
??
Minutely Schedule
??
??
Number
Hourly Schedule
??
Number
Number
Daily Schedule
According to the hardware limitation, not all patterns with wildcards are supported. The rule is:
wildcards have to show up from let to right, and there is no number between two wildcards. So “??
??:??:12”is OK, while “?? 15:??:25”is not supported.
If you input an unsupported pattern, Witty Pi 3 will try to change it to the closest one that could be
supported. You will see the message on the console.
Here are some examples of scheduling the startup:
15 07:30:00 means 7:30 in the morning, on 15th in this month.
?? 23:30:00 means 23:30:00 at night everyday (daily schedule)
?? ??:15:00 means the 15th minute every hour (hourly schedule)
?? ??:??:05 means the 5th second every minute (minutely schedule)
6. Choose Schedule Script
What if you want to define a complex ON/OFF sequence for your Raspberry Pi? The answer is
“schedule script”.
A schedule script (.wpi file) defines a loop, with all states and their durations inside. By
automatically running “runScript.sh” after booting, Witty Pi 3 will automatically schedule the next
shutdown and next startup for you, and hence a complex ON/OFF sequence could be achieved.

15
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 3 will take care of the rest.
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 on.
If you want to create your own schedule script, please read the “Making Schedule Script”chapter.
7. Set low voltage threshold
If you are powering your Witty Pi 3 from the XH2.54 connector, and the input voltage is lower than
the low voltage threshold, Witty Pi 3 will shutdown your Raspberry Pi. Here you can specify the low
voltage from 2.0V to 25.0V. If you want to disable the low voltage threshold, just set it to 0.
8. Set recovery voltage threshold
If you are powering your Witty Pi 3 from the XH2.54 connector, and the input voltage is higher than
the recovery voltage threshold, Witty Pi 3 will turn on your Raspberry Pi if it was previously shut
down due to too low input voltage. Here you can specify the recovery voltage from 2.0V to 25.0V. If
you want to disable the recovery voltage threshold, just set it to 0.
Remarks: the low voltage threshold and recovery voltage threshold can be set individually and their
combinations will make Witty Pi 3 work differently.
Low Voltage
Recovery
Voltage
Result
Not Set
Not Set
Witty Pi 3 doesn’t care about the input voltage changing.
Set
Not Set
Witty Pi 3 will shutdown 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 3 will shutdown your Raspberry Pi if input voltage is too low. Once this happens,
Witty Pi 3 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 3 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 turn on Raspberry Pi again just after shutting it down.

16
9. 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 3, and you will need to tap the button on Witty Pi 3 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 3 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 8.0.
Pulsing interval during sleep
This parameter will decide how long Witty Pi 3’s micro control 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. Here you can only pick a value from 1, 2, 4 and 8.
White LED duration
This parameter will decide how long the white LED should stay on, when Witty Pi 3 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.
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 3 + Raspberry Pi, after turning off
Raspberry Pi and cut the power, Witty Pi 3 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 3 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 to use 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.

17
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.
10. 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 3 will not auto-start your Raspberry Pi.
Clear auto shutdown time:
The auto-shutdown time will be erased and Witty Pi 3 will not auto-shutdown your Raspberry
Pi.
Stop using schedule script:
The “schedule.wpi”file will be deleted.
Clear low voltage threshold:
The low voltage threshold will be unset.
Clear recovery voltage threshold
The recovery voltage threshold will be unset.
Perform all actions above:
Clear all scheduled times, remove the “schedule.wpi”file and unset the low voltage and
recovery voltage thresholds.
11. Exit
Selecting this option will simply exit the software and return to the console.