About The Project

daisyHat aims to provide a framework for writing and executing automated tests for embedded hardware, with premium support for the Electro Smith Daisy platform. Tests can be run locally or in github actions and cover a wide range of test scenarios from simple one-device tests to complex hardware setups including custom measurement equipment and test fixtures.

daisyHat provides ...

a device-side C++ library that comes with assertion macros, flow control and other tooling to write tests on the hardware,
a host-side python library to upload device firmware images, collect test results and orchestrate tests that involve other hardware,
CMake functions and utilities to create a CMake project that contains multiple daisyHat tests which can be built and run with one command respectively,
a Docker image that can be used to deploy ephemeral github actions runners that are safe to use on public repositories,
setup scripts to prepare and install this Docker image on a Raspberry Pi 4B and turn it into the heart of a automated hardware testbed for github repositories.

WOKR IN PROGRESS This project is in very early stages and not production ready. Don't expect everything to be plug-and-play yet. Please help out where you can!

Example test

The simplest test consists of a single firmware image that performs the entire test on a Daisy Seed. View more complex example code here.

firmware.cpp

#include <daisy_seed.h>
#include <daisyHat.h>

daisy::DaisySeed seed;

int main()
{
    seed.Configure();
    seed.Init();

    daisyhat::Init(seed, "test1");
    int a = 1;
    int b = 1;
    EXPECT_EQ(a, b);
    daisyhat::FinishTest();
}

CMakeLists.txt

# register the test with CMake.
# This will upload the test to a Daisy Seed with name "Alice" and collect the results over USB-Serial
daisyhat_add_test(
    NAME test1
    SEED Alice
    SOURCES 
        firmware.cpp
)

Getting started

Core concepts:

Tests live in a git repository where daisyHat and libDaisy are available (e.g. as submodules)
A project-level daisyHat.config.json file describes the hardware setup
Depending on the test scenario, each test consists of one or multiple firmware images and additional host-side test execution scripts, if needed
All tests are accumulated into a CMake project so that building and running is entirely handled by CMake
GitHub actions integration is realised with an ephemeral test runner based on a docker image that can easily be deployed to a Raspberry Pi and is safe to use for public repositories

Setting up a test project

Create a new repository for your tests
Add libDaisy as a submodule in the lib/libDaisy folder
Add the daisyHat repo as a submodule in the lib/daisyHat folder
Add a CMakeLists.txt in the repository root that includes lib/libDaisy and lib/daisyHat as sub directories (with add_subdirectory()) (you can copy and edit this file)
For each test, create a new directory tests/<testName> and add to it
1. The C++ source code for your test firmware (take a look here)
2. A CMakeLists.txt file that registers a test firmware with the daisyhat_add_test() function (you can copy this file)
Include each of the test directories in the root CMakeLists.txt
Future addition: Describe the hardware configuration of your test setup in the daisyHat.config.json at the project root

Running the tests locally

Setup your toolchain with CMake, make, gcc-arm-none-eabi, openocd and Python3.9
Connect to each Daisy Seed board via USB
Connect to each Daisy Seed board via an STLinkv3 JTAG programmer
Configure the project: cmake -D TOOLCHAIN_PREFIX=<path-to-gcc-arm-none-eabi> -D CMAKE_TOOLCHAIN_FILE="lib/libDaisy/cmake/toolchains/stm32h750xx.cmake" -S . -B build -G "Unix Makefiles"
Build libDaisy, daisyHat and the tests: cmake --build build
Run the tests: ctest --output-on-failure

Running tests automatically via github ations

Prepare the target github repository by generating a personal access token to be able to register new github actions runners (see here)
Install Ubuntu Server 20.04 on a Raspberry Pi 4B
Download and execute the setup script (see here)
Connect the Pi to each Daisy Seed board via USB
Connect the Pi to each Daisy Seed board via an STLinkv3 JTAG programmer

Detailed instructions can be found here. Please note that the setup is currently not fully automated and still work in progress.

Project Structure

cmake/ contains cmake functions
docs/ contains documentation and guides
docker/ contains files to build the github action runner docker image
examples/ contains a usage example with two tests (one succeeds, one fails)
python/ contains the python library for the host computer / test runner
scripts/ contains scripts to setup and run a daisyHat test runner
src/ contains C++ library for the device firmware

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

TheSlowGrowth/daisyHat

daisyHat