Status: working procedure, not yet executed in Capella by the author. Menu and wizard names below are best-effort and differ between Capella versions - where a step names a menu, treat it as "look for this", and confirm in Capella's own Help (Help > Help Contents > Capella User Guide, chapters "Libraries" and "Reuse: REC/RPL"). Element names in the appendix come from the real repository, so they can be typed in as-is.

Audience: the person building the models in Capella (one architect, working alone at first).

1. What you are building

Four reusable Capella projects, then one project-specific model that pulls them together.

RTE composition.** The RCA Safe Computing Platform (RTE) is delivered as Platform core plus safe communication. Both stay separate Capella libraries (they are separately assessed and separately reusable). In RBC_PKP, model an "RTE" grouping component that references both, and record the RTE release tuple (Platform core tag, OSAdapter tag, safe communication tag) in compatibility.md. See docs/safety/CERTIFICATION_PLAN.dox section 2.1.

Rule of thumb: unchanged and reused -> reference. Must be customized per project -> instantiate.

2. Decisions to make before you start (10 minutes, write the answers down)

1. Capella version. Everything below depends on it. Note it here: ____.
2. Instantiate GA by duplication or by REC/RPL?
   • Duplicate project (File > Duplicate, or copy the folder): simple, but the copy silently drifts from the template - the same risk ab_siteGA.c has against ab_siteGP.c.
   • REC/RPL (Reusable Element Collection / Replica): you publish GA-Template's elements as a REC, and RBC_PKP holds replicas (RPL) that remember their origin, can be compared to it, and can be updated from it while keeping intentional local changes. Recommended if your Capella version has the REC/RPL manager - it addresses drift, which duplication does not. Use duplication only as a fallback.
3. Version pinning policy. Suggested: libraries are tagged in git (Platform_RTE-v0.3.0), and RBC_PKP records the exact tag of each library it references in the compatibility table (section 7). Never reference "latest".
4. Who owns each project. Capella model files (.aird, .capella) are XML but merge-hostile** - two people editing the same model in git will produce painful conflicts. One owner per project, or use Team for Capella (a server-based option) later.
5. Where the models live. Suggested: a new sibling folder RBC_Template/architecture/capella/ (one subfolder per project), its own git repo like every other subproject.

3. Step 1 - create the four library projects

Repeat for Platform_RTE, Platform_Protocol_SafeComm, RBC_GP, RBC_GA_Template:

1. File > New > Capella Project. Name it exactly as in the table. Keep the default model name, and leave "Create empty" (do not add the sample).
2. Open the model. You will build the Logical Architecture (LAB diagram) and the Interfaces** package for each. Do not build Operational/System Analysis inside the libraries - those belong to the project (RBC_PKP), because they describe what this customer's system must do.
3. Put every reusable thing in the Logical Architecture of the library project. Only elements a consumer should reuse belong there; internal helper detail can stay out.
4. Enter the content from the appendix (section 8) for that project.
5. Run model validation (right-click the model > Validate model). Fix errors before continuing.
6. Commit to git and tag (Platform_RTE-v0.1.0 etc.).

4. Step 2 - make them usable as libraries

Goal: RBC_PKP can see the elements of these projects, read-only.

1. In RBC_PKP (created in step 3), right-click the model in Project Explorer and look for an action such as Libraries > Manage referenced libraries / Reference library (wording varies by version). Add Platform_RTE, Platform_Protocol_SafeComm, RBC_GP.
2. The referenced models appear under a Libraries node. Their elements can be dragged into your own diagrams (LAB, PAB) and used as types.
3. Expect read-only. You cannot edit library elements from RBC_PKP. To change them, open the library project, change, validate, re-tag, then update the reference in RBC_PKP. This is the model-level version of "you don't edit `Platform_RTE` from inside GP".
4. If a library reference cannot be added, the usual causes are: the library project is not in the same Eclipse workspace, or it has unresolved validation errors, or your Capella version needs the library flagged first (check the Libraries chapter of the help).

