> 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)** jest platformą chmurową i zalecaną ścieżką dla nowych obiektów — szczegóły poniżej. **Siemens Desigo CC** jest starszą platformą lokalną, nadal wspieraną, ale wymagającą ręcznej konfiguracji sygnałów wirtualnych w BMS; podsumowanie na końcu. Obie ścieżki nie mają wspólnych wymagań wstępnych.

## Siemens Building X (BPCloud)

### Co robi integracja

myCoreAI łączy się z tenantem Building X poprzez jego publiczne JSON:API, aby wykrywać urządzenia i punkty, odczytywać bieżące i historyczne wartości oraz zapisywać numeryczne nastawy, gdy jest to dozwolone. Odkrywanie automatycznie mapuje urządzenia, aparaty i punkty Building X na systemy, komponenty i sygnały Myrspoven.

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

### Wymagane poświadczenia

Dla każdego obiektu:

| 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 tenantowy dla wszystkich wywołań API |
| `ExternalBuildingId`          | GUID lokalizacji budynku w API struktury Building X                    |

{% hint style="warning" %}
**Bezpieczeństwo.** `ClientSecret` jest udostępniany wyłącznie za pośrednictwem uzgodnionego bezpiecznego kanału (udostępnienie w menedżerze 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

* **API struktury (odczyt):** `urządzenia`, `typy urządzeń`, `lokalizacje`, `grupy punktów`, `point-groups/{id}/points`
* **API operacyjne (odczyt):** `urządzenia`, `devices/{id}/points`, `points/{id}`, `zasób wartości punktu` (bieżące i historia)
* **API operacyjne (zapis):** `POST points/{id}` — tylko wtedy, gdy myCoreAI zapisuje nastawy

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

### Odkrywanie

Odkrywanie 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ę urządzeń i katalog typów urządzeń dla partycji.
2. Ustal zakres lokalizacji budynku i odfiltruj urządzenia do tego budynku.
3. Zbuduj mapę urządzenie–sprzęt na podstawie `isControlledBy` relacji.
4. Pobierz urządzenia w lokalizacji budynku.
5. Zbuduj mapy wzbogacania grup punktów (tagi, identyfikatory urządzeń, identyfikatory sprzętu według identyfikatora punktu).
6. Dla każdego urządzenia pobierz jego punkty i ustal właścicielski sprzęt.

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

1. Utwórz komponenty na podstawie urządzeń, korzystając ze znanych mapowań typów urządzeń.
2. Przekształć każdy punkt w sygnał i znormalizuj jego tagi grup punktów.
3. Porównaj z katalogiem reguł (GUID typu urządzenia + wymagane/zabronione tagi), aby przypisać pozycję sygnału i typ komponentu.
4. W razie braku dopasowania użyj domyślnego przypisania komponentu dla urządzenia.
5. Przetwarzanie końcowe: scal duplikaty, usuń duplikaty nazw sygnałów, usuń niekompatybilne przypisania.

### Grupy punktów i strategia awaryjna

Grupy punktów Building X deterministycznie łączą punkty ze sprzętem. Identyfikator grupy punktów koduje typ encji — `Sprzęt-{id}` lub `Urządzenie-{id}`.

Preferowaną ścieżką jest `GET /structure/partitions/{partitionId}/point-groups`. Niektórzy tenanci ograniczają ten endpoint i zwracają HTTP 403; integracja automatycznie to wykrywa i przechodzi do sondowania dla każdej encji osobno. Bez koniecznej konfiguracji.

### Odczyt i zapis wartości

**Bieżące wartości** są odczytywane z trzystopniowym mechanizmem awaryjnym dla każdego sygnału:

1. Endpoint grupy punktów (partiami — najmniej żądań)
2. Wsadowy endpoint wartości punktów
3. Endpoint historii dla pojedynczego punktu (ostatnia wartość, ostateczność)

Parser wartości obsługuje ciągi znaków, liczby, wartości logiczne i elementy JSON. `„włączony”/„wyłączony”` i `„otwarty”/„zamknięty”` są normalizowane do 1/0. NaN i nieskończoność są odrzucane.

**Wartości historyczne** są pobierane za pośrednictwem endpointu point-value-resource z zakresem dat w UTC. Paginacja jest automatyczna.

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

### Obsługiwane typy urządzeń i sygnałów

Mapowanie sygnałów jest sterowane przez katalog reguł oparty na GUID-ach typów urządzeń i tagach semantycznych.

| Rodzina urządzeń                       | System Myrspoven        | Przykładowe pozycje sygnałów                                                    |
| -------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- |
| Jednostka wentylacyjna (AHU)           | Wentylacja              | Temperatura powietrza nawiewanego/powrotnego, ciśnienie, przepływ, CO₂, nastawy |
| Jednostka końcowa (VAV/CAV)            | Wentylacja              | Sterowanie strefą, obserwable komfortu, pozycja przepustnicy                    |
| Obieg hydrauliczny                     | Ogrzewanie              | Temperatury zasilania/powrotu, nastawy, pozycja 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 odcięcia                          |
| Licznik energii                        | Energia                 | Punkty zużycia energii                                                          |
| Czujniki obserwowalne                  | Obserwable              | Pogoda, komfort pomieszczenia, CO₂, zajętość                                    |

Sprzęt spoza tej listy nadal przechodzi odkrywanie; niedopasowane punkty nie są automatycznie przypisywane i mogą wymagać rozszerzenia reguł. Plik diagnostyczny jest punktem wyjścia do takiego rozszerzenia.

### Lista kontrolna wdrożenia

* Utwórz konto usługi OAuth2 (grant client credentials) w tenancie Building X / Auth0.
* Nadaj 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 używają lokalnego Desigo CC zamiast Building X. Model integracji zasadniczo się różni: zamiast chmurowego API ze ustrukturyzowanymi metadanymi sprzętu, myCoreAI komunikuje się za pośrednictwem wirtualnych sygnałów utworzonych 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 ogólne:

1. Uruchom odkrywanie w 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 dla każdego budynku).
4. Uruchom ponownie odkrywanie, aby wykryć sygnały wirtualne.
5. Potwierdź wynikową strukturę w Myrspoven.

Układ folderów sygnałów wirtualnych, obsługa watchdogów i zachowanie awaryjne są uzgadniane indywidualnie z Myrspoven, aby nie zakłócić działającego 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/myrspoven-docs/myrspoven-docs-pl/integracje/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.