### REST API Quick Start Examples

Source: https://github.com/rushb-fr/freekiosk/wiki/INTEGRATIONS

Examples for getting device status, navigating to a new URL, and taking a screenshot using cURL. Ensure you replace 'your-key' with your actual API key and 'tablet-ip' with the device's IP address.

```bash
# Get device status
curl -H "X-Api-Key: your-key" http://tablet-ip:8080/api/status
```

```bash
# Navigate to new URL
curl -X POST -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://new-dashboard.com"}' \
  http://tablet-ip:8080/api/url
```

```bash
# Take screenshot
curl -H "X-Api-Key: your-key" http://tablet-ip:8080/api/screenshot -o screenshot.png
```

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

### Headless Setup: MQTT Configuration via ADB

Source: https://github.com/rushb-fr/freekiosk/wiki/INTEGRATIONS

Example ADB command to enable and configure MQTT for FreeKiosk during headless setup. This includes broker details and authentication credentials.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es mqtt_enabled "true" \
    --es mqtt_broker_url "192.168.1.100" \
    --es mqtt_username "homeassistant" \
    --es mqtt_password "mqtt-password" \
    --es pin "1234"
```

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

### Headless Setup: Combined REST API and MQTT Configuration via ADB

Source: https://github.com/rushb-fr/freekiosk/wiki/INTEGRATIONS

Example ADB command to enable and configure both REST API and MQTT for FreeKiosk during headless setup. This combines settings for both integration methods.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080" \
    --es rest_api_key "my-secret-key" \
    --es mqtt_enabled "true" \
    --es mqtt_broker_url "192.168.1.100" \
    --es mqtt_username "homeassistant" \
    --es mqtt_password "mqtt-password" \
    --es pin "1234"
```

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

### Headless Setup: REST API Configuration via ADB

Source: https://github.com/rushb-fr/freekiosk/wiki/INTEGRATIONS

Example ADB command to enable and configure the REST API for FreeKiosk during headless setup. This sets the API port and authentication key.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080" \
    --es rest_api_key "my-secret-key" \
    --es pin "1234"
```

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

### Install Dependencies

Source: https://github.com/rushb-fr/freekiosk/blob/main/CONTRIBUTING.md

Install the necessary project dependencies using npm.

```bash
npm install
```

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

### Switch to External App Mode

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Switches the display mode to an external application. The specified 'package' must correspond to an installed application. The overlay service is automatically started.

```json
{ "mode": "external_app", "package": "com.example.app" }
```

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

### Install Target App with ADB

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

Use this command to install the application that will be locked by FreeKiosk if it's not already present on the device.

```bash
adb install myapp.apk
```

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

### Install Android Platform Tools on Mac using Homebrew

Source: https://github.com/rushb-fr/freekiosk/wiki/installation

Recommended method for installing ADB on macOS.

```bash
brew install android-platform-tools
```

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

### Clone Repository and Install Dependencies

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/development.md

Clone the FreeKiosk repository and install project dependencies using npm. For iOS development, ensure you run `pod install` in the `ios` directory.

```bash
# Clone the repository
git clone https://github.com/rushb-fr/freekiosk.git
cd freekiosk

# Install dependencies
npm install

# iOS dependencies (if developing for iOS)
cd ios && pod install && cd ..
```

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

### Clone Repository and Install Dependencies

Source: https://github.com/rushb-fr/freekiosk/wiki/development

Clone the FreeKiosk repository and install project dependencies. For iOS development, ensure you run `pod install` after installing npm packages.

```bash
git clone https://github.com/rushb-fr/freekiosk.git
cd freekiosk

npm install

cd ios && pod install && cd ..
```

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

### Install ADB on Fedora

Source: https://github.com/rushb-fr/freekiosk/wiki/installation

Installs the Android Debug Bridge utility on Fedora Linux.

```bash
sudo dnf install android-tools
```

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

### Enable REST API via ADB

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Enables the REST API and sets its port and an optional API key using ADB for headless provisioning. Ensure to consult the ADB Configuration Guide for comprehensive setup.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es pin "1234" \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080" \
    --es rest_api_key "your_secret_key"
```

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

### Install ADB on Ubuntu/Debian

