===========================
Introduction to CI-tron
===========================

This project provides the source for the CI-tron infrastructure, a bare-metal
automated CI system for Linux driver development.

Its main purpose is to build a CI gateway service, with different components,
responsible for the orchestration and management of devices under test (DUTs).
Each component has been designed with a focus on creating well-designed
interfaces to form an open source toolbox that CI systems can easily
reuse and customize to their requirements, without limiting their future options.

This test system was approached with several design principles in mind:

* Avoiding dependence on specific software, so as to remain flexible and adaptable.

* Implementing auto-discovery to simplify the setup process of DUTs.

* Making the system as easy to use and intuitive as possible, so that users can
  quickly get up and running with it.

* Avoiding complex and difficult-to-manage configuration.

* Ensuring that the system is easy to administer and maintain, so its maintenance
  burden is minimal.


All code is hosted by the `freedesktop.org`_ project at `ci-tron`_.

.. _ci-tron: https://gitlab.freedesktop.org/gfx-ci/ci-tron/
.. _freedesktop.org: https://www.freedesktop.org/wiki/

Physical Overview
=================

.. mermaid::
    :align: center
    :alt: Physical setup of a CI-tron bare-metal infrastructure
    :caption: Physical setup of a CI-tron bare-metal infrastructure

    graph TD
        internet[fa:fa-globe Internet ] <-->|fa:fa-ethernet Public network| gateway[CI-tron<br>Gateway]
        pdu[fa:fa-plug Switchable Power<br>Delivery Unit] --> |fa:fa-plug Port 1| gateway
        pdu <--> |fa:fa-wifi Control channel| gateway
        gateway <--> |fa:fa-ethernet Port 1| switch[fa:fa-network-wired Private<br>Network Switch]
        gateway <--> |fa:fa-usb USB cable| usbhub[USB Hub]

        %% Dut 1
        switch <--> |fa:fa-ethernet Port 2| dut1[fa:fa-mobile-phone Test Machine 1<br>w/ serial port]
        pdu --> |fa:fa-plug Port 2| dut1
        dut1 <--> |UART| ftdi_1[TTL Serial to USB]
        ftdi_1 <--> |fa:fa-usb USB cable| usbhub

        %% Dut 2
        switch <--> |fa:fa-ethernet Port 3| dut2[fa:laptop Test Machine 2<br>w/o serial port]
        pdu --> |fa:fa-plug Port 3| dut2
        dut2 <--> |fa:fa-usb USB cable| rs232_usb_2_1[RS232 to USB]
        rs232_usb_2_1 <--> |Null-modem<br>RS232 cable| rs232_usb_2_2[RS232 to USB]
        rs232_usb_2_2 <--> |fa:fa-usb USB cable| usbhub

*TODO*: Finalize and document the job description format