Wiki

Ovo je wiki za OZDS projekt.

Testiranje

Ovaj odjeljak je posvećen testiranju.

Unit testovi nisu dokumentirani na wiki jer su previše detaljni, ali neki E2E testovi koji su vitalni za projekt su dokumentirani ovdje.

Push

Prema arhitekturi, s gledišta cloud servera, postoje više točaka s kojih mogu nastati pogreške. Počevši od lokacija pa do baze podataka, možemo očekivati pogreške u ovim područjima:

• Raspberry PI -> Server: Raspberry PI je odgovoran za slanje podataka s mjerača na server. Ako Raspberry PI izgubi vezu sa serverom, server neće primati nikakve podatke. Raspberry PI također može slati netočne podatke ili ne biti ovlašten za slanje podataka.

• Server: Sam server može prestati raditi ili imati bug koji uzrokuje prestanak primanja podataka s Raspberry PI.

• Server -> Baza podataka: Server šalje podatke u bazu podataka. Ako je baza podataka nedostupna ili nema veze s bazom podataka ili postoje problemi s upitima, server neće moći pohraniti podatke.

Kvarovi

Ovdje je popis kvarova koji se mogu pojaviti u procesu push podijeljenih po područjima:

• Raspberry PI -> Server:

  • Raspberry PI ne šalje podatke
  • Raspberry PI šalje netočne podatke

• Server:

  • Server nije povezan na mrežu
  • Server baca iznimku (softverski bug)

• Server -> Baza podataka:

  • Baza podataka nije povezana na mrežu
  • Baza podataka baca iznimku (softverski bug)

Testiranje

Da bismo testirali otpornost u procesu push, možemo simulirati kvarove na sljedeće načine:

• Raspberry PI ne šalje podatke: isključite fake push skriptu i provjerite kako se server ponaša. Server ne bi trebao prestati raditi i trebao bi generirati alarm nakon nekog vremena.

• Raspberry PI šalje netočne podatke: stvorite CSV datoteke s netočnim podacima iz CSV datoteka s točnim podacima i fake push skriptom pošaljite te mjere na server. Server ne bi trebao prestati raditi i trebao bi generirati alarm.

• Server nije povezan na mrežu: isključite server i ponovo ga uključite nakon nekog vremena. Server bi trebao ponovno početi raditi, niti jedno mjerenje ne bi trebalo biti izgubljeno (fake skripta bi trebala ponovno pokušati kao i aplikacija), i alarm bi trebao biti generiran.

• Server baca iznimku: stvorite bug na serveru koji uzrokuje prestanak obrade dolaznih mjera. Server ne bi trebao prestati raditi i trebao bi generirati alarm.

• Baza podataka nije povezana na mrežu: isključite bazu podataka i ponovo je uključite nakon nekog vremena. Server bi trebao ponovno početi raditi, niti jedno mjerenje ne bi trebalo biti izgubljeno (fake skripta bi trebala ponovno pokušati kao i aplikacija), i alarm bi trebao biti generiran.

• Baza podataka baca iznimku: stvorite bug na serveru koji uzrokuje prestanak obrade dolaznih mjera u bazi podataka. Server ne bi trebao prestati raditi i trebao bi generirati alarm.

Naplata

Kao što je prikazano u workflow-u naplate, naplata je orkestrirani proces koji uključuje cloud server, bazu podataka i Altibiz ERP server. Imajući to na umu, možemo identificirati sljedeće točke kvara:

• Server -> Baza podataka: Server šalje podatke u bazu podataka. Ako je baza podataka nedostupna ili nema veze s bazom podataka ili postoje problemi s upitima, server neće moći pohraniti podatke.

• Server: Sam server može prestati raditi ili imati bug koji uzrokuje prekid komunikacije s drugim servisima.

• Server -> Altibiz ERP: Cloud server šalje podatke o naplati na Altibiz ERP server. Ako je Altibiz ERP server nedostupan ili nema veze s Altibiz ERP serverom ili postoje problemi s podacima, cloud server neće moći pohraniti odgovor. Ova točka kvara bit će proširena kada se implementira pravilna integracija s Altibiz ERP serverom.

Kvarovi

Ovdje je popis kvarova koji se mogu pojaviti u procesu naplate podijeljenih po područjima:

• Server -> Baza podataka:

  • Baza podataka nije povezana na mrežu
  • Baza podataka baca iznimku (softverski bug)

• Server:

  • Server nije povezan na mrežu
  • Server baca iznimku (softverski bug)

• Server -> Altibiz ERP:

  • Altibiz ERP server nije povezan na mrežu
  • Altibiz ERP server šalje netočne podatke
  • Altibiz ERP server baca iznimku (softverski bug)

