### Seed Example Plugins

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Executes the database seeder to populate the application with example plugins like Zen Quotes and Weather. This command requires a configured Laravel environment.

```bash
php artisan db:seed --class=ExampleRecipesSeeder
```

--------------------------------

### GET /api/setup

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Registers a new TRMNL device upon its first connection to the server and returns an API key for subsequent requests.

```APIDOC
## GET /api/setup

### Description
Registers a device on the server and returns an API key. Supports auto-join functionality.

### Method
GET

### Endpoint
/api/setup

### Parameters
#### Headers
- **id** (string) - Required - The MAC address of the device (e.g., AA:BB:CC:DD:EE:FF)
- **model-id** (string) - Required - The model identifier of the device

### Response
#### Success Response (200)
- **api_key** (string) - The unique access token for the device
- **friendly_id** (string) - Human-readable device identifier
- **image_url** (string) - URL to the setup logo image

### Response Example
{
  "status": 200,
  "api_key": "abc123def456ghi789jkl0",
  "friendly_id": "XyZ123",
  "image_url": "http://localhost:4567/storage/images/setup-logo.png"
}
```

--------------------------------

### Register Device via Setup API

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Initializes a new TRMNL device connection. It registers the device and returns an API key for subsequent authenticated requests.

```bash
curl -X GET "http://localhost:4567/api/setup" \
  -H "id: AA:BB:CC:DD:EE:FF" \
  -H "model-id: og_png"
```

--------------------------------

### Define Application Layout Styles

Source: https://github.com/usetrmnl/larapaper/blob/main/public/mirror/index.html

Provides the CSS structure for the application, including full-screen containers, setup panels, and dark/night mode theme overrides.

```css
body { overflow: hidden; font-family: sans-serif; margin: 0; padding: 0; }
#screen-container, #setup { position: fixed; top: 0; left: 0; width: 100vw; height: 100vh; display: flex; flex-direction: column; justify-content: center; align-items: center; }
#screen { cursor: pointer; width: 100vw; height: 100vh; object-fit: contain; background-color: #000000; }
body.dark #screen, body.night #screen { filter: invert(1) hue-rotate(180deg); background-color: #ffffff; }
```

--------------------------------

### Activate TRMNL Device with Cloud Proxy in LaraPaper

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Steps to activate a TRMNL device and connect it to LaraPaper using the Cloud Proxy. This involves device setup, LaraPaper configuration, and enabling proxy settings. Ensure the queue worker is active for full functionality.

--------------------------------

### GET /api/devices

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Retrieves a list of all devices associated with the authenticated user, including current status metrics.

```APIDOC
## GET /api/devices

### Description
List all devices belonging to the authenticated user.

### Method
GET

### Endpoint
/api/devices

### Response
#### Success Response (200)
- **data** (array) - List of device objects containing id, name, friendly_id, mac_address, battery_voltage, and rssi.

### Response Example
{
  "data": [
    {
      "id": 1,
      "name": "Office Display",
      "friendly_id": "XyZ123",
      "mac_address": "AA:BB:CC:DD:EE:FF",
      "battery_voltage": 3.8,
      "rssi": -45
    }
  ]
}
```

--------------------------------

### GET /api/display

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Primary endpoint for devices to fetch the current screen image and receive operational instructions like firmware updates or sleep commands.

```APIDOC
## GET /api/display

### Description
Fetches the current screen image and device configuration settings.

### Method
GET

### Endpoint
/api/display

### Parameters
#### Headers
- **id** (string) - Required - Device MAC address
- **access-token** (string) - Required - Device API key
- **rssi** (integer) - Optional - Signal strength
- **battery_voltage** (float) - Optional - Current battery voltage

### Response
#### Success Response (200)
- **image_url** (string) - URL to the generated screen image
- **refresh_rate** (integer) - Seconds until next refresh
- **special_function** (string) - Current mode (e.g., sleep)

### Response Example
{
  "status": 0,
  "image_url": "http://localhost:4567/storage/images/generated/550e8400.png",
  "refresh_rate": 900,
  "special_function": "sleep"
}
```

--------------------------------

### GET /api/display/status

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Retrieves detailed status information for a device, including battery levels, firmware version, and sleep settings.

```APIDOC
## GET /api/display/status

### Description
Returns comprehensive status data for a managed device.

### Method
GET

### Endpoint
/api/display/status

### Parameters
#### Query Parameters
- **device_id** (integer) - Required - The ID of the device to query

### Response
#### Success Response (200)
- **battery_percent** (integer) - Current battery percentage
- **sleep_mode_enabled** (boolean) - Whether sleep mode is active
- **last_firmware_version** (string) - Current firmware version

### Response Example
{
  "id": 1,
  "name": "Office Display",
  "battery_percent": 67,
  "sleep_mode_enabled": true
}
```