5. Step 3 - create RBC_PKP

1. Get the GA template into RBC_PKP.
   • REC/RPL route (recommended): in RBC_GA_Template, select the GA Logical Components and Interfaces and create a REC from them (REC/RPL manager). Publish it in a REC catalog. In a new empty project RBC_PKP, instantiate the REC (creates replicas). Later, use "Update from REC" to pull template changes and "Compare" to see local drift.
   • Duplicate route: File > Duplicate on RBC_GA_Template, rename the copy RBC_PKP. Remember you now own a fork - record the template version you copied in section 7.
2. Add the three library references (section 4 step 1).
3. Operational Analysis (OA). Actors and activities from the PKP operational need. Suggested entities: Train (onboard EVC), Interlocking (IL), Traffic control (CTC), Dispatcher, Maintenance. Activities: "Report position", "Request/receive Movement Authority", "Set/release route", "Fail over to the other site".
4. System Analysis (SA). Boundary = "RBC PKP system". System functions matching the GP behaviour: process position report, compute Movement Authority, cross-compare A vs B, negotiate site role (online/standby), transfer state on promotion, raise CTC alarm. Define functional chains, e.g. Position report -> compute MA -> cross-compare -> send MA to train.
5. Logical Architecture (LA). Bring in from libraries: Safe Computing Platform (RBC_Template- Framework), the GP component (RBC_GP), and the specialized GA replica. Draw the required/ provided interfaces: GA requires GP's ga_interface; GP requires the framework's PI-API (the rte_flow interface). Allocate the SA functions to these components.
6. Physical Architecture (PA). See section 6.
7. Site data (the Specific Application tier). Model the PKP-specific configuration as elements/properties in RBC_PKP only: track layout source (ab_site.railml.xml), port plan, topology and standby mode (section 6), channel names per link. Never push these into a library - they are what makes it a Specific Application.

6. Physical Architecture recipe - 2oo2 with redundancy on Kontron

1. Create Physical Components of nature Node for the hardware: Kontron-3U-Site-WEST, Kontron-3U-Site-EAST (each with the A and B channel processors if they are separate boards, otherwise one node each - decide from the real chassis).
2. Create Behavior Physical Components for the deployed processes and deploy them on nodes: A/WEST, B/WEST, C/WEST, A/EAST, B/EAST, C/EAST. Each realizes the matching LA component (A/B realize GP+GA; C realizes the gateway).
3. Physical Links (and Physical Paths) matching the real network:
   • ab-peer A<->B within a site (A listens, B connects)
   • ab-negotiate WEST<->EAST per channel (WEST listens, EAST connects)
   • ab-relay-{train,il,ctc,util} from A and B to C
   • C to the external simulators/real systems (Train, IL, CTC)
4. Replication and standby as properties, not separate models. Use Property Values Management (PVMT) to define a small property group and attach it to the deployment: topology (2oo2 | 2oo2_redundant | 2oo3 | nmr), replicas (int), standby_mode (hot | warm | cold), diversity (compiler-channel A/B, physical separation, power feed). This mirrors rte_redundancy_config in the code, so model and config stay one-to-one.
5. Common-cause-failure notes. Same CPU architecture on both channels means diversity has to come from elsewhere; record on the PA: compiler diversity (ADR-008 gcc vs clang), separate power/cooling, temporal offset, independent V&V. These become evidence links for the beta-factor argument (IEC 61508-6 Annex D style) in the safety case.

7. Versioning and compatibility table (keep this in the RBC_PKP project docs)

Add a row per release. If a library changes, re-run validation in RBC_PKP and update this table in the same commit.

8. Appendix - what to model in each library project (from the real code)

8.1 Platform_RTE

Logical Component Safe Computing Platform with sub-components:

Interfaces (put in the Interfaces package; use a Class Diagram (CDB) for data types):

