Initial import: clean snapshot from /home/olafn/infoscreen-dev (2025-10-25)
This commit is contained in:
RobbStarkAustria
274
src/README.md
Normal file
274
src/README.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# Infoscreen Client - Raspberry Pi Development
|
||||
|
||||
A presentation system client for Raspberry Pi that communicates with a server via MQTT to display presentations, videos, and web content in kiosk mode.
|
||||
|
||||
## Features
|
||||
|
||||
- 📡 MQTT communication with server
|
||||
- 📥 Automatic file downloads (presentations, videos)
|
||||
- 🖥️ **Automated display management** with dedicated Display Manager
|
||||
- 🎯 Event-driven content switching (presentations, videos, web pages)
|
||||
- ⏰ Time-based event scheduling with automatic start/stop
|
||||
- 🔄 Graceful application transitions (LibreOffice, Chromium, VLC)
|
||||
- 📸 Screenshot capture for dashboard monitoring
|
||||
- 👥 Group-based content management
|
||||
- 💖 Heartbeat monitoring
|
||||
|
||||
## Quick Setup
|
||||
|
||||
### 1. Flash Raspberry Pi OS
|
||||
- Use **Raspberry Pi OS (64-bit) with Desktop**
|
||||
- Enable SSH and configure WiFi in Pi Imager
|
||||
- Boot Pi and connect to network
|
||||
|
||||
### 2. Install Development Environment
|
||||
```bash
|
||||
# Run on your Raspberry Pi:
|
||||
curl -sSL https://raw.githubusercontent.com/RobbStarkAustria/infoscreen_client_2025/main/pi-dev-setup.sh | bash
|
||||
```
|
||||
|
||||
### 3. Configure MQTT Broker
|
||||
```bash
|
||||
cd ~/infoscreen-dev
|
||||
nano .env
|
||||
# Update MQTT_BROKER=your-server-ip
|
||||
```
|
||||
|
||||
### 4. Test Setup
|
||||
```bash
|
||||
./scripts/test-mqtt.sh # Test MQTT connection
|
||||
./scripts/test-screenshot.sh # Test screenshot capture
|
||||
./scripts/test-presentation.sh # Test presentation tools
|
||||
```
|
||||
|
||||
### 5. Start Development
|
||||
```bash
|
||||
# Terminal 1: Start MQTT client (receives events)
|
||||
./scripts/start-dev.sh
|
||||
|
||||
# Terminal 2: Start Display Manager (controls screen)
|
||||
./scripts/start-display-manager.sh
|
||||
|
||||
# Or use interactive menu:
|
||||
./dev-workflow.sh
|
||||
```
|
||||
|
||||
**Important**: You need **both** processes running:
|
||||
- `simclient.py` - Handles MQTT communication and writes events
|
||||
- `display_manager.py` - Reads events and controls display software
|
||||
|
||||
See [DISPLAY_MANAGER.md](DISPLAY_MANAGER.md) for detailed documentation.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Daily Development
|
||||
```bash
|
||||
cd ~/infoscreen-dev
|
||||
./dev-workflow.sh # Interactive menu with all options
|
||||
```
|
||||
|
||||
**Menu Options:**
|
||||
1. Start development client (MQTT)
|
||||
2. Start Display Manager
|
||||
3. View live logs
|
||||
4. Test Display Manager
|
||||
5. Test screenshot capture
|
||||
6. Test MQTT connection
|
||||
7. Test presentation tools
|
||||
8. Git status and sync
|
||||
9. Restart systemd services
|
||||
10. Monitor system resources
|
||||
11. Open tmux session
|
||||
|
||||
### Remote Development (Recommended)
|
||||
```bash
|
||||
# From your main computer:
|
||||
# Add to ~/.ssh/config
|
||||
Host pi-dev
|
||||
HostName YOUR_PI_IP
|
||||
User pi
|
||||
|
||||
# Connect with VS Code
|
||||
code --remote ssh-remote+pi-dev ~/infoscreen-dev
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
~/infoscreen-dev/
|
||||
├── .env # Configuration
|
||||
├── src/ # Source code (this repository)
|
||||
│ ├── simclient.py # MQTT client (event receiver)
|
||||
│ ├── display_manager.py # Display controller (NEW!)
|
||||
│ ├── current_event.json # Current active event
|
||||
│ ├── DISPLAY_MANAGER.md # Display Manager documentation
|
||||
│ └── config/ # Client UUID and group ID
|
||||
├── venv/ # Python virtual environment
|
||||
├── presentation/ # Downloaded presentation files
|
||||
├── screenshots/ # Screenshot captures
|
||||
├── logs/ # Application logs
|
||||
│ ├── simclient.log # MQTT client logs
|
||||
│ └── display_manager.log # Display Manager logs
|
||||
└── scripts/ # Development helper scripts
|
||||
├── start-dev.sh # Start MQTT client
|
||||
├── start-display-manager.sh # Start Display Manager (NEW!)
|
||||
├── test-display-manager.sh # Test display events (NEW!)
|
||||
├── test-mqtt.sh # Test MQTT connection
|
||||
├── test-screenshot.sh # Test screenshot capture
|
||||
└── test-presentation.sh # Test presentation tools
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables (.env)
|
||||
```bash
|
||||
# Development settings
|
||||
ENV=development
|
||||
DEBUG_MODE=1
|
||||
LOG_LEVEL=DEBUG
|
||||
|
||||
# MQTT Configuration
|
||||
MQTT_BROKER=192.168.1.100 # Your MQTT server IP
|
||||
MQTT_PORT=1883
|
||||
|
||||
# Intervals (seconds)
|
||||
HEARTBEAT_INTERVAL=10 # Heartbeat frequency
|
||||
SCREENSHOT_INTERVAL=30 # Screenshot capture frequency
|
||||
DISPLAY_CHECK_INTERVAL=5 # Display Manager event check frequency
|
||||
```
|
||||
|
||||
## MQTT Topics
|
||||
|
||||
### Client → Server
|
||||
- `infoscreen/discovery` - Client registration
|
||||
- `infoscreen/{client_id}/heartbeat` - Regular heartbeat
|
||||
- `infoscreen/{client_id}/dashboard` - Screenshot + status
|
||||
|
||||
### Server → Client
|
||||
- `infoscreen/{client_id}/discovery_ack` - Registration acknowledgment
|
||||
- `infoscreen/{client_id}/group_id` - Group assignment
|
||||
- `infoscreen/events/{group_id}` - Event messages with content
|
||||
|
||||
## Event Format
|
||||
|
||||
The Display Manager supports three event types:
|
||||
|
||||
**Presentation Event:**
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"title": "Company Overview",
|
||||
"start": "2025-10-01 08:00:00",
|
||||
"end": "2025-10-01 18:00:00",
|
||||
"presentation": {
|
||||
"files": [
|
||||
{
|
||||
"url": "https://server/presentations/slide.pptx",
|
||||
"name": "slide.pptx"
|
||||
}
|
||||
],
|
||||
"slide_interval": 10,
|
||||
"auto_advance": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Web Page Event:**
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"title": "Dashboard",
|
||||
"start": "2025-10-01 08:00:00",
|
||||
"end": "2025-10-01 18:00:00",
|
||||
"web": {
|
||||
"url": "https://dashboard.example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Video Event:**
|
||||
```json
|
||||
{
|
||||
"id": 3,
|
||||
"title": "Promo Video",
|
||||
"start": "2025-10-01 08:00:00",
|
||||
"end": "2025-10-01 18:00:00",
|
||||
"video": {
|
||||
"url": "https://server/videos/promo.mp4",
|
||||
"loop": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [DISPLAY_MANAGER.md](DISPLAY_MANAGER.md) for complete event documentation.
|
||||
|
||||
## Debugging
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
tail -f ~/infoscreen-dev/logs/simclient.log
|
||||
```
|
||||
|
||||
### MQTT Debugging
|
||||
```bash
|
||||
# Subscribe to all infoscreen topics
|
||||
mosquitto_sub -h YOUR_BROKER_IP -t "infoscreen/+/+"
|
||||
|
||||
# Publish test event
|
||||
mosquitto_pub -h YOUR_BROKER_IP -t "infoscreen/events/test-group" -m '{"web":{"url":"https://google.com"}}'
|
||||
```
|
||||
|
||||
### System Service (Optional)
|
||||
```bash
|
||||
# Enable automatic startup
|
||||
sudo systemctl enable infoscreen-dev
|
||||
sudo systemctl start infoscreen-dev
|
||||
|
||||
# View service logs
|
||||
sudo journalctl -u infoscreen-dev -f
|
||||
```
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
- **Raspberry Pi 4 or 5** (recommended Pi 5 for best performance)
|
||||
- **SSD storage** (much faster than SD card)
|
||||
- **Display** connected via HDMI
|
||||
- **Network connection** (WiFi or Ethernet)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Display Issues
|
||||
```bash
|
||||
export DISPLAY=:0
|
||||
echo $DISPLAY
|
||||
```
|
||||
|
||||
### Screenshot Issues
|
||||
```bash
|
||||
# Test screenshot manually
|
||||
scrot ~/test.png
|
||||
# Check permissions
|
||||
sudo usermod -a -G video pi
|
||||
```
|
||||
|
||||
### MQTT Connection Issues
|
||||
```bash
|
||||
# Test broker connectivity
|
||||
telnet YOUR_BROKER_IP 1883
|
||||
# Check firewall
|
||||
sudo ufw status
|
||||
```
|
||||
|
||||
## Development vs Production
|
||||
|
||||
This setup is optimized for **development**:
|
||||
- ✅ Fast iteration (edit → save → restart)
|
||||
- ✅ Native debugging and logging
|
||||
- ✅ Direct hardware access
|
||||
- ✅ Remote development friendly
|
||||
|
||||
For **production deployment** with multiple clients, consider containerization for easier updates and management.
|
||||
|
||||
## License
|
||||
|
||||
This project is part of the infoscreen presentation system for educational/research purposes.
|
||||
Reference in New Issue
Block a user