> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.mentra.glass/llms.txt
> Use this file to discover all available pages before exploring further.

# Hardware

> REST endpoints for hardware-related requests from glasses

## Button Press Event

Handle button press events from smart glasses.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/hardware/button-press
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/hardware/button-press
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/hardware/button-press
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <glassesJwt>
```

<Note>
  This endpoint requires glasses authentication, not regular user authentication.
</Note>

### Request Body

```json theme={null}
{
  "buttonId": "main",
  "pressType": "short" // or "long"
}
```

### Response

When no apps are subscribed to button events:

```json theme={null}
{
  "success": true,
  "action": "take_photo",
  "requestId": "photo-request-123"
}
```

When apps are subscribed to button events:

```json theme={null}
{
  "success": true
}
```

Error (500):

```json theme={null}
{
  "error": "Failed to process button press"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/hardware.routes.ts:20-59`
* **Middleware**: `validateGlassesAuth`
* **Behavior**: Creates system photo request if no apps are subscribed to `BUTTON_PRESS` stream

### Button Press Handling Logic

1. Checks if any apps are subscribed to `BUTTON_PRESS` events
2. If no apps subscribed:
   * Creates a system photo request using `photoRequestService`
   * Returns photo request ID for glasses to take photo
3. If apps subscribed:
   * Lets apps handle the button press via WebSocket
   * Returns success without action

## Check System Photo Request

Check if a system-initiated photo request exists.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  GET https://api.mentra.glass/api/hardware/system-photo-request/:requestId
  ```

  ```bash Development theme={null}
  GET https://devapi.mentra.glass/api/hardware/system-photo-request/:requestId
  ```

  ```bash Local theme={null}
  GET http://localhost:8002/api/hardware/system-photo-request/:requestId
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <glassesJwt>
```

### Parameters

| Parameter   | Type   | Description                            |
| ----------- | ------ | -------------------------------------- |
| `requestId` | string | The photo request ID to check (in URL) |

### Response

Success (200):

```json theme={null}
{
  "success": true,
  "action": "take_photo"
}
```

Not Found (404):

```json theme={null}
{
  "success": false,
  "message": "Photo request not found"
}
```

Error (500):

```json theme={null}
{
  "error": "Failed to check system photo request"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/hardware.routes.ts:66-86`
* **Service**: Uses `photoRequestService.getPendingPhotoRequest()`
* **Validation**: Only returns requests with `origin: 'system'`

## System Behavior

### Default Button Action

When no apps are subscribed to button events:

1. System creates a photo request with unique ID
2. Glasses receive instruction to take photo
3. Photo is uploaded via `/api/photos/upload` endpoint
4. Photo is saved to user's gallery

### App-Controlled Buttons

When apps subscribe to button events:

1. Button press is relayed to subscribed apps via WebSocket
2. Apps decide what action to take
3. System takes no default action
4. Apps can request photos through their own logic

## Button Types

| Button ID | Description               |
| --------- | ------------------------- |
| `main`    | Primary button on glasses |

## Press Types

| Press Type | Description        |
| ---------- | ------------------ |
| `short`    | Quick button press |
| `long`     | Button held down   |

## Error Codes

| Code | Description                                  |
| ---- | -------------------------------------------- |
| 401  | Unauthorized - invalid glasses token         |
| 404  | Photo request not found or not system-origin |
| 500  | Internal server error                        |

## Notes

* Button events are a key hardware interaction point
* System provides default photo-taking behavior
* Apps can override default behavior by subscribing to `BUTTON_PRESS` stream
* Photo requests are managed centrally by `photoRequestService`
* All endpoints require glasses authentication
* The user is identified by email from the decoded JWT token