# DUT Enablement

This section outlines the recommended process for companies to efficiently
prepare their platform for integration on the LAA and into a Linaro Remote Lab
infrastructure such as ONELab.

```{mermaid}
graph TD;
    Start --> Pre_Operational_Activities;
    Pre_Operational_Activities --> LAA_Integration;
    LAA_Integration --> Platform_Automations;
    Platform_Automations --> Enabled;
```

Each step listed in the workflow above is detailed in the following
sections.

## Pre-Operational Activities

Linaro Remote Labs utilize the Test Automation Framework (TAF) known as LAVA
(Linaro Automated Validation Architecture). Therefore, platforms (DUTs)
must be **automation-enabled** and **LAVA-enabled**, with corresponding
**LAVA jobs** created to support the DUT before they can be used in
a Linaro Remote Lab. By default,a Remote Lab customer is responsible for this
enablement.

```{mermaid}
graph TD;

    A(Start Enablement) --> B[Foundational Orientation];

   subgraph **Pre-Operational Activities**

    B --> C["Run ACS Tests (optional)"];
    B --> F[Complete Questionnaire];

  subgraph **Validate Automation**
   F --> P[Automation Review]
   P --> I{Automatable? Yes or No}
   end
   I -->|Yes| G[Order LAA]
   G -->H[H/W Automation Prep]


   I -->|No| Q((End))
   end


   H --> E(Begin LAA Integration);
```
<p style="text-align: center;"><strong>Pre-Operational Activity Phase</strong></p>

### Foundational Orientation

Each platform (DUT) integrated into a Remote Lab instance such as ONELab must meet
specific requirements for automation enablement. Requirements specific to such
Remote Lab instances can be found in the associated Users Guide. Reference content
common to all Remote Labs can be found in this section.


#### Linaro LAVA technology used to integrate an embedded test platform into the LAA CI test harness.

