🖥️ Simple Work Instruction Display

"A lightweight, low-resource application for displaying work instruction images directly from removable storage."

🚀 Quick Start • ✨ Features • 🔄 How It Works • 📁 Project Structure • 🛡️ Hardware Display Extension • 🤝 Contributing

---

🚀 Quick Start

Get the display running in under a minute using uv:

# 1. Install uv and project dependencies in development mode
pip install uv && uv pip install -e .

# 2. Run the display application pointing to your storage media
python src/main.py --storage-path /media/pi/work_instructions --display-time 15

⚙️ Advanced Configuration

You can configure the display loop parameters directly from the command line:

Argument	Shortcut	Description	Default
--storage-path	-s	Absolute path to the directory containing work instruction images.	/media/pi/work_instructions
--display-time	-t	Display duration in seconds per image before cycling.	30

Default settings can also be modified in src/config.py.

---

✨ Features

Feature	Description
📂 Removable Storage	Automatically reads steps directly from SD cards, USB flash drives, or custom folders.
⏱ Configurable Timing	Adjustable step intervals to fit assembly lines, tutorials, or packaging stations.
🔌 Offline-First	Zero network connectivity required. Fully air-gapped design for high-reliability shop floors.
🐌 Minimalist Footprint	Low memory and CPU usage, optimized for budget hardware (e.g. Raspberry Pi Zero).
🛡️ Integrity Verification	Pre-validates image files via Pillow to prevent screen freeze on corrupt data.

---

🔄 How It Works

🔍 View Execution Cycle Diagram

The application runs a continuous execution loop to dynamic-scan and cycle files, allowing media to be hot-swapped seamlessly during operation:

sequenceDiagram
    participant Storage as Removable Storage
    participant App as Main Loop (main.py)
    participant Pillow as Image Validator
    participant Display as Output Handler

    rect rgb(100, 100, 100)
        Note over App, Storage: Cycle Begins
        App->>Storage: Scan directory for image formats (.jpg, .png, etc.)
        Storage-->>App: Return list of files
        loop Integrity Check
            App->>Pillow: Verify image structure & integrity
            Pillow-->>App: Valid / Invalid file status
        end
        App->>Display: Log active step & dimensions
        App->>App: Sleep for specified interval (t seconds)
    end

Loading

---

📁 Project Structure

simple-work-instruction-display/
├── src/
│   ├── main.py          # Core application loop and directory scanner
│   └── config.py        # Default configurations and supported format list
├── test/                # Test suites & unit tests
├── docs/
│   └── HARDWARE_INTEGRATION.md  # Guide to extending the renderer with Pygame/LCD
├── scripts/
│   ├── create_samples.py        # Generates test images for verification
│   ├── install.sh               # Install helper script for Raspberry Pi OS
│   └── work_instruction_display.service # systemd service template
├── pyproject.toml       # Python metadata and tool specifications
└── uv_usage.md          # Guide to managing environment/testing with uv

---

🖌️ Hardware Display Extension

Note

The default display_image implementation in src/main.py is a simulated reference implementation. It validates file headers and logs metadata but does not draw directly to the physical display screen.

For rendering instructions onto actual screens (e.g., HDMI/SPI display panels connected to a Raspberry Pi), see docs/HARDWARE_INTEGRATION.md.

📖 View Pygame Extension Summary

To subclass the display and blit frames using Pygame, follow this architecture:

import pygame
from PIL import Image
from src.main import WorkInstructionDisplay

class HardwareWorkInstructionDisplay(WorkInstructionDisplay):
    def _init_display(self):
        pygame.init()
        self.display_surface = pygame.display.set_mode((800, 600))
        
    def display_image(self, image_path):
        with Image.open(image_path) as img:
            img = img.convert('RGB')
            # Convert PIL Image to Pygame surface and refresh display
            pygame_image = pygame.image.frombuffer(img.tobytes(), img.size, img.mode)
            self.display_surface.blit(pygame_image, (0, 0))
            pygame.display.flip()

---

📦 Systemd Service Deployment

🛠️ Setup Autostart on Boot

To run the application continuously as a background service on a Raspberry Pi:

1. Copy the systemd service template:

   sudo cp scripts/work_instruction_display.service /etc/systemd/system/

2. Reload the systemd daemon:

   sudo systemctl daemon-reload

3. Enable the service to launch automatically at startup:

   sudo systemctl enable work_instruction_display.service

4. Start the service immediately:

   sudo systemctl start work_instruction_display.service

Use scripts/install.sh to fully automate the directory preparation, virtual environment construction, and module verification. See scripts/install.sh for details.

---

🗺️ Roadmap

• Support multi-display setups
• Add native SPI display screen drivers
• Implement manual forward/backward navigation overrides
• Add smooth image transition animations (e.g., crossfade)
• Support video instruction clips (.mp4, .gif)

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Commit your changes: git commit -m 'Add some amazing feature'.
4. Push to the branch: git push origin feature/amazing-feature.
5. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.