openapi.yaml

openapi: 3.1.0
info:
  title: MTUI HTTP API
  description: |
    HTTP API exposed by MTUI for reading and writing Modbus
    registers on the currently connected device, sending raw function
    codes, plus a health probe.

    The server binds to `0.0.0.0` on a configurable port and proxies requests
    to the live Modbus device backing the TUI. When no device is connected,
    register operations return `503 Service Unavailable`.
  version: 1.0.0
  license:
    name: GPL-2.0-only
    identifier: GPL-2.0-only

servers:
  - url: http://{host}:{port}
    description: mtui API server
    variables:
      host:
        default: localhost
      port:
        default: "8080"
        description: Configured API port (set in mtui; 0 selects an ephemeral port)

paths:
  /read:
    post:
      summary: Read registers or bits
      description: |
        Reads `count` items of the given `type` starting at `address` from the
        connected device. `holding` and `input` return raw 16-bit values;
        `coil` and `discrete` return `0` or `1` per bit.

        An optional `unit_id` targets a specific Modbus unit for this
        request only; the device's configured unit is restored afterwards.
        When omitted, the configured unit is used. Specifying `unit_id`
        requires the "API unit id override" setting to be enabled; otherwise
        the request is rejected with `403`.
      operationId: readRegisters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReadRequest"
            examples:
              holdings:
                summary: Read 4 holding registers from address 0
                value:
                  type: holding
                  address: 0
                  count: 4
              coils:
                summary: Read 8 coils from address 0
                value:
                  type: coil
                  address: 0
                  count: 8
              unit:
                summary: Read 2 holding registers from unit 5
                value:
                  type: holding
                  address: 0
                  count: 2
                  unit_id: 5
      responses:
        "200":
          description: Values read successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadResponse"
              examples:
                registers:
                  summary: holding/input register values
                  value:
                    values: [230, 0, 4998, 12]
                bits:
                  summary: coil/discrete values (0 or 1)
                  value:
                    values: [1, 1, 1, 1, 0, 1, 1, 0]
        "403":
          description: |
            A `unit_id` was specified but the "API unit id override" setting
            is disabled.
        "503":
          description: No device is currently connected
        "502":
          description: The device read failed (Modbus / transport error)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailureResponse"

  /write:
    post:
      summary: Write registers or coils
      description: |
        Writes one or more consecutive items starting at `address`. The
        `type` selects `holding` (16-bit registers) or
        `coil` (bits, where `0` is off and any non-zero value is on).
        Read-only types (`input`, `discrete`) are rejected with `400`, and
        all writes are rejected with `403` when the server is in read-only
        mode.

        An optional `unit_id` targets a specific Modbus unit for this
        request only; the device's configured unit is restored afterwards.
        When omitted, the configured unit is used. Specifying `unit_id`
        requires the "API unit id override" setting to be enabled; otherwise
        the request is rejected with `403`.
      operationId: writeRegisters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WriteRequest"
            examples:
              single:
                summary: Write one holding register
                value:
                  type: holding
                  address: 50
                  values: [1234]
              multiple:
                summary: Write three consecutive holding registers
                value:
                  type: holding
                  address: 50
                  values: [1234, 5678, 9012]
              coils:
                summary: Write three consecutive coils (on, off, on)
                value:
                  type: coil
                  address: 0
                  values: [1, 0, 1]
              unit:
                summary: Write one holding register to unit 5
                value:
                  type: holding
                  address: 50
                  values: [1234]
                  unit_id: 5
      responses:
        "204":
          description: Values written successfully (no body)
        "400":
          description: The requested type is read-only (input or discrete)
        "403":
          description: |
            The write is forbidden: the server is in read-only mode, or a
            `unit_id` was specified while the "API unit id override" setting
            is disabled.
        "503":
          description: No device is currently connected
        "502":
          description: The device write failed (Modbus / transport error)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailureResponse"

  /raw:
    post:
      summary: Send a raw Modbus function
      description: |
        Sends an arbitrary function `code` with `data` as the request bytes
        and returns the bytes the device answered with. Nothing is
        interpreted on either side.

        The endpoint is disabled by default and every request is rejected
        with `501` until the "API raw function" setting is enabled. Read-only
        mode does not apply here: the server cannot tell whether a raw
        function writes, so enabling the setting is the opt-in.

        An optional `unit_id` targets a specific Modbus unit for this
        request only; the device's configured unit is restored afterwards.
        When omitted, the configured unit is used. Specifying `unit_id`
        requires the "API unit id override" setting to be enabled; otherwise
        the request is rejected with `422`.
      operationId: rawFunction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RawRequest"
            examples:
              diagnostics:
                summary: Diagnostics (0x08) return query data
                value:
                  code: 8
                  data: [0, 0, 18, 52]
              report_server_id:
                summary: Report server id (0x11) without data
                value:
                  code: 17
              unit:
                summary: Diagnostics (0x08) sent to unit 5
                value:
                  code: 8
                  data: [0, 0, 18, 52]
                  unit_id: 5
      responses:
        "200":
          description: The device answered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RawResponse"
              examples:
                echo:
                  value:
                    data: [0, 0, 18, 52]
        "422":
          description: |
            A `unit_id` was specified but the "API unit id override" setting
            is disabled.
        "501":
          description: The "API raw function" setting is disabled
        "503":
          description: No device is currently connected
        "502":
          description: The device call failed (Modbus / transport error)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FailureResponse"

  /health:
    get:
      summary: Health probe
      description: |
        Reports server health. Returns `200` only when a device is present and
        its connection status is serving (`unknown`, `reading`, or
        `connected`); otherwise `503` with the same body.

        In the TUI the status follows the app's own device polling. In
        `--headless` mode nothing polls the device, so the status starts as
        `unknown` and then reflects the outcome of the latest API read or
        write.
      operationId: health
      responses:
        "200":
          description: Device present and serving
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              examples:
                connected:
                  value:
                    status: connected
                    device_present: true
                    read_only: false
        "503":
          description: No device present, or status is not serving
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
              examples:
                disconnected:
                  value:
                    status: error
                    device_present: false
                    read_only: false

