NanoKVMSharp 1.0.1

NanoKVMSharp

.NET-клиент для управления NanoKVM (Sipeed) по HTTP API и WebSocket. Предназначен для встраивания в панель управления сервером: удалённый экран, мышь, клавиатура, GPIO, питание, хранилище, сеть и состояние устройства.

Возможности

• Авторизация — вход, смена пароля, проверка состояния пароля (AES-обфускация пароля как в оригинале).
• Удалённый экран — MJPEG-поток (/api/stream/mjpeg), получение снимка, постраничная передача кадров, автоматическое определение разрешения, управление детектором кадров.
• Удалённый ввод — клавиатура и мышь через WebSocket (/api/ws) в штатном HID-формате NanoKVM (относительная и абсолютная мышь, колесо, мультимедиа- и модификаторные клавиши, ввод текста).
• HID API — сброс HID, режимы normal / hid-only, состояние LED (Num/Caps/Scroll Lock), вставка текста через буфер обмена и выбор раскладки.
• Прочее — GPIO (power/reset), настройки экрана, образы/ISO, Wake-on-LAN, Wi-Fi, Tailscale, версия ПО.

Установка

dotnet add package NanoKVMSharp

Быстрый старт

using NanoKVMSharp;

var client = new NanoKVMClient("http://192.168.1.50");

// 1. Авторизация. Токен сохраняется в client.AuthToken и cookie nano-kvm-token.
await client.LoginAsync("admin", "admin");

// 2. URL MJPEG-потока — можно отдать в панель как <img src="...">.
string streamUrl = client.GetScreenStreamUrl();

// 3. Один снимок экрана вместе с разрешением.
ScreenSnapshot snapshot = await client.GetScreenSnapshotInfoAsync();
Console.WriteLine($"{snapshot.Width}x{snapshot.Height}, {snapshot.Jpeg.Length} байт");

Передача потока экрана в панель

Для непрерывного проксирования потока (например, в ASP.NET-контроллер) используйте StreamScreenAsync:

await foreach (var jpegFrame in client.StreamScreenAsync(httpContext.RequestAborted))
{
    await WriteJpegAsync(jpegFrame, httpContext.RequestAborted);
}

Альтернативно можно отдать браузеру MJPEG напрямую по client.GetScreenStreamUrl() (авторизация выполняется cookie nano-kvm-token).

Удалённое управление мышью и клавиатурой

await using var hid = await client.CreateHidSessionAsync();

// Абсолютная мышь: нормализованные координаты 0.0..1.0 относительно изображения экрана.
await hid.MouseMoveAbsoluteAsync(0.5, 0.5);
await hid.MouseClickAsync(HidMouseButton.Left);
await hid.MouseWheelAsync(-1);                       // прокрутка вверх

// Относительная мышь: смещения в диапазоне -127..127.
await hid.MouseMoveRelativeAsync(10, -10);

// Клавиатура: модификаторы, удержание и одиночные нажатия.
await hid.PressKeyAsync(HidKeycode.KeyC, HidModifier.LeftCtrl); // Ctrl+C
await hid.ModifierDownAsync(HidModifier.LeftAlt);
await hid.PressKeyAsync(HidKeycode.Tab);                        // Alt+Tab
await hid.ModifierUpAsync(HidModifier.LeftAlt);

// Ввод ASCII-текста (US-раскладка). Для не-ASCII используйте PasteTextAsync.
await hid.TypeTextAsync("Hello, world!\n");

// Состояние LED удалённой клавиатуры приходит по WebSocket.
hid.KeyboardLedStatusReceived += (_, status) =>
    Console.WriteLine($"CapsLock={status.CapsLock}, NumLock={status.NumLock}");

При потере фокуса вкладкой вызывайте hid.ReleaseAllAsync() — это отпустит все клавиши и кнопки.

Вставка текста и раскладки

await client.PasteTextAsync("Привет, мир!", language: "ru"); // поле langue в API
await client.PasteTextAsync("äöüß", language: "de");

Низкоуровневый доступ к HID-протоколу

// Готовые сообщения формата NanoKVM (тип + HID-отчёт).
byte[] heartbeat = HidReports.BuildHeartbeat();
byte[] keyReport = HidReports.BuildKeyboardMessage(HidModifier.LeftShift, [HidKeycode.KeyA]);
byte[] mouseAbs  = HidReports.BuildMouseAbsoluteMessage(HidMouseButton.Left, 0.25, 0.75);
byte[] mouseRel  = HidReports.BuildMouseRelativeMessage(HidMouseButton.None, 5, -5);

// Собственный транспорт (например, уже существующее WebSocket-соединение).
await using var session = NanoKVMClient.CreateHidSession(myTransport);

HID API и состояние

await client.ResetHidAsync();
HidMode mode = (await client.GetHidModeAsync()).Mode;
var leds = await client.GetKeyboardLedStatusAsync();
await client.StopFrameDetectAsync(10);

Формат WebSocket-протокола

Каждое бинарное сообщение начинается с байта типа:

От устройства по WebSocket приходят текстовые JSON-события (hid-led-status, capture-status), которые транслируются в события KeyboardLedStatusReceived / CaptureStatusReceived.

Сборка и тесты

dotnet build NanoKVMSharp.sln
dotnet test  NanoKVMSharp.sln

Проект нацелен на net9.0. Если runtime .NET 9 не установлен, тесты можно запустить на более новом runtime: DOTNET_ROLL_FORWARD=Major dotnet test.