asyncapi: 3.0.0
info:
  title: Jellyfish WebSocket API
  version: 0.23.1
  description: >-
    Live telemetry channel between robots and the Jellyfish backend. Robots open a WebSocket connection to
    `ws://<host>:4001/ws` and push JSON envelopes; the backend re-publishes them over GraphQL subscriptions and to
    internal listeners.
  license:
    name: MIT
servers:
  production:
    host: ws.clearbot.dev:4001
    protocol: ws
    pathname: /ws
    description: Alternate HTTP server on port 4001 — separate from the main REST/GraphQL server on port 4000.
defaultContentType: application/json
channels:
  live/status:
    address: /ws/live/status
    description: >-
      Live LiveStatus telemetry from a robot. Messages are JSON envelopes conforming to the `LiveStatusSocketMessage`
      interface.
    messages:
      LiveStatusSocketMessage:
        $ref: '#/components/messages/LiveStatusSocketMessage'
  battery/status:
    address: /ws/battery/status
    description: >-
      Live BatteryStatus telemetry from a robot. Messages are JSON envelopes conforming to the
      `BatteryStatusSocketMessage` interface.
    messages:
      BatteryStatusSocketMessage:
        $ref: '#/components/messages/BatteryStatusSocketMessage'
  lidar/scan:
    address: /ws/lidar/scan
    description: >-
      Live LidarScan telemetry from a robot. Messages are JSON envelopes conforming to the `LidarScanSocketMessage`
      interface.
    messages:
      LidarScanSocketMessage:
        $ref: '#/components/messages/LidarScanSocketMessage'
  hardware/status:
    address: /ws/hardware/status
    description: >-
      Live HardwareStatus telemetry from a robot. Messages are JSON envelopes conforming to the
      `HardwareStatusSocketMessage` interface.
    messages:
      HardwareStatusSocketMessage:
        $ref: '#/components/messages/HardwareStatusSocketMessage'
  dongle/status:
    address: /ws/dongle/status
    description: >-
      Live DongleStatus telemetry from a robot. Messages are JSON envelopes conforming to the
      `DongleStatusSocketMessage` interface.
    messages:
      DongleStatusSocketMessage:
        $ref: '#/components/messages/DongleStatusSocketMessage'
  e/propulsion/motor:
    address: /ws/e/propulsion/motor
    description: >-
      Live ePropulsionMotor telemetry from a robot. Messages are JSON envelopes conforming to the
      `EPropulsionMotorStatusMessage` interface.
    messages:
      EPropulsionMotorStatusMessage:
        $ref: '#/components/messages/EPropulsionMotorStatusMessage'
operations:
  onLiveStatus:
    action: receive
    channel:
      $ref: '#/channels/live/status'
    summary: Receive LiveStatus events
    messages:
      - $ref: '#/channels/live/status/messages/LiveStatusSocketMessage'
  onBatteryStatus:
    action: receive
    channel:
      $ref: '#/channels/battery/status'
    summary: Receive BatteryStatus events
    messages:
      - $ref: '#/channels/battery/status/messages/BatteryStatusSocketMessage'
  onLidarScan:
    action: receive
    channel:
      $ref: '#/channels/lidar/scan'
    summary: Receive LidarScan events
    messages:
      - $ref: '#/channels/lidar/scan/messages/LidarScanSocketMessage'
  onHardwareStatus:
    action: receive
    channel:
      $ref: '#/channels/hardware/status'
    summary: Receive HardwareStatus events
    messages:
      - $ref: '#/channels/hardware/status/messages/HardwareStatusSocketMessage'
  onDongleStatus:
    action: receive
    channel:
      $ref: '#/channels/dongle/status'
    summary: Receive DongleStatus events
    messages:
      - $ref: '#/channels/dongle/status/messages/DongleStatusSocketMessage'
  onePropulsionMotor:
    action: receive
    channel:
      $ref: '#/channels/e/propulsion/motor'
    summary: Receive ePropulsionMotor events
    messages:
      - $ref: '#/channels/e/propulsion/motor/messages/EPropulsionMotorStatusMessage'