--------------------------------

### Fetch TRMNL Display Data

Source: https://github.com/usetrmnl/larapaper/blob/main/public/mirror/index.html

Performs an asynchronous GET request to the TRMNL API to retrieve display configuration and image URLs. It handles response parsing, error reporting, and schedules automatic refreshes based on the returned refresh rate.

```javascript
var url = baseURL + "/api/display";
var xhr = new XMLHttpRequest();
xhr.open("GET", url, true);
for (var headerName in headers) {
  if (headers.hasOwnProperty(headerName)) {
    xhr.setRequestHeader(headerName, headers[headerName]);
  }
}
xhr.onload = function () {
  if (xhr.status >= 200 && xhr.status < 300) {
    try {
      var data = JSON.parse(xhr.responseText);
      if (data.status !== 0) {
        trmnl.showStatus("Error: " + (data.error || data.message || data.status));
        return;
      }
      trmnl.showScreen(data.image_url);
      if (data.refresh_rate) {
        trmnl.refreshTimer = setTimeout(function () {
          trmnl.fetchDisplay({ quiet: true });
        }, 1000 * data.refresh_rate);
      }
    } catch (e) {
      trmnl.showStatus("Error processing response: " + e.message);
    }
  }
};
xhr.send();
```

--------------------------------

### Initialize Browser UI and Settings

Source: https://github.com/usetrmnl/larapaper/blob/main/public/mirror/index.html

Handles the application initialization sequence, including parsing URL parameters for configuration overrides, setting default base URLs, and binding event listeners to UI elements like fullscreen and wake lock toggles.

```javascript
init: function () {
  trmnl.applySettingsFromUrl();
  trmnl.cleanUrl();
  trmnl.setDefaultBaseUrlIfMissing();
  trmnl.ui.img = document.getElementById("screen");
  document.addEventListener("fullscreenchange", trmnl.syncFullscreenToggle);
  if (trmnl.isWakeLockSupported()) {
    trmnl.ui.wakeLockToggle.addEventListener("change", function () {
      trmnl.toggleWakeLock();
    });
  }
}
```

--------------------------------

### Import Plugins with PluginImportService

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Demonstrates how to import plugins into the system using ZIP archives or remote URLs. It handles user association and optional configuration parameters like entry paths and renderers.

```php
use App\Services\PluginImportService;
use Illuminate\Http\UploadedFile;

$importer = app(PluginImportService::class);

// Import from uploaded ZIP file
$zipFile = $request->file('plugin_archive');
$plugin = $importer->importFromZip($zipFile, auth()->user());

// Import from URL (e.g., GitHub releases)
$plugin = $importer->importFromUrl(
    zipUrl: 'https://github.com/user/trmnl-recipe/archive/refs/heads/main.zip',
    user: auth()->user(),
    zipEntryPath: 'trmnl-recipe-main/src',
    preferredRenderer: 'trmnl-liquid',
    iconUrl: 'https://example.com/icon.png',
    allowDuplicate: true
);
```

--------------------------------

### List Device Models

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Fetches a list of available device models along with their display specifications such as dimensions, bit depth, and color support. Requires bearer token authentication.

```bash
curl -X GET "http://localhost:4567/api/device-models" \
  -H "Authorization: Bearer your_sanctum_token"
```

--------------------------------

### Configure Environment Variables

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Lists essential environment configuration settings for the application, including proxy settings, security modes, and performance tuning.

```bash
TRMNL_PROXY_BASE_URL=https://trmnl.app
TRMNL_PROXY_REFRESH_MINUTES=15
REGISTRATION_ENABLED=1
SSL_MODE=off
FORCE_HTTPS=0
TRUSTED_PROXIES="172.0.0.0/8"
PHP_OPCACHE_ENABLE=0
TRMNL_IMAGE_URL_TIMEOUT=30
APP_TIMEZONE=UTC
```

--------------------------------

### Run Tests with PHP Artisan

Source: https://github.com/usetrmnl/larapaper/blob/main/CONTRIBUTING.md

This command executes the test suite for the project using the Artisan command-line interface. Ensure all tests pass before submitting changes.

```shell
php artisan test
```

--------------------------------

### Initialize Browser Features and UI

Source: https://github.com/usetrmnl/larapaper/blob/main/public/mirror/index.html

