PTP: ship hardware-timestamped timing engine in v0.1.1 production firmware

.github/scripts/p0_ribbon_phase1.py

@@ -0,0 +1,137 @@
+from pathlib import Path
+import re
+
+ROOT = Path('.')
+
+
+def replace_once(text: str, old: str, new: str, label: str) -> str:
+    if old not in text:
+        raise SystemExit(f'{label}: expected source block not found')
+    return text.replace(old, new, 1)
+
+# Register QML components.
+cmake_path = ROOT / 'apps/arstack_studio/CMakeLists.txt'
+cmake = cmake_path.read_text(encoding='utf-8')
+needle = '        qml/WorkflowBar.qml\n        qml/CalmButton.qml\n'
+replacement = ('        qml/WorkflowBar.qml\n'
+               '        qml/ModernRibbon.qml\n'
+               '        qml/RibbonGroup.qml\n'
+               '        qml/RibbonAction.qml\n'
+               '        qml/CalmButton.qml\n')
+cmake = replace_once(cmake, needle, replacement, 'CMake ribbon registration')
+cmake_path.write_text(cmake, encoding='utf-8')
+
+# Theme: define every surface token used by QML. This fixes the white PTP card.
+theme_path = ROOT / 'apps/arstack_studio/qml/StudioTheme.qml'
+theme = theme_path.read_text(encoding='utf-8')
+theme = replace_once(theme,
+    '    readonly property color surface2: "#0e141b"\n    readonly property color raised: "#151d27"\n',
+    '    readonly property color surface2: "#0e141b"\n    readonly property color panelAlt: "#101820"\n    readonly property color raised: "#151d27"\n',
+    'StudioTheme panelAlt')
+theme_path.write_text(theme, encoding='utf-8')
+
+# WorkflowBar keeps the existing session/dialog implementation, but presentation becomes ribbon-native.
+workflow_path = ROOT / 'apps/arstack_studio/qml/WorkflowBar.qml'
+workflow = workflow_path.read_text(encoding='utf-8')
+anchor = '''    function resetDockLayout() {
+        controller.phasorDetached = false
+        controller.waveformDetached = false
+        controller.phasorDockVisible = true
+        controller.waveformDockVisible = false
+        controller.telemetryDockVisible = true
+        controller.telemetryExpanded = false
+        controller.showMessage("Dock layout reset.", false)
+    }
+'''
+helpers = anchor + '''
+    function openUpdatePrompt() {
+        updatePromptDeferred = false
+        updateDialog.open()
+    }
+
+    function openInstallPrompt() {
+        installPromptDeferred = false
+        installDialog.open()
+    }
+
+    function retryProfileSync() {
+        if (smartSession.retryProfileSync())
+            controller.showMessage("Retrying 4I+4V profile synchronization.", false)
+        else
+            controller.showMessage(smartSession.statusText, true)
+    }
+'''
+workflow = replace_once(workflow, anchor, helpers, 'WorkflowBar ribbon helpers')
+pattern = re.compile(r'\n    implicitHeight: 72\n    color: theme\.surface2\n    border\.color: theme\.line\n.*\n\}', re.S)
+modern = '''
+    implicitHeight: ribbon.compact ? 70 : 96
+    color: "transparent"
+    border.width: 0
+
+    ModernRibbon {
+        anchors.fill: parent
+        theme: ribbon.theme
+        controller: ribbon.controller
+        workflow: ribbon
+        session: smartSession
+        device: ribbon.device
+        uiFont: ribbon.uiFont
+        compact: ribbon.compact
+    }
+}'''
+workflow, count = pattern.subn(modern, workflow, count=1)
+if count != 1:
+    raise SystemExit(f'WorkflowBar presentation replacement count={count}')
+workflow_path.write_text(workflow, encoding='utf-8')
+
+# Main shell: denser desktop instrument proportions, transient-only toast, and 0 Hz = DC.
+main_path = ROOT / 'apps/arstack_studio/qml/Main.qml'
+main = main_path.read_text(encoding='utf-8')
+main = replace_once(main,
+    '    width: 1480\n    height: 900\n    minimumWidth: 1080\n    minimumHeight: 720\n',
+    '    width: 1240\n    height: 760\n    minimumWidth: 960\n    minimumHeight: 620\n',
+    'Main default geometry')
+main = replace_once(main,
+    '    readonly property bool compactLayout: width < 1300\n',
+    '    readonly property bool compactLayout: width < 1120\n',
+    'Main compact breakpoint')
+main = replace_once(main,
+    '    readonly property string toastMessage: transientMessage.length ? transientMessage : device.lastError\n    readonly property bool toastError: transientMessage.length ? transientError : device.lastError.length > 0\n',
+    '    readonly property string toastMessage: transientMessage\n    readonly property bool toastError: transientError\n',
+    'Main transient toast policy')
+main = replace_once(main,
+    '            Layout.preferredHeight: 72\n            Layout.minimumHeight: 72\n',
+    '            Layout.preferredHeight: workflowBar.implicitHeight\n            Layout.minimumHeight: workflowBar.implicitHeight\n',
+    'Main ribbon height')
+main = replace_once(main,
+    '                                CalmButton { theme: studioTheme; uiFont: root.uiFont; text: "AC"; tone: root.signalFrequency > 0 ? "accent" : "normal"; implicitWidth: 46; onClicked: root.setWaveformMode("AC") }\n                                CalmButton { theme: studioTheme; uiFont: root.uiFont; text: "DC"; tone: root.signalFrequency === 0 ? "accent" : "normal"; implicitWidth: 46; onClicked: root.setWaveformMode("DC") }\n                                Rectangle { width: 1; height: 24; color: studioTheme.lineSoft }\n\n',
+    '',
+    'Remove AC/DC mode buttons')
+main = replace_once(main,
+    '                                            enabled: root.signalFrequency > 0\n                                            validator: DoubleValidator { bottom: 0.001; top: 1000.0; decimals: 3 }\n',
+    '                                            enabled: true\n                                            validator: DoubleValidator { bottom: 0.0; top: 1000.0; decimals: 3 }\n',
+    'Frequency accepts DC zero')
+main = main.replace('root.showMessage("AC frequency must be greater than 0 and not exceed 1000 Hz.", true)',
+                    'root.showMessage("Frequency must be within 0..1000 Hz (0 = DC).", true)')
+main = main.replace('CalmButton { visible: root.signalFrequency > 0; theme: studioTheme; uiFont: root.uiFont; text: "50";',
+                    'CalmButton { theme: studioTheme; uiFont: root.uiFont; text: "50";', 1)
+main = main.replace('CalmButton { visible: root.signalFrequency > 0; theme: studioTheme; uiFont: root.uiFont; text: "60";',
+                    'CalmButton { theme: studioTheme; uiFont: root.uiFont; text: "60";', 1)
+quick_50 = '                                CalmButton { theme: studioTheme; uiFont: root.uiFont; text: "50"; implicitWidth: 44; onClicked: root.setFrequencyValue(50) }\n'
+if quick_50 not in main:
+    raise SystemExit('Quick frequency 50 button not found')
+main = main.replace(quick_50,
+    '                                CalmButton { theme: studioTheme; uiFont: root.uiFont; text: "0"; implicitWidth: 44; toolTipText: "DC"; onClicked: root.setFrequencyValue(0) }\n' + quick_50,
+    1)
+main_path.write_text(main, encoding='utf-8')
+
+# Matrix density: desktop instrument rows, not dashboard cards.
+matrix_path = ROOT / 'apps/arstack_studio/qml/SignalMatrix.qml'
+matrix = matrix_path.read_text(encoding='utf-8')
+matrix = replace_once(matrix,
+    '                Layout.preferredHeight: matrix.compact ? 54 : 60\n',
+    '                Layout.preferredHeight: matrix.compact ? 46 : 50\n',
+    'SignalMatrix row density')
+matrix_path.write_text(matrix, encoding='utf-8')
+
+print('Phase 1 ribbon + compact UX patch applied successfully')