Source: https://github.com/rushb-fr/freekiosk/wiki/installation

Installs the Android Debug Bridge utility on Debian-based Linux distributions.

```bash
sudo apt install adb
```

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

### Start Metro Bundler

Source: https://github.com/rushb-fr/freekiosk/blob/main/CONTRIBUTING.md

Start the Metro bundler, which is used for developing React Native applications.

```bash
npm start
```

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

### Run FreeKiosk Deployment Script

Source: https://github.com/rushb-fr/freekiosk/blob/main/scripts/README.md

Executes the main deployment script for setting up FreeKiosk on a Mac. Follow on-screen prompts for device connection and APK installation.

```bash
./deploy_mac.zsh
```

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

### Configure FreeKiosk via ADB for Home Assistant

Source: https://github.com/rushb-fr/freekiosk/wiki/README

Configure FreeKiosk using ADB commands for a Home Assistant dashboard. This example sets the URL, PIN, and enables MQTT with broker details.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es url "https://homeassistant.local:8123" \
    --es pin "1234" \
    --es mqtt_enabled "true" \
    --es mqtt_broker_url "192.168.1.100"
```

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

### Basic ADB Command Syntax for FreeKiosk

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

This illustrates the fundamental structure for sending commands to FreeKiosk via ADB. The `am start` command is used to launch the FreeKiosk MainActivity with various options.

```bash
adb shell am start -n com.freekiosk/.MainActivity [OPTIONS]
```

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

### Configure Corporate Information Display

Source: https://github.com/rushb-fr/freekiosk/wiki/features-and-modes

Set up FreeKiosk for a corporate information display using ADB. This example configures the URL, PIN, and enables the REST API for remote control.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es url "https://dashboard.company.com" \
    --es pin "0000" \
    --es rest_api_enabled "true"
```

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

### Conventional Commit Message Examples

Source: https://github.com/rushb-fr/freekiosk/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification.

```text
✨ feat: Add new feature
```

```text
🐛 fix: Fix bug
```

```text
📝 docs: Update documentation
```

```text
♻️ refactor: Refactor code
```

```text
🎨 style: Improve styling
```

```text
⚡ perf: Performance improvement
```

```text
✅ test: Add tests
```

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

### GET /api/info

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves general device information.

```APIDOC
## GET /api/info

### Description
Device information.

### Method
GET

### Endpoint
/api/info

### Response
#### Success Response (200)
- **ip** (string) - The IP address of the device.
- **hostname** (string) - The hostname of the device.
- **version** (string) - The current software version.
- **isDeviceOwner** (boolean) - Whether the app has Device Owner privileges.
- **kioskMode** (boolean) - Whether kiosk lock task mode is currently active.

### Response Example
```json
{
  "success": true,
  "data": {
    "ip": "192.168.1.50",
    "hostname": "freekiosk",
    "version": "1.2.11",
    "isDeviceOwner": true,
    "kioskMode": true
  }
}
```
```

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

### Initial PDF Load

Source: https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/assets/pdfjs/viewer.html

Initiates the loading of the PDF document using the provided PDF URL. This is the starting point for displaying the PDF content.

```javascript
loadPdf(pdfUrl);
```

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

### Run FreeKiosk on Android

Source: https://github.com/rushb-fr/freekiosk/wiki/development

Start the Metro bundler and then run the FreeKiosk application on an Android device or emulator. You can specify a device ID if multiple devices are connected.

```bash
npm start

npx react-native run-android

npx react-native run-android --device <device_id>
```

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

### Get Device Information

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Fetches general device information such as IP address, hostname, app version, and Device Owner status. Useful for device identification and management.

```json
{
  "success": true,
  "data": {
    "ip": "192.168.1.50",
    "hostname": "freekiosk",
    "version": "1.2.11",
    "isDeviceOwner": true,
    "kioskMode": true
  }
}
```

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

### Get GPS Location (No Location Available)

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Example response when no location data is available. Indicates that GPS might be disabled or location permission is not granted.

```json
{
  "success": true,
  "data": {
    "executed": true,
    "command": "getLocation",
    "available": false,
    "error": "No location available. Ensure GPS is enabled and location permission is granted.",
    "providers": ["network", "passive"]
  }
}
```

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

