openapi.yaml

openapi: "3.0.0"
info:
  title: "SenseHat Listener"
  description: "This API allows remote or local applications to easily manage the output of the SenseHat 8x8 LED display in a structured way."
  version: "1.0.0"
  termsOfService: "https://github.com/sircinnamon/SenseHatListener/blob/master/README.md"
  contact:
    name: "Riley Lahd"
    email: "sircinnamon@gmail.com"
    url: "https://github.com/sircinnamon"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
servers:
- url: "https://thor.sircinnamon.ca/sensehat/api"
# basePath: "/api"
# schemes:
# - "http"
# consumes:
# - "application/json"
paths:
  /queue:
    get:
      summary: "Get the current queue length"
      description: "Get the number of posted states waiting to be displayed"
      operationId: "getQueue"
      responses:
        200:
          description: "Successful GET"
          content:
            application/json:
              schema:
                properties:
                  length:
                    type: integer
              example:
                length: 5
    delete:
      summary: "Clear job queue"
      description: "Clear the queue of all jobs not already picked up by the worker thread."
      operationId: "deleteQueue"
      responses:
        200:
          description: "Cleared job queue"
        401:
          description: "User is not authenticated"
  /grid:
    get:
      summary: "Get the current grid content"
      description: "Get the map representing the current grid"
      operationId: "getGrid"
      responses:
        200:
          description: "Successful GET"
          content:
            application/json:
              schema:
                properties:
                  map:
                    $ref: "#/components/schemas/2dmap"
  /string:
    post:
      summary: "Input a string to scroll across the grid"
      description: "Input text will scroll across the screen from right to left. Speed, text colour and backing colour are configurable."
      operationId: "postString"
      requestBody:
        description: "JSON containing the data and options"
        required: True
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/stringSchema"
      responses:
        200:
          description: "Body recieved and queued for display"
        400:
          description: "Request was malformed"
        401:
          description: "User is not authenticated"
  /map:
    post:
      summary: "Input an 8x8 Map to display on the grid"
      description: "8x8 Map of RGB values will be displayed on the 8x8 LED Grid"
      operationId: "postMap"
      requestBody:
        description: "JSON containing the data and options"
        required: True
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/mapSchema"
      responses:
        200:
          description: "Body recieved and queued for display"
        400:
          description: "Request was malformed"
        401:
          description: "User is not authenticated"
  /sequence:
    post:
      summary: "Input a start state and set of steps to display in sequence"
      description: "Starting with start state on screen each step will be read and displayed. Steps can be whole maps, lists of specific pixels, or a single pixel."
      operationId: "postSequence"
      requestBody:
        description: "JSON containing the data and options"
        required: True
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/sequenceSchema"
      responses:
        200:
          description: "Body recieved and queued for display"
        400:
          description: "Request was malformed"
        401:
          description: "User is not authenticated"
  /passive:
    post:
      summary: "Input a passive state for the board to display when no other actions are queued"
      description: "Set a passive state for the board or for individual pixels. This can be used for 'always on' status lights or other persistent uses."
      operationId: "postPassive"
      requestBody:
        description: "JSON containing the data and options"
        required: True
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/passiveSchema"
      responses:
        200:
          description: "Body recieved and queued for display"
        400:
          description: "Request was malformed"
        401:
          description: "User is not authenticated"
    get:
      summary: "Get the current passive state"
      description: "Get the map representing the idle state of the board when it is not handling tasks."
      operationId: "getPassive"
      responses:
        200:
          description: "Successful GET"
          content:
            application/json:
              schema:
                properties:
                  map:
                    $ref: "#/components/schemas/2dmap"
    delete:
      summary: "Clear passive state"
      description: "Set a blank passive state for the entire board. If something set a passive state and never cleared it this can be used."
      operationId: "deletePassive"
      responses:
        200:
          description: "Cleared passive state"
        401:
          description: "User is not authenticated"
  /flash:
    post:
      summary: "Input an 8x8 Map to flash on the LED grid"
      description: "As with the Map endpoint, but this will flash on and off at a configurable interval"
      operationId: "postFlash"
      requestBody:
        description: "JSON containing the data and options"
        required: True
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/flashSchema"
      responses:
        200:
          description: "Body recieved and queued for display"
        400:
          description: "Request was malformed"
        401:
          description: "User is not authenticated"
  /scroll:
    post:
      summary: "Input an 8x8 Map to scroll across the LED grid"
      description: "As with the Map endpoint, but this will scroll across the grid in a given direction"
      operationId: "postScroll"
      requestBody:
        description: "JSON containing the data and options"
        required: True
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/scrollSchema"
      responses:
        200:
          description: "Body recieved and queued for display"
        400:
          description: "Request was malformed"
        401:
          description: "User is not authenticated"
  /spin:
    post:
      summary: "Input an 8x8 Map to rotate on the LED grid"
      description: "As with the Map endpoint, but this will rotate around the grid in a given direction"
      operationId: "postSpin"
      requestBody:
        description: "JSON containing the data and options"
        required: True
        content:
          application/json:
            schema: 
              $ref: "#/components/schemas/spinSchema"
      responses:
        200:
          description: "Body recieved and queued for display"
        400:
          description: "Request was malformed"
        401:
          description: "User is not authenticated"
