swagger.yml

openapi: 3.0.0
info:
  title: Xiaomi Light bar for ESP API
  version: 1.1.0
  description: REST API for interacting with the Xiaomi Light bar for ESP system.

servers:
  - url: "http://{host}/"
    description: "API Server for version 1"
    variables:
      host:
        default: "localhost"

tags:
  - name: V1
    description: All endpoints related to Xiaomi Light bar for ESP system interaction.

paths:
  /api/v1/status:
    get:
      tags:
        - V1
      summary: Get system status
      description: Returns system uptime, free heap memory, and IP address.
      responses:
        "200":
          description: System status information
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
                  ip:
                    type: string
                    example: "192.168.1.123"
                  sys_timestamp:
                    type: integer
                    example: "1242013890"
                  free_heap:
                    type: string
                    example: "190.23 KB"
                  uptime:
                    type: string
                    example: "0d 02h 25m 10s"

  /api/v1/wifi/connect:
    post:
      tags:
        - V1
      summary: Connect to Wi-Fi
      description: Attempts to connect to the given Wi-Fi SSID using the provided credentials.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ssid
                - password
              properties:
                ssid:
                  type: string
                  example: "MyNetwork"
                password:
                  type: string
                  example: "mypassword123"
      responses:
        "200":
          description: Successfully connected
        "400":
          description: Invalid request or missing fields
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"

  /api/v1/wifi/scan:
    get:
      tags:
        - V1
      summary: Scan Wi-Fi networks
      description: Performs a scan of available Wi-Fi networks nearby.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: List of available networks
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  networks:
                    type: array
                    items:
                      type: object
                      properties:
                        ssid:
                          type: string
                          example: "MyNetwork"
                        rssi:
                          type: integer
                          example: -55
                        authmode:
                          type: string
                          example: "WPA2_PSK"

  /api/v1/ntp/set:
    post:
      tags:
        - V1
      summary: Set NTP server for time sync
      description: Sync time with the given NTP server
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ntp_domain
              properties:
                ntp_domain:
                  type: string
                  example: "pool.ntp.org"
      responses:
        "200":
          description: Time successfully synchronized with the NTP server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "NTPS sync ok"
        "400":
          description: Bad request (Invalid JSON or missing `ntp_domain`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Missing or invalid NTP domain"
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"
        "500":
          description: Failed to sync with the NTP server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Failed to sync time with NTP"

  /api/v1/logs:
    get:
      tags:
        - V1
      summary: Get ESP32 logs
      description: Returns the captured logs from the ESP32 as an array of log lines (same as idf.py monitor output).
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Successfully retrieved logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  log_lines:
                    type: array
                    items:
                      type: string
                    example:
                      - "I (12345) MAIN: Starting application..."
                      - "I (12346) HTTP_SERVER: Webserver starting on port: 80"
                      - "I (12347) WIFI: Initializing WiFi..."
                  total_lines:
                    type: integer
                    example: 3
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"

  /api/v1/logs/clear:
    delete:
      tags:
        - V1
      summary: Clear ESP32 logs
      description: Clears the log buffer, removing all captured logs.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Logs successfully cleared
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Logs cleared"
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"

  /api/v1/nrf24/scan:
    get:
      tags:
        - V1
      summary: Scan for Xiaomi remote control
      description: Performs a scan to detect and decode the Xiaomi remote control ID from NRF24 radio packets. The scan listens on multiple 2.4 GHz channels and classifies received commands (on/off, cooler, warmer, higher, lower, reset).
      security:
        - ApiKeyAuth: []
      parameters:
        - name: duration
          in: query
          description: Duration of the scan in seconds (1-60). Default is 10 seconds.
          schema:
            type: integer
            minimum: 1
            maximum: 60
            default: 10
            example: 10
      responses:
        "200":
          description: Scan completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the scan detected a remote control ID
                    example: true
                  xiaomi_remote_id:
                    type: string
                    description: The detected remote control ID in hexadecimal format (null if not detected)
                    example: "0x700000"
                  xiaomi_id_saved:
                    type: boolean
                    description: Indicates if the detected ID was successfully persisted to NVS
                    example: true
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"

  /api/v1/xiaomi/set-id:
    post:
      tags:
        - V1
      summary: Manually set the Xiaomi remote ID
      description: Persists a provided Xiaomi remote ID into NVS storage.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - xiaomi_remote_id
              properties:
                xiaomi_remote_id:
                  type: string
                  description: Xiaomi remote control ID in hexadecimal format
                  example: "0x700000"
      responses:
        "200":
          description: Xiaomi ID saved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Xiaomi ID saved successfully"
                  xiaomi_id:
                    type: string
                    example: "0x700000"
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"

  /api/v1/xiaomi/get-id:
    get:
      tags:
        - V1
      summary: Retrieve the stored Xiaomi remote ID
      description: Reads the Xiaomi remote ID persisted in NVS storage and returns it if present.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Xiaomi ID read result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Return the NVS stored remote ID
                    example: true
                  xiaomi_id:
                    type: string
                    nullable: true
                    description: Stored Xiaomi remote ID, or null if not set
                    example: "0x700000"
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"

  /api/v1/xiaomi/power/toogle:
    post:
      tags:
        - V1
      summary: Toggle Xiaomi light bar power
      description: Sends a power toggle command to the Xiaomi light bar using the stored remote ID.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Command sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  xiaomi_remote_id:
                    type: string
                    example: "0x700000"
                  command:
                    type: string
                    example: "power_toggle"
                  status:
                    type: string
                    example: "ESP_OK"
        "401":
          description: Unauthorized (missing or invalid X-API-Key)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: "Unauthorized"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key required for protected endpoints.