### Configure FreeKiosk via ADB for Information Display

Source: https://github.com/rushb-fr/freekiosk/wiki/README

Configure FreeKiosk using ADB commands for a simple URL kiosk with REST API enabled. This example sets the URL, PIN, and REST API port.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es url "https://dashboard.company.com" \
    --es pin "0000" \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080"
```

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

### Navigate to URL

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/MQTT.md

Send a URL to the device to be opened in its web view. Replace BROKER_IP and TOPIC_ID.

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/url" -m "https://example.com"
```

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

### Configure Simple Restaurant Menu Kiosk

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

Sets up FreeKiosk to display a restaurant menu URL. The status bar is disabled for a cleaner display.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es url "https://menu.restaurant.com" \
    --es pin "0000" \
    --es status_bar "false"

```

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

### Provision FreeKiosk Device with Bash Script

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

A complete bash script to provision a new device, setting it as the device owner and configuring FreeKiosk with essential parameters.

```bash
#!/bin/bash
# provision_kiosk.sh - Provision a FreeKiosk device

PACKAGE="com.cloudgaming.app"
PIN="1234"
API_KEY="my_secret_key"

echo "Setting Device Owner..."
adb shell dpm set-device-owner com.freekiosk/.DeviceAdminReceiver

echo "Waiting for device..."
sleep 2

echo "Granting Usage Stats permission (required for foreground monitoring)..."
adb shell appops set com.freekiosk android:get_usage_stats allow

echo "Granting WRITE_SECURE_SETTINGS (required for auto-enabling accessibility service)..."
adb shell pm grant com.freekiosk android.permission.WRITE_SECURE_SETTINGS

echo "Configuring FreeKiosk..."
adb shell am start -n com.freekiosk/.MainActivity \
    --es lock_package "$PACKAGE" \
    --es pin "$PIN" \
    --es auto_relaunch "true" \
    --es test_mode "false" \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080" \
    --es rest_api_key "$API_KEY" \
    --ez auto_start true

echo "✅ Device provisioned!"
echo "   Locked to: $PACKAGE"
echo "   REST API: http://<device-ip>:8080"

```

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

### Turn Screen On/Off

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/MQTT.md

Publish an MQTT message to control the device screen state. Replace BROKER_IP and TOPIC_ID.

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/screen" -m "ON"
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/screen" -m "OFF"
```

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

### cURL: Get tablet GPS location

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current GPS location data from the tablet via an API GET request.

```bash
# Get GPS location
curl http://TABLET_IP:8080/api/location
```

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

### MQTT Topic Structure Examples

Source: https://github.com/rushb-fr/freekiosk/wiki/INTEGRATIONS

Illustrates the topic structure for FreeKiosk MQTT communication, covering device availability, sensor data, and command subscriptions. Replace 'lobby' with your device's specific topic name if applicable.

```plaintext
freekiosk/lobby/availability         # Device online/offline
freekiosk/lobby/state                # All sensor data (JSON)
freekiosk/lobby/set/brightness       # Set brightness command
freekiosk/lobby/set/url              # Navigate to URL
```

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

### Configure FreeKiosk with Full JSON Configuration

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

Shows how to configure FreeKiosk using a single JSON string for complex setups. It also provides an alternative using individual parameters, which is recommended for shell scripts due to easier escaping.

```bash
# Linux/Mac - use single quotes for JSON

```

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es pin "1234" \
    --es config '{"lock_package":"com.app","auto_relaunch":"true"}'

```

```bash
# Or use individual parameters (recommended for shell scripts)

```

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es lock_package "com.app" \
    --es auto_relaunch "true" \
    --es status_bar "true" \
    --es rest_api_enabled "true" \
    --es rest_api_port "8080" \
    --es pin "1234"

```

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

### Get Status

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/rest-api.md

Retrieves the current status of the device.

```APIDOC
## GET /api/status

### Description
Retrieves the current status of the device.

### Method
GET

### Endpoint
/api/status

### Response
#### Success Response (200)
- **status** (object) - Device status information.

### Request Example
```bash
curl http://TABLET_IP:8080/api/status
```
```

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

### Control Freekiosk Device via MQTT

Source: https://github.com/rushb-fr/freekiosk/wiki/MQTT

Use these mosquitto_pub commands to send instructions to your Freekiosk device. Replace BROKER_IP with your MQTT broker's IP address and TOPIC_ID with your device's identifier.

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/screen" -m "ON"
```

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/url" -m "https://example.com"
```

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/reload" -m "PRESS"
```

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/audio_play" -m '{"url":"https://example.com/sound.mp3","volume":50}'
```

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/tts" -m "Hello from Home Assistant"
```

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/toast" -m "Hello!"
```

```bash
mosquitto_pub -h BROKER_IP -t "freekiosk/TOPIC_ID/set/motion_always_on" -m "ON"
```

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

### GET /api/camera/list

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Lists the available cameras on the device.

```APIDOC
## GET /api/camera/list

### Description
List available cameras on the device.

### Method
GET

### Endpoint
/api/camera/list

### Response
#### Success Response (200)
- **cameras** (array) - A list of available cameras.
  - **id** (string) - Unique identifier for the camera.
  - **facing** (string) - Direction the camera is facing (`front` or `back`).
  - **maxWidth** (integer) - Maximum supported photo width.
  - **maxHeight** (integer) - Maximum supported photo height.

### Response Example
```json
{
  "success": true,
  "data": {
    "cameras": [
      { "id": "0", "facing": "back", "maxWidth": 4032, "maxHeight": 3024 },
      { "id": "1", "facing": "front", "maxWidth": 2560, "maxHeight": 1920 }
    ]
  }
}
```
```

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

### Configure FreeKiosk via ADB for Cloud Gaming

Source: https://github.com/rushb-fr/freekiosk/wiki/README

Configure FreeKiosk using ADB commands to lock onto a specific application like Steam Link for cloud gaming. This example sets the lock package, PIN, and enables auto-start.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es lock_package "com.valvesoftware.steamlink" \
    --es pin "1234" \
    --es test_mode "false" \
    --ez auto_start true
```

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

### Configure Home Assistant Dashboard in WebView Mode

Source: https://github.com/rushb-fr/freekiosk/wiki/features-and-modes

Use this ADB command to launch FreeKiosk in WebView mode, specifically configured for a Home Assistant dashboard. Requires the 'url' and 'pin' parameters.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es url "https://homeassistant.local:8123" \
    --es pin "1234"
```

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

### Get Status

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current status of the FreeKiosk device.

```APIDOC
## GET /api/status

### Description
Retrieves the current status of the FreeKiosk device.

### Method
GET

### Endpoint
/api/status

### Response
#### Success Response (200)
- **status** (object) - Contains various status details of the device.

### Request Example
```bash
curl http://TABLET_IP:8080/api/status
```
```

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

### Get Tablet Screenshot

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves a screenshot of the tablet screen.

```APIDOC
## GET /api/screenshot

### Description
Retrieves a screenshot of the tablet screen.

### Method
GET

### Endpoint
http://TABLET_IP:8080/api/screenshot

### Response
#### Success Response (200)
- **image/png** - The screenshot image in PNG format.
```

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

### MQTT CLI: Subscribe to all FreeKiosk topics

Source: https://github.com/rushb-fr/freekiosk/wiki/MQTT

Use this command to subscribe to all topics published by FreeKiosk. Replace BROKER_IP with your MQTT broker's IP address.

```bash
mosquitto_sub -h BROKER_IP -t "freekiosk/#" -v
```

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

### GET /api/health

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Performs a simple health check on the device.

```APIDOC
## GET /api/health

### Description
Simple health check.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the device (e.g., "ok").

### Response Example
```json
{
  "success": true,
  "data": { "status": "ok" }
}
```
```

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

### Wiki Sync Workflow Commands

Source: https://github.com/rushb-fr/freekiosk/wiki/pipeline-and-wiki-sync

This bash script outlines the commands used to clone the wiki repository, synchronize files using rsync, copy the README to Home.md, and commit/push the changes.

```bash
git clone https://github.com/user/repo.wiki.git
rsync --delete docs/ wiki/
cp docs/README.md wiki/Home.md
cd wiki && git add . && git commit -m "Sync docs" && git push
```

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

