Giter Club home page Giter Club logo

piosk's Introduction

PiOSK Banner One-shot set up Raspberry Pi in kiosk mode as a webpage shuffler, with a web interface for management.

0. Foreword

This started as a simple automation script — a wrapper of the official Raspberry Pi kiosk mode tutorial for personal use. Then one thing lead to the other and I found myself installing nodejs & writing systemd unit files...

That's when I realized... maybe there are other people (or future me) who'd also find it useful.

This is far from done. It's just the first checkpoint that meets my initial goal of making the entire process a "single script setup".

1. Set Up Guide

PiOSK Setup Video Walkthrough

PiOSK Setup Video Walkthrough

Important

As of version 1.x, PiOSK assumes a few things to keep itself lean and just focus on essentials. It may still work even if some of those assumptions aren't met; however, report/fixes for those edge cases are welcome and appreciated.

1.1 Preparation

  1. Boot into Raspberry Pi desktop1
  2. Ensure network/WiFi/internet is working
  3. Ensure desktop auto login is enabled (is default)
  4. Ensure screen does not timeout & adjust brightness
  5. Ensure SSH is working if you want to install remotely

Note

Check recommendations section for more detailed explanations.

1.2 Installation

Either open terminal on the Raspberry Pi's desktop environment, or remote login to it; and run the following command:

curl -sSL https://raw.githubusercontent.com/debloper/piosk/main/setup.sh | sudo bash -

That's it2.

1.3 Configuration

1.3.1 Basic

  1. Visit http://<pi's IP address>/3 from a different device on the network
  2. You should see the PiOSK dashboard with a list of sample URLs as kiosk mode screens
  3. Feel free to add & remove links as necessary (at least 1 link is necessary for it to work)
  4. Once you're happy with the list, press APPLY ⏻ button to apply changes and reboot PiOSK
  5. When rebooted, wait for the kiosk mode to start & flip through the pages in fullscreen mode

1.3.2 Advanced

Warning

Try these at your own risk; if you know what you're doing. Misconfiguration(s) may break the setup.

  1. The PiOSK repo is cloned to the user's $HOME/piosk
  2. You can change the dashboard port from index.js
  3. You can change the per-page timeout from switcher.sh
  4. You can change browser behavior (e.g. no full screen) from browser.sh
  5. Some changes can be applied without rebooting, but rebooting is safer

PiOSK Dashboard Web GUI

1.4 Updating

For now, there's no direct way to update the setup. This will change.

You should uninstall old version and then reinstall the new version. As long as you don't delete the backup config file (created during uninstallation), it should be picked up and reinstated by the reinstallation process.

Look into the Uninstallation section for the next steps.

1.5 Uninstallation

In order to uninstall/remove PiOSK from your system, run the cleanup.sh script as the user for whom PiOSK was installed:

sudo cleanup.sh

Note

By default PiOSK doesn't uninstall the system packages it installs as dependencies (i.e. git, jq, Node.js, wtype). The reason being, if they're force removed, then other packages (which have been installed since) that may also rely on them - will break. It's also because if you're going to reinstall or update PiOSK, then they'll have to be installed again. Uncomment the last section in cleanup.sh file if you really want to remove those packages.

2. Appendix

2.1 Assumptions

  1. You're using a Raspberry Pi (other SBCs may work, not tested)
  2. You're using "Raspberry Pi OS with desktop (32bit)" (other distros may work, not tested)
  3. You've applied proper OS customizations & the Pi is able to access the internet (required for setup)
  4. You're using Wayland with Wayfire compositor (probably the only "must have" during runtime)
  5. You're using the same user to run the setup script for whom desktop auto login is configured
  6. You're not using port 80 on the Pi to run some other web server (apart from PiOSK dashboard)

2.2 Recommendations

  • Choose the right Raspberry Pi
    • Pi Zero 2 W is perhaps the most fitting RPi for the job
    • Older Pi Zero (1.3, Zero W etc.) may struggle running Chromium
    • A Pi4 or Pi5 may be overkill, but shouldn't face any issue
  • Choose the right display/screen
    • Not related to PiOSK, but resolution matters for browser based kiosk mode
      • Browser content window resolutions smaller than 1024px*600px may not be ideal
      • Different websites have different responsive rules & handle small screens differently
    • Also be mindful of LCD burn-in if displaying very limited number of static pages
    • DSI displays are more discreet, but they may require driver setup to work properly
  • Choose the right OS Image
    • Use the Pi imager tool for flashing
    • If your Pi has 4GB or less memory, choose 32bit image
    • Use Debian Bookworm based images (for better Wayland/Wayfire support)
  • Take necessary steps to harden security
    • Disable touchscreen unless required
    • Disable ports that aren't required
    • Disable unused network interfaces, remote SSH
    • Enable OverlayFS to write protect storage
  • Discover the Pi on the network
    • Set hostname (e.g. piosk) so you can call it by hostname without needing to hunt for IP
    • The dashboard's URL with the hostname & IP address is shown at the end of the install script
    • Or, run angry IP scanner or login to router/switch to discover the Pi's IP the hard way

