# Setting up a new Raspberry Pi screen

Everything on this page happens on the Pi itself. It takes about five minutes, most of which is
waiting for a download.

Mirrored at
<https://msvinstalls.blob.core.windows.net/ebes-appstore-client-linux/install-guide.md>


## Before you start

- **Raspberry Pi OS, 64-bit.** A Pi 4 or Pi 5. The Lite image is fine and is what these screens run —
  there is no need for a desktop.
- **On the network, and able to reach the internet.** The Pi downloads the agent from Azure and then
  talks to Central.
- **SSH on, and a user with `sudo`.** Set both up in Raspberry Pi Imager when you flash the card.
- **The screen plugged in and switched on before the Pi boots.** This matters more than it sounds —
  see *The picture is the wrong size* below.


## 1. Install the agent

SSH to the Pi and run:

```bash
curl -fsSL https://msvinstalls.blob.core.windows.net/ebes-appstore-client-linux/bootstrap.sh | sudo bash
```

You should see it download four files and finish with:

```
Done. Watch it register with:
  journalctl -u ebes-appstore.service -f
```

**This is the only thing you install by hand.** From here the media player, and the agent's own
updates, all arrive from Central.


## 2. Check it registered

```bash
journalctl -u ebes-appstore -n 20
```

Looking for:

```
Registered as client 132 (my-pi-hostname)
Connected to https://ebes-api-msv.azurewebsites.net
```

If you also see `Installing EBES.AppStore.Client.Linux <version>` and a restart, that is the agent
updating itself to whatever Central has published. That is correct, not a fault.

The device now appears in Central under **AppStore → Clients**, with Operating System `Linux`.


## 3. Send it the media player

In Central, assign **EBES.MediaPlayer.Linux** to the device.

The agent downloads it and sets the whole screen up on its own — service account, kiosk browser,
compositor, the NDI runtime, the lot. Nothing else is done by hand.

Watch it happen:

```bash
journalctl -u ebes-mediaplayer -f
```


## 4. Adopt the screen

The screen will show **"Device needs to be adopted"** and a long ID. In Central, go to
**Hardware → MediaPlayer**, find that ID in the unadopted list, give it a name, and adopt it.

Then give it a schedule, and it starts playing.


## If something is wrong

**Nothing on screen at all**
```bash
systemctl status ebes-mediaplayer
journalctl -u ebes-mediaplayer -n 50
```

**"Device needs to be adopted" never appears — it says "Not connected to server"**
The Pi cannot reach Central. Check the network, then check nothing on this screen is pointing it
somewhere else:
```bash
cat /var/lib/ebes-mediaplayer/appsettings.json
```
On a normal device that file is all comments and an empty `{}`. If there is an `InternalApiUrl` line
in it, that is where this screen is trying to connect — delete the line and restart:
```bash
sudo systemctl restart ebes-mediaplayer
```

**The screen is blank but the player is running**
The display was probably off or asleep when the Pi booted, so it read no EDID and picked a default
resolution — or output nothing. Reboot with the screen on. If the screen is on a long cable, a
splitter, or gets switched off overnight, pin the mode instead by adding this to the end of the line
in `/boot/firmware/cmdline.txt` and rebooting:
```
video=HDMI-A-1:1920x1080@60D
```
The `D` on the end is the important part: it forces the output on even with no screen detected.

**The picture is the wrong size**
Same cause, same fix.

**Nothing arrives after assigning the player in Central**
Check the agent is still connected:
```bash
journalctl -u ebes-appstore -n 20
```

**The device does not appear in Central at all**
Check the agent is running (`systemctl status ebes-appstore`) and that the Pi can reach the internet.


## Useful to know

| | |
|---|---|
| Agent | `/opt/ebes/AppStore/current` |
| Player | `/opt/ebes/MediaPlayer/current` |
| This screen's settings | `/var/lib/ebes-mediaplayer/appsettings.json` |
| Logs | `journalctl -u ebes-appstore` / `journalctl -u ebes-mediaplayer` |

**Never delete `/var/lib/ebes-mediaplayer/chrome`.** The screen's identity lives in it, and wiping it
makes the device come back as a new, unadopted screen that has to be re-adopted and re-scheduled.

Reinstalling the agent is safe — re-run the command at the top. It will not disturb a screen that is
already playing.