Testing hardware-driven projects pays off quickly. Compared to driving a single LEGO motor, controlling a WS2812B lightstrip involves timing constraints, color math, frame buffers, and update sequencing–lots of places where regressions can hide. A focused unit-testing approach helps keep this code reliable and fast to iterate on. For more background on the general pattern, see the Build HAT article: Raspberry Build HAT: Unit Testing Strategies with .NET .
This post is a follow-up to: Raspberry Pi WS2812B Lightstrip Control with .NET . Here, we’ll make the lightstrip control testable by introducing a tiny device abstraction with two implementations: a physical SPI+WS2812B device for production, and a virtual device for unit tests. The overall structure mirrors the Build HAT approach, but the implementation details are a bit more involved because of pixel framing and update timing.
Shared interface:
1public interface ILedStripDevice : IDisposable
2{
3 int NumberOfLeds { get; }
4 LedStripResult SetPixels(List<PixelMessage> pixels, bool update, bool preClear);
5 LedStripResult Reset();
6 LedStripResult Update();
7}
And the shared options:
1public class LedStripDeviceOptions
2{
3 public int NumberOfLeds { get; set; } = 1;
4}
Physical device (SPI + WS2812B):
1public class PhysicalSpiLedStripDevice : ILedStripDevice, IDisposable
2{
3 private readonly Ws2812b _ledDevice;
4 private readonly SpiDevice _spiDevice;
5 private readonly LedStripDeviceOptions _options;
6 private readonly Lock _lock = new();
7 private readonly ILogger<PhysicalSpiLedStripDevice> _log;
8 private bool _disposed;
9
10 public int NumberOfLeds => _options.NumberOfLeds;
11
12 public PhysicalSpiLedStripDevice(IOptions<LedStripDeviceOptions> options, ILogger<PhysicalSpiLedStripDevice> log)
13 {
14 _options = options.Value;
15 _log = log;
16
17 if (_options.NumberOfLeds <= 0)
18 {
19 _log.LogError("Invalid NumberOfLeds: {NumberOfLeds}", _options.NumberOfLeds);
20 throw new ArgumentOutOfRangeException(nameof(_options.NumberOfLeds), "NumberOfLeds must be > 0.");
21 }
22
23 SpiConnectionSettings spi = new(busId:0, chipSelectLine: 0)
24 {
25 ClockFrequency = 2_400_000,
26 Mode = SpiMode.Mode0,
27 DataBitLength = 8
28 };
29
30 _spiDevice = SpiDevice.Create(spi);
31 _ledDevice = new Ws2812b(_spiDevice, _options.NumberOfLeds);
32
33 ClearAll();
34 }
35
36 public LedStripResult SetPixels(List<PixelMessage> pixels, bool update, bool preClear)
37 {
38 if (_disposed)
39 {
40 _log.LogWarning("SetPixels called on disposed device.");
41 return LedStripResult.Disposed;
42 }
43 if (pixels is null)
44 {
45 _log.LogError("SetPixels called with null pixels list.");
46 return LedStripResult.InvalidValue;
47 }
48
49 lock (_lock)
50 {
51 if (preClear)
52 {
53 _ledDevice.Image.Clear();
54 _log.LogInformation("Pre-cleared all pixels on strip.");
55 }
56
57 foreach (PixelMessage p in pixels)
58 {
59 Color color = p.Color.ToColor();
60
61 if (p.Y != 0 || p.X < 0 || p.X >= NumberOfLeds)
62 {
63 _log.LogError("Pixel out of range: X={X}, Y={Y}", p.X, p.Y);
64 return LedStripResult.InvalidValue;
65 }
66
67 _ledDevice.Image.SetPixel(p.X, p.Y, color);
68 _log.LogInformation("Set pixel X={X}, Y={Y}, Color={Color}", p.X, p.Y, color);
69 }
70
71 if (update)
72 {
73 _ledDevice.Update();
74 Thread.Sleep(1); // Latch/Reset ≥ 50 µs (1ms for safety)
75 _log.LogInformation("Pixels updated on strip.");
76 }
77 }
78
79 _log.LogInformation("SetPixels executed successfully.");
80 return LedStripResult.Executed;
81 }
82
83 public LedStripResult Update()
84 {
85 if (_disposed)
86 {
87 _log.LogWarning("Update called on disposed device.");
88 return LedStripResult.Disposed;
89 }
90
91 lock (_lock)
92 {
93 _ledDevice.Update();
94 Thread.Sleep(1); // Latch/Reset ≥ 50 µs
95 _log.LogInformation("Framebuffer transmitted to strip.");
96 }
97
98 _log.LogInformation("Update executed successfully.");
99 return LedStripResult.Executed;
100 }
101
102 public LedStripResult ClearAll()
103 {
104 if (_disposed)
105 {
106 _log.LogWarning("ClearAll called on disposed device.");
107 return LedStripResult.Disposed;
108 }
109
110 lock (_lock)
111 {
112 _ledDevice.Image.Clear(Color.Black);
113 _ledDevice.Update();
114 Thread.Sleep(1);
115 _log.LogInformation("All LEDs cleared (set to black).");
116 }
117
118 _log.LogInformation("ClearAll executed successfully.");
119 return LedStripResult.Executed;
120 }
121
122 public LedStripResult Reset() => ClearAll();
123
124 public void Dispose()
125 {
126 lock (_lock)
127 {
128 if (_disposed)
129 {
130 _log.LogWarning("Dispose called on already disposed device.");
131 return;
132 }
133 _disposed = true;
134 _spiDevice?.Dispose();
135 _log.LogInformation("PhysicalSpiLedStripDevice disposed.");
136 }
137 GC.SuppressFinalize(this);
138 }
139}
Virtual device:
1public sealed class VirtualLedStripDevice : ILedStripDevice
2{
3 private readonly ILogger<VirtualLedStripDevice> _log;
4 private readonly LedStripDeviceOptions _options;
5 private readonly Lock _lock = new();
6 private bool _disposed;
7
8 public int NumberOfLeds => _options.NumberOfLeds;
9
10 public VirtualLedStripDevice(IOptions<LedStripDeviceOptions> options, ILogger<VirtualLedStripDevice> log)
11 {
12 _options = options.Value;
13 _log = log ?? throw new ArgumentNullException(nameof(log));
14
15 if (_options.NumberOfLeds <= 0)
16 {
17 throw new ArgumentOutOfRangeException(nameof(_options.NumberOfLeds), "NumberOfLeds must be > 0.");
18 }
19
20 _log.LogInformation("VirtualLedStripDevice initialized with {Count} LEDs", _options.NumberOfLeds);
21 }
22
23 public LedStripResult Reset()
24 {
25 if (_disposed) return LedStripResult.Disposed;
26
27 lock (_lock)
28 {
29 _log.LogInformation("Virtual reset invoked (clearing {Count} LEDs)", _options.NumberOfLeds);
30 return LedStripResult.Executed;
31 }
32 }
33
34 public LedStripResult SetPixels(List<PixelMessage> pixels, bool update, bool preClear)
35 {
36 if (_disposed) return LedStripResult.Disposed;
37 if (pixels is null)
38 {
39 _log.LogWarning("SetPixel called with null list");
40 return LedStripResult.InvalidValue;
41 }
42
43 lock (_lock)
44 {
45 if (preClear)
46 {
47 _log.LogInformation("Pre-clearing all pixels on virtual strip");
48 }
49
50 if (pixels.Exists(p => p.X < 0 || p.Y < 0))
51 {
52 _log.LogWarning("SetPixel contains invalid (negative) coordinates");
53 return LedStripResult.InvalidValue;
54 }
55
56 _log.LogInformation("SetPixel applying {Count} pixels (virtual)", pixels.Count);
57 }
58
59 // auto update
60 if (update)
61 {
62 return Update();
63 }
64
65 return LedStripResult.Executed;
66 }
67
68 public LedStripResult Update()
69 {
70 if (_disposed) return LedStripResult.Disposed;
71
72 lock (_lock)
73 {
74 _log.LogInformation("Virtual update (flush) called");
75 return LedStripResult.Executed;
76 }
77 }
78
79 public void Dispose()
80 {
81 lock (_lock)
82 {
83 if (_disposed) return;
84 _disposed = true;
85 _log.LogInformation("VirtualLedStripDevice disposed");
86 }
87 GC.SuppressFinalize(this);
88 }
89}
Factory:
1public interface ILedStripDeviceFactory
2{
3 ILedStripDevice Create();
4}
5
6public class LedStripDeviceFactory(IServiceProvider serviceProvider, ILogger<LedStripDeviceFactory> log) : ILedStripDeviceFactory
7{
8 public ILedStripDevice Create()
9 {
10 IOptions<LedStripDeviceOptions> options = serviceProvider.GetRequiredService<IOptions<LedStripDeviceOptions>>();
11
12 ILedStripDevice device;
13 try
14 {
15 ILogger<PhysicalSpiLedStripDevice> deviceLog = serviceProvider.GetRequiredService<ILogger<PhysicalSpiLedStripDevice>>();
16 device = new PhysicalSpiLedStripDevice(options, deviceLog);
17 log.LogInformation("Physical SPI LED strip device initialized with {Count} LEDs", device.NumberOfLeds);
18 }
19 catch
20 {
21 ILogger<VirtualLedStripDevice> logger = serviceProvider.GetRequiredService<ILogger<VirtualLedStripDevice>>();
22 device = new VirtualLedStripDevice(options, logger);
23 log.LogWarning("Failed to initialize physical LED strip device, falling back to virtual device with {Count} LEDs", device.NumberOfLeds);
24 }
25
26 return device;
27 }
28}
Result enum to keep API outcomes explicit (and exception-free for expected cases):
1public enum LedStripResult
2{
3 Unknown,
4 Disposed,
5 Executed,
6 InvalidValue
7}
With the abstraction in place, unit testing becomes straightforward:
1 [Fact]
2 public void SetPixel_WithNullPixels_ShouldNotCallDevice_AndLogSuccess()
3 {
4 // arrange
5 ILedStripDevice device = Substitute.For<ILedStripDevice>();
6 InMemoryLogger<LedStripProvider> providerLogger = new();
7 LedStripProvider provider = new(device, providerLogger);
8
9 // act
10 provider.SetPixel(null!, update: false, preClear: false);
11
12 // assert
13 device.DidNotReceive().SetPixels(Arg.Any<List<PixelMessage>>(), Arg.Any<bool>(), Arg.Any<bool>());
14 }
15
16 [Fact]
17 public void Update_ShouldDelegateToDevice()
18 {
19 // arrange
20 ILedStripDevice device = Substitute.For<ILedStripDevice>();
21 device.Update().Returns(LedStripResult.Executed);
22 InMemoryLogger<LedStripProvider> providerLogger = new();
23 LedStripProvider provider = new(device, providerLogger);
24
25 // act
26 provider.Update();
27
28 // assert
29 device.Received(1).Update();
30 }
More tests worth adding
1[Fact]
2public void SetPixels_WithOutOfRangeX_ShouldReturnInvalidValue()
3{
4 IOptions<LedStripDeviceOptions> options = Substitute.For<IOptions<LedStripDeviceOptions>>();
5 options.Value.Returns(new LedStripDeviceOptions { NumberOfLeds = 5 });
6 InMemoryLogger<PhysicalSpiLedStripDevice> log = new();
7 VirtualLedStripDevice device = new (options, new InMemoryLogger<VirtualLedStripDevice>());
8
9 List<PixelMessage> pixels = new () { new PixelMessage { X = 7, Y = 0, Color = PixelColor.Red } };
10
11 // Using the virtual device here; your provider facade should map this to InvalidValue
12 LedStripResult result = device.SetPixels(pixels, update: false, preClear: false);
13 Assert.Equal(LedStripResult.InvalidValue, result);
14}
Tips:
- Treat tests that talk to the real strip as integration tests (to be run on a Pi with the strip attached).
- Validate boundary cases (0 and last LED index), preClear behavior, and that Update is called when requested.
- Keep thread-safety: the device uses a lock to avoid interleaving SPI writes and to protect disposal.
Conclusion
By separating the LED strip access behind a small interface and providing both physical and virtual implementations, you get a fast unit test loop and a production-ready path. The LedStripResult keeps outcomes explicit, while dependency injection makes it simple to switch implementations.
It’s a small amount of extra structure compared to direct SPI calls–but it delivers big gains in confidence, maintainability, and collaboration. From here you can expand the virtual device to simulate timing, animations, and failure modes, and add a handful of integration tests that run on hardware in CI when available.
Author
BEN ABT
Ben is a Principal Software Engineer at Medialesson.de, with a strong focus on .NET and Microsoft Azure. In his professional role, he designs and builds highly scalable platforms for hybrid and cloud-based scenarios. He also advises companies and C-levels on migrating to the sovereign cloud.
He runs myCSharp.de, the largest and most active German-speaking C# community forum, actively contributes to both his own and external open-source projects, and regularly shares his knowledge through his blog, at community events, conferences, and as a writer for technical magazines.
Comments