• PI-API (provided by Platform, required by Functional Actor): flow_open, flow_close, flow_send, flow_receive, flow_getattr, flow_setattr; open flags requester/responder/ publisher/subscriber/non-block; channels USER/CTRL.
• OSAdapter Adaptation Interface (ADR-005): provided by an OSAdapter, required by the Platform - one per OAL service (rte_osadapter_flow_t, rte_osadapter_netlink_t, ...).
• Capability Declaration (required from the integrator): "which topology/replica_count do you support?"
• State Registration (required from the integrator): "which fields survive a promotion?"

OSAdapters as separate components in the same library: POSIX OSAdapter (Platform_OS_POSIX), Flow/DDS OSAdapter (safeAPIFlowBackendDDS, currently a stub delegating to netlink - mark the component with a property status = stub).

8.2 Platform_Protocol_SafeComm

Components: Safety Functional Module (SFM) (AU1/AU2/AU3 setup, per-message MAC, sequence numbers, supervision - vital, runs in channels A and B), Communication Functional Module (CFM) (bearer management), Application Layer Entity (ALE) (non-vital gateway relay to A and B), Config. Interfaces: transport abstraction (upward from CFM), EuroRadio (SS-037) and RBC-RBC (SS-098) profiles. Mark vital vs non-vital with a property vital = true/false.

8.3 RBC_GP

Component RBC Generic Platform (requires PI-API). Sub-components: communication layer (peer, relay, negotiate links), cross-compare stage, checkpoint stage, ERTMS procedures engine and FSMs (session, train data, MA, position, shunting, emergency stop, EoM, TSR, handover, text message), route/train database, MA-logic gate, status. Provided interface: GA Interface (the ga_interface.h contract: route/train context snapshots, single context-change notification per domain, context pulls, validated setters, one bare init call ab_ga_ma_adaptation_init).

8.4 RBC_GA_Template

Components: IL adapter, CTC adapter, MA logic adaptation, dispatch. Required interface: GP's GA Interface. Provided: nothing to the outside except through GP. Everything project-specific (route tables, site projection) stays a replaceable part - mark it with a property project_specific = true so the specialization step is visible.

9. Order of work (suggested)

1. Decisions in section 2, then create the four library projects.
2. Model Platform_RTE first (everything else refers to it); validate; tag.
3. RBC_GP, then RBC_GA_Template, then Platform_Protocol_SafeComm; validate; tag each.
4. Create RBC_PKP, wire libraries and GA, then OA -> SA -> LA -> PA in that order.
5. Fill the compatibility table and commit.

9a. Optional automation (RBC_Template/architecture/capella/)

• model_spec.json - the section 8 inventory as data (single source of truth).
• scaffold_capella_workspace.py - plain Python 3, run from a shell: creates one folder per project with a README (manual steps + inventory), compatibility.md, and a .gitignore. Idempotent; --git initialises a repo, --force overwrites.
• p4c_build_model.py - runs inside Capella via Python4Capella: fills a project's Logical Architecture with the components and interfaces from the spec; re-running is a no-op.

What scripts cannot do (checked against the upstream Python4Capella source): create the Capella project (CapellaModel.create() is an unimplemented "TODO"), add library references, draw diagrams, or build the Physical Architecture - those stay manual. The scaffold script was run and its output checked; p4c_build_model.py was exercised only against a stand-in for the API (its control flow and idempotency), not in a real Capella.

10. Known limits of the code that the model should not overstate

• Only 2oo2 (and 2oo2_redundant with exactly 2 replicas) runs today; 2oo3/nmr are rejected at startup. Model 2oo3 as a planned variant, not a supported one.
• standby_mode = hot is not safely implementable yet: the standby replica does not compute its own sessions/db, and ADR-029 requires them to be transferred on promotion. Model it as a planned capability with that prerequisite noted.
• Cross-compare data currently shares the ab-peer link with checkpoint and site-state frames (kind-multiplexed, staged and released by the checkpoint result). Represent it as one physical link carrying three exchange types until that is redesigned.
• The DDS OSAdapter is a stub over netlink; there is no real DDS wire protocol yet.