docs(lifecycle): add PEv2 HAL interface lifecycle documentation chain (Phase 02–04)

[Copilot]

Per the defined lifecycle process, all Functional/Non-Functional Requirements, Architecture Decision Records, and SDDs must precede code changes. This PR establishes that full documentation chain for the PEv2 HAL interface work tracked in StR #33.

What's Added

.github/workflows/create-lifecycle-issues-pev2.yml

• Idempotent workflow (skips already-existing issues) that auto-creates the full Phase 02–04 issue chain and wires sub-issue relationships back to StR HAL Interface: PEv2 #33.

Phase 02 — System Requirements (req-f-pev2-*.md, req-nf-pev2-*.md)

• 8 Functional Requirements covering: global PEv2 pin export, per-axis pin export, conditional creation for enabled axes only, input-pin→PoKeysLib-pointer sync, output-pin→PoKeysLib-pointer sync, bitmapped-field decomposition (AxesSwitchConfig / AxesConfig / SignalConfig), HAL parameter export, and async function call sequence.
• 3 Non-Functional Requirements: RT safety (servo-thread deadline), interface completeness (all pins from issue spec present), correct PoKeysLib enumeration usage.

Phase 03 — Architecture (adr-pev2-*.md, arc-c-pev2.md)

• 5 ADRs: HAL pin naming convention (pokeys.[DevID].PEv2.*), axis-conditional pin creation strategy, bitmapped→HAL-pin decomposition strategy, read/write phase separation, sPoKeysHalPEv2 global-vs-per-axis struct organisation.
• Architecture Component description for the PEv2 HAL interface.

Phase 04 — Design (sdd-pev2.md)

• IEEE 1016-2009 Software Design Description covering struct layout, HAL export function signatures, per-axis read/write loops, and the full pin/parameter inventory from the issue spec.

str-comment-pev2.md

• Template comment for posting traceability back-references onto StR HAL Interface: PEv2 #33 once issues are created.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Real-time / HAL component change

Traceability

• Requirements: addressed by the REQ-F/REQ-NF files committed here
• Architecture / Design: addressed by the ADR/ARC-C/SDD files committed here
• Tests: n/a — documentation-only commit; test cases to follow in Phase 05

Testing

Documentation-only commit; no build or RT artefacts changed.

• bash test_compile.sh passes
• make -f Makefile.noqmake builds without errors
• HAL userspace component loads (halrun / loadusr)
• HAL RT component loads (halrun / loadrt)
• No memory allocation in RT paths
• No blocking calls in RT paths

Real-Time Safety Checklist (if RT code changed)

• No malloc/free in real-time thread paths
• No blocking socket operations (all sockets are O_NONBLOCK)
• RT function completes within timing budget (<50µs for PREEMPT_RT userspace/soft-RT; <5µs for RTAI/hard-RT kernel module)
• mlockall used where required
• HAL pin types are correct (hal_s32_t, hal_bit_t, hal_float_t)

Checklist

• All tests pass
• Documentation updated alongside code changes
• No unrelated files changed
• Traceability links verified (PR links to implementing issue)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>HAL Interface: PEv2</issue_title>
<issue_description>ensure pokeys_py and pokeys_rt follow the definition below for halinterface of PEv2 and use the correct enumerations and commands to update and extract information for each axis

ensure that pins for required & enabled axes are created only

ensure that input pins are updated by the corresponding pointers in pokeyslib
for outputs ensure that the pointers in pokeyslib are update based on corresponding pins

update documentation accordingly

PEv2 information

Pins