components:
  messages:
    LiveStatusSocketMessage:
      name: LiveStatusSocketMessage
      title: LiveStatus
      contentType: application/json
      payload:
        $ref: '#/components/schemas/LiveStatusSocketMessage'
    BatteryStatusSocketMessage:
      name: BatteryStatusSocketMessage
      title: BatteryStatus
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BatteryStatusSocketMessage'
    LidarScanSocketMessage:
      name: LidarScanSocketMessage
      title: LidarScan
      contentType: application/json
      payload:
        $ref: '#/components/schemas/LidarScanSocketMessage'
    HardwareStatusSocketMessage:
      name: HardwareStatusSocketMessage
      title: HardwareStatus
      contentType: application/json
      payload:
        $ref: '#/components/schemas/HardwareStatusSocketMessage'
    DongleStatusSocketMessage:
      name: DongleStatusSocketMessage
      title: DongleStatus
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DongleStatusSocketMessage'
    EPropulsionMotorStatusMessage:
      name: EPropulsionMotorStatusMessage
      title: ePropulsionMotor
      contentType: application/json
      payload:
        $ref: '#/components/schemas/EPropulsionMotorStatusMessage'
  schemas:
    LiveStatusSocketMessage:
      type: object
      properties:
        __type__:
          type: string
          enum:
            - LiveStatus
        robotId:
          type: number
        live:
          type: boolean
      required:
        - __type__
        - robotId
        - live
    BatteryStatusSocketMessage:
      type: object
      properties:
        __type__:
          type: string
          enum:
            - BatteryStatus
        robotId:
          type: number
        battery_id:
          type: number
        soc_percentage:
          type: number
        total_voltage:
          type: number
        current:
          type: number
        cell_voltages:
          type: array
          items:
            type: number
      required:
        - __type__
        - robotId
        - battery_id
        - soc_percentage
        - total_voltage
        - current
        - cell_voltages
    LidarScanSocketMessage:
      type: object
      properties:
        __type__:
          type: string
          enum:
            - LidarScan
        robotId:
          type: number
        angle_min:
          type: number
        angle_max:
          type: number
        intensities:
          type: array
          items:
            type: number
        ranges:
          type: array
          items:
            type: number
      required:
        - __type__
        - robotId
        - angle_min
        - angle_max
        - intensities
        - ranges
    HardwareStatusSocketMessage:
      type: object
      properties:
        messageData:
          type: object
          properties:
            network_speed:
              type: number
            temperature:
              type: number
            front_camera_status:
              type: boolean
            back_camera_status:
              type: boolean
            lidar_status:
              type: boolean
            uart_status:
              type: boolean
          required:
            - network_speed
            - temperature
            - front_camera_status
            - back_camera_status
            - lidar_status
            - uart_status
        __type__:
          type: string
          enum:
            - HardwareStatus
        robotId:
          type: number
      required:
        - messageData
        - __type__
        - robotId
    DongleStatusSocketMessage:
      type: object
      properties:
        messageData:
          type: object
          properties:
            traffic_up_info:
              type: number
            traffic_down_info:
              type: number
            signal_info:
              type: number
            network_info:
              type: string
            network_type:
              type: string
          required:
            - traffic_up_info
            - traffic_down_info
            - signal_info
            - network_info
            - network_type
        __type__:
          type: string
          enum:
            - DongleStatus
        robotId:
          type: number
      required:
        - messageData
        - __type__
        - robotId
    MotorDrivingStatusMessage:
      type: object
      properties:
        speed:
          type: number
        target_throttle:
          type: number
        current_throttle:
          type: number
        throttle_direction:
          type: boolean
      required:
        - speed
        - target_throttle
        - current_throttle
        - throttle_direction
    MotorPowerStatusMessage:
      type: object
      properties:
        power:
          type: number
        output_current:
          type: number
        is_over_current:
          type: boolean
        is_over_voltage:
          type: boolean
        is_under_voltage:
          type: boolean
      required:
        - power
        - output_current
        - is_over_current
        - is_over_voltage
        - is_under_voltage
    MotorTemperatureStatusMessage:
      type: object
      properties:
        temperature:
          type: number
        is_over_temperature:
          type: boolean
      required:
        - temperature
        - is_over_temperature
    MotorFailureStatusMessage:
      type: object
      properties:
        drive_communication_failure:
          type: boolean
        temperature_sensor_failure:
          type: boolean
        control_failure:
          type: boolean
      required:
        - drive_communication_failure
        - temperature_sensor_failure
        - control_failure
    EPropulsionMotorStatusMessage:
      type: object
      properties:
        __type__:
          type: string
          enum:
            - ePropulsionMotor
        robotId:
          type: number
        position:
          oneOf:
            - type: string
              enum:
                - left
            - type: string
              enum:
                - right
        driving_status:
          $ref: '#/components/schemas/MotorDrivingStatusMessage'
        power_status:
          $ref: '#/components/schemas/MotorPowerStatusMessage'
        temperature_status:
          $ref: '#/components/schemas/MotorTemperatureStatusMessage'
        failure_status:
          $ref: '#/components/schemas/MotorFailureStatusMessage'
      required:
        - __type__
        - robotId
        - position
        - driving_status
        - power_status
        - temperature_status
        - failure_status
    GenericDataChannelMessage:
      type: object
      properties:
        __type__:
          type: string
          enum:
            - GenericDataChannelMessage
        robotId:
          type: number
      required:
        - __type__
        - robotId