This guide will lead you through installation and basic configuration of the most recent release of Pygenda on a Gemini PDA running Gemian Linux.
The guide is intended for users who want to install/run/test Pygenda. If you want to contribute to or modify Pygenda, then you probably want to get the latest version from GitHub (which is usually a little ahead of the latest official release). This guide may be useful to refer to for dependencies and initial configuration.
Note that Pygenda is alpha software, and as such has lots of missing/incomplete features as well as bugs. It is released for testing and feedback purposes, but you may also find it useful.
This guide may seem rather long. This is partly because Gemian Linux has not been updated for several years, so it is necessary to make some changes so that standard Debian packages can be installed. If you are using these instructions to help you install Pygenda on a different (relatively up-to-date) Linux distribution, then it should be simpler than described here: there will be no need to edit the apt sources files or update pip.
First, check that you have the correct device and operating system for this guide: the Gemini PDA made by Planet Computers. This should be running Gemian Linux (a version of Debian), not Android.
To check your Gemian (Debian) version, open a command prompt on the Gemini and enter the following command:
cat /etc/debian_version
It should output one line saying 9.13.
At the time of writing, version 9.13 is the most recent version. If you have an older version of Debian, then I suggest you update before installing Pygenda. Unfortunately, since Debian themselves no longer support Debian version 9, updating Gemian is not a simple process, and is not described in this document1. If you have Debian 10.x or later, then the quickstart for Debian-like systems will be a better starting point than this guide.
Since Debian version 9 ("stretch") is no longer supported by Debian, the packages have moved to Debian's "archive" server. If you have not already done so, you should update the apt sources to use to the new URL.
To do this, you need to edit the file /etc/apt/sources.list.d/multistrap-debian.list.
First, make a backup:
cp -i /etc/apt/sources.list.d/multistrap-debian.list ~/multistrap-debian.list-BACKUP
Then edit the file with the command:
sudo nano /etc/apt/sources.list.d/multistrap-debian.list
(You will probably need to enter your password here.)
The file has several lines referring to http.debian.net. Change each
of these to archive.debian.org (note, two parts change: http and
net). The final file should look something like:
deb [arch=arm64] http://archive.debian.org/debian stretch main contrib non-free
deb-src http://archive.debian.org/debian stretch main contrib non-free
(There may be some variation if you have previously made changes to this file).
Save the file and exit: ctrl+o (confirm filename), ctrl+x.
The following commands install dependencies for Pygenda. Note that you will need to be connected to the Internet, since these download packages.
Enter the following command in the command prompt (requires password):
sudo apt update
This apt update gives me errors relating to the thinkglobally repository, its certificates and lack of a Release file. For this guide, I don't believe this matters because everything we need to install comes from the Debian repository2. So continue...
sudo apt install python3
sudo apt install python3-pip
sudo apt install libgtk+3
Now use the "pip" Python package tool to update itself:
pip3 install --user pip==20.3.4
(This version of pip has better support for installation of binary "wheel" packages.)
Enter the following command to download and install Pygenda (and the Python modules that it depends on) from the PyPI repository:
pip3 install --user pygenda
(This gives a warning about being invoked by an old script wrapper, and a notice about deprecation. These can be ignored as they both concern "future version"s of pip, i.e. ones after version 20.3.4 installed above.)
Test Pygenda runs:
python3 -m pygenda
Pygenda should start in a small window. Don't worry if the font sizes are inappropriate, these will be configured below. For now we're just checking that it starts. (There will be a few warnings on the console related to the accessibility bus and the theme. This is expected on the Gemini.)
Enter the following to edit the Pygenda user CSS file:
mkdir -p ~/.config/pygenda/
nano ~/.config/pygenda/pygenda.css
(Commands in this section use the Nano text editor, you can use vim or emacs or something else if you want.)
This should open an empty file. Add the following line:
@import "../../.local/lib/python3.5/site-packages/pygenda/css/gemini.css";
Save the file and exit: ctrl+o (confirm filename), ctrl+x.
Now edit the Pygenda configuration file:
nano ~/.config/pygenda/user.ini
Again, this should open an empty file. You have some choice about what to enter here, depending on your preferences. Here's a reasonable basic configuration, which you can modify as required:
[global]
24hr = True
# Localisation settings should be picked up from the system.
# If not, language & date order (DMY, MDY, YMD) can be set with:
#language = fr
#date_ord = DMY
[startup]
# You probably want the UI either maximised or full-screen,
# so choose one of the following to be True...
maximize = True
fullscreen = False
[softkeys]
# Uncomment one of these if you want the soft keys on the left
# or hidden:
#display = left
#display = hide
[todo_view]
list0_filter = UNCATEGORIZED
list1_title = Shopping list
list1_filter = shopping
# ...and so on for additional todo lists: list2_title, list2_filter etc.
# listN_title gives the todo list name as displayed in the UI.
# listN_filter gives the tag to use internally in the icalendar data.
(Lines starting with a # are comments, so can be changed or omitted.
For other settings, see defaults.ini.)
As before, save the file and exit: ctrl+o (confirm filename), ctrl+x.
Now you can start Pygenda again, and it should look better (appropriate font sizes and other elements).
The custom CSS file ~/.config/pygenda/pygenda.css gives the user
lots of scope to customise the appearance of Pygenda to their own
needs.
One possibility is a "dark mode". An example dark mode CSS file is available: darkmode.css. To use this, copy its contents into your user CSS file, below the import line, and edit the URLs in the CSS so that they point to the .svg files in the Pygenda install (these are the files for the icons in Year View; they are in the same directory as the gemini.css file, so the directory path will be the same for the import that you added above). You can then edit/tweak/add to the CSS as desired.
To add a launch icon to your desktop menu, in a command prompt:
mkdir -p ~/.local/share/applications/
ln -s ~/.local/lib/python3.5/site-packages/pygenda/app/pygenda.desktop ~/.local/share/applications/
(This creates a link to the .desktop file included with Pygenda.)
To add a launch icon to the LXQt panel (LXQt is the the default desktop on Gemian), edit the panel configuration file:
nano ~/.config/lxqt/panel.conf
This file should already exist, with sections named [General],
[mainmenu], etc. Scroll down to the [quicklaunch] section. It
should look something like this:
[quicklaunch]
type=quicklaunch
alignment=Left
apps\size=2
apps\1\desktop=SOME_APPLICATION
apps\2\desktop=SOME_OTHER_APPLICATION
You will need to add an extra line:
apps\NUMBER\desktop=HOME_DIR/.local/lib/python3.5/site-packages/pygenda/app/pygenda.desktop
Note 1: Change NUMBER above to the next number in the sequence in
your panel.conf file (so that would be 3 in the example shown above).
Note 2: Change HOME_DIR to your home directory (which will be
/home/gemini for the default user account, and probably /home/xyz
if your user login name is xyz).
Note 3: Also change to line apps\size=XX to reflect the number of
applications now listed (that would mean changing 2 to 3 in the
example above).
If you have no [quicklaunch] section, you can add a new one at the
end of the file:
[quicklaunch]
type=quicklaunch
alignment=Left
apps\size=1
apps\1\desktop=/home/gemini/.local/lib/python3.5/site-packages/pygenda/app/pygenda.desktop
There should already be a reference to the plugin quicklaunch in one
of the panelX sections. For example:
[panel1]
...
plugins=... quicklaunch, ...
...
If this does not exist, then you will need to add it to the list of plugins for your chosen panel.
After all this, save the file and exit: ctrl+o (confirm filename), ctrl+x.
You will need to log out and back in again for this change to take effect.
By default, Pygenda saves entries in a single file. This is convenient for testing, but it could lead to data loss (if multiple programs try to update the same file) or slowdown for large files. Hence, if you want to use Pygenda for more than just testing, we recommended that you store your agenda data in a server (running on the same device).
Pygenda supports CalDAV servers and the Evolution Data Server. Unfortunately, the package needed to access EDS is only available in Debian Bullseye (11) and later, so for the Gemini we will use a CalDAV server.
In this section we go through a basic install and setup using the Radicale CalDAV server (version 3).
For those who want more technical details (e.g. to configure Pygenda to use a different server), more complete information is available here: CalDAV.md
First install Radicale and dependencies with pip:
pip3 install radicale --user
Create a configuration file for Radicale:
mkdir ~/.config/radicale
nano ~/.config/radicale/config
Add the following content to the file and save it:
[storage]
filesystem_folder = ~/.radicale-data
Now set Radicale to launch when you login. In the LXQt app menu, go to
Preferences -> LXQt Configuration Center -> Session Settings ->
Autostart. Tap the "Add" button and add a command with name "Radicale"
and command "python3 -m radicale" (this will create a .desktop file
in ~/.config/autostart/).
Then logout and login again to start the Radicale server.
To add calendars to Radicale, use the web interface. In a web browser go to: http://localhost:5232/
In the Radicale web interface, enter the user name of your choice, leave the password blank, and login. Once logged in you can create a new calendar. We suggest a Title of "agenda" (but you may want to create several calendars, e.g. "personal" and "work") and Type "calendar and tasks". Now close the browser.
Install the Python caldav package and dependencies:
sudo apt install libxml2-dev libxslt-dev
pip3 install caldav==0.11.0 --user
Note: Installing caldav takes a long time (around ten minutes). In particular, I thought it had frozen when running setup.py for lxml.
Now edit the file ~/.config/pygenda/user.ini (see above, Configuration) and add the following:
[calendar]
type = caldav
server = http://localhost:5232/
username = USERNAME_ENTERED_ABOVE
password = pass
calendar = agenda
A password is required, but it can be anything.
If you used a different Title creating the calendar, in the Radicale web interface, use that instead of "agenda" for the calendar value (in fact, if you only have one calendar then you can omit that line). If you created more than one calendar, you can configure the others as [calendar1], [calendar2], etc., giving the appropriate names for the calendar setting in each section.
Now test that Pygenda launches, and that you can create new entries.
Security note: You may be concerned that the Radicale server is accessible to other people on the network. This should not be a problem because by default it only binds to localhost.
I'd be grateful if you emailed me at [email protected] to let me know that you've tried Pygenda. It's a small project without lots of testers, so even feedback to say "it worked for me" is useful to let me know I haven't accidentally broken it. (I also welcome bug reports, feature requests, bug fixes, translations, corrections & additions to the documentation, new features, etc.)
To update to the latest release of Pygenda, enter the following command:
pip3 install --user pygenda --upgrade
You can check the latest available version at https://pypi.org/project/pygenda/
To see which version is currently installed, either check the "About" menu in Pygenda, or run:
pip3 show pygenda
If an update breaks something, please let us know about the problem at [email protected]. Then you can go back to an older version using:
pip3 install --user pygenda==0.2.8
(Change 0.2.8 to your desired version.)
Footnotes
-
Seriously, this is much more risky that a standard Debian upgrade. You risk losing data, breaking your installed apps, or even stopping Linux from booting (meaning you'll need to re-flash to get it back – possibly losing data on your Android or other partitions too). You must backup any data/files that you don't want to lose before starting, including anything on your Android or other partitions. I can't help you, since it's not going to be the same on every device. However, I'll mention some things that seemed to work when I was helping someone upgrade from 9.11 to 9.13. First, you'll need to update the apt sources as described in this document. Then when doing
apt updateyou may need to use the options to allow insecure repositories (this is a security risk). Now try the upgrade command:sudo apt full-upgrade. If you get file conflicts with LibreOffice-Base, you could try forcing it with:sudo apt install -o DPkg::options::="--force-overwrite" libreoffice-base. ↩ -
If you find that you do need something from the thinkglobally repository, you can try forcing it to trust these repositories with:
sudo apt -o Acquire::AllowInsecureRepositories=true -o Acquire::AllowDowngradeToInsecureRepositories=true update. Obviously, allowing insecure repositories like this is a security risk. ↩