Dispatcher Quick Start
======================

Dependencies
------------

LAVA needs python >= 2.6.  For the dispatcher, you need the pexpect
module.


Configuring for local development
---------------------------------

Configuring conmux
++++++++++++++++++

You will need to have a card containing a 'master image' for your
board.  The process of creating a master image is outlined on
https://wiki.linaro.org/Platform/Validation/Specs/MasterBootImage.

For LAVA development and testing using only locally attached resources,
you should be able to make use of most features, even without the use of
special equipment such as a console server.

First install conmux and cu::

    sudo add-apt-repository ppa:linaro-maintainers/tools
    sudo apt-get update
    sudo apt-get install conmux cu

Connect a development board to a local serial device (e.g. ttyUSB0).
You may have permission problem with cu running as root under conmux.

Create a configuration file for your board under /etc/conmux which
should look something like this::

    listener panda01
    application console 'panda01 console' 'cu -l /dev/ttyUSB0 -s 115200'

Make sure to give the file a '.cf' extension (e.g. panda01.cf).

If you see this permission problem when running cu, you can try
adjusting your .cf file to call cu using sg, and the group name owning
the device.  For example::

    sg dialout "cu -l ttyUSB0 -s 115200"

Finally restart conmux::

    sudo stop conmux
    sudo start conmux

You can test the connection using::

    conmux-console panda01
    (use ~$quit to exit)

You should be able to type commands and interact with the shell inside
conmux-console.  If you cannot, run "sudo stop conmux" and try running
'sg dialout "cu -l ttyUSB0 -s 115200"'.  If that doesn't work, you
probably need to add some files to /etc/uucp.  Add ::

    port ttyUSB0
    type direct
    device /dev/ttyUSB0
    hardflow false
    speed 115200

to /etc/uucp/port and append ::

    system  panda01
    port    ttyUSB0
    time    any

to /etc/uucp/sys.  If this doesn't let you interact with the shell in
conmux-console, complain in #linaro on freenode and hopefully someone
will help you out :)


Configuring the dispatcher
++++++++++++++++++++++++++

The dispatcher looks for config values in ~/.config/lava-dispatcher/, then
/etc/lava-dispatcher (inside the current virtual environment if any, or
/etc/lava-dispatcher itself otherwise), then its own source tree.

To get started, you ned to make a directory for storing artefacts
before they are downloaded to the device being tested
(LAVA_IMAGE_TMPDIR in the config and /linaro/images/tmp by default)::

    # mkdir -p /linaro/images/tmp

You will need to set LAVA_SERVER_IP to the address of the machine
running the dispatcher in ~/.config/lava-dispatcher/lava-dispatcher.conf::

    $ cat ~/.config/lava-dispatcher/lava-dispatcher.conf
    LAVA_SERVER_IP = 192.168.88.77

You can set LAVA_PROXY if you have a proxy available in
~/.config/lava-dispatcher/lava-dispatcher.conf, squid proxy service
is preferred, if no, please leave it blank::

    $ cat ~/.config/lava-dispatcher/lava-dispatcher.conf
    LAVA_PROXY = http://192.168.88.77:3128/

The dispatcher will use ``pip`` to install the lava-test package by default.
You may want to use ``apt-get`` to install a ``.deb`` package instead, and
will need to set the LAVA_TEST_DEB, with the name of the package::

    $ cat ~/.config/lava-dispatcher/lava-dispatcher.conf
    LAVA_TEST_DEB = lava-test

You will need to add a configuration file for your device. It can be
extremely simple, just identifying the type of the device::

    $ cat ~/.config/lava-dispatcher/devices/panda01.conf
    device_type = panda

You also need a webserver such as Apache set up, and serve
LAVA_IMAGE_TMPDIR/images as /images.  This snippet does this for
Apache::

    Alias /images/ "/linaro/images/"
    <Directory "/linaro/images/">
        Options Indexes MultiViews FollowSymLinks
    </Directory>

If you want to upload the results to a local dashboard instance, you
need to set one of those up.  XXX link to doc on this!

Modify the server in job file doc/examples/jobs/lava-ltp-job.json to local 
lava-dashboard url, like:

    {
      "command": "submit_results",
      "parameters":
        {
          "server": "http://staging.linaro.dev/lava-server/RPC2/",
          "stream": "/anonymous/panda01-ltp/"
        }
    }


A note on logging: Conmux keeps logs in /var/log/conmux.  If it cannot
attach to the device, it may continually send output to the log every
few seconds.  For non-production purposes, you may simply want to run
'sudo stop conmux' when you are not using the console, to avoid
needlessly growing large logfiles.


Dispatching a job
-----------------

From the toplevel, run (as root):

    ./lava-dispatch doc/examples/jobs/lava-ltp-job.json

