API¶

The shepherd API offers high level access to shepherd’s functionality and forms the base for the two command line utilities. Note that the API only convers local functionality on a single shepherd node. Use the shepherd-herd command line utility to orchestrate a group of shepherd nodes remotely.

Recorder¶

The recorder is used to configure all relevant hardware and software and to sample and extract data from the analog frontend.

class shepherd.Recorder(mode: str = 'harvesting', load: str = 'artificial', harvesting_voltage: float = None, ldo_voltage: float = None, ldo_mode: str = 'pre-charge')¶

API for recording data with shepherd.

Provides an easy to use, high-level interface for recording data with shepherd. Configures all hardware and initializes the communication with kernel module and PRUs.

Parameters

mode (str) – Should be either ‘harvesting’ to record harvesting data or ‘load’ to record target consumption data.
load (str) – Selects, which load should be used for recording. Should be one of ‘artificial’ or ‘node’.
harvesting_voltage (float) – Fixed reference voltage for boost converter input.
ldo_voltage (float) – Pre-charge capacitor to this voltage before starting recording.
ldo_mode (str) – Selects if LDO should just pre-charge capacitor or run continuously.

get_buffer(timeout: float = 1.0) → NoReturn¶

Reads a data buffer from shared memory.

Polls the RPMSG channel for a message from PRU0 and, if the message points to a filled buffer in memory, returns the data in the corresponding memory location as DataBuffer.

Parameters: timeout (float) – Time in seconds that should be waited for an incoming RPMSG
Returns: Index and content of corresponding data buffer
Raises: TimeoutException – If no message is received on RPMSG within specified timeout

return_buffer(index: int)¶

Returns a buffer to the PRU

After reading the content of a buffer and potentially filling it with emulation data, we have to release the buffer to the PRU to avoid it running out of buffers.

Parameters: index (int) – Index of the buffer. 0 <= index < n_buffers

set_harvester(state: bool) → NoReturn¶

Enables or disables connection to the harvester.

The harvester is connected to the main power path of the shepherd cape through a MOSFET relay that allows to make or break that connection. This way, we can completely disable the harvester during emulation.

Parameters: state (bool) – True for enabling harvester, False for disabling

set_harvesting_voltage(voltage: float) → NoReturn¶

Sets the reference voltage for the boost converter

In some cases, it is necessary to fix the harvesting voltage, instead of relying on the built-in MPPT algorithm of the BQ25505. This function allows setting the set point by writing the desired value to the corresponding DAC. Note that the setting only takes effect, if MPPT is disabled (see set_mppt())

Parameters: voltage (float) – Desired harvesting voltage in volt
Raises: ValueError – If requested voltage is out of range

set_ldo_voltage(voltage: float) → NoReturn¶

Enables or disables the constant voltage regulator.

The shepherd cape has a linear regulator that is connected to the load power path through a diode. This allows to pre-charge the capacitor to a defined value or to supply a sensor node with a fixed voltage. This function allows to enable or disable the output of this regulator.

Parameters: voltage (float) – Desired output voltage in volt. Providing 0 or False disables the LDO.

set_load(load: str) → NoReturn¶

Selects which load is connected to shepherd’s output.

The output of the main power path can be connected either to the on-board ‘artificial’ load (for recording) or to an attached sensor node (for emulation). This function configures the corresponding hardware switch.

Parameters

load (str) – The load to connect to the output of shepherd’s output.
of 'artificial' or 'node'. (One) –

Raises

NotImplementedError – If load is not ‘artificial’ or ‘node’

set_lvl_conv(state: bool) → NoReturn¶

Enables or disables the GPIO level converter.

The shepherd cape has a bi-directional logic level shifter (TI TXB0304) for translating UART and SWD signals between BeagleBone and target voltage levels. This function enables or disables the converter.

Parameters: state (bool) – True for enabling converter, False for disabling

set_mppt(state: bool) → NoReturn¶

Enables or disables Maximum Power Point Tracking of BQ25505

