A high-performance ATM telemetry simulator designed to generate realistic data for the ATM Insights monitoring system. This simulator produces telemetry data for a fleet of 612 ATMs with sophisticated cash management, error generation, and alert calibration capabilities.
- Realistic ATM Fleet Simulation: Generates telemetry for 612 ATMs across different regions (Airport, Supermarket, Mall, Hospital, University)
- Smart Cash Management: Advanced cash depletion and refill algorithms calibrated to generate exactly ~50 cash alerts per day
- Error Generation: Sophisticated error simulation with daily limits and realistic frequency patterns
- Alert Calibration: Dual-tier alert system with warnings (<20% cash) and critical alerts (<10% cash)
- Notification Integration: Supports Telegram and Email notifications through the backend API
- Performance Optimized: Batched API calls and efficient data structures for high-throughput simulation
- Docker Ready: Containerized deployment with Docker support
- Warning Alerts (10-20% cash): Telegram notifications, 12-hour cooldown
- Critical Alerts (<10% cash): Telegram + Email notifications, 8-hour cooldown
- Target: Calibrated to generate ~50 total cash alerts per day across all ATMs
- Daily Limits: Maximum 300 total errors, 100 critical errors per day
- Frequency: Each ATM generates errors every 40-58 hours on average
- Types: Hardware failures, network issues, cash dispenser problems, etc.
- Python 3.10 or higher
- Poetry
- Docker (optional, for containerized deployment)
-
Clone the repository (if not already done):
git clone <repository-url> cd atm-insights-simulator
-
Install dependencies:
poetry install
-
Configure environment:
cp .env.example .env # Edit .env with your configuration -
Run the simulator:
poetry run python run_simulator.py
-
Build the Docker image:
make build
-
Run the container:
make run
-
Run database migrations (if needed):
make migration
The simulator is configured through environment variables. Copy .env.example to .env and modify as needed:
# Backend API URL - Point to your ATM Insights backend
BACKEND_URL=http://localhost:8000# Fleet Configuration
NUM_ATMS=612 # Number of ATMs to simulate
SEND_INTERVAL_SECONDS=30 # Telemetry transmission interval
BATCH_SIZE=10 # API batch size for performance
# Cash Management (Calibrated for 50 alerts/day)
TARGET_DAILY_CASH_ALERTS=50 # Target daily cash alerts
CASH_WARNING_THRESHOLD=20.0 # Warning threshold percentage
CASH_CRITICAL_THRESHOLD=10.0 # Critical threshold percentage
# Error Control
MAX_DAILY_ERRORS=300 # Maximum total errors per day
MAX_DAILY_CRITICAL_ERRORS=100 # Maximum critical errors per day
MIN_HOURS_BETWEEN_ERRORS=40.0 # Minimum hours between errors per ATM
MAX_HOURS_BETWEEN_ERRORS=58.0 # Maximum hours between errors per ATMsimulator.py: Main simulation engine with cash management and error generationconfig.py: Configuration management and ATM fleet generationrun_simulator.py: Entry point script for running the simulator
Each simulated ATM includes:
- Identification: Unique ATM ID, location, region
- Hardware: Manufacturer, model, firmware version
- Health Metrics: Health factor influencing error probability
- Cash Management: Dynamic cash levels with realistic depletion patterns
- Error States: Tracking for error frequency and cooldown periods
The simulator implements a sophisticated cash management system:
- Dynamic Depletion: Cash levels decrease based on location multipliers and time-of-day patterns
- Smart Refills: Three-tier refill strategy (100%, 80%, 40%) based on cash levels
- Alert Generation: Calibrated to maintain exactly 50 alerts per day across all ATMs
- Real-time Adjustment: Daily monitoring and adjustment to meet alert targets
- New Alert Types: Add to
config.pyerror codes and modify alert logic insimulator.py - Custom ATM Models: Extend the ATM generation logic in
config.py - Advanced Cash Patterns: Modify the cash management algorithms in
simulator.py - Additional Metrics: Add new telemetry fields to the data generation methods
The simulator is precisely calibrated to meet specific alert frequency requirements:
- Total ATMs: 612
- Alert Rate: ~0.082 alerts per ATM per day
- Warning Threshold: 20% cash level
- Critical Threshold: 10% cash level
- Depletion Rate: 0.08-0.15% per 30-second cycle
- Location Multipliers: Airport (1.5x), Mall (1.3x), Supermarket (1.2x), etc.
- Time Patterns: Higher consumption during business hours
- Refill Strategy: Prevents excessive alerts while maintaining realistic patterns
- High Alert Frequency: Adjust
TARGET_DAILY_CASH_ALERTSin configuration - Backend Connection Failed: Verify
BACKEND_URLand ensure backend is running - Performance Issues: Increase
BATCH_SIZEorSEND_INTERVAL_SECONDS - Docker Build Failed: Ensure Docker is running and has sufficient resources
The simulator provides detailed logging:
- Info level: Normal operation, alert generation, daily summaries
- Warning level: API failures, configuration issues
- Error level: Critical failures, connection problems
Enable debug logging by modifying the logging level in simulator.py.
This project is part of the ATM Insights trial task developed by Lavendar Solution.
For issues, improvements, or questions, please contact:
- Email: lavendarsolution@gmail.com
- Author: Lavendar Solution
- ATM Insights Backend: REST API and data processing engine
- ATM Insights Frontend: Web dashboard for monitoring and analytics
Note: This simulator is designed to work in conjunction with the ATM Insights backend system. Ensure the backend is properly configured with Telegram and email notification services for complete functionality.