Handles browser-level events such as visibility changes, Wake Lock acquisition, and Fullscreen mode activation based on user settings stored in localStorage.

```javascript
document.addEventListener("visibilitychange", function () { 
  if (document.visibilityState === "visible" && trmnl.ui.wakeLockToggle.checked) { 
    trmnl.acquireWakeLock(); 
  } 
});

var settings = trmnl.getSettings();
if (!settings || !settings.api_key) {
  trmnl.showSetupForm();
} else {
  trmnl.fetchDisplay();
}

if (settings.fullscreen && trmnl.isFullscreenSupported()) {
  var activateFullscreenOnce = function () {
    trmnl.enterFullscreen();
    document.removeEventListener("click", activateFullscreenOnce);
  };
  document.addEventListener("click", activateFullscreenOnce, { once: true });
}
```

--------------------------------

### Export and Import Plugin Archives using cURL

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Demonstrates how to export a plugin's settings as a ZIP archive and import a plugin from a ZIP archive using cURL commands. Requires authentication with a bearer token and specifies the API endpoints for these operations.

```bash
curl -X GET "http://localhost:4567/api/plugin_settings/my-plugin-id/archive" \
  -H "Authorization: Bearer your_sanctum_token" \
  -o plugin-backup.zip

curl -X POST "http://localhost:4567/api/plugin_settings/new-plugin-id/archive" \
  -H "Authorization: Bearer your_sanctum_token" \
  -F "file=@plugin-backup.zip"
```

--------------------------------

### Verify Developer License

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Endpoint to verify if a TRMNL device has a Developer license.

```APIDOC
## Verify Developer License

This endpoint can be used to check if a TRMNL device is equipped with a Developer license.

### Method
GET

### Endpoint
`https://trmnl.app/api/display`

### Response
#### Success Response (200)
*   **license_type** (string) - The type of license the device has (e.g., "Developer").
*   **device_id** (string) - The unique identifier of the device.
```

--------------------------------

### Fetch Current Screen via Display API

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Retrieves the current screen image URL and configuration for a device. It includes metadata like refresh rates and firmware update flags.

```bash
curl -X GET "http://localhost:4567/api/display" \
  -H "id: AA:BB:CC:DD:EE:FF" \
  -H "access-token: your_device_api_key" \
  -H "rssi: -45" \
  -H "battery_voltage: 3.8" \
  -H "fw-version: 1.5.0"
```

--------------------------------

### Plugin Model - Data Handling

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Demonstrates how to create, update, and render plugins using the Plugin model.

```APIDOC
## Plugin Model Usage

### Description
This section details the usage of the `Plugin` model for creating, managing, and rendering plugins, including data fetching strategies and rendering.

### Method
PHP (Eloquent ORM)

### Endpoint
N/A (Model usage within application code)

### Parameters
N/A

### Request Example
```php
use App\Models\Plugin;
use App\Models\Device;

// Create a recipe plugin with polling strategy
$plugin = Plugin::create([
    'user_id' => $user->id,
    'name' => 'Weather Dashboard',
    'plugin_type' => 'recipe',
    'data_strategy' => 'polling',
    'polling_url' => 'https://api.weather.gov/gridpoints/MTR/84,105/forecast',
    'polling_verb' => 'get',
    'polling_header' => "User-Agent: LaraPaper/1.0\nAccept: application/json",
    'data_stale_minutes' => 30,
    'markup_language' => 'liquid',
    'render_markup' => '
        <div class="layout layout--col">
            <h2 class="title title--large">{{ data.properties.periods[0].name }}</h2>
            <p class="content">{{ data.properties.periods[0].detailedForecast }}</p>
            <span class="label">{{ data.properties.periods[0].temperature }}°{{ data.properties.periods[0].temperatureUnit }}</span>
        </div>
    ',
    'configuration' => ['location' => 'San Francisco'],
    'configuration_template' => [
        'custom_fields' => [
            ['field_type' => 'text', 'name' => 'location', 'keyname' => 'location', 'default' => 'San Francisco']
        ]
    ]
]);

// Update data payload from external API
$plugin->updateDataPayload();

// Check if data needs refresh
if ($plugin->isDataStale()) {
    $plugin->updateDataPayload();
}

// Render plugin for a device
$device = Device::with(['deviceModel', 'user'])->find(1);
$html = $plugin->render(size: 'full', standalone: true, device: $device);

// Render for mashup layouts
$halfHtml = $plugin->render(size: 'half_horizontal', standalone: false, device: $device);
$quadrantHtml = $plugin->render(size: 'quadrant', standalone: false, device: $device);

// Duplicate a plugin
$copy = $plugin->duplicate($newUserId);
```

