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.

![SL Transport Departures Display](screenshots/main-display.png)

> **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)
![Landscape Layout](screenshots/landscape-layout.png)

> **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**
   ```bash
   git clone http://192.168.68.53:3000/kyle/SignageHTML.git
   cd SignageHTML
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Configure environment variables**
   
   Create a `.env` file in the root directory (or copy from `.env.example` if it exists):
   ```bash
   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](https://openweathermap.org/api).

4. **Start the server**
   ```bash
   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:

```bash
# 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

```bash
# 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](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** 🚌🚊