openapi: 3.1.0

info:
  title: Raspi ESP API
  version: 1.0.0
  description: |
    Raspi ESP API is a simple state-based HTTP API designed as a demonstrator
    for controlling physical devices using a remote decision-making model
    (such as ChatGPT).

    The system consists of:
    - a Node.js HTTP server (this API),
    - an ESP32 microcontroller acting purely as a renderer,
    - a remote client (e.g. ChatGPT) that decides what should be displayed.

    The API does not control hardware directly.
    Instead, it stores the desired visual state:
    - text for a small OLED display (2 lines),
    - RGB values for an 8x8 WS2812B LED matrix.

    The ESP32 periodically polls this API (read-only)
    and renders the current state on physical devices.

    This architecture intentionally separates:
    - decision logic (client / model),
    - state storage (server),
    - hardware rendering (ESP).

servers:
  - url: https://api.raspi4.fun

paths:

  /get-oled:
    get:
      operationId: getOled
      summary: Get current OLED text
      description: |
        Returns the current text assigned to the OLED display.
        The OLED consists of two text lines, each with a maximum length of 9 characters.
      responses:
        "200":
          description: OLED text state
          content:
            application/json:
              schema:
                type: object
                properties:
                  line1:
                    type: string
                    maxLength: 9
                    description: First line of the OLED display
                  line2:
                    type: string
                    maxLength: 9
                    description: Second line of the OLED display
                required:
                  - line1
                  - line2

  /get-matrix:
    get:
      operationId: getMatrix
      summary: Get current LED matrix state
      description: |
        Returns the current state of the 8x8 RGB LED matrix.
        Each pixel is represented as an array [R, G, B],
        where values are in the range 0–255.
      responses:
        "200":
          description: LED matrix state
          content:
            application/json:
              schema:
                type: array
                minItems: 64
                maxItems: 64
                items:
                  type: array
                  minItems: 3
                  maxItems: 3
                  items:
                    type: integer
                    minimum: 0
                    maximum: 255

  /set-oled:
    post:
      operationId: setOled
      summary: Set OLED text
      description: |
        Sets the desired text for the OLED display.
        Text is stored on the server and later rendered by the ESP32.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                line1:
                  type: string
                  maxLength: 9
                line2:
                  type: string
                  maxLength: 9
      responses:
        "200":
          description: Operation status
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

  /set-matrix:
    post:
      operationId: setMatrix
      summary: Set LED matrix state
      description: |
        Sets the desired RGB values for the 8x8 LED matrix.
        The server normalizes the data to exactly 64 pixels.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pixels:
                  type: array
                  items:
                    type: array
                    minItems: 3
                    maxItems: 3
                    items:
                      type: integer
                      minimum: 0
                      maximum: 255
      responses:
        "200":
          description: Operation status
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean

security: []