### Response
Returns plugin instances and rendered HTML content.
```

--------------------------------

### List User Devices

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Retrieves a list of all devices associated with the authenticated user, including key status information. Authentication is required via a bearer token.

```bash
curl -X GET "http://localhost:4567/api/devices" \
  -H "Authorization: Bearer your_sanctum_token"
```

--------------------------------

### Retrieve Plugin Display Image via Alias

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Fetches the rendered output of a plugin as an image via a public URL. This is useful for embedding TRMNL screens in other applications. Requires the plugin's alias feature to be enabled and accepts an optional device-model parameter.

```bash
# Get plugin display for default device model (og_png)
curl -X GET "http://localhost:4567/api/display/550e8400-e29b-41d4-a716-446655440000/alias"
```

```bash
# Get plugin display for specific device model
curl -X GET "http://localhost:4567/api/display/550e8400-e29b-41d4-a716-446655440000/alias?device-model=og_2bit"
```

--------------------------------

### Generate Screens via API

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Dynamically update TRMNL screens by sending a POST request to the /api/screen endpoint.

```APIDOC
## Generate Screens via API

This endpoint allows for dynamic screen updates on TRMNL devices by sending a POST request.

### Method
POST

### Endpoint
/api/screen

### Parameters
#### Header
*   **Authorization** (string) - Required - Bearer token for authentication. Example: `Bearer <TOKEN>`

#### Request Body
*   **markup** (string) - Required - The HTML markup for the screen content. Example: `"<h1>Hello World</h1>"`

### Request Example
```json
{
    "markup": "<h1>Hello World</h1>"
}
```

### Response
#### Success Response (200)
*   **message** (string) - Confirmation message indicating the screen was updated.
```

--------------------------------

### Generate Screens from Blade Views using Artisan

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Provides Artisan commands to generate screen layouts from Blade views for specific devices. It allows for default views or custom views to be specified, facilitating development and testing of screen designs.

```bash
php artisan trmnl:screen:generate

php artisan trmnl:screen:generate 2 custom-dashboard
```

--------------------------------

### Interact with Device Model

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Covers the management of display devices, including initialization, telemetry updates, sleep mode logic, and device mirroring. It utilizes Eloquent models to handle hardware-specific settings.

```php
use App\Models\Device;
use Carbon\Carbon;

$device = Device::create([
    'user_id' => $user->id,
    'mac_address' => 'AA:BB:CC:DD:EE:FF',
    'api_key' => Str::random(22),
    'name' => 'Office Display',
    'friendly_id' => Str::random(6),
    'default_refresh_interval' => 900,
    'device_model_id' => $deviceModel->id,
    'sleep_mode_enabled' => true,
    'sleep_mode_from' => '22:00',
    'sleep_mode_to' => '07:00',
    'proxy_cloud' => false,
]);

// Update device telemetry
$device->update([
    'last_rssi_level' => -45,
    'last_battery_voltage' => 3.85,
    'last_firmware_version' => '1.5.2',
    'last_refreshed_at' => now(),
]);
```

--------------------------------

### Screen Generation Command

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Command-line interface for generating screen layouts from Blade views.

```APIDOC
## Generate Screen

### Description
Generates screens for devices using Blade views. This is useful for development and testing screen layouts.

### Method
CLI Command

### Endpoint
`php artisan trmnl:screen:generate [device_id] [view_path]`

### Parameters
#### Path Parameters
- **device_id** (integer) - Optional - The ID of the device for which to generate the screen. Defaults to the default trmnl view if not provided.
- **view_path** (string) - Optional - The custom Blade view to use for generating the screen. Defaults to the default trmnl view if not provided.

### Request Example
```bash
# Generate screen for device ID 1 using default trmnl view
php artisan trmnl:screen:generate

# Generate screen for specific device with custom view
php artisan trmnl:screen:generate 2 custom-dashboard
```

### Response
This command generates screen output directly to the console or as configured. No explicit JSON response is provided.
```

--------------------------------

### Manage Playlists and Scheduling

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Shows how to create playlists for devices, define scheduling rules, and manage playlist items including support for mashup layouts. It also provides methods to check active status and retrieve the next item to display.

```php
use App\Models\Playlist;
use App\Models\PlaylistItem;
use App\Models\Device;

// Create a playlist for a device
$playlist = Playlist::create([
    'device_id' => $device->id,
    'name' => 'Workday Schedule',
    'is_active' => true,
    'weekdays' => [1, 2, 3, 4, 5],
    'active_from' => '09:00',
    'active_until' => '18:00',
    'refresh_time' => 300,
]);

