# Smart Store Agent — Linux Installation Guide

## Download

| File | Type | Size |
|------|------|------|
| [smart-store-agent_1.0.0_amd64.deb](https://downloads.domoda.eu/linux/smart-store-agent_1.0.0_amd64.deb) | Debian/Ubuntu installer | ~104 MB |
| [Smart Store Agent-1.0.0.AppImage](https://downloads.domoda.eu/linux/Smart%20Store%20Agent-1.0.0.AppImage) | Portable (any Linux) | ~143 MB |

---

## Option A: Debian/Ubuntu (.deb) — Recommended

```bash
# 1. Download
wget https://downloads.domoda.eu/linux/smart-store-agent_1.0.0_amd64.deb

# 2. Install
sudo dpkg -i smart-store-agent_1.0.0_amd64.deb
sudo apt-get install -f   # fix missing dependencies

# 3. Add user to dialout group (required for USB relay)
sudo usermod -aG dialout $USER

# 4. Reboot (for group change to take effect)
sudo reboot

# 5. Run
smart-store-agent
```

Uninstall: `sudo apt remove smart-store-agent`

---

## Option B: AppImage — Portable (any Linux distro)

```bash
# 1. Download
wget "https://downloads.domoda.eu/linux/Smart%20Store%20Agent-1.0.0.AppImage"

# 2. Make executable
chmod +x "Smart Store Agent-1.0.0.AppImage"

# 3. Add user to dialout group (required for USB relay)
sudo usermod -aG dialout $USER
# Then logout/login or reboot

# 4. Run
./"Smart Store Agent-1.0.0.AppImage"
```

---

## First-time Setup

### Step 1: Connect to Backend

1. Open the app — Settings window appears
2. Set **Server URL**: `https://api.domoda.eu`
3. Enter **API Key** (get from Admin Dashboard → Agents → Create Key)
4. Click **Connect**
5. App should show: "Connected" with location name

### Step 2: Staff Login

1. Go to **POS** window (or Settings → Open POS)
2. Login with staff credentials (email + password)
3. This stores a JWT token needed for entry code validation

### Step 3: Configure Door Relay (if hardware connected)

1. Settings → Door Relay
2. **Port**: `/dev/ttyUSB0` (check with `ls /dev/ttyUSB*`)
3. **Baud Rate**: `9600`
4. **Enabled**: ON
5. **Open Command**: `open\n` (default, same as Lewiatan relay)
6. Click Save

If no relay hardware: the app works in **software mode** — all events are logged but no serial command is sent.

### Step 4: Open Kiosk Window

1. Settings → Open Self-Checkout
2. The kiosk window shows:
   - **Phone tab** — customer enters phone → OTP → scan products → pay
   - **Code tab** — customer enters 4-digit PIN → door opens
   - **Exit button** — "Otworz drzwi wyjscia" for customers who don't buy

---

## Hardware Setup

### USB Relay Module

Connect relay module to mini PC via USB. The relay appears as `/dev/ttyUSB0`.

```
Mini PC ──USB──> Relay Module ──wire──> Electric Door Lock
                 (9600 baud)            (12V/24V)
```

The app sends `open\n` to open the lock. The relay module handles timing (auto-close after ~5 seconds).

### QR/Barcode Scanner

Connect USB barcode scanner (HID keyboard mode). No driver needed — it types scanned codes as keyboard input.

```
Mini PC ──USB──> Barcode Scanner (HID)
```

When a customer shows a QR code (43+ characters), the app automatically:
1. Validates the token with the backend
2. Opens the door relay
3. Logs the entry event

---

## Auto-start on Boot

### Using systemd (recommended)

```bash
cat > ~/.config/systemd/user/smart-store-agent.service << 'EOF'
[Unit]
Description=Smart Store Agent
After=graphical-session.target

[Service]
ExecStart=/usr/bin/smart-store-agent
Restart=on-failure
RestartSec=5
Environment=DISPLAY=:0

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable smart-store-agent
systemctl --user start smart-store-agent
```

### For AppImage

Replace `ExecStart` with:
```
ExecStart=/path/to/Smart Store Agent-1.0.0.AppImage
```

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| "Permission denied" on `/dev/ttyUSB0` | `sudo usermod -aG dialout $USER` then reboot |
| Relay not detected | Check `ls /dev/ttyUSB*`, try different USB port |
| "401 Unauthorized" on entry code | Staff must be logged in via POS window |
| QR scan not working | Ensure scanner is in HID keyboard mode |
| App won't start (GPU error) | Run with `--disable-gpu` flag |
| Blank screen | Run with `--no-sandbox` flag |

## Check USB Relay Port

```bash
# List USB serial devices
ls -la /dev/ttyUSB*

# Check device info
udevadm info /dev/ttyUSB0

# Test relay manually
echo -ne "open\n" > /dev/ttyUSB0
```

---

## System Requirements

- **OS**: Ubuntu 20.04+ / Debian 11+ / any Linux x64 with glibc 2.31+
- **RAM**: 512 MB minimum
- **Disk**: 300 MB
- **USB**: 1 port for relay, 1 port for QR scanner
- **Network**: Internet access to backend API