### GET /api/brightness

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current screen brightness level.

```APIDOC
## GET /api/brightness

### Description
Returns the current screen brightness level.

### Method
GET

### Endpoint
/api/brightness

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the brightness details.
  - **brightness** (number) - The current screen brightness level.

### Response Example
```json
{
  "success": true,
  "data": { "brightness": 75 }
}
```
```

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

### REST API Method Handling

Source: https://github.com/rushb-fr/freekiosk/blob/main/CHANGELOG.md

Updates control endpoints to accept both GET and POST methods. Endpoints that do not require a request body now support both GET and POST, while endpoints requiring a body remain POST-only. Incorrect methods for POST-only endpoints now return a 405 error.

```APIDOC
## REST API Method Handling

### Description
Control endpoints have been updated to accept both GET and POST HTTP methods for increased flexibility.

### Endpoint Behavior
- Endpoints that do not require a request body (e.g., `/api/screen/on`, `/api/reboot`, `/api/reload`) now accept either GET or POST requests.
- Endpoints that require a request body (e.g., `/api/url`, `/api/tts`, `/api/brightness`) remain exclusively POST-only.

### Error Response
Requests made with an incorrect HTTP method to POST-only endpoints will now return a `405 Method Not Allowed` error, instead of the previous `404 Not Found`.
```

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

### Multi-App Kiosk Configuration

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/adb-configuration.md

Configures FreeKiosk to manage a home screen grid with multiple specified applications. Apps can be set to launch on boot and remain alive. Display names can be customized.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es external_app_mode "multi" \
    --es managed_apps '[{"packageName":"com.spotify.music"},{"packageName":"com.netflix.mediaclient"},{"packageName":"com.youtube","launchOnBoot":true,"keepAlive":true}]' \
    --es pin "1234" \
    --es test_mode "false"

```

```bash
--es managed_apps '[{"packageName":"com.app","displayName":"My Custom Name"}]'

```

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

### Get GPS Location

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/rest-api.md

Retrieves the current GPS location of the device.

```APIDOC
## GET /api/location

### Description
Retrieves the current GPS location of the device.

### Method
GET

### Endpoint
/api/location

### Response
#### Success Response (200)
- **location** (object) - GPS location data (latitude, longitude, etc.).

### Request Example
```bash
curl http://TABLET_IP:8080/api/location
```
```

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

### GET /api/screenshot

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Captures and returns the current screen as a PNG image.

```APIDOC
## GET /api/screenshot

### Description
Returns a PNG image of the current screen.

### Method
GET

### Endpoint
/api/screenshot

### Response
#### Success Response (200)
- **Content-Type**: `image/png`
- **Response Body**: Binary PNG image data.

### Usage Examples
```bash
# Save screenshot to file
curl http://TABLET_IP:8080/api/screenshot -o screenshot.png

# Display in HTML
<img src="http://TABLET_IP:8080/api/screenshot" />
```
```

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

### Enable Kiosk Mode with Auto-Start

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

Enables kiosk mode for a specified package and automatically starts the app after configuration. This snippet uses ADB to send the configuration command and then monitors logcat for a specific broadcast to confirm completion.

```typescript
private async setupKioskModeUsingFreeKiosk(packageName: string): Promise<void> {
  console.log(`Setting up kiosk mode for ${packageName}...`);

  // Start listening for EXTERNAL_APP_LAUNCHED broadcast
  const appLaunchMonitor = this.execAsync(
    `adb -s ${this.adbTarget} logcat -c && adb -s ${this.adbTarget} logcat -s "FreeKiosk-ADB" | grep -m 1 "EXTERNAL_APP_LAUNCHED: ${packageName}"`
  );

  // Send configuration command with auto_start
  const kioskCmd = `adb -s ${this.adbTarget} shell am start -n com.freekiosk/.MainActivity --es lock_package "${packageName}" --es pin "${PIN}" --ez auto_start true`;
  await this.execAsync(kioskCmd);

  // Wait for external app to be launched and visible (timeout after 30s)
  console.log("Waiting for app to launch...");
  await Promise.race([
    appLaunchMonitor,
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error('App launch timeout after 30s')), 30000)
    )
  ]);

  console.log(`✅ ${packageName} is now running and ready!`);
  // Start sending video/content here
}
```

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

### GET /api/wifi

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current Wi-Fi connection status and details.

```APIDOC
## GET /api/wifi

