Package: shepherd-herd
Shepherd-HerdShepherd-herdis the command line utility for controlling a group of shepherd nodes remotely through an IP-based network.Documentation:https://orgua.github.io/shepherd/Source Code:https://github.com/orgua/shepherdInstallationshepherd-herdis a python package and available onPyPI.
Use your python package manager to install it.
For example, using pip:pip3installshepherd-herdFor install directly from GitHub-Sources (heredev-branch):pipinstallgit+https://github.com/orgua/shepherd.git@dev#subdirectory=software/shepherd-herd-UFor install from local sources:cdshepherd/software/shepherd-herd/
pip3install.-UUsageAllshepherd-herdcommands require the list of hosts on which to perform the requested action.
This list of hosts is provided with the-ioption, that takes either the path to a file or a comma-separated list of hosts (compare Ansible-i).For example, save the following file in your current working directory as an ansible style, YAML-formatted inventory file namedherd.yml.sheep:hosts:sheep0:sheep1:sheep2:vars:ansible_user:janeTo find active nodes a ping-sweep (in this example from .1 to .64) can be achieved with:nmap-sn192.168.1.1-64After setting up the inventory, use shepherd-herd to check if all your nodes are responding correctly:shepherd-herd-iherd.ymlshell-cmd"echo 'hello'"Or, equivalently define the list of hosts on the command lineshepherd-herd-isheep0,sheep1,sheep2,shell-cmd"echo 'hello'"Tosimplify usageit is recommended to set up theherd.ymlin either of these directories (with falling lookup priority):relative to your current working directory ininventory/herd.ymlin your local home-directory~/herd.ymlin theconfig path/etc/shepherd/herd.yml(recommendation)From then on you can just call:shepherd-herdshell-cmd"echo 'hello'"Or select individual sheep from the herd:shepherd-herd--limitsheep0,sheep2,shell-cmd"echo 'hello'"Library-ExamplesSeeexample-filesfor details.CLI-ExamplesHere, we just provide a selected set of examples of how to useshepherd-herd. It is assumed that theherd.ymlis located at the recommended config path.For a full list of supported commands and options, runshepherd-herd --helpand for more detail for each commandshepherd-herd [COMMAND] --help.HarvestingSimultaneously start harvesting the connected energy sources on the nodes:shepherd-herdharvest-acv20-d30-ohrv.h5or with long arguments as alternativeshepherd-herdharvest--virtual-harvestercv20--duration30.0--output-pathhrv.h5Explanation:uses cv20 algorithm as virtual harvester (constant voltage 2.0 V)duration is 30sfile will be stored to/var/shepherd/recordings/hrv.h5and not forcefully overwritten if it already exists (add-ffor that)nodes will sync up and start immediately (otherwise add--no-start)For more harvesting algorithms seevirtual_harvester_fixture.yaml.EmulationUse the previously recorded harvest for emulating an energy environment for the attached sensor nodes and monitor their power consumption and GPIO events:shepherd-herdemulate--virtual-sourceBQ25504-oemu.h5hrv.h5Explanation:duration (-d) will be that of input file (hrv.h5)target port A will be selected for current-monitoring and io-routing (implicit--enable-io --io-port A --pwr-port A)second target port will stay unpowered (add--voltage-auxfor that)virtual source will be configured as BQ25504-Converterfile will be stored to/var/shepherd/recordings/emu.h5and not forcefully overwritten if it already exists (add-ffor that)nodes will sync up and start immediately (otherwise add--no-start)For more virtual source models seevirtual_source_fixture.yaml.Generalized Task-ExecutionAn individual task or set of tasks can be generated from experiments via theshepherd-coreof thedatalibshepherd-herdrunexperiment_file.yaml--attachExplanation:a set of tasks is send to the individual sheep and executed theretaskscurrently range frommodifying firmware / patching a node-id,flashing firmware to the targets,running an emulation- or harvest-taskthese individual tasks can be bundled up in observer-tasks -> a task-set for one sheepthese observer-tasks can be bundled up once more into testbed-tasksonlinemeans the program stays attached to the task and shows cli-output of the sheep, once the measurements are doneFile-distribution & retrievalRecordings and config-files can bedistributedto the remote nodes via:shepherd-herddistributehrv.h5The default remote path is/var/shepherd/recordings/. For security reasons there are only two allowed paths:/var/shepherd/for hdf5-recordings/etc/shepherd/for yaml-config-filesTo retrieve the recordings from the shepherd nodes and store them locally on your machine in the current working directory (./):shepherd-herdretrievehrv.h5./Explanation:look for remote/var/shepherd/recordings/hrv.h5(when not issuing an absolute path)don't delete remote file (add-dfor that)be sure measurement is done, otherwise you get a partial file (or add--force-stopto force it)files will be put in current working director (./rec_[node-name].h5, or./[node-name]/hrv.h5if you add--separate)you can add--timestampto extend filename (./rec_[timestamp]_[node-name].h5)Start, check and stop MeasurementsManuallystartinga pre-configured measurement can be done via:shepherd-herdstartNote 1: configuration is loading locally from/etc/shepherd/config.yml.Note 2: the start is not synchronized itself (you have to settime_startin config).The current state of the measurement can becheckedwith (console printout and return code):shepherd-herdstatusIf the measurement runs indefinitely or something different came up, and you want tostopforcefully:shepherd-herd-lsheep1stopCreating an InventoryCreating an overview for what's running on the individual sheep / hosts. An inventory-file is created for each host.shepherd-herdinventorize./Programming Targets (pru-programmer)The integrated programmer allows flashing a firmware image to an MSP430FR (SBW) or nRF52 (SWD) and shares the interface withshepherd-sheep. This example writes the imagefirmware_img.hexto a MSP430 on target port B and its programming port 2:shepherd-herdprogram--mcu-typemsp430--target-portB--mcu-port2firmware_img.hexTo check available options and arguments callshepherd-herdprogram--helpThe options default to:nRF52 as TargetTarget Port AProgramming Port 13 V Target Supply500 kbit/sDeprecated - Programming Targets (OpenOCD Interface)Flash a firmware imagefirmware_img.hexthat is stored on the local machine in your current working directory to the attached sensor nodes:shepherd-herdtargetflashfirmware_img.hexReset the sensor nodes:shepherd-herdtargetresetShutdownSheep can either be forced to power down completely or in this case reboot:shepherd-herdpoweroff--restartNOTE: Be sure to have physical access to the hardware for manually starting them again.TestbenchFor testingshepherd-herdthere must be a validherd.ymlat one of the three mentioned locations (look atsimplified usage) with accessible sheep-nodes (at least one). Navigate your host-shell into the package-folder/shepherd/software/shepherd-herd/and run the following commands for setup and running the testbench (~ 30 tests):pip3install./[tests]pytestToDoNone