// Add plugins to playlist
PlaylistItem::create([
    'playlist_id' => $playlist->id,
    'plugin_id' => $weatherPlugin->id,
    'order' => 1,
    'is_active' => true,
]);

// Create mashup playlist item
PlaylistItem::create([
    'playlist_id' => $playlist->id,
    'mashup_plugin_ids' => json_encode([$weatherPlugin->id, $clockPlugin->id]),
    'mashup_layout' => '1Lx1R',
    'order' => 3,
    'is_active' => true,
]);

// Check if playlist is currently active
if ($playlist->isActiveNow()) {
    $nextItem = $playlist->getNextPlaylistItem();
}
```

--------------------------------

### Push Screen via Device Authentication

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Allows external systems to push screen content directly to a device using the device's own access token.

```bash
curl -X POST "http://localhost:4567/api/screens" \
  -H "id: AA:BB:CC:DD:EE:FF" \
  -H "access-token: your_device_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {
      "content": "<x-trmnl::view><x-trmnl::headline>Weather Update</x-trmnl::headline><x-trmnl::title>72°F Sunny</x-trmnl::title></x-trmnl::view>",
      "file_name": "weather.png"
    }
  }'
```

--------------------------------

### Activate TRMNL Device with Cloud Proxy

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Steps to activate a TRMNL device with LaraPaper's cloud proxy service.

```APIDOC
## Activate TRMNL Device with Cloud Proxy

This section outlines the process for setting up and activating a TRMNL device to work with LaraPaper's cloud proxy.

### Steps

1.  **Setup TRMNL Device**: Configure your TRMNL device as per the official documentation, ensuring it connects to the cloud service.
2.  **Setup LaraPaper**: Install and configure LaraPaper, create a user, and log in.
3.  **Enable Auto-Join**: In LaraPaper's header bar, activate the "Permit Auto-Join" toggle.
4.  **Reactivate Captive Portal**: Press and hold the button on the back of your TRMNL for 5 seconds to reactivate the captive portal (or reflash).
5.  **Configure Wi-Fi and Server URL**: During the TRMNL setup process, when prompted for Wi-Fi credentials, also enter the local address of LaraPaper as the Server URL.
6.  **Verify Device Appearance**: The TRMNL device should automatically appear in the LaraPaper device list. You can then deactivate the "Permit Auto-Join" toggle.
7.  **Enable Cloud Proxy**: In the device list, activate the "☁️ Proxy" toggle for your TRMNL device. Ensure the queue worker is active (it should be running automatically in the Docker image).
8.  **View Cloud Plugins**: As long as no LaraPaper plugin is scheduled, the device will display your cloud plugins.

### Troubleshooting

*   Ensure your TRMNL device has a Developer license. You can verify this by calling the `https://trmnl.app/api/display` endpoint.
```

--------------------------------

### Plugin Model: Data Fetching, Rendering, and Management in PHP

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Illustrates the usage of the Plugin Eloquent model in PHP for creating, updating, and rendering plugins. It supports various data strategies (polling, webhook), markup languages (Liquid, Blade), and includes methods for data refreshing, rendering, duplication, and cache management.

```php
use App\Models\Plugin;
use App\Models\Device;

// Create a recipe plugin with polling strategy
$plugin = Plugin::create([
    'user_id' => $user->id,
    'name' => 'Weather Dashboard',
    'plugin_type' => 'recipe',
    'data_strategy' => 'polling',
    'polling_url' => 'https://api.weather.gov/gridpoints/MTR/84,105/forecast',
    'polling_verb' => 'get',
    'polling_header' => "User-Agent: LaraPaper/1.0\nAccept: application/json",
    'data_stale_minutes' => 30,
    'markup_language' => 'liquid',
    'render_markup' => '
        <div class="layout layout--col">
            <h2 class="title title--large">{{ data.properties.periods[0].name }}</h2>
            <p class="content">{{ data.properties.periods[0].detailedForecast }}</p>
            <span class="label">{{ data.properties.periods[0].temperature }}°{{ data.properties.periods[0].temperatureUnit }}</span>
        </div>
    ',
    'configuration' => ['location' => 'San Francisco'],
    'configuration_template' => [
        'custom_fields' => [
            ['field_type' => 'text', 'name' => 'location', 'keyname' => 'location', 'default' => 'San Francisco']
        ]
    ]
]);

// Update data payload from external API
$plugin->updateDataPayload();

// Check if data needs refresh
if ($plugin->isDataStale()) {
    $plugin->updateDataPayload();
}

