openapi.yaml

openapi: 3.0.3

info:
  title: LXA TAC HTTP API
  description: Control and view inputs and outputs of your LXA TAC
  version: 0.1.0

paths:
  /v1/tac/display/screen:
    get:
      summary: Get the name of the screen currently shown on the display
      tags: [User Interface]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Screen'
    put:
      summary: Set the screen to show on the display
      tags: [User Interface]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Screen'
      responses:
        '204':
          description: The screen was set successfully
        '400':
          description: The value could not be parsed into a screen name

  /v1/tac/display/alerts:
    get:
      summary: A list of currently pending alerts shown on the local UI
      tags: [User Interface]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alerts'

  /v1/tac/display/backlight/brightness:
    get:
      summary: Get the current backlight brightness (between 0.0, and 1.0)
      tags: [User Interface]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: number
    put:
      summary: Set the current backlight brightness (between 0.0 and 1.0)
      tags: [User Interface]
      requestBody:
        content:
          application/json:
            schema:
              type: number
      responses:
        '204':
          description: The display brightness was set successfully
        '400':
          description: The value could not be parsed as a number

  /v1/tac/display/buttons:
    put:
      summary: Simulate a button press/release on the device
      tags: [User Interface]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ButtonEvent'
      responses:
        '204':
          description: The button event will be simulated
        '400':
          description: The value could not be parsed as button event

  /v1/tac/display/content:
    get:
      summary: The current screen content rendered into a PNG
      tags: [User Interface]
      responses:
        '200':
          content:
            image/png:

  /v1/tac/display/locator:
    get:
      summary: Get the current locator status
      tags: [User Interface]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean
    put:
      summary: Set the current locator status
      tags: [User Interface]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: The locator status was set successfully
        '400':
          description: The value could not be parsed into a boolean

  /v1/tac/display/show_help:
    get:
      summary: Display a help menu on the local screen
      tags: [User Interface]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean
    put:
      summary: Display a help menu on the local screen
      tags: [User Interface]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: Help will be shown or hidden as requested
        '400':
          description: The request could not be parsed as boolean

  /v1/tac/led/{led}/pattern:
    parameters:
      - name: led
        description: The name of the respective LED
        required: true
        schema:
          type: string
          enum:
            - out_0
            - out_1
            - dut_pwr
            - eth_dut
            - eth_lab
            - status

    get:
      summary: Get the current blink pattern of the LED
      tags: [User Interface]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlinkPattern'

  /v1/tac/led/{led}/color:
    parameters:
      - name: led
        description: The name of the respective LED
        required: true
        schema:
          type: string
          enum:
            - status

    get:
      summary: Get the current RGB color of the LED
      tags: [User Interface]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: number
                minItems: 3
                maxItems: 3

  /v1/dut/powered:
    get:
      summary: Get the current power switch state
      tags: [DUT Power]
      responses:
        '200':
          description: The DUT power can either be "On" or in a couple of off states.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DutPwrStatus'
    put:
      summary: Try to set the power switch state
      description: >
        While the request will return immediately with a successful response, this does not mean
        that the switch is actually on at this or a later point in time.
        You will always have to check with e.g. a GET request if you really want to know, as an
        error state could always take precedence.
      tags: [DUT Power]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DutPwrRequest'
      responses:
        '204':
          description: The request was set
        '400':
          description: The value could not be parsed into a a power switch request

  /v1/usb/host/{port}/powered:
    parameters:
      - name: port
        description: The name of the respective port on the hub
        required: true
        schema:
          type: string
          enum:
            - port1
            - port2
            - port3
    get:
      summary: Get the power status for an USB host port
      tags: [USB Host]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean

    put:
      summary: Set the power status for an USB host port
      tags: [USB Host]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: A power on/off was requested
        '400':
          description: The value could not be parsed as boolean

  /v1/usb/host/{port}/device:
    parameters:
      - name: port
        description: The name of the respective port on the hub
        required: true
        schema:
          type: string
          enum:
            - port1
            - port2
            - port3
    get:
      summary: Get the device connected to the respective USB port
      tags: [USB Host]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsbDevice'

  /v1/usb/host/overload:
    get:
      summary: Get the name of the currently overloaded port (if any)
      tags: [USB Host]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
                enum:
                  - Total
                  - Port1
                  - Port2
                  - Port3

  /v1/tac/temperatures/soc:
    get:
      summary: Get the current temperature inside the SoC
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

  /v1/tac/temperatures/warning:
    get:
      summary: Get the current temperature warning state
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
                enum:
                  - Okay
                  - SocHigh
                  - SocCritical

  /v1/tac/info/uname:
    get:
      summary: Get the information commonly accessed via "uname"
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Uname'

  /v1/tac/info/bootloader:
    get:
      summary: Get the information passed through from the bootloader
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Barebox'

  /v1/tac/info/tacd/version:
    get:
      summary: Get the tacd version string
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string

  /v1/tac/info/hardware_generation:
    get:
      summary: Get the LXA TAC hardware generation
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string
                enum:
                  - Gen1
                  - Gen2
                  - Gen3

  /v1/tac/setup_mode:
    get:
      summary: Check if the TAC has completed the set up or is still in setup mode
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean
    put:
      summary: Leave setup mode by writing false
      tags: [System]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: Setup mode left (when false was sent)
        '400':
          description: The request could not be parsed as boolean

  /v1/labgrid/{file}:
    parameters:
      - name: file
        description: The name of the file to read/write
        required: true
        schema:
          type: string
          enum:
            - configuration
            - environment
            - userconfig
    get:
      summary: Get the current content of a labgrid config file
      tags: [System]
      responses:
        '200':
          content:
            text/plain:
              schema:
                type: string

    put:
      summary: Set a new content for the labgrid config file
      tags: [System]
      requestBody:
        content:
          text/plain:
            schema:
              type: string
      responses:
        '204':
          description: New config set

  /v1/tac/ssh/authorized_keys:
    get:
      summary: Get the current content of roots authorized_keys file
      tags: [System]
      responses:
        '200':
          content:
            text/plain:
              schema:
                type: string
        '403':
          description: The device is not in setup mode

    put:
      summary: Set a new content for roots authorized_keys file
      tags: [System]
      requestBody:
        content:
          text/plain:
            schema:
              type: string
      responses:
        '204':
          description: New ssh keys set
        '403':
          description: The device is not in setup mode

  /v1/iobus/server/info:
    get:
      summary: Get (cached) info from the local IOBus server
      tags: [IOBus]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IOBusServerInfo'

  /v1/iobus/server/nodes:
    get:
      summary: Get the list of connected nodes
      tags: [IOBus]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IOBusServerNodes'

  /v1/output/{out_n}/asserted:
    parameters:
      - name: out_n
        description: The name of the output, that shall be asserted
        required: true
        schema:
          type: string
          enum:
            - out_0
            - out_1
    get:
      summary: Get the current asserted/deasserted status of the output
      tags: [Input/Output]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean

    put:
      summary: Set the asserted/deasserted status of the output
      tags: [Input/Output]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: The output was set to asserted/deasserted state
        '400':
          description: The value could not be parsed as boolean

  /v1/uart/{rx_tx}/enabled:
    parameters:
      - name: rx_tx
        description: The direction to get status for/modify
        required: true
        schema:
          type: string
          enum:
            - rx
            - tx
    get:
      summary: Check if the selected direction is activated
      tags: [Input/Output, UART]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean

    put:
      summary: Activate/Deactivate the direction
      tags: [Input/Output, UART]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: The direction was enabled/disabled
        '400':
          description: The value could not be parsed as boolean

  /v1/uart/powered:
    get:
      summary: Check if the power supply on the DUT UART connector is turned on
      tags: [Input/Output, UART]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean

    put:
      summary: Turn the power supply on the DUT UART connector on/off
      tags: [Input/Output, UART]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: The UART supply was turned on/off
        '400':
          description: The value could not be parsed as boolean

  /v1/iobus/powered:
    get:
      summary: Check if the IOBus power supply is turned on
      tags: [Input/Output, IOBus]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean

    put:
      summary: Turn the IOBus supply on/off
      tags: [Input/Output, IOBus]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: The IOBus supply was turned on/off
        '400':
          description: The value could not be parsed as boolean

  /v1/iobus/feedback/fault:
    get:
      summary: Check if the IOBus supply is in an error state
      tags: [Input/Output, IOBus]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean

  /v1/usb/host/{port}/feedback/current:
    parameters:
      - name: port
        description: The port to get measurements for
        required: true
        schema:
          type: string
          enum:
            - total
            - port1
            - port2
            - port3

    get:
      summary: Get the current consumed by devices on this port
      tags: [Input/Output, USB Host]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

  /v1/output/{out_n}/feedback/voltage:
    parameters:
      - name: out_n
        description: The output to get voltage feedback for
        required: true
        schema:
          type: string
          enum:
            - out_0
            - out_1

    get:
      summary: Get the voltage between the two OUT_N pins
      tags: [Input/Output]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

  /v1/iobus/feedback/current:
    get:
      summary: Get the current consumed by devices on the IOBus
      tags: [Input/Output, IOBus]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

  /v1/iobus/feedback/voltage:
    get:
      summary: Get the voltage of the IOBus power supply
      description: A voltage dip indicates a fault on the bus
      tags: [Input/Output, IOBus]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

  /v1/dut/feedback/current:
    get:
      summary: Get the current consumed by the DUT
      tags: [Input/Output, DUT Power]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

  /v1/dut/feedback/voltage:
    get:
      summary: Get the voltage applied to the DUT
      tags: [Input/Output, DUT Power]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Measurement'

  /v1/tac/service/{service}/action:
    parameters:
      - name: service
        description: The service to perform the action on
        required: true
        schema:
          type: string
          enum:
            - network-manager
            - labgrid-exporter
            - lxa-iobus
            - rauc
    put:
      summary: Perform an action on a systemd service
      tags: [System]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceAction'
      responses:
        '204':
          description: The service was asked to perform the action
        '400':
          description: The value could not be parsed as action

  /v1/tac/service/{service}/status:
    parameters:
      - name: service
        description: The service to get the status for
        required: true
        schema:
          type: string
          enum:
            - network-manager
            - labgrid-exporter
            - lxa-iobus
            - rauc
    get:
      summary: Get the status of a systemd service
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatus'

  /v1/tac/reboot:
    put:
      summary: Reboot the TAC
      tags: [System]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: If the body was true the TAC will soon reboot
        '400':
          description: The value could not be parsed as boolean

  /v1/tac/time/now:
    get:
      summary: Get the current time on the TAC as milliseconds since the Unix Epoch
      tags: [System]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: number

  /v1/tac/update/enable_polling:
    put:
      summary: Enable periodic polling for operating system updates
      tags: [Updating]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: Polling for OS updates was enabled/disabled
        '400':
          description: The value could not be parsed as boolean

  /v1/tac/update/enable_auto_install:
    put:
      summary: Enable automatic installation of operating system updates
      tags: [Updating]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: Automatic installation of updates was enabled/disabled
        '400':
          description: The value could not be parsed as boolean

  /v1/tac/update/inhibit/dut_power:
    get:
      summary: Whether the TAC should look for and install updates while the DUT is powered
      tags: [Updating]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean
    put:
      summary: Set whether polling for updates while the DUT is powered is inhibited or not
      tags: [Updating]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: The configuration was applied
        '400':
          description: The value could not be parsed as boolean

  /v1/tac/update/operation:
    get:
      summary: Get the currently running system update operation
      tags: [Updating]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string

  /v1/tac/update/progress:
    get:
      summary: Get the progress report of the running update operation
      tags: [Updating]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RaucProgress'

  /v1/tac/update/slots:
    get:
      summary: Get the progress report of the running update operation
      tags: [Updating]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object

  /v1/tac/update/last_error:
    get:
      summary: Get the last error reported by the update system
      tags: [Updating]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string

  /v1/tac/update/install:
    put:
      summary: Request the installation of a RAUC bundle from an URL
      tags: [Updating]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequest'
      responses:
        '204':
          description: The value was parsed successfully and will be tried
        '400':
          description: The value could not be parsed

  /v1/tac/update/channels:
    get:
      summary: Get a list of update channels and available updates
      tags: [Updating]
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateChannels'

  /v1/tac/update/channels/reload:
    put:
      summary: Request an update of the channels list and update availability
      tags: [Updating]
      requestBody:
        content:
          application/json:
            schema:
              type: boolean
      responses:
        '204':
          description: An update was requested (if true was sent)
        '400':
          description: The value could not be parsed as boolean

  /v1/tac/update/should_reboot:
    get:
      summary: Should the system be rebooted as there is a new bundle in the other slot?
      tags: [Updating]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: boolean

  /v1/tac/network/hostname:
    get:
      summary: Get the systems hostname
      tags: [Network]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: string

  /v1/tac/network/tac-bridge:
    get:
      summary: Get the IPv4 addresses associated with the tac-bridge interface
      tags: [Network]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /v1/tac/network/interface/{if}:
    parameters:
      - name: if
        description: The name of the interface to query
        required: true
        schema:
          type: string
          enum:
            - dut
            - uplink
    get:
      summary: Get the link status of the respective interface
      tags: [Network]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  speed:
                    type: number
                  carrier:
                    type: boolean

