Skip to main content

Synchronized Energy Harvesting Emulator and Recorder CLI

Project description


PyPiVersion CodeStyle

Shepherd-herd is the command line utility for controlling a group of shepherd nodes remotely through an IP-based network.


Source Code:


shepherd-herd is a pure python package and available on PyPI. Use your python package manager to install it. For example, using pip:

pip3 install shepherd-herd

For install from local sources:

cd shepherd/software/shepherd-herd/
pip3 install . -U


All shepherd-herd commands require the list of hosts on which to perform the requested action. This list of hosts is provided with the -i option, 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 named herd.yml.

    ansible_user: jane

To find active nodes a ping-sweep (in this example from .1 to .64) can be achieved with:

nmap -sn

After setting up the inventory, use shepherd-herd to check if all your nodes are responding correctly:

shepherd-herd -i herd.yml shell-cmd "echo 'hello'"

Or, equivalently define the list of hosts on the command line

shepherd-herd -i sheep0,sheep1,sheep2, shell-cmd "echo 'hello'"

To simplify usage it is recommended to set up the herd.yml in either of these directories (with falling lookup priority):

  • relative to your current working directory in inventory/herd.yml
  • in your local home-directory ~/herd.yml
  • in the config path /etc/shepherd/herd.yml (recommendation)

From then on you can just call:

shepherd-herd shell-cmd "echo 'hello'"

Or select individual sheep from the herd:

shepherd-herd --limit sheep0,sheep2, shell-cmd "echo 'hello'"


Here, we just provide a selected set of examples of how to use shepherd-herd. It is assumed that the herd.yml is located at the recommended config path.

For a full list of supported commands and options, run shepherd-herd --help and for more detail for each command shepherd-herd [COMMAND] --help.


Simultaneously start harvesting the connected energy sources on the nodes:

shepherd-herd harvest -a cv20 -d 30 -o hrv.h5

or with long arguments as alternative

shepherd-herd harvest --virtual-harvester cv20 --duration 30.0 --output-path hrv.h5


  • uses cv20 algorithm as virtual harvester (constant voltage 2.0 V)
  • duration is 30s
  • file will be stored to /var/shepherd/recordings/hrv.h5 and not forcefully overwritten if it already exists (add -f for that)
  • nodes will sync up and start immediately (otherwise add --no-start)

For more harvesting algorithms see virtual_harvester_fixture.yaml.


Use the previously recorded harvest for emulating an energy environment for the attached sensor nodes and monitor their power consumption and GPIO events:

shepherd-herd emulate --virtual-source BQ25504 -o emu.h5 hrv.h5


  • 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-aux for that)
  • virtual source will be configured as BQ25504-Converter
  • file will be stored to /var/shepherd/recordings/emu.h5 and not forcefully overwritten if it already exists (add -f for that)
  • nodes will sync up and start immediately (otherwise add --no-start)

For more virtual source models see virtual_source_fixture.yaml.

Data distribution & retrieval

Recordings and config-files can be distributed to the remote nodes via:

shepherd-herd distribute hrv.h5

The 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-files

To retrieve the recordings from the shepherd nodes and store them locally on your machine in the current working directory (./):

shepherd-herd retrieve hrv.h5 ./


  • look for remote /var/shepherd/recordings/hrv.h5 (when not issuing an absolute path)
  • don't delete remote file (add -d for that)
  • be sure measurement is done, otherwise you get a partial file (or add --force-stop to force it)
  • files will be put in current working director (./rec_[node-name].h5, or ./[node-name]/hrv.h5 if you add --separate)
  • you can add --timestamp to extend filename (./rec_[timestamp]_[node-name].h5)

Start, check and stop Measurements

Manually starting a pre-configured measurement can be done via:

shepherd-herd start

Note 1: configuration is loading from /etc/shepherd/config.yml.

Note 2: the start is not synchronized itself (you have to define a start-time in config).

The current state of the measurement can be checked with (console printout and return code):

shepherd-herd status

If the measurement runs indefinitely or something different came up, and you want to stop forcefully:

shepherd-herd -l sheep1 stop

Programming Targets (pru-programmer)

The integrated programmer allows flashing a firmware image to an MSP430FR (SBW) or nRF52 (SWD) and shares the interface with shepherd-sheep. This example writes the image firmware_img.hex to a MSP430 on target port B and its programming port 2:

shepherd-herd program --mcu-type msp430 --target-port B --mcu-port 2 firmware_img.hex

To check available options and arguments call

shepherd-herd program --help

The options default to:

  • nRF52 as Target
  • Target Port A
  • Programming Port 1
  • 3 V Target Supply
  • 500 kbit/s

Programming Targets (not maintained OpenOCD Interface)

Flash a firmware image firmware_img.hex that is stored on the local machine in your current working directory to the attached sensor nodes:

shepherd-herd target flash firmware_img.hex

Reset the sensor nodes:

shepherd-herd target reset


Sheep can either be forced to power down completely or in this case reboot:

shepherd-herd poweroff --restart


For testing shepherd-herd there must be a valid herd.yml at one of the three mentioned locations (look at simplified 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):

pip3 install ./[tests]


  • None

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shepherd_herd-0.4.5.tar.gz (20.5 kB view hashes)

Uploaded source

Built Distribution

shepherd_herd-0.4.5-py3-none-any.whl (20.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page