# ADMS Local Sync Agent

Local sync agent for syncing users from cloud ADMS to biometric devices on your local network.

## 📦 Contents

- `sync_agent.py` - Main sync agent application
- `requirements.txt` - Python dependencies
- `QUICK_START.md` - 5-minute quick start guide
- `UBUNTU_SETUP.md` - **Ubuntu 24.04+ specific guide** (READ THIS IF ON UBUNTU!)
- `sync_agent_config.json` - Configuration file (create with `--create-config`)

## ⚠️ Ubuntu 24.04+ Users

If you're on Ubuntu 24.04 or newer and get an error about "externally-managed-environment", **see [UBUNTU_SETUP.md](UBUNTU_SETUP.md)** - it has the quick fix!

**Quick fix:**
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## 🚀 Quick Setup (5 minutes)

### 1. Install Python
Python 3.8 or higher required. [Download from python.org](https://www.python.org/downloads/)

### 2. Install Dependencies
```bash
pip install -r requirements.txt
```

**On Ubuntu 24.04+:** Use virtual environment (see UBUNTU_SETUP.md)

### 3. Create Configuration
```bash
python sync_agent.py --create-config
```

This creates `sync_agent_config.json`

### 4. Configure
Edit `sync_agent_config.json` and set your cloud URL:
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "auto_discover": true,
  "network_prefix": "192.168.1"
}
```

### 5. Test
```bash
python sync_agent.py --device 192.168.1.100
```

Should show: `✅ Success: Successfully synced X users`

### 6. Run
```bash
python sync_agent.py
```

Done! The agent will now sync users every 10 minutes.

## 📚 Full Documentation

See `QUICK_START.md` for more details.

## 🔑 Device Password Support

Add device password to your config:
```json
{
  "devices": [
    {
      "ip": "192.168.1.100",
      "password": "your_device_password"
    }
  ],
  "auto_discover": false
}
```

The agent will use the password to authenticate with devices during sync.

## 📊 Configuration Options

- `cloud_url` - Your ADMS cloud URL (required)
- `sync_interval_minutes` - How often to sync (default: 10)
- `device_timeout_seconds` - Device connection timeout (default: 30)
- `devices` - List of device IPs or objects with IP + password
- `auto_discover` - Enable auto-discovery (default: true)
- `network_prefix` - Network range for discovery (e.g., "192.168.1")
- `port` - Device port (default: 4370)

## 🛠️ Deployment

### Linux/Mac (systemd)
```bash
sudo cp adms-sync-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable adms-sync-agent
sudo systemctl start adms-sync-agent
```

### Windows (Task Scheduler)
1. Open Task Scheduler
2. Create Basic Task → "ADMS Sync Agent"
3. Trigger: At startup
4. Action: `python sync_agent.py`

## 📋 System Requirements

- Python 3.8+
- Network access to cloud ADMS (HTTPS)
- Network access to local devices (HTTP)
- 50-100 MB RAM
- Internet connection for cloud API

## 🐛 Troubleshooting

### "Cloud API unreachable"
- Check cloud URL in config
- Verify HTTPS connectivity: `curl https://your-adms.cloud.com`

### "Cannot connect to device"
- Check device IP address
- Verify device is on same network
- Test: `ping 192.168.1.100`

### "No module named requests"
- Run: `pip install -r requirements.txt`
- **On Ubuntu 24.04+:** Use virtual environment (see UBUNTU_SETUP.md)

### View logs
```bash
tail -f logs/sync_agent_*.log
```

## 📞 Support

For issues, check logs and verify:
1. Cloud URL is correct
2. Device IPs are reachable
3. Network connectivity
4. Device password is correct (if set)
5. Virtual environment activated (Ubuntu 24.04+)

## ✨ Features

✅ Auto-discovers devices on network  
✅ Manual device list support  
✅ Device password authentication  
✅ Periodic sync (configurable)  
✅ Error handling and retries  
✅ Comprehensive logging  
✅ Works through firewalls  
✅ Multi-location support  

## 🎯 Next Steps

1. Read `QUICK_START.md`
2. Create config file
3. Test with one device
4. Deploy as background service
5. Monitor via logs and dashboard

Ready to sync! 🚀