> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikselsystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnose and fix an offline screen

> Learn what causes a Piksel screen to go offline, how to identify the root cause, and the steps to restore a reliable connection.

When a screen appears as offline in your Piksel dashboard, it means the platform has stopped receiving heartbeat signals from the device. This guide explains what offline means, the most common causes, and how to work through a step-by-step diagnostic to get the screen back online.

<Note>
  Piksel marks a screen as offline when no heartbeat signal has been received from the device for approximately two minutes. The Piksel app on the Apple TV sends these signals automatically at regular intervals while running. Once signals resume, the screen status returns to online automatically — no manual intervention is needed.
</Note>

## What triggers an offline alert

If you have offline alerts enabled in your notification preferences, Piksel sends an email to the account owner as soon as a screen is marked offline. The alert includes the screen name, its assigned location, and the timestamp of the last heartbeat received.

Offline alerts are controlled by the `offline_alerts` preference in your account notification settings. This preference defaults to enabled.

## Common causes

* **Network interruption** — the Apple TV has lost its internet connection or cannot reach the Piksel backend.
* **App not running** — the Piksel app on the Apple TV was closed, crashed, or the device was restarted and the app did not relaunch automatically.
* **Pairing lost** — the display record was deleted or reset, so the device is no longer recognized by the platform.
* **Device sleeping** — the Apple TV entered a sleep or idle state that suspended the app's background processes.

## Diagnostic steps

<Steps>
  <Step title="Check the dashboard status">
    Open the Screens page in your Piksel dashboard and locate the affected screen. Confirm that its status shows as offline and note the last heartbeat timestamp if visible. This tells you when the device last successfully communicated with the platform.
  </Step>

  <Step title="Verify the Apple TV is powered on and connected to the network">
    At the physical location of the screen, confirm that the Apple TV is powered on and that the TV it is connected to is displaying output. Check that the Apple TV has a working internet connection by navigating to **Settings > Network** on the device and confirming a valid IP address and network name.
  </Step>

  <Step title="Confirm the Piksel app is running">
    On the Apple TV, navigate to the home screen and check whether the Piksel app is open. If it is not running, launch it. The app should begin sending heartbeats within moments of starting, and the dashboard status should update to online within approximately two minutes.

    <Tip>
      If the app appears to launch but the screen remains offline, force-quit the app and reopen it: press and hold the TV button on the Siri Remote to open the app switcher, swipe up on the Piksel app to close it, then relaunch from the home screen.
    </Tip>
  </Step>

  <Step title="Check for pairing status">
    In the Piksel dashboard, open the screen's detail page. If the screen shows as unpaired, the device needs to be re-paired. This can happen if the display record was deleted or if the Apple TV app was reinstalled.

    To re-pair:

    1. Open the Piksel app on the Apple TV. It will display a fresh 6-digit pairing code.
    2. In the Piksel dashboard, go to **Screens** and select **Pair a Screen**.
    3. Enter the 6-digit code shown on the Apple TV.
    4. Confirm the pairing. The screen will appear in your dashboard and begin sending heartbeats.

    <Warning>
      A pairing code only works once and only while the display is in an unpaired state. If the app is restarted on the Apple TV, a new code is generated. Always use the code currently shown on the device screen.
    </Warning>
  </Step>

  <Step title="Wait for the status to update">
    After the Apple TV app is running and connected, Piksel will receive the next heartbeat and automatically update the screen's status to online. This typically takes less than two minutes. You do not need to refresh or manually trigger anything in the dashboard — the update happens as soon as heartbeat signals resume.
  </Step>

  <Step title="Contact support if the issue persists">
    If the screen remains offline after confirming the app is running and the device is connected, there may be a deeper network or configuration issue. Check whether other Apple TVs on the same network are affected. If only one screen is offline, the issue is likely device-specific. Gather the screen name, last heartbeat timestamp, and any error messages from the Apple TV and reach out to Piksel support.
  </Step>
</Steps>