patlite-beacon-serv 0.1.0

# PATLITE Beacon Server

A RESTful API server for controlling PATLITE USB beacons using the rust-patlite-beacon crate.

## Features

- **Complete RESTful API** for all PATLITE beacon functions
- **Optional API key authentication** for secure access
- **Single light control** with 5 colors (Red, Yellow, Green, Blue, White)
- **6 light patterns** including solid, blink, flash, and custom patterns
- **Sequential light commands** with precise timing control
- **Looping or one-shot sequences** for complex light shows
- **8 buzzer patterns** including melodies (London Bridge, Shining Star)
- **Automatic timeouts** for both lights and buzzers
- **Real-time status monitoring** via REST endpoints
- **Touch sensor support** - Press the beacon button to instantly clear all outputs
- **Background task management** for sequences and timeouts
- **Test sequence functionality** for hardware validation

## Requirements

- PATLITE USB beacon device (USB HID)
- Rust 1.70 or later
- Linux/macOS/Windows with USB support

## Installation

### From Source

```bash
git clone https://github.com/yourusername/patlite-beacon-serv.git
cd patlite-beacon-serv
cargo build --release
```

The compiled binary will be in `target/release/patlite-beacon-serv`

## Usage

### Basic Usage

Run the server with default settings (localhost:38861):

```bash
cargo run
# or
./target/release/patlite-beacon-serv
```

### Command Line Options

```bash
patlite-beacon-serv [OPTIONS]

Options:
  --host <HOST>          Host address to bind to [default: 127.0.0.1]
  --port <PORT>          Port to listen on [default: 38861]
  --api-key <API_KEY>    API key for authentication (optional)
  -h, --help             Print help
  -V, --version          Print version
```

### Examples

Run on all interfaces with custom port:
```bash
./patlite-beacon-serv --host 0.0.0.0 --port 8080
```

Run with API key authentication:
```bash
./patlite-beacon-serv --api-key my-secret-key
```

### Docker Support (Optional)

```dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y libusb-1.0-0 && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/patlite-beacon-serv /usr/local/bin/
EXPOSE 38861
CMD ["patlite-beacon-serv", "--host", "0.0.0.0"]
```

## Quick Start

1. Connect your PATLITE USB beacon to your computer
2. Build and run the server:
   ```bash
   cargo run
   ```
3. Test the connection:
   ```bash
   # Turn on red light
   curl -X PUT http://localhost:38861/light \
     -H "Content-Type: application/json" \
     -d '{"color": "red", "mode": "on"}'
   
   # Play a melody
   curl -X PUT http://localhost:38861/buzzer \
     -H "Content-Type: application/json" \
     -d '{"pattern": "london_bridge", "volume": 60}'
   
   # Clear everything
   curl -X POST http://localhost:38861/clear
   ```

## API Documentation

### Base URL
```
http://localhost:38861
```

### Authentication
All endpoints support optional API key authentication via the `?apiKey=<key>` query parameter if the server was started with an API key.

Example:
```bash
curl http://localhost:38861/status?apiKey=my-secret-key
```

### Status Endpoints

#### GET `/` or GET `/status`
Returns the current status of the light, sequence, and buzzer.

**Response:**
```json
{
  "light": {
    "color": "red",
    "mode": "on",
    "active": true,
    "remaining_ms": 5000
  },
  "sequence": {
    "commands": [
      {"color": "red", "mode": "on", "duration_ms": 3000},
      {"color": "blue", "mode": "flash", "duration_ms": 3000}
    ],
    "current_index": 0,
    "loop_sequence": true,
    "active": true
  },
  "buzzer": {
    "active": false,
    "pattern": null,
    "volume": 50
  },
  "connected": true,
  "last_updated": "2025-01-10T12:00:00Z"
}
```

### Light Control Endpoints

#### PUT `/light`
Set the light to a specific color and mode with optional duration.

**Request Body:**
```json
{
  "color": "red",  // One of: red, yellow, amber, green, blue, white, clear
  "mode": "pattern3",  // One of: off, on, solid, pattern1-6, blink, flash
  "duration_ms": 5000  // Optional, in milliseconds
}
```

**Available Modes:**
- `off` - Light is off
- `on` or `solid` - Light is continuously on
- `pattern1` or `blink` - Pattern 1 (slow blink)
- `pattern2` or `flash` - Pattern 2 (fast flash)
- `pattern3` - Pattern 3
- `pattern4` - Pattern 4
- `pattern5` - Pattern 5
- `pattern6` - Pattern 6