Napomena: Svaki kvar može se pojaviti u različitim fazama procesa naplate.

Testiranje

Da bismo testirali otpornost u procesu naplate, možemo simulirati kvarove na sljedeće načine:

• Baza podataka nije povezana na mrežu: isključite bazu podataka i ponovo je uključite nakon nekog vremena. Server bi trebao ponovno početi raditi i svi podaci trebaju biti ispravno pohranjeni. Ako je neka operacija završena, server bi trebao nastaviti s tim operacijama.

• Baza podataka baca iznimku: stvorite bug na serveru koji uzrokuje prestanak obrade dolaznih upita u bazi podataka. Server ne bi trebao prestati raditi i trebao bi generirati alarm.

• Server nije povezan na mrežu: isključite server i ponovo ga uključite nakon nekog vremena. Server bi trebao ponovno početi raditi i svi podaci trebaju biti ispravno pohranjeni, a alarm bi trebao biti generiran. Ako je neka operacija završena, server bi trebao nastaviti s tim operacijama.

• Server baca iznimku: stvorite bug na serveru koji uzrokuje prestanak obrade dolaznih upita. Server ne bi trebao prestati raditi i trebao bi generirati alarm.

• Altibiz ERP server nije povezan na mrežu: isključite lažni Altibiz server i ponovo ga uključite nakon nekog vremena. Server bi trebao ponovno početi raditi i svi podaci trebaju biti ispravno pohranjeni, a alarm bi trebao biti generiran.

• Altibiz ERP server baca iznimku

Izvješća

Izvješće za prvi kvartal 2024. godine

Zahtjevi

Trenutno su podržani samo uređaji Abb B2x i Schneider iEM3xxx. Priručnici za te uređaje analizirani su kako bi se odredila strategija sučeljavanja.

Konačno rješenje uključuje korištenje Raspberry PI Model 4B nazvanog posrednik na lokaciji za čitanje podataka mjerenja s uređaja ili gatewaya. Za sada se planira koristiti jedan posrednik za svaku lokaciju, ali to se može proširiti na više uređaja po lokaciji ako je potrebno radi redundancije.

Posrednik čita podatke s uređaja koristeći Modbus TCP i šalje podatke na server putem jednostavnog REST API-ja. Server je cloud-based server koji je smješten na Azure-u.

Registri Modbusa koji se čitaju sa svakog tipa uređaja određeni su iz njihovih priručnika kao i registri potrebni za konfiguriranje trenutne tarife uređaja.

Za Abb B2x uređaje čitaju se sljedeći registri:

Za uređaje Schneider iEM3xxx koriste se sljedeći registri:

Tipovi korišteni u tablicama:

• u32 - pozitivni 32-bitni cijeli broj
• s32 - 32-bitni cijeli broj
• u64 - pozitivni 64-bitni cijeli broj
• f32 - 32-bitni realni broj

Registri aktivne i reaktivne energije koriste se za izračun podataka za naplatu. Vrhovi aktivne snage izračunavaju se preko aktivne energije. Ostali registri mjere se u svrhu praćenja i dijagnostike.

Okruženje

OZDS je ASP.NET Core web aplikacija smještena na Azure App Service. Aplikacija se povezuje s Postgresql bazom podataka s TimescaleDB ekstenzijom. Aplikacija prima dolazne podatke s Raspberry Pi 4B uređaja putem HTTP POST zahtjeva. Korisnici pristupaju aplikaciji putem web preglednika. Aplikacija se prikazuje putem Blazor SSR.

Razvoj

Alati koji se koriste za razvoj OZDS-a su:

• dotnet
• just
• docker
• node
• dvc
• git
• nushell

Kod za poslužitelj nalazi se na github-u. Kod se razvija u vscode.

Kod za Raspberry Pi 4B posrednike se nalazi na github-u. Kod za te uređaje obično se razvija spajanjem na njih preko SSH. Posrednici rade na linux distribuciji zvanoj NixOS. Razlog za to je što NixOS olakšava reprodukciju istog okruženja na svim uređajima.

Implementacija

Implementacija se vrši putem github akcija. Radni proces implementacije definiran je u .github/workflows/deploy.yml. Radni proces se pokreće prilikom git push na main. Radni proces gradi OZDS web aplikaciju i prenosi je na Azure App Service.

Arhitektura

Arhitektura OZDS je distribuirani sustav s više lokacija. Sustav se sastoji od poslužitelja koji pokreće ASP.NET Core aplikaciju, PostgreSQL baze podataka i više lokacija s brojilima. Brojila su povezani s poslužiteljem putem Raspberry Pi uređaja koji djeluje kao posrednik. Server prima podatke od brojila i pohranjuje ih u bazu podataka. Server također poslužuje web aplikaciju klijentima.

