Blink1.Api 1.0.8

dotnet add package Blink1.Api --version 1.0.8
                    
NuGet\Install-Package Blink1.Api -Version 1.0.8
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Blink1.Api" Version="1.0.8" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Blink1.Api" Version="1.0.8" />
                    
Directory.Packages.props
<PackageReference Include="Blink1.Api" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Blink1.Api --version 1.0.8
                    
#r "nuget: Blink1.Api, 1.0.8"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Blink1.Api@1.0.8
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Blink1.Api&version=1.0.8
                    
Install as a Cake Addin
#tool nuget:?package=Blink1.Api&version=1.0.8
                    
Install as a Cake Tool

Blink1.Api

NuGet License: MIT .NET 11.0 CI Codacy Badge Codacy Coverage

Need help with APIs or .NET? Panoramic Data are experts in APIs and .NET, and we can help with your development. Contact us or see our software services.

A typed, modern .NET client for the ThingM blink(1) USB RGB LED: find the devices attached, and send every firmware command (colours and fades, single LEDs, stored patterns and playback, server tickle, notes, startup parameters and more) on Windows, Linux and macOS.

Supports .NET 11.0.

Blink1.Api is an independent open-source project by Panoramic Data Limited. It is not made, endorsed or supported by ThingM. blink(1) is a trademark of ThingM Corporation.

Installation

dotnet add package Blink1.Api

Blink1.Api targets .NET 11.0 and uses HidSharp for USB HID access. On Linux, give your user access to the device with a udev rule, then replug it:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="27b8", ATTRS{idProduct}=="01ed", TAG+="uaccess"

Quick start

using Blink1.Api;

using var blink1 = Blink1Client.Open(new Blink1ClientOptions());

await blink1.FadeToColorAsync(Blink1Colors.Green, TimeSpan.FromMilliseconds(500), CancellationToken.None);

Finding devices

foreach (var device in Blink1Client.GetDevices())
{
	Console.WriteLine($"{device.SerialNumber} {device.ProductName} ({device.Generation})");
}

using var second = Blink1Client.Open(new Blink1ClientOptions { SerialNumber = "20002" });

With no serial number or device path in the options, the first device (by serial number) is opened. Blink1Exception is thrown when none matches.

Colours

var ct = CancellationToken.None;

await blink1.SetColorAsync(Blink1Color.Parse("#FF8000"), ct);                              // every LED, at once
await blink1.FadeToColorAsync(Blink1Colors.Blue, TimeSpan.FromSeconds(2), Blink1Led.Second, ct);
await blink1.SetColorAsync(Blink1Colors.Red, Blink1Led.First, ct);                          // mk2 and later
var top = await blink1.ReadColorAsync(Blink1Led.First, ct);                                 // mk2 and later
await blink1.TurnOffAsync(ct);

Colours are gamma-corrected as ThingM's own tools do, so they look the same. Set ApplyGammaCorrection = false to send raw values.

Patterns and playback

The device stores a pattern of colour lines (12 on mk1, 32 on later generations) and can play it by itself.

await blink1.WritePatternLineAsync(0, new Blink1PatternLine(Blink1Colors.Red, TimeSpan.FromMilliseconds(300), Blink1Led.All), ct);
await blink1.WritePatternLineAsync(1, new Blink1PatternLine(Blink1Colors.Black, TimeSpan.FromMilliseconds(300), Blink1Led.All), ct);
await blink1.PlayLoopAsync(0, 1, 5, ct);      // lines 0 to 1 inclusive, five times
var state = await blink1.ReadPlayStateAsync(ct);
await blink1.StopAsync(ct);
await blink1.SavePatternsAsync(ct);           // keep the pattern over power-down

After SavePatternsAsync the device answers slowly for about ten seconds while it writes flash; failed USB transfers in that time are retried automatically (MaxRetries, default 3).

Server tickle

A watchdog: unless your program calls again within the timeout, the device starts playing its pattern by itself, so a crashed or hung host is visible.

await blink1.EnableServerTickleAsync(TimeSpan.FromSeconds(30), ct);   // call again before 30 s pass
await blink1.DisableServerTickleAsync(ct);

Device information and mk3 features

var version = await blink1.GetFirmwareVersionAsync(ct);   // for example 204

mk3 and later also have notes (WriteNoteAsync, ReadNoteAsync), startup parameters (SetStartupParametersAsync, GetStartupParametersAsync), the chip ID (GetChipIdAsync) and bootloader commands (EnterBootloaderAsync, and the irreversible LockBootloaderAsync). mk1 has EEPROM access (ReadEepromAsync, WriteEepromAsync).

A command the device's generation lacks throws NotSupportedException before anything is sent. When the generation cannot be determined, every command is sent.

Read-only mode

using var observer = Blink1Client.Open(new Blink1ClientOptions { IsReadOnly = true });

Every command that changes the device then throws InvalidOperationException before it is sent; reads still work.

Errors

  • Blink1Exception: no matching device, a USB transfer that still failed after retries, or an unexpected answer.
  • NotSupportedException: the device's generation lacks the command.
  • InvalidOperationException: a write on a read-only client.
  • ArgumentOutOfRangeException: a pattern position past the device's pattern, or a time outside 0 to 655.35 s.

Blink1Client is safe to share between threads; commands to one device are sent one at a time.

Coverage

All 21 firmware commands are implemented; docs/endpoints/commands.md lists each with its client methods and tests. They are verified live on a blink(1) mk2 (firmware 204); mk1, mk3 and mk4 commands are verified by unit tests against the documented protocol. See docs/TESTING.md.

Quality

Unit tests cover 100% of lines and branches, and an inventory test keeps the command list and the client in step. The build treats warnings as errors.

Licence

MIT. See LICENSE.

Product Compatible and additional computed target framework versions.
.NET net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.8 0 11/19/2026
1.0.7 85 11/13/2026
1.0.6 91 11/11/2026
1.0.5 89 11/11/2026
1.0.3 94 11/8/2026