SignageHTML/documentation.md

SL Transport Departures Display System Documentation

System Overview

This is a comprehensive digital signage system designed to display transit departures and weather information. 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. Departures Component - Displays transit departure information
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
• departures.js - Transit departure display 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
• 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 / 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
• 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

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. Departures Component (departures.js)

The Departures component displays transit departure information from the SL Transport API.

Key Features:

• Real-time Updates: Fetches departure data periodically
• Multiple Sites: Supports displaying departures from multiple transit stops
• Grouped Display: Groups departures by line and direction
• Countdown Timers: Shows time until departure

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

   • Look for JavaScript errors in console

4. 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:

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:

window.weatherManager = new WeatherManager({
    latitude: YOUR_LATITUDE,
    longitude: YOUR_LONGITUDE
});

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    |
|  - Departures       |       |                      |
|  - 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, Departures)
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.