From e208855151ebef246626c8a0d67c40b568c7f5ee Mon Sep 17 00:00:00 2001 From: Diego Quintana Date: Fri, 27 Sep 2024 20:55:20 +0200 Subject: [PATCH] docs: merge existing documentation for registering new plants (et/somenergia-jardiner!161) * new: let mkdocs add anchors and track them on screen * docs: update instructions on how to add new plants * merge two documents into one * add missing references and reorder document structure --- .../2023-08-28-afegir-planta-a-superset.md | 37 --- .../desenvolupadors/2023-08-28-alta_planta.md | 222 ++++++++++++++---- mkdocs.yml | 6 + 3 files changed, 179 insertions(+), 86 deletions(-) delete mode 100644 docs/desenvolupadors/2023-08-28-afegir-planta-a-superset.md diff --git a/docs/desenvolupadors/2023-08-28-afegir-planta-a-superset.md b/docs/desenvolupadors/2023-08-28-afegir-planta-a-superset.md deleted file mode 100644 index 64d5cf8a..00000000 --- a/docs/desenvolupadors/2023-08-28-afegir-planta-a-superset.md +++ /dev/null @@ -1,37 +0,0 @@ -title: Afegir dades de planta des de DSET a dashboards -description: Com afegir una planta (dset) -date: 2023-08-28 - -# Com afegir dades d'una planta nova a instància de superset - -Tenim una instància de [superset](https://indicadors.somenergia.coop) que mostra dades de plantes des de el pipe de transformació de dades arribant del nostre proveïdor de dades. - -Per afegir una nova planta a la visualització, cal seguir un protocol documentat al [Formulari d’inscripció de noves plantes a Superset](https://docs.google.com/document/d/172qofxlvavQhdQhyJ9HE73CX6YLVYA2u6Mq3w_NOzyA/edit#heading=h.mcehna5jn0kc) - -Un cop aquest formulari estigui completat, cal seguir els següents passos: - -!!! warning "Necessites permisos d'administrador" - - Aquesta tasca és per a desenvolupadors que treballen amb el pipe de transformació de dades. Si no ets un desenvolupador, no cal que facis aquesta tasca. - -1. Verificar que estem rebent dades dels senyals de la planta nova des de l'API del proveïdor. Si no, avisar a l'equip de gestió d'actius per que facin incidència al proveïdor. -2. Executar la tasca de sync de l'airbyte d'uuids - 1. [Dades fixes de plantes noves](https://airbyte.moll.somenergia.coop/workspaces/12f265b4-e398-44b4-9c95-1b5b165d6883/connections/e3301299-f721-4efb-b864-0e5b0233b145) - 2. [Objectius de producció](https://airbyte.moll.somenergia.coop/workspaces/12f265b4-e398-44b4-9c95-1b5b165d6883/connections/e5a12532-7c8b-4e12-a7ee-9b71f47c655a/status) - 3. [Relacions entre UUIDs de senyals, aparells i plantes](https://airbyte.moll.somenergia.coop/workspaces/12f265b4-e398-44b4-9c95-1b5b165d6883/connections/6ee76168-27ab-4ac4-9f50-b619664191db/status) -3. Executar `dbt snapshot` per tractar canvis a les plantes segons SCD2, si ni ha hagut. Tenir cura que al actualitzar les dades de la planta, s'ha de modificar les columnes del tipus `updated_at` dins dels documents a omplir. -4. Verificar que les dades apareixen a la visualització de superset. -5. Actualitzar els filtres i els rols de seguretat de la nova planta a superset. Veure [Row Level Security](2024-02-16-row-level-security.md) per més informació. - -!!! info "Per què no un ORM?" - - Tenim al roadmap fer-ho amb un model normalitzat, però està al roadmap del ERP i no tenim una data concreta. - - Com que ja no tenim ORM que verifiqui la integritat de les dades, tenim tests que compleixen aquesta funció. - - Si algun senyal d'un device no té una definició igual de device (per uuid), els tests no passaran. - Per a veure quin senyal és el transgressor, executeu amb el flag `--store-failures` - i així guardarà el resultat de la query del test en una taula sota l'schema `_dbt_test__audit` - - En particular, podeu veure `test_to_debug_device_uuid_errors` per veure les senyals que no quadren. - diff --git a/docs/desenvolupadors/2023-08-28-alta_planta.md b/docs/desenvolupadors/2023-08-28-alta_planta.md index a52d3430..4687a6df 100644 --- a/docs/desenvolupadors/2023-08-28-alta_planta.md +++ b/docs/desenvolupadors/2023-08-28-alta_planta.md @@ -1,87 +1,211 @@ -title: Alta d'una planta fotovoltaica a +title: Alta d'una planta fotovoltaica al pipe de Jardiner description: Procediment a seguir a l’incorporar una nova planta fotovoltaica +lang: ca_ES +tags: [pipe, jardiner, planta, fotovoltaica] date: 2023-08-28 -# Procediment a seguir a l’incorporar una nova planta fotovoltaica +# Context -## Dades +Tenim un pipe de transformació de dades que acaba en una serie de dashboards de [superset](https://indicadors.somenergia.coop) que mostra dades de plantes des de el pipe de transformació de dades arribant del nostre proveïdor de dades. -Les dades necessàries per a donar d'alta una planta són +## Protocol d'alta d'una planta fotovoltaica -[Unificació Noms Projectes Generació](https://docs.google.com/spreadsheets/d/1JwHmZ_FuIs7em8nLrdSNg052O_0IA9Fm1qGp_hz8QlU/edit#gid=0) +Per afegir una nova planta a la visualització, cal seguir un protocol documentat al [Formulari d’inscripció de noves plantes a Superset](https://docs.google.com/document/d/172qofxlvavQhdQhyJ9HE73CX6YLVYA2u6Mq3w_NOzyA/edit#heading=h.mcehna5jn0kc) -Càlcul Rendiment de Planta\_ (buscar-ho al cercador de drive) +El equip de gestio d'actius ha d'omplir aquest formulari amb les dades de la planta i ens ho han de comunicar per a que puguem seguir amb el procés nosaltres. + +!!! info "Obres en curs amb jardiner-admin" + + Aquesta tasca està en procés de ser portada al [jardiner-admin](https://jardiner-admin.moll.somenergia.coop/). Per tant, aquest protocol pot canviar en el futur. + +!!! warning "Necessites permisos d'administrador" + + Aquesta tasca és per a desenvolupadors que treballen amb el pipe de transformació de dades. Si no ets un desenvolupador, no cal que facis aquesta tasca. + +Aqui sota ens dediquem a documentar técnicament els passos a seguir des de la perspectiva de desenvolupament. + +## Checklist general per IT + +- [ ] Tenir accés als següents documents + - [ ] [Mapeig de senyals](#fitxer-mapeig-de-senyals) + - [ ] [Dades fixes de planta](#fitxer-dades-fixes-de-planta) + - [ ] [Info api solargis](#fitxer-info-api-solargis) + - [ ] [Rendiment de planta](#fitxer-rendiment-de-planta) + - [ ] [Producció actual de planta](#fitxer-produccio-actual-de-planta) +- [ ] [Omplir dades al excel de mapeigs d’airbyte](#afegir-mapeig-airbyte) +- [ ] [Afegir planta segons l’estructura de plantmonitor](#afegir-meteologica-plantmonitor) +- [ ] [Dades de Solargis de planta nova són al script a plantmonitor](#afegir-solargis) +- [ ] Dades apareixen al superset correctament + +## Descripció de Dades + + +### Mapeig de senyals de Planta {#fitxer-mapeig-de-senyals} + +Per cada planta, GdA genera fitxers amb informació de la planta per la seva gestió. Aquests fitxers contenen informació de senyals, aparells, plantes, etc. però sense el context del pipe de Jardiner. Com IT, portem aquesta informació al [fitxer de mapeig de senyals](#afegir-mapeig-airbyte) per a que el pipe de Jardiner pugui fer integrar les dades de la planta. + +[Un exemple d'aquest fitxer pot ser aquest](https://docs.google.com/spreadsheets/d/1Fo1y_d2hks8Az9Bx4hzOrqVVNCwMf5t2/edit?gid=455448997#gid=455448997). + + +### Dades fixes de planta {#fitxer-dades-fixes-de-planta} + +Aquest fitxer conté dades fixes de la planta, com ara la potència de la planta, la seva ubicació, etc. [Es trova a google drive](https://docs.google.com/spreadsheets/d/1Av9l0y--J4755JRMWL5kOSQlSY-c797X13CUqzfu3rw/edit?usp=sharing) i [es transforma amb airbyte aqui](https://airbyte.moll.somenergia.coop/workspaces/12f265b4-e398-44b4-9c95-1b5b165d6883/connections/e3301299-f721-4efb-b864-0e5b0233b145) + +### Info API SolarGIS {#fitxer-info-api-solargis} + +GdA ha de crear una entrada per la planta nova al [fitxer excel per això](https://docs.google.com/spreadsheets/d/1J2G6IuqIxIXT4ETG3vxVpryszs9Or_ss8NtMnGCJ6yw/edit#gid=0) + +### Rendiment de planta {#fitxer-rendiment-de-planta} + +Té un nom tipus `"Càlcul Rendiment de Planta "`. El podeu buscar al cercador de drive. + +### Objectius de producció de planta {#fitxer-produccio-actual-de-planta} + +Es trova al fitxer de [google sheets aqui](https://docs.google.com/spreadsheets/d/1VR5wQiHahicm9Q5mxVvzJUfBESYPGP5yvtLDf5NiMfc/edit#gid=2056763057) i es [transforma amb airbyte aqui](https://airbyte.moll.somenergia.coop/workspaces/12f265b4-e398-44b4-9c95-1b5b165d6883/connections/e5a12532-7c8b-4e12-a7ee-9b71f47c655a/status). + +### Unificació Noms Projectes Generació {#fitxer-unificacio-noms-projectes-generacio} + +Conté els llistat de noms unificats en un sol fitxer. Ves a [Unificació Noms Projectes Generació](https://docs.google.com/spreadsheets/d/1JwHmZ_FuIs7em8nLrdSNg052O_0IA9Fm1qGp_hz8QlU/edit#gid=0). + +### Modelos contadores_inversores_SCADAS {#fitxer-modelos-contadores-inversores-scadas} [Modelos contadores_inversores_SCADAS](https://docs.google.com/spreadsheets/d/1Z7_QpzestHBzVf9o78IC3hdGWMDH6dlyUr8f9LewO1o/edit#gid=904950265) -## Xarxa +## Descripció de tasques -1. Conectar-se a la ip del router de la planta i afegir el port forwarding que calgui (raspberrypi o aparells) -2. Demanar a sistemes que afegeixi la planta al dns e.g. planta-.somenergia.coop +### Afegir dades al mapeig d'airbyte {#afegir-mapeig-airbyte} -Tot això ha de quedar escrit en el document Mapeig de Planta +Tenim un [document](https://docs.google.com/spreadsheets/d/1ybUXREO8cMaLMlV4Kt2iYyoNg2msirnbTTiYL2PBY2M/edit?gid=310640207#gid=310640207) on consolidem relacions entre UUIDs de senyals, aparells i plantes que inserim amb [airbyte](https://airbyte.moll.somenergia.coop/workspaces/12f265b4-e398-44b4-9c95-1b5b165d6883/connections/6ee76168-27ab-4ac4-9f50-b619664191db/status) -## Aparells +Aquest mapeig es una traducció del [fitxer de mapeigs](#fitxer-mapeig-de-senyals). -### Comptador +Un cop heu acabat de fer el mapeig, cal engegar la tasca de sync de l'airbyte d'uuids per que les dades arribin a la base de dades. Heu de tenir especial cura d'omplir les columnes `updated_at` i aquelles que posen UUIDs, ja que amb elles se creuen les dades dins del pipe. -Agafar les dades de [Modelos contadores_inversores_SCADAS](https://docs.google.com/spreadsheets/d/1Z7_QpzestHBzVf9o78IC3hdGWMDH6dlyUr8f9LewO1o/edit#gid=904950265) +!!! info "`update_at` s'actualitza automagicament" -ip lan, port, porta d’enllaç i contrasenya + Al fitxer de google sheets hi ha un script que actualitza la columna `updated_at` quan hi ha hagut un canvi a nivell de fila. Es molt limitat i heu de supervisar que s'ha actualitzat correctament, ja que de vegades google sheets no ho fa. Podeu mirar a `Extensions > Apps Script` per veure el codi. -telèfon si s'escau +!!! warning "UUID són versió 4" -### Inversor + Els senyals porten UUID4 (han de ser versio 4) únics al mapeig de la planta indicada. Es poden generar UUID4 amb O ben vé amb un script de python que podeu afegir a `~/.bash_aliases`: -ip + ```bash + #·function·to·genenerate·random·uuid4·using·python$ + function pyuuid4() { + python -c "import uuid$ + for _ in range(${N:-1}): + print(uuid.uuid4())" ; } + ``` -### Raspberrypi + i el podeu executar amb `N= pyuuid4` per a generar `n` UUID4. + + ```bash + $ N=10 pyuuid4 + bf98707e-688c-471c-8700-9ffeaf436531 + 8f6bfcc0-48bf-4b7c-895f-0b2efa37dd63 + ee5dcfd1-80ba-48fb-800d-5bc8c04d217f + d32b0a23-c479-4ae9-bb54-43390fedf8e4 + eced945e-7a91-4451-bbd5-974a82c9c0d4 + fbacbf3d-23f6-4361-b5ec-b48b390d9c09 + b9c4ea66-672e-4dca-ad08-fddacdfb3627 + ae3e242e-9a57-4359-a72b-313a72b48348 + 9e11a595-c32c-42e1-8549-a5161c0ea624 + 172061ed-96b4-4aa3-b5bd-0c66e850383b + ``` -ip lan, usuari, password -## Prèvia +### Afegir planta per `meteologica` amb `plantmonitor` {#afegir-meteologica-plantmonitor} -Tots els scripts fan referència al repositori de github `plantmonitor`. +!!! info "Què és `meteologica`?" -crear la planta a la base de dades tant a la raspberrypi com a plantmonitor (no calen els dispositius, que els crea automàticament), -afegir la plantlocation, plantparameters i moduleparameters. Un exemple [a plantmonitor](https://github.com/Som-Energia/plantmonitor/blob/master/docs/2023-01-09-add_plantparameters_of_a_plant.md) + `meteologica` és un servei que ens permet tenir dades meteorològiques de les plantes fotovoltaiques. Aquest servei es comunica amb `plantmonitor` per a obtenir dades de les plantes. + +!!! info "Què és `plantmonitor`?" + + Tots els scripts en aquest apartat fan referència al repositori de github [`plantmonitor`](https://github.com/Som-Energia/plantmonitor/). És un projecte previ a `jardiner` que ens permet monitoritzar plantes fotovoltaiques quan l'obtenció de dades la gestionem nosaltres. + +A `plantmonitor` tenim un script que ens permet afegir plantes noves. Aquest script s'ha de cridar amb un fitxer yaml que contingui les dades de la planta. + +S'ha de crear la planta a la base de dades tant a la raspberrypi com a plantmonitor (no calen els dispositius, que els crea automàticament). Haureu d'afegir `plantlocation`, `plantparameters` i `moduleparameters`. Trobareu un exemple [a plantmonitor](https://github.com/Som-Energia/plantmonitor/blob/master/docs/2023-01-09-add_plantparameters_of_a_plant.md) + +Un cop teniu el fitxer yaml, per exemple `data/plant-nova.yaml`, podeu cridar l'script `addPlant.py` amb el següent comandament: ```bash PLANTMONITOR_MODULE_SETTINGS='conf.settings.prod' python addPlant.py data/plant-asomada.yaml ``` -De moment manualment cal afegir els registres de plantestimatedmonthlyenergy. L'any és irrellevant. +Haureu de tenir un fitxer `.env.prod` amb les variables d'entorn necessàries per a que l'script funcioni correctament. Mireu a la documentació de plantmonitor per a més informació. + +De moment manualment cal afegir els registres de `plantestimatedmonthlyenergy`. L'any és irrellevant. Si tenim històrics d'energia objectiu, els podeu afegir. ```sql - INSERT INTO public.plantestimatedmonthlyenergy(plantparameters, "time", monthly_target_energy_kwh) VALUES -(33, '2022-01-01 00:00:00+01', 473630), -(33, '2022-02-01 00:00:00+01', 453370), -(33, '2022-03-01 00:00:00+01', 592040), -(33, '2022-04-01 00:00:00+02', 617000), -(33, '2022-05-01 00:00:00+02', 667210), -(33, '2022-06-01 00:00:00+02', 648940), -(33, '2022-07-01 00:00:00+02', 703030), -(33, '2022-08-01 00:00:00+02', 644500), -(33, '2022-09-01 00:00:00+02', 574580), -(33, '2022-10-01 00:00:00+02', 524110), -(33, '2022-11-01 00:00:00+01', 446490), -(33, '2022-12-01 00:00:00+01', 442060); +INSERT INTO + public.plantestimatedmonthlyenergy(plantparameters, "time", monthly_target_energy_kwh) +VALUES + (33, '2022-01-01 00:00:00+01', 473630), + (33, '2022-02-01 00:00:00+01', 453370), + (33, '2022-03-01 00:00:00+01', 592040), + (33, '2022-04-01 00:00:00+02', 617000), + (33, '2022-05-01 00:00:00+02', 667210), + (33, '2022-06-01 00:00:00+02', 648940), + (33, '2022-07-01 00:00:00+02', 703030), + (33, '2022-08-01 00:00:00+02', 644500), + (33, '2022-09-01 00:00:00+02', 574580), + (33, '2022-10-01 00:00:00+02', 524110), + (33, '2022-11-01 00:00:00+01', 446490), + (33, '2022-12-01 00:00:00+01', 442060); ``` si té raspberrypi: -escriure el modmap.yaml (TODO: unificar tots els modmaps a un de sol?) +- escriure el fitxer `.yaml` de la planta +- Executar l’script d’alba i posta per a generar totes les albes i postes dels propers 10 anys -Executar l’script d’alba i posta per a generar totes les albes i postes dels propers 10 anys + ```bash + python scripts/sun_events.py -p Alcolea -s 2021-12-13 -e 2021-12-14 + ``` -```bash -python scripts/sun_events.py -p Alcolea -s 2021-12-13 -e 2021-12-14 -``` +- whitelistejar la ip pública al plantmonitor per a què pugui pujar lectures +- Afegir les dades al diccionari de solargis ([Veure com aqui](#afegir-solargis)). Quan deixi de ser hard-coded ja no caldrà aquest pas. -whitelistejar la ip pública al plantmonitor per a què pugui pujar lectures +### Afegir planta al script de SolarGIS {#afegir-solargis} -Afegir les dades al diccionari de solargis (quan deixi de ser hard-coded ja no caldrà aquest pas) +S'ha de modificar el codi de plantmonitor per incloure la nova planta. Podeu trobar un exemple de modificacions [github](https://github.com/Som-Energia/plantmonitor/pull/40/commits/77aa3914905cce6d39062271085a633d8c6a1506) + +Amb la MR aprovada i fusionada, s'ha de fer `git pull` des de el servidor de producció i reiniciar el servei de plantmonitor. + +La API de SolarGIS requereix un token d'accés i es crida remotament amb `supervisord`, amb codi al repositori de [plantmonitor](https://github.com/Som-Energia/plantmonitor). + +!!! info "L'API de SolarGIS és SOAP" + + [L'API es del tipus SOAP i no REST](https://www.redhat.com/es/topics/integration/whats-the-difference-between-soap-rest). És a dir, demana un XML amb les dades de la planta. + +## Xarxa + +1. Conectar-se a la ip del router de la planta i afegir el port forwarding que calgui (raspberrypi o aparells) +2. Demanar a sistemes que afegeixi la planta al dns e.g. `planta-.somenergia.coop` + +Tot això ha de quedar escrit en el document `Mapeig de Planta` + +## Dades requerides per aparells + +### Comptador + +Agafar les dades de [Modelos contadores_inversores_SCADAS](https://docs.google.com/spreadsheets/d/1Z7_QpzestHBzVf9o78IC3hdGWMDH6dlyUr8f9LewO1o/edit#gid=904950265) + +- ip lan, port, porta d’enllaç i contrasenya +- telèfon, si s'escau + +### Inversor + +- ip + +### Raspberrypi + +- ip lan +- usuari +- password ## Serveis de SomEnergia addicionals @@ -91,19 +215,19 @@ afegir-la al nagios o modificar-la en cas de canvi d’ip pública ### opendata -Cal afegir la info de la nova planta a taula literal que es fa servir a somenergia-opendata/som_opendata/queries/plantpower.sql - -(Un cop aquesta info estigui a plantmonitor, l’opendata podrà agafar-la directament per sql i no caldrà fer aquest pas) +Cal afegir la info de la nova planta a taula literal que es fa servir a `somenergia-opendata/som_opendata/queries/plantpower.sql`. Un cop aquesta info estigui a plantmonitor, l’opendata podrà agafar-la directament per sql i no caldrà fer aquest pas. ### generationkwh Si la planta està inclosa al generation, és important afegir-la a l’erp abans de la mitja nit del dia de posada a producció. Si no, cal descartar càlculs de drets del generation per a que incloguin els resultats. Si, a més, els drets s’han començat a gastar (15 dies de marge de facturació), cal reperfilar els nous drets amb la producció afegida perquè no superi els drets ja atorgats. -La nova planta es crea fent servir l’script: somenergia-generationkwh/scripts/genkwh_plants.sh +La nova planta es crea fent servir l’script a [`somenergia-generationkwh/scripts/genkwh_plants.py`](https://github.com/Som-Energia/somenergia-generationkwh/blob/master/scripts/genkwh_plants.py) -Un exemple complert de com afegir una planta amb aquest script: +Un exemple complert de com afegir una planta amb aquest script el podeu trobar a Es recomana provar primer a un ERP de testing o local, i, després aplicar-ho a producció. +#### Reperfilació de dades + Un exemple d’script de migració en la que vam haver de reperfilar: diff --git a/mkdocs.yml b/mkdocs.yml index 022cd9e5..2f9f6662 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,10 +12,12 @@ theme: - navigation.path - navigation.indexes - navigation.top + - navigation.tracking - content.action.edit - content.action.view - content.code.copy - content.code.annotate + - toc.follow icon: edit: material/pencil view: material/eye @@ -40,6 +42,10 @@ markdown_extensions: - attr_list - admonition - pymdownx.details + - toc: + permalink: true + permalink_class: headerlink + permalink_title: Permalink - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg