EyeOn Logo

Kiosk Troubleshooting Guide

Comprehensive troubleshooting guide for common kiosk issues and maintenance procedures

Kiosk Troubleshooting

This troubleshooting guide provides solutions to common issues that may occur with the EyeOn Kiosk Application. From hardware problems to software glitches, this guide covers the most frequent issues and their resolutions.

The guide is organized by problem categories and includes step-by-step solutions, prevention tips, and escalation procedures for complex issues. Regular maintenance procedures are also included to help prevent common problems.

EyeOn Kiosk Application troubleshooting interface and diagnostic tools

EyeOn Kiosk Application - Troubleshooting and diagnostic tools

Common Issues

Frequently encountered problems and their solutions

Hardware Issues

Problems related to kiosk hardware components

Touch screen not responding

Symptoms:
  • •Touch input not registering on screen
  • •No visual feedback when touching screen
  • •Touch calibration appears off
  • •Partial touch screen response
Possible Causes:
  • •Loose USB connection to touch controller
  • •Touch screen driver issues
  • •Hardware failure of touch controller
  • •Calibration drift over time
Solutions:
  1. 1.Check USB connection to touch controller
  2. 2.Restart touch screen service: sudo systemctl restart touchscreen
  3. 3.Recalibrate touch screen using calibration tool
  4. 4.Update touch screen drivers if available
  5. 5.Check for physical damage to screen surface
Prevention Tips:
  • •Regular touch screen cleaning with appropriate materials
  • •Avoid using sharp objects on screen
  • •Regular calibration checks
  • •Proper cable management to prevent strain

Display issues or blank screen

Symptoms:
  • •Screen appears black or blank
  • •Distorted or garbled display
  • •Incorrect resolution or aspect ratio
  • •Flickering or unstable display
Possible Causes:
  • •Loose HDMI or DisplayPort connection
  • •Graphics driver issues
  • •Incorrect display settings
  • •Hardware failure of display or graphics card
Solutions:
  1. 1.Check HDMI/DisplayPort cable connections
  2. 2.Verify display is powered on and receiving signal
  3. 3.Check display settings: xrandr --query
  4. 4.Restart display manager: sudo systemctl restart gdm3
  5. 5.Update graphics drivers if available
  6. 6.Test with different display if possible
Prevention Tips:
  • •Secure cable connections with proper strain relief
  • •Use high-quality cables
  • •Regular display cleaning and maintenance
  • •Monitor display temperature and ventilation

Audio not working

Symptoms:
  • •No sound from speakers
  • •Distorted or low-quality audio
  • •Audio device not detected
  • •Volume controls not responding
Possible Causes:
  • •Audio driver issues
  • •Incorrect audio device selection
  • •Hardware failure of audio components
  • •Audio service not running
Solutions:
  1. 1.Check audio device selection in system settings
  2. 2.Test audio with: speaker-test -t wav -c 2
  3. 3.Restart audio service: sudo systemctl restart pulseaudio
  4. 4.Check audio cable connections
  5. 5.Update audio drivers if available
Prevention Tips:
  • •Regular audio system testing
  • •Proper audio cable management
  • •Monitor audio system health
  • •Keep audio drivers updated

Software Issues

Problems related to kiosk application and system software

Application won't start

Symptoms:
  • •Kiosk application fails to launch
  • •Error messages during startup
  • •Application crashes immediately
  • •Systemd service fails to start
Possible Causes:
  • •Configuration file errors
  • •Missing dependencies
  • •Permission issues
  • •API connection problems
  • •Corrupted application files
Solutions:
  1. 1.Check application logs: journalctl -u eyeon-kiosk -f
  2. 2.Validate configuration files: python -m json.tool config/api.json
  3. 3.Check file permissions: ls -la /opt/eyeon-kiosk/
  4. 4.Restart systemd service: sudo systemctl restart eyeon-kiosk
  5. 5.Reinstall application dependencies: cd /opt/eyeon-kiosk && npm install
  6. 6.Restore from backup if files are corrupted
Prevention Tips:
  • •Regular configuration validation
  • •Proper file permission management
  • •Regular dependency updates
  • •Configuration backup procedures

Content not updating