.github/workflows/arstack-studio-qt.yml

@@ -209,18 +209,20 @@ jobs:
           root=/tmp/arstack-firmware-contract
           rm -rf "$root"
           mkdir -p "$root/firmware" "$root/tools"
-          printf 'ARStack-P0-firmware-contract\n' > "$root/firmware/arstack-esp32p4-smv-0.1.0.bin"
-          sha="$(sha256sum "$root/firmware/arstack-esp32p4-smv-0.1.0.bin" | awk '{print $1}')"
+          printf 'ARStack-P0-firmware-contract\n' > "$root/firmware/arstack-esp32p4-smv-0.1.1.bin"
+          sha="$(sha256sum "$root/firmware/arstack-esp32p4-smv-0.1.1.bin" | awk '{print $1}')"
           cat > "$root/firmware/firmware-manifest.json" <<EOF
           {
             "schema": "arstack.studio.firmware.v1",
             "product": "ARStack ESP32-P4 SMV Injector",
             "chip": "esp32p4",
             "chipRevisionPolicy": "pre-v3",
-            "version": "0.1.0",
+            "version": "0.1.1",
+            "sourceCommit": "0123456789abcdef0123456789abcdef01234567",
             "protocol": 1,
+            "capabilities": ["SMV-4I4V", "PROFILE", "LIVE-SETPOINTS", "SESSION-LEASE", "PTP-P2", "SMPSYNCH-AUTO"],
             "flashOffset": 0,
-            "image": "arstack-esp32p4-smv-0.1.0.bin",
+            "image": "arstack-esp32p4-smv-0.1.1.bin",
             "sha256": "$sha"
           }
           EOF
