openapi: 3.0.0
info:
  title: Sonic local API
  version: 2024.2.1
  description: |
    # Overview

    This is the API hosted on Sonic allowing to manage the device and retrieve collected data.
    Available endpoints allow to:
    - Get device state
    - Get/change valve state
    - Get telemetry data
    - Get power supply status
    - Get/change networking status
    - Get auto shut-off settings
    - Get auto shut-off report
    - Execute a command (reboot)
    - Get/set webhook URL

    Whenever unknown request is received, API returns a 404 Not Found response.

    ---
    # Webhook

    If a webhook is configured, the device will send PUT requests for the following events: "auto-shut-off-report", "telemetry",  "valve", "power-supply-changed", "wifi-changed" and "online".

    ---

    ### telemetry

    Message sent when new telemetry data was collected.
    | Label | Unit |
    | --- | --- |
    | Flow | ml/min |
    | Pressure | mbar |
    | Temperature | °C |
    | Event volume | ml |
    | Event duration | s |

    ```json
    {
        "type": "telemetry",
        "data":
            {
                "flow": integer,
                "pressure": integer,
                "temperature": integer,
                "event": { "volume": integer, "duration": integer },
                "errors": ["flow"/"pressure"/"temperature"],
            },
    }    
    ```
    ---

    ### valve

    Message sent when the valve state changes.

    ```json
    {
        "type": "valve",
        "data": {
            "state": "open"/"closed"/"opening"/"closing/unknown"
        }
    }
    ```
    ---

    ### power-supply-changed

    Message sent when the power supply status changes.

    ```json
    {
        "type": "power-supply-changed",
        "data": {
            "supply": "battery"/"external"/"external+battery"
            ]
        }
    }
    ```
    ---

    ### auto-shut-off-report

    Message sent when the auto shut-off module gets triggered due to detecting a potential leak.
    | Label | Unit |
    | --- | --- |
    | Volume | ml |
    | Duration | s |
    | Timestamp | ms |

    ```json
    {
        "type": "auto-shut-off-report",
        "data":
            {
                "type": ["VOLUME_THRESHOLD"/"DURATION_THRESHOLD"],
                "volume": integer,
                "duration": integer,
                "timestamp": integer,
            },
    }
    ```

tags:
  - name: Sonic
paths:
  /api/sonic/:
    get:
      tags: [Sonic]
      operationId: getDeviceState
      summary: Get device state
      description: |
        Retrieve specified information from the device: valve state, water flow indicator, MQTT and Wi-Fi connection status, power supply, firmware version, water meter data, and device uptime.
        | Label | Unit |
        | --- | --- |
        | Water meter volume | L |
        | Water meter duration | min |
        | Uptime | s |
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.device-state.v2+json:
              schema:
                $ref: "#/components/schemas/DeviceStateV2"
            application/vnd.wtg.local.device-state.v1+json:
              schema:
                $ref: "#/components/schemas/DeviceStateV1"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sonic/valve:
    get:
      tags: [Sonic]
      operationId: getValveState
      summary: Get valve state
      description: Retrieve the current state of the valve.
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.valve.v1+json:
              schema:
                $ref: "#/components/schemas/ValveState"
    put:
      tags: [Sonic]
      operationId: setValveState
      summary: Set valve state
      description: |
        Request the change of the valve state. If the valve is already in the desired state, its position won't change.
      requestBody:
        required: true
        content:
          application/vnd.wtg.local.valve-change.v1+json:
            schema:
              $ref: "#/components/schemas/ValveStateChange"
      responses:
        "204":
          description: No content
        "400":
          $ref: "#/components/responses/BadRequestError"
        "406":
          $ref: "#/components/responses/NotAcceptableError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sonic/telemetry:
    get:
      tags: [Sonic]
      operationId: getTelemetryData
      summary: Get telemetry data
      description: |
        Retrieve sensors readings from the device.
        This includes: flow rate, pressure, water temperature, ongoing event data and potential errors.
        When an error is detected, the corresponding value is excluded from the payload.
        When water is not flowing, the event data is excluded from the payload.
        | Label | Unit |
        | --- | --- |
        | Flow rate | ml/min |
        | Pressure | mbar |
        | Water temperature | °C |
        | Event volume | ml |
        | Event duration | s |
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.telemetry.v1+json:
              schema:
                $ref: "#/components/schemas/Telemetry"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sonic/power:
    get:
      tags: [Sonic]
      operationId: getPowerSupplyData
      summary: Get power status
      description: |
        Retrieve the power status of the device. When the device is running only on external power supply, the battery voltage is excluded from the payload.
        | Label | Unit |
        | --- | --- |
        | Battery voltage | mV |
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.power.v1+json:
              schema:
                $ref: "#/components/schemas/PowerSupply"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sonic/networking:
    get:
      tags: [Sonic]
      operationId: getNetworkingData
      summary: Get networking status
      description: |
        Retrieve the networking status of the device.
        | Label | Unit |
        | --- | --- |
        | RSSI | dBm |
        | Wi-Fi uptime | ms |
        | MQTT uptime | ms |
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.networking.v1+json:
              schema:
                $ref: "#/components/schemas/Networking"
        "500":
          $ref: "#/components/responses/InternalServerError"
    put:
      tags: [Sonic]
      operationId: changeNetwork
      summary: Update networking configuration
      description: Update the networking configuration of the system.
      requestBody:
        required: true
        content:
          application/vnd.wtg.local.network-change.v1+json:
            schema:
              $ref: "#/components/schemas/NetworkChange"
      responses:
        "204":
          description: No content
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sonic/auto-shut-off:
    get:
      tags: [Sonic]
      operationId: getAutoShutOff
      summary: Get auto shut-off settings
      description: |
        Retrieve the auto shut-off settings of the device.
        | Label | Unit |
        | --- | --- |
        | Volume threshold | L |
        | Duration threshold | min |
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.auto-shut-off.v1+json:
              schema:
                $ref: "#/components/schemas/AutoShutOff"
        "204":
          description: No content
        "500":
          $ref: "#/components/responses/InternalServerError"
  /api/sonic/auto-shut-off/report:
    get:
      tags: [Sonic]
      operationId: getAutoShutOffReport
      summary: Get auto shut-off report
      description: |
        Retrieve the auto shut-off report of the system.
        | Label | Unit |
        | --- | --- |
        | Volume | ml |
        | Duration | s |
        | Timestamp | ms |
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.auto-shut-off.report.v1+json:
              schema:
                $ref: "#/components/schemas/AutoShutOffReport"
        "204":
          description: No content
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sonic/command:
    put:
      tags: [Sonic]
      operationId: sendCommand
      summary: Execute a command
      description: |
        Execute a specific command on the device.
        | Command | Description |
        | --- | --- |
        | reboot | Software reboot of the device |
      requestBody:
        required: true
        content:
          application/vnd.wtg.local.command.v1+json:
            schema:
              $ref: "#/components/schemas/Command"
      responses:
        "204":
          description: No content
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalServerError"

  /api/sonic/webhook:
    get:
      tags: [Sonic]
      operationId: getWebhookUrl
      summary: Get webhook URL
      description: Retrieve the webhook URL of the system.
      responses:
        "200":
          description: Successful response
          content:
            application/vnd.wtg.local.webhook.v1+json:
              schema:
                $ref: "#/components/schemas/Webhook"
        "204":
          description: No content
    put:
      tags: [Sonic]
      operationId: setWebhookUrl
      summary: Update webhook URL
      description: Update the webhook URL of the system.
      requestBody:
        required: true
        content:
          application/vnd.wtg.local.webhook.v1+json:
            schema:
              $ref: "#/components/schemas/Webhook"
      responses:
        "204":
          description: No content
        "400":
          $ref: "#/components/responses/BadRequestError"
        "406":
          $ref: "#/components/responses/NotAcceptableError"
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  responses:
    BadRequestError:
      description: Invalid request.
      content:
        application/vnd.wtg.local.error.v1+json: {}
    InternalServerError:
      description: Internal error during processing the request.
      content:
        application/vnd.wtg.local.error.v1+json: {}
    NotAcceptableError:
      description: Invalid request content type.
      content:
        application/vnd.wtg.local.error.v1+json: {}

  schemas:
    WaterMeter:
      type: object
      properties:
        volume:
          description: Total volume of water passed through the device [L].
          type: integer
          example: 567820
        duration:
          description: Total time of water flowing through the device [min].
          type: integer
          example: 3908
    DeviceStateV1:
      type: object
      properties:
        valveState:
          type: string
          enum: ["open", "closed", "opening", "closing", "unknown"]
          example: "closed"
        waterFlowing:
          type: boolean
          example: false
        mqttConnected:
          type: boolean
          example: true
        wifiConnected:
          type: boolean
          example: true
        powerSupply:
          type: string
          enum: ["battery", "external", "external+battery"]
          example: "external"
        firmwareVersion:
          type: string
          example: "2024.1.0"
        serialNumber:
          type: string
          example: "abcdef1234567890"
        waterMeter:
          allOf:
            - description: Water meter differential flow data(subtraction of positive and negative readings).
            - $ref: "#/components/schemas/WaterMeter"
        uptime:
          description: Total time since the device was booted [s].
          type: integer
          example: 1024560
    DeviceStateV2:
      type: object
      properties:
        valveState:
          type: string
          enum: ["open", "closed", "opening", "closing", "unknown"]
          example: "closed"
        waterFlowing:
          type: boolean
          example: false
        mqttConnected:
          type: boolean
          example: true
        wifiConnected:
          type: boolean
          example: true
        powerSupply:
          type: string
          enum: ["battery", "external", "external+battery"]
          example: "external"
        firmwareVersion:
          type: string
          example: "2024.1.0"
        serialNumber:
          type: string
          example: "abcdef1234567890"
        waterMeter:
          type: object
          properties:
            positive:
              allOf:
                - description: Water meter positive flow data (aligned with device water flow detection direction).
                - $ref: "#/components/schemas/WaterMeter"
            negative:
              allOf:
                - description: Water meter negative flow data (opposite to device water flow detection direction).
                - $ref: "#/components/schemas/WaterMeter"
        uptime:
          description: Total time since the device was booted [s].
          type: integer
          example: 1024560
    ValveState:
      type: object
      properties:
        state:
          type: string
          enum: ["open", "closed", "opening", "closing", "unknown"]
          default: "closed"
    ValveStateChange:
      type: object
      properties:
        state:
          type: string
          enum: ["open", "close"]
          default: "close"
    Telemetry:
      type: object
      properties:
        flow:
          type: integer
          description: Flow rate [ml/min].
          example: 6800
        pressure:
          type: integer
          description: Pressure [mbar].
          example: 2320
        temperature:
          type: number
          description: Water temperature [°C].
        event:
          type: object
          properties:
            volume:
              type: integer
              description: Volume of water passed through the device of ongoing the event [ml].
              example: 16000
            duration:
              type: integer
              description: Duration of the event of ongoing event [s].
              example: 90
        errors:
          type: array
          items:
            type: string
            enum: ["flow", "pressure", "temperature"]
            example: ["flow", "pressure"]
    PowerSupply:
      type: object
      properties:
        battery:
          type: boolean
          description: Batteries power supply status.
          example: false
        external:
          type: boolean
          description: External power supply status.
          example: true
        batteriesVoltage:
          type: integer
          description: Voltage of the batteries [mV].
          example: 6800
    Networking:
      type: object
      properties:
        mqttConnected:
          type: boolean
          description: MQTT connection status.
          example: true
        wifiConnected:
          type: boolean
          description: Wi-Fi connection status.
          example: true
        ip:
          type: string
          description: IP address of the device.
          example: "192.168.21.37"
        gateway:
          type: string
          description: Gateway IP address.
          example: "192.168.1.0"
        subnet:
          type: string
          description: Subnet mask.
          example: "192.168.1.0/24"
        ssid:
          type: string
          description: SSID of the connected Wi-Fi network.
          example: "MyWi-Fi"
        rssi:
          type: integer
          description: Received Signal Strength Indicator [dBm].
          example: -45
        wifiUpTime:
          type: integer
          description: Time since the Wi-Fi connection was established [ms].
          example: 1024560
        mqttUpTime:
          type: integer
          description: Time since the MQTT connection was established [ms].
          example: 1023450
    NetworkChange:
      type: object
      properties:
        ssid:
          type: string
          description: SSID of the Wi-Fi network to connect.
          example: "MyWi-Fi"
        password:
          type: string
          description: Password of the Wi-Fi network to connect.
          example: "password"
    AutoShutOff:
      type: object
      properties:
        enabled:
          type: boolean
          description: Auto shut-off feature status.
          example: true
        volumeThreshold:
          type: integer
          description: Volume threshold to trigger the auto shut-off [L].
          example: 300
        durationThreshold:
          type: integer
          description: Duration threshold to trigger the auto shut-off [min].
          example: 60
    AutoShutOffReport:
      type: object
      properties:
        type:
          type: string
          enum: ["VOLUME_THRESHOLD", "DURATION_THRESHOLD"]
          description: Type of the auto shut-off event, specifying which threshold was reached.
        volume:
          type: integer
          description: Volume of water passed through the device when the event occurred [ml].
          example: 300
        duration:
          type: integer
          description: Duration of the event when the event occurred [s].
          example: 60000
        timestamp:
          type: integer
          description: Timestamp of the event occurrence [ms].
          example: 1623456789
    Command:
      type: object
      properties:
        type:
          type: string
          enum: ["reboot"]
          description: Type of the command to execute.
          example: "reboot"
    Webhook:
      type: object
      properties:
        url:
          type: string
          description: URL of the webhook.
          example: "https://webhook.site/12345678-1234-1234-1234-1234567890ab"