Merge branch 'publication' into 'master'

MIT License

Copyright (c) 2025 Jakob Moser

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

# Used third party content

## pinout.xyz

We adapted the excellent pinout.xyz to generate the interactive and static wiring diagrams.

- Files: `docs/wiring/*`

    - Modified version of [pinout.xyz](https://pinout.xyz/)

    - GitHub: https://github.com/pinout-xyz/Pinout.xyz

    - Maintainers: [@Gadgetoid](https://github.com/Gadgetoid) and [@RogueM](https://github.com/RogueM)

    - License: [CC BY-SA 4.0](https://github.com/pinout-xyz/Pinout.xyz/blob/master/LICENSE)

## Fira Sans

- Files: `poolpay/ui/pygame/resources/FiraSans/*`

    - Authors: The Mozilla Foundation and Telefonica S.A.

    - License: [SIL OPEN FONT LICENSE Version 1.1](./poolpay/ui/pygame/resources/FiraSans/OFL.txt)

## Strategy to write to Framebuffer display with PyGame

Adapted from an excellent Stack Overflow answer / Raspberry Pi Forum post:

- [Answer to “Python pygame fails to output to /dev/fb1 on a Raspberry Pi + TFT screen”](https://stackoverflow.com/a/54986161/)

    - Author: [Attila](https://stackoverflow.com/users/1327762/attila)

    - License: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)

### Base Image

1. Use the official “Raspberry Pi Imager” to flash an SD card

   * Use “Raspberry Pi OS” (the one recommended)

   * Use custom OS settings:

     * Hostname `poolpaypi`(`.local`)

     * Username `jakob`

     * Password: Auto-generate a safe one

     * Don't setup WiFi

     * Timezone: Europe/Berlin

     * Keyboard layout: de

     * Enable SSH auth via public-key, generate a keypair manually

     * Disable telemetry

    - Use “Raspberry Pi OS” (the one recommended)

    - Use custom OS settings:

        - Hostname `poolpaypi`(`.local`)

        - Username `jakob`

        - Password: Auto-generate a safe one

        - Don't setup WiFi

        - Timezone: Europe/Berlin

        - Keyboard layout: de

        - Enable SSH auth via public-key, generate a keypair manually

        - Disable telemetry

2. Insert the SD card into the Pi and boot it up

3. On your main computer, use Network Manager (GUI or [CLI](https://ubuntu.com/core/docs/networkmanager/configure-shared-connections)) to enable a “Shared Ethernet” connection

4. Use an ethernet cable to connect the Pi to your main computer

     * Your computer should immediately start acting as a “wired hotspot” now and provide IP address and internet access to the Pi.

    - Your computer should immediately start acting as a “wired hotspot” now and provide IP address and internet access to the Pi.

5. You can now `ssh jakob@poolpaypi.local` on your main computer and it shoud Just Work™.

### NFC Reader

Connect female-female cables to the RC522 module:

| Pin  | Color     |

| ---- | -------- |

| ---- | --------- |

| VCC  | 🩶 Gray   |

| RST  | 💜 Purple |

| GND  | 💙 Blue   |

2. Go to “Interface Options”

3. Go to “SPI”

4. Enable it (no reboot necessary)

   * This will enable the first SPI bus (SPI0)

    - This will enable the first SPI bus (SPI0)

5. Add the line `dtoverlay=spi1-1cs,cs0_pin=16` somewhere in `/boot/firmware/config.txt` (reboot might be necessary here)

   * This will enable the second SPI bus (SPI1). Furthermore, it will set the Chip Select pin for device 0 (`cs0`) to GPIO 16.

    - This will enable the second SPI bus (SPI1). Furthermore, it will set the Chip Select pin for device 0 (`cs0`) to GPIO 16.

<details>

<summary>Links</summary>

1. Plug in a WiFi stick (on the Raspberry Pi 3 Model V1.2, I didn't get the internal WiFi to work as a hotspot, however, that seems to be an issue that only I with my specific Pi have)

2. Create a network manager configuration in `/etc/NetworkManager/system-connection/PoolPayPi.nmconnection`, get the following information ...

   * The `interface-name` for the stick (`wlan1` if the Pi has built-in wifi, `wlan0` if it hasn't)

   * A secure password (Pre-Shared Key, `psk`)

    - The `interface-name` for the stick (`wlan1` if the Pi has built-in wifi, `wlan0` if it hasn't)

    - A secure password (Pre-Shared Key, `psk`)

    ... and insert it into this ready made template, which you then save:

<details>

<summary>Further information on hotspots</summary>

* You can create a hotspot (which will create more or less the same config as seen above using):

- You can create a hotspot (which will create more or less the same config as seen above using):

    ```bash

    sudo nmcli dev wifi hotspot ifname wlan1 ssid PoolPayPi password $PASSWORD

    ```

* If you want the hotspot to start on boot, you need to add `autoconnect=true` to the config file (which you can, btw, also do using some `nmcli` command)

* If you use both the WiFi hotspot and the shared ethernet connection (which is easily possible), [one of the connections needs its own IP range](https://askubuntu.com/questions/844913/how-to-control-ip-ranges-of-network-managers-hotspots), otherwise, they will collide.

- If you want the hotspot to start on boot, you need to add `autoconnect=true` to the config file (which you can, btw, also do using some `nmcli` command)

- If you use both the WiFi hotspot and the shared ethernet connection (which is easily possible), [one of the connections needs its own IP range](https://askubuntu.com/questions/844913/how-to-control-ip-ranges-of-network-managers-hotspots), otherwise, they will collide.

</details>

    ```ini

    dtoverlay=fbtft,spi0-0,ili9486,width=320,height=480,regwidth=16,reset_pin=25,dc_pin=24,rotate=270

    ```

3. Add `fbcon=map:2` at the end of the line to `/boot/firmware/cmdline.txt`

   * This will tell the framebuffer console (fbcon) to map all its terminals to `/dev/fb2` (which doesn't exist), i.e. don't show a Linux TTY on the display

    - This will tell the framebuffer console (fbcon) to map all its terminals to `/dev/fb2` (which doesn't exist), i.e. don't show a Linux TTY on the display

<details>

<summary>Links</summary>

- [Raspberry Pi Forum post mentioning the line to include in the config (German)](https://forum-raspberrypi.de/forum/thread/55290-displays-mit-spi-anschluss-unter-raspberry-pi-os-bullseye-bookworm/)

- [Python pygame fails to output to /dev/fb1 on a Raspberry Pi + TFT screen](https://stackoverflow.com/a/54986161/)

CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/)

- [Device tree overlays README](https://github.com/raspberrypi/firmware/blob/master/boot/overlays/README)

- [RB-TFT3.5 Manual (German)](https://joy-it.net/files/files/Produkte/RB-TFT3.5/RB-TFT-Anleitung_04082020.pdf)

- [Frame Buffer Kernel Docs](https://www.kernel.org/doc/html/latest/fb/fbcon.html)

Create a user account called `poolpay`. Equip it with the necessary permissions:

* Allow `poolpay` to access GPIO

* Allow `poolpay` to use `sudo` **to use `luks`** (don't give it general sudo access)!

- Allow `poolpay` to access GPIO

- Allow `poolpay` to use `sudo` **to use `luks`** (don't give it general sudo access)!

Create a folder `/coli`, cd into it and make sure the permissions are correct.

sudo cp /coli/poolpay/poolpay.service /etc/systemd/system

sudo systemctl enable --now poolpay

```

## License

This project is licensed under the [MIT license](https://opensource.org/licenses/MIT), for details see the file [`LICENSE`](LICENSE).

This license only applies to the original contributions of the project's authors and not necessarily for used contents from third parties. The file [`LICENSE-3RD-PARTY.md`](LICENSE-3RD-PARTY.md) documents, which (parts of which) files come from third parties and under what license they are used.

I currently want to avoid having to start an X Server or Wayland, mostly because:

* I am afraid they will introduce additional ways to escape my application.

* They will likely add additional complexity I don't need.

- I am afraid they will introduce additional ways to escape my application.

- They will likely add additional complexity I don't need.

This means we will likely even use **Raspberry Pi OS Lite**, because if we don't need an X Server or a desktop environment, why install it?

1. Create extra user (without `sudo` etc.) for login

2. Configure auto login for that user (there should be official documentation on that)

3. Change shell to the Python app

   * For 2. and 3., see [`autologin.md`](autologin.md) for details

    - For 2. and 3., see [`autologin.md`](autologin.md) for details

4. Build a terminal-based Python app (e.g. with Textualize)

## Autostart via systemd unit

We want to extract the following data:

* 7 byte UID of the card (see MF0ICU1 data sheet, section 1.2.1)

* Complete user Read/Write area

- 7 byte UID of the card (see MF0ICU1 data sheet, section 1.2.1)

- Complete user Read/Write area

As a reference we use the NXP TagInfo smartphone app. We want to extract everything in the “Full Scan” → “Memory Content” section.