masarray · Oct 24, 2026 · Oct 24, 2026 · Oct 24, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -1,46 +1,54 @@
 name: Bug report
-description: Report a reproducible ARStack application, protocol or device issue
+description: Report a problem with ARStack Studio, board connection, SCL import or an engineering tool
 title: "Bug: "
+labels: []
 body:
   - type: markdown
     attributes:
-      value: "Please avoid posting private station configurations, credentials, or customer packet captures. For security vulnerabilities, use the private reporting instructions in SECURITY.md."
-  - type: dropdown
-    id: area
-    attributes:
-      label: Component
-      options:
-        - ARStack Studio (Windows or Linux)
-        - ESP32-P4 SV / PTP
-        - IED Browser / Workbench
-        - IED Simulator
-        - Build / installation
-        - Other
-    validations:
-      required: true
+      value: |
+        Thanks for testing ARStack! Short reports are welcome. Remove confidential details from screenshots and files. For security vulnerabilities, follow the private reporting process in [SECURITY.md](../../SECURITY.md) rather than creating a public issue.
   - type: textarea
-    id: repro
+    id: problem
     attributes:
-      label: How to reproduce
-      description: Steps and input settings sufficient to reproduce in a lab
-      placeholder: "1. Open Studio... 2. Connect... 3. Observe..."
+      label: What happened?
+      description: Tell us what you tried and what went wrong.
+      placeholder: "I opened a .scd file, but the selected SV stream was not shown."
     validations:
       required: true
   - type: textarea
-    id: observed
+    id: expected
     attributes:
-      label: Expected and actual behavior
-      placeholder: "Expected: ... Actual: ..."
+      label: What did you expect?
+      placeholder: "I expected to see the SV ID and multicast address."
     validations:
-      required: true
+      required: false
   - type: input
     id: version
     attributes:
-      label: Version and environment
-      description: Release tag, Windows/Linux version and ESP32-P4 firmware Build ID, if relevant
-      placeholder: "M3.H; Windows 11; firmware a922e9bdba4e57a4"
+      label: ARStack version
+      description: See Help / About or the downloaded release.
+      placeholder: "M3.H"
+    validations:
+      required: false
+  - type: dropdown
+    id: area
+    attributes:
+      label: Where did it happen?
+      options:
+        - ARStack Studio (Windows / Linux)
+        - ESP32-P4 firmware / device connection
+        - SCL or engineering file import
+        - IED Browser / Workbench
+        - IED Simulator
+        - SV / PTP traffic
+        - Build / installation
+        - Other
+    validations:
+      required: false
   - type: textarea
     id: evidence
     attributes:
-      label: Sanitized evidence (optional)
-      description: Logs, screenshots or short anonymized captures; never secrets or customer-identifying files
+      label: Screenshot, logs or sample file (optional)
+      description: You can drag a screenshot or sanitized sample here.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/interoperability.yml b/.github/ISSUE_TEMPLATE/interoperability.yml
@@ -0,0 +1,38 @@
+name: Community interoperability experiment
+description: Share what you observed in an isolated IEC 61850 Process Bus test
+title: "Community test: "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for sharing an experiment! This form is intentionally short. Results can be successful, partial or unexpected. Never upload private substation configurations.
+  - type: textarea
+    id: setup
+    attributes:
+      label: Your lab setup
+      description: Which ARStack release, firmware, analyzer or IEC 61850 subscriber did you use?
+      placeholder: "M3.H Studio + ESP32-P4 → lab switch → Wireshark / subscriber"
+    validations:
+      required: true
+  - type: textarea
+    id: configuration
+    attributes:
+      label: SV and PTP configuration
+      placeholder: "4I+4V / 4 kHz, APPID, svID, PTP source mode and relevant settings"
+    validations:
+      required: false
+  - type: textarea
+    id: observation
+    attributes:
+      label: What did you observe?
+      description: What worked? What was unexpected?
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Optional capture or screenshot
+      description: Attach sanitized PCAP, logs or images only if you have permission to share them.
+    validations:
+      required: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,27 +1,32 @@
 # Contributing to ARStack61850
 
-ARStack61850 is an open-source IEC 61850 engineering toolkit. Improvements to interoperability, usability, timing evidence, tests and documentation are welcome.
+Thanks for helping make IEC 61850 experimentation accessible to more engineers.
+
+You can contribute without writing C++: improve a tutorial, report a reproducible issue, translate an explanation, contribute an example, or share results from an isolated lab setup.
 
 ## Start here
 