TI’s BQ25505 implements an MPPT algorithm, that dynamically adapts the harvesting voltage according to current conditions. Alternatively, it allows to provide a reference voltage to which it will regulate the harvesting voltage. This is necessary for emulation and can be used to fix harvesting voltage during recording as well.

Parameters: state (bool) – True for enabling MPPT, False for disabling

start(start_time: float = None, wait_blocking: bool = True) → NoReturn¶

Starts sampling either now or at later point in time.

Parameters

start_time (int) – Desired start time in unix time
wait_blocking (bool) – If true, block until start has completed

static wait_for_start(timeout: float) → NoReturn¶

Waits until shepherd has started sampling.

Parameters: timeout (float) – Time to wait in seconds

Usage:

# Configure converter for fixed 1.5V input regulation
with Recorder(harvesting_voltage=1.5) as recorder:
    recorder.start()

    for _ in range(100):
        idx, buf = recorder.get_buffer()
        recorder.release_buffer(idx)

Emulator¶

The emulator is used to replay previously recorded IV data to an attached sensor node.

class shepherd.Emulator(initial_buffers: list = None, calibration_recording: shepherd.calibration.CalibrationData = None, calibration_emulation: shepherd.calibration.CalibrationData = None, load: str = 'node', ldo_voltage: float = 0.0)¶

API for emulating data with shepherd.

Provides an easy to use, high-level interface for emulating data with shepherd. Configures all hardware and initializes the communication with kernel module and PRUs.

Parameters

calibration_recording (CalibrationData) – Shepherd calibration data belonging to the IV data that is being emulated
calibration_emulation (CalibrationData) – Shepherd calibration data belonging to the cape used for emulation
load (str) – Selects, which load should be used for recording. Should be one of ‘artificial’ or ‘node’.
ldo_voltage (float) – Pre-charge the capacitor to this voltage before starting recording.

get_buffer(timeout: float = 1.0) → NoReturn¶

Reads a data buffer from shared memory.

Polls the RPMSG channel for a message from PRU0 and, if the message points to a filled buffer in memory, returns the data in the corresponding memory location as DataBuffer.

Parameters: timeout (float) – Time in seconds that should be waited for an incoming RPMSG
Returns: Index and content of corresponding data buffer
Raises: TimeoutException – If no message is received on RPMSG within specified timeout

set_harvester(state: bool) → NoReturn¶

Enables or disables connection to the harvester.

The harvester is connected to the main power path of the shepherd cape through a MOSFET relay that allows to make or break that connection. This way, we can completely disable the harvester during emulation.

Parameters: state (bool) – True for enabling harvester, False for disabling

set_harvesting_voltage(voltage: float) → NoReturn¶

Sets the reference voltage for the boost converter

In some cases, it is necessary to fix the harvesting voltage, instead of relying on the built-in MPPT algorithm of the BQ25505. This function allows setting the set point by writing the desired value to the corresponding DAC. Note that the setting only takes effect, if MPPT is disabled (see set_mppt())

Parameters: voltage (float) – Desired harvesting voltage in volt
Raises: ValueError – If requested voltage is out of range

set_ldo_voltage(voltage: float) → NoReturn¶

Enables or disables the constant voltage regulator.

The shepherd cape has a linear regulator that is connected to the load power path through a diode. This allows to pre-charge the capacitor to a defined value or to supply a sensor node with a fixed voltage. This function allows to enable or disable the output of this regulator.

Parameters: voltage (float) – Desired output voltage in volt. Providing 0 or False disables the LDO.

set_load(load: str) → NoReturn¶

Selects which load is connected to shepherd’s output.

The output of the main power path can be connected either to the on-board ‘artificial’ load (for recording) or to an attached sensor node (for emulation). This function configures the corresponding hardware switch.

Parameters

load (str) – The load to connect to the output of shepherd’s output.
of 'artificial' or 'node'. (One) –

Raises

NotImplementedError – If load is not ‘artificial’ or ‘node’

set_lvl_conv(state: bool) → NoReturn¶

Enables or disables the GPIO level converter.

