初始化奇妙小屏幕控制器项目

2026-09-08 22:56:52 +08:00
commit 8d368de3b5
491 changed files with 67678 additions and 0 deletions
@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import re
+import struct
+from typing import Any
+
+
+PRODUCT_ID = "matrix-screen-controller-walnutpi"
+CONFIG_FILE_BYTES = 64 * 1024
+HEADER_BYTES = 4096
+SLOT_BYTES = (CONFIG_FILE_BYTES - HEADER_BYTES) // 2
+FILE_MAGIC = b"MSCCFG2\0"
+SLOT_MAGIC = b"MSCSLOT\0"
+FORMAT_VERSION = 1
+_HEADER = struct.Struct("<8sII")
+_SLOT_HEADER = struct.Struct("<8sQI32s")
+_USERNAME = re.compile(r"[a-z_][a-z0-9_-]{0,31}", re.ASCII)
+_VERSION = re.compile(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)", re.ASCII)
+
+
+class ImageConfigError(ValueError):
+    pass
+
+
+def _exact_object(value: Any, fields: set[str], label: str) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) != fields:
+        raise ImageConfigError(f"{label}字段无效")
+    return value
+
+
+def _utf16_units(value: str) -> int:
+    # .NET String.Length counts UTF-16 code units; retain 1.0.1 validation semantics.
+    return len(value.encode("utf-16-le")) // 2
+
+
+def _validate_secret(value: Any, label: str, minimum: int, maximum: int) -> str:
+    if not isinstance(value, str) or not minimum <= _utf16_units(value) <= maximum:
+        raise ImageConfigError(f"{label}长度或字符无效")
+    if any(character in value for character in ("\0", "\r", "\n")):
+        raise ImageConfigError(f"{label}长度或字符无效")
+    return value
+
+
+def _validate_text(value: Any, label: str, minimum: int, maximum_bytes: int) -> str:
+    if not isinstance(value, str) or _utf16_units(value) < minimum or len(value.encode("utf-8")) > maximum_bytes:
+        raise ImageConfigError(f"{label}长度或字符无效")
+    if any(character in value for character in ("\0", "\r", "\n")):
+        raise ImageConfigError(f"{label}长度或字符无效")
+    return value
+
+
+def validate_config(value: Any) -> dict[str, Any]:
+    source = _exact_object(
+        value,
+        {"schema_version", "product", "software_version", "account", "wifi", "ipv4"},
+        "镜像配置",
+    )
+    schema = source["schema_version"]
+    if type(schema) is not int or schema != FORMAT_VERSION or source["product"] != PRODUCT_ID:
+        raise ImageConfigError("镜像产品或配置版本不受支持")
+    software_version = source["software_version"]
+    if not isinstance(software_version, str) or _VERSION.fullmatch(software_version) is None:
+        raise ImageConfigError("软件版本格式无效")
+
+    account = _exact_object(source["account"], {"username", "password"}, "账户配置")
+    username = account["username"]
+    if not isinstance(username, str) or _USERNAME.fullmatch(username) is None:
+        raise ImageConfigError("用户名只能使用小写字母、数字、下划线和连字符，且最长 32 个字符")
+    account_password = _validate_secret(account["password"], "账户密码", 8, 128)
+
+    wifi = _exact_object(source["wifi"], {"ssid", "password"}, "Wi-Fi 配置")
+    ssid = _validate_text(wifi["ssid"], "Wi-Fi 名称", 1, 32)
+    wifi_password = _validate_secret(wifi["password"], "Wi-Fi 密码", 8, 63)
+
+    ipv4 = _exact_object(source["ipv4"], {"mode", "address", "prefix", "gateway", "dns"}, "IPv4 配置")
+    mode = ipv4["mode"]
+    if mode == "dhcp":
+        normalized_ipv4: dict[str, Any] = {"mode": "dhcp", "address": "", "prefix": 0, "gateway": "", "dns": []}
+    elif mode == "static":
+        try:
+            address = ipaddress.IPv4Address(ipv4["address"])
+            gateway = ipaddress.IPv4Address(ipv4["gateway"])
+        except (ipaddress.AddressValueError, TypeError) as exception:
+            raise ImageConfigError("静态 IPv4 地址或网关无效") from exception
+        prefix = ipv4["prefix"]
+        if type(prefix) is not int or not 1 <= prefix <= 32:
+            raise ImageConfigError("IPv4 前缀必须是 1 到 32")
+        if gateway not in ipaddress.IPv4Network(f"{address}/{prefix}", strict=False):
+            raise ImageConfigError("静态 IPv4 网关必须与地址处于同一子网")
+        dns_source = ipv4["dns"]
+        if not isinstance(dns_source, list) or not 1 <= len(dns_source) <= 4:
+            raise ImageConfigError("DNS 必须包含 1 到 4 个 IPv4 地址")
+        try:
+            dns = [str(ipaddress.IPv4Address(item)) for item in dns_source]
+        except (ipaddress.AddressValueError, TypeError) as exception:
+            raise ImageConfigError("DNS 必须包含 1 到 4 个 IPv4 地址") from exception
+        normalized_ipv4 = {
+            "mode": "static",
+            "address": str(ipv4["address"]),
+            "prefix": prefix,
+            "gateway": str(ipv4["gateway"]),
+            "dns": dns,
+        }
+    else:
+        raise ImageConfigError("IPv4 模式无效")
+
+    return {
+        "schema_version": FORMAT_VERSION,
+        "product": PRODUCT_ID,
+        "software_version": software_version,
+        "account": {"username": username, "password": account_password},
+        "wifi": {"ssid": ssid, "password": wifi_password},
+        "ipv4": normalized_ipv4,
+    }
+
+
+def serialize_config(value: Any) -> str:
+    return json.dumps(validate_config(value), ensure_ascii=False, separators=(",", ":"))
+
+
+def deserialize_config(text: str) -> dict[str, Any]:
+    try:
+        value = json.loads(text)
+    except (UnicodeError, json.JSONDecodeError) as exception:
+        raise ImageConfigError("配置 JSON 无效") from exception
+    return validate_config(value)
+
+
+def _slot_offset(index: int) -> int:
+    return HEADER_BYTES + index * SLOT_BYTES
+
+
+def _encode_slot(config: Any, generation: int) -> bytes:
+    payload = (serialize_config(config) + "\n").encode("utf-8")
+    if len(payload) > SLOT_BYTES - _SLOT_HEADER.size:
+        raise ImageConfigError("配置内容过大")
+    header = _SLOT_HEADER.pack(SLOT_MAGIC, generation, len(payload), hashlib.sha256(payload).digest())
+    return header + payload + bytes(SLOT_BYTES - len(header) - len(payload))
+
+
+def create_config_file(config: Any) -> bytes:
+    result = bytearray(CONFIG_FILE_BYTES)
+    _HEADER.pack_into(result, 0, FILE_MAGIC, FORMAT_VERSION, CONFIG_FILE_BYTES)
+    result[_slot_offset(0) : _slot_offset(0) + SLOT_BYTES] = _encode_slot(config, 1)
+    return bytes(result)
+
+
+def read_config_file(data: bytes) -> tuple[dict[str, Any], int, int]:
+    if len(data) != CONFIG_FILE_BYTES:
+        raise ImageConfigError("镜像配置文件大小无效")
+    try:
+        magic, version, declared_size = _HEADER.unpack_from(data, 0)
+    except struct.error as exception:
+        raise ImageConfigError("镜像配置区头部无效") from exception
+    if magic != FILE_MAGIC or version != FORMAT_VERSION or declared_size != CONFIG_FILE_BYTES:
+        raise ImageConfigError("镜像配置区头部无效")
+
+    valid: list[tuple[int, int, dict[str, Any]]] = []
+    for index in range(2):
+        offset = _slot_offset(index)
+        slot_magic, generation, payload_bytes, digest = _SLOT_HEADER.unpack_from(data, offset)
+        if slot_magic != SLOT_MAGIC or payload_bytes <= 0 or payload_bytes > SLOT_BYTES - _SLOT_HEADER.size:
+            continue
+        payload_start = offset + _SLOT_HEADER.size
+        payload = data[payload_start : payload_start + payload_bytes]
+        if hashlib.sha256(payload).digest() != digest:
+            continue
+        try:
+            document = deserialize_config(payload.decode("utf-8"))
+        except (UnicodeError, ImageConfigError):
+            continue
+        valid.append((generation, index, document))
+    if not valid:
+        raise ImageConfigError("镜像配置区没有可恢复的有效副本")
+    generation, index, document = max(valid, key=lambda item: (item[0], item[1]))
+    return document, generation, index
+
+
+def encode_update(data: bytes, config: Any) -> tuple[bytes, int]:
+    _current, generation, active = read_config_file(data)
+    target = 1 - active
+    return _encode_slot(config, generation + 1), target
+
+
+def update_config_file(data: bytes, config: Any) -> bytes:
+    slot_data, target = encode_update(data, config)
+    result = bytearray(data)
+    offset = _slot_offset(target)
+    result[offset : offset + SLOT_BYTES] = slot_data
+    return bytes(result)
+
+
+def slot_offset(index: int) -> int:
+    if index not in (0, 1):
+        raise ValueError("配置槽索引无效")
+    return _slot_offset(index)
+