KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #open-source #agent-skills #ai #dsh-plugin #llm #windows

ESP32-P4-NINA-Display

★ 45 Open GitHub ↗

NINA Astrophotography display using Waveshare ESP32-P4-WIFI6-Touch-LCD-4B

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">
  <img src="images/logo.png" alt="logo" height="40" style="vertical-align: middle;"> ESP32-P4 NINA Display
</h1>

A touchscreen dashboard for [N.I.N.A. astrophotography software](https://nighttime-imaging.eu/), built for the **Waveshare ESP32-P4-WIFI6-Touch-LCD-4B** (720x720). It polls the [ninaAPI Advanced plugin](https://github.com/christian-photo/ninaAPI) over HTTP and WebSocket to show real-time session data: exposure arcs, guiding RMS, filter status, sequence progress, power draw, and more. Monitor up to three separate N.I.N.A. instances from one device. Beyond NINA it also runs a Spotify Now Playing screen, AllSky environmental panel, clock with weather and 3D moon phase, and GOES/solar imagery.

## Table of Contents

- [Screenshots](#screenshots)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [First-Time Setup](#first-time-setup)
- [Security](#security)
- [Display Interface](#display-interface)
- [Features](#features)
- [Web API](#web-api)

---

## Screenshots

### Device Display

### Toast Notifications

### Spotify Album Art Display

<table align="center">
  <tr>
    <td align="center" colspan="2"><img src="images/Spotify_desk.jpg" alt="Spotify on two devices" width="480"></td>
  </tr>
  <tr>
    <td align="center"><img src="images/Spotify_overlay.jpg" alt="Spotify overlay with controls" width="480"></td>
    <td align="center"><img src="images/Spotify_overlay_minimal.jpg" alt="Spotify minimal overlay" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>With controls</em></td>
    <td align="center"><em>Controls hidden</em></td>
  </tr>
</table>

### Clock & Weather

<table align="center">
  <tr>
    <td align="center"><img src="images/clock-face.jpg" alt="Clock Face with Weather" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>Clock face with weather data and forecast bars</em></td>
  </tr>
</table>

### Moon Phase Display

Real-time 3D rendered Moon with accurate phase, libration, and sub-solar lighting. Optional glow halo and starfield background.

<table align="center">
  <tr>
    <td align="center"><img src="images/moon.jpg" alt="Moon phase" width="480"></td>
    <td align="center"><img src="images/moon_glow.jpg" alt="Moon with glow halo" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>Default</em></td>
    <td align="center"><em>Glow halo</em></td>
  </tr>
  <tr>
    <td align="center"><img src="images/moon_stars.jpg" alt="Moon with starfield" width="480"></td>
    <td align="center"><img src="images/moon_glow_stars.jpg" alt="Moon with glow and starfield" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>Starfield background</em></td>
    <td align="center"><em>Glow and starfield</em></td>
  </tr>
</table>

### Web Configuration UI

Every setting is managed from the on-device web UI, organized into tabs.

<table align="center">
  <tr>
    <td align="center"><img src="images/settings_nina.jpg" alt="N.I.N.A. instance settings" width="480"></td>
    <td align="center"><img src="images/settings_display.jpg" alt="Display and page navigation settings" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>N.I.N.A. instances (hosts, filter colors, RMS/HFR thresholds)</em></td>
    <td align="center"><em>Display (theme, home page, auto-cycle, page rotation)</em></td>
  </tr>
  <tr>
    <td align="center"><img src="images/settings_behavior.jpg" alt="Behavior settings" width="480"></td>
    <td align="center"><img src="images/settings_system.jpg" alt="System settings" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>Behavior (power, polling, notifications)</em></td>
    <td align="center"><em>System (network, MQTT, firmware, auth)</em></td>
  </tr>
  <tr>
    <td align="center"><img src="images/settings_clock.jpg" alt="Clock and weather settings" width="480"></td>
    <td align="center"><img src="images/settings_spotify.jpg" alt="Spotify settings" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>Clock &amp; Weather (provider, location, units)</em></td>
    <td align="center"><em>Spotify (client ID, playback options)</em></td>
  </tr>
  <tr>
    <td align="center"><img src="images/settings_allsky.jpg" alt="AllSky settings" width="480"></td>
    <td align="center"><img src="images/settings_image.jpg" alt="Image display settings" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>AllSky (connection, per-quadrant field mappings)</em></td>
    <td align="center"><em>Image Display (GOES / Moon / Solar / custom URL)</em></td>
  </tr>
  <tr>
    <td align="center"><img src="images/settings_logs.jpg" alt="Logs tab" width="480"></td>
    <td align="center"><img src="images/settings_backup.jpg" alt="Backup and restore tab" width="480"></td>
  </tr>
  <tr>
    <td align="center"><em>Logs (live console output, crash log, download)</em></td>
    <td align="center"><em>Backup (export / restore configuration)</em></td>
  </tr>
  <tr>
    <td align="center" colspan="2"><img src="images/settings_api.jpg" alt="HTTP API reference tab" width="480"></td>
  </tr>
  <tr>
    <td align="center" colspan="2"><em>API (in-UI reference for every HTTP endpoint)</em></td>
  </tr>
</table>

---

## Prerequisites

### Hardware

- **[Waveshare ESP32-P4-WIFI6-Touch-LCD-4B](https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm?sku=31416)** — currently the only tested board. The layout is tuned for its 720x720 display.
- **[3D Printed Stand](https://www.thingiverse.com/thing:7321463)** (optional) — a printable stand for the display, designed by [@chicago925](https://github.com/chicago925) ([#116](https://github.com/chvvkumar/ESP32-P4-NINA-Display/issues/116)).
- **[3D Printed Mount](https://www.printables.com/model/1784141-waveshare-esp32-p4-wifi6-touch-lcd-4b-mount)** (optional) — a printable desk mount for the display, designed by the project author.

### Software (on the N.I.N.A. PC)

- [N.I.N.A. Nighttime Imaging 'N' Astronomy](https://nighttime-imaging.eu/)
- [ninaAPI Advanced plugin](https://github.com/christian-photo/ninaAPI) by Christian Palm — install it from N.I.N.A.'s plugin manager, then enable it. Required for operation.

---

## Installation

Download the latest factory binary from the [Releases page](../../releases). No build environment is needed: use a Chromium-based browser and the [ESP Web Flasher](https://espressif.github.io/esptool-js/), then flash `nina-display-factory.bin` at address `0x0000`. Each release includes step-by-step flashing instructions.

> **Note:** If your board warns about outdated `esp-hosted` co-processor firmware, flash `network_adapter.bin` at address `0x0000` to the ESP32-C6 coprocessor. A pre-built binary is in the [`firmware/`](firmware/) folder.

After the first flash, further updates can be delivered over the air from GitHub releases (System tab in the web UI).

---

## First-Time Setup

On first boot (or whenever WiFi is not connected), the device broadcasts a WiFi access point named **`NINA-DISPLAY`** (password: `12345678`). Connect to it from your phone or laptop and open `http://192.168.4.1`.

Set at minimum:

1. **WiFi credentials** — your observatory/home network where NINA runs.
2. **NINA host(s)** — the IP or hostname of each NINA PC (e.g. `192.168.1.50`). The device builds the full API URL automatically. Up to three instances.

Save. The device reconnects to your network and starts polling immediately.

> Once connected to your network, the config AP is disabled to reduce radio interference. If the WiFi connection drops, the AP reappears so you can reconfigure.

---

## Security

The web interface is protected by a session-cookie login (default password: `changeme123!`; there is no username). **Change it on first boot:** web UI, System tab, Admin Password section.

- Authentication is enabled by default and covers all configuration, reboot, factory reset, OTA, and secret-returning endpoints. Sessions expire after 12 hours.
- Transport is HTTP, not HTTPS. Treat your LAN segment as the trust boundary.
- Secrets (WiFi/MQTT passwords, Spotify client ID) are redacted as `********` in API responses regardless of the auth setting.
- Authentication can be disabled (System tab). When off, every endpoint is open to anyone on the LAN, including reboot, factory reset, and OTA. Use only on trusted networks.

---

## Display Interface

The **Summary page** shows a card for each configured NINA instance: name, active filter, target, progress, RMS, HFR, and time to meridian flip. Tap a card to jump to that instance's full dashboard.

Each **instance page** is a 720x720 bento-box grid: header (target, profile, WiFi, connection dot), sequence, an animated exposure arc colored by the active filter, filter/timing, guiding RMS, image stats (HFR, star count), mount flip time, session time, and power (voltage, current, watts, dew-heater PWM). A pulsing header dot marks an active API request; grey means NINA is unreachable, and the page dims after prolonged stale data.

### Touch interactions

Every section on an instance page is tappable:

| Tap area | Opens |
|---|---|
| Header | Full-screen JPEG preview of the last captured image (tap to dismiss) |
| Sequence box | Sequence detail overlay (container, step, exposure counts) |
| Exposure arc | Camera & weather overlay (camera name, temperature, dew point, humidity, pressure) |
| Filter label (arc center) | Filter wheel overlay (current and available filters) |
| RMS box | RMS history graph (up to 500 points, RA/Dec/Total, threshold lines) |
| HFR box (short tap) | HFR history graph (up to 500 points, threshold lines) |
| HFR box (long press) | Autofocus overlay (V-curve, focus position) |
| Flip time box | Mount overlay (RA/Dec, altitude, azimuth, meridian flip state) |
| Session time box | Session statistics overlay (total exposures, imaging time, target altitude, dawn) |
| Stars box | Image statistics overlay (star count, HFR, FWHM, eccentricity, SNR) |
| Power row | Jump back to Summary page |

### On-device settings

Swipe to the **Settings** page for on-device configuration in four tabs: Display (theme, brightness), Behavior (auto-rotate, sleep, timeouts), Nodes (NINA hosts), and System. The web UI exposes the full set of options. The **System Info** page reports IP, WiFi, CPU, memory, PSRAM, uptime, and task count.

---

## Features

### Navigation

Swipe left/right to cycle pages, or press the **BOOT button** (GPIO 35) to advance. **Auto-cycle** rotates through a selectable, reorderable list of pages on a configurable interval with fade, slide, or instant transitions, and can skip disconnected instances. The **Home Page** setting picks the page the display settles on; when it is a NINA instance, the display also returns there whenever that instance is online. Page-indicator dots at the bottom mark the NINA instance pages.

### Multi-Instance Support

Add up to three NINA hosts. Only the active (visible) page gets full ~2-second polling; background instances get a slower heartbeat (default 30 s). When the Summary page is active, all instances are polled at full rate.

### Themes & Filter Colors

Nine built-in dark themes, selectable in the Display tab; changes apply instantly without a reboot. A color-brightness slider (0-100%) uniformly dims all theme colors for dark-site use. Filter colors are set per-instance as hex values, and new filters reported by NINA are added automatically with a default color. RMS and HFR threshold colors are configurable, so out-of-range values shift green to amber to red.

### Voice Alerts

The firmware speaks alerts through the onboard speaker. Announcements are assembled from pre-rendered voice clips, so no network or cloud service is involved at playback time.

Two alert sources feed the voice system:

- **Threshold breaches**: guiding RMS, HFR, and the ASCOM safety monitor, evaluated per instance. A breach is announced once on entry, for example "Warning, NINA one, HFR, two point five, above limit". A Brief Announcements option shortens this to "NINA one, HFR, is above set threshold". Re-announcement while the value stays out of range is controlled by a configurable repeat interval, and the alert re-arms once the value recovers below 95% of the threshold.
- **Session events**: each of the twelve event categories (equipment connects and disconnects, sequence, focuser, mount, meridian flip, guider, safety, error, profile, dome, flat device) has an independent voice toggle next to its pop-up toggle. Equipment events name the device, for example "NINA two, Camera, disconnected". A 30-second per-category cooldown suppresses bursts. Disconnects, meridian flip, safety, and error are enabled by default; the remaining categories are opt-in.

Controls in the Behavior tab: master enable, volume, alert-type selection, brief mode, repeat interval, and per-category toggles with preview buttons that play each announcement on the device. Each NINA node card has a voice mute for that instance. A separate Startup Sound toggle plays a short jingle when the display finishes booting. Voice alerts are disabled by default.

### Custom Voice Clips

Replace any of the 47 built-in clips from the **Voice Clips** tab in the web UI (Device menu, after Behavior): the chime, the startup jingle, the "NINA one/two/three" identity clips, sentence fragments, digits, equipment names, and event phrases. Upload mp3, m4a, wav, or ogg files and the browser converts them to the required 16 kHz, 16-bit, mono PCM before upload; .pcm files upload unchanged. Clips are stored on the device's SPIFFS storage partition, survive firmware updates, and apply immediately. Each row has a play button that plays the active clip on the device speaker, and a reset control that restores the built-in recording. **Reset All** and a factory reset both remove every custom clip. Record a rig name over the "NINA one" identity clip to tell side-by-side devices apart by ear. The first boot after updating to this firmware prepares the storage partition in the background for about a minute; uploads are rejected with a message until preparation finishes.

Limits: 10 seconds per clip, 15 seconds for the startup jingle, 4 MB total for all custom clips.

### Spotify

The display doubles as a full-screen Spotify Now Playing screen with album art, playback controls, progress bar, and scrolling track info. NINA and AllSky polling pause while the Spotify page is active to free bandwidth for album-art downloads.

Setup (Spotify tab in the web UI):

1. Create a free app at [developer.spotify.com](https://developer.spotify.com).
2. Set its redirect URI to `http://127.0.0.1:8000/callback`.
3. Paste the **Client ID** into the Spotify tab and **Save**.
4. Click **Login with Spotify** and approve access.
5. Spotify redirects to a "can't connect" page: copy the full URL from the address bar and paste it into the Redirect URL field.

### MQTT / Home Assistant

Point MQTT at your broker to publish the device's own state via Home Assistant auto-discovery: screen brightness and text brightness (dimmable light entities), a reboot button, and an uptime sensor. Home Assistant can then set brightness or reboot the device, for example dimming during a dark-site session. NINA session data is not published over MQTT.

### AllSky, Weather, and Imagery

- **AllSky** — a four-quadrant environmental panel (thermal, sky quality, ambient, power) fed from an AllSky API with configurable field mappings and thresholds.
- **Weather** — OpenWeatherMap, Open-Meteo, or Weather Underground data on the clock page.
- **Image Display** — full-screen GOES satellite, NASA SDO/SOHO solar imagery, or a custom image URL.

---

## Web API

The device serves an HTTP API on port 80. A full, always-current reference for every endpoint (with copy-paste `curl` examples) lives in the web UI's **API tab**.

The `/api/screenshot` endpoint captures a live JPEG of the current display using the ESP32-P4's hardware JPEG encoder:

```bash
curl -o screenshot.jpg http://<device-ip>/api/screenshot
```

ESP32-P4-NINA-Display

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README