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, the 04:00 daily reboot, security updates and agent updates are all handled 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.
  • Set the daily reboot time — every Pi reboots at 04:00 UK time by default (the cheapest insurance against a browser slowly eating memory). Pick another small-hours time or Off to disable it.
  • 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.

The Device card updates itself — every 30 seconds, and every 5 seconds while a command is queued — so badges like “Restarting the display…”, “Rebooting…” and “Updating…” clear by themselves once the Pi has picked the command up. If an online Pi hasn't picked a command up after 5 minutes the badge says “not picked up yet”.

The downloadable image at wemasjid.com/os is rebuilt automatically with every Pi software release (same URL), and a Pi flashed from an older image updates itself on its first quiet window.

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 by itself during the quiet window, 01:00–05:00 UK time — never while a hall is watching. It is the same path as Update software (~2–3 minutes, then the kiosk comes back), which still runs immediately when you press it. The card shows “Updating…” while it runs and “Up to date” when done; a failed install is recorded too, so support can see it. Agents too old to know about this are still pushed an update by the server.

  • Security updates (Debian security + Raspberry Pi archive) install automatically every day. They never reboot the Pi on their own — the daily reboot picks them up.
  • The Pi's hardware watchdog is on: if the board ever wedges, it reboots itself within seconds instead of showing a frozen clock.
  • Reload screens (Screens page) refreshes the display page on every TV of your masjid — Pi, Fire TV app or smart-TV browser — within a minute, waiting for any adhan, iqamah countdown or prayer to finish. TVs also pick up new WeMasjid releases by themselves within minutes of a deploy, with the same prayer-aware timing.
WeMasjid staff see the whole fleet on a Super Admin Devices page — online/offline, agent version, kiosk health, temperature, disk and the last update result for every Pi — and can update, reboot (a few at a time) or reload all screens at once.

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.