> 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/myrspoven-docs/myrspoven-docs-pl/integracje/overview/bms-integrations/siemens.md).

# Siemens

Integracja Siemens obejmuje dwie platformy. **Siemens Building X (BPCloud)** to platforma chmurowa i zalecana ścieżka dla nowych obiektów — szczegóły poniżej. **Siemens Desigo CC** to starsza platforma lokalna, nadal wspierana, ale wymagająca ręcznej konfiguracji sygnałów wirtualnych w BMS; podsumowanie znajduje się na końcu. Obie ścieżki nie mają wspólnych wymagań wstępnych.

## Siemens Building X (BPCloud)

### Co robi integracja

myCoreAI łączy się z dzierżawą Building X za pośrednictwem publicznego JSON:API, aby wykrywać wyposażenie i punkty, odczytywać bieżące i historyczne wartości oraz zapisywać numeryczne nastawy, gdy jest to dozwolone. Wykrywanie automatycznie mapuje wyposażenie, urządzenia i punkty Building X na systemy, komponenty i sygnały Myrspoven.

* **Styl API:** JSON:API przez HTTPS
* **Uwierzytelnianie:** poświadczenia klienta OAuth2
* **Adres bazowy:** `https://api.bpcloud.siemens.com/`

### Wymagane poświadczenia

Na budynek:

| Właściwość                    | Opis                                                                   |
| ----------------------------- | ---------------------------------------------------------------------- |
| `ClientId`                    | Identyfikator klienta OAuth2 dla konta usługi                          |
| `ClientSecret`                | Sekret klienta OAuth2 (traktuj jako poświadczenie)                     |
| `SiemensBuildingXPartitionId` | UUID partycji Building X — zakres dzierżawy dla wszystkich wywołań API |
| `ExternalBuildingId`          | GUID lokalizacji budynku w interfejsie API struktury Building X        |

{% hint style="warning" %}
**Bezpieczeństwo.** `ClientSecret` jest udostępniany wyłącznie przez uzgodniony bezpieczny kanał (udostępnienie przez menedżer haseł lub szyfrowane przekazanie). Jeśli zostanie ujawniony na czacie, w e-mailu lub w zgłoszeniu, sekret jest rotowany w Building X / Auth0 i udostępniany ponownie.
{% endhint %}

### Wymagane uprawnienia API

* **Structure API (odczyt):** `equipment`, `equipment-types`, `locations`, `point-groups`, `point-groups/{id}/points`
* **Operations API (odczyt):** `devices`, `devices/{id}/points`, `points/{id}`, `point-value-resource` (bieżące i historia)
* **Operations API (zapis):** `POST points/{id}` — tylko gdy myCoreAI zapisuje nastawy

Dostęp tylko do odczytu jest wystarczający do analizy i raportowania. Dostęp do zapisu jest wymagany tylko wtedy, gdy myCoreAI aktywnie optymalizuje budynek.

### Wykrywanie

Wykrywanie przebiega w dwóch deterministycznych fazach. Najpierw pobierane są surowe dane; interpretacja odbywa się w osobnym przebiegu. Wynik jest audytowalny i odtwarzalny z uruchomienia na uruchomienie.

**Faza 1 — zbieranie migawki**

1. Pobierz listę wyposażenia i katalog typów wyposażenia dla partycji.
2. Ustal zakres lokalizacji budynku i odfiltruj wyposażenie do tego budynku.
3. Zbuduj mapę urządzenie–wyposażenie na podstawie `isControlledBy` relacji.
4. Pobierz urządzenia w lokalizacji budynku.
5. Zbuduj mapy wzbogacające grup punktów (tagi, identyfikatory wyposażenia, identyfikatory urządzeń według identyfikatora punktu).
6. Dla każdego urządzenia pobierz jego punkty i ustal właściciela wyposażenia.

**Faza 2 — oznaczanie sygnałów i komponentów**

1. Inicjuj komponenty na podstawie wyposażenia, korzystając ze znanych mapowań typów wyposażenia.
2. Przekształć każdy punkt w sygnał i znormalizuj jego tagi grup punktów.
3. Dopasuj do katalogu reguł (GUID typu wyposażenia + wymagane/zabronione tagi), aby przypisać pozycję sygnału i typ komponentu.
4. W razie braku dopasowania reguły użyj domyślnego powiązania komponentu wyposażenia.
5. Postprocessing: scal duplikaty, usuń duplikaty nazw sygnałów, usuń niezgodne przypisania.

### Grupy punktów i strategia awaryjna

Grupy punktów Building X deterministycznie wiążą punkty z wyposażeniem. Identyfikator grupy punktów koduje typ encji — `Equipment-{id}` lub `Device-{id}`.

