Command-line tools¶
Shepherd offers two command line utilities:
Shepherd-herd is the command line utility for remotely controlling a group of shepherd nodes. This is the key user interface to shepherd. The pure-python package is installed on the user’s local machine and sends commands to the shepherd nodes over ssh.
Shepherd-sheep is the command line utility for locally controlling a single shepherd node. Depending on your use-case you may not even need to directly interact with it!
shepherd-herd¶
shepherd-herd¶
shepherd-herd [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-filename<key_filename>¶ Path to private ssh key file
-
-v,--verbose¶
emulate¶
Emulates IV data read from INPUT hdf5 file
shepherd-herd 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
-
--no-calib¶ Use default calibration values
-
--load<load>¶ Choose artificial or sensor node load
- Options
artificial|node
-
-c,--ldo-voltage<ldo_voltage>¶ Pre-charge capacitor before starting recording
-
--config<config>¶ Read configuration from FILE.
-
--start,--no-start¶ Start shepherd after uploading config
Arguments
-
INPUT_PATH¶ Required argument
record¶
Records IV data
shepherd-herd record [OPTIONS]
Options
-
-o,--output_path<output_path>¶ Dir or file path for resulting hdf5 file
-
--mode<mode>¶ Record ‘harvesting’ or ‘load’ data
- Options
harvesting|load
-
-d,--duration<duration>¶ Duration of recording in seconds
-
-f,--force_overwrite¶ Overwrite existing file
-
--no-calib¶ Use default calibration values
-
--harvesting-voltage<harvesting_voltage>¶ Set fixed reference voltage for harvesting
-
--load<load>¶ Choose artificial or sensor node load
- Options
artificial|node
-
-c,--ldo-voltage<ldo_voltage>¶ Sets voltage of variable LDO
-
--ldo-mode<ldo_mode>¶ Select if LDO should just pre-charge capacitor or run continuously
- Options
pre-charge|continuous
-
--start,--no-start¶ Start shepherd after uploading config
retrieve¶
Retrieves remote hdf file FILENAME and stores in in OUTDIR
shepherd-herd retrieve [OPTIONS] FILENAME OUTDIR
Options
-
-r,--rename¶
-
-d,--delete¶ Delete the file from the remote filesystem after retrieval
-
-s,--stop¶ Stop the on-going recording/emulation process before retrieving the data
Arguments
-
FILENAME¶ Required argument
-
OUTDIR¶ Required argument
run¶
Run COMMAND on the shell
shepherd-herd run [OPTIONS] COMMAND
Options
-
-s,--sudo¶ Run command with sudo
Arguments
-
COMMAND¶ Required argument
target¶
Remote programming/debugging of the target sensor node
shepherd-herd target [OPTIONS] COMMAND [ARGS]...
Options
-
-p,--port<port>¶ Port on which OpenOCD should listen for telnet
-
--on,--off¶ Enable/disable power and debug access to the target
Examples¶
In the following we assume that you have an ansible style, YAML-formatted inventory file named hosts in your current working diretory. Refer to the example hosts file in the root directory of the shepherd repository. To start recording harvesting data using the hardware MPPT algorithm and store it under the default path, overwriting existing data and precharging the capacitor before starting the recording:
shepherd-herd -i hosts record -f --init-charge
To stop recording on a subset of nodes (sheep1 and sheep3 in this example):
shepherd-herd -i hosts -l sheep1,sheep3 stop
Another example for recording, this time with a fixed harvesting voltage of 600mV, limited recording duration of 30s and storing the result under /var/shepherd/recordings/rec_v_fixed.h5. Also, instead of using the inventory file option, we specify hosts and ssh user on the command line:
shepherd-herd -i sheep0,sheep1, -u jane record -d 30 --harvesting-voltage 0.6 -o rec_v_fixed.h5
To retrieve the recordings from the shepherd nodes and store them locally on your machine under the recordings/ directory:
shepherd-herd -i hosts retrieve -d rec_v_fixed.h5 recordings/
Before turning to emulation, here’s how to flash a firmware image to the attached sensor nodes. To flash the image firmware.bin that is stored on the local machine:
shepherd-herd -i hosts target flash firmware.bin
To reset the CPU on the sensor nodes:
shepherd-herd -i hosts target reset
Finally, to replay previously recorded data from the file rec.h5 in the shepherd node’s file system and store the recorded IV data from the load as load.h5:
shepherd-herd -i hosts emulate -o load.h5 rec.h5