c41196d5

Quick start

python3 -m venv _venv && souce _venv/bin/activate
pip install --upgrade pip
git clone https://github.com/f0cal/f0cal.farm.client && \
  cd f0cal.farm.client
pip install ./ -r requirements.txt -c constraints.txt
f0cal farm config set api_key ${API_KEY}
f0cal farm instance create my_pi \
  --device rpi3b+ \
  --os ubuntu-18.04:latest
f0cal farm instance access my_pi \
  --ssh

Note: Your ${API_KEY} can be retrieved by logging in here.

Basics

The f0cal.farm.client Python package implements a simple API client and a command line interface (CLI), both capable of running key workflows on the device farm:

  • Spin up devices of various types.

  • Set operating system parameters on target devices.

  • Access running devices.

Both the CLI and client use a simple “noun-verb” interaction model to enable these workflows. For the sake of brevity, example code in this document will use the CLI. Documentation for the Python client can be found here.

The CLI’s nou-verb model interaction model takes the form f0cal farm {noun} {verb} {args}. User-facing nouns mirror those found in typical virtual machine workflows:

  • image – The complete operating system for a device. (Includes a kernel, device tree, root filesystem, etc.)

  • instance – The association of an operating system image to a device.

Other nouns are specific to the farm:

  • device_type –

  • device –

Every noun has basic CRUD verb semantics. In addition, “special” verbs provide the core functionality of the device farm.

  • instance start –

  • instance stop –

  • instance connect –

Getting started

Accessing the f0cal farm CLI requires the installtion of the f0cal.farm.client Python package. The established best-practice for installing third-party Python packages like ours is to use a virtual environment. You can quickly create and activate a Python virtual environment – or “venv” for short – as follows:

python3 -m venv ${VENV_PATH} && source ${VENV_PATH}/bin/activate

If Python complains about not having venv support, you may need to use your system-wide package manager to get it. (Learn more.)

Once your new venv is active, you can install the f0cal.farm.client package from Github.

pip install --upgrade pip
git clone https://github.com/f0cal/f0cal.farm.client && \
  cd f0cal.farm.client
pip install ./ -r requirements.txt -c constraints.txt
f0cal farm config set api_key ${API_KEY}

All the workflows that we exhibit in the remainder of the document will require an API key. API keys can’t be generated programmatically; you will need to visit our web dashboard to get yours. API keys are, effectively, passwords; please take reasonable measures to keep yours secure.

Examples

Available devices

f0cal farm device_type list

This is the basic entrypoing for making queries about what kinds of devices are in the farm.

f0cal farm device_type list --query "manufacturer==NVidia"

More detailed queries can be made using the --query flag. The query syntax is

f0cal farm device_type list --query "hourly_price<0.25"

Availabled images

f0cal farm image list

This is the basic entrypoing for making queries about what kinds of devices are in the farm.

f0cal farm image list --query "manufacturer==NVidia"

More detailed queries can be made using the --query flag. The query syntax is

f0cal farm image list --query "hourly_price<0.25"