Kiwix Hotspot

⚠️ STATUS NOTICE ⚠️

This project will be superseeded by another one. As such it is not receiving any improvement effort beside critical bug fixes. Watch this file or notify yourself to contact@kiwix.org if you want to be informed once the new project is released.

---

This Windows/macOS/Linux software installs an hotspot system on an SD card (or an img file) for raspberrypi (from Pi zero to Pi400).

This solution serves offline content (using kiwix-serve and other tools) from the web such as Wikipedia, the Gutenberg library, TED talks.

Kiwix Hotspot configures the RaspberryPi image into a WiFi hotspot with offline contents.

Building an hotspot image is a long and resources consuming process (from 30mn to 7h+ depending on your content selection, Internet bandwidth and computer power).

Hotspot Cardshop is an online service that builds the image for you and sends you a link to download it (or sends you an SD-card by mail).

CLI usage

Kiwix Hotspot is a graphical app but has a command-line counterpart that

• run cli mode: kiwix-hotspot cli
• show help: kiwix-hotspot cli -h
• show catalog (list of Zim packages available): kiwix-hotspot cli --catalog

usage: kiwix-hotspot [-h] [--name NAME] [--timezone TIMEZONE]
                     [--language {en,fr}] [--wifi-pwd WIFI_PWD]
                     [--kalite {fr,en,es} [{fr,en,es} ...]]
                     [--aflatoun {yes,no}] [--wikifundi {fr,en,es} [{fr,en,es} ...]]
                     [--edupi {yes,no}] [--nomad {yes,no}]
                     [--mathews {yes,no}] [--africatik {yes,no}]
                     [--edupi-resources EDUPI_RESOURCES]
                     [--zim-install package package package]
                        install zim
  --size SIZE           resize image (8GB)
  --favicon FAVICON     set favicon
  --logo LOGO           set logo
  --css CSS             set css style
  --build-dir BUILD_DIR
                        set build directory (.)
  --catalog             show catalog and exit
  --admin-account ADMIN_ACCOUNT ADMIN_ACCOUNT
                        create admin account [LOGIN, PWD]
  --config CONFIG       use a JSON config file to set parameters (superseeds
                        cli parameters)
  --filename FILENAME   Output file name (without suffix)
  --shrink {yes,no}     Shrink image file
  --ram RAM             Max RAM for QEMU
  --sdcard SDCARD       Device to copy image to
  --root                Don't use udisks2 (linux-only, must be ran as root)

Run kiwix-hotspot from source

Setting up the environment is a bit tedious due to the number of external dependencies and the use of pygobjects as a GUI framework. It varies a lot by platform so the safest and most up-to-date instructions are in the build workflow.

• run GUI application: python3 kiwix-hotspot
• run CLI application: python3 kiwix-hotspot cli

Build base image

kiwix-hotspot uses a custom base image based off raspiOS with the following modifications (not exhaustive):

• SSH enabled
• 7GB / partition (ext4)
• 1GB /data partition (extfat)
• ansiblecube deployed: nginx, kiwix-serve, etc.

Should you want to build the base image:

kiwix-hotspot image --root 7GB --size 8GB --out my-base.img

See create-master workflow.

⚠️ currently fails on GH Actions (looses SSH connection to QEMU) but runs fine elsewhere. Very long process though: about 4h on a fast computer.

Contribute

We use black Coding Style and Formatting tool. Please make sure your contributions passes black.

Kiwix Hotspot is a python3 (3.7+) application that use PyGobject for GUI and QEMU for emulating ARM machine.

how it works:

• ask user for configuration
• download master image
• resize the this master image to the expected final size (adjusted to QEMU requirements)
• boot qemu with the image
• run ansiblecube (our ansible rules to setup everything in the running system) inside the emulation
• resize the image to the required minimal size
• write image to SD card if requested

insert_id_to_class_glade.py is a python3 script that insert id to class in the ui.glade file in order to be gtk3.10 compatible

Windows

we use a self extracting archive 7zS.sfx because pyinstaller in onefile on windows fails to give admin rights and also there was an issue if we set no console. assets are in /windows_bundle.

License

GPLv3 or later, see LICENSE for more details.