@@ -311,4 +313,4 @@ jobs:
             /tmp/arstack-studio-launch.log
             /tmp/arstack-studio-hidpi.log
           if-no-files-found: ignore
-          retention-days: 7
+          retention-days: 7

.github/workflows/arstack-studio-release.yml

@@ -22,7 +22,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  ARSTACK_VERSION: '0.1.0'
+  ARSTACK_VERSION: '0.1.1'
   QT_VERSION: '6.10.3'
   ESPFLASH_VERSION: '4.5.0'
   ESPFLASH_WINDOWS_ZIP_SHA256: '854c82c947c20e7f337f120f0398042ed1760f2269cb0f9be3d2beae3b66fbfb'
@@ -324,4 +324,4 @@ jobs:
           files: |
             release/ARStack-Studio-${{ env.ARSTACK_VERSION }}-win-x64-portable.zip
             release/ARStack-Studio-${{ env.ARSTACK_VERSION }}-win-x64-setup.exe
-            release/SHA256SUMS.txt
+            release/SHA256SUMS.txt

.github/workflows/arstack-studio-windows-lifecycle.yml

@@ -0,0 +1,84 @@
+name: ARStack Studio Windows Lifecycle
+
+on:
+  push:
+    paths:
+      - 'apps/arstack_studio/**'
+      - '.github/workflows/arstack-studio-windows-lifecycle.yml'
+  pull_request:
+    paths:
+      - 'apps/arstack_studio/**'
+      - '.github/workflows/arstack-studio-windows-lifecycle.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: arstack-studio-windows-lifecycle-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  close-exit-reopen:
+    name: Close -> process exit -> immediate reopen
+    runs-on: windows-2022
+    timeout-minutes: 12
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Qt
+        uses: jurplel/install-qt-action@v4
+        with:
+          version: '6.10.3'
+          arch: win64_msvc2022_64
+          modules: 'qtserialport'
+          cache: true
+      - name: Configure Studio
+        shell: powershell
+        run: |
+          cmake -S apps/arstack_studio -B build-arstack-studio -G "Visual Studio 17 2022" -A x64 `
+            -DARIEC61850_WARNINGS_AS_ERRORS=ON
+          if ($LASTEXITCODE -ne 0) { throw "Studio configure failed: $LASTEXITCODE" }
+      - name: Build actual Studio executable
+        shell: powershell
+        run: |
+          cmake --build build-arstack-studio --config Release --target arstack_studio --parallel
+          if ($LASTEXITCODE -ne 0) { throw "Studio build failed: $LASTEXITCODE" }
+      - name: Two-cycle normal-close lifecycle regression
+        shell: powershell
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $env:QT_QPA_PLATFORM = 'offscreen'
+          $env:QT_QUICK_BACKEND = 'software'
+          $candidate = Get-ChildItem -Path (Join-Path $PWD 'build-arstack-studio') -Recurse -File |
+            Where-Object { $_.Name -ieq 'arstack_studio.exe' -or $_.Name -ieq 'ARStackStudio.exe' } |
+            Select-Object -First 1
+          if ($null -eq $candidate) { throw 'Built ARStack Studio executable was not found.' }
+          $exe = $candidate.FullName
+          function Invoke-LifecycleCycle([int]$Cycle) {
+            $startInfo = New-Object System.Diagnostics.ProcessStartInfo
+            $startInfo.FileName = $exe
+            $startInfo.Arguments = '--check-app-lifecycle'
+            $startInfo.UseShellExecute = $false
+            $startInfo.CreateNoWindow = $true
+            $process = New-Object System.Diagnostics.Process
+            $process.StartInfo = $startInfo
+            if (-not $process.Start()) {
+              $process.Dispose()
+              throw "Cycle ${Cycle}: failed to start Studio process."
+            }
+            $pidValue = $process.Id
+            if (-not $process.WaitForExit(12000)) {
+              Stop-Process -Id $pidValue -Force -ErrorAction SilentlyContinue
+              $process.Dispose()
+              throw "Cycle ${Cycle}: Studio process did not exit within 12 seconds after normal primary-window close."
+            }
+            $exitCode = $process.ExitCode
+            $process.Dispose()
+            if ($exitCode -ne 0) { throw "Cycle ${Cycle}: Studio lifecycle coordinator exited with code $exitCode." }
+            if (Get-Process -Id $pidValue -ErrorAction SilentlyContinue) { throw "Cycle ${Cycle}: Studio PID $pidValue remained alive after native WaitForExit." }
+            Write-Host "Cycle $Cycle PASS: normal close -> clean worker retirement -> PID exit."
+          }
+          Invoke-LifecycleCycle 1
+          Start-Sleep -Milliseconds 250
+          Invoke-LifecycleCycle 2
+          Write-Host 'Windows lifecycle gate: PASS · normal close -> process exit -> lock release -> immediate reopen -> clean exit'

.github/workflows/esp32p4-ptp-lab.yml

@@ -21,6 +21,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: esp32p4-ptp-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-esp32p4-ptp:
     strategy:
@@ -33,6 +37,7 @@ jobs:
             role_value: 1
     name: build-esp32p4-ptp-${{ matrix.role_name }}
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     container:
       image: espressif/idf:v5.5.4
     defaults:
@@ -45,6 +50,54 @@ jobs:
       - name: Select ESP32-P4 target
         run: source /opt/esp/idf/export.sh && idf.py set-target esp32p4
 
+      - name: Verify PTP source readiness and ESP-IDF 5.5 TX contract
+        shell: bash
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          eth = Path('main/ethernet_port.c').read_text(encoding='utf-8')
+          app = Path('main/app_main.cpp').read_text(encoding='utf-8')
+          ptp = Path('main/ptp_lab_task.cpp').read_text(encoding='utf-8')
+          receiver = Path('main/ptp_receiver_task.cpp').read_text(encoding='utf-8')
+
+          # Never allow the old premature boot path back into Ethernet init.
+          if 'ar_ptp_lab_try_start(handle)' in eth:
+              raise SystemExit('PTP must not auto-start inside Ethernet initialization before app_main starts Ethernet')
+          if 'ESP_ERROR_CHECK(esp_eth_start(eth_handle));' not in app:
+              raise SystemExit('app_main must explicitly start Ethernet before operator-controlled PTP can run')
+
+          # ESP-IDF 5.5 esp_eth_transmit_ctrl_vargs forwards argc as the number
+          # of variadic arguments. ESP32-P4 EMAC computes buf_num = argc / 2,
+          # so one frame is two varargs: buffer pointer + buffer length.
+          tx_signature = '2U,\n        frame.data(),\n        frame.size()'
+          if tx_signature not in ptp:
+              raise SystemExit('PTP SOURCE timestamp TX must pass argc=2 for one buffer/length frame on ESP-IDF 5.5')
+          if tx_signature not in receiver:
+              raise SystemExit('PTP RECEIVER timestamp TX must pass argc=2 for one buffer/length frame on ESP-IDF 5.5')
+          if 'argc counts buffer/length pairs' in ptp or 'argc counts buffer/length pairs' in receiver:
+              raise SystemExit('stale/incorrect esp_eth_transmit_ctrl_vargs argc documentation remains')
+          if 'PTP hardware-timestamp TX failed:' not in ptp or 'without a valid hardware timestamp' not in ptp:
+              raise SystemExit('PTP SOURCE must distinguish driver TX errors from invalid timestamp evidence')
+
+          # Admission truth is the stronger bounded runtime contract: explicit
+          # operator start is accepted only after real Announce + Sync + Follow_Up TX.
+          required = [
+              'const bool started = ar_ptp_lab_try_start(s_eth_handle);',
+              'ar_esp32p4_restore_normal_emac();',
+              'g_ptp_ready',
+              'PTP source readiness timeout',
+              'g_announce_sent.load',
+              'g_sync_sent.load',
+              'g_follow_up_sent.load',
+              'return g_ptp_ready.load',
+          ]
+          combined = eth + '\n' + ptp
+          missing = [token for token in required if token not in combined]
+          if missing:
+              raise SystemExit('PTP verified-start contract missing: ' + ', '.join(missing))
+          print('PTP contract: post-Ethernet start + ESP-IDF 5.5 argc=2 timestamp TX + verified core timing + rollback')
+          PY
+
       - name: Enable guarded PTP-P2 profile
         shell: bash
         run: |