shepherd-herd
shepherd-herd is the command line utility for controlling a group of shepherd nodes remotely through an IP-based network.
Installation
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 ./
Usage
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.
sheep:
hosts:
sheep0:
sheep1:
sheep2:
vars:
ansible_user: jane
To find active nodes a ping-sweep (in this example from .1 to .64) can be achieved with:
nmap -sn 192.168.1.1-64
After setting up the inventory, use shepherd-herd to check if all your nodes are responding correctly:
shepherd-herd -i herd.yml run echo 'hello'
Or, equivalently define the list of hosts on the command line
shepherd-herd -i sheep0,sheep1,sheep2, run 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 run echo 'hello'
Or select individual sheep from the herd:
shepherd-herd --limit sheep0,sheep2, run echo 'hello'
Examples
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.
Harvesting
Simultaneously start harvesting the connected energy sources on the nodes:
shepherd-herd harvester -a cv20 -d 30 -o hrv.h5
or with long arguments as alternative
shepherd-herd harvester --algorithm cv20 --duration 30.0 --output_path hrv.h5
Explanation:
- uses cv33 algorithm (constant voltage 2.0 V)
- duration is 30s
- file 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 see virtual_harvester_defs.yml.
Emulation
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 emulator --virtsource BQ25504 -o emu.h5 hrv.h5
Explanation:
- 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_target A --pwr_target A) - second target port will stay unpowered (add
--aux_voltagefor that) - virtual source will be configured as BQ25504-Converter
- file 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 see virtual_source_defs.yml.
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 ./
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 Measurements
Manually starting a pre-configured measurement can be done via:
shepherd-herd start
Note 1: config is loading from /etc/shepherd/config.yml
Note 2: start is only loosely synchronized
The current state of the measurement can be checked with (console printout and return code):
shepherd-herd check
If the measurement runs indefinitely or something different came up, and you want to stop forcefully:
shepherd-herd -l sheep1 stop
Programming Targets
Flash a firmware image firmware_img.bin that is stored on the local machine in your current working directory to the attached sensor nodes:
shepherd-herd target flash firmware_img.bin
Reset the sensor nodes:
shepherd-herd target reset
Shutdown
Sheep can either be forced to power down completely or in this case reboot:
shepherd-herd poweroff --restart
Testbench
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. Navigate your shell into the package-folder /shepherd/software/shepherd-herd/ and run:
pytest
Note: keep the herd small for the tests as the current implementation does not parallelize connections to the nodes.
ToDo
- add programming-option to test
- add new pru-programmer to interface
Metadata
Release files for shepherd-herd 0.4.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| shepherd_herd-0.4.3.tar.gz | 17.7 kB | Without provenance | Details for shepherd_herd-0.4.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| shepherd_herd-0.4.3-py3-none-any.whl | Python 3 | none | any | Details for shepherd_herd-0.4.3-py3-none-any.whl |
Total release size: 35.4 kB
Release files / shepherd_herd-0.4.3.tar.gz
| Download URL | shepherd_herd-0.4.3.tar.gz |
|---|---|
| Size | 17.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
745930c8fadd7f534809419de7cc89cd5fad7bf38c2f0df656d088fb3be78b34
|
|
BLAKE2b-256 checksum How to use checksums |
8d8103f910da40b4f1251a3dd51e6e202cbbc70776c04973ab17eca7b854abff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.9.16
|
Release files / shepherd_herd-0.4.3-py3-none-any.whl
| Download URL | shepherd_herd-0.4.3-py3-none-any.whl |
|---|---|
| Size | 17.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
06dc9b8dfb0ccc8b30ebd254f7e33867c5c4057ac0f82a8e298b43055fe40422
|
|
BLAKE2b-256 checksum How to use checksums |
cc4dc058ae08a27379af438b7c8e4219f123b0c1f381bd2d15346ebcd0c03261
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.9.16
|
Security for shepherd-herd 0.4.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.