// Render plugin for a device
$device = Device::with(['deviceModel', 'user'])->find(1);
$html = $plugin->render(size: 'full', standalone: true, device: $device);

// Render for mashup layouts
$halfHtml = $plugin->render(size: 'half_horizontal', standalone: false, device: $device);
$quadrantHtml = $plugin->render(size: 'quadrant', standalone: false, device: $device);

// Duplicate a plugin
$copy = $plugin->duplicate($newUserId);
```

--------------------------------

### Manage Local Storage Settings

Source: https://github.com/usetrmnl/larapaper/blob/main/public/mirror/index.html

Provides methods to persist and retrieve user settings using the browser's localStorage API. Includes functionality to save, clear, and load configuration objects.

```javascript
getSettings: function () {
  try {
    return JSON.parse(localStorage.getItem(trmnl.STORAGE_KEY)) || {};
  } catch (e) {
    return {};
  }
},
saveSettings: function (data) {
  var settings = trmnl.getSettings();
  for (var key in data) {
    if (data.hasOwnProperty(key)) {
      settings[key] = data[key];
    }
  }
  localStorage.setItem(trmnl.STORAGE_KEY, JSON.stringify(settings));
}
```

--------------------------------

### Update Screen with Custom Markup

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Pushes custom HTML or Blade markup to a specific device. Requires a Sanctum token with the update-screen ability.

```bash
curl -X POST "http://localhost:4567/api/display/update" \
  -H "Authorization: Bearer your_sanctum_token" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "markup": "<div class=\"view view--full\"><h1 class=\"title\">Hello World</h1><p class=\"description\">Current time: {{ now() }}</p></div>"
  }'
```

--------------------------------

### POST /api/display/update

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Updates a device screen by pushing custom HTML/Blade markup to be rendered by the server.

```APIDOC
## POST /api/display/update

### Description
Renders provided markup and updates the screen for a specific device.

### Method
POST

### Endpoint
/api/display/update

### Parameters
#### Request Body
- **device_id** (integer) - Required - Internal ID of the device
- **markup** (string) - Required - HTML/Blade template content

### Response
#### Success Response (200)
- **message** (string) - Status message

### Response Example
{
  "message": "success"
}
```

--------------------------------

### Submit Device Logs

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Allows devices to submit diagnostic logs to the server. Supports both new format with a 'logs' array and legacy format. Requires an access token for authentication.

```bash
curl -X POST "http://localhost:4567/api/log" \
  -H "access-token: your_device_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "logs": [
      {
        "creation_timestamp": "2024-01-15T10:30:00Z",
        "level": "info",
        "message": "Screen refresh completed",
        "battery_voltage": 3.85
      },
      {
        "creation_timestamp": "2024-01-15T10:30:05Z",
        "level": "info",
        "message": "WiFi signal strong",
        "rssi": -42
      }
    ]
  }'
```

--------------------------------

### Image Generation Service for E-Ink Displays in PHP

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Details the ImageGenerationService for converting HTML/Blade markup into optimized images for e-ink displays using Browsershot and ImageMagick. It covers generating images from markup, device models, default screens, and includes utility functions for cleanup and cache management.

```php
use App\Services\ImageGenerationService;
use App\Models\Device;
use App\Models\DeviceModel;

// Generate image for a device from markup
$device = Device::find(1);
$markup = '<div class="view"><h1>Hello World</h1></div>';
$imageUuid = ImageGenerationService::generateImage($markup, $device->id);
// Returns: "550e8400-e29b-41d4-a716-446655440000"
// Image stored at: storage/app/public/images/generated/{uuid}.png

// Generate image using device model (without a physical device)
$deviceModel = DeviceModel::where('name', 'og_png')->first();
$imageUuid = ImageGenerationService::generateImageFromModel(
    markup: $markup,
    deviceModel: $deviceModel,
    user: $user,
    palette: $deviceModel->palette
);

// Generate default screen images (setup, sleep, error)
$setupUuid = ImageGenerationService::generateDefaultScreenImage($device, 'setup-logo');
$sleepUuid = ImageGenerationService::generateDefaultScreenImage($device, 'sleep');
$errorUuid = ImageGenerationService::generateDefaultScreenImage($device, 'error', 'Weather Plugin');

// Get device-specific default image path
$imagePath = ImageGenerationService::getDeviceSpecificDefaultImage($device, 'setup-logo');
// Returns: "images/default-screens/setup-logo_800_480_1_0.png"

// Cleanup unused generated images
ImageGenerationService::cleanupFolder();

