WeMasjid
Docs — all pages

Raspberry Pi — WeMasjid OS

WeMasjid OS is a managed player: the Pi boots to a PIN, you link it to a screen from the dashboard, and rotation, Wi-Fi, daily reboots and updates are all driven remotely — no SSH, ever.

Supported hardware

  • Pi 4 or 5 — best for boards with video and heavy slides (~£50–80)
  • Pi 3B+ — fine for prayer boards
  • Pi Zero 2 W — cheapest (~£15); Wi-Fi only, no video slides
The original Pi Zero / Zero W is not supported — it's ARMv6 and Chromium doesn't run on it. Use a 3 A power supply and (on Pi 4/5) the HDMI 0 micro-HDMI port — the one next to the USB-C power socket.

Set up a new Pi

  1. Download the WeMasjid OS image: https://wemasjid.com/os/wemasjid-os.img.xz (also linked from Admin → Screens → Players & downloads).
  2. Flash it to a good SD card with Raspberry Pi Imager: Choose OS → Use custom and pick the downloaded file. Prefer it in the Imager's list instead? Run rpi-imager --repo https://wemasjid.com/os/imager.json.
  3. No Ethernet? Use Imager's OS customisation step to set Wi-Fi only (SSID + password + country, and locale if needed) — it's applied on first boot. Leave hostname/username/SSH off — the image manages those. Or skip this and use wemasjid.txt below.
  4. Plug in HDMI and power (Ethernet if you have it). First boot takes a couple of minutes, then the TV shows a device ID and a 6-digit PIN.
  5. In the dashboard either: Screens → Link a device and enter the PIN — or type it straight into Add screen → Device PIN to create the screen and link in one go. Already have a screen? Open it and use Connect → Raspberry Pi. The TV switches to your content within seconds.

The PIN rotates every 15 minutes for safety — if it changes while you're linking, just type the new one. The image supports Pi 5 natively (same file for every model).

Managing the Pi

Once linked, open the screen's page (Screens → the screen) — a Device card shows the Pi's model, IP, Wi-Fi network, CPU temperature, RAM use, uptime, and a Wi-Fi or Ethernet icon with an Online badge (in the screen header too). It lets you:

  • Set rotation — Landscape / Portrait (left or right) / Upside down
  • Set the resolution — Auto (1080p) or 4K where the TV offers it; the card shows the current mode (e.g. 1920×1080) and warns if the TV didn't offer 4K. 4K can feel sluggish on a Pi 4; a Pi 5 handles it fine.
  • Schedule a daily reboot (recommended, e.g. 04:00) or turn it off
  • Add/remove Wi-Fi networks — the Add dialog lists networks the Pi can actually see (strongest signal first), or pick Other / hidden network… to type one. Each saved network shows a status badge — Connected, In range, Wrong password, Not in range, Checking… — and a mistyped name gets a “Did you mean …?” hint when a lookalike SSID is nearby. Passwords are sent to the Pi and never shown again.
  • Restart display, Reboot, Update software and Unlink remotely — Unlink asks you to type the screen name so a stray click can't take a TV down.
Everything is pulled by the agent on the Pi, so the Pi can sit behind any NAT or firewall — it only needs outbound HTTPS to wemasjid.com.

Updates look after themselves

The agent checks in every 20 seconds. When a newer release exists the card shows “Update available” and the Pi installs it automatically within the hour — the same path as Update software (~2–3 minutes, then the kiosk comes back). The card shows “Updating…” while it runs, and “Up to date” when done. Agents too old to know about this are still pushed an update by the server.

Diagnostics

The Diagnostics panel on the Device card (edit access only) shows the agent's recent log and the raw NetworkManager state — connection list and the last Wi-Fi scan — exactly what you'd need to hand support. Passwords are never logged or shown.

Wi-Fi without Ethernet

For the very first boot on Wi-Fi, put a file called wemasjid.txt on the SD card's boot partition (visible from any computer after flashing):

WIFI_SSID=MyNetwork
WIFI_PSK=thepassword
WIFI_COUNTRY=GB

The agent applies it and renames the file to wemasjid.txt.applied — it still contains the password in plain text, so delete it once the Pi is online. Once linked, prefer adding networks from the dashboard — they survive reflashes.

Moving to another masjid or screen

Unlink device on the screen's page releases it: the Pi clears its screen code, goes back to showing a fresh PIN and can be linked again — by any masjid. To keep the same Pi but change screens, unlink and link it again to the new screen.

Troubleshooting

  • No PIN on screen — check HDMI and give it two minutes; the Pi shows the PIN as soon as the agent is up, even before it can reach the internet.
  • Picture sits in a corner / doesn't fill the TV — fixed in current releases; press Update software once on the Device card.
  • “Offline — reconnecting…” — the Pi can't reach the network at all: check the router/Ethernet, or fix Wi-Fi below.
  • “Waiting for the device to register…” — it's online but hasn't reached our servers yet; it sorts itself out.
  • “WeMasjid is having trouble (error n)” — a fault on our side, not yours; the Pi retries by itself.
  • PIN not recognised — it rotates every 15 minutes; re-check the TV. Also confirm the Pi has internet (Ethernet link lights, or the boot log line).
  • Wi-Fi won't connect — SSIDs are case-sensitive (“2.4Ghz” vs “2.4GHz”): open Add Wi-Fi network and pick the exact name from the scan list, and check the status badge — “Wrong password” means exactly that. The Pi is 2.4 GHz; many dual-band routers share one SSID across bands, but a 5 GHz-only network won't appear. Make sure Imager customisation sets a Wi-Fi country.
  • Linked but wrong orientation — set Rotation on the screen's Device card; it applies on the next poll.
  • Intermittent dropouts on Wi-Fi — wired Ethernet is the reliable fix; the dashboard shows which SSID the Pi is on.
The display caches the last good timetable and slides, so a Pi keeps showing correct times through internet outages and picks up changes within seconds once it's back.