feat: allow aliased enum PVs to map values to underlying fastcs PVs

[shihab-dls]

Summary by CodeRabbit

• New Features
  • Added support for EPICS aliases backed by enum mappings.
  • Enum mappings now translate read, write, and command values between EPICS and application fields.
  • Added validation and alarm handling for unmapped or invalid enum values.
• Bug Fixes
  • Connection state now correctly reports success after connecting.
  • Successful commands clear previously raised alarms.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 7026f61f-6ef0-4df3-961c-a988e67cd253

📝 Walkthrough

Walkthrough

EPICS CA aliases now support structured enum mappings for read, write, and command PVs. Schemas and options accept the new mapping type. Tests cover conversion, propagation, PVI exposure, and alarms. The demo temperature controller now records successful connections.

Changes

EPICS CA enum aliases

Layer / File(s)	Summary
Enum mapping contracts and configuration src/fastcs/transports/epics/options.py, src/fastcs/demo/schema.json, tests/data/schema.json, tests/example_softioc.py	Adds the EnumMapping model and schema. Extends alias options to accept mappings. Adds enum-valued example attributes and aliases.
IOC enum alias translation src/fastcs/transports/epics/ca/ioc.py	Creates enum-backed read, write, and command aliases. Converts mapped values, validates command mappings, reports warnings, and updates alarms.
Enum alias integration validation tests/transports/epics/ca/test_softioc.py, tests/transports/epics/ca/test_softioc_system.py	Tests alias creation, value conversion, propagation, PVI structure, command alarms, and alarm reset behavior.

Temperature controller connection state

Layer / File(s)	Summary
Connection state update src/fastcs/demo/controllers.py	Sets _connected to True after a successful connection.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant EPICS_CA_Client
  participant EpicsCAIOC
  participant Enum_Attribute
  participant ControllerAPI
  EPICS_CA_Client->>EpicsCAIOC: Put mapped enum value
  EpicsCAIOC->>Enum_Attribute: Convert mapped value
  Enum_Attribute->>ControllerAPI: Update attribute or invoke command
  ControllerAPI-->>EpicsCAIOC: Return operation result
  EpicsCAIOC-->>EPICS_CA_Client: Update PV value and alarm

Loading

Possibly related PRs

• DiamondLightSource/fastcs#332: Updates related temperature controller connection state handling.
• DiamondLightSource/fastcs#385: Provides the existing EPICS CA alias support extended by this change.

Suggested reviewers: gilesknap

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: mapping aliased enum PV values to underlying fastcs PVs.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add_enum_mapping

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 94.78261% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.49%. Comparing base (8df703e) to head (9133573).

Files with missing lines	Patch %	Lines
src/fastcs/transports/epics/ca/ioc.py	94.39%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #417      +/-   ##
==========================================
+ Coverage   91.44%   91.49%   +0.05%     
==========================================
  Files          72       72              
  Lines        2944     3034      +90     
==========================================
+ Hits         2692     2776      +84     
- Misses        252      258       +6     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/fastcs/transports/epics/ca/ioc.py`:
- Around line 40-45: Validate structured alias PV values from EnumMapping.pv
against EPICS_MAX_NAME_LENGTH before IOC record creation, just as _add_alias
validates string aliases. Update the record-creation paths around the affected
alias handling so oversized structured aliases are rejected or skipped
consistently before they are used.
- Around line 483-515: Update _add_write_enum_alias so successful writes through
enum_attr also synchronize the alias record created for alias.pv, while
preventing the update from invoking convert_to_value recursively. Ensure the
alias record reflects the underlying enum value after direct writes to the
original PV, and preserve the existing alias-to-underlying conversion and alarm
handling.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8e74ed54-6c70-4cde-879d-a01bb35df28b

📥 Commits

Reviewing files that changed from the base of the PR and between a2e77b6 and a06629a.

📒 Files selected for processing (8)

• src/fastcs/demo/controllers.py
• src/fastcs/demo/schema.json
• src/fastcs/transports/epics/ca/ioc.py
• src/fastcs/transports/epics/options.py
• tests/data/schema.json
• tests/example_softioc.py
• tests/transports/epics/ca/test_softioc.py
• tests/transports/epics/ca/test_softioc_system.py