Preferowana ścieżka to `GET /structure/partitions/{partitionId}/point-groups`. Niektóre dzierżawy ograniczają ten punkt końcowy i zwracają HTTP 403; integracja automatycznie to wykrywa i przechodzi do sondowania per encja. Bez konfiguracji.

### Odczyt i zapis wartości

**Wartości bieżące** są odczytywane z trzypoziomowym mechanizmem awaryjnym dla każdego sygnału:

1. Punkt końcowy grup punktów (wsadowy — najmniej żądań)
2. Punkt końcowy wsadowych wartości punktów
3. Punkt końcowy historii dla pojedynczego punktu (ostatnia wartość, ostateczność)

Parser wartości obsługuje ciągi znaków, liczby, wartości logiczne i elementy JSON. `"włączone"/"wyłączone"` i `"otwarte"/"zamknięte"` normalizują się do 1/0. NaN i nieskończoność są odrzucane.

**Wartości historyczne** są pobierane przez punkt końcowy point-value-resource z zakresem dat UTC. Paginacja odbywa się automatycznie.

**Zapisy** są akceptowane tylko dla skończonych wartości liczbowych.

### Obsługiwane typy wyposażenia i sygnałów

Mapowanie sygnałów jest sterowane przez katalog reguł oparty na GUID-ach typów wyposażenia i tagach semantycznych.

| Rodzina wyposażenia                    | System Myrspoven        | Przykładowe pozycje sygnałów                                                        |
| -------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
| Centrala wentylacyjna (AHU)            | Wentylacja              | Temperatura, ciśnienie, przepływ, CO₂ oraz nastawy powietrza nawiewanego/powrotnego |
| Jednostka końcowa (VAV/CAV)            | Wentylacja              | Sterowanie strefą, obserwable komfortu, położenie przepustnicy                      |
| Obieg hydroniczny                      | Ogrzewanie              | Temperatury zasilania/powrotu, nastawy, położenie zaworu, status pompy              |
| Chłodzenie (chiller, wieża chłodnicza) | Chłodzenie              | Temperatury chillera, woda skraplacza, sygnały wieży chłodniczej                    |
| Wymiennik ciepła                       | Ogrzewanie / Chłodzenie | Pozycje zaworów zasilania/powrotu, obejścia i odcinającego                          |
| Licznik energii                        | Energia                 | Punkty zużycia energii                                                              |
| Czujniki obserwowalne                  | Obserwowalne            | Pogoda, komfort pomieszczenia, CO₂, zajętość                                        |

Wyposażenie spoza tej listy nadal przechodzi wykrywanie; niedopasowane punkty nie są automatycznie wiązane i mogą wymagać rozszerzenia reguł. Plik diagnostyczny jest punktem wyjścia dla takiego rozszerzenia.

### Lista kontrolna wdrożenia

* Utwórz konto usługi OAuth2 (grant client credentials) w dzierżawie Building X / Auth0.
* Przyznaj dostęp do odczytu — oraz dostęp do zapisu, jeśli dotyczy — do odpowiedniej partycji.
* Udostępnij `ClientId`, `ClientSecret`, `SiemensBuildingXPartitionId`, oraz `ExternalBuildingId` z Myrspoven za pośrednictwem uzgodnionego bezpiecznego kanału.

## Starsze rozwiązanie: Desigo CC (lokalnie)

Starsze wdrożenia Siemens korzystają z lokalnego Desigo CC zamiast Building X. Model integracji zasadniczo się różni: zamiast chmurowego API ze структурированnymi metadanymi wyposażenia, myCoreAI komunikuje się za pośrednictwem sygnałów wirtualnych tworzonych wewnątrz samego BMS.

Ta ścieżka jest nadal wspierana, ale nie jest już zalecana dla nowych obiektów. Obiekty Desigo CC są wdrażane indywidualnie z Myrspoven, ponieważ dokładny układ sygnałów wirtualnych zależy od tego, które sygnały są odczytywane, a które zapisywane.

Kroki na wysokim poziomie:

1. Uruchom wykrywanie względem BMS, aby wyliczyć dostępne sygnały.
2. Wybierz sygnały do odczytu i zapisu.
3. Utwórz wymagane sygnały wirtualne wewnątrz BMS (jednorazowa ręczna konfiguracja na budynek).
4. Uruchom ponownie wykrywanie, aby uwzględnić sygnały wirtualne.
5. Potwierdź wynikową strukturę w Myrspoven.

Układ folderów sygnałów wirtualnych, obsługa watchdogów i zachowanie awaryjne są koordynowane indywidualnie z Myrspoven, aby uniknąć zakłóceń działania aktywnego 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:

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

The question should be specific, self-contained, and written in natural language.
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.