Server hostira ASP.NET Core aplikaciju, koja je podijeljena u tri glavna dijela:

• Ozds.Data: Sloj za pristup podacima
• Ozds.Client: Klijentska aplikacija
• Ozds.Business: Poslovna logika

Evo potpunog grafa implementacije za OZDS:

IOT

Uređaji Raspberry PI 4 (posrednici) sadrže Rust program koji kontinuirano čita mjerenja s mjerača, grupira ih svakim određenim intervalom i šalje ih na cloud server.

Rust program se pokreće putem Systemd servisa koji radi na NixOS-u. Servis je konfiguriran da se pokrene pri pokretanju sustava i ponovno pokrene u slučaju neuspjeha. Mjerenja se pohranjuju u lokalno instaliranu Postgresql bazu podataka s TimescaleDB ekstenzijom.

Pidgeon

Pidgeon je aplikacija bazirana na Raspberry Pi-u dizajnirana za prikupljanje i upravljanje podacima o električnom napajanju s različitih lokacija. To je ključna komponenta u mreži za distribuciju električne energije, koja omogućuje prikupljanje i prijenos podataka iz mjernih uređaja.

Ključne značajke

• Otkriće mjernih uređaja: Pidgeon automatski otkriva mjerne uređaje koje prepoznaje na mreži lokacije.
• Provjere stanja: Redoviti pingovi i provjere stanja osiguravaju ispravno funkcioniranje mjernih uređaja i samog Pidgeona.
• Prikupljanje podataka: Pozadinski procesi započinju uzimanje električnih mjerenja visoke frekvencije kako bi osigurali točne i aktualne podatke.
• Lokalno pohranjivanje: Mjerenja se pohranjuju u lokalno instaliranu PostgreSQL bazu podataka, koja služi kao buffer prije slanja podataka na poslužitelj.
• Komunikacija s poslužiteljem: Pidgeon šalje mjerenja na poslužitelj i provjerava ima li ikakvih izmjena u konfiguraciji na poslužitelju.
• Postavljanje tarifa: Pidgeon je također odgovoran za postavljanje dnevnih i noćnih tarifa mjernih uređaja.

Optimiziranjem frekvencije mjerenja, Pidgeon osigurava najtočnije i najnovije podatke. Ovi podaci su ključni za generiranje točnih informacija o naplati i pružanje vrijednih podataka za istraživanje i analizu.

Arhitektura

Arhitektura Pidgeona dizajnirana je za učinkovito prikupljanje i upravljanje podacima o električnom napajanju. Dijagram ispod pruža vizualni prikaz arhitekture sustava.

U kontekstu jedne lokacije postoje različiti tipovi brojila, kao što su Abb B2x brojilo i Schneider iEM3xxx brojilo, koji su povezani putem RS-485. Gateway, dostupan putem porta 502, služi kao posrednik za komunikaciju podataka.

Raspberry Pi pokreće Pidgeon aplikaciju, koja je podijeljena na tri glavna paketa: Konfiguracija, Usluge i Procesi.

• Konfiguracija: Ovaj paket sadrži komponentu Manager, odgovornu za upravljanje konfiguracijom aplikacije.
• Usluge: Ovaj paket sadrži nekoliko servisnih komponenti:
  • Hardware: Interagira s fizičkim hardverom Raspberry Pi-a.
  • Network: Upravljanje mrežnim komunikacijama.
  • Modbus: Upravljanje Modbus protokolom za komunikaciju s mjeriteljima.
  • Database: Upravljanje lokalnom PostgreSQL bazom podataka.
  • Cloud: Upravljanje komunikacijom s cloud serverom.
• Procesi: Ovaj paket sadrži različite procese koje Pidgeon pokreće:
  • Discovery: Otkriva brojila na mreži.
  • Ping: Redovito provjerava stanje brojila.
  • Measure: Preuzima električna mjerenja s brojila.
  • Health: Provjerava stanje Pidgeona i pohranjuje ga u lokalnu bazu podataka.
  • Push: Šalje mjerenja na cloud server.
  • Poll: Provjerava cloud server za ažuriranja konfiguracije.
  • Update: Ažurira server o stanju brojila i Raspberry PI-a.
  • Daily: Postavlja dnevnu tarifu brojila.
  • Nightly: Postavlja noćnu tarifu brojila.

Dijagram za vizualni prikaz ovih komponenti i njihovih interakcija:

Okruženje