The shepherd cape has a bi-directional logic level shifter (TI TXB0304) for translating UART and SWD signals between BeagleBone and target voltage levels. This function enables or disables the converter.

Parameters: state (bool) – True for enabling converter, False for disabling

set_mppt(state: bool) → NoReturn¶

Enables or disables Maximum Power Point Tracking of BQ25505

TI’s BQ25505 implements an MPPT algorithm, that dynamically adapts the harvesting voltage according to current conditions. Alternatively, it allows to provide a reference voltage to which it will regulate the harvesting voltage. This is necessary for emulation and can be used to fix harvesting voltage during recording as well.

Parameters: state (bool) – True for enabling MPPT, False for disabling

start(start_time: float = None, wait_blocking: bool = True) → NoReturn¶

Starts sampling either now or at later point in time.

Parameters

start_time (int) – Desired start time in unix time
wait_blocking (bool) – If true, block until start has completed

static wait_for_start(timeout: float) → NoReturn¶

Waits until shepherd has started sampling.

Parameters: timeout (float) – Time to wait in seconds

Usage:

# We'll read existing data using a LogReader
lr = LogReader("mylog.h5")
with ExitStack() as stack:
    stack.enter_context(lr)
    emu = Emulator(
        calibration_recording=lr.get_calibration_data(),
        initial_buffers=lr.read_buffers(end=64),
    )
    stack.enter_context(emu)
    emu.start()

    for hrvst_buf in lr.read_buffers(start=64):
        idx, _ = emu.get_buffer()
        emu.put_buffer(idx, hrvst_buf)

LogWriter¶

The LogWriter is used to store IV data sampled with shepherd to an hdf5 file.

class shepherd.LogWriter(store_path: pathlib.Path, calibration_data: shepherd.calibration.CalibrationData, mode: str = 'harvesting', force_overwrite: bool = False, samples_per_buffer: int = 10000, buffer_period_ns: int = 100000000)¶

Stores data coming from PRU’s in HDF5 format

Parameters

store_path (str) – Name of the HDF5 file that data will be written to
calibration_data (CalibrationData) – Data is written as raw ADC values. We need calibration data in order to convert to physical units later.
mode (str) – Indicates if this is data from recording or emulation
force_overwrite (bool) – Overwrite existing file with the same name
samples_per_buffer (int) – Number of samples contained in a single shepherd buffer
buffer_period_ns (int) – Duration of a single shepherd buffer in nanoseconds

write_buffer(buffer: shepherd.shepherd_io.DataBuffer) → NoReturn¶

Writes data from buffer to file.

Parameters: buffer (DataBuffer) – Buffer containing IV data

write_exception(exception: shepherd.datalog.ExceptionRecord) → NoReturn¶

Writes an exception to the hdf5 file.

Parameters: exception (ExceptionRecord) – The exception to be logged

Usage:

with LogWriter("mylog.h5") as log_writer, Recorder() as recorder:
    recorder.start()
    for _ in range(100):
        idx, buf = recorder.get_buffer()
        log_writer.write_buffer(buf)
        recorder.release_buffer(idx)

LogReader¶

The LogReader is used to read previously recorded data from an hdf5 file buffer by buffer. It can be used with the Emulator to replay recorded data to an attached sensor node.

class shepherd.LogReader(store_path: pathlib.Path, samples_per_buffer: int = 10000)¶

Sequentially Reads data from HDF5 file.

Parameters

store_path (Path) – Path of hdf5 file containing IV data
samples_per_buffer (int) – Number of IV samples per buffer

get_calibration_data() → shepherd.calibration.CalibrationData¶

Reads calibration data from hdf5 file.

Returns: Calibration data as CalibrationData object

read_buffers(start: int = 0, end: int = None)¶

Reads the specified range of buffers from the hdf5 file.

Parameters

start (int) – Index of first buffer to be read
end (int) – Index of last buffer to be read

Yields

Buffers between start and end

Usage:

with LogReader("mylog.h5") as log_reader:
    for buf in log_reader.read_buffers(end=1000):
        print(len(buf))