-   [What is
    LAVA](https://docs.lavasoftware.org/lava/index.html)?

-   [LAVA Device Type
    Enablement](https://docs.lavasoftware.org/lava/device-integration.html?highlight=device%20type)

-   [Creating LAVA Device
    Dictionary](https://docs.lavasoftware.org/lava/pipeline-admin.html#create-device-dictionary)

-   [Creating a LAVA Test
    Definition](https://docs.lavasoftware.org/lava/writing-tests.html?highlight=lava%20job%20creation)

#### ONELab/Linaro Remote Labs Documents

-   [ONELab Users
    Guide](https://linaro-onelab-user-guide.readthedocs-hosted.com/en/latest/index.html)

-   [Linaro Automation Appliance (LAA) Users
    Guide](https://linaro-linaro-automation-appliance-users-guide.readthedocs-hosted.com/en/latest/index.html)

    -   [Introduction to Automated Device
        Testing](https://linaro-linaro-automation-appliance-users-guide.readthedocs-hosted.com/en/latest/laa_overview.html#introduction-to-automated-device-testing)

### Run ACS Tests (optional)

This optional step is ONELab specific and further details can be found in the
ONELab Users Guide
[here.](https://hub.linaro.com/library/onelab/support#locally-running-acs) It is
included in the LAA flow as an example of the parallel activity an LAA user may
consider when preparing to run workloads on the LAA.

### Validate Automation

This section defines the process of verifying whether a platform can be
automated and if so the steps to do so. Each Linaro Remote Lab instance has
unique requirements from an assessment perspective, thus the details for each
are in their associated User's Guide. The list below is where these reviews can
be found:

-  [ONELab Comprehensive Assessment
Review](https://hub.linaro.com/library/onelab/onelab_platform_enablement#onelab-comprehensive-assessment-review)

The output of this section is a go / no-go based upon the ability of the
platform to be automated and work within an embedded Test Automation
Framework (i.e. LAVA).

### Order LAA

Once your platform is confirmed to be automatable and optionally running
any desired pre-integration validation test suites, you are ready to obtain
your subscription. This subscription grants you access to your accounts
and initiates the process for shipping an LAA to your chosen location. While
awaiting delivery, you can proceed with the next section to prepare for
installing your DUT and connecting it to your Remote Lab.

Please contact
[linaro-sales@linaro.org](mailto:linaro-sales@linaro.org)
for more information on attaining a your Remote Lab subscription(s).

### H/W Automation Prep

The first step a user must perform is to make the platform "automatable." This
means you'll be able to to reset, power cycle, flash, and connect to the
platform with zero manual intervention. If your platform requires hardware patch
wiring to support automation in a Linaro Remote Lab, these modifications should
be completed at this stage.  It's recommended to document the h/w mods as well
as reworking platforms ahead of time in preparation for integration. Preparing
the DUTs before receiving the LAA is recommended, allowing you to move directly
into the LAA integration phase upon its arrival. Ideally, consider preparing
multiple platforms in advance to have a backup on hand if any platform failures
occur.

**Note:** The most common reason for requiring automation is
hardware-imposed special cases during firmware installation at reset.
For example, if entering a specific boot mode requires pressing buttons
or toggling jumpers/switches during reset or power-on, the DUT must be
modified for automation. This may involve adding jumper wires, removing
a switch, or a combination of both. Refer to the [Introduction to
Automation](https://linaro-linaro-automation-appliance-users-guide.readthedocs-hosted.com/en/latest/laa_overview.html#introduction-to-automated-device-testing)
section of this document for a quick overview.

```{admonition} TODO
:class: todo
Create a "rollup sheet" that will document all needed options.
```

## LAA Integration Tasks

This section outlines the steps to configure your newly received LAA and
prepare it for use.

```{mermaid}
graph TD;

    R(Receive LAA) -.-> A
    style R fill:#00AA00,stroke:#000,color:#FFF;

    A(Begin LAA Integration)--> C[LAA Unboxing];


   subgraph **Integration Tasks**
    C;

    subgraph **Set Up LAA Platform**
    C --> D[MIB Installation];
    D --> E[Connect DUT]
    E --> F[Power Up];
    end

    F --> G[Verify Platform Activation];
    G --> H[LAA Integration Complete];
   end

    H --> I(Begin Platform Automations);
```

<p style="text-align: center;"><strong>Remote Lab Integration Phase</strong></p>

### Set Up LAA Platform

Upon receipt of your LAA, you're ready to set up your LAA, connect your
DUT, and get it connected to the ONELab service. This process is
detailed in the [LAA
Unboxing](https://linaro-linaro-automation-appliance-users-guide.readthedocs-hosted.com/en/latest/laa_getting_started.html#laa-unboxing)
section of the LAA Users Guide.

```{admonition} To update
:class: todo
Notes from presentation on unboxing:
* FlyLead MIB 2:00 mark
```

### Verify Platform Activation

This step verifies that you can log into ONELab, navigate to the
Platform section, and confirm that your platform is visible and marked
as "online." Once fully configured and powered up, the system
automatically connects to the Linaro Remote Labs backend. If successful,
your newly enabled platform will appear in your ONELab Dashboard,
confirming a successful connection.

```{admonition} TODO
:class: todo
Add a picture of DashBoard showing the LAA OR video
```

The [User Interface
section](https://linaro-onelab-user-guide.readthedocs-hosted.com/en/latest/onelab-operation/onelab_iot_user_interface.html)
of the ONELab Users Guide provides detailed information on how to log in
and confirm the LAA is now present.

## Platform Automations

With the DUT connected to the LAA/MIB, you're now able to go through the
process of creating the needed automations to enable your platform into
the ONELab CI.

```{mermaid}
graph TD;

    A[Begin Platform Automations] --> F[Complete Questionnaire];
    A --> C[Create Device Type];

   subgraph **Platform Automations**
    C;
    F[Document Platform Mods];

    subgraph **Enable CI Automations**
    C --> H[Create Device Dictionary];
    H --> I[Create Health Check Job]
    I -->L[Create Payload Jobs]
    L -->D[Create ACS Test Job];
    end

    subgraph **Validate Automation**
        F --> G[Modify DUT if required];
    end

    D --> K[Upload Jobs]

   end

    G --> E(Congratulations!);
    K --> E

```

<p style="text-align: center;"><strong>Platform Automation Phase</strong></p>

### Enable CI Automations

Preparing your platform with the needed software/CI automations consists
primarily of LAVA enablement on your platform. This consists of several
steps outlined in the Enable LAVA Automations section of the LAA Users
Guide.

#### Create Device Dictionary

```{admonition} TODO
:class: todo
Show how to create and upstream or patch LAVA Device Dictionary
```

```{admonition} Tip
:class: tip
To check the timing, sum the seconds in all `sleep` commands in the `power_off_command` list.
The total **must be less than 10 seconds** – otherwise, LAVA will throw an error during shutdown handling.
```

#### Create Device Type

```{admonition} TODO
:class: todo
Show how to create and upstream or patch LAVA Device Types
```

#### Create LAVA Jobs

```{admonition} TODO
:class: todo
Show how to create LAVA jobs
```
##### Create Health Check

```{admonition} TODO
:class: todo
Show how to build a health check, this may include recovery steps
```
##### Create Payload Jobs

```{admonition} TODO
:class: todo
Show how to build Payload Jobs
```

## Ready for Operation

Congratulations! You're now ready to use the LAA in a remote labs
solution!

Please see the Users Guide for the Linaro Remote Labs solution you're using for next steps.

## Hardware Automation Configuration Template

```{admonition} TODO
:class: todo
Add sample worksheet to capture functionality and LAA mapping for use in
creating LAVA jobs.
```