components:
  schemas:
    RegisterType:
      type: string
      description: |
        Modbus data class. `holding` (16-bit, read/write) and `input` (16-bit,
        read-only) are register types; `coil` (1-bit, read/write) and
        `discrete` (1-bit, read-only) are bit types. Reads of bit types return
        `0` or `1` per item.
      enum:
        - holding
        - input
        - coil
        - discrete

    ReadRequest:
      type: object
      required: [type, address, count]
      properties:
        type:
          $ref: "#/components/schemas/RegisterType"
        address:
          type: integer
          format: uint16
          minimum: 0
          maximum: 65535
          description: Starting register address.
        count:
          type: integer
          format: uint16
          minimum: 0
          maximum: 65535
          description: Number of registers to read.
        unit_id:
          type: integer
          format: uint8
          minimum: 0
          maximum: 255
          description: |
            Modbus unit id to target for this request only. Defaults to
            the device's configured unit when omitted. Requires the "API unit
            id override" setting to be enabled; a request that sets this while
            the setting is disabled is rejected with `403`.

    FailureResponse:
      type: object
      required: [exception, timed_out]
      properties:
        exception:
          type: integer
          format: uint8
          minimum: 0
          maximum: 255
          nullable: true
          description: |
            Modbus exception code answered by the device, or `null` when the
            failure was not a Modbus exception (timeout, transport error).
        timed_out:
          type: boolean
          description: |
            `true` when the device did not answer within the configured
            timeout, `false` otherwise.

    ReadResponse:
      type: object
      required: [values]
      properties:
        values:
          type: array
          description: |
            Values in address order: raw 16-bit for `holding`/`input`, or
            `0`/`1` for `coil`/`discrete`.
          items:
            type: integer
            format: uint16
            minimum: 0
            maximum: 65535

    WriteRequest:
      type: object
      required: [type, address, values]
      properties:
        type:
          allOf:
            - $ref: "#/components/schemas/RegisterType"
          description: |
            Target data class. Only `holding` and `coil` are writable;
            `input` and `discrete` are rejected with `400`.
        address:
          type: integer
          format: uint16
          minimum: 0
          maximum: 65535
          description: Starting address.
        values:
          type: array
          description: |
            Values to write to consecutive items. For coils, `0` is off and
            any non-zero value is on.
          items:
            type: integer
            format: uint16
            minimum: 0
            maximum: 65535
        unit_id:
          type: integer
          format: uint8
          minimum: 0
          maximum: 255
          description: |
            Modbus unit id to target for this request only. Defaults to
            the device's configured unit when omitted. Requires the "API unit
            id override" setting to be enabled; a request that sets this while
            the setting is disabled is rejected with `403`.

    RawRequest:
      type: object
      required: [code]
      properties:
        code:
          type: integer
          format: uint8
          minimum: 0
          maximum: 255
          description: Modbus function code to send.
        data:
          type: array
          description: Request bytes sent after the function code. Defaults to none.
          items:
            type: integer
            format: uint8
            minimum: 0
            maximum: 255
        unit_id:
          type: integer
          format: uint8
          minimum: 0
          maximum: 255
          description: |
            Modbus unit id to target for this request only. Defaults to
            the device's configured unit when omitted. Requires the "API unit
            id override" setting to be enabled; a request that sets this while
            the setting is disabled is rejected with `422`.

    RawResponse:
      type: object
      required: [data]
      properties:
        data:
          type: array
          description: Response bytes the device answered after the function code.
          items:
            type: integer
            format: uint8
            minimum: 0
            maximum: 255

    HealthResponse:
      type: object
      required: [version, status, device_present, read_only]
      properties:
        version:
          type: string
          description: MTUI version serving the API.
        status:
          type: string
          description: Connection status label.
          enum:
            - unknown
            - reading
            - connected
            - reconnecting
            - error
        device_present:
          type: boolean
          description: Whether a Modbus device is currently connected.
        read_only:
          type: boolean
          description: Whether the server rejects writes.