**Response:** Current beacon status

**Example:**
```bash
curl -X PUT http://localhost:38861/light \
  -H "Content-Type: application/json" \
  -d '{"color": "red", "mode": "flash", "duration_ms": 10000}'
```

#### DELETE `/light`
Turn off the current light.

**Response:** Current beacon status

**Example:**
```bash
curl -X DELETE http://localhost:38861/light
```

### Sequence Endpoints

#### POST `/sequence`
Start a sequence of light commands that execute one after another.

**Request Body:**
```json
{
  "commands": [
    {
      "color": "red",
      "mode": "on",
      "duration_ms": 3000
    },
    {
      "color": "blue",
      "mode": "flash",
      "duration_ms": 3000
    },
    {
      "color": "green",
      "mode": "blink",
      "duration_ms": 2000
    }
  ],
  "loop_sequence": true  // Optional, defaults to true. If false, sequence runs once
}
```

**Response:** Current beacon status

**Example (looping sequence):**
```bash
curl -X POST http://localhost:38861/sequence \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"color": "red", "mode": "on", "duration_ms": 3000},
      {"color": "blue", "mode": "flash", "duration_ms": 3000}
    ],
    "loop_sequence": true
  }'
```

**Example (one-shot sequence):**
```bash
curl -X POST http://localhost:38861/sequence \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"color": "red", "mode": "on", "duration_ms": 1000},
      {"color": "yellow", "mode": "on", "duration_ms": 1000},
      {"color": "green", "mode": "on", "duration_ms": 1000}
    ],
    "loop_sequence": false
  }'
```

#### DELETE `/sequence`
Stop the current running sequence.

**Response:** Current beacon status

**Example:**
```bash
curl -X DELETE http://localhost:38861/sequence
```

#### POST `/update`
Trigger an update of the sequence state (advances to next command if current duration has elapsed).

**Response:** Current beacon status

**Example:**
```bash
curl -X POST http://localhost:38861/update
```


### Buzzer Control Endpoints

#### PUT `/buzzer`
Activate the buzzer with a specific pattern.

**Request Body:**
```json
{
  "pattern": "strong_attention",  // See available patterns below
  "volume": 75,         // Optional, 0-100
  "duration_ms": 5000   // Optional, in milliseconds
}
```

**Available Patterns:**
- `off` - No sound
- `on` or `continuous` - Continuous tone
- `sweep` - Sweeping sound pattern
- `intermittent` - Intermittent beeping
- `weak_attention` or `weak` or `chirp` - Weak attention sound (gentle chirp)
- `strong_attention` or `strong` or `alarm` - Strong attention sound (alarm)
- `shining_star` - "Shining Star" melody
- `london_bridge` - "London Bridge" melody

**Response:** Current beacon status

**Example:**
```bash
curl -X PUT http://localhost:38861/buzzer \
  -H "Content-Type: application/json" \
  -d '{"pattern": "strong_attention", "volume": 80, "duration_ms": 10000}'
```

**Example with melody:**
```bash
curl -X PUT http://localhost:38861/buzzer \
  -H "Content-Type: application/json" \
  -d '{"pattern": "london_bridge", "volume": 60}'
```

#### DELETE `/buzzer`
Stop the buzzer.

**Response:** Current beacon status

**Example:**
```bash
curl -X DELETE http://localhost:38861/buzzer
```

#### POST `/buzzer/pattern`
Play a custom buzzer pattern with specific frequencies.

**Request Body:**
```json
{
  "pattern": [
    {
      "frequency_hz": 1000,
      "duration_ms": 200,
      "pause_ms": 100
    },
    {
      "frequency_hz": 1500,
      "duration_ms": 200,
      "pause_ms": 100
    }
  ],
  "repetitions": 3,
  "volume": 60  // Optional, 0-100
}
```

**Response:** Current beacon status

**Example:**
```bash
curl -X POST http://localhost:38861/buzzer/pattern \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": [
      {"frequency_hz": 800, "duration_ms": 250, "pause_ms": 150},
      {"frequency_hz": 1200, "duration_ms": 250, "pause_ms": 150}
    ],
    "repetitions": 2,
    "volume": 70
  }'
```

### Utility Endpoints

#### POST `/clear`
Turn off the light, stop any running sequence, and stop the buzzer.

**Response:** Current beacon status

**Example:**
```bash
curl -X POST http://localhost:38861/clear
```

#### POST `/test`
Run a test sequence that cycles through all light colors.