### Description
Retrieves the current Wi-Fi connection status and details.

### Method
GET

### Endpoint
/api/wifi

### Response
#### Success Response (200)
- **connected** (boolean) - Whether the device is connected to Wi-Fi.
- **ssid** (string) - The SSID of the connected Wi-Fi network.
- **rssi** (integer) - Received Signal Strength Indicator.
- **ip** (string) - The IP address of the device.

### Response Example
```json
{
  "success": true,
  "data": {
    "connected": true,
    "ssid": "HomeNetwork",
    "rssi": -45,
    "ip": "192.168.1.50"
  }
}
```
```

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

### GET /api/storage

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves information about the device's storage usage.

```APIDOC
## GET /api/storage

### Description
Retrieves information about the device's storage usage.

### Method
GET

### Endpoint
/api/storage

### Response
#### Success Response (200)
- **totalMB** (integer) - Total storage in megabytes.
- **availableMB** (integer) - Available storage in megabytes.
- **usedMB** (integer) - Used storage in megabytes.
- **usedPercent** (integer) - Percentage of storage used.

### Response Example
```json
{
  "success": true,
  "data": {
    "totalMB": 32000,
    "availableMB": 15000,
    "usedMB": 17000,
    "usedPercent": 53
  }
}
```
```

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

### GET|POST /api/screen/on

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/rest-api.md

Turns the screen on or wakes the device. The behavior may depend on the device's privilege level (e.g., Device Owner, Device Admin).

```APIDOC
## GET|POST /api/screen/on

### Description
Turn screen on / wake device.

### Method
GET or POST

### Endpoint
/api/screen/on

### Parameters
(None)

### Request Example
(No request body documented)

### Response
(No specific success response documented)
```

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

### Get GPS Location

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current GPS location of the FreeKiosk device.

```APIDOC
## GET /api/location

### Description
Retrieves the current GPS location of the FreeKiosk device.

### Method
GET

### Endpoint
/api/location

### Response
#### Success Response (200)
- **location** (object) - Contains latitude and longitude information.

### Request Example
```bash
curl http://TABLET_IP:8080/api/location
```
```

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

### Get Tablet Camera Photo

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves a photo from the specified tablet camera.

```APIDOC
## GET /api/camera/photo?camera={camera}&quality={quality}

### Description
Retrieves a photo from the specified tablet camera.

### Method
GET

### Endpoint
http://TABLET_IP:8080/api/camera/photo

### Parameters
#### Query Parameters
- **camera** (string) - Required - The camera to use ('back' or 'front').
- **quality** (integer) - Optional - The desired image quality (0-100). Defaults to 80.
```

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

### Configure Kiosk Mode and Wait for Completion

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

Configures kiosk mode for a given package and waits for the FreeKiosk settings to be loaded using logcat. This script automates the process of setting up kiosk mode and confirms its completion.

```bash
#!/bin/bash
PACKAGE="com.example.app"
PIN="1234"

# Monitor logcat for completion marker in background
adb logcat -c
adb logcat -s "FreeKiosk-ADB" | grep -m 1 "SETTINGS_LOADED" &
LOGCAT_PID=$!

# Send configuration
adb shell am start -n com.freekiosk/.MainActivity \
    --es lock_package "$PACKAGE" \
    --es pin "$PIN" \
    --ez auto_start true

# Wait for completion (with 30s timeout)
timeout 30 wait $LOGCAT_PID

echo "Configuration complete!"
```

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

### Verify ADB Connection on Windows

Source: https://github.com/rushb-fr/freekiosk/wiki/installation

Navigates to the platform-tools directory and lists connected devices to verify ADB connection.

```bash
cd C:\platform-tools
adb devices
```

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

### GET /api/camera/photo

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Takes a photo using the device camera with specified parameters.

```APIDOC
## GET /api/camera/photo

### Description
Take a photo using the device camera.

### Method
GET

### Endpoint
/api/camera/photo