-- **Using the software?** Follow the [installation guide](docs/INSTALL.md) and select the [latest stable release](https://github.com/masarray/arstack61850/releases/latest).
-- **Found a problem?** Open a [GitHub issue](https://github.com/masarray/arstack61850/issues/new/choose) with the steps to reproduce it, the expected result, and the actual result. The exact Studio version, firmware Build ID, OS and relevant IEC 61850 profile help when available.
-- **Want to improve the code?** Read [Developer Guide](docs/DEVELOPER_GUIDE.md) for the existing build and test workflow. Check for an existing issue before implementing a large new feature.
+- New to ARStack? Follow [Getting Started](docs/GETTING_STARTED.md).
+- Found a problem? Use the [bug report form](https://github.com/masarray/arstack61850/issues/new?template=bug_report.yml).
+- Tested another IEC 61850 setup? Share a [community interoperability report](docs/COMMUNITY_TESTING.md).
+- Want to change source code? Open an issue describing the improvement before undertaking a large change.
+
+## Pull requests
 
-## Submitting a pull request
+1. Fork the repository and create a branch for your change.
+2. Keep each PR focused, with a short description of why it helps users.
+3. For code changes, run the relevant build and tests and describe what you actually tested.
+4. Attach a screenshot for user-interface changes when possible.
+5. Keep public copy **vendor-neutral**, friendly to first-time users, and accurate about supported workflows.
 
-1. Branch from current `main`; do not reuse an old divergent release-candidate branch.
-2. Keep each PR focused on one change. Describe the engineering problem, proposed behavior and affected modules.
-3. Include a reproducible test or captured evidence for the behavior you changed. Run relevant C++/Qt/embedded checks and link the exact GitHub Actions results.
-4. Preserve defined protocol behavior and fail closed on unknown SCL/MMS identity or unsupported SV/PTP synchronization claims.
-5. State clearly which checks passed and what still requires physical equipment, a real peer or longer endurance testing.
+Never submit proprietary firmware, confidential substation configurations, credentials, or private customer captures. Security vulnerabilities should be reported privately using [SECURITY.md](SECURITY.md), not in public issues.
 
-The current public M3.H Lab Simulator has a pinned firmware Build ID and immutable release artifacts. Future source changes belong to a new reviewed milestone; never overwrite old published binaries.
+Keep new work on current `main` and do not modify immutable release tags or published binaries. For changes involving hardware timing or packet behavior, include measured evidence when available.
 
-## Vendor-neutral evidence
+## Product and engineering documentation
 
-Use standards-based descriptions rather than manufacturer-specific workarounds. Sanitise captures and SCL files before publishing: remove site names, station IPs, customer identifiers, credentials, private certificates and proprietary details. Prefer small synthetic regression fixtures that reproduce the same observable protocol behavior.
+User-facing guides should put the action first: what to click, what to expect, and how to troubleshoot. Put architecture notes, internal test records and historical decisions in [developer documentation](docs/DEVELOPER_GUIDE.md).
 
-Security vulnerabilities should be reported privately using [SECURITY.md](SECURITY.md), not through a public exploit issue.
+Active SV/PTP injection belongs in an isolated laboratory network. See the [release notes](https://github.com/masarray/arstack61850/releases/latest) for the current firmware/application pair.
 
-Contributions are subject to the repository's [GPL-3.0 license](LICENSE) and applicable third-party notices.
+By contributing, you agree that your contributions are provided under the repository's [GPL-3.0 license](LICENSE).
diff --git a/README.md b/README.md
@@ -1,61 +1,59 @@
 # ARStack61850
 
-An open-source **IEC 61850 engineering lab** for exploring Sampled Values, PTP timing and process-bus behavior. Configure waveforms in a native desktop app, then generate real Ethernet traffic with an ESP32-P4 board.
+**Open-source IEC 61850 Process Bus engineering lab**
 
-[![Latest release](https://img.shields.io/github/v/release/masarray/arstack61850?label=Latest%20release)](https://github.com/masarray/arstack61850/releases/latest)
-[![C++ CI](https://github.com/masarray/arstack61850/actions/workflows/cpp-ci.yml/badge.svg)](https://github.com/masarray/arstack61850/actions/workflows/cpp-ci.yml)
-[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue)](LICENSE)
+Generate real Sampled Values (SV) traffic, explore PTP synchronization, and experiment with digital-substation signals using **ARStack Studio** and an **ESP32-P4 Ethernet board**.
 
-[**Download latest release**](https://github.com/masarray/arstack61850/releases/latest) · [Product website](https://masarray.github.io/arstack61850/) · [Installation guide](docs/INSTALL.md) · [Report an issue](https://github.com/masarray/arstack61850/issues)
+[**Download the latest stable release**](https://github.com/masarray/arstack61850/releases/latest) · [**Getting started**](docs/GETTING_STARTED.md) · [**Product website**](https://masarray.github.io/arstack61850/) · [**Get help**](SUPPORT.md)
 
-## What can you do with ARStack?
+## What you can do
 
-| Capability | Your workflow |
+| Explore | With ARStack |
 | --- | --- |
-| 4I + 4V Sampled Values | Set current, voltage, frequency and phase scenarios in ARStack Studio, then publish SV from an ESP32-P4 Ethernet board |
-| PTP laboratory timing | Explore a simulated grandmaster and observe Announce, Sync and Follow_Up frames |
-| Capture and inspect | Review traffic, counters, waveform/phasor behavior and timing evidence |
-| IEC 61850 engineering files | Explore SCL-based configurations and reference profiles in the desktop tooling |
-| Open protocol foundations | Build on C++20 MMS, GOOSE, Sampled Values, SCL and COMTRADE components |
+| **Generate Sampled Values** | Publish 4 current + 4 voltage channels over real Ethernet at 4,000 SV frames/s. |
+| **Experiment with PTP** | Run an internal laboratory grandmaster emulator with hardware-assisted phase synchronization. |
+| **Control waveforms** | Set current, voltage and phase values in the ARStack Studio desktop interface. |
+| **Inspect live traffic** | Capture SV and PTP using Studio, Wireshark, ARSAS or DigSubAnalyzer. |
+| **Learn with engineering files** | Open SCL files and deploy supported 4I+4V publisher profiles. |
 
-ARStack is made for hands-on experimentation, demonstrations and engineering validation. You can launch the desktop app and explore its controls before connecting hardware; Ethernet SV/PTP output uses the supported ESP32-P4 device.
+**M3.H stable lab release (24 October 2026):** an independent capture measured **163,048 consecutive SV frames at 3,999.884 frames/s**, with no missing, duplicate or malformed SV packets and `smpSynch=2` throughout the recorded interval. [View the full measurements](docs/releases/PROCESS_BUS_SIMULATOR_M3H_PUBLIC_20261024.md).
 
-## Get started
+## Get started in minutes
 
-1. **Install Studio.** Open the [latest stable release](https://github.com/masarray/arstack61850/releases/latest) and download the Windows x64 Setup EXE or Portable ZIP.
+1. **[Download ARStack Studio](https://github.com/masarray/arstack61850/releases/latest)** for Windows x64 (Setup EXE or Portable ZIP).
+2. Open Studio and try the built-in **4I+4V Quick Start** profile. You can explore the interface before connecting hardware.
+3. To transmit real Ethernet frames, connect a compatible **ESP32-P4 Ethernet** board over USB and Ethernet. Use **Configuration → Firmware** to install the firmware bundled with **the same release**.
+4. Choose **PTP SOURCE**, set **SMPSYNCH AUTO**, configure voltage/current waveforms, and press **Start**.
+5. View the output using Studio capture or Wireshark (`0x88BA` for SV, `0x88F7` for PTP).
 
-2. **Choose a scenario.** Open ARStack Studio and select the built-in **4I+4V** profile, or open a compatible SCL configuration.
+**[Full first-run guide →](docs/GETTING_STARTED.md)** · [Installation on Windows and Linux](docs/INSTALL.md)
 
-3. **Connect hardware for live output.** Attach your ESP32-P4 Ethernet board through USB and install the firmware shipped with the *same release* using Studio's Firmware panel.
+For active SV/PTP transmission, use an **isolated laboratory Ethernet network**, not an operating substation process bus.
 
-4. **Start your lab traffic.** Connect Ethernet to a dedicated test switch, set your signals and PTP mode, then use **Start / Stop** and inspect the resulting SV/PTP packets.
+## Downloads and platforms
 
-Prefer installing from a Windows terminal? The verified installer script follows GitHub's current public stable release:
-
-```powershell
-$script = Join-Path $env:TEMP 'arstack-install.ps1'
-Invoke-WebRequest 'https://raw.githubusercontent.com/masarray/arstack61850/main/scripts/install-windows.ps1' -OutFile $script
-& $script
-```
+| Package | Availability |
+| --- | --- |
+| Windows Setup EXE | **Available** in the [latest release](https://github.com/masarray/arstack61850/releases/latest) |
+| Windows Portable ZIP | **Available** in the [latest release](https://github.com/masarray/arstack61850/releases/latest) |
+| Matched ESP32-P4 firmware | **Available** with the same release |
+| Linux AppImage | Shown in the [latest release](https://github.com/masarray/arstack61850/releases/latest) when a tested package is published |
+| Windows package manager | [WinGet preparation and status](docs/INSTALL.md#windows-package-manager--winget) |
 
-For Linux x86_64, check [Downloads](https://github.com/masarray/arstack61850/releases/latest) for an AppImage when it is published; the [installation guide](docs/INSTALL.md) also covers Linux command-line setup and WinGet package status.
+Every published Windows release includes the application dependencies and a matched firmware package; no C++ build environment is required for ordinary installation.
 
-## See it in action
+## Community
 
-The released **M3.H** laboratory milestone captured **163,048 SV frames** in 40.763 seconds at **3,999.884 frames/s**, with continuous `smpCnt` and no missing, duplicate or malformed SV frames in that captured interval. The same test recorded PTP Announce / Sync / Follow_Up traffic.
+ARStack is built to make IEC 61850 experiments more accessible to engineers, students and automation enthusiasts around the world.
 
-[View the M3.H engineering results](docs/releases/PROCESS_BUS_SIMULATOR_M3H_PUBLIC_20261024.md) · [Explore the product page](https://masarray.github.io/arstack61850/)
+- **[Ask a question or report a problem](SUPPORT.md)** — share what you tried and what happened.
+- **[Share an interoperability experiment](docs/COMMUNITY_TESTING.md)** — feedback from independent laboratory setups helps improve the project.
+- **[Contribute](CONTRIBUTING.md)** — improvements to documentation, software, tests and examples are welcome.
 
-## Developers & contributors
+ARStack uses the [GPL-3.0 license](LICENSE). It is a laboratory simulation and engineering tool, not a certified primary measurement or UTC reference device.
 
-ARStack includes a portable C++20 IEC 61850 engine, Qt desktop applications, embedded targets and automated protocol tests.
+## For developers
 
-- [Contributing](CONTRIBUTING.md) — propose improvements with reproducible evidence and current-main PRs
-- [Security policy](SECURITY.md) — report vulnerabilities privately and handle lab evidence responsibly
-- [Technical & developer reference](docs/DEVELOPER_GUIDE.md) — architecture, build commands, implemented modules and lab validation
-- [Project direction](NORTH_STAR.md) — product goals and architecture
-- [Studio operator guide](apps/arstack_studio/README.md) — usage and firmware handling
-- [IEC 61850 simulator](apps/ied_simulator/README.md) — MMS server and model-based engineering workbench
-- [Issues and discussions](https://github.com/masarray/arstack61850/issues) — report a problem or share a reproducible test
+Want to explore the protocol engine or build from source? Start with the [developer documentation index](docs/DEVELOPER_GUIDE.md).
 
-The application is free and open source under the [GPL-3.0 license](LICENSE). Keep active SV/PTP publishing on a dedicated lab network rather than a live substation LAN.
+The source tree includes a portable C++20 IEC 61850 protocol engine, SCL/COMTRADE tooling, MMS and GOOSE foundations, ESP32-P4 firmware and reproducible tests. Capabilities vary by application and release; the [feature matrix](docs/FEATURE_MATRIX.md) separates released tools from libraries and development features.
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -0,0 +1,19 @@
+# ARStack support
+
+**[Download the latest version](https://github.com/masarray/arstack61850/releases/latest)** · **[Getting started](docs/GETTING_STARTED.md)** · **[Installation](docs/INSTALL.md)**
+
+## Something not working?
+
+Use the [simple bug-report form](https://github.com/masarray/arstack61850/issues/new?template=bug_report.yml). A short description is enough to start.
+
+Useful details include the Studio release, Windows version, ESP32-P4 firmware build if connected, the exact error shown and the last action you tried.
+
+**SCL import issue?** Share a screenshot of the validation result and, if permissible, a sanitized SCL/CID/SCD/IID file that reproduces it. Never share confidential installation data.
+
+**Can't find the board?** Check the USB data cable and serial device selection; use **Configuration → Firmware** to verify the ESP32-P4 and install matching firmware.
+
+**Can't see SV in Wireshark?** Verify the isolated Ethernet topology, selected capture interface and whether a switch mirror/TAP is needed.
+
+**Interested in IEC 61850 subscriber testing?** Share results in the [community interoperability guide](docs/COMMUNITY_TESTING.md).
+
+For a new release, always install the Studio/firmware pairing shipped together. Do not connect active SV/PTP lab output to an operating substation LAN.