47996121

f0cal/farm is a device automation platform – a service architecture and associated tools that provide automation, monitoring, and collaboration on finicky “edge” hardware. The platform supports SBCs, SoCs, dev boards, and other embedded hardware targets from a variety of manufacturers. The goal of the project is to bring the reproducibility, flexibility, and extensibility that developers have come to expect from containers and VMs to challenging engineering domains like robotics, drones, and IoT.

Testing, evaluation, and benchmarking are key target use-cases for f0cal/farm. Its service architecture supports full automation of key workflows including loading firmware, installing operating systems, configuring software, snapshotting device storage, and more. Every platform artifact – firware, OS images, storage snapshots, etc – can be cached and shared with collaborators through the central service.

f0cal/farm implements a client-API-server topology in which:

  • The server is responsible for instrumenting and automating the devices under test (DUTs).

  • The client provides a single, familiar interface to all relevant developer and administrator workflows.

  • The API manages client ingress, allowing a single client to orchestrate complex workflows on sets of geographically distributed devices.

Client demo

The client is implemented in Python, and also provides a command line interface. See examples, below.

Prerequisites

  • Log in to your demo shell via ssh. – We’ve already set up a client environment for you. See here. ssh to the client URL using the key pair you provided to us.

Code

  • bash: Raspberry Pi

  • python: None contributed – Feel free to add!

Explanation

  1. Activate the Python virtual environment.

source ${VENV_DIR}/bin/activate
  1. See available device clusters.

f0cal farm cluster query
  1. Authenticate with one or more clusters.

f0cal farm remote add \
  ${CLUSTER}
  
f0cal farm remote add \
  ${ANOTHER_CLUSTER}
  1. See available devices.

f0cal farm device-type query \
  --remote ${CLUSTER}
  1. See available OS images.

f0cal farm image query \
  --remote ${CLUSTER}
  1. Provision a device/image instance. – It takes about 5 minutes to flash the OS image to the device.

f0cal farm instance create \
  ${INST} \
  --device-type ${DEVICE_TYPE} \
  --image ${IMAGE} \
  --remote ${CLUSTER}
  1. Log in to the instance – Via ssh.

f0cal farm instance connect \
  ${INST} \
  --remote ${CLUSTER} \
  --ssh
  1. Explore the running OS image – You’re root. It’s your device, top to bottom. Modify something.

date > I_WAS_HERE
  1. Log out.

exit
  1. Save the instance.

f0cal farm instance save \
  ${INST} \
  --image ${IMAGE} \
  --remote ${CLUSTER}
  1. Pull the saved image. – Download it to your client environment.

f0cal farm image pull \
  ${IMAGE} \
  --remote ${CLUSTER}
  1. Destroy the instance. – This returns the device to the pool.

f0cal farm instance destroy \
  ${INST} \
  --remote ${CLUSTER}
  1. Push the saved image. – Upload it to the other cluster.

f0cal farm image push \
  ${IMAGE} \
  --remote ${OTHER_CLUSTER}
  1. Re-instantiate. – Now on a completely different device in a different part of the world.

f0cal farm instance create \
  ${INST}_clone \
  --image ${IMAGE} \
  --device-type ${DEVICE_TYPE} \
  --remote ${OTHER_CLUSTER}
  1. SSH in. – Verify that the pull/push worked.

f0cal farm instance connect \
  ${INST}_clone \
  --remote ${CLUSTER} \
  --ssh \
  "cat I_WAS_HERE"
  1. Destroy the instance. – Release the hardware so others can use it.

f0cal farm instance destroy \
  ${INST}_clone \
  --remote ${ANOTHER_CLUSTER}

NOTE: Please be sure to destroy any instances and release the hardware for others to use.

Server demo

The server is a software appliance implemented as pre-packaged QEMU/KVM virtual machine.

Prerequisites

  • The demonstrated workflows are known to work recent Debian Linux (and related) workstations.

  • Your workstation must be capable of running libvirt. Ensure that virtualization support is enabled in the BIOS. This setting is typically motherboard-specific, and you may need to consult vendor docs. Run kvm ok on the Linux command line to verify KVM acceleration can be used.

  • The target devices (DUTs) must sit together on an isolated physical subnet, ie, a wired switch. We will refer to this as the device LAN (“DLAN”).

  • Your workstation must have an Ethernet NIC available to dedicate to the DLAN.

  • [! IMPORTANT !] To support automated power-cycling (recommended for all workflows) and management of USB storage devices (required for some workflows), you’ll need to attach a supported power relay and relay controller to the DLAN.

Code

  • python: (Release expected 2020-09-01.)

Explanation

  1. Create a Python virtual environment.

  2. Install the f0cal/farm server bootstrap – From source.

  3. Get a server API key – Visit [http://app.f0cal.com].

  4. Run the server bootstrap – Use the credentials obtained in the previous step.