Raspberry Build HAT: Unit Testing Strategies with .NET

If you go beyond hobby tinkering and aim for reliable, maintainable software, you need tests. Hardware projects are no exception. In fact, the closer you get to IO, timing and device state, the more you benefit from having a fast feedback loop and repeatable verification.

This post builds on the previous article where we controlled LEGO motors from .NET using the Raspberry Pi Build HAT: Raspberry Build HAT: Controlling LEGO Engines with .NET . Here, we focus on testability and show a pragmatic way to introduce unit tests without needing the physical hardware for every run.

Why not just unit test everything? Direct calls into Build HAT are by nature integration tests: they cross process and machine boundaries (serial/I2C), depend on timing and require the hardware to be connected. In addition:

The Build HAT stack is hardware-dependent; without a Pi and the HAT attached, calls will fail by design.
APIs and firmware can vary, leading to occasional flakiness when testing “for real”.
Behavior differs between Windows (dev box) and Linux (the Pi), so portability issues can creep in.

The solution is to define a small abstraction for the device and test your application logic against it. Use a real implementation for production and a virtual or mocked implementation for unit tests. Keep end-to-end tests (that hit the actual HAT) as integration tests executed on a Raspberry Pi.

Implementation

Concrete device class for physical access:

C#
 1public class BrickHatEngineDevice : IEngineDevice
 2{
  private readonly Lock _lock = new();
  private readonly EngineDeviceOptions _options;
  private Brick? _brick;
 6
  public string SerialPort => _options.SerialPort;
 8
  public BrickHatEngineDevice(IOptions<EngineDeviceOptions> optionsAccessor)
  {
      _options = optionsAccessor.Value;
      _brick = new Brick(_options.SerialPort);
  }
14
  public void Dispose()
  {
      _brick?.Dispose();
      _brick = null;
  }
20
  public void SendRawCommand(string command)
  {
      lock (_lock)
      {
          _brick?.SendRawCommand(command);
      }
  }
28}

About locking: the lock ensures only one thread interacts with the underlying Brick at a time. This prevents accidental concurrent access (for example while initializing or disposing) and avoids interleaving commands on the serial connection.

Virtual device class to run without hardware, enabling fast and deterministic unit tests:

C#
 1public class VirtualEngineDevice : IEngineDevice
 2{
  private readonly Lock _lock = new();
  private bool _disposed;
  private readonly EngineDeviceOptions _options;
  private const int MaxCommands = 500;
 7
  public VirtualEngineDevice(IOptions<EngineDeviceOptions> options)
  {
      _options = options.Value;
  }
12
  public IReadOnlyList<string> Commands
  {
      get
      {
          lock (_lock)
          {
              return _commands.ToList();
          }
      }
  }
23
  public string SerialPort => _options.SerialPort;
25
  private readonly Queue<string> _commands = new();
27
  public void SendRawCommand(string command)
  {
      if (_disposed)
      {
          throw new ObjectDisposedException(nameof(VirtualEngineDevice));
      }
34
      if (string.IsNullOrWhiteSpace(command))
      {
          return; // ignore invalid / empty commands in virtual implementation
      }
39
      lock (_lock)
      {
          _commands.Enqueue(command);
          if (_commands.Count > MaxCommands)
          {
              _commands.Dequeue(); // drop oldest
          }
      }
  }
49
  public void Dispose()
  {
      lock (_lock)
      {
          _disposed = true;
          _commands.Clear();
      }
      GC.SuppressFinalize(this);
  }
59}

Shared device interface to keep your higher-level code independent from hardware specifics:

C#
1public interface IEngineDevice : IDisposable
2{
3    string SerialPort { get; }
4    void SendRawCommand(string command);
5}

Options class to hold configuration (injected via .NET Options pattern):

C#
1public class EngineDeviceOptions
2{
3    [Required]
4    public string SerialPort { get; set; } = null!;
5}

A small factory that tries to create the physical device; if that fails, it falls back to the virtual one. This gives you a graceful runtime behavior (with logs) while keeping tests simple:

