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

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.

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.