// Check and reset plugin cache if device dimensions changed
ImageGenerationService::resetIfNotCacheable($plugin, $device);
```

--------------------------------

### Verify TRMNL Device Developer License via API

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Troubleshooting step to verify if a TRMNL device has a Developer license by calling a specific API endpoint. This helps in diagnosing potential issues with device activation or feature access.

```http
GET https://trmnl.app/api/display
```

--------------------------------

### POST /api/custom_plugins/{id}

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Updates data for a specific plugin configured with the webhook strategy, triggering a screen regeneration.

```APIDOC
## POST /api/custom_plugins/{id}

### Description
Push data to a webhook-enabled plugin to update its display content.

### Method
POST

### Endpoint
/api/custom_plugins/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The UUID of the plugin

#### Request Body
- **merge_variables** (object) - Required - Key-value pairs to be merged into the plugin template.

### Response Example
{
  "message": "Data updated successfully"
}
```

--------------------------------

### POST /api/log

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Allows devices to submit diagnostic logs to the server. Supports both modern array-based log formats and legacy structures.

```APIDOC
## POST /api/log

### Description
Submit diagnostic logs from a device to the server.

### Method
POST

### Endpoint
/api/log

### Parameters
#### Request Body
- **logs** (array) - Required - List of log objects containing creation_timestamp, level, message, and optional metrics like battery_voltage or rssi.

### Response
#### Success Response (200)
- **status** (integer) - HTTP status code

### Response Example
{
  "status": 200
}
```

--------------------------------

### Generate TRMNL Screen via API POST Request

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Dynamically update TRMNL screens by sending a POST request to the '/api/screen' endpoint. The request requires an 'Authorization' header with a Bearer token and a JSON payload containing the 'markup'.

```http
POST /api/screen

Authorization: Bearer <TOKEN>

{
    "markup": "<h1>Hello World</h1>"
}
```

--------------------------------

### Retrieve Device Status

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Fetches detailed status information for a device, including battery levels, signal strength, and sleep mode configurations.

```bash
curl -X GET "http://localhost:4567/api/display/status?device_id=1" \
  -H "Authorization: Bearer your_sanctum_token"
```

--------------------------------

### Plugin Archive Management

Source: https://context7.com/usetrmnl/larapaper/llms.txt

APIs for exporting and importing plugin settings as ZIP archives.

```APIDOC
## Export Plugin as ZIP Archive

### Description
Exports the settings for a specific plugin as a ZIP archive.

### Method
GET

### Endpoint
`/api/plugin_settings/{plugin_id}/archive`

### Parameters
#### Path Parameters
- **plugin_id** (string) - Required - The unique identifier of the plugin to export.

#### Query Parameters
None

### Request Example
```bash
curl -X GET "http://localhost:4567/api/plugin_settings/my-plugin-id/archive" \
  -H "Authorization: Bearer your_sanctum_token" \
  -o plugin-backup.zip
```

### Response
#### Success Response (200)
- **file** (binary) - The ZIP archive containing the plugin settings.

## Import Plugin from ZIP Archive

### Description
Imports plugin settings from a provided ZIP archive.

### Method
POST

### Endpoint
`/api/plugin_settings/{plugin_id}/archive`

### Parameters
#### Path Parameters
- **plugin_id** (string) - Required - The unique identifier for the new or existing plugin.

#### Query Parameters
None

#### Request Body
- **file** (file) - Required - The ZIP archive file containing the plugin settings.

### Request Example
```bash
curl -X POST "http://localhost:4567/api/plugin_settings/new-plugin-id/archive" \
  -H "Authorization: Bearer your_sanctum_token" \
  -F "file=@plugin-backup.zip"
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful processing.
- **data** (object) - Contains additional data, such as the processed settings.
  - **settings_yaml** (string) - The plugin settings in YAML format.
```

--------------------------------

### Update Device Settings

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Updates the display settings for a specific device. Requires device ID, and allows configuration of name, refresh interval, and sleep mode. Authentication is handled via a bearer token.

```bash
curl -X POST "http://localhost:4567/api/display/status" \
  -H "Authorization: Bearer your_sanctum_token" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": 1,
    "name": "Living Room Display",
    "default_refresh_interval": 600,
    "sleep_mode_enabled": true,
    "sleep_mode_from": "23:00",
    "sleep_mode_to": "06:00"
  }'
```

--------------------------------

### Upload Image to Plugin via Webhook

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Uploads images directly to image webhook plugins. Supports multiple methods: multipart form data, base64-encoded strings, and raw binary uploads. Requires a plugin ID in the URL.