**Response:**
```json
{
  "success": true,
  "results": [
    "Test sequence started",
    "Step 1 executed",
    "Step 2 executed",
    "Step 3 executed",
    "Step 4 executed",
    "Step 5 executed"
  ]
}
```

**Example:**
```bash
curl -X POST http://localhost:38861/test
```

## Advanced Usage

### API Authentication

When the server is started with the `--api-key` parameter, all API endpoints require authentication:

```bash
# Start server with API key
./patlite-beacon-serv --api-key my-secret-key

# Make authenticated request
curl http://localhost:38861/status?apiKey=my-secret-key
```

Without the correct API key, requests will return `401 Unauthorized`.

### Touch Sensor Integration

The server automatically monitors the beacon's touch sensor. When pressed:
- All lights turn off immediately
- Any running sequence stops
- All buzzer sounds stop
- Server logs: "Touch sensor pressed - clearing all outputs"

This provides a hardware "panic button" for instant shutdown of all beacon activity.

### Sequence Programming

Create complex light shows with sequences:

```bash
# Traffic light sequence (loops forever)
curl -X POST http://localhost:38861/sequence \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"color": "red", "mode": "on", "duration_ms": 3000},
      {"color": "yellow", "mode": "on", "duration_ms": 1000},
      {"color": "green", "mode": "on", "duration_ms": 3000}
    ],
    "loop_sequence": true
  }'

# Alert sequence (runs once)
curl -X POST http://localhost:38861/sequence \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"color": "red", "mode": "pattern3", "duration_ms": 500},
      {"color": "blue", "mode": "pattern3", "duration_ms": 500}
    ],
    "loop_sequence": false
  }'
```

### Automatic Timeouts

Both lights and buzzers support automatic timeouts:

```bash
# Red light for exactly 5 seconds
curl -X PUT http://localhost:38861/light \
  -H "Content-Type: application/json" \
  -d '{"color": "red", "mode": "on", "duration_ms": 5000}'

# Alarm for 10 seconds
curl -X PUT http://localhost:38861/buzzer \
  -H "Content-Type: application/json" \
  -d '{"pattern": "strong_attention", "volume": 80, "duration_ms": 10000}'
```

After the specified duration, the light/buzzer automatically turns off without affecting other active components.

## Data Types

### Light Modes
- `off`: Light is turned off
- `on`: Light is continuously on
- `flash`: Light flashes rapidly
- `blink`: Light blinks slowly

### Light Colors
- `red`
- `yellow` or `amber`
- `green`
- `blue`
- `white` or `clear`

### Buzzer Patterns
- `off` - No sound
- `on` or `continuous` - Continuous tone
- `sweep` - Sweeping sound pattern
- `intermittent` - Intermittent beeping
- `weak_attention` (aliases: `weak`, `chirp`) - Gentle attention sound
- `strong_attention` (aliases: `strong`, `alarm`) - Strong alarm sound
- `shining_star` - Plays "Shining Star" melody
- `london_bridge` - Plays "London Bridge" melody

## Error Responses

The API returns appropriate HTTP status codes:

- `200 OK`: Successful operation
- `400 Bad Request`: Invalid parameters or request body
- `401 Unauthorized`: Invalid or missing API key (when authentication is enabled)
- `500 Internal Server Error`: Server or beacon communication error

## Troubleshooting

### Common Issues

1. **"Device not found" error**
   - Ensure the PATLITE beacon is connected via USB
   - Check USB permissions on Linux: `sudo usermod -a -G dialout $USER`
   - May need to logout/login after adding user to dialout group

2. **"Resource busy" error**
   - Another application may be using the beacon
   - Check if another instance of the server is running: `ps aux | grep patlite`

3. **Touch sensor not working**
   - The touch sensor monitoring requires the beacon to support this feature
   - Check server logs for "Touch sensor monitoring enabled" message

4. **API returns 401 Unauthorized**
   - Verify you're using the correct API key in the query parameter
   - Check server startup logs for the API key if auto-generated

## Development

### Building from Source

```bash
git clone https://github.com/yourusername/patlite-beacon-serv.git
cd patlite-beacon-serv
cargo build --release
```

### Running Tests

```bash
cargo test
```

### Code Structure

```
src/
├── main.rs          # Server initialization and route handlers
├── beacon.rs        # Beacon controller logic
├── api.rs           # API types and serialization
└── auth.rs          # Authentication middleware
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `cargo test`
5. Submit a pull request

## License

MIT License

Copyright (c) 2025 Benjamin Burkhart

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.