### Query Parameters
- **camera** (string) - Optional - Camera to use: `front` or `back`. Defaults to `back`.
- **quality** (integer) - Optional - JPEG compression quality (1-100). Defaults to `80`.

### Response
#### Success Response (200)
- **Content-Type**: `image/jpeg`
- **Response Body**: Binary JPEG image data.

### Examples
```
GET /api/camera/photo?camera=back&quality=80
GET /api/camera/photo?camera=front&quality=60
```
```

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

### Configure MQTT Settings via ADB Intents

Source: https://github.com/rushb-fr/freekiosk/blob/main/CHANGELOG.md

Use ADB intents to configure all MQTT settings for automated tablet provisioning. All 11 MQTT parameters are supported.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es mqtt_enabled "true" \
    --es mqtt_broker_url "broker.local" \
    --es mqtt_port "1883" \
    --es mqtt_username "user" \
    --es mqtt_password "pass"
```

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

### GET /api/memory

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves information about the device's memory (RAM) usage.

```APIDOC
## GET /api/memory

### Description
Retrieves information about the device's memory (RAM) usage.

### Method
GET

### Endpoint
/api/memory

### Response
#### Success Response (200)
- **totalMB** (integer) - Total memory in megabytes.
- **availableMB** (integer) - Available memory in megabytes.
- **usedMB** (integer) - Used memory in megabytes.
- **usedPercent** (integer) - Percentage of memory used.
- **lowMemory** (boolean) - Indicates if the device is experiencing low memory.

### Response Example
```json
{
  "success": true,
  "data": {
    "totalMB": 4096,
    "availableMB": 2048,
    "usedMB": 2048,
    "usedPercent": 50,
    "lowMemory": false
  }
}
```
```

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

### Get Current Media Volume

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current media volume level of the device.

```APIDOC
## GET /api/volume

### Description
Get current media volume.

### Method
GET

### Endpoint
/api/volume

### Response
#### Success Response (200)
- **data** (object) - Contains volume information.
  - **level** (integer) - The current volume level.
  - **maxLevel** (integer) - The maximum possible volume level.

#### Response Example
```json
{
  "success": true,
  "data": { "level": 80, "maxLevel": 100 }
}
```
```

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

### Configure Multi-App Kiosk

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

Configures FreeKiosk to manage a home screen grid with multiple specified applications. It allows setting specific apps to launch on boot and to be kept alive.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es external_app_mode "multi" \
    --es managed_apps '[{"packageName":"com.spotify.music"},{"packageName":"com.netflix.mediaclient"},{"packageName":"com.youtube","launchOnBoot":true,"keepAlive":true}]' \
    --es pin "1234" \
    --es test_mode "false"

```

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

### GET /api/sensors

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves data from the device's light, proximity, and accelerometer sensors.

```APIDOC
## GET /api/sensors

### Description
Returns light, proximity, and accelerometer data.

### Method
GET

### Endpoint
/api/sensors

### Response
#### Success Response (200)
- **light** (float) - Ambient light level.
- **proximity** (integer) - Proximity sensor reading.
- **accelerometer** (object) - Accelerometer data.
  - **x** (float) - X-axis acceleration.
  - **y** (float) - Y-axis acceleration.
  - **z** (float) - Z-axis acceleration.

### Response Example
```json
{
  "success": true,
  "data": {
    "light": 150.5,
    "proximity": 5,
    "accelerometer": { "x": 0.1, "y": 0.2, "z": 9.8 }
  }
}
```
```

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

### GET /api/screen

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current status of the physical screen and any active screensaver overlay.

```APIDOC
## GET /api/screen

### Description
Returns screen status with separated physical and overlay states.

### Method
GET

### Endpoint
/api/screen

### Response
#### Success Response (200)
- **on** (boolean) - Physical screen state.
- **brightness** (integer) - Current brightness percentage (0-100).
- **screensaverActive** (boolean) - Whether the screensaver overlay is showing.