Footnotes

  1. That is to say... boot into runlevel 5 or graphical.target and not in console mode — it's NOT a recommendation to use the 3.4GB boot image named Raspberry Pi OS Desktop

  2. For some reason, if that's NOT it, and you hit a snag... please report an issue & give us some context to replicate & debug it.

  3. PiOSK uses port 80 on the Pi to serve the web dashboard. If you're planning to use the Pi for other purposes, make sure to avoid port collision.

piosk's People

Contributors

debloper avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

piosk's Issues

Easy Mode instructions

Easy Mode:

  1. set pi to book from USB
  2. hold shift to start the network installer
  3. When booted, plug in USB stick
  4. choose 32bit
  5. modify the settings before apply
  6. success

Auto Mouse Hiding Enhancement

Seems like this would be a good option here:

https://raspberrypi.stackexchange.com/questions/145382/remove-hide-mouse-cursor-when-idle-on-rasbperry-pi-os-bookworm/145390#145390

2

I've had success with installing the hideaway plugin for Interception Tools using the script below.

Adapted from https://forums.raspberrypi.com/viewtopic.php?t=358285#p2176499

#!/bin/bash
# hide mouse in wayland raspbian

sudo apt install -y interception-tools interception-tools-compat
sudo apt install -y cmake
cd ~
git clone https://gitlab.com/interception/linux/plugins/hideaway.git
cd hideaway
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
sudo cp /home/$USER/hideaway/build/hideaway /usr/bin
sudo chmod +x /usr/bin/hideaway

cd ~
wget https://raw.githubusercontent.com/ugotapi/wayland-pagepi/main/config.yaml
sudo cp /home/$USER/config.yaml /etc/interception/udevmon.d/config.yaml
sudo systemctl restart udevmon

Avoid nodejs installation by distributing single executable binary package

Currently we're using nodejs to run the backend service for the web GUI. There are a couple of inconveniences to this:

  • Lack of first party debian aptitude package
  • Best effort (but still clumsy) third party installation script
  • Necessitates dependency installation during setup process
  • Which necessitates dependency version locking management
  • Because entrypoint script takes argument (node index), it needs to be wrapped in a script to be used as ExecStart command

I think this can be much more effective, efficient and elegant by using Node.js SEA. We can use GitHub actions to generate the package, and in future, instead of cloning the entire repo, hopefully we'll just need to download the release binary.

Update docs and version bump major

Add update and uninstall docs.

Update major version due to breaking changes between the new setup and cleanup script having breaking changes compared to previous approach.

Thankfully we can still to do that before too many users start using it. Let's make sure people start with v2 - so that at least there's a cleanup script.

Releasing v1 without cleanup or update script was plain stupid, with severe lack of foresight.

Implement a clean update mechanism

This utility is meant to be "set it and forget it", so no one is forced to update if they're satisfied with how it's working for them. It shouldn't even have to have automated updates, notifying annoying them to update.

But at least for the ones who want to stay at the bleeding edge & update, it shouldn't be more than just one or two scripts to run.

Implement API integration for the UX

The frontend needs to

  • Be able to fetch & parse list of URLs
  • Generate elements for URL list from HTML templates
  • Serialize the updated list of URLs and POST request to update config

Fake API or assume defaults until backend is ready.

Write a setup script to automate the process

The setup script needs to:

  • install dependencies: wtype, git, nodejs,
  • clone this repo in ~/ directory
  • setup kiosk mode autostart
  • setup web service daemon

Basically if the user performs the following steps, the rest should be handled by PiOSK after that:

  1. flash OS image, boot up the SBC and ssh into it
  2. update software packages
  3. enable autologin
  4. run this setup script

Restore backup config file

If an backup config exists (from prior uninstallation or otherwise), use that instead of sample config).

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.