Skip to content

Commit 2c74acb

Browse files
blink-zeroblink-zero
committed
Add KIOSK.md documentation and improve README.md with Quick Start section
1 parent 035bb4a commit 2c74acb

File tree

2 files changed

+240
-5
lines changed

2 files changed

+240
-5
lines changed

‎KIOSK.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# PowerPulse Kiosk Mode
2+
3+
This document provides detailed information about the PowerPulse Kiosk Mode feature, which allows you to display UPS monitoring information on dedicated screens without requiring authentication.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Accessing Kiosk Mode](#accessing-kiosk-mode)
9+
- [URL Parameters](#url-parameters)
10+
- [View Modes](#view-modes)
11+
- [Setting Up a Dedicated Display](#setting-up-a-dedicated-display)
12+
- [Security Considerations](#security-considerations)
13+
- [Troubleshooting](#troubleshooting)
14+
15+
## Overview
16+
17+
Kiosk Mode is designed for displaying UPS monitoring information on dedicated screens in server rooms, network operations centers (NOCs), or other locations where you want to have a continuous display of UPS status. Key features include:
18+
19+
- **No Authentication Required**: Accessible without logging in
20+
- **Auto-rotation**: Automatically cycles through UPS systems
21+
- **Multi-view Mode**: Display all UPS systems at once
22+
- **Dark Theme**: Easy on the eyes for continuous display
23+
- **Responsive Design**: Works on various screen sizes
24+
- **No Session Timeout**: Runs continuously without logging out
25+
- **URL Parameters**: Customize the display via URL parameters
26+
27+
## Accessing Kiosk Mode
28+
29+
Kiosk Mode is accessible via the `/kiosk` URL path. For example:
30+
31+
```
32+
http://your-powerpulse-server/kiosk
33+
```
34+
35+
By default, this will display all UPS systems in single-view mode with auto-rotation.
36+
37+
## URL Parameters
38+
39+
You can customize the Kiosk Mode display using the following URL parameters:
40+
41+
### Multi-view Mode
42+
43+
To enable multi-view mode (displaying all UPS systems at once):
44+
45+
```
46+
http://your-powerpulse-server/kiosk?multi=true
47+
```
48+
49+
To switch back to single-view mode:
50+
51+
```
52+
http://your-powerpulse-server/kiosk?multi=false
53+
```
54+
55+
### UPS Selection
56+
57+
To display only specific UPS systems, use the `ups` parameter with a comma-separated list of UPS IDs:
58+
59+
```
60+
http://your-powerpulse-server/kiosk?ups=1,3,5
61+
```
62+
63+
This will only display UPS systems with IDs 1, 3, and 5.
64+
65+
### Combining Parameters
66+
67+
You can combine parameters to customize the display further:
68+
69+
```
70+
http://your-powerpulse-server/kiosk?multi=true&ups=1,3,5
71+
```
72+
73+
This will display UPS systems with IDs 1, 3, and 5 in multi-view mode.
74+
75+
## View Modes
76+
77+
### Single-view Mode
78+
79+
In single-view mode, Kiosk Mode displays one UPS system at a time and automatically rotates between them every 10 seconds. This mode provides detailed information about each UPS system, including:
80+
81+
- Battery charge percentage
82+
- Runtime remaining
83+
- Load percentage
84+
- Input/output voltage
85+
- Battery voltage
86+
- Temperature (if available)
87+
88+
You can manually navigate between UPS systems using the dots at the bottom of the screen.
89+
90+
### Multi-view Mode
91+
92+
In multi-view mode, Kiosk Mode displays all UPS systems at once in a grid layout. This mode provides a summary of each UPS system, including:
93+
94+
- Battery charge percentage
95+
- Runtime remaining
96+
- Load percentage
97+
- Input/output voltage (if available)
98+
99+
You can toggle between single-view and multi-view modes using the button in the top-right corner of the screen.
100+
101+
## Setting Up a Dedicated Display
102+
103+
For optimal use of Kiosk Mode on a dedicated display:
104+
105+
1. **Use a dedicated device**: A Raspberry Pi, small form-factor PC, or smart TV with a web browser works well
106+
2. **Set up auto-start**: Configure the browser to start automatically and load the Kiosk Mode URL
107+
3. **Disable screen saver and power saving**: Ensure the display stays on continuously
108+
4. **Use full-screen mode**: Configure the browser to run in full-screen mode (F11 in most browsers)
109+
5. **Disable browser UI**: Hide address bar, tabs, and other browser UI elements
110+
6. **Consider display rotation**: For portrait displays, consider using CSS to rotate the display
111+
112+
### Example: Setting up Kiosk Mode on a Raspberry Pi
113+
114+
1. Install Raspberry Pi OS
115+
2. Install Chromium browser
116+
3. Create an autostart file:
117+
```
118+
mkdir -p ~/.config/autostart
119+
nano ~/.config/autostart/kiosk.desktop
120+
```
121+
4. Add the following content:
122+
```
123+
[Desktop Entry]
124+
Type=Application
125+
Name=PowerPulse Kiosk
126+
Exec=chromium-browser --noerrdialogs --disable-infobars --kiosk http://your-powerpulse-server/kiosk
127+
```
128+
5. Save and reboot
129+
130+
## Security Considerations
131+
132+
While Kiosk Mode does not require authentication, it only provides read-only access to UPS status information. No sensitive configuration data or user information is exposed through Kiosk Mode.
133+
134+
However, you should consider the following security aspects:
135+
136+
- Kiosk Mode is designed for use on internal networks
137+
- If your PowerPulse instance is exposed to the internet, consider using a reverse proxy with IP restrictions for the `/kiosk` path
138+
- The data shown in Kiosk Mode is the same as what authenticated users see on the dashboard
139+
- No administrative actions can be performed through Kiosk Mode
140+
141+
## Troubleshooting
142+
143+
### Kiosk Mode Not Loading
144+
145+
If Kiosk Mode is not loading:
146+
147+
1. Verify that the PowerPulse server is running
148+
2. Check that you can access the main PowerPulse login page
149+
3. Verify that the URL is correct (http://your-powerpulse-server/kiosk)
150+
4. Check browser console for any JavaScript errors
151+
5. Ensure your browser supports modern JavaScript features
152+
153+
### UPS Systems Not Showing
154+
155+
If UPS systems are not showing in Kiosk Mode:
156+
157+
1. Verify that UPS systems are configured in PowerPulse
158+
2. Check that the NUT server is running and accessible
159+
3. Verify that UPS systems are visible in the main dashboard when logged in
160+
4. If using the `ups` parameter, ensure the UPS IDs are correct
161+
162+
### Auto-rotation Not Working
163+
164+
If auto-rotation is not working in single-view mode:
165+
166+
1. Ensure you have more than one UPS system configured
167+
2. Check that you are not in multi-view mode
168+
3. Verify that JavaScript is enabled in your browser
169+
4. Check browser console for any errors
170+
171+
### Display Issues
172+
173+
If you experience display issues:
174+
175+
1. Try a different browser
176+
2. Ensure your browser is up to date
177+
3. Check that JavaScript is enabled
178+
4. Try clearing browser cache and cookies
179+
5. Adjust the browser zoom level if needed

‎README.md‎

Lines changed: 61 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,61 @@ PowerPulse is a modern UPS (Uninterruptible Power Supply) monitoring dashboard i
3535
- **Responsive Design**: Works on desktop, tablet, and mobile devices
3636
- **Dark Mode Support**: Easy on the eyes during those late-night monitoring sessions
3737

38+
## Quick Start
39+
40+
Get up and running with PowerPulse in minutes:
41+
42+
### Using Docker (Recommended)
43+
44+
```bash
45+
# Create a directory for PowerPulse
46+
mkdir powerpulse && cd powerpulse
47+
48+
# Create a data directory for the server
49+
mkdir -p server/data
50+
51+
# Download the Docker Compose file
52+
wget https://raw.githubusercontent.com/blink-zero/powerpulse/v1.10.0/docker-compose.dockerhub.yml -O docker-compose.yml
53+
54+
# Download and configure the environment file
55+
wget https://raw.githubusercontent.com/blink-zero/powerpulse/v1.10.0/.env.example -O .env
56+
# Edit .env with your configuration
57+
58+
# Start PowerPulse
59+
docker-compose up -d
60+
```
61+
62+
Then open your browser and navigate to `http://localhost:3000` to access PowerPulse.
63+
64+
### Using Node.js
65+
66+
```bash
67+
# Clone the repository
68+
git clone https://github.com/blink-zero/powerpulse.git
69+
cd powerpulse
70+
71+
# Install dependencies
72+
npm run install-all
73+
74+
# Configure environment variables
75+
cp .env.example .env
76+
# Edit .env with your configuration
77+
78+
# Start the development server
79+
npm run dev
80+
```
81+
82+
Then open your browser and navigate to `http://localhost:3000` to access PowerPulse.
83+
84+
### First-time Setup
85+
86+
1. Create an admin account when prompted
87+
2. Configure your NUT server connection
88+
3. PowerPulse will automatically discover your UPS systems
89+
4. Start monitoring your UPS systems!
90+
91+
For more detailed instructions, see the [Installation](#installation) section below.
92+
3893
## Project Structure
3994

4095
```
@@ -139,12 +194,12 @@ You can also run PowerPulse directly from Docker Hub without cloning the reposit
139194

140195
3. Download the Docker Compose file:
141196
```
142-
wget https://raw.githubusercontent.com/blink-zero/powerpulse/v1.9.0/docker-compose.dockerhub.yml -O docker-compose.yml
197+
wget https://raw.githubusercontent.com/blink-zero/powerpulse/v1.10.0/docker-compose.dockerhub.yml -O docker-compose.yml
143198
```
144199

145200
4. Create an environment file:
146201
```
147-
wget https://raw.githubusercontent.com/blink-zero/powerpulse/v1.9.0/.env.example -O .env
202+
wget https://raw.githubusercontent.com/blink-zero/powerpulse/v1.10.0/.env.example -O .env
148203
# Edit .env with your configuration
149204
```
150205

@@ -204,11 +259,11 @@ You can also run PowerPulse directly from Docker Hub without cloning the reposit
204259
```
205260
# Edit your docker-compose.yml file and update the image tags
206261
# From:
207-
# image: blinkzero/powerpulse-server:1.8.3
208-
# image: blinkzero/powerpulse-client:1.8.3
209-
# To:
210262
# image: blinkzero/powerpulse-server:1.9.0
211263
# image: blinkzero/powerpulse-client:1.9.0
264+
# To:
265+
# image: blinkzero/powerpulse-server:1.10.0
266+
# image: blinkzero/powerpulse-client:1.10.0
212267
```
213268

214269
Alternatively, download the latest docker-compose file (replace X.Y.Z with the latest version):
@@ -329,6 +384,7 @@ This will generate 24 hours of simulated battery history data for all configured
329384
- [Server Documentation](server/README.md): Information about the backend API and architecture
330385
- [API Documentation](API.md): Complete reference for all API endpoints
331386
- [Docker Documentation](DOCKER.md): Detailed instructions for Docker setup and configuration
387+
- [Kiosk Mode Documentation](KIOSK.md): Comprehensive guide to using the Kiosk Mode feature
332388
- [Changelog](CHANGELOG.md): History of changes and version updates
333389

334390
## License

0 commit comments

Comments
 (0)