trex-core/skills/draft-batch-verification/references/opspro-visioncfg-hardware-verification.md

OpsPro VISIONCFG hardware verification reference

Use this reference when drafting or updating verification evidence for OpsPro VISIONCFG CTSP and migration work.

CTSP hardware verification patterns

1. Start with non-destructive probes.
   • DATE confirms port/CTSP responsiveness.
   • VISIONCFG read confirms payload shape before any write.
2. For VISIONCFG, always capture:
   • raw request
   • raw response
   • parsed value count
   • slot interpretation (1..26 legacy/public, 27 ratio, 28..32 reserved for current 32-value contract)
3. When write tests are allowed, use this order:
   • current 32-value round-trip
   • legacy 26-value compatibility write
   • invalid ratio reject / no partial write
   • reboot persistence
   • migration from pure legacy device/state
4. After write-based evidence capture, restore baseline values and confirm readback.

Migration verification lessons

Exclude downgrade/re-upgrade drift from pure legacy migration evidence

If a device has already booted a newer firmware that can write a current visioncfg, then later downgrade/re-upgrade behavior is not clean REQ-005 legacy migration evidence. Treat that as a separate compatibility/schema-drift investigation, not as the primary legacy-to-current migration acceptance path.

Pure legacy migration acceptance path

For REQ-005 migration evidence, use a device that has never been updated to the newer firmware revision being tested.

Required sequence:

1. Confirm legacy firmware returns 26-value VISIONCFG.
2. Write distinctive 26-value legacy test data.
3. Capture legacy readback before upgrade.
4. Upgrade to target firmware and reboot.
5. On first boot, read VISIONCFG and confirm:
   • 32 values total
   • slots 1..26 exactly match pre-upgrade legacy values
   • slot 27 is 10
   • slots 28..32 are -1/-1/-1/-1/-1
6. Reboot via CTSP REBOOT and confirm current readback is unchanged.
7. Restore baseline current values after evidence capture.

Diagnostic logging for schema issues

When investigating migration failures, instrument _load_vision_config() to log:

• sizeof(struct prop_header)
• sizeof(struct ocv_rect)
• sizeof(struct _vision_config_rev0)
• sizeof(struct _vision_config)
• header probe rc, type, revision
• current read expected size vs rc
• revision-0 read expected size vs rc

Interpretation rule:

• current revision size mismatch (...) followed by vision config default means the stored blob was interpreted as current revision but its binary size/layout did not match the current firmware's expected current schema. Do not misclassify that as successful legacy migration.

ABI / struct-layout caution

Do not infer target firmware ABI from PYDEBUG-only fallback definitions or host-side binding builds. For firmware storage compatibility analysis, trust target-firmware definitions and on-device logs first.