mgth/LittleBigMouse · error · ArgumentException

A Wi-Fi MAC address is required for VIDAA authentication.

Error message

A Wi-Fi MAC address is required for VIDAA authentication.

What it means

VIDAA credential generation (GenerateCredentials) builds the client identity from the device's Wi-Fi MAC address. If the macAddress argument normalizes to null/whitespace, ArgumentException is thrown, because auth (dynamic pattern hash, clientId, username) cannot be derived without it.

Solutions

1. Supply the device's Wi-Fi MAC address (colon/space separated forms accepted after NormalizeMac)
2. Re-fetch the descriptor and confirm mac/macWifi/macEthernet fields are populated; use macWifi preference
3. Store the MAC at discovery time so it is available for authentication later
4. Fetch the MAC from the TV's network settings or router DHCP table if the descriptor lacks it

Example fix

// before
var creds = HisenseVidaaProtocol.GenerateCredentials(device.Mac ?? "", method);
// after
if (string.IsNullOrWhiteSpace(device.Mac))
    throw new InvalidOperationException("Descriptor had no MAC; re-discover the device.");
var creds = HisenseVidaaProtocol.GenerateCredentials(device.Mac, method);

if (string.IsNullOrWhiteSpace(device.Mac))
    throw new InvalidOperationException("Descriptor has no MAC; re-discover device.");

bool HasMac(HisenseVidaaDevice d) => !string.IsNullOrWhiteSpace(d.Mac);

try { creds = GenerateCredentials(mac, method); }
catch (ArgumentException ex) { /* prompt re-discovery to fetch MAC */ }

When it happens

Trigger: Calling GenerateCredentials with an empty/whitespace MAC, or passing a descriptor-derived MAC that was absent (descriptor didn't expose mac/macWifi/macEthernet and the caller passed an empty string).

Common situations: Projector descriptor XML omits MAC fields so the caller stored an empty MAC; reading the Ethernet MAC when the auth expects the Wi-Fi MAC; manual config entry left blank.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Enter a valid projector IPv4 address.
• Invalid VIDAA remote key.
• Enter a VIDAA picture-setting menu ID between 1 and 999.
• Enter a VIDAA picture-setting value between -1000 and 1000.
• Enter a volume between 0 and 100.

AI-assisted analysis of mgth/LittleBigMouse@7a42f01d47 (2026-09-16). Data as JSON: /api/errors/77d42d1f153b3a4d. Report an issue: GitHub.

Appendix: source

Thrown at LittleBigMouse.Plugins/LittleBigMouse.Plugin.Vcp.Avalonia/HisenseVidaa/HisenseVidaaProtocol.cs:64

        null => VidaaAuthMethod.Modern,
        _ => VidaaAuthMethod.Legacy,
    };

    public static bool UsesStaticLegacyProtocol(int? protocolVersion)
        => protocolVersion is > 0 and < 3000;

    public static string LegacyDeviceTopic(string controllerMac)
        => $"{NormalizeMac(controllerMac).ToUpperInvariant()}$normal";

    public static VidaaMqttCredentials GenerateCredentials(
        string macAddress,
        VidaaAuthMethod authMethod,
        long? unixTimeSeconds = null,
        string brand = "his")
    {
        var uuid = NormalizeMac(macAddress, preserveCase: true);
        if (string.IsNullOrWhiteSpace(uuid))
            throw new ArgumentException("A Wi-Fi MAC address is required for VIDAA authentication.", nameof(macAddress));

        var timestamp = unixTimeSeconds ?? DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        var raceHash = Md5($"{DynamicPattern}${uuid}")[..6];
        var clientId = $"{uuid}${brand}${raceHash}_vidaacommon_001";
        var usernameTime = authMethod == VidaaAuthMethod.Legacy
            ? unchecked((ulong)timestamp)
            : unchecked((ulong)timestamp) ^ TimeXorConstant;
        var username = $"{brand}${usernameTime}";
        var remainder = timestamp.ToString(CultureInfo.InvariantCulture)
            .Where(char.IsAsciiDigit)
            .Sum(c => c - '0') % 10;
        var suffix = authMethod == VidaaAuthMethod.Modern ? ModernSuffix : LegacySuffix;
        var valueHash = Md5($"{brand}{remainder}{suffix}")[..6];
        var password = Md5($"{timestamp}${valueHash}");
        return new VidaaMqttCredentials(clientId, username, password);
    }

    public static HisenseVidaaDevice ParseDescriptor(string ipAddress, string xml)

View on GitHub (pinned to 7a42f01d47)