Što se tiče razvojnog okruženja potrebno je opisati razvojne ovisnosti i razvojni proces. Ove ovisnosti su potrebne za izvršavanje naredbi definiranih u justfile koji opisuje razvojni proces pobliže.

Ovisnosti

• Rust: Projekt koristi Rust, a naredba cargo se koristi za izgradnju, testiranje i pokretanje Rust koda. Također se koristi za generiranje dokumentacije i formatiranje Rust koda.
• Docker: Docker se koristi za upravljanje uslugama o kojima aplikacija ovisi. Naredba docker compose up -d se koristi za pokretanje tih usluga, a docker compose down -v se koristi za njihovo zaustavljanje.

Opcionalni ovisnosti

Sljedeći alati su opcionalni za neke razvojne procese, ali se preporučuju za razvoj:

Probe

• Python: Python se koristi za probe skriptu. Trebate imati instaliran Python kako biste pokrenuli ovu skriptu.
• Poetry: Poetry se koristi za upravljanje Python ovisnostima.

Formatiranje

• Yapf: Yapf se koristi za formatiranje Python koda u projektu.
• Prettier: Prettier se koristi za formatiranje i provjeru formata koda u projektu.
• shfmt: shfmt se koristi za formatiranje shell skripti u projektu.

Provjera koda

• ShellCheck: ShellCheck se koristi za provjeru shell skripti.
• cspell: cspell se koristi za provjeru pravopisa u projektu.
• Ruff: Ruff se koristi za provjeru Rust koda u projektu.
• Clippy: Clippy je Rust linter koji se koristi u projektu.
• Pyright: Pyright se koristi za provjeru tipova Python koda.

Dokumentacija

• mdbook: mdbook se koristi za izradu dokumentacije u docs direktoriju.

Razvojni proces

Razvojni proces upravlja se pomoću just, upravitelja naredbama sličnog make. justfile definira različite naredbe za izgradnju, testiranje, pokretanje i upravljanje projektom.

Evo koraka za postavljanje razvojnog okruženja i korištenje just:

1. Instalirajte ovisnosti: Instalirajte sve potrebne alate navedene u ovom poglavlju.

2. Pripremite okruženje: Pokrenite just prepare za instalaciju Python ovisnosti, pokretanje Docker usluga i pokretanje migracija baze podataka.

3. Pokrenite aplikaciju: Koristite just run za pokretanje aplikacije. Možete proslijediti argumente aplikaciji dodavanjem uz naredbu, poput just run --arg.

4. Pokrenite Probe skriptu: Koristite just probe za pokretanje probe skripte. Možete proslijediti argumente skripti na isti način kao i za run naredbu.

5. Formatirajte kod: Koristite just format za formatiranje koda u projektu pomoću raznih formatera.

6. Provjerite kod: Koristite just lint za provjeru koda u projektu pomoću raznih lint alata.

7. Testirajte kod: Koristite just test za pokretanje testova za projekt.

8. Izgradite projekt: Koristite just build za izgradnju projekta. Ovo će stvoriti release build projekta i premjestiti rezultat u artifacts direktorij.

9. Generirajte dokumentaciju: Koristite just docs za generiranje dokumentacije projekta. Ovo će izgraditi dokumentaciju i premjestiti rezultat u artifacts direktorij.

Zapamtite da pokrenete just prepare svaki put kada povučete nove promjene iz repozitorija kako biste osigurali da je vaše okruženje ažurirano.

Instalacija

Instalacija Pidgeona uključuje nekoliko koraka, od kojih je svaki detaljno opisan na svojoj stranici. Evo pregleda procesa:

1. Generiranje tajni: Skripta u repozitoriju koristi sops i openssl za generiranje tajni za određeni Raspberry Pi. Ovaj korak je ključan za osiguravanje komunikacije između uređaja i poslužitelja.

2. Kreiranje ISO slike: Druga skripta u repozitoriju koristi nix build za kreiranje ISO slike za uređaj. Ova slika sadrži Pidgeon aplikaciju i sve njene ovisnosti.

3. Umetanje tajnog ključa: Tajni ključ generiran u koraku 1 umeće se u sliku pomoću skripte u repozitoriju. Tajni ključ se koristi za dešifriranje tajni generiranih u koraku 1 tijekom pokretanja.

4. Sastavljanje uređaja: ISO slika se zapisuje na 1TB SSD. SSD se zatim priključuje u USB port Raspberry Pi-a, a USB-C kabel za napajanje se priključuje.

Push

Mjerenja se šalju na server putem posredničkih uređaja preko jednostavnog REST API-ja. Krajnja točka se nalazi na /iot/push/{messengerId} i prihvaća JSON poruke s sljedećom shemom:

{
  // Vrijeme kada je zahtjev poslan
  "timestamp": "<ISO 8601 vremenska oznaka>",
  "measurements": [
    {
      // Identifikator mjerača je niz sa sljedećom shemom:
      // <proizvođač>-<model>-<serija>
      "meterId": "<meterId>",
      // Vrijeme kada je mjerenje uzeto
      "timestamp": "<ISO 8601 vremenska oznaka>",
      "data": {
        // <registri ovisno o tipu uređaja> ...
      }
    }
    // <više mjerenja> ...
  ]
}

Backend

Backend OZDS-a je ASP.NET Core web aplikacija. Podijeljena je u pakete:

• Ozds.Server: početni projekt
• Ozds.Data: sloj pristupa podacima
• Ozds.Business: poslovni sloj
• Ozds.Client: sloj korisničkog sučelja

Poslovni sloj je odgovoran za rukovanje administrativnim zadacima u web aplikaciji. Sljedeći odjeljci objašnjavaju potrebne radnje za obavljanje administrativnih zadataka.

Naplata

Naplata je proces kreacije računa korisnicima mreže i lokacijama. Trenutno je implementirana samo naplata korisnika mreže. Trenutno, operateri mogu izdati račune na zahtjev za zadnje razdoblje naplate (prošli mjesec).

Naplata je implementirana putem skupa klasa koje izračunavaju različite dijelove računa ovisno o lokacijama mjerenja i tarifama.

Frontend

Frontend OZDS-a je Blazor SSR (Server-Side Rendering) projekt baziran na OrchardCore, koji je trenutno u intenzivnom razvoju.

Do sada su implementirani osnovni izgled, navigacija, lista korisnika, lista uređaja, detaljni pregled uređaja i agregacija mjerenja.

Prijava

Na stranici za prijavu korisnici započinju svoju sesiju. Nakon prijave, korisnik je preusmjeren na stranicu prilagođenu njihovim potrebama, na temelju njihove vrste korisnika, privilegija te lokacija i mrežnih korisnika za koje su odgovorni.

/login

Admin

Ovaj odjeljak opisuje stranice koje su dostupne samo administratorima (obično programerima).

Korisnici

Na ovom sučelju mogu se mijenjati svi aspekti korisnika, mogu se stvarati novi korisnici ili brisati postojeći. Ti korisnici kasnije se povezuju s predstavnicima mrežnih korisnika i lokacija.

/admin/users

Operator

Ovaj odjeljak opisuje stranice koje su dostupne samo operatorima.

Predstavnici

Predstavnici su povezani s korisnicima OrchardCore i omogućuju nam dodavanje više podataka korisnicima. Ovi podaci mogu se pregledavati i uređivati na ovoj stranici.

/app/representatives

Mrežni korisnik

Ovaj odjeljak opisuje stranice koje su dostupne samo mrežnim korisnicima.

Nadzorna ploča

Ovdje korisnik može vidjeti agregirane podatke o mjerenju potrošnje za tekući mjesec, prethodni mjesec i grafikon potrošnje tijekom dužih razdoblja. Ispod agregiranih vrijednosti nalazi se tablica s lokacijama mjerenja koje prikazuju potrošnju pojedinačnih mjernih lokacija u tekućem i prethodnom mjesecu, te obračune ukupno u prethodnom mjesecu.

Klikom na imena lokacija, mrežnih korisnika ili mjernih lokacija, korisnici se preusmjeravaju na detaljan pregled tih entiteta. Lokacije i mrežni korisnici preusmjeravaju na pregled podataka o korisniku i privilegijama. Klik na mjerna mjesta preusmjerava na detaljan pregled pojedinačnih mjernih lokacija.

/app/dashboard

Ostalo

Ovaj odjeljak opisuje stranice koje su dostupne svim korisnicima ovisno o navigaciji i privilegijama. Drugim riječima, stranice koje nisu ograničene na specifičnu ulogu.

Mjerni uređaj

Kada se klikne na jednu od mjernih lokacija, postaju vidljivi detaljni podaci o toj mjernoj lokaciji. Prikazuju se početna i krajnja očitanja na toj mjernoj lokaciji po mjesecu, zajedno s ukupnom potrošnjom i maksimalnom snagom tijekom tog mjeseca. Grafikon s desne strane pokazuje mjerenja za posljednjih četvrt sata, pola sata, sat i šest sati, i može prikazivati vrijednosti za napon, struju, aktivnu snagu, reaktivnu snagu i prividnu snagu. Pokazivač na lijevoj strani pokazuje trenutnu snagu i uspoređuje je s priključnom snagom.

/app/meters