SignageHTML/README.md

SL Transport Departures Display

A modern digital signage system for displaying real-time transit departures and weather information. Perfect for Raspberry Pi-based information displays, kiosks, and public transport information boards.

Note

: Screenshots should be added to the screenshots/ directory. The application displays real-time transit departures in a modern, optimized layout.

Features

🚌 Real-Time Transit Information

• Multi-stop support: Display departures from up to 4 transit stops simultaneously
• Smart grouping: Departures grouped by line number with direction indicators
• Visual indicators:
  • Color-coded countdowns (green for "Now", red for <5 minutes, white for 5+ minutes)
  • Direction arrows showing bus/tram direction
  • Transport mode icons (Bus, Tram, Metro, Train, Ship)
• Accurate timing: Uses expected time from API to account for delays

🌤️ Weather Display

• Current weather conditions with icons
• Hourly forecast (8-hour outlook)
• Sunrise/sunset times
• Automatic dark mode based on time of day

⚙️ Flexible Configuration

• Screen orientations: Support for 0°, 90°, 180°, 270° rotations
• Landscape optimization: Automatic 4-column grid layout for wide screens
• Dark mode: Automatic, always on, or always off
• Custom backgrounds: Upload your own background images with adjustable opacity
• Map-based site selection: Visual map interface for selecting transit stops (no Swedish required!)

🎨 Modern Design

• Swedish color scheme (blue/yellow gradient clock banner)
• Compact ribbon-style clock with time and date on one line
• Optimized spacing and typography for readability
• Responsive design that adapts to screen size
• Smooth animations and visual effects

Screenshots

Main Display (Landscape Layout)

Screenshot: The system automatically optimizes for landscape orientation with a 4-column grid layout, maximizing screen real estate while maintaining readability. Add your screenshot to screenshots/landscape-layout.png.

Key Features Highlighted

• Clock Banner: Compact ribbon-style header with time and date
• Departure Cards: Color-coded boxes with transport icons, line numbers, and direction arrows
• Weather Widget: Fixed at bottom with current conditions and hourly forecast

Quick Start

Prerequisites

• Node.js (v12 or higher)
• Modern web browser with CSS3 support
• Internet connection for API access

Installation

1. Clone the repository

   git clone http://192.168.68.53:3000/kyle/SignageHTML.git
   cd SignageHTML
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   Create a .env file in the root directory (or copy from .env.example if it exists):

   PORT=3002
   OPENWEATHERMAP_API_KEY=your_openweathermap_api_key_here
   DEFAULT_LATITUDE=59.3293
   DEFAULT_LONGITUDE=18.0686
   DEFAULT_LOCATION_NAME=Stockholm
   

   Get your OpenWeatherMap API key from openweathermap.org.

4. Start the server

   npm start
   # or for development with auto-reload:
   npm run dev
   

5. Open in browser Navigate to: http://localhost:3002

The server will start on port 3002 by default (or the port specified in .env). The application will automatically load and begin fetching transit and weather data.

Configuration

Adding Transit Stops

Method 1: Search by Name

1. Click the gear icon (⚙️) in the top-right corner
2. Go to the "Content" tab
3. Enter a stop name in the search box (e.g., "Ambassaderna")
4. Click "Search" and select from results

Method 2: Select from Map

1. Click "Select from Map" button
2. Navigate to your location on the map
3. Click on any transit stop marker
4. Click "Select This Stop" in the popup

Method 3: Manual Entry

1. Click "Add Site Manually"
2. Enter the Site Name and Site ID
3. Enable/disable the site as needed

Environment Variables

The application uses environment variables for configuration. Create a .env file in the root directory:

# Server port (default: 3002)
PORT=3002

# OpenWeatherMap API key (required for weather features)
OPENWEATHERMAP_API_KEY=your_api_key_here

# Default location coordinates (Stockholm, Sweden)
DEFAULT_LATITUDE=59.3293
DEFAULT_LONGITUDE=18.0686
DEFAULT_LOCATION_NAME=Stockholm

Note: The OpenWeatherMap API key is injected into the HTML at runtime by the server. You can also configure the weather location through the settings panel in the UI.

Screen Orientation

The system supports multiple orientations:

• Normal (0°): Standard portrait/landscape
• Vertical (90°): Rotated 90° clockwise
• Upside Down (180°): Rotated 180°
• Vertical Reverse (270°): Rotated 270°
• Landscape (2-column): Optimized landscape layout

Select your orientation from the settings panel (⚙️ → Display → Screen Orientation).

Raspberry Pi Setup

For a dedicated display on Raspberry Pi, we've included a setup script that:

1. Installs Node.js if needed
2. Creates a systemd service to run the server on boot
3. Sets up Chromium to launch in kiosk mode on startup
4. Disables screen blanking and screensaver
5. Creates a desktop shortcut for manual launch

Setup Instructions

# Clone the repository
git clone http://192.168.68.53:3000/kyle/SignageHTML.git
cd SignageHTML

# Make the setup script executable
chmod +x scripts/raspberry-pi-setup.sh

# Run the setup script as root
sudo ./scripts/raspberry-pi-setup.sh

# Reboot to apply all changes
sudo reboot

After reboot, the display will automatically start in kiosk mode.

Architecture

The system consists of the following components:

1. Node.js Server (server.js)

   • Handles API proxying (SL Transport API, OpenWeatherMap)
   • Serves static files from public/ directory
   • Manages site configuration
   • Route handlers organized in server/routes/:
     • departures.js - Transit departure data endpoints
     • sites.js - Site search and nearby sites
     • config.js - Configuration management endpoints