Symptoms:
  • •Store information appears outdated
  • •Promotions and events not showing
  • •Map changes not reflected
  • •Static content instead of dynamic updates
Possible Causes:
  • •API connection issues
  • •Invalid API credentials
  • •Network connectivity problems
  • •Content caching issues
  • •Portal CMS synchronization problems
Solutions:
  1. 1.Check API connectivity: curl -H 'Authorization: Bearer $API_KEY' $BASE_URL/health
  2. 2.Verify API credentials in configuration
  3. 3.Test network connectivity: ping -c 1 8.8.8.8
  4. 4.Clear content cache: rm -rf /opt/eyeon-kiosk/cache/*
  5. 5.Restart application to force content refresh
  6. 6.Check Portal CMS for content updates
Prevention Tips:
  • •Regular API connectivity monitoring
  • •Proper network configuration
  • •Regular content cache management
  • •API credential rotation procedures

Performance issues

Symptoms:
  • •Slow application response
  • •High CPU or memory usage
  • •Laggy touch interactions
  • •Slow content loading
Possible Causes:
  • •Insufficient system resources
  • •Memory leaks in application
  • •Inefficient content caching
  • •Background processes consuming resources
Solutions:
  1. 1.Monitor system resources: htop
  2. 2.Check memory usage: free -h
  3. 3.Restart application to clear memory leaks
  4. 4.Optimize content cache settings
  5. 5.Close unnecessary background processes
  6. 6.Check for system updates
Prevention Tips:
  • •Regular system resource monitoring
  • •Proper content cache configuration
  • •Regular application restarts
  • •System maintenance procedures

Network Issues

Problems related to network connectivity and API communication

No internet connectivity

Symptoms:
  • •Cannot access external websites
  • •API calls failing
  • •Content not updating
  • •Network interface shows no connection
Possible Causes:
  • •Network cable disconnected
  • •WiFi connection lost
  • •Router or switch issues
  • •DNS resolution problems
  • •Firewall blocking connections
Solutions:
  1. 1.Check network cable connections
  2. 2.Restart network interface: sudo systemctl restart networking
  3. 3.Check WiFi connection: iwconfig
  4. 4.Test DNS resolution: nslookup google.com
  5. 5.Check firewall settings: sudo ufw status
  6. 6.Restart network services: sudo systemctl restart NetworkManager
Prevention Tips:
  • •Redundant network connections
  • •Regular network monitoring
  • •Proper cable management
  • •Network configuration backup

API connection timeouts

Symptoms:
  • •Slow API responses
  • •Connection timeout errors
  • •Intermittent API failures
  • •High latency to Portal CMS
Possible Causes:
  • •Network congestion
  • •API server issues
  • •Firewall or proxy problems
  • •DNS resolution delays
  • •Incorrect timeout settings
Solutions:
  1. 1.Check network latency: ping api.eyeonllc.com
  2. 2.Test API endpoint directly: curl -w '@curl-format.txt' $API_URL
  3. 3.Adjust timeout settings in configuration
  4. 4.Check proxy settings if applicable
  5. 5.Contact API provider for server status
  6. 6.Implement retry logic in application
Prevention Tips:
  • •Appropriate timeout configuration
  • •Network quality monitoring
  • •Redundant API endpoints
  • •Regular API health checks

Diagnostic Tools

Built-in and command-line tools for troubleshooting kiosk issues:

System Status Check

Comprehensive system health check

Command:sudo systemctl status eyeon-kiosk
Output:

Shows service status, recent logs, and error messages

Usage:

Use when application won't start or behaves unexpectedly

Application Logs

View real-time application logs

Command:journalctl -u eyeon-kiosk -f
Output:

Real-time log output showing errors and warnings

Usage:

Monitor application behavior and identify error patterns

Network Connectivity Test

Test network connectivity and API access

Command:curl -H 'Authorization: Bearer $API_KEY' $BASE_URL/health
Output:

API response status and timing information

Usage:

Verify API connectivity and response times

System Resource Monitor

Monitor CPU, memory, and disk usage

Command:htop
Output:

Real-time system resource usage display

Usage:

Identify performance bottlenecks and resource issues

Touch Screen Test

Test touch screen functionality

Command:xinput test-xi2 --root
Output:

Touch events and coordinates

Usage:

Verify touch screen is working and calibrated correctly

Display Information

Check display configuration and status

Command:xrandr --query
Output:

Display resolution, refresh rate, and connection status

Usage:

Verify display settings and troubleshoot display issues

Network Interface Status

Check network interface configuration

Command:ip addr show
Output:

Network interface status and IP configuration

Usage:

Verify network connectivity and configuration

Disk Space Check

Check available disk space

Command:df -h
Output:

Disk usage and available space

Usage:

Ensure sufficient disk space for application operation

Maintenance Procedures

Regular maintenance tasks to prevent issues and ensure optimal performance:

Daily Maintenance

Daily

Tasks:

  • •Check application status and logs
  • •Verify content updates are working
  • •Clean touch screen surface
  • •Check network connectivity
  • •Monitor system resources

Commands:

  1. 1.sudo systemctl status eyeon-kiosk
  2. 2.curl -H 'Authorization: Bearer $API_KEY' $BASE_URL/health
  3. 3.htop
  4. 4.ping -c 1 8.8.8.8

Weekly Maintenance

Weekly

Tasks:

  • •Review application logs for errors
  • •Test all major application features
  • •Check for system updates
  • •Verify backup systems
  • •Clean system files and logs

Commands:

  1. 1.journalctl -u eyeon-kiosk --since '1 week ago'
  2. 2.sudo apt update && sudo apt list --upgradable
  3. 3.sudo systemctl status eyeon-kiosk
  4. 4.sudo find /var/log -name '*.log' -mtime +7 -delete

Monthly Maintenance

Monthly

Tasks:

  • •Update application to latest version
  • •Review and update configuration
  • •Test disaster recovery procedures
  • •Clean hardware components
  • •Review performance metrics

Commands:

  1. 1.cd /opt/eyeon-kiosk && git pull && npm install
  2. 2.sudo systemctl restart eyeon-kiosk
  3. 3.sudo apt upgrade -y
  4. 4.sudo reboot

Quarterly Maintenance

Quarterly

Tasks:

  • •Complete hardware inspection
  • •Review security settings
  • •Test all backup and recovery procedures
  • •Evaluate performance and optimization
  • •Update documentation and procedures

Commands:

  1. 1.sudo systemctl stop eyeon-kiosk
  2. 2.sudo cp -r config/ backups/config-$(date +%Y%m%d)/
  3. 3.sudo systemctl start eyeon-kiosk
  4. 4.sudo systemctl status eyeon-kiosk

Emergency Procedures

Critical procedures for handling emergency situations:

Application Complete Failure

When the kiosk application completely stops working

Steps:

  1. 1.Check system status: sudo systemctl status eyeon-kiosk
  2. 2.Review error logs: journalctl -u eyeon-kiosk --since '1 hour ago'
  3. 3.Restart application: sudo systemctl restart eyeon-kiosk
  4. 4.If restart fails, check configuration files
  5. 5.Restore from backup if necessary
  6. 6.Contact support if issue persists

Escalation:

Contact technical support immediately if application cannot be restored

Hardware Failure

When critical hardware components fail

Steps:

  1. 1.Document the specific hardware issue
  2. 2.Check warranty status and support options
  3. 3.Implement temporary workarounds if possible
  4. 4.Order replacement hardware if needed
  5. 5.Schedule maintenance window for replacement
  6. 6.Update documentation with failure details

Escalation:

Contact hardware vendor for warranty claims and replacements

Security Incident

When security issues are detected

Steps:

  1. 1.Immediately disconnect from network if necessary
  2. 2.Document the security incident
  3. 3.Check for unauthorized access or changes
  4. 4.Change all passwords and API keys
  5. 5.Review system logs for suspicious activity
  6. 6.Contact security team and management

Escalation:

Follow security incident response procedures immediately

Data Loss

When critical data is lost or corrupted

Steps:

  1. 1.Stop all operations to prevent further data loss
  2. 2.Assess the scope of data loss
  3. 3.Restore from most recent backup
  4. 4.Verify data integrity after restoration
  5. 5.Identify cause of data loss
  6. 6.Implement additional safeguards

Escalation:

Contact data recovery specialists if backup restoration fails

Log Analysis

Understanding and analyzing kiosk application logs:

Application Logs

Location:journalctl -u eyeon-kiosk

Main application logs including errors, warnings, and info messages

Common Entries:
  • •API connection status and responses
  • •Content update notifications
  • •Touch interaction events
  • •Configuration changes
  • •Error messages and stack traces

System Logs

Location:/var/log/syslog

System-level logs including hardware and service issues

Common Entries:
  • •Hardware detection and errors
  • •Network interface status
  • •Service start/stop events
  • •Kernel messages
  • •Authentication events

Touch Screen Logs

Location:/var/log/Xorg.0.log

Touch screen and display related logs

Common Entries:
  • •Touch screen calibration events
  • •Display resolution changes
  • •Input device detection
  • •Graphics driver messages
  • •Touch event processing

Network Logs

Location:/var/log/network.log

Network connectivity and API communication logs

Common Entries:
  • •Network interface status changes
  • •API request/response logs
  • •Connection timeouts and errors
  • •DNS resolution issues
  • •Firewall and security events

Log Analysis Commands

  1. 1.View recent errors: journalctl -u eyeon-kiosk --since '1 hour ago' | grep -i error
  2. 2.Monitor real-time logs: journalctl -u eyeon-kiosk -f
  3. 3.Search for specific patterns: journalctl -u eyeon-kiosk | grep 'API'
  4. 4.Export logs to file: journalctl -u eyeon-kiosk --since '1 day ago' > kiosk-logs.txt
  5. 5.View system logs: tail -f /var/log/syslog | grep eyeon

Performance Optimization

Tips and techniques for optimizing kiosk performance:

Memory Optimization

Optimize memory usage and prevent memory leaks

Techniques:

  • •Regular application restarts to clear memory
  • •Monitor memory usage with htop
  • •Configure appropriate cache sizes
  • •Close unnecessary background processes
  • •Use memory-efficient image formats

Commands:

  1. 1.Monitor memory: free -h
  2. 2.Check memory usage: ps aux --sort=-%mem
  3. 3.Clear memory cache: sudo sync && sudo echo 3 > /proc/sys/vm/drop_caches

CPU Optimization

Reduce CPU usage and improve responsiveness

Techniques:

  • •Optimize content loading and caching
  • •Use efficient image compression
  • •Minimize background processes
  • •Configure appropriate update intervals
  • •Use hardware acceleration when available

Commands:

  1. 1.Monitor CPU: htop
  2. 2.Check CPU usage: ps aux --sort=-%cpu
  3. 3.Set CPU governor: echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

Network Optimization

Improve network performance and reduce latency

Techniques:

  • •Use wired connection when possible
  • •Optimize API request frequency
  • •Implement content caching
  • •Use CDN for static content
  • •Configure appropriate timeout values

Commands:

  1. 1.Test network speed: speedtest-cli
  2. 2.Check latency: ping -c 10 api.eyeonllc.com
  3. 3.Monitor network usage: iftop

Display Optimization

Optimize display performance and visual quality

Techniques:

  • •Use appropriate resolution settings
  • •Optimize image quality vs. file size
  • •Enable hardware acceleration
  • •Configure appropriate refresh rates
  • •Use efficient rendering techniques

Commands:

  1. 1.Check display info: xrandr --query
  2. 2.Test display performance: glxgears
  3. 3.Check graphics drivers: lspci | grep VGA

Best Practices

Recommended practices for kiosk troubleshooting and maintenance

Prevention

  • •Implement regular maintenance schedules
  • •Monitor system health continuously
  • •Keep software and drivers updated
  • •Maintain proper environmental conditions
  • •Use quality hardware and cables

Monitoring

  • •Set up automated health checks
  • •Monitor system resources regularly
  • •Track application performance metrics
  • •Log all significant events
  • •Implement alerting for critical issues

Documentation

  • •Document all configuration changes
  • •Maintain troubleshooting procedures
  • •Keep contact information current
  • •Document known issues and solutions
  • •Regularly update maintenance logs

Support

  • •Establish escalation procedures
  • •Maintain vendor contact information
  • •Keep spare parts available
  • •Train staff on basic troubleshooting
  • •Have backup systems ready

Need Additional Help?

If you're unable to resolve the issue using this troubleshooting guide, contact our support team for assistance.

Contact Support