EVC Monitor

A TypeScript application that monitors EV Connect charging station availability and sends notifications via Pushover when connectors become available.

Disclaimer: This project is an unofficial, personal tool and is not affiliated with or endorsed by EV Connect. It interacts with the EV Connect API for personal monitoring purposes only. Use at your own risk.

Features

• 🔌 Real-time monitoring of EV Connect charging stations
• 📱 Pushover notifications when connectors become available
• 🔋 Charging session tracking to avoid false alerts
• 🚨 Parking time notifications when charging is complete
• 💾 State persistence across restarts
• 🐳 Docker support for easy deployment

Quick Start

Prerequisites

• Node.js 18+
• pnpm package manager
• EV Connect account credentials
• Pushover account (optional)

Installation

# Clone the repository
git clone https://github.com/darnfish/evc-monitor.git
cd evc-monitor

# Install dependencies
pnpm install

# Copy environment template
cp env.template .env

# Edit .env with your credentials
# See Environment Variables section below

Running

# Development
pnpm dev

# Production
pnpm build
pnpm start

# Docker
docker-compose up -d

Environment Variables

Required Variables

EMAIL=your-evconnect-email
PASSWORD=your-evconnect-password
NETWORK_ID=your-network-id
LOCATION_ID=your-location-id

Optional Variables

# Monitoring settings
CHECK_INTERVAL_MS=60000                    # Check interval in milliseconds (default: 60000)
IGNORE_CONNECTOR_IDS=connector1,connector2 # Comma-separated list of connectors to ignore
DATA_DIR=./data                            # Directory for state persistence
PERSIST_LAST_CHECK_TIMESTAMP=true          # Respect check interval on restart

# Pushover notifications
PUSHOVER_ENABLED=true                      # Enable Pushover notifications
PUSHOVER_USER_KEY=your-pushover-user-key   # Your Pushover user key
PUSHOVER_APP_TOKEN=your-pushover-app-token # Your Pushover app token
PUSHOVER_SERVICE_NOTIFICATIONS=true        # Send service start/stop notifications

# Non-priority notifications (low priority, quiet notifications)
PUSHOVER_OCCUPIED_NOTIFICATIONS=false      # Send notifications when connectors become occupied
PUSHOVER_SERVICE_STATUS_NOTIFICATIONS=false # Send notifications when connectors go in/out of service

# Parking notifications
ENABLE_PARKING_NOTIFICATIONS=true          # Enable parking time notifications
DISABLE_ALERTS_WHILE_CHARGING=true         # Disable availability alerts while you're charging (default: true)

Testing

The application includes a comprehensive test suite with unit and integration tests.

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run tests for CI
pnpm test:ci

Test Environment Variables

For testing, the following environment variables are automatically set:

EMAIL=test@example.com
PASSWORD=test-password
NETWORK_ID=test-network-id
LOCATION_ID=test-location-id
PUSHOVER_ENABLED=false
PUSHOVER_USER_KEY=test-user-key
PUSHOVER_APP_TOKEN=test-app-token
PUSHOVER_SERVICE_NOTIFICATIONS=false
ENABLE_PARKING_NOTIFICATIONS=true
PERSIST_LAST_CHECK_TIMESTAMP=true
CHECK_INTERVAL_MS=60000
IGNORE_CONNECTOR_IDS=""
DATA_DIR=./test-data

GitHub Actions

The repository includes GitHub Actions workflows for:

• Testing: Runs on every pull request (required for merge)
• Building: Creates Docker images
• Deployment: Pushes to container registry

Required GitHub Secrets

For production deployments, set these as GitHub repository secrets:

EMAIL=your-actual-email
PASSWORD=your-actual-password
NETWORK_ID=your-actual-network-id
LOCATION_ID=your-actual-location-id
PUSHOVER_USER_KEY=your-pushover-user-key
PUSHOVER_APP_TOKEN=your-pushover-app-token

Development

Adding New Features

When adding new features, please ensure:

1. Write tests first (TDD approach)
2. Add unit tests for all new functionality
3. Add integration tests for service interactions
4. Test error handling and edge cases
5. Maintain >90% code coverage
6. Update documentation

Code Quality

• Use TypeScript strict mode
• Follow existing code patterns
• Add JSDoc comments for public APIs
• Handle errors gracefully
• Use meaningful variable names

Pull Request Process

1. Create feature branch
2. Write tests for new functionality
3. Implement feature
4. Ensure all tests pass
5. Update documentation
6. Create pull request with template

Architecture

Core Components

• AuthService: Handles EV Connect authentication and token management
• EVCMonitor: Main monitoring service that checks connector availability
• PushoverService: Sends notifications via Pushover API
• StateManager: Persists connector states across restarts
• TokenStorageService: Manages authentication token storage

Data Flow

1. Authentication: Authenticate with EV Connect API using email/password
2. Monitoring: Check location data → Compare with previous state → Detect changes
3. Notifications: Send Pushover notifications for newly available connectors
4. State Management: Save current state for next check cycle

Docker Deployment

Using Docker Compose

# Copy environment file
cp env.template .env

# Edit .env with your credentials
# Start services
docker-compose up -d

# View logs
docker-compose logs -f evc-monitor

Manual Docker

# Build image
docker build -t evc-monitor .

# Run container
docker run -d \
  --name evc-monitor \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  evc-monitor

Troubleshooting

Common Issues

1. Authentication errors: Check your email, password, and network ID
2. No notifications: Verify Pushover configuration
3. High CPU usage: Increase check interval
4. State file issues: Clear data directory and restart

Logs

The application provides detailed logging:

• 🔐 Authentication status
• 🔌 Connector availability changes
• 📱 Notification delivery status
• ❌ Error conditions

Support

• Check existing issues and discussions
• Review documentation
• Create detailed bug reports with logs

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Implement your changes
5. Ensure all tests pass
6. Submit a pull request

See DEVELOPMENT.md and TESTING.md for detailed development guidelines.