C#
 1public interface IEngineDeviceFactory
 2{
 3    IEngineDevice Create();
 4}
 5
 6public class EngineDeviceFactory : IEngineDeviceFactory
 7{
 8    private readonly IServiceProvider _serviceProvider;
 9    private readonly ILogger<EngineDeviceFactory> _log;
10
11    public EngineDeviceFactory(IServiceProvider serviceProvider, ILogger<EngineDeviceFactory> log)
12    {
13        _serviceProvider = serviceProvider;
14        _log = log;
15    }
16
17    public IEngineDevice Create()
18    {
19        IOptions<EngineDeviceOptions> options = _serviceProvider.GetRequiredService<IOptions<EngineDeviceOptions>>();
20
21        IEngineDevice device;
22        try
23        {
24            device = new BrickHatEngineDevice(options);
25            _log.LogInformation("Physical engine device initialized in port {SerialPort}", device.SerialPort);
26        }
27        catch(Exception ex)
28        {
29            _log.LogError(ex, "Failed to initialize physical engine device in port {SerialPort}", options.Value.SerialPort);
30            device = new VirtualEngineDevice(options);
31            _log.LogWarning("Virtual engine device initialized in port {SerialPort}", device.SerialPort);
32        }
33
34        return device;
35    }
36}

Unit testing with a virtual device or a mock

With the abstraction in place, unit tests can run on any machine without the HAT attached. You can either:

Use the VirtualEngineDevice for realistic, append-only command capture, or
Mock IEngineDevice with your favorite library (e.g., NSubstitute, Moq) to verify interactions and error paths.

Example with NSubstitute (verifying delegation and error handling):

C#
 1  [Fact]
 2  public void SendRawCommand_ShouldDelegateToDevice()
 3  {
 4      IEngineDevice engine = Substitute.For<IEngineDevice>();
 5      InMemoryLogger<BrickCommandProvider> logger = new();
 6      BrickCommandProvider provider = new(engine, logger);
 7
 8      provider.SendRawCommand("FORWARD");
 9
10      engine.Received(1).SendRawCommand("FORWARD");
11  }
12
13[Fact]
14public void SendRawCommand_WhenDeviceThrows_ShouldLogAndRethrow()
15{
16    IEngineDevice engine = Substitute.For<IEngineDevice>();
17    engine.When(e => e.SendRawCommand(Arg.Any<string>())).Do(_ => throw new InvalidOperationException("boom"));
18    InMemoryLogger<BrickCommandProvider> logger = new();
19    BrickCommandProvider provider = new(engine, logger);
20
21    InvalidOperationException ex = Assert.Throws<InvalidOperationException>(() => provider.SendRawCommand("ERR"));
22    Assert.Equal("boom", ex.Message);
23}

You can also unit-test the behavior of the virtual implementation itself. For example, ignoring empty commands and honoring the ring buffer limit:

C#
 1[Fact]
 2public void VirtualDevice_ShouldIgnoreEmptyAndKeepCapacity()
 3{
 4    IOptions<EngineDeviceOptions> options = Substitute.For<IOptions<EngineDeviceOptions>>();
 5    options.Value.Returns(new EngineDeviceOptions { SerialPort = "/dev/serial0" });
 6
 7    VirtualEngineDevice device = new (options);
 8
 9    device.SendRawCommand("");          // ignored
10    device.SendRawCommand(" ");         // ignored
11    device.SendRawCommand("FORWARD");   // kept
12
13    Assert.Single(device.Commands);
14    Assert.Equal("FORWARD", device.Commands[0]);
15}

Tips:

Treat tests that talk to the real HAT as integration tests. Mark/skip them on CI unless a Pi runner is available.
Test concurrency: ensure your orchestration code doesn’t interleave commands. The lock in the physical device helps here.
Test disposal and error paths: verify your component logs and surfaces exceptions appropriately.

Conclusion

By introducing a tiny abstraction, you can keep all your orchestration logic unit-testable while still supporting the real device at runtime. The virtual implementation enables fast and deterministic tests and the factory provides a graceful fallback when hardware isn’t present.

It’s only a few extra lines compared to “spaghetti” code that talks to the HAT directly–but it pays off immediately with confidence, safety during refactors and easier collaboration. From here, consider adding richer simulations (timing, failures), categorizing integration tests and wiring this into your CI so both fast unit tests and slower device tests have their place.