Shepherd-Sheep

shepherd-sheep is the command line utility for locally controlling a single shepherd observer. Depending on your use-case you may not even need to directly interact with it. Use the shepherd-herd command line utility to orchestrate a group of shepherd observer remotely.

For using the tool, deploy the software as described in Getting started.

Command-Line Interface

Note

The tool has integrated help-functionality. For a full list of supported commands and options, run shepherd-sheep --help and for more detail for each command shepherd-sheep [COMMAND] --help.

The command-line Interface is as follows:

shepherd-sheep

Entry for command line with settings to interface the herd.

shepherd-sheep [OPTIONS] COMMAND [ARGS]...

Options

-i, --inventory <inventory>

List of target hosts as comma-separated string or path to ansible-style yaml file

-l, --limit <limit>

Comma-separated list of hosts to limit execution to

-u, --user <user>

User name for login to nodes

-k, --key-filepath <key_filepath>

Path to private ssh key file

-v, --verbose
--version

Prints version-infos (combinable with -v)

alive

Check if all remote hosts are present & responding.

shepherd-sheep alive [OPTIONS]

distribute

Upload a file FILENAME to the remote observers, which will be stored in REMOTE_PATH.

shepherd-sheep distribute [OPTIONS] FILENAME

Options

-r, --remote-path <remote_path>

for safety only allowed: /var/shepherd/* or /etc/shepherd/*

-f, --force-overwrite

Overwrite existing file

Arguments

FILENAME

Required argument

emulate

Emulate an energy environment for the attached sensor nodes.

Use the previously recorded harvest-data for emulating an energy environment for the attached sensor nodes and monitor their power consumption and GPIO events - INPUT-PATH is a hdf5-file on the sheep-hosts

shepherd-sheep emulate [OPTIONS] INPUT_PATH

Options

-o, --output-path <output_path>

Dir or file path for resulting hdf5 file with load recordings

-d, --duration <duration>

Duration of recording in seconds

-f, --force-overwrite

Overwrite existing file

-c, --use-cal-default

Use default calibration values

--enable-io, --disable-io

Switch the GPIO level converter to targets on/off

--io-port <io_port>

Choose Target that gets connected to IO

Options:

A | B

--pwr-port <pwr_port>

Choose (main)Target that gets connected to virtual Source / current-monitor

Options:

A | B

-x, --voltage-aux <voltage_aux>

Set Voltage of auxiliary Power Source (second target)

-a, --virtual-source <virtual_source>

Use the desired setting for the virtual source

-n, --no-start

Start shepherd synchronized after uploading config

Arguments

INPUT_PATH

Required argument

fix

Reload the shepherd-kernel-module on each sheep.

shepherd-sheep fix [OPTIONS]

harvest

Simultaneously record IV data from harvesting-sources on the chosen observers.

shepherd-sheep harvest [OPTIONS]

Options

-o, --output-path <output_path>

Dir or file path for resulting hdf5 file

-a, --virtual-harvester <virtual_harvester>

Choose one of the predefined virtual harvesters

-d, --duration <duration>

Duration of recording in seconds

-f, --force-overwrite

Overwrite existing file

-c, --use-cal-default

Use default calibration values

-n, --no-start

Start shepherd synchronized after uploading config

inventorize

Collect information about the observer-hosts -> saved to local file.

shepherd-sheep inventorize [OPTIONS] [OUTPUT_PATH]

Arguments

OUTPUT_PATH

Optional argument

poweroff

Power off shepherd observers.

shepherd-sheep poweroff [OPTIONS]

Options

-r, --restart

Reboot

program

Programmer for Target-Controller.

shepherd-sheep program [OPTIONS] FIRMWARE_FILE

Options

-p, --target-port <target_port>

Choose Target-Port of Cape for programming

Options:

A | B

-m, --mcu-port <mcu_port>

Choose MCU on Target-Port (only valid for SBW & SWD)

-v, --voltage <voltage>

Target supply voltage

-d, --datarate <datarate>

Bit rate of Programmer (bit/s)

-t, --mcu-type <mcu_type>

Target MCU

Options:

nrf52 | msp430

--simulate

dry-run the programmer - no data gets written

Arguments

FIRMWARE_FILE

Required argument

resync

Get current time and restarts PTP on each sheep.

shepherd-sheep resync [OPTIONS]

retrieve

Retrieve remote hdf file FILENAME and stores in OUTDIR.

filename: can either be (a) remote file with absolute path or relative path in ‘/var/shepherd/recordings/’ or (b) local job- / task-file that did already run (embedded paths are retrieved)

outdir: local path to put the files in ‘outdir/[node-name]/filename’

shepherd-sheep retrieve [OPTIONS] FILENAME OUTDIR

Options

-t, --timestamp

Add current timestamp to measurement file

-s, --separate

Every remote node gets own subdirectory

-d, --delete

Delete the file from the remote filesystem after retrieval

-f, --force-stop

Stop the on-going harvest/emulation process before retrieving the data

Arguments

FILENAME

Required argument

OUTDIR

Required argument

run

Run a task or set of tasks with provided config/task file (YAML).

shepherd-sheep run [OPTIONS] CONFIG

Options

-a, --attach

Wait and receive output on shell

Arguments

CONFIG

Required argument

shell-cmd

Run COMMAND on the shell.

shepherd-sheep shell-cmd [OPTIONS] COMMAND

Options

-s, --sudo

Run command with sudo

Arguments

COMMAND

Required argument

start

Start pre-configured shp-service.

  • source /etc/shepherd/config.yml,

  • UNSYNCED when ‘time_start’ is not set)

shepherd-sheep start [OPTIONS]

status

Information about current state of shepherd measurement.

shepherd-sheep status [OPTIONS]

stop

Stop any harvest/emulation or other processes blocking the sheep.

shepherd-sheep stop [OPTIONS]

Unittests

To run the full range of python tests, have a copy of the source code on a BeagleBone. Build and install from source (see Getting started for more). Change into the software/python-package directory on the BeagleBone and run the following commands to:

  • install dependencies of tests

  • run testbench

cd /opt/shepherd/software/python-package
sudo pip3 install ./[tests]
sudo pytest-3

Some tests (~40) are hardware-independent, while most of them require a BeagleBone to work (~100). The testbench detects the BeagleBone automatically. A small subset of tests (~8) are writing & configuring the EEPROM on the shepherd cape and must be enabled manually (sudo pytest --eeprom-write)

The following commands allow to:

  • restartable run that exits for each error (perfect for debugging on slow BBone)

  • run single tests,

  • whole test-files or

sudo pytest-3 --stepwise

sudo pytest-3 tests/test_sheep_cli.py::test_cli_emulate_aux_voltage

sudo pytest-3 tests/test_sheep_cli.py

Reference