Version support:
MICROSMARTGRID_IN_ACTION.mp4
See how Energy flows and calculate Insights.
This alpha-stage application enables admins of microsmartgrid architectures to easily deploy a distributed supervision tool. Currently supported protocol: MQTT
You need a distribution of Java 11 (e.g. OpenJDK11), Maven, Docker (for Windows and Mac you can get your desktop client here) and Docker Compose. If you plan to debug the system or setup your own database outside of the docker environment, you need TimescaleDB v1.6 which must be configured according to this shell script. Then clone this repository.
Once you installed all necessary tools and cloned this repository, navigate to the base folder and execute mvn clean build install -DskipTests.
There are different ways to use Msg-Vis. You can run all services together with docker or you can execute each service individually, either with docker or via maven.
To run all services with docker, simply build the project and execute docker-compose up --build in the base directory. All the work will be done for you.
To run individual services with maven, navigate to the service's directory and execute mvn spring-boot:run.
To run individual services with docker, first navigate into the service's directory, build the image with docker build -t <serviceTag> . and then run it with docker run -p <ext-port>:<int-port> <serviceTag>.
All services which other services depend on are exposing spring actuator endpoints (e.g. actuator/health) by default (see docs).
Listed dependencies are transitive.
Provides all necessary configuration for each service. Has to always start as first service and gets called by each service on startup.
Port: 8888
Relies on: None
Endpoints: None
Service discovery. Provides a graphical overview page on /.
Port: 8761
Relies on: Config Server
Endpoints: None
Reads and aggregates data from the database.
Port: 4720
Relies on: Eureka Server, Timescale DB
Endpoints:
| Method | Path | Variables | Description |
|---|---|---|---|
| GET | /latest | DTF* Cutoff | Queries the database for the last reading within <cutoff> days from each device. |
| GET | /readings | int id, DTF*/Duration** since, DTF*/Duration** until | Queries the database for all readings within an interval. |
| GET | /readings/avg | int id, DTF*/Duration** since, DTF*/Duration** until, Duration step | Queries the database for all readings or only readings with 'id'. The interval is defined using 'since' and 'until' with either a timestamp (UTC) or a duration (last seven days and one hour "P7DT1H"). Readings will be aggregated over 'step' and the average is returned. |
| GET | /readings/min | see above | (see above) returns the minimum from readings over 'step'. |
| GET | /readings/max | see above | (see above) returns the maximum from readings over 'step'. |
| GET | /readings/std | see above | (see above) returns the standard deviation from readings over 'step'. |
| GET | /deviceList | - | Queries a list of all registered devices. |
| GET | /deviceById | int id | Query devices table by id. |
| GET | /deviceByName | String name | Queries devices table by name. |
*DTF refers to datetime-format
**Duration uses DTFs Durations, however only the time portion. "P1D" is supported but will resolve to "PT24H".
Writes data to the database.
Port: 4721
Relies on: Eureka Server, Timescale DB
Endpoints:
| Method | Path | Variables | Description |
|---|---|---|---|
| PUT | /device | Deviceinformation*** deviceInfo | Save or update DeviceInformation to a Device. |
| POST | /reading | String name, String json | Deserialize the json to a java object and assign it to a DeviceInformation object. Save the created object to the database. |
*** see database model
Graphical Frontend. Written mainly with D3. The topology can be passed as a json (see here) and has to match the database.
Port: 8080
Relies on: Timescale DB Reader
Endpoints: None
Is able to subscribe to MQTT brokers. Config must be done in-code.
Port: 1883
Relies on: Timescale DB Writer
Endpoints: None
To uninstall Msg-Vis and all its dependencies you should delete the whole base directory, then clean your .m2 and docker images/containers. Finally, you should uninstall all services named in the beginning.
To deploy Msg-Vis via docker to docker swarm or kubernetes just follow the usual steps for deploying a spring cloud application with Eureka. Remember to change the host of all services from localhost to dynamic, auto-detectable docker-compose network-addresses (see docs) and to set the ports to 0 to allow dynamic port allocation.
To deploy single Msg-Vis services to single tomcat instances, change <packaging>jar</packaging> to <packaging>war</packagin> in every pom.xml file which applies. Additionally, navigate into the <ServiceName>Application.java usually located at <servicename>/src/main/java/com/microsmartgrid/<servicename> and extend the main class with extends SpringBootServletInitializer. Then clean-build the project and drop the resulting .war-file into your tomcat's webapps folder.
To deploy all Msg-Vis services to one single tomcat instance, refer to this dedicated branch and execute the install.sh as root. It will clean-build the project and auto-configure your tomcat instance. Be sure to have an appropriate instance of timescaleDb already running. The build depends on it.
Note however, this does only work on an Ubuntu distribution.
There are two tables: devices and readings.
Intuitively devices stores all known devices. The ids should match the ids in the topology JSON file so the view service can query the database correctly.
Readings stores all readings. The device id matches the id in devices.