Core Library
Main Documentation: https://nes-lab.github.io/shepherd
Source Code: https://github.com/nes-lab/shepherd-tools
Main Project: https://github.com/nes-lab/shepherd
shepherd-core is designed as a library and bundles data-models and file-access-routines for the shepherd-testbed, that are used by several codebases.
For postprocessing shepherds .h5-files usage of shepherd_data is recommended.
Features
- read and write shepherds hdf5-files
- create, read, write and convert experiments for the testbed
- all required data-models are included
- simulate the virtual source, including virtual harvesters (and virtual converter as a whole)
- connect and query the testbed via a webclient (TestbedClient in alpha-stage)
- offline usage defaults to static demo-fixtures loaded from yaml-files in the model-directories
- work with target-firmwares
- embed, modify, verify, convert
- Note: working with ELF-files requires external dependencies, see
Installation-Chapter
- decode waveforms (gpio-state & timestamp) to UART
- create an inventory (for deployed versions of software, hardware)
See official documentation or example scripts for more details and usage. Most functionality is showcased in both. The extra-directory holds data-generators relevant for the testbed. Notably is a trafficbench-experiment that's used to derive the link-matrix of the testbed-nodes.
Config-Models in Detail
These pydantic data-models are used throughout all shepherd interfaces. Users can create an experiment, include their own content and feed it to the testbed.
- orchestration
/data-modelswith focus on remote shepherd-testbed - classes of sub-models
/base: base-classes, configuration and -functionality for all models/testbed: meta-data representation of all testbed-components/content: reusable user-defined meta-data for fw, h5 and vsrc-definitions/experiment: configuration-models including sub-systems/task: digestible configs for shepherd-herd or -sheep- behavior controlled by
ShpModelandcontent-model
- a basic database is available as fixtures through a
tb_client- fixtures selectable by name & ID
- fixtures support inheritance
- the models support
- auto-completion with neutral / sensible values
- complex and custom datatypes (i.e. PositiveInt, lists-checks on length)
- checking of inputs and type-casting
- generate their own schema (for web-forms)
- pre-validation
- store to & load from yaml with typecheck through wrapper
- documentation
- experiment-definition is designed securely
- types are limited in size (str)
- exposes no internal paths
- experiments can be transformed to task-sets (
TestbedTasks.from_xp())
Compatibility
| OS | PyVersion | Comment |
|---|---|---|
| Ubuntu | 3.8 - 3.13 | |
| Windows | 3.8 - 3.13 | no support for elf and hex-conversions yet |
| MacOS | 3.8 - 3.13 | hex-conversion missing |
Notes:
- hex-conversion needs a working and accessible objcopy
- elf-supports needs
shepherd-core[elf]installspwntools-elf-only- most elf-features also still utilize hex-conversion
Installation
The Library is available via PyPI and can be installed with
pip install shepherd-core -U
# or for the full experience (includes core)
pip install shepherd-data -U
For bleeding-edge-features or dev-work it is possible to install directly from GitHub-Sources (here dev-branch):
pip install git+https://github.com/nes-lab/shepherd-tools.git@dev#subdirectory=shepherd_core -U
# and on sheep with newer debian
sudo pip install git+https://github.com/nes-lab/shepherd-tools.git@dev#subdirectory=shepherd_core -U --break-system-packages
If you are working with .elf-files (embedding into experiments) you make "objcopy" accessible to python. In Ubuntu, you can either install build-essential or binutils-$ARCH with arch being msp430 or arm-none-eabi for the nRF52.
sudo apt install build-essential
For more advanced work with .elf-files (modify value of symbols / target-ID) you should install
pip install shepherd-core[elf]
and also make sure the prereqs for the pwntools are met.
For creating an inventory of the host-system you should install
pip install shepherd-core[inventory]
Unittests
To run the testbench, follow these steps:
- Navigate your host-shell into the package-folder and
- install dependencies
- run the testbench (~ 320 tests):
cd shepherd-tools/shepherd_core
pip3 install ./[tests]
pytest
1 maintainer
Release files for shepherd-core 2026.8.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| shepherd_core-2026.8.1.tar.gz | 599.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| shepherd_core-2026.8.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size:783.7 kB
Release files / shepherd_core-2026.8.1.tar.gz
| Download URL | shepherd_core-2026.8.1.tar.gz |
|---|---|
| Size | 599.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0bae2038e7e60456f28a1ef02899c72a44bff269438e2f251cb02e0678bf7829
|
|
BLAKE2b-256 checksum How to use checksums |
3e273a03cafbb110abc5b1545c42d02b00d7d77736120e248a920188bf8e1063
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logRelease files / shepherd_core-2026.8.1-py3-none-any.whl
| Download URL | shepherd_core-2026.8.1-py3-none-any.whl |
|---|---|
| Size | 184.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1d1d47db13001dd132831d035928df29fb7348c0b2a70f4235c161e8cb85464b
|
|
BLAKE2b-256 checksum How to use checksums |
4e42142467773914910e37761196423e3e0a671bcc4fd83d29ce64ee2d1bfa3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency log
