openapi: 3.0.3
info:
  title: M-Bus HTTPD API
  version: 0.3.5
servers:
- url: /
paths:
  /mbus/api:
    get:
      description: Returns this API specification
      operationId: mbus_api
      responses:
        "200":
          content:
            text/x-yaml:
              schema:
                $ref: '#/components/schemas/yaml'
          description: OK
        "404":
          content:
            text/plain:
              example: File not found
              schema:
                $ref: '#/components/schemas/textError'
          description: Not found
  /mbus/hat:
    get:
      description: Gets Raspberry Pi Hat information
      operationId: hat
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/hat'
          description: OK
        "404":
          content:
            text/plain:
              example: Hat information not found
              schema:
                $ref: '#/components/schemas/textError'
          description: Not found
  /mbus/hat/on:
    post:
      description: Turns on power to the M-Bus
      operationId: hatOn
      responses:
        "200":
          description: OK
        "404":
          content:
            text/plain:
              example: M-Bus Master Hat not installed
              schema:
                $ref: '#/components/schemas/textError'
          description: Not found
  /mbus/hat/off:
    post:
      description: Turns off power to the M-Bus
      operationId: hatOff
      responses:
        "200":
          description: OK
        "404":
          content:
            text/plain:
              example: M-Bus Master Hat not installed
              schema:
                $ref: '#/components/schemas/textError'
          description: Not found
  /mbus/scan/{device}/{baudrate}:
    post:
      description: Scan the specified device for slaves
      operationId: scan
      parameters:
      - description: The serial device to scan - /dev/ is pre-pended to {device} by
          M-Bus HTTPD before scanning
        example: ttyAMA0
        explode: false
        in: path
        name: device
        required: true
        schema:
          $ref: '#/components/schemas/device'
        style: simple
      - description: Baudrate to communicate with M-Bus devices
        example: 2400
        explode: false
        in: path
        name: baudrate
        required: true
        schema:
          $ref: '#/components/schemas/baudrate'
        style: simple
      responses:
        "200":
          content:
            text/plain:
              example: Found a M-Bus device at address 1
              schema:
                $ref: '#/components/schemas/slaves'
          description: OK
        "400":
          content:
            text/plain:
              example: Baudrate {baudrate} is invalid
              schema:
                $ref: '#/components/schemas/textError'
          description: Bad request
        "404":
          content:
            text/plain:
              example: Device /dev/{device} does not exist
              schema:
                $ref: '#/components/schemas/textError'
          description: Not found (e.g. device not found, or M-Bus HTTPD is unauthorized
            to access it, or to change baud rate to that specified, device not responding
            etc)
  /mbus/get/{device}/{baudrate}/{address}:
    post:
      description: Gets data from the slave identified by {address}
      operationId: get
      parameters:
      - description: The serial device to scan - /dev/ is pre-pended to {device} by
          M-Bus HTTPD before scanning
        example: ttyAMA0
        explode: false
        in: path
        name: device
        required: true
        schema:
          $ref: '#/components/schemas/device'
        style: simple
      - description: Baudrate to communicate with M-Bus devices
        example: 2400
        explode: false
        in: path
        name: baudrate
        required: true
        schema:
          $ref: '#/components/schemas/baudrate'
        style: simple
      - description: The slave device to get data from
        example: 48
        explode: false
        in: path
        name: address
        required: true
        schema:
          $ref: '#/components/schemas/address'
        style: simple
      responses:
        "200":
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/mbusData'
          description: OK
        "400":
          content:
            text/plain:
              example: Baudrate {baudrate} is invalid
              schema:
                $ref: '#/components/schemas/textError'
          description: Bad request
        "404":
          content:
            text/plain:
              example: Slave {address} not responding
              schema:
                $ref: '#/components/schemas/textError'
          description: Not found (or M-Bus HTTPD is unauthorized to access it, or
            to change baud rate to that specified, etc)
  /mbus/getMulti/{device}/{baudrate}/{address}/{maxframes}:
    post:
      description: Gets data from the slave identified by {address}, and supports
        multiple responses from the slave
      operationId: getMulti
      parameters:
      - description: The serial device to scan - /dev/ is pre-pended to {device} by
          M-Bus HTTPD before scanning
        example: ttyAMA0
        explode: false
        in: path
        name: device
        required: true
        schema:
          $ref: '#/components/schemas/device'
        style: simple
      - description: Baudrate to communicate with M-Bus devices
        example: 2400
        explode: false
        in: path
        name: baudrate
        required: true
        schema:
          $ref: '#/components/schemas/baudrate'
        style: simple
      - description: The slave device to get data from
        example: 48
        explode: false
        in: path
        name: address
        required: true
        schema:
          $ref: '#/components/schemas/address'
        style: simple
      - description: The slave device to get data from
        example: 16
        explode: false
        in: path
        name: maxframes
        required: true
        schema:
          $ref: '#/components/schemas/maxframes'
        style: simple
      responses:
        "200":
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/mbusData'
          description: OK
        "400":
          content:
            text/plain:
              example: Baudrate {baudrate} is invalid
              schema:
                $ref: '#/components/schemas/textError'
          description: Bad request
        "404":
          content:
            text/plain:
              example: Slave {address} not responding
              schema:
                $ref: '#/components/schemas/textError'
          description: Not found (or M-Bus HTTPD is unauthorized to access it, or
            to change baud rate to that specified, etc)
components:
  schemas:
    yaml:
      description: A YAML file
      example: A YAML file
      type: string
    textError:
      description: Some error text
      example: Device /dev/{device} does not exist
      type: string
    device:
      description: The device the M-Bus is connected to - /dev/ is prepended to {device}
        by M-Bus HTTPD
      example: ttyAMA0
      type: string
    baudrate:
      description: Baudrate to use for the communication - valid values 300, 600,
        1200, 2400, 4800, 9600
      enum:
      - 300
      - 600
      - 1200
      - 2400
      - 4800
      - 9600
      example: 2400
      format: int32
      type: integer
    slaves:
      description: Output of libmbus scan command
      example: Found a M-Bus device at address 1
      type: string
    mbusData:
      description: M-Bus device data as an XML document
      example: <?xml version="1.0" encoding="UTF-8"?>...
      type: string
    address:
      description: Slave address (primary or secondary)
      example: "48"
      format: string
      maxLength: 16
      minLength: 1
      type: string
    maxframes:
      description: Max frames to listen for
      example: 16
      format: int32
      maximum: 250
      minimum: 1
      type: integer
    hat:
      description: Raspberry Pi Hat Information
      example:
        index: 1
        addr: 30
        enabled: true
      properties:
        product:
          description: Product
          example: M-Bus Master
          type: string
        productId:
          description: Product ID
          example: 0x0001
          type: string
        productVer:
          description: Product Version
          example: 0x0002
          type: string
        uuid:
          description: Hat UUID
          example: 148fa981-a33b-a07a-a13f-a2405d08e0fe
          type: string
        vendor:
          description: Hat Vendor
          example: packom.net
          type: string