### Response Example
```json
{
  "success": true,
  "data": {
    "on": true,
    "brightness": 75,
    "screensaverActive": false
  }
}
```
```

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

### Run on Android Device

Source: https://github.com/rushb-fr/freekiosk/blob/main/CONTRIBUTING.md

Build and run the FreeKiosk application on a connected Android device.

```bash
npm run android
```

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

### GET /api/autoBrightness

Source: https://github.com/rushb-fr/freekiosk/blob/main/docs/rest-api.md

Retrieves the current status of the auto-brightness feature, including whether it is enabled and its configuration.

```APIDOC
## GET /api/autoBrightness

### Description
Get current auto-brightness status.

### Method
GET

### Endpoint
/api/autoBrightness

### Parameters
(None)

### Request Example
(No request body documented)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the auto-brightness status.
  - **enabled** (boolean) - Whether auto-brightness is currently enabled.
  - **min** (integer) - The minimum brightness percentage.
  - **max** (integer) - The maximum brightness percentage.
  - **currentLightLevel** (float) - The current ambient light level detected.

### Response Example
```json
{
  "success": true,
  "data": {
    "enabled": true,
    "min": 10,
    "max": 100,
    "currentLightLevel": 250.5
  }
}
```
```

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

### Get Effective Scale

Source: https://github.com/rushb-fr/freekiosk/blob/main/android/app/src/main/assets/pdfjs/viewer.html

Returns the current zoom scale, defaulting to fit-width scale if currentScale is 0.

```javascript
function getEffectiveScale() {
  return currentScale === 0 ? fitWidthScale : currentScale;
}
```

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

### Configure Cloud Gaming Kiosk with Auto-Relaunch

Source: https://github.com/rushb-fr/freekiosk/wiki/adb-configuration

Sets up FreeKiosk to lock onto a game streaming app, enabling auto-relaunch and production mode. The `test_mode "false"` setting ensures the Android back button immediately relaunches the app.

```bash
adb shell am start -n com.freekiosk/.MainActivity \
    --es lock_package "com.valvesoftware.steamlink" \
    --es pin "1234" \
    --es auto_relaunch "true" \
    --es test_mode "false" \
    --ez auto_start true

```

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

### Clear Metro Bundler Cache

Source: https://github.com/rushb-fr/freekiosk/wiki/development

If the Metro bundler fails to start, try clearing its cache by running this command.

```bash
npm start -- --reset-cache
```

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

### Get Screen State via REST API

Source: https://github.com/rushb-fr/freekiosk/blob/main/CHANGELOG.md

Retrieve the current state of the physical screen and the screensaver overlay.

```http
GET /api/screen
```

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

### Make Deployment Script Executable

Source: https://github.com/rushb-fr/freekiosk/blob/main/scripts/README.md

Sets execute permissions on the deployment script. This command must be run once before executing the script.

```bash
chmod +x deploy_mac.zsh
```

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

### GET|POST /api/screen/on

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Turns the device screen on or wakes the device. The behavior and effectiveness may vary depending on device privileges (No privileges, Device Admin, AccessibilityService, Device Owner).

```APIDOC
## GET|POST /api/screen/on

### Description
Turn screen on / wake device.

### Method
GET or POST

### Endpoint
/api/screen/on

### Parameters
(No parameters required)

### Response
#### Success Response (200)
(No specific success response schema provided in source)

> ⚠️ **Device Owner Required for Full Screen Control**
> 
> | Feature | No privileges | Device Admin | AccessibilityService (API 28+) | Device Owner |
> |---------|--------------|--------------|-------------------------------|---------------|
> | `screen/on` | Restores brightness | Wakes device | Wakes device | Wakes device |
> 
> **Understanding `"on"` vs `"screensaverActive"`:**  
> - `"on"` reports the **physical screen state** (PowerManager.isInteractive)
> - `"screensaverActive"` reports whether the **screensaver overlay** is showing
> - These are **independent**: screensaver can be active while screen is physically on
```

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

### cURL: Get tablet status

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Use this command to retrieve the current status information from the tablet's API.

```bash
# Get status
curl http://TABLET_IP:8080/api/status
```

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

### Get Current Media Volume

Source: https://github.com/rushb-fr/freekiosk/wiki/rest-api

Retrieves the current media volume level and the maximum possible volume level.

```json
{
  "success": true,
  "data": { "level": 80, "maxLevel": 100 }
}
```