DOC_DataSourceInterface_AsyncAPI

asyncapi: 3.0.0
id: 'urn:com:example:devicesamplingapi'
info:
  title: Data Source Interface of OmnAIScopes
  version: 0.1.0
  description: |
    This interface description documents the interface to the OmnAIScope-Backend v0.4.0: https://github.com/AI-Gruppe/OmnAIScope-DataServer/releases/tag/v0.4.0 . 
    The interface consists of a REST API endpoint and a WebSocket connection.
    A data source has one or more data streams, each data stream has a UUID and a color.
    Currently the port on which OmnAIView is running is set to 8080. 
    
    1. **Data Source List (HTTP GET)**
       - **URL:** `http://<ip>:8080/UUID`
       - **Description:** Returns a list of available data streams (UUIDs) and associated colors in JSON format.

    2. **WebSocket Connection (Bidirectional)**
       - **URL:** `ws://<ip>:8080/ws`
       - **Description:** OmnAIView can send a control command as a text message via WebSocket to define which data streams of the data source should be retrieved.
         The command consists of:
         - A list of UUIDs (any number, at least one), separated by spaces.
         - Optionally, a sampling rate (integer between 1 and 100000, default: 60 Sa/s).
         - Optionally, an output format (`json`, `csv`, or `binary`).
         **Example:** `UUID1 UUID2 UUID3 1000 csv`
       - **Response:** Sample data is returned as JSON, CSV, or binary messages.

defaultContentType: application/json
servers:
  httpServer:
    host: '<ip>:8080'
    protocol: http
  wsServer:
    host: '<ip>:8080'
    protocol: ws

channels:
  /UUID:
    address: /UUID
    servers:
      - $ref: '#/servers/httpServer'
    messages:
      deviceListResponse:
        contentType: application/json
        payload:
          type: object
          properties:
            Datastreams:
              type: array
              description: List of data streams.
              items:
                type: object
                properties:
                  UUID:
                    type: string
            colors:
              type: array
              description: List of colors.
              items:
                type: object
                properties:
                  color:
                    type: object
                    properties:
                      r:
                        type: integer
                        example: 81
                      g:
                        type: integer
                        example: 237
                      b:
                        type: integer
                        example: 96
          example:
            datastreams:
              - UUID: E66368254F77B524
            colors:
              - color:
                  r: 81
                  g: 237
                  b: 96
  /ws:
    address: /ws
    servers:
      - $ref: '#/servers/wsServer'
    messages:
      controlCommand:
        $ref: '#/components/messages/ControlCommand'
      sampleDataJson:
        $ref: '#/components/messages/SampleDataJson'
      sampleDataCsv:
        $ref: '#/components/messages/SampleDataCsv'
      sampleDataBinary:
        $ref: '#/components/messages/SampleDataBinary'
    bindings:
      ws: {}
operations:
  getDeviceList:
    action: receive
    channel:
      $ref: '#/channels/~1UUID'
    summary: Returns the list of available data streams and their colors.
    bindings:
      http:
        method: GET
    messages:
      - $ref: '#/channels/~1UUID/messages/deviceListResponse'
  startDeviceData:
    action: send
    channel:
      $ref: '#/channels/~1ws'
    summary: Defines data streams, sampling rate, and format to determine how the server responds.
    messages: 
      - $ref: '#/channels/~1ws/messages/controlCommand'
  sendControlCommand:
    action: send
    channel:
      $ref: '#/channels/~1ws'
    summary: Sends a control command to the WebSocket.
    messages:
      - $ref: '#/channels/~1ws/messages/controlCommand'
  receiveSampleData:
    action: receive
    channel:
      $ref: '#/channels/~1ws'
    summary: Receives sample data in JSON, CSV, or binary format.
    messages:
      - $ref: '#/channels/~1ws/messages/sampleDataJson'
      - $ref: '#/channels/~1ws/messages/sampleDataCsv'
      - $ref: '#/channels/~1ws/messages/sampleDataBinary'
components:
  messages:
    ControlCommand:
      name: ControlCommand
      title: Control Command
      contentType: text/plain
      summary: >
        This control command is sent to the WebSocket and consists of a
        single text string containing the following components (all separated by a space):
          - One or more UUIDs (any number, at least one).
          - Optional: A sampling rate (integer between 1 and 100000, default: 60 Sa/s).
          - Optional: An output format (`json`, `csv`, or `binary`).
      payload:
        type: string
        pattern: '^(?<uuids>[A-Za-z0-9]+(?:\s+[A-Za-z0-9]+)*)(?:\s+(?<rate>[1-9]\d{0,4}|100000))?(?:\s+(?<format>json|csv|binary))?$'
      examples:
        - summary: CSV request for 1000 Sa/s
          payload: UUID1 UUID2 UUID3 1000 csv
    SampleDataJson:
      name: SampleDataJson
      title: Sample Data (JSON)
      contentType: application/json
      summary: Sample data in JSON format.
      payload:
        type: object
        properties:
          data:
            type: array
            description: List of samples.
            items:
              type: object
              properties:
                timestamp:
                  type: number
                  example: -0.999
                value:
                  type: array
                  items:
                    type: number
                  example:
                    - 0.04
          datastreams:
            type: array
            description: List of device UUIDs.
            items:
              type: string
    SampleDataCsv:
      name: SampleDataCsv
      title: Sample Data (CSV)
      contentType: text/csv
      summary: Sample data in CSV format.
      payload:
        type: string
    SampleDataBinary:
      name: SampleDataBinary
      title: Sample Data (Binary)
      contentType: application/x-protobuf
      summary: Sample data in protobuf binary format. syntax = "proto3"; message Sample {double timestamp = 1; repeated double values = 2;}
      payload:
        type: string