components:
  schemas:
    stringSchema:
      title: "stringSchema"
      description: "Post object for string display"
      type: "object"
      example:
        string: "Hello World!"
      properties:
        string:
          description: "String to display"
          type: "string"
          minLength: 1
          maxLength: 32
        colour:
          $ref: "#/components/schemas/RGB"
        background:
          $ref: "#/components/schemas/RGB"
        speed:
          description: "Seconds to wait between 1-pixel shift"
          type: "number"
          minimum: 0.01
          maximum: 1
          default: 0.1
          example: 0.1
          format: "float"
      required:
      - "string"
    mapSchema:
      title: "mapSchema"
      description: "Object containing 1 8x8 Map to display, as 2d (8x8) or 1d (64) array."
      type: "object"
      required:
      - "map"
      properties:
        map:
          $ref: "#/components/schemas/map"
      example: >
        {
          "map": [
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]],
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]],
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]],
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]],
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]],
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]],
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]],
            [[255,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,255,0]]
          ]
        }
    sequenceSchema:
      title: "sequenceSchema"
      description: "Object containing a start state and a sequence of steps representing board states to animate through at given timing."
      type: "object"
      required:
      - "sequence"
      properties:
        start:
          $ref: "#/components/schemas/map"
        sequence:
          type: "array"
          minItems: 1
          items:
            $ref: "#/components/schemas/sequenceStep"
      example: >
        {
          "start": [[255,0,0]],
          "sequence": [
            {
              "pixel": {
                "colour": [255,0,0],
                "x": 1,
                "y": 0
              },
              "delay": 0.5
            },
            {
              "pixel": {
                "colour": [255,0,0],
                "x": 2,
                "y": 0
              },
              "delay": 0.5
            }
          ]
        }
    sequenceStep:
      title:  "sequenceStep"
      description: "Object describing the difference between two map states. Provide one of [ pixels | map | pixel ]"
      oneOf:
      - title:  "sequenceStepMap"
        description: "Set entire grid using a full map object."
        type: "object"
        minProperties: 1
        maxProperties: 2
        required:
        - "map"
        properties:
          map:
            $ref: "#/components/schemas/map"
          delay:
            type: "number"
            format: "float"
            description: "Time (in seconds) to hold the frame"
            minimum: 0
            maximum: 1
      - title:  "sequenceStepPixel"
        description: "Provide a single pixel to update"
        type: "object"
        minProperties: 1
        maxProperties: 2
        required:
        - "pixel"
        properties:
          pixel:
            $ref: "#/components/schemas/pixel"
          delay:
            type: "number"
            format: "float"
            description: "Time (in seconds) to hold the frame"
            minimum: 0
            maximum: 1
      - title:  "sequenceStepPixels"
        description: "Provide a list of pixels to update"
        type: "object"
        minProperties: 1
        maxProperties: 2
        required:
        - "pixels"
        properties:
          pixels:
            description: "An array of colours and XY coords corresponding to single pixel changes"
            type: "array"
            maxItems: 64
            minItems: 2
            items:
              $ref: "#/components/schemas/pixel"
          delay:
            type: "number"
            format: "float"
            description: "Time (in seconds) to hold the frame"
            minimum: 0
            maximum: 1
          
    passiveSchema:
      title:  "passiveSchema"
      description: "Object describing an update to the passive state of the grid. Provide one of [ pixels | map | pixel ]"
      type: "object"
      minProperties: 1
      maxProperties: 1
      properties:
        pixels:
          description: "An array of colours and XY coords corresponding to single pixel changes"
          type: "array"
          maxItems: 64
          minItems: 2
          items:
            $ref: "#/components/schemas/pixel"
        map:
          $ref: "#/components/schemas/map"
        pixel:
          $ref: "#/components/schemas/pixel"
      example: >
        {
          "pixel":{
            "x":5,
            "y":5,
            "colour":[0,255,0]
          }
        }
    flashSchema:
      title:  "flashSchema"
      description: "Object containing 1 8x8 Map to flash on the LED grid"
      type: "object"
      required:
      - "map"
      properties:
        map:
          $ref: "#/components/schemas/map"
        ontime:
          type: "number"
          format: "float"
          description: "Time (in seconds) to hold the state on"
          minimum: 0
          maximum: 1
        offtime:
          type: "number"
          format: "float"
          description: "Time (in seconds) to hold the state off"
          minimum: 0
          maximum: 1
        loops:
          type: "integer"
      example: >
        {
          "map": [
            [[30,0,0],[],[],[],[],[],[],[0,30,0]],
            [[60,0,0],[],[],[],[],[],[],[0,60,0]],
            [[90,0,0],[],[],[],[],[],[],[0,90,0]],
            [[120,0,0],[],[],[],[],[],[],[0,120,0]],
            [[150,0,0],[],[],[],[],[],[],[0,150,0]],
            [[180,0,0],[],[],[],[],[],[],[0,180,0]],
            [[210,0,0],[],[],[],[],[],[],[0,210,0]],
            [[240,0,0],[],[],[],[],[],[],[0,240,0]]
          ],
          "ontime": 1,
          "offtime": 0.3,
          "loops": 15
        }
    scrollSchema:
      title:  "scrollSchema"
      description: "Object containing 1 8x8 Map to scroll across the LED grid"
      type: "object"
      required:
      - "map"
      properties:
        map:
          $ref: "#/components/schemas/map"
        direction:
          description: "Representing the direction with 4 cardinals and 4 diagonals. 0 is UP, 4 is DOWN, 7 is UP+LEFT, etc..."
          type: "integer"
          minimum: 0
          maximum: 7
        speed:
          type: "number"
          format: "float"
          description: "Time (in seconds) to hold each frame of the scroll"
          minimum: 0
          maximum: 1
      example: >
        {
          "map": [
            [[],[],[],[0,0,255],[],[],[],[]],
            [[],[],[0,255,0],[],[],[],[],[]],
            [[],[255,255,0],[],[],[],[],[],[]],
            [[255,0,0],[255,0,0],[255,0,0],[255,0,0],[255,0,0],[255,0,0],[255,0,0],[255,0,0]],
            [[],[255,255,0],[],[],[],[],[],[]],
            [[],[],[0,255,0],[],[],[],[],[]],
            [[],[],[],[0,0,255],[],[],[],[]],
            [[],[],[],[],[],[],[],[]]
          ],
          "direction": 6,
          "speed": 1
        }
    spinSchema:
      title:  "spinSchema"
      description: "Object containing 1 8x8 Map to rotate on the LED grid"
      type: "object"
      required:
      - "map"
      properties:
        map:
          $ref: "#/components/schemas/map"
        counterclockwise:
          type: "boolean"
          default: false
        loops:
          type: "integer"
        delay:
          type: "number"
          format: "float"
          description: "Time (in seconds) to hold each frame of the scroll"
          minimum: 0
          maximum: 1
      example: >
        {
          "map": [
              [[255,255,255],[255,255,255],[255,255,255]],
              [[255,255,255]],
              [[255,255,255]]
            ],
          "loops": 20,
          "delay": 0.5,
          "counterclockwise": false
        }
        
    RGB:
      description: "An RGB colour value. Missing values are assumed to be zeros, i.e. [] = [0,0,0], [0, 255] = [0,255,0]"
      type: "array"
      example: [0,0,0]
      items:
        type: "integer"
        maximum: 255
        minimum: 0
      maxItems: 3
      minItems: 0
    2dmap:
      description: "2-Dimensional (8x8) array of RGB values representing the whole grid. Trailing black pixels or rows can be omitted. Blank rows can be shortened to an empty array."
      type: "array"
      minItems: 0
      maxItems: 8
      items:
        type: "array"
        minItems: 0
        maxItems: 8
        items:
          $ref: "#/components/schemas/RGB"
    1dmap:
      description: "1-Dimensional (1x64) array of RGB values representing the whole grid. Trailing black pixels or rows can be omitted."
      type: "array"
      minItems: 0
      maxItems: 64
      items:
        $ref: "#/components/schemas/RGB"
    map:
      anyOf:
        - $ref: "#/components/schemas/2dmap"
        - $ref: "#/components/schemas/1dmap"
    pixel:
      description: "Represents a pixel's state with its XY coord and RGB colour"
      type: "object"
      required:
      - "colour"
      - "x"
      - "y"
      properties:
        colour:
          $ref: "#/components/schemas/RGB"
        x:
          type: "integer"
          minimum: 0
          maximum: 7
        y:
          type: "integer"
          minimum: 0
          maximum: 7