CircleCI integration

Quick start

First, create a CircleCI account and connect your favorite Github repository. Now you have a CircleCI “project.” In the project dashboard, you’ll need to do two things:

  1. Import your f0cal API key. (Learn more)
  2. Export a SSH fingerprint.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
git clone ${MY_REPO} && cd ${MY_REPO}
git checkout -b circleci_integration
mkdir .circleci
echo <<EOF > .circleci/config.yml
version: 2.1
orbs:
  farm: f0cal/farm@1.0.0
workflows:
build-test-deploy:
  jobs:
    - farm/with_f0cal_device:
        name: test_device
        device_type: rpi3b+
        image: ubuntu-18.04:latest
        ssh_key_fingerprint: "${SSH_FP}"
        steps:
          - farm/f0cal_run:
              command: cmake .
          - farm/f0cal_run:
              command: make
          - farm/f0cal_run:
              command: ./bin/test
EOF
git add .circleci/config.yml
git commit -m "Added basic CircleCI pipeline"
git push origin circleci_integration

About

CircleCI is a continuous integration and delivery platform. When you push your code to Github, CircleCI will pull it and run it through a build/test/deploy pipeline of your making. CircleCI pipelines are defined in YAML, and can leverage third-party infrastructure and tools through through a simple namespacing scheme. Third-party integrations of this nature are referred to as “orbs.”

FØCAL provides orbs comprising a single f0cal namespace. The remainder of this document details key functionality encapsulated in the f0cal orbs.

Getting started

FØCAL account setup

Create an API key under the API keys tab. Make sure you keep the key handy, as you will need it in the next step, but it will on be visible once. (Learn more.)

CircleCI account setup

f0cal/farm orb

The goal of the f0cal/farm orb is to simplify automated testing on edge hardware including the Raspberry Pi, NVidia Jetson devices, and many others.

Usage

The following is an example of using the orb with a cmake project:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
version: 2.1
orbs:
  farm: f0cal/farm@1.0.0
workflows:
build-test-deploy:
  jobs:
    - farm/with_f0cal_device:
        name: test_device
        device_type: rpi3b+
        image: ubuntu-18.04:latest
        ssh_key_fingerprint: "${SSH_FP}"
        steps:
          - farm/f0cal_run:
              command: cmake .
          - farm/f0cal_run:
              command: make
          - farm/f0cal_run:
              command: ./bin/test

Note the following:

Gotchas

Each instance of farm/f0cal_run spawns a new shell. So, if you assign the output of a f0cal_run command to an environment variable, that variable will not be available to subsequent instances of f0cal/run. If you need to do something complex and stateful, write it using YAML’s multiline support as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
version: 2.1
orbs:
  farm: f0cal/farm@1.0.0
workflows:
build-test-deploy:
  jobs:
    - farm/with_f0cal_device:
        name: test_device
        device_type: rpi3b+
        image: ubuntu-18.04:latest
        ssh_key_fingerprint: "${SSH_FP}"
        steps:
          - farm/f0cal_run:
              command: |
                cmake .
                make
                ./bin/test
Early access