openapi.yaml

openapi: 3.0.3
info:
  title: LED Panel Control API
  description: API for controlling AM03127 LED panels
  version: 1.0.0
servers:
  - url: http://localhost:80
    description: Local development server
paths:
  /page/{pageId}:
    parameters:
      - name: pageId
        in: path
        required: true
        schema:
          type: string
          pattern: '^[A-Z]$'
        description: Single uppercase letter (A-Z) identifying the page
    get:
      summary: Get a specific page
      description: Retrieves the content and settings of a specific page by ID
      responses:
        '200':
          description: Page found and returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '400':
          description: Invalid page ID
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Page not found
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
    post:
      summary: Create or update a page
      description: Creates a new page or updates an existing page with the specified ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Page'
      responses:
        '200':
          description: Page created or updated successfully
        '400':
          description: Invalid page ID or request body
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
    delete:
      summary: Delete a page
      description: Deletes a page with the specified ID
      responses:
        '200':
          description: Page deleted successfully
        '400':
          description: Invalid page ID
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
  /pages:
    get:
      summary: Get all pages
      description: Retrieves all stored pages
      responses:
        '200':
          description: List of pages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Page'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
    post:
      summary: Create or update multiple pages
      description: Creates or updates multiple pages at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Page'
      responses:
        '200':
          description: Pages created or updated successfully
        '400':
          description: Invalid request body
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
  /schedule/{scheduleId}:
    parameters:
      - name: scheduleId
        in: path
        required: true
        schema:
          type: string
          pattern: '^[A-E]$'
        description: Single uppercase letter (A-E) identifying the schedule
    get:
      summary: Get a specific schedule
      description: Retrieves a specific schedule by ID
      responses:
        '200':
          description: Schedule found and returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '400':
          description: Invalid schedule ID
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Schedule not found
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
    post:
      summary: Create or update a schedule
      description: Creates a new schedule or updates an existing schedule with the specified ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schedule'
      responses:
        '200':
          description: Schedule created or updated successfully
        '400':
          description: Invalid schedule ID or request body
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
    delete:
      summary: Delete a schedule
      description: Deletes a schedule with the specified ID
      responses:
        '200':
          description: Schedule deleted successfully
        '400':
          description: Invalid schedule ID
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
  /schedules:
    get:
      summary: Get all schedules
      description: Retrieves all stored schedules
      responses:
        '200':
          description: List of schedules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
    post:
      summary: Create or update multiple schedules
      description: Creates or updates multiple schedules at once
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Schedule'
      responses:
        '200':
          description: Schedules created or updated successfully
        '400':
          description: Invalid request body
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
  /clock:
    post:
      summary: Set panel clock
      description: Sets the internal clock of the LED panel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DateTime'
      responses:
        '200':
          description: Clock set successfully
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
  /reset:
    post:
      summary: Delete all content
      description: Deletes all pages and schedules from the LED panel
      responses:
        '200':
          description: All content deleted successfully
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
  /ota:
    put:
      summary: Over-the-air firmware update
      description: Uploads a new firmware image for OTA update
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Update successful
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Bad request (wrong content type, invalid content length, or image too large)
          content:
            text/plain:
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
components:
  schemas:
    Font:
      type: string
      enum:
        - Normal
        - Bold
        - Narrow
        - Large
        - Long
      description: Font style for text display
    ColumnStart:
      type: object
      properties:
        column:
          type: integer
          format: uint8
          minimum: 0
          maximum: 255
          description: Starting column position (0-255)
      required:
        - column
      description: Specifies the starting column for text
    Clock:
      type: string
      enum:
        - Date
        - Time
      description: Clock display format
    Leading:
      type: string
      enum:
        - block_move
        - curtain_down
        - curtain_up
        - hold
        - immediate
        - pen_amplus
        - pen_hello_world
        - pen_welcome
        - random
        - scroll_down
        - scroll_left
        - scroll_right
        - scroll_up
        - snow
        - twinkle
        - vclose
        - vopen
        - xopen
      description: Animation effect for page entry
    Lagging:
      type: string
      enum:
        - curtain_down
        - curtain_up
        - hold
        - immediate
        - scroll_down
        - scroll_left
        - scroll_right
        - scroll_up
        - vclose
        - vopen
        - xopen
      description: Animation effect for page exit
    WaitingModeAndSpeed:
      type: string
      enum:
        - fastest_blinking
        - fastest_normal
        - fastest_song1
        - fastest_song2
        - fastest_song3
        - middle_fast_blinking
        - middle_fast_normal
        - middle_fast_song1
        - middle_fast_song2
        - middle_fast_song3
        - middle_slow_blinking
        - middle_slow_normal
        - middle_slow_song1
        - middle_slow_song2
        - middle_slow_song3
        - slowest_blinking
        - slowest_normal
        - slowest_song1
        - slowest_song2
        - slowest_song3
      description: Display mode and speed while waiting
    Page:
      type: object
      properties:
        line:
          type: integer
          format: uint8
          default: 1
          description: Line number (usually 1)
        id:
          type: string
          pattern: '^[A-Z]$'
          default: "A"
          description: Page identifier (A-Z)
        leading:
          $ref: '#/components/schemas/Leading'
          default: "immediate"
          description: Animation effect for page entry
        lagging:
          $ref: '#/components/schemas/Lagging'
          default: "hold"
          description: Animation effect for page exit
        waiting_mode_and_speed:
          $ref: '#/components/schemas/WaitingModeAndSpeed'
          default: "fastest_normal"
          description: Display mode and speed while waiting
        waiting_time:
          type: integer
          format: uint8
          minimum: 0
          maximum: 25
          description: Waiting time between leading and lagging (0=0.5s to 25=25s)
        message:
          type: string
          maxLength: 16
          description: Text content displayed on the page
      required:
        - id
        - message
    Schedule:
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-E]$'
          default: "A"
          description: Schedule identifier (A-E)
        from:
          $ref: '#/components/schemas/ScheduleDateTime'
          description: Start date and time
        to:
          $ref: '#/components/schemas/ScheduleDateTime'
          description: End date and time
        pages:
          type: string
          maxLength: 31
          pattern: '^[A-Z]+$'
          description: String of page IDs to display in sequence (e.g., "ABC")
      required:
        - id
        - from
        - to
        - pages
    DateTime:
      type: object
      properties:
        year:
          type: integer
          format: uint8
          minimum: 0
          maximum: 99
          description: Year (last two digits)
        week:
          type: integer
          format: uint8
          minimum: 1
          maximum: 53
          description: Week of year
        month:
          type: integer
          format: uint8
          minimum: 1
          maximum: 12
          description: Month
        day:
          type: integer
          format: uint8
          minimum: 1
          maximum: 31
          description: Day of month
        hour:
          type: integer
          format: uint8
          minimum: 0
          maximum: 23
          description: Hour (24-hour format)
        minute:
          type: integer
          format: uint8
          minimum: 0
          maximum: 59
          description: Minute
        second:
          type: integer
          format: uint8
          minimum: 0
          maximum: 59
          description: Second
      required:
        - year
        - month
        - day
        - hour
        - minute
        - second
    ScheduleDateTime:
      type: object
      properties:
        year:
          type: integer
          format: uint8
          minimum: 0
          maximum: 99
          description: Year (last two digits)
        month:
          type: integer
          format: uint8
          minimum: 1
          maximum: 12
          description: Month
        day:
          type: integer
          format: uint8
          minimum: 1
          maximum: 31
          description: Day of month
        hour:
          type: integer
          format: uint8
          minimum: 0
          maximum: 23
          description: Hour (24-hour format)
        minute:
          type: integer
          format: uint8
          minimum: 0
          maximum: 59
          description: Minute
      required:
        - year
        - month
        - day
        - hour
        - minute