> For the complete documentation index, see [llms.txt](https://docs.myrspoven.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myrspoven.com/integrations/overview/bms-integrations/siemens.md).

# Siemens

The Siemens integration covers two platforms. **Siemens Building X (BPCloud)** is the cloud platform and the recommended path for new sites — detailed below. **Siemens Desigo CC** is the legacy on-prem platform, still supported but requiring manual virtual-signal setup in the BMS; summarized at the end. The two paths share no prerequisites.

## Siemens Building X (BPCloud)

### What the integration does

myCoreAI connects to a Building X tenant over its public JSON:API to discover equipment and points, read current and historical values, and write numeric setpoints where permitted. Discovery maps Building X equipment, devices, and points into Myrspoven systems, components, and signals automatically.

* **API style:** JSON:API over HTTPS
* **Auth:** OAuth2 client credentials
* **Base URL:** `https://api.bpcloud.siemens.com/`

### Required credentials

Per building:

| Property                      | Description                                                  |
| ----------------------------- | ------------------------------------------------------------ |
| `ClientId`                    | OAuth2 client ID for the service account                     |
| `ClientSecret`                | OAuth2 client secret (treat as credential)                   |
| `SiemensBuildingXPartitionId` | Building X partition UUID — tenant scope for all API calls   |
| `ExternalBuildingId`          | The building's location GUID in the Building X structure API |

{% hint style="warning" %}
**Security.** `ClientSecret` is shared over an agreed secure channel only (password-manager share or encrypted handoff). If exposed in chat, email, or a ticket, the secret is rotated in Building X / Auth0 and re-shared.
{% endhint %}

### Required API permissions

* **Structure API (read):** `equipment`, `equipment-types`, `locations`, `point-groups`, `point-groups/{id}/points`
* **Operations API (read):** `devices`, `devices/{id}/points`, `points/{id}`, `point-value-resource` (current and history)
* **Operations API (write):** `POST points/{id}` — only when myCoreAI writes setpoints

Read-only access is sufficient for analysis and reporting. Write access is required only when myCoreAI is actively optimizing the building.

### Discovery

Discovery runs in two deterministic phases. Raw data is fetched first; interpretation happens in a separate pass. The result is auditable and reproducible run-to-run.

**Phase 1 — snapshot collection**

1. Fetch the equipment list and equipment-type catalog for the partition.
2. Resolve the building's location scope and filter equipment to that building.
3. Build a device-to-equipment map from `isControlledBy` relationships.
4. Fetch devices in the building location.
5. Build point-group enrichment maps (tags, equipment IDs, device IDs by point ID).
6. For each device, fetch its points and resolve the owning equipment.

**Phase 2 — signal and component tagging**

1. Seed components from equipment using the known equipment-type mappings.
2. Convert each point to a signal and normalize its point-group tags.
3. Match against the rule catalog (equipment-type GUID + required/forbidden tags) to assign a signal position and component type.
4. Fall back to the equipment's default component binding when no rule matches.
5. Post-process: merge duplicates, deduplicate signal names, remove incompatible assignments.

### Point-groups and fallback strategy

Building X point-groups bind points to equipment deterministically. A point-group ID encodes the entity type — `Equipment-{id}` or `Device-{id}`.

The preferred path is `GET /structure/partitions/{partitionId}/point-groups`. Some tenants restrict this endpoint and return HTTP 403; the integration auto-detects this and falls back to per-entity probing. No configuration required.

### Reading and writing values

**Current values** are read with a three-level fallback per signal:

1. Point-group endpoint (batched — fewest requests)
2. Batch point-values endpoint
3. Per-point history endpoint (last value, last-resort)

The value parser handles strings, numbers, booleans, and JSON elements. `"on"/"off"` and `"open"/"closed"` normalize to 1/0. NaN and infinity are rejected.

**Historical values** are fetched via the point-value-resource endpoint with a UTC date range. Pagination is automatic.

**Writes** are accepted only for finite numeric values.

### Supported equipment and signal types

Signal mapping is driven by a rule catalog keyed on equipment-type GUIDs and semantic tags.

| Equipment family                 | Myrspoven system  | Example signal positions                                           |
| -------------------------------- | ----------------- | ------------------------------------------------------------------ |
| Air handling unit (AHU)          | Ventilation       | Supply/return air temperature, pressure, flow, CO₂, setpoints      |
| Terminal unit (VAV/CAV)          | Ventilation       | Zone control, comfort observables, damper position                 |
| Hydronic circuit                 | Heating           | Supply/return temperatures, setpoints, valve position, pump status |
| Cooling (chiller, cooling tower) | Cooling           | Chiller temps, condenser water, cooling-tower signals              |
| Heat exchanger                   | Heating / Cooling | Supply/return, bypass and isolation valve positions                |
| Energy meter                     | Energy            | Energy consumption points                                          |
| Observable sensors               | Observables       | Weather, room comfort, CO₂, occupancy                              |

Equipment outside this list still completes discovery; unmatched points are not auto-bound and may need a rule extension. The diagnostics file is the starting point for that extension.

### Onboarding checklist

* Provision an OAuth2 service account (client credentials grant) in the Building X / Auth0 tenant.
* Grant read access — and write access if applicable — to the relevant partition.
* Share `ClientId`, `ClientSecret`, `SiemensBuildingXPartitionId`, and `ExternalBuildingId` with Myrspoven through the agreed secure channel.

## Legacy: Desigo CC (on-prem)

Older Siemens deployments use on-site Desigo CC rather than Building X. The integration model differs fundamentally: instead of a cloud API with structured equipment metadata, myCoreAI communicates through virtual signals created inside the BMS itself.

This path is still supported but is no longer recommended for new sites. Desigo CC sites are onboarded case-by-case with Myrspoven, as the exact virtual-signal layout depends on which signals are read versus written.

High-level steps:

1. Run discovery against the BMS to enumerate available signals.
2. Select signals to read and write.
3. Create the required virtual signals inside the BMS (one-time manual setup per building).
4. Re-run discovery to pick up the virtual signals.
5. Confirm the resulting structure in Myrspoven.

Virtual-signal folder layout, watchdog handling, and fallback behavior are coordinated case-by-case with Myrspoven to avoid disrupting the live BMS.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.myrspoven.com/integrations/overview/bms-integrations/siemens.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.