• pokeys.[DevID].PEv2.nrOfAxes;
• pokeys.[DevID].PEv2.maxPulseFrequency;
• pokeys.[DevID].PEv2.bufferDepth;
• pokeys.[DevID].PEv2.slotTiming;
• pokeys.[DevID].PEv2.digin.Emergency.in;
• pokeys.[DevID].PEv2.digin.Emergency.in-not;
• pokeys.[DevID].PEv2.PulseEngineEnabled; // Pulse engine enabled status, also number of enabled axes
• pokeys.[DevID].PEv2.PulseGeneratorType; // Pulse engine generator type (0: external, 1: internal 3ch)
• pokeys.[DevID].PEv2.PG_swap_stepdir;
• pokeys.[DevID].PEv2.PG_extended_io;
• pokeys.[DevID].PEv2.ChargePumpEnabled; // Charge pump output enabled
• pokeys.[DevID].PEv2.PulseEngineActivated; // Pulse engine activation status
• pokeys.[DevID].PEv2.PulseEngineState; // State of pulse engine - see ePoKeysPEState
• pokeys.[DevID].PEv2.MiscInputStatus; // Miscelenous digital inputs...
• pokeys.[DevID].PEv2.digin.Misc-#.in[8]; // Miscelenous digital inputs status (NOT bit-mapped)
• pokeys.[DevID].PEv2.digin.Misc-#.in-not[8]; // inverted Miscelenous digital inputs status (NOT bit-mapped)
• pokeys.[DevID].PEv2.LimitOverride; // Limit override status
• pokeys.[DevID].PEv2.LimitOverrideSetup; // Limit override configuration
• pokeys.[DevID].PEv2.digin.Probed.in;
• pokeys.[DevID].PEv2.digout.Emergency.out;
• pokeys.[DevID].PEv2.AxisEnabledMask; // Bit-mapped ouput enabled mask
• pokeys.[DevID].PEv2.AxisEnabledStatesMask; // Bit-mapped states, where axis enabled and charge pump signals are active
• pokeys.[DevID].PEv2.ExternalRelayOutputs; // External relay outputs
• pokeys.[DevID].PEv2.ExternalOCOutputs; // External open-collector outputs
• pokeys.[DevID].PEv2.digout.ExternalRelay-#.out[4]; // External relay outputs
• pokeys.[DevID].PEv2.digout.ExternalOC-#.out[4]; // External open-collector outputs
• pokeys.[DevID].PEv2.HomingStartMaskSetup; // Bit-mapped axes indexes to be homed
• pokeys.[DevID].PEv2.ProbeStartMaskSetup; // Bit-mapped axis indexes for probing
• pokeys.[DevID].PEv2.ProbeStatus; // Probe status (probe completion bit-mapped status)
• pokeys.[DevID].PEv2.ProbeSpeed; // Probe speed (ratio of the maximum speed)
• pokeys.[DevID].PEv2.BacklashCompensationEnabled;

Parameters

• pokeys.[DevID].PEv2.digin.Emergency.Pin "";
• pokeys.[DevID].PEv2.digin.Emergency.invert "Emergency switch polarity (set to 1 to invert)"; // Emergency switch polarity (set to 1 to invert)
• pokeys.[DevID].PEv2.digout.Emergency.Pin "added in component only for estop-out to reset estop (if 0 EmergencyInput will be reused)"; //added in component only for estop-out to reset estop (if 0 EmergencyInput will be reused)
• pokeys.[DevID].PEv2.digin.Probe.Pin "Probe input (0:disabled, 1-8:external inputs, 9+ Pin ID-9)"; // Probe input (0:disabled, 1-8:external inputs, 9+ Pin ID-9)
• pokeys.[DevID].PEv2.digin.Probe.invert "Probe input polarity"; // Probe input polarity

PEv2 information - for each axis

Pins

• pokeys.[DevID].PEv2.[PEv2ID].AxesState [8]; // Axis states (bit-mapped) - see ePK_PEAxisState
• pokeys.[DevID].PEv2.[PEv2ID].AxesConfig [8]; // Axis configuration - see ePK_PEv2_AxisConfig
• pokeys.[DevID].PEv2.[PEv2ID].AxesSwitchConfig [8]; // Axis switch configuration - see ePK_PulseEngineV2_AxisSwitchOptions
• pokeys.[DevID].PEv2.[PEv2ID].SoftLimitMaximum [8]; // Soft limit maximum position
• pokeys.[DevID].PEv2.[PEv2ID].SoftLimitMinimum [8]; // Soft limit minimum position
• pokeys.[DevID].PEv2.[PEv2ID].HomingSpeed [8]; // Homing speed per axis (in %)
• pokeys.[DevID].PEv2.[PEv2ID].HomingReturnSpeed [8]; // Homing return speed per axis (in % of the homing speed)
• pokeys.[DevID].PEv2.[PEv2ID].HomingAlgorithm[8]; // Homing algorithm configuration
• pokeys.[DevID].PEv2.[PEv2ID].HomeOffsets [8]; // Home position offset
• pokeys.[DevID].PEv2.[PEv2ID].ProbePosition [8]; // Position where probe detected change
• pokeys.[DevID].PEv2.[PEv2ID].ProbeMaxPosition [8]; // Maximum position to travel to until stopping and returning error
• pokeys.[DevID].PEv2.[PEv2ID].CurrentPosition [8]; // Current position
• pokeys.[DevID].PEv2.[PEv2ID].PositionSetup [8]; // Position to be set as current position
• pokeys.[DevID].PEv2.[PEv2ID].ReferencePositionSpeed [8]; // Reference position or speed (position or pulses/s)
• pokeys.[DevID].PEv2.[PEv2ID].MaxSpeed [8...

• Fixes HAL Interface: PEv2 #33

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.