```bash
# Upload image via multipart form
curl -X POST "http://localhost:4567/api/plugin_settings/550e8400-e29b-41d4-a716-446655440000/image" \
  -F "image=@/path/to/screen.png"
```

```bash
# Upload image via base64
curl -X POST "http://localhost:4567/api/plugin_settings/550e8400-e29b-41d4-a716-446655440000/image" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }'
```

```bash
# Upload raw binary PNG
curl -X POST "http://localhost:4567/api/plugin_settings/550e8400-e29b-41d4-a716-446655440000/image" \
  -H "Content-Type: image/png" \
  --data-binary '@/path/to/screen.png'
```

--------------------------------

### Generate TRMNL Screen via Blade View Command

Source: https://github.com/usetrmnl/larapaper/blob/main/README.md

Command to generate a TRMNL screen using the LaraPaper Blade components. This command is executed via the Artisan CLI and requires the 'trmnl:screen:generate' command.

```bash
php artisan trmnl:screen:generate
```

--------------------------------

### Image Generation Service

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Service for converting markup into images for e-ink displays.

```APIDOC
## Image Generation Service

### Description
Provides functionality to generate images from HTML/Blade markup, optimized for e-ink displays using Browsershot and ImageMagick.

### Method
PHP (Static Class Methods)

### Endpoint
N/A (Service usage within application code)

### Parameters
N/A

### Request Example
```php
use App\Services\ImageGenerationService;
use App\Models\Device;
use App\Models\DeviceModel;

// Generate image for a device from markup
$device = Device::find(1);
$markup = '<div class="view"><h1>Hello World</h1></div>';
$imageUuid = ImageGenerationService::generateImage($markup, $device->id);
// Returns: "550e8400-e29b-41d4-a716-446655440000"
// Image stored at: storage/app/public/images/generated/{uuid}.png

// Generate image using device model (without a physical device)
$deviceModel = DeviceModel::where('name', 'og_png')->first();
$imageUuid = ImageGenerationService::generateImageFromModel(
    markup: $markup,
    deviceModel: $deviceModel,
    user: $user,
    palette: $deviceModel->palette
);

// Generate default screen images (setup, sleep, error)
$setupUuid = ImageGenerationService::generateDefaultScreenImage($device, 'setup-logo');
$sleepUuid = ImageGenerationService::generateDefaultScreenImage($device, 'sleep');
$errorUuid = ImageGenerationService::generateDefaultScreenImage($device, 'error', 'Weather Plugin');

// Get device-specific default image path
$imagePath = ImageGenerationService::getDeviceSpecificDefaultImage($device, 'setup-logo');
// Returns: "images/default-screens/setup-logo_800_480_1_0.png"

// Cleanup unused generated images
ImageGenerationService::cleanupFolder();

// Check and reset plugin cache if device dimensions changed
ImageGenerationService::resetIfNotCacheable($plugin, $device);
```

### Response
Returns UUIDs for generated images or image paths. Provides utility methods for cleanup and cache management.
```

--------------------------------

### POST /api/display/status

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Updates the configuration settings for a specific TRMNL device, including refresh intervals and sleep mode schedules.

```APIDOC
## POST /api/display/status

### Description
Updates device settings such as name, refresh interval, and sleep mode configuration.

### Method
POST

### Endpoint
/api/display/status

### Parameters
#### Request Body
- **device_id** (integer) - Required - The ID of the device to update
- **name** (string) - Optional - New display name
- **default_refresh_interval** (integer) - Optional - Refresh interval in seconds
- **sleep_mode_enabled** (boolean) - Optional - Enable or disable sleep mode
- **sleep_mode_from** (string) - Optional - Start time for sleep mode (HH:MM)
- **sleep_mode_to** (string) - Optional - End time for sleep mode (HH:MM)

### Request Example
{
  "device_id": 1,
  "name": "Living Room Display",
  "default_refresh_interval": 600,
  "sleep_mode_enabled": true,
  "sleep_mode_from": "23:00",
  "sleep_mode_to": "06:00"
}
```

--------------------------------

### Update Custom Plugin Data via Webhook

Source: https://context7.com/usetrmnl/larapaper/llms.txt

Updates plugin data for plugins configured with the 'webhook' data strategy. This allows external services to push data that triggers screen regeneration. The endpoint uses a plugin ID in the URL.

```bash
curl -X POST "http://localhost:4567/api/custom_plugins/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "merge_variables": {
      "temperature": "72",
      "humidity": "45",
      "condition": "Sunny",
      "location": "San Francisco"
    }
  }'
```