2. Configuration Manager (public/js/components/ConfigManager.js)

   • Manages system settings and UI customization
   • Handles site selection and map integration
   • Persists settings to localStorage

3. Weather Component (public/js/components/WeatherManager.js)

   • Displays weather data from OpenWeatherMap
   • Manages dark mode based on sunrise/sunset
   • Shows hourly forecasts

4. Clock Component (public/js/components/Clock.js)

   • Shows current time and date
   • Swedish locale formatting
   • Updates every second

5. Departures Component (public/js/components/DeparturesManager.js)

   • Fetches and displays transit departure information
   • Groups departures by line number
   • Handles direction indicators and timing

6. Utilities (public/js/utils/)

   • constants.js - Application constants and configuration
   • logger.js - Centralized logging utility

7. Main UI (index.html)

   • Responsive layout with multiple orientation support
   • CSS Grid-based landscape optimization
   • Modern styling with animations
   • External CSS in public/css/:
     • main.css - Base styles, dark mode, orientation styles
     • components.css - Component-specific styles

API Integration

SL Transport API

The system uses the SL Transport API to fetch real-time departure information:

• Endpoint: https://transport.integration.sl.se/v1/sites/{siteId}/departures
• Returns: Real-time departure data with expected times, directions, and line information

OpenWeatherMap API

Weather data is fetched from OpenWeatherMap:

• Requires API key (configured in weather.js)
• Provides current conditions and hourly forecasts
• Used for dark mode timing calculations

For detailed API response documentation, see docs/API_RESPONSE_DOCUMENTATION.md.

UI Settings

The gear icon (⚙️) in the top-right corner opens the settings panel with tabs for:

Display

• Screen orientation selection
• Dark mode settings (Automatic/Sunset-Sunrise, Always On, Always Off)

Appearance

• Background image URL or local file upload
• Background opacity slider

Content

• Transit site management
  • Search for stops by name
  • Select from interactive map
  • Add manually
  • Enable/disable sites
• Option to combine departures going in the same direction

Options

• Additional system preferences

Settings are automatically saved to localStorage and persist across sessions.

Recent Updates

Version 1.1.0 - Landscape Optimization

• ✅ Optimized 4-column grid layout for landscape screens
• ✅ Replaced text labels with transport mode icons
• ✅ Reduced box sizes for better space efficiency
• ✅ Increased font sizes after space optimization
• ✅ Changed default box color to blue with white line numbers
• ✅ Fixed TRAM display to correctly show from API
• ✅ Improved time display formatting and prevented cutoff
• ✅ Compact ribbon-style clock banner

Troubleshooting

Common Issues

1. Server won't start

   • Check if port 3002 is already in use: netstat -ano | findstr :3002
   • Ensure Node.js is installed correctly: node --version
   • Check server logs for error messages

2. No departures displayed

   • Verify internet connection
   • Check server console for API errors
   • Ensure site IDs are correct and enabled
   • Verify sites are configured in settings

3. Weather data not loading

   • Check OpenWeatherMap API key in .env file
   • Ensure .env file exists in the root directory
   • Verify the API key is correctly set: OPENWEATHERMAP_API_KEY=your_key_here
   • Restart the server after changing .env file
   • Verify internet connection
   • Look for errors in browser console (F12)
   • Check API key quota/limits on openweathermap.org

4. Map not loading

   • Ensure internet connection is active
   • Check browser console for Leaflet.js errors
   • Verify OpenStreetMap tile access

5. Layout issues

   • Clear browser cache and refresh (Ctrl+F5)
   • Check browser console for CSS errors
   • Verify screen orientation setting matches physical setup

Development

Project Structure

SignageHTML/
├── index.html              # Main HTML file
├── server.js               # Node.js server entry point
├── server/
│   └── routes/             # API route handlers
│       ├── departures.js   # Departure data endpoints
│       ├── sites.js        # Site search endpoints
│       └── config.js       # Configuration endpoints
├── public/                 # Static assets
│   ├── css/
│   │   ├── main.css        # Base styles, dark mode, orientations
│   │   └── components.css  # Component-specific styles
│   └── js/
│       ├── main.js         # Application initialization
│       ├── components/     # Component classes
│       │   ├── Clock.js
│       │   ├── ConfigManager.js
│       │   ├── DeparturesManager.js
│       │   └── WeatherManager.js
│       └── utils/          # Utility modules
│           ├── constants.js
│           └── logger.js
├── config/
│   └── sites.json          # Persistent site configuration
├── docs/
│   └── API_RESPONSE_DOCUMENTATION.md  # API response documentation
├── scripts/
│   └── raspberry-pi-setup.sh  # Raspberry Pi deployment script
├── package.json            # Node.js dependencies
├── .env                    # Environment variables (create from .env.example)
├── .env.example            # Environment variable template
├── archive/                # Archived legacy files (see archive/README.md)
└── README.md               # This file

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License

Acknowledgements

• SL Transport API - Real-time transit departure information
• OpenWeatherMap - Weather data and forecasts
• OpenStreetMap - Map tiles for site selection
• Leaflet.js - Interactive map functionality

Support

For issues, questions, or contributions, please use the Gitea repository:

• Repository: http://192.168.68.53:3000/kyle/SignageHTML
• Issues: http://192.168.68.53:3000/kyle/SignageHTML/issues

---

Built for Stockholm public transport 🚌🚊