Initial commit: Digital signage system for transit departures, weather, and news ticker
This commit is contained in:
295
documentation.md
Normal file
295
documentation.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# SL Transport Departures Display System Documentation
|
||||
|
||||
## System Overview
|
||||
|
||||
This is a comprehensive digital signage system designed to display transit departures, weather information, and news tickers. The system is built with a modular architecture, making it easy to maintain and extend. It's specifically designed to work well on a Raspberry Pi for dedicated display purposes.
|
||||
|
||||
## Architecture
|
||||
|
||||
The system consists of the following components:
|
||||
|
||||
1. **Node.js Server** - Handles API proxying and serves static files
|
||||
2. **Configuration Manager** - Manages system settings and UI customization
|
||||
3. **Weather Component** - Displays weather data and manages dark mode
|
||||
4. **Clock Component** - Shows current time and date
|
||||
5. **Ticker Component** - Displays scrolling news from RSS feeds
|
||||
6. **Main UI** - Responsive layout with multiple orientation support
|
||||
|
||||
## File Structure
|
||||
|
||||
- `index.html` - Main HTML file containing the UI structure and inline JavaScript
|
||||
- `server.js` - Node.js server for API proxying and static file serving
|
||||
- `config.js` - Configuration management module
|
||||
- `weather.js` - Weather display and dark mode management
|
||||
- `clock.js` - Time and date display
|
||||
- `ticker.js` - News ticker component
|
||||
|
||||
## Detailed Component Documentation
|
||||
|
||||
### 1. Node.js Server (server.js)
|
||||
|
||||
The server component acts as a proxy for external APIs and serves the static files for the application.
|
||||
|
||||
#### Key Features:
|
||||
|
||||
- **Port**: Runs on port 3002
|
||||
- **API Proxying**:
|
||||
- `/api/departures` - Proxies requests to SL Transport API
|
||||
- `/api/rss` - Proxies and parses RSS feeds
|
||||
- **Error Handling**: Provides structured error responses
|
||||
- **Static File Serving**: Serves HTML, CSS, JavaScript, and image files
|
||||
- **CORS Support**: Allows cross-origin requests
|
||||
|
||||
#### API Endpoints:
|
||||
|
||||
- `GET /api/departures` - Returns transit departure information
|
||||
- `GET /api/rss` - Returns parsed RSS feed items
|
||||
- `GET /` or `/index.html` - Serves the main application
|
||||
- `GET /*.js|css|png|jpg|jpeg|gif|ico` - Serves static assets
|
||||
|
||||
#### Implementation Details:
|
||||
|
||||
The server handles malformed JSON responses from the SL Transport API by implementing custom JSON parsing and fixing. It also provides fallback data when API requests fail.
|
||||
|
||||
### 2. Configuration Manager (config.js)
|
||||
|
||||
The Configuration Manager handles all system settings and provides a UI for changing them.
|
||||
|
||||
#### Key Features:
|
||||
|
||||
- **Screen Orientation**: Controls display rotation (0°, 90°, 180°, 270°, landscape)
|
||||
- **Dark Mode**: Automatic (based on sunrise/sunset), always on, or always off
|
||||
- **Background Image**: Custom background with opacity control
|
||||
- **Ticker Speed**: Controls the scrolling speed of the news ticker
|
||||
- **Settings Persistence**: Saves settings to localStorage
|
||||
- **Configuration UI**: Modal-based interface with live previews
|
||||
|
||||
#### Configuration Options:
|
||||
|
||||
- `orientation`: Screen orientation (`normal`, `vertical`, `upsidedown`, `vertical-reverse`, `landscape`)
|
||||
- `darkMode`: Dark mode setting (`auto`, `on`, `off`)
|
||||
- `backgroundImage`: URL or data URL of background image
|
||||
- `backgroundOpacity`: Opacity value between 0 and 1
|
||||
- `tickerSpeed`: Scroll speed in seconds for one complete cycle
|
||||
|
||||
#### Implementation Details:
|
||||
|
||||
The ConfigManager class creates a gear icon button that opens a modal dialog for changing settings. It applies settings immediately and dispatches events to notify other components of changes.
|
||||
|
||||
### 3. Weather Component (weather.js)
|
||||
|
||||
The Weather component displays current weather conditions, forecasts, and manages dark mode based on sunrise/sunset times.
|
||||
|
||||
#### Key Features:
|
||||
|
||||
- **Current Weather**: Temperature, condition, and icon
|
||||
- **Hourly Forecast**: Weather predictions for upcoming hours
|
||||
- **Sunrise/Sunset**: Calculates and displays sun times
|
||||
- **Dark Mode Control**: Automatically switches between light/dark based on sun position
|
||||
- **API Integration**: Uses OpenWeatherMap API
|
||||
- **Fallback Data**: Provides default weather data when API is unavailable
|
||||
|
||||
#### Implementation Details:
|
||||
|
||||
The WeatherManager class fetches data from OpenWeatherMap API and updates the UI. It calculates sunrise/sunset times and uses them to determine if dark mode should be enabled. It dispatches events when dark mode changes.
|
||||
|
||||
### 4. Clock Component (clock.js)
|
||||
|
||||
The Clock component displays the current time and date.
|
||||
|
||||
#### Key Features:
|
||||
|
||||
- **Time Display**: Shows current time in HH:MM:SS format
|
||||
- **Date Display**: Shows current date with weekday, month, day, and year
|
||||
- **Timezone Support**: Configured for Stockholm timezone
|
||||
- **Auto-Update**: Updates every second
|
||||
- **Optional Time Sync**: Can synchronize with WorldTimeAPI
|
||||
|
||||
#### Implementation Details:
|
||||
|
||||
The Clock class creates and updates time and date elements. It uses the browser's Date object with the specified timezone and formats the output using toLocaleTimeString and toLocaleDateString.
|
||||
|
||||
### 5. Ticker Component (ticker.js)
|
||||
|
||||
The Ticker component displays scrolling news or announcements at the bottom of the screen.
|
||||
|
||||
#### Key Features:
|
||||
|
||||
- **RSS Integration**: Fetches and displays items from RSS feeds
|
||||
- **Smooth Animation**: CSS-based scrolling with configurable speed
|
||||
- **Fallback Content**: Provides default items when RSS feed is unavailable
|
||||
- **Themed Display**: Red, white, and blue color scheme
|
||||
- **Orientation Support**: Properly rotates with screen orientation changes
|
||||
|
||||
#### Implementation Details:
|
||||
|
||||
The TickerManager class creates a fixed container at the bottom of the screen and populates it with items from an RSS feed. It uses CSS animations for scrolling and adjusts the animation direction based on screen orientation.
|
||||
|
||||
### 6. Main UI (index.html)
|
||||
|
||||
The main UI integrates all components and provides responsive layouts for different screen orientations.
|
||||
|
||||
#### Key Features:
|
||||
|
||||
- **Responsive Design**: Adapts to different screen sizes and orientations
|
||||
- **Dark Mode Support**: Changes colors based on dark mode setting
|
||||
- **Departure Cards**: Displays transit departures with line numbers, destinations, and times
|
||||
- **Weather Widget**: Shows current conditions and forecast
|
||||
- **Auto-Refresh**: Periodically updates departure information
|
||||
|
||||
#### Implementation Details:
|
||||
|
||||
The HTML file contains the structure and styling for the application. It initializes all components and sets up event listeners for updates. The JavaScript in the file handles fetching and displaying departure information.
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### Prerequisites:
|
||||
|
||||
- Node.js installed
|
||||
- Internet connection for API access
|
||||
- Browser with CSS3 support
|
||||
|
||||
### Installation Steps:
|
||||
|
||||
1. Clone or download all files to a directory
|
||||
2. Run `node server.js` to start the server
|
||||
3. Access the application at `http://localhost:3002`
|
||||
|
||||
### Raspberry Pi Setup:
|
||||
|
||||
1. Install Node.js on Raspberry Pi
|
||||
2. Copy all files to a directory on the Pi
|
||||
3. Set up auto-start for the server:
|
||||
```
|
||||
# Create a systemd service file
|
||||
sudo nano /etc/systemd/system/sl-departures.service
|
||||
|
||||
# Add the following content
|
||||
[Unit]
|
||||
Description=SL Departures Display
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/bin/node /path/to/server.js
|
||||
WorkingDirectory=/path/to/directory
|
||||
Restart=always
|
||||
User=pi
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
4. Enable and start the service:
|
||||
```
|
||||
sudo systemctl enable sl-departures
|
||||
sudo systemctl start sl-departures
|
||||
```
|
||||
5. Configure Raspberry Pi to auto-start Chromium in kiosk mode:
|
||||
```
|
||||
# Edit autostart file
|
||||
mkdir -p ~/.config/autostart
|
||||
nano ~/.config/autostart/kiosk.desktop
|
||||
|
||||
# Add the following content
|
||||
[Desktop Entry]
|
||||
Type=Application
|
||||
Name=Kiosk
|
||||
Exec=chromium-browser --kiosk --disable-restore-session-state http://localhost:3002
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues:
|
||||
|
||||
1. **Server won't start**
|
||||
- Check if port 3002 is already in use
|
||||
- Ensure Node.js is installed correctly
|
||||
|
||||
2. **No departures displayed**
|
||||
- Verify internet connection
|
||||
- Check server console for API errors
|
||||
- Ensure the site ID is correct (currently set to 9636)
|
||||
|
||||
3. **Weather data not loading**
|
||||
- Check OpenWeatherMap API key
|
||||
- Verify internet connection
|
||||
- Look for errors in browser console
|
||||
|
||||
4. **Ticker not scrolling**
|
||||
- Check if RSS feed is accessible
|
||||
- Verify ticker speed setting is not set to 0
|
||||
- Look for JavaScript errors in console
|
||||
|
||||
5. **Screen orientation issues**
|
||||
- Ensure the content wrapper is properly created
|
||||
- Check for CSS conflicts
|
||||
- Verify browser supports CSS transforms
|
||||
|
||||
## Customization Guide
|
||||
|
||||
### Changing Transit Stop:
|
||||
|
||||
To display departures for a different transit stop, modify the API_URL in server.js:
|
||||
|
||||
```javascript
|
||||
const API_URL = 'https://transport.integration.sl.se/v1/sites/YOUR_SITE_ID/departures';
|
||||
```
|
||||
|
||||
### Changing Weather Location:
|
||||
|
||||
To display weather for a different location, modify the latitude and longitude in index.html:
|
||||
|
||||
```javascript
|
||||
window.weatherManager = new WeatherManager({
|
||||
latitude: YOUR_LATITUDE,
|
||||
longitude: YOUR_LONGITUDE
|
||||
});
|
||||
```
|
||||
|
||||
### Changing RSS Feed:
|
||||
|
||||
To display a different news source, modify the RSS_URL in server.js:
|
||||
|
||||
```javascript
|
||||
const RSS_URL = 'https://your-rss-feed-url.xml';
|
||||
```
|
||||
|
||||
### Adding Custom Styles:
|
||||
|
||||
Add custom CSS to the style section in index.html to modify the appearance.
|
||||
|
||||
## System Architecture Diagram
|
||||
|
||||
```
|
||||
+---------------------+ +----------------------+
|
||||
| | | |
|
||||
| Browser Interface |<----->| Node.js Server |
|
||||
| (index.html) | | (server.js) |
|
||||
| | | |
|
||||
+---------------------+ +----------------------+
|
||||
^ ^
|
||||
| |
|
||||
v v
|
||||
+---------------------+ +----------------------+
|
||||
| | | |
|
||||
| UI Components | | External APIs |
|
||||
| - Clock | | - SL Transport API |
|
||||
| - Weather | | - OpenWeatherMap |
|
||||
| - Ticker | | - RSS Feeds |
|
||||
| - Config Manager | | |
|
||||
+---------------------+ +----------------------+
|
||||
```
|
||||
|
||||
## Component Interaction Flow
|
||||
|
||||
1. User loads the application in a browser
|
||||
2. Node.js server serves the HTML, CSS, and JavaScript files
|
||||
3. Browser initializes all components (Clock, Weather, Config, Ticker)
|
||||
4. Components make API requests through the Node.js server
|
||||
5. Server proxies requests to external APIs and returns responses
|
||||
6. Components update their UI based on the data
|
||||
7. User can change settings through the Config Manager
|
||||
8. Settings are applied immediately and saved to localStorage
|
||||
|
||||
## Conclusion
|
||||
|
||||
This documentation provides a comprehensive overview of the SL Transport Departures Display System. With this information, you should be able to understand, maintain, and recreate the system if needed.
|
||||
Reference in New Issue
Block a user