Steps

Steps make up the fundamental building blocks of BeetleboxCI. This document will describe the features of steps as well as provide examples of using them.

Overview

Every job executes as series of tasks known as steps. Steps can run command-line programs and by default are executed in a bash shell.

Status

An individual step may have a status:

Status	Description
Pass	Step has completed succesfully
Fail	Step has failed
Pending	Step is in progress
Idle	Step has not started
Not Run	Step in job not started due to previous error

Configuration Examples

Command-line programs

Steps may be used to execute command-line programs. To do so, the steps key is used followed by a list of steps to execute. You can indicate that you wish to run a command through the run step. The step must be provided a name through the name key as well as the commands to be executed through the command. In the provided example, two steps will be executed in sequence. The first step Say Hello World 1 demonstrates running a single line command, whilst Say Hello World 1 and 2 demonstrates how to run multiple commands in a single step.

runners:
 example-runner:
  image: work1-virtualbox:5000/ubuntu-generic

jobs:   
 example-build:
  runner: example-runner
  steps:
   - run:
      name: Say Hello World 1
      command: echo "Hello World 1"
   - run:
      name: Say Hello World 2 and 3
      command: |
       echo "Hello World 2"
       echo "Hello World 3"


workflows:
 workflow-example:
  jobs:
   - example-build

Step Types

In the previous example, you would have noted that all of the steps listed are a run type. There are in fact two types of steps: transfer and run. A transfer step will copy files to or from a device depending on the source and destination specified in the step. In order to use the transfer step, the user must ensure that they have added a record of the device to the device registry and defined the transfer command in the device's config settings. A run step does exactly what it says: it runs the specified command. The command in a run step may be executed directly in the container which handles the job (by default) or the user may specify the on-device option which instructs BeetleboxCI to execute the command in a terminal within the device itself (for devices that have their own operating system).

In the code snippets below, sshpass is first installed on the job container, to allow the container to perform password authentication to access the device via SSH.

The second step transfers the contents of the the folder Hardware/package/sd_card/ to the device. This folder came from the input artifact once the tarball was decompressed. The transfer step makes use of the transfer command defined in the device config, as shown in the second code snippet.

The next step is to execute a ./script.sh on the device and send the output of the execution to a text file called output.txt. This script was among the files that were copied to the device in the previous step.

The final step is to read the output.txt back from the device using another transfer step.

This job has an output artifact specified as output.txt, and this will be the file that is read back from the device, and it will be saved as an artifact for the user to inspect.

jobs:
 run-hw-brief:
  runner: generic-runner
  device: zcu104-device-vitis
  input: 
   artifact: 
    - fpga-artifact.tar.gz
  output: 
   artifact: 
    - output.txt   
  steps:
   - run:
      name: Setup
      command: apt-get install sshpass
   - transfer:
      name: Transfer
      source: Hardware/package/sd_card/*
      destination: root@192.168.1.86:/mnt/sd-mmcblk0p1/
   - run:
      name: Run device
      on-device: True
      command: |      
       cd /mnt/sd-mmcblk0p1
       ./script.sh > output.txt
   - transfer:
      name: Transfer
      source: root@192.168.1.86:/mnt/sd-mmcblk0p1/output.txt       
      destination: ~/
      

devices:
 raspberry-pi:
  transfer: bash -c "sshpass -p raspberry scp -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -r $SOURCE $DESTINATION"
  connection: sshpass -p raspberry ssh -o "UserKnownHostsFile=/dev/null" -o "StrictHostKeyChecking=no" pi@192.168.1.92
  prompt: "$"