# Simple Buzzer Control Guide - reTerminal DM4

## Overview

The reTerminal DM4 has a built-in buzzer that can be controlled for alerts and notifications. The buzzer is located at the bottom right corner of the screen.

## Quick Start

### Turn Buzzer ON
```bash
echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
```

### Turn Buzzer OFF
```bash
echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
```

### Check Buzzer Status
```bash
cat /sys/class/leds/usr-buzzer/brightness
```
- `0` = OFF
- `1` or `255` = ON

---

## Basic Control Methods

### Method 1: Command Line (Simple)

**Single Beep (0.2 seconds):**
```bash
echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
sleep 0.2
echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
```

**Double Beep:**
```bash
for i in 1 2; do
    echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
    sleep 0.1
    echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
    sleep 0.1
done
```

**Long Beep (1 second):**
```bash
echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
sleep 1
echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
```

### Method 2: Python Script

**Simple Python Control:**
```python
import subprocess
import time

BUZZER_PATH = '/sys/class/leds/usr-buzzer/brightness'

def buzzer_on():
    """Turn buzzer ON"""
    subprocess.run(['sudo', 'tee', BUZZER_PATH], input='1', text=True)

def buzzer_off():
    """Turn buzzer OFF"""
    subprocess.run(['sudo', 'tee', BUZZER_PATH], input='0', text=True)

def beep(duration=0.2):
    """Play a beep for specified duration (in seconds)"""
    buzzer_on()
    time.sleep(duration)
    buzzer_off()

# Usage
beep(0.2)        # Short beep
beep(0.5)        # Medium beep
beep(1.0)        # Long beep
```

**Blinking Pattern:**
```python
def beep_pattern(count=3, on_time=0.1, off_time=0.1):
    """Blink buzzer multiple times"""
    for _ in range(count):
        buzzer_on()
        time.sleep(on_time)
        buzzer_off()
        time.sleep(off_time)

# Usage
beep_pattern(3, 0.1, 0.1)  # 3 quick beeps
```

### Method 3: Bash Function

Add to your `~/.bashrc`:
```bash
buzzer() {
    local action=$1
    local duration=${2:-0.2}
    local BUZZER='/sys/class/leds/usr-buzzer/brightness'
    
    case $action in
        on)
            echo 1 | sudo tee $BUZZER > /dev/null
            ;;
        off)
            echo 0 | sudo tee $BUZZER > /dev/null
            ;;
        beep)
            echo 1 | sudo tee $BUZZER > /dev/null
            sleep $duration
            echo 0 | sudo tee $BUZZER > /dev/null
            ;;
        *)
            echo "Usage: buzzer {on|off|beep [duration]}"
            ;;
    esac
}
```

Then use:
```bash
buzzer on           # Turn on
buzzer off          # Turn off
buzzer beep 0.2     # Beep for 0.2 seconds
buzzer beep 0.5     # Beep for 0.5 seconds
```

---

## Common Patterns

### Success Alert (2 short beeps)
```bash
for i in 1 2; do
    echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
    sleep 0.1
    echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
    sleep 0.1
done
```

### Error Alert (3 fast beeps)
```bash
for i in 1 2 3; do
    echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
    sleep 0.05
    echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
    sleep 0.05
done
```

### Warning Alert (1 long beep)
```bash
echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
sleep 0.5
echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
```

### Notification (1 short beep)
```bash
echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
sleep 0.2
echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
```

---

## Using the Test Script

A test script is available at `/tmp/test_buzzer.sh` on the device:

```bash
# Run the test script
ssh guard "/tmp/test_buzzer.sh"
```

Or copy and run locally:
```bash
scp guard:/tmp/test_buzzer.sh ./
chmod +x test_buzzer.sh
./test_buzzer.sh
```

---

## Important Notes

1. **Requires sudo**: All buzzer control commands require root privileges
2. **Simple on/off**: The buzzer can only be turned ON or OFF - no volume or frequency control
3. **Location**: Bottom right corner of the screen
4. **Use case**: Alerts, notifications, system events

---

## Troubleshooting

### Buzzer Not Working

1. **Check device exists:**
   ```bash
   ls -la /sys/class/leds/usr-buzzer/
   ```

2. **Test manually:**
   ```bash
   echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
   # Wait a moment - you should hear the buzzer
   echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
   ```

3. **Check permissions:**
   ```bash
   ls -la /sys/class/leds/usr-buzzer/brightness
   # Should show: -rw-r--r-- (requires sudo to write)
   ```

4. **Verify current state:**
   ```bash
   cat /sys/class/leds/usr-buzzer/brightness
   # 0 = off, 1 or 255 = on
   ```

### No Sound from Buzzer

- Check if buzzer is physically present and working
- Verify the device is powered on
- Try a longer duration (e.g., `sleep 1` instead of `sleep 0.2`)
- Check kernel messages: `dmesg | grep -i buzzer`

---

## Examples

### Example 1: Simple Alert Function
```bash
#!/bin/bash
alert() {
    echo 1 | sudo tee /sys/class/leds/usr-buzzer/brightness
    sleep 0.3
    echo 0 | sudo tee /sys/class/leds/usr-buzzer/brightness
}

# Use it
alert
```

### Example 2: Python Notification System
```python
import subprocess
import time

def notify(message_type):
    BUZZER = '/sys/class/leds/usr-buzzer/brightness'
    
    patterns = {
        'info': (1, 0.1),      # 1 beep, 0.1s
        'success': (2, 0.1),   # 2 beeps, 0.1s each
        'error': (3, 0.05),    # 3 fast beeps
        'warning': (1, 0.5),   # 1 long beep
    }
    
    count, duration = patterns.get(message_type, (1, 0.2))
    
    for _ in range(count):
        subprocess.run(['sudo', 'tee', BUZZER], input='1', text=True)
        time.sleep(duration)
        subprocess.run(['sudo', 'tee', BUZZER], input='0', text=True)
        time.sleep(0.1)

# Usage
notify('success')  # 2 short beeps
notify('error')    # 3 fast beeps
```

---

## Quick Reference

| Action | Command |
|--------|---------|
| Turn ON | `echo 1 \| sudo tee /sys/class/leds/usr-buzzer/brightness` |
| Turn OFF | `echo 0 \| sudo tee /sys/class/leds/usr-buzzer/brightness` |
| Check Status | `cat /sys/class/leds/usr-buzzer/brightness` |
| Single Beep | `echo 1 \| sudo tee /sys/class/leds/usr-buzzer/brightness && sleep 0.2 && echo 0 \| sudo tee /sys/class/leds/usr-buzzer/brightness` |

---

## Related Documentation

- `BUZZER-TEST-GUIDE.md` - Detailed testing guide
- `FLASK-BUZZER-CONTROL.md` - Flask web API for buzzer control
- `starwars_buzzer.sh` - Star Wars theme example script

---

## Summary

The buzzer is simple to control:
1. **Path**: `/sys/class/leds/usr-buzzer/brightness`
2. **Values**: `0` = OFF, `1` = ON
3. **Requires**: `sudo` privileges
4. **Control**: Write `1` to turn on, `0` to turn off

That's it! Simple and straightforward.