{{TableOfContents}}
Running tests from Fuego on your hardware can be accomplished in a few simple steps.

Overview [edit section]

= Overview =
The overview of the steps is:
 * 1. install pre-requisite software
 * 2. download the fuego repository
 * 3. build your fuego container
 * 4. start the container
 * 5. access the interface
 * 6. add your board to fuego
 * 7. run a test

These steps are described below.

Install pre-requisite software [edit section]

= Install pre-requisite software =
To retrieve the fuego software and create the docker image for it, you need
to have git and docker installed on your system.

On Ubuntu, try the following commands:

{{{#!YellowBox
$ sudo apt-get install git
$ sudo apt-get install docker.io
}}}

Download, build, start and access [edit section]

= Download, build, start and access =
To accomplish the first 4 steps, do the following from a Linux command prompt:

{{{#!YellowBox
$ git clone https://bitbucket.org/tbird20d/fuego.git
$ cd fuego ; ./install.sh
$ fuego-host-scripts/docker-create-container.sh
$ fuego-host-scripts/docker-start-container.sh
$ firefox http://localhost:8080/fuego
}}}

The second step (with ./install.sh) will take some time - about 45 minutes
on my machine.  This is the main step that is building the docker
container.

NOTE: if you are experimenting with the unreleased version of Fuego in the
'next' branch, then please replace the 'git clone' command in the instructions above with this:
 * git clone -b next ht''''''tps://bitbucket.org/tbird20d/fuego.git

On the last step, you can use any browser instead of firefox to access
the Fuego web interface.  By default
the Fuego interface runs on your host machine, on port 8080, with URL
path "/fuego".

In your browser, you should see a screen similar to the following:

[[image:fuego-dashboard-history.png|width="500"]]

Add your board to fuego [edit section]

= Add your board to fuego =
To add your own board to Fuego, there are three main steps:
 * 1. create a test directory on the target
 * 2. create a board file (on the host)
 * 3. add your board to the Jenkins interface

Create test directory [edit section]

== Create test directory ==
First, log in to your target board, and create a directory where
tests can be run.  Usually, you do this as root, and a commonly
used directory for this is "/home/a".  To do this configuration
do the following:
{{{#!YellowBox
 $ ssh root@your_target
 <target>$ mkdir /home/a
 <target>$ exit
}}}

Create board file [edit section]

== Create board file ==
Now, create your board file.
The board file resides in userdata/conf/boards, and has a filename
with the name of the board, with the extension ".board".

The easiest way to create a board file is to copy an existing one,
and edit the variables to match those of your board.  The following
instructions are for a board called 'myboard', that has networking
access, an ssh daemon running on target, and the ARM architecture.

Do the following:
{{{#!YellowBox
 $ cd userdata/conf/boards
 $ cp template-dev.board myboard.board
 $ vi myboard.board
}}}

Note: you can use your own editor in place of 'vi'

''Note: you can use your own editor in place of 'vi' ''

A board file has parameters which define how Fuego interacts with your
board.  There are lots of different parameters, but the most important
to get started quickly (and the most commonly edited) are:
 * IPADDR
 * SSH_PORT
 * FUEGO_HOME
 * TRANSPORT
 * PLATFORM

IPADDR is the network address of your board.  SSH_PORT is the port where
the ssh daemon is listening for connections.  By default this is 22, but
you set this to whatever your target board uses.

The FUEGO_HOME directory is an absolute path where the Fuego tests are run.
Normally this is set to something like "/home/a", but you can set it to
anything.  The user you specify for LOGIN should have access rights to
this directory.

Set the value of TRANSPORT to "ssh"

Some of the other options are self-explanatory, such as the LOGIN and PASSWORD, which is the account name and password that Fuego should use to execute tests on the target.  The ARCHITECTURE is a string describing the architecture used by toolchains to build the tests for the target.  If using an ARM-based target,
set the ARCHITECTURE to "arm".

The PLATFORM variable indicates the toolchain to use to build the tests
for the target.  If you are using an ARM target, set this to "qemu-armv7hf".
This is a default ARM toolchain installed in the docker container, and should
work for most ARM boards.

If you are not using ARM, or for some reason the pre-installed arm toolchains
don't work for the Linux distribution installed on your board, then 
you will need to install your own SDK or toolchain.  In this case, follow
the steps in [[Adding a toolchain]], then come back to this step and set
the PLATFORM variable to the name you used for that operation.

For other variables in the board file, see the section below.

Add target in Jenkins interface [edit section]

== Add target in Jenkins interface ==
Finally, add the board in the Jenkins interface.

In the Jenkins interface, boards are referred to as "Targets".

From the main screen in the web interface, click on "Target Status" (in the left hand pane).  Then select "'''New Node'''".

[[image:Add-board-New-Node-screen.png|width="800"]]

On the New Node page, input the name of the target board, and tell the system to copy from a pre-existing target.  Do this by clicking on "'''Copy Existing Node'''" and entering ''template-dev'' in the 'Copy from' box.  Then click 'OK'.

This will take you to the "Configure Target" page.

[[image:Add-board-Configure-Target-screen.png|width="800"]]

On the "Configure Target" page, the only thing you need to do is change the
value for the BOARD_OVERLAY environment variable.  Change the value of this field to the name of the board file you created previously.  Include the 'boards' directory.  For example, you might use: boards/myboard.board

Click 'Save' to finish adding the board to the system.

Run a test [edit section]

= Run a test =
To run a test manually, you do the following:
 * Select a test
 * Select the target (myboard)
 * Select the testplan (leave it set to default.testplan)
 * Click “Run the test”

To select a test, on the main dashboard view, click on one
of the tab for test categories (besides History).  This would be one of
"Benchmark", "Functional" or "All".

Let's run a simple functional test: Functional.bc.
This tests whether the program 'bc' on the target operates correctly on 
some simple expressions.

Select Functional.bc from the list of tests.  A page will appear with the current Status and information for this test.  In the left-hand menu, select
"'''Run Test Now'''"

A page like the following will appear:

[[image:Run-Test-Now-screen.png|width="800"]]

On this page, select the target you want to run the test on from the "Device" dropdown list.  (Possibly you might select "myboard", if you've added that to the system.  Select the TESTPLAN "default.testplan".  Leave other options the unchanged.  Finally, click on "Run test".

There should appear a test run in the "Test Run History" pane on the left side of the page, with a progress bar indicating that the test is in progress.  You can wait for the test to complete, or right-click on the progress bar, and view the console log for the test, to watch it's progress.

When the test has completed, the status will be shown by a colored ball by the side of the test in the "Test Run History".  You can get details about the test run by clicking on the link in the history list.

Additional Notes [edit section]

= Additional Notes =
== Other variables in the board file ==
Depending on the test you want to run, you may need to define some other
variables that are specific to your board or the configuration of the
filesystem on it.  Please see [[Adding a board]] for detailed instructions
and a full list of variables that may be used on the target.

Troubleshooting [edit section]

= Troubleshooting =
If you have problems installing or using Fuego, please see our [[Troubleshooting Guide]]