CANConfigPython 0.1.0a1__py3-none-win_amd64.whl

canconfigpython/resources/skill/canconfig-python/assets/examples/index.zh-CN.md

@@ -0,0 +1,55 @@
+# 配置修改用例（CANConfigConsole 2.3）
+
+[English](index.en.md)
+
+每个链接都是完整请求文件，含 schema_version、device_uid、changes。全零 UID 是待替换标记；从已确认目标的 info 取得实际 UID 后再填写。先复制到工作目录，按用户要求编辑，UTF-8 保存，再执行 apply --dry-run；预检成功且影响范围已授权后执行同一文件。详见[公共参数与命令参考](../../references/operations.md)。
+
+这些用例已设计为隔离假驱动验收输入；测试结果不证明真实硬件时序、总线通信或断电保存。普通局部补丁会继承整个所选配置段的其他值，write_count 因而可以大于修改字段数。下表写入数和 SAVE 范围是 index.json 指定型号/版本夹具的预期值；真实设备以本次预检结果为准。用户应评估其对整个配置段的影响，不要把局部字段补丁理解成仅写该字段。
+
+类型：13=CANBridge/B_CC_A，24=CANCOM，26=CANFB-2F2C，30=CANRPT-600，35=CANHub-X6H，36=CANHub-X6L。其他通道数或版本必须重新检查能力，不能直接照搬数组、通道或写入数。
+
+## 正例（22）
+
+| 文件 / 目的 | 前提 | 预期配置写入数 / SAVE 域 |
+| --- | --- | --- |
+| [CANFB CAN1 固定 500 kbit/s](fb_500k.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 2 / SAVE/1/1 |
+| [CANFB CAN1 固定 1 Mbit/s](fb_1m.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 2 / SAVE/1/1 |
+| [CANBridge 两路不同波特率](bridge_dual_rates.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 2 / SAVE/1/0 |
+| [CANRPT-600 CAN3 静默模式](rpt_silent.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 6 / SAVE/1/0 |
+| [CANHub-X6H 外部 CAN3 500 kbit/s](hub_h_external.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 6 / SAVE/1/1 |
+| [CANHub-X6L 外部 CAN3 500 kbit/s](hub_l_external.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 6 / SAVE/1/1 |
+| [CANFB CAN1 开启自适应](fb_adaptive_single.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 1 / SAVE/1/1 |
+| [CANRPT-600 全部六路开启自适应](rpt_adaptive_all.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 6 / SAVE/1/0 |
+| [CANFB 从自适应切回两路明确手动参数](fb_return_manual.json) | 允许当前为自适应；明确授权覆盖全部两路参数，使用用户指定的新手动值；无 DIP 接管。 | 2 / SAVE/1/1 |
+| [CANBridge CAN1 掩码过滤 ID 0x123](filter_mask.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 32 / SAVE/1/0 |
+| [CANBridge CAN1 范围过滤 0x100–0x1FF](filter_range.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 32 / SAVE/1/0 |
+| [CANBridge 切换黑名单](filter_blacklist.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 1 / SAVE/1/0 |
+| [CANHub 两路输入过滤并启用](hub_input_filter.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 257 / SAVE/1/2, SAVE/1/5 |
+| [CANBridge 标准 ID 0x123 映射为 0x321](bridge_mapping.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 128 / SAVE/5 |
+| [CANHub 映射并转发到 CAN2](hub_mapping.json) | Hub 固件 01.16 及以上（mapping_format=3）；所有通道当前为手动、参数可完整读取。 | 257 / SAVE/1/3, SAVE/1/5 |
+| [CANHub CAN1 路由到 CAN2 与 CAN3](hub_routing.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 2 / SAVE/1/4, SAVE/1/5 |
+| [CANFB 静默自适应选项](fb_silent_adaptive_option.json) | CANFB 固件 05.09/05.10 支持该位；该选项不等于 BRT_AUTO 开启命令。 | 1 / SAVE/1/5 |
+| [CANCOM 串口 115200 8N1](cancom_115200_8n1.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 1 / SAVE/4 |
+| [CANCOM 双向透明转换与标准 ID](cancom_transparent_id.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 1 / SAVE/4 |
+| [CANCOM 格式转换并启用 CRC](cancom_format_crc.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 1 / SAVE/4 |
+| [CANCOM 字符流与消息间隔](cancom_gap.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 1 / SAVE/4 |
+| [写入 USER_DATA 第一块 32 字节](user_data.json) | 所有通道当前为手动、参数可完整读取；无 DIP 开关接管。 | 2 / 无独立 SAVE |
+
+所有正例预检预期 exit_code=0，effects 的写入计数为 0；模拟执行预期 exit_code=0。普通配置 verification.readback=matched；开启自适应仅为 adaptive_flags_matched，adaptive_result=not_verified。所有用例 power_cycle=not_verified。USER_DATA 无独立 SAVE，不能根据 save_acknowledged=0 判失败。
+
+## 负例（8，仅测试）
+
+| 文件 / 错误 | 标准 Schema | CLI 预期退出码 / 错误码 |
+| --- | --- | --- |
+| [目标 UID 不匹配](negative/wrong_uid.json) | 通过，设备预检拒绝 | 6 / uid_mismatch |
+| [把数值 ID 写成字符串](negative/string_numeric_id.json) | 拒绝 | 7 / invalid_patch_value |
+| [不存在的参数名](negative/unknown_field.json) | 拒绝 | 7 / invalid_patch_field |
+| [自适应开启与其他修改混合](negative/adaptive_mixed.json) | 拒绝 | 7 / adaptive_enable_only |
+| [从自适应读回继承参数](negative/restricted_inheritance.json) | 通过，设备预检拒绝 | 7 / readonly_parameters |
+| [CANCOM 不支持开启自适应](negative/unsupported_adaptive.json) | 通过，设备预检拒绝 | 5 / adaptive_not_supported |
+| [Hub 的 BRT 缺少 PS](negative/hub_missing_ps.json) | 通过，设备预检拒绝 | 7 / invalid_configuration |
+| [USER_DATA 不足 32 字节](negative/short_user_data.json) | 拒绝 | 7 / invalid_patch_value |
+
+负例 CLI 验收绕过外部 Schema 直接调用解析器，预期 dry-run 与执行均无配置 SET/WRITE/SAVE；部分错误在连接前发生，无驱动 trace。一般 Schema 允许型号并集，例如 BRT 的 4/5 项，但 Hub 必须有第 5 项 PS，由设备预检判定。wrong_uid 保持全零 UID；其他负例在夹具中替换 UID 以抵达待测错误分支。
+
+[index.json](index.json) 是用例与预期结果的机器索引，也是进程测试的输入。不要把索引、Schema、命令结果 envelope 当作 changes 请求文件。

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/adaptive_mixed.json

@@ -0,0 +1,8 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/BRT_AUTO": 1,
+    "CAN1_PARAMETER/MODE": 0
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/hub_missing_ps.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN3_PARAMETER/BRT": [
+      500000,
+      1,
+      5,
+      3
+    ]
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/restricted_inheritance.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/BRT": [
+      500000,
+      2,
+      15,
+      3
+    ]
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/short_user_data.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "USER_DATA/DATA1": "00"
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/string_numeric_id.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CANCOM/CAN_ID": "0x123"
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/unknown_field.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/BAUD_RATE": 500000
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/unsupported_adaptive.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/BRT_AUTO": 1
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/negative/wrong_uid.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/MODE": 0
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/rpt_adaptive_all.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/BRT_AUTO": 1,
+    "CAN2_PARAMETER/BRT_AUTO": 1,
+    "CAN3_PARAMETER/BRT_AUTO": 1,
+    "CAN4_PARAMETER/BRT_AUTO": 1,
+    "CAN5_PARAMETER/BRT_AUTO": 1,
+    "CAN6_PARAMETER/BRT_AUTO": 1
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/rpt_silent.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN3_PARAMETER/MODE": 2
+  }
+}

canconfigpython/resources/skill/canconfig-python/assets/examples/user_data.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "USER_DATA/DATA1": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
+  }
+}

canconfigpython/resources/skill/canconfig-python/references/operations.md

@@ -0,0 +1,68 @@
+# Operation reference
+
+Use `canconfig COMMAND --help` for current syntax.
+Windows: COM3. Linux: /dev/ttyACM0 or a confirmed /dev/serial/by-id/... alias.
+Never auto-select the first device. Linux paths are case-sensitive. The wrapper
+resolves an alias for the current operation. Ensure serial permissions; do not
+default to sudo.
+
+## Command map
+
+| Task | Invocation after canconfig | Device I/O |
+|---|---|---|
+| Check install | doctor --json | None |
+| Contract | schema --json | None |
+| Identity | info --port PORT --expect-uid UID --json | Live |
+| Validate backup | validate --file backup.ini --json | None |
+| Backup | export --port PORT --file backup.ini --password-env CAN_PASSWORD --expect-uid UID --json | Live |
+| Restore original | restore --port PORT --file backup.ini --password-env CAN_PASSWORD --expect-uid UID --check-device --dry-run --json | Live, no SET/WRITE/SAVE |
+| Apply patch | apply --port PORT --file changes.json --password-env CAN_PASSWORD --expect-uid UID --dry-run --json | Live, no SET/WRITE/SAVE |
+| Password | change-password --port PORT --expect-uid UID --password-env CAN_PASSWORD --new-password-env CAN_NEW_PASSWORD --dry-run --json | Live old-password auth |
+| Firmware preflight | firmware-update --port PORT --file image.sfb --dry-run --json | None |
+
+PORT/UID/HASH are placeholders. Execute writes by removing only --dry-run after
+preparation and authorization. Preserve target, files, sections and identity checks.
+Config writes never retry. Firmware retries numbered packets, not whole sessions.
+
+--sections applies to validate/export/restore: all or a comma-separated list of
+parameters, filters, filter_mode, mapping, options, routing, cancom, user_data.
+Partial backup requires matching explicit sections on restore. Unsupported explicit
+sections are errors. A successful export replaces an existing destination.
+
+## Credentials
+
+Passwords are 1–10 UTF-8 bytes without NUL; a character can occupy multiple bytes.
+Use PowerShell Read-Host -AsSecureString or Bash read -s, then a temporary environment
+variable. Clean up in finally/trap. Values are forwarded only in the child environment.
+Environment variables are not a secret vault; administrators may inspect them.
+The Python CLI has no plaintext --password or native legacy aliases.
+
+Change-password requires different old/new variable names. It is not a JSON/INI
+configuration field. Success: verification.new_password == "authenticated".
+Readback is not applicable; power-cycle persistence is unverified.
+
+## Firmware
+
+Use final .sfb (SFU1/SFU2/SFU3 header, payload, <=64 MiB), not encrypted .sfu.
+Transport is 115200 8N1; DTR enabled unless --no-dtr selected.
+After offline preflight, pin data.sha256 with --expect-sha256 HASH.
+Use --expect-usb-serial SERIAL if known. The bootloader has no configuration
+UID/password authentication. Device must already be in update mode.
+
+Success: verification.transfer == "completed" and device_return == "observed".
+Installed image/version/signature/compatibility remain not_verified.
+Do not automatically restart a failed session.
+
+## Results
+
+Every operation emits a UTF-8 result envelope. --json emits one compact line.
+Schema version is 1. Missing valid final output after hardware execution means
+effects.status unknown and counts null. Preserve uncertainty.
+
+Exits: 0 success; 1 connection/runtime/lock; 2 credentials; 3 file;
+4 communication/protocol; 5 unsupported; 6 identity; 7 configuration/patch;
+8 unknown hardware result; 9 usage; 10 verification mismatch;
+11 timeout; 12 cancellation. Native timeout/cancel results may also carry unknown
+effects; an exit alone never proves zero writes.
+
+Export the full guide: `canconfig docs export --output ./canconfig-docs`.

canconfigpython/resources.py

@@ -0,0 +1,17 @@
+from pathlib import Path
+import shutil
+from .errors import ConfigError
+
+ROOT = Path(__file__).resolve().parent / "resources"
+
+
+def export(kind, output):
+    source = ROOT / ("docs" if kind == "docs" else "skill/canconfig-python")
+    target = Path(output).absolute()
+    if target.exists():
+        raise ConfigError("output_exists", "Choose a new output directory; export never merges or overwrites files.", 3)
+    try:
+        shutil.copytree(str(source), str(target))
+    except OSError:
+        raise ConfigError("export_failed", "Resource export failed; remove incomplete output or choose a new directory.", 3)
+    return {"directory": str(target), "files": len(list(target.rglob("*")))}

canconfigpython/runtime/manifest.json

@@ -0,0 +1,19 @@
+{
+  "format": 1,
+  "platform": "windows",
+  "architecture": "x86",
+  "wheel_platform": "win32",
+  "backend_version": "2.3",
+  "bridge_api": 1,
+  "executable": "canconfigconsole.exe",
+  "sha256": {
+    "Qt5Core.dll": "0a4da23fbfdab54c975bff15717137acd8738c19dc8a4a9aa3f5c7b9a7d94585",
+    "Qt5Network.dll": "02a0b66118b459113e4c060d3a49210ca6e53a6bc7f9ad8561b22f71bbbff0c3",
+    "Qt5SerialPort.dll": "7158896af1688d100fc4a231712b92ac03248acd65c030ec9617b8f3fd79e6b8",
+    "WIICAN.dll": "1e8a69aa368db34cf701bbfca0b616459430f4e17606279c7b9477841dd83268",
+    "canconfigconsole.exe": "504f0df4da6a46d5c679f67698678e9b32f0ab3ef2ab9e6df7d250790fe91a07",
+    "libgcc_s_dw2-1.dll": "4d2e2d408d399d066b0aaef2047f7a33515c13c589832de0d9f1ba87a530c394",
+    "libstdc++-6.dll": "79622396dc4c7afbbceca03e69f727bf1862735ee3ad671aa3ee7ada8aa446c3",
+    "libwinpthread-1.dll": "b5fe4d6408ef2baabdd168f4c7250900606468e9aeb24c71e0c833d3d715ae65"
+  }
+}

canconfigpython/runtime.py

@@ -0,0 +1,61 @@
+import hashlib
+import json
+import os
+from pathlib import Path
+import platform
+import sys
+from .errors import ConfigError
+
+ROOT = Path(__file__).resolve().parent / "runtime"
+BACKEND_VERSION = "2.3"
+BRIDGE_API = 1
+
+
+def inspect_runtime(root=None):
+    root = Path(root or ROOT).resolve()
+    try:
+        manifest = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
+        expected = "windows" if sys.platform == "win32" else "linux" if sys.platform.startswith("linux") else None
+        if expected is None or manifest["platform"] != expected:
+            raise ConfigError("unsupported_platform", "Install a wheel for this operating system.", 5)
+        if expected == "linux" and platform.machine().lower() not in ("x86_64", "amd64"):
+            raise ConfigError("unsupported_architecture", "This Linux runtime requires x86_64.", 5)
+        if manifest["backend_version"] != BACKEND_VERSION or manifest["bridge_api"] != BRIDGE_API:
+            raise ValueError("contract")
+        files = manifest["sha256"]
+        exe = manifest["executable"]
+        if not isinstance(files, dict) or exe not in files:
+            raise ValueError("files")
+        for name, expected_hash in files.items():
+            relative = Path(name)
+            if relative.is_absolute() or ".." in relative.parts or "\\" in name:
+                raise ValueError("path")
+            target = (root / relative).resolve()
+            if root not in target.parents or hashlib.sha256(target.read_bytes()).hexdigest() != expected_hash:
+                raise ValueError("digest")
+        executable = root / exe
+        if expected == "linux" and not os.access(str(executable), os.X_OK):
+            raise ConfigError("runtime_not_executable", "Backend is not executable; reinstall the platform wheel.", 1)
+        return executable, manifest
+    except ConfigError:
+        raise
+    except (OSError, ValueError, KeyError, TypeError):
+        raise ConfigError("runtime_invalid", "Bundled runtime is missing or inconsistent. Reinstall the wheel, or build/stage the runtime from source.", 1)
+
+
+def child_environment(runtime, secrets=()):
+    env = dict(os.environ)
+    # A shell/Qt setup must not redirect resolution to a different Qt installation.
+    for key in list(env):
+        if key.startswith("QT_") or key.startswith("QML") or key in ("LD_PRELOAD", "LD_AUDIT", "LD_LIBRARY_PATH"):
+            env.pop(key, None)
+    if sys.platform == "win32":
+        system = env.get("SystemRoot", r"C:\Windows")
+        env["PATH"] = os.pathsep.join((str(runtime), str(Path(system) / "System32"), system))
+        env["NoDefaultCurrentDirectoryInExePath"] = "1"
+    else:
+        # Libraries live next to the executable; never change the caller's environment.
+        env["LD_LIBRARY_PATH"] = str(runtime)
+    for name, value in secrets:
+        env[name] = value
+    return env