diff --git a/.gitignore b/.gitignore index d34d66bc..901c79a3 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ __pycache__ db.sqlite3 media +!media/readme.md # Backup files # *.bak diff --git a/README.md b/README.md index df072d77..cec7ab17 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ - Django 4.1 - Bootstrap 5.2 - htmx 1.8.2 +- Python 3.8/3.9 ## Roadmap Have a look at our [roadmap](./docs/ROADMAP.md) to see what features we plan to work on in the short and long run. We kindly invite you to participate in [discussions](https://github.com/N5GEH/n5geh.tools.entirety/discussions) about possible features as well. @@ -114,14 +115,14 @@ See [changelog](./docs/CHANGELOG.md) for detailed overview of changes. ## Further project information - National 5G Energy Hub National 5G Energy Hub ## Acknowledgments -We gratefully acknowledge the financial support of the Federal Ministry
-for Economic Affairs and Climate Action (BMWK), promotional references +We gratefully acknowledge the financial support of the Federal Ministry
+for Economic Affairs and Climate Action (BMWK), promotional references 03EN1030B and 03ET1561B. - BMWK BMWK diff --git a/app/Entirety/.env.EXAMPLE b/app/Entirety/.env.EXAMPLE index e75be9d6..7d679015 100644 --- a/app/Entirety/.env.EXAMPLE +++ b/app/Entirety/.env.EXAMPLE @@ -41,8 +41,8 @@ OIDC_TOKEN_ROLE_FIELD=roles # FIWARE CB_URL=http://localhost:1026 -IOTA_URL="http://localhost:4041" -QL_URL="http://localhost:8668" +IOTA_URL=http://localhost:4041 +QL_URL=http://localhost:8668 # CSRF CSRF_TRUSTED_ORIGINS=[] diff --git a/app/Entirety/media/readme.md b/app/Entirety/media/readme.md new file mode 100644 index 00000000..26a2cfe3 --- /dev/null +++ b/app/Entirety/media/readme.md @@ -0,0 +1 @@ +This folder is needed for creating local development environment. diff --git a/docs/GUI_TUTORIALS.md b/docs/GUI_TUTORIALS.md new file mode 100644 index 00000000..b3a07b7b --- /dev/null +++ b/docs/GUI_TUTORIALS.md @@ -0,0 +1,51 @@ +# Entirety GUI Tutorials + +Entirety is a web-based tool developed to facilitate the work with dedicated FIWARE APIs. It is structured into different modules that are designed to interact with specific FIWARE Generic Enablers (GEs). This tutorial will guide you through the basics of the Entirety GUI and then through the usage of every module. + + +## *LOGIN* + +- You can login to the Entirety tool with you Entirety username and password. +- Based on your access rights , you can login as an `admin` or a `project_admin` or a `user`. + + 1. Admin : Admin has all the admin rights like adding of projects , assigning owners to a project and adding/removing user. + 2. Project Admin : Project admin can manage the different projects by creating new projects , assigning users and maintainers to a project and editing projects. + 3. User : Users are only allowed to edit a particular project which is assigned to them. + 4. Viewers: Viewers are only allowed to view the existing contents of a particular project. + +![Alt text](GUI_TUTORIALS/images/image.png) + + + +## *PROJECTS* + +Entirety uses the concept of projects to separate the database into independent data spaces. Each project is bound to specific "fiware-service" headers, following FIWARE's approach to [multi-tenancy](https://fiware-orion.readthedocs.io/en/latest/orion-api.html#multi-tenancy). This ensures that projects can only access and manipulate data that they created and are authorized for. +- Click on Projects on the top left corner to see the current projects. +- You can only add a new project if you have the role `project_admin` or `admin`. + +![Alt text](GUI_TUTORIALS/images/image-1.png) + +- For creating a new project , click on the + and fill in the fields with you project details like project name , project description , Fiware service and webpage url. +- You can also add a project logo by choosing a file and uploading it. +- You must assign owners for the project and select the maintainers and users + +![Alt text](GUI_TUTORIALS/images/image-2.png) + +- Once you are done saving your project , click on Project image to view your project . +- Add edit page + +![Alt text](GUI_TUTORIALS/images/image-3.png) + +- See the description of the project and also the available apps on the sidebar + +![Alt text](GUI_TUTORIALS/images/image-4.png) + + + +## *Modules* +Modules are developed to interact with FIWARE Generic Enablers (GEs). Currently, Entirety supports interaction with the following Generic Enablers: Orion, IoT Agent-JSON, and QuantumLeap. Accordingly, the Apps "Entities", "Devices", and "Notifications" are developed to communicate with these GEs. +The following pages will guide you through each module. + +1. [Entities](GUI_TUTORIALS/ENTITIES.md) +2. [Devices](GUI_TUTORIALS/DEVICES.md) +3. [Notifications](GUI_TUTORIALS/NOTIFICATIONS.md) diff --git a/docs/GUI_TUTORIALS/DEVICES.md b/docs/GUI_TUTORIALS/DEVICES.md new file mode 100644 index 00000000..9bc9c269 --- /dev/null +++ b/docs/GUI_TUTORIALS/DEVICES.md @@ -0,0 +1,44 @@ +# *DEVICES MODULE* + +The "Devices" module is developed to interact with the FIWARE Generic Enabler known as IoT Agent-JSON, which manages `devices` and `service group` and their interactions within the FIWARE platform. The basic functionalities include registration, update, and removal of devices. + +![Alt text](images/image-11.png) + +On the landing page of the "Devices" module, you can see a list of all devices that belong to the project. +By clicking on the blue + , you can add new Devices. By clicking on the red bin, you can delete a specific Device. And by clicking on the grey pen, you can edit an already existing Device. +Furthermore, you can create Batch Devices by clicking on the batch devices option. +You can choose which device to perform actions on by selecting the white selection box in the left column. + +- [Create New Device](#create-new-device) +- [Create Multiple Devices](#create-multiple-devices) +- [Delete Device](#delete-device) + +## *Create New Device* +- By clicking the blue + , you can create a new Device by filling in the Device ID, Device Name and the Device Type. + +![Alt text](images/image-12.png) + +- The new device can be linked to an Entity by specifying the Entity Name and Entity Type. +- Multiple Device Attributes can be added by filling in the Attribute Name, Attribute Type and Object ID (optional). +- You can also add multiple Device Commands for a specific Device by adding the Command Name and Command Type. + +![Alt text](images/image-13.png) + +## *Create Multiple Devices* +- This option lets you create a batch of devices. This needs to be done by adding a JSON representation describing your multiple devices along with their associated attributes and metadata. + +![Alt text](images/image-14.png) + +## *Delete Device* +- To delete a Device, you can select the desired Device and click on the *red bin*, this will open a dialog box which gives you options for deleting the device. + +![Alt text](images/image-15.png) + +- You can choose to delete the entity related to this device by clicking the select box before deleting +- Clicking the advanced setting option will open a new dialog which lets you select whether to delete the subscriptions and relationships which are associated to the device + +![Alt text](images/image-16.png) + +Back: [Entirety GUI](../GUI_TUTORIALS.md#modules) + +Further: [Notification ](NOTIFICATIONS.md) diff --git a/docs/GUI_TUTORIALS/ENTITIES.md b/docs/GUI_TUTORIALS/ENTITIES.md new file mode 100644 index 00000000..ae4d81c4 --- /dev/null +++ b/docs/GUI_TUTORIALS/ENTITIES.md @@ -0,0 +1,39 @@ +# *Entities Module* + +The Entities app is developed to interact with the Orion Context Broker (CB). +It allows users to manage entities within the CB. +Entities, in the FIWARE context, hold information in a smart solution, typically corresponding to real-world objects or abstract entities. + +![Alt text](images/image-5.png) + +Users are able to create, update, retrieve, and delete entities via the "Entities" module. By clicking on the *blue +* , you can add new entities , by clicking on the *red bin* you can delete a specific entity and by clicking on the *grey pen* you can edit an already existing entity. You can choose which entity to perform actions on by selecting the white box. + +- [Create New Entity](#create-new-entity) +- [Delete an Entity](#delete-an-entity) + + +## *Create New Entity* +- Creating a new entity : On clicking the *blue +* , you can create a new entity by filling in the *Entity ID* and the *Entity Type*. +- The ID of the entity should always be a combination of *Entity ID* and *Entity type* in the following manner: 'Type:ID' + +![Alt text](images/image-6.png) + +- You can also add in multiple entity attributes for a specific entity by adding the *Attribute Name, Attribute Type, Attribute Value (optional) and Metadata (optional)*. + +![Alt text](images/image-7.png) + +## *Delete an Entity* +- To delete an entity, you can select the desired entity and click on the *red bin*, this will open a dialog box with different options as described below. + +![Alt text](images/image-8.png) + +- Force Delete: delete an entity without deleting their associations +- Advanced selection: this option will open another dialog box which offers three options for deleting the associations of the entity which are: *1. Subscriptions 2. Relationships 3.Devices* + +![Alt text](images/image-10.png) + +- The advanced selection for deleting an entity lets you delete the subscriptions, relationships and devices that this particular entity is linked with. + +Back: [Entirety GUI](../GUI_TUTORIALS.md#modules) + +Further: [Devices](DEVICES.md) diff --git a/docs/GUI_TUTORIALS/NOTIFICATIONS.md b/docs/GUI_TUTORIALS/NOTIFICATIONS.md new file mode 100644 index 00000000..b32b25ec --- /dev/null +++ b/docs/GUI_TUTORIALS/NOTIFICATIONS.md @@ -0,0 +1,27 @@ +# *NOTIFICATIONS MODULE* + +The "Notifications" module is designed to interact with the FIWARE Generic Enabler Orion. +This module provides a user interface to manage and view NGSI-v2 `Subscriptions`, which can be used to subscribe to changes in specific entities and attributes, and then forward the data to external endpoints, such as time-series data base. + +![Alt text](images/image-17.png) + +- [Create New Subscription](#create-new-subscription) + +## *Create New Subscription* +- Creating a new Subscription: On clicking the blue + , you can create a new Subscription by filling in the `Name`, `Description`(free text to describe the subscription), `Throttling`(Minimum number of seconds that must elapse between two consecutive notifications) and `Expiries`(datetime that this subscription will expire). + +![Alt text](images/image-18.png) + +- In the `Subject` section , select the entities and fill in the entity details, you want to subscribe to. + +![Alt text](images/image-19.png) + +- In the `Notificaton` section , mention the `HTTP` or `MQTTP` endpoints where you want to recieve the notifications. +- Include the list of metadata you want to include with the notification. +- Also select the Attribute format (between `normalized` , `keyValues` or `values`, see more information [here](https://fiware-orion.readthedocs.io/en/master/orion-api.html#notification-messages) ) + +![Alt text](images/image-20.png) + +Back: [Entirety GUI](../GUI_TUTORIALS.md#modules) + +Further: [Entirety GUI](../GUI_TUTORIALS.md#modules) diff --git a/docs/GUI_TUTORIALS/images/image-1.png b/docs/GUI_TUTORIALS/images/image-1.png new file mode 100644 index 00000000..6c2140b2 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-1.png differ diff --git a/docs/GUI_TUTORIALS/images/image-10.png b/docs/GUI_TUTORIALS/images/image-10.png new file mode 100644 index 00000000..cf13ac68 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-10.png differ diff --git a/docs/GUI_TUTORIALS/images/image-11.png b/docs/GUI_TUTORIALS/images/image-11.png new file mode 100644 index 00000000..aa811bde Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-11.png differ diff --git a/docs/GUI_TUTORIALS/images/image-12.png b/docs/GUI_TUTORIALS/images/image-12.png new file mode 100644 index 00000000..5953d860 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-12.png differ diff --git a/docs/GUI_TUTORIALS/images/image-13.png b/docs/GUI_TUTORIALS/images/image-13.png new file mode 100644 index 00000000..7cfad53b Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-13.png differ diff --git a/docs/GUI_TUTORIALS/images/image-14.png b/docs/GUI_TUTORIALS/images/image-14.png new file mode 100644 index 00000000..b3110b97 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-14.png differ diff --git a/docs/GUI_TUTORIALS/images/image-15.png b/docs/GUI_TUTORIALS/images/image-15.png new file mode 100644 index 00000000..924c79a1 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-15.png differ diff --git a/docs/GUI_TUTORIALS/images/image-16.png b/docs/GUI_TUTORIALS/images/image-16.png new file mode 100644 index 00000000..184a8e23 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-16.png differ diff --git a/docs/GUI_TUTORIALS/images/image-17.png b/docs/GUI_TUTORIALS/images/image-17.png new file mode 100644 index 00000000..60aac572 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-17.png differ diff --git a/docs/GUI_TUTORIALS/images/image-18.png b/docs/GUI_TUTORIALS/images/image-18.png new file mode 100644 index 00000000..f643949e Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-18.png differ diff --git a/docs/GUI_TUTORIALS/images/image-19.png b/docs/GUI_TUTORIALS/images/image-19.png new file mode 100644 index 00000000..1513dadc Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-19.png differ diff --git a/docs/GUI_TUTORIALS/images/image-2.png b/docs/GUI_TUTORIALS/images/image-2.png new file mode 100644 index 00000000..624eedcf Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-2.png differ diff --git a/docs/GUI_TUTORIALS/images/image-20.png b/docs/GUI_TUTORIALS/images/image-20.png new file mode 100644 index 00000000..28dfce66 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-20.png differ diff --git a/docs/GUI_TUTORIALS/images/image-3.png b/docs/GUI_TUTORIALS/images/image-3.png new file mode 100644 index 00000000..cc563eb8 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-3.png differ diff --git a/docs/GUI_TUTORIALS/images/image-4.png b/docs/GUI_TUTORIALS/images/image-4.png new file mode 100644 index 00000000..984cc354 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-4.png differ diff --git a/docs/GUI_TUTORIALS/images/image-5.png b/docs/GUI_TUTORIALS/images/image-5.png new file mode 100644 index 00000000..537c5725 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-5.png differ diff --git a/docs/GUI_TUTORIALS/images/image-6.png b/docs/GUI_TUTORIALS/images/image-6.png new file mode 100644 index 00000000..4a1c8c52 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-6.png differ diff --git a/docs/GUI_TUTORIALS/images/image-7.png b/docs/GUI_TUTORIALS/images/image-7.png new file mode 100644 index 00000000..64f63d41 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-7.png differ diff --git a/docs/GUI_TUTORIALS/images/image-8.png b/docs/GUI_TUTORIALS/images/image-8.png new file mode 100644 index 00000000..fd1ebbe8 Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image-8.png differ diff --git a/docs/GUI_TUTORIALS/images/image.png b/docs/GUI_TUTORIALS/images/image.png new file mode 100644 index 00000000..df1e2dca Binary files /dev/null and b/docs/GUI_TUTORIALS/images/image.png differ