components:
  schemas:
    Screen:
      type: string
      enum:
        - DutPower
        - Usb
        - DigOut
        - System
        - IoBus
        - Uart

    Alerts:
      type: array
      items:
        type: string
        enum:
          - ScreenSaver
          - Locator
          - RebootConfirm
          - UpdateAvailable
          - UpdateInstallation
          - Help
          - Setup

    ButtonEvent:
      type: object
      properties:
        type: object
        properties:
          dir:
            type: string
            enum:
              - Press
              - Release
          btn:
            type: string
            enum:
              - Upper
              - Lower
          dur:
            type: string
            enum:
              - Short
              - Long

    BlinkPattern:
      type: object
      properties:
        repetitions:
          type: integer
        steps:
          type: array
          items:
            type: array
            oneOf:
              - type: number
              - type: object
                properties:
                  secs:
                    type: integer
                  nanos:
                    type: integer
            minItems: 2
            maxItems: 2

    DutPwrStatus:
      type: string
      enum:
        - On
        - Off
        - OffFloating
        - Changing
        - InvertedPolarity
        - OverCurrent
        - OverVoltage
        - RealtimeViolation

    DutPwrRequest:
      type: string
      enum:
        - On
        - Off
        - OffFloating

    UsbDevice:
      type: object
      properties:
        id_product:
          type: string
        id_vendor:
          type: string
        manufacturer:
          type: string
        product:
          type: string

    Measurement:
      type: object
      properties:
        ts:
          type: number
        value:
          type: number

    Uname:
      type: object
      properties:
        sysname:
          type: string
        nodename:
          type: string
        release:
          type: string
        version:
          type: string
        machine:
          type: string

    Barebox:
      type: object
      properties:
        version:
          type: string
        baseboard_release:
          type: string
        powerboard_release:
          type: string
        baseboard_timestamp:
          type: string
        powerboard_timestamp:
          type: string
        baseboard_featureset:
          type: array
          items:
            type: string
        powerboard_featureset:
          type: array
          items:
            type: string

    IOBusServerInfo:
      type: object
      properties:
        hostname:
          type: string
        started:
          type: string
        can_interface:
          type: string
        can_interface_is_up:
          type: boolean
        lss_state:
          type: string
          enum:
            - Idle
            - Scanning
        can_tx_error:
          type: boolean

    IOBusServerNodes:
      type: object
      properties:
        code:
          type: number
        error_message:
          type: string
        result:
          type: array
          items:
            type: string

    RaucProgress:
      type: object
      properties:
        percentage:
          type: number
        message:
          type: string
        nesting_depth:
          type: number

    UpdateRequest:
      type: object
      properties:
        url:
          type: string
        manifest_hash:
          type: string

    UpdateChannels:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          display_name:
            type: string
          description:
            type: string
          url:
            type: string
          polling_interval:
            type: object
            properties:
              secs:
                type: integer
              nanos:
                type: integer
          enabled:
            type: boolean
          primary:
            type: boolean
          bundle:
            type: object
            properties:
              compatible:
                type: string
              version:
                type: string,
              manifest_hash:
                type: string,
              effective_url:
                type: string,
              newer_than_installed:
                type: boolean
          force_polling:
            type: boolean
          force_auto_install:
            type: boolean
          candidate_criteria:
            type: string
          install_criteria:
            type: string
          reboot_criteria:
            type: string

    ServiceStatus:
      type: object
      properties:
        active_state:
          type: string
        sub_state:
          type: string
        active_enter_ts:
          type: number
        active_exit_ts:
          type: number

    ServiceAction:
      type: string
      enum:
        - Start
        - Stop
        - Restart

tags:
  - name: User Interface
    description: Everything concerning the user interface
  - name: DUT Power
    description: Control the power supply of the device under test
  - name: USB Host
    description: Control the USB Hub directly on the TAC
  - name: System
    description: System and Health info
  - name: IOBus
    description: Status of the local IOBus server
  - name: Input/Output
    description: Analog and Digtial Inputs/Outputs
  - name: Updating
    description: System upgrades via RAUC
  - name: Network
    description: Network information