Repository files navigation

FiLiP (FIWARELibrary forPython) is a python Software Development Kit (SDK) foraccelerating the development of web services that use Fiware's GenericEnablers (GEs) as backend.

It is mainly based on thePydanticpackage which is a sophisticated library for data validation and settingsmanagement using python type annotations.Pydantic enforces type hints at runtime, and provides user friendly errorswhen data is invalid.We mainly use the Pydantic model to build our own data model structure requiredfor efficient data model parsing and validation and interaction with FIWAREservices' RestAPIs.

For API interaction, FiLiP relies on the well-knownrequests package.It is important to understand that we do not in any way restrict anyfeatures of requests.

Furthermore, FiLiP is designed to help with the fast development of FIWARE-basedapplications and avoid hundreds of lines of boilerplate, but it cannotsubstitute learning the basic concepts behind the used FIWARE components.

This project is part ofFIWARE. For more information check the FIWARE Catalogue entry for theCore Context Management.

Why implement a client library when clients can be auto-generatedfrom openapi documentation?A general prerequisite to do so is that the documentation is in depth and ofgood quality.While FIWARE generally providesopenapi documentation,here are some thoughts on the challenges of auto-generating client code fromthese documents:

• Auto-generated code tends to become rather bulky and its quality stronglydepends on the provided input data.
• Manipulating generated code can result in a big hassle for maintenance ifadditional features need to be integrated.
• The underlying NGSI (Next Generation Service Interface) for FIWARE is arather generic specification.Hence, generated models may also be of generic types as listsand dicts in Python. So there is no real benefit.Furthermore, there is no chance for reasonable validation and error handling.

The following section shortly describes how to use the library.

Since FiLiP is designed as a client library, it requires a server that providesthe target Service-APIs.Hence, if you do not yet have a running instance of a FIWARE based platform,using docker is the most convenient way to set it up.Please checkhere for a tutorialon this.If this is not an option for you, FIWARE also provides a testing server.You can register for a testing accounthere.

Note: FiLiP is now compatible toPydantic V2. If your program still require Pydantic V1.x for some reason, please use releasev0.2.5 or earlier version of FiLiP. Besides, we recommended to setpydantic~=1.10 in therequirements.txt, otherwise Pydantic V2 might still be installed.

✅ Tested python versions have passed the unittests

The easiest way to install the library is via pip:

pip install -U filip

If you want to benefit from the latest changes, use the following command(This will install the current master branch from this repository):

pip install -U git+git://github.com/RWTH-EBC/filip

Note: For development, you should install FiLiP in editable mode with the following command:

pip install -e .[development]

Thedevelopment option will install extra libraries required for contribution. Please check theCONTRIBUTING.md for more information.

If you need to go through the tutorials or examples, please install filip with extra moduletutorials:

pip install -U filip[tutorials]

If you want to use the optionalsemantics module, use the following command. This will install the libraries (e.g.,igraph andrdflib) that only required for the semantics module):

pip install -U filip[semantics]

The following section introduces FIWARE. If you are already familiar withFIWARE, you can skip this section and go straight toGetting Started.

FIWARE is a framework of open-source cloud platform components, createdto facilitate the development of smart solutions within various applicationdomains.At the moment, the FIWAREcatalogue contains over 30interoperable software modules, so-called Generic Enablers(GE) for developing and providing customized IoT platform solutions.

To get familiar with the APIs of the different modules we highly recommendchecking thestep-by-step tutorial.It provides a good overview on FIWARE and its basic usage.Whereas the tutorial helps to understand most of the general concepts,for a deep dive, where you can learn about the components in more detail,FIWARE also offers extended lessons through theiracademy.

However, usually one only requires a small set of components.Hence, we recommend using the cited pages only as needed.

The easiest way to set up a FIWARE platform is by using docker as all GEs areopen-source and distributed as docker containers on dockerhub.

However, as mentioned before, for most use cases only a subset of GEs is required.Hence, we wrote a smalltutorialexplaining how to set up a platform suited for most use cases within the energydomain.

FiLiP is a library developed on demand.Hence, we do not aim to cover the APIs of all GEs that are included in thecatalogue.This would mean an unnecessary development overhead.Therefore, FiLiP currently only covers the APIs of the following GEs:

• NGSIv2 Context Broker for managing context data. We use itsreference implementation ORION for testing. There is also warning in Filip if you are using an old version of ORION which could have breaking changes.

  • documentation
  • github
  • swagger
  • NGSI v2 specifications

• NGSI-LD Context Broker for managing context data with Linked Data concept. The functionalities that FiLiP supports are closely aligned with the specificationNGSI-LD V1.3.1, which is according to the FIWAREcatalogue the latest spec version that has been implemented by all three brokers (Orion-LD, Scorpio, and Stellio). We currently use Orion-LD for testing.

  • github
  • swagger

  Note:-experimental flag need to be set for Orion-LD Context Broker to enable the full functionality. Check thisissue for more information

• IoT-Agents for managing IoT Devices. IoT agents are implemented usingthe FIWARE IoT Agent Node Lib as a common framework.

  • documentation
  • github

• IoT-Agent-JSON for managing devices using a JSON message payload protocolformat.

  • documentation
  • github
  • apiary(partly deprecated)

  Example payload:

    {      "humidity": "45%",      "temperature": "23",      "luminosity": "1570"  }

• IoT-Agent-Ultralight for managing devices using an Ultralight 2.0 messagepayload protocol.

  • documentation
  • github
  • apiary(partly deprecated)

  Example payload:

    humidity|45%|temperature|23|luminosity|1570

• QuantumLeap for the management of time series data

  • documentation
  • github
  • swagger

We are still working on the documentation.You can find our current documentationhere.

Once you have installed the library, you can check theexamplesto learn how to use the different components.

Currently, we provide basic examples for the usage of FiLiP for the FIWAREGEs mentioned above.We suggest to start in the right order to first understand theconfiguration of clients.Afterwards, you can start modelling context data and interacting with the contextbroker and use its functionalities before you learn how to connectIoT Devices and store historic data.

We use unittests to write our test cases.To test the source code of the library in our CI workflow, the CIexecutes all tests located in thetests-directory and prefixed withtest_ .

The best way to report a bug or request a new feature is to open an issue. Please use one of the available issue templates and provide as much detail as possible.

We warmly welcome code contributions! If you're planning to contribute, please first read ourContribution Guide for details on our development workflow, coding standards, and how to submit a pull request.

For other inquiries, you can still contact us viaebc-tools@eonerc.rwth-aachen.de.

• Thomas Storek
• Junsong Du (corresponding)
• Saira Bano

• Jeff Reding
• Felix Rehmann
• Daniel Nikolay
• Sebastian Blechmann

If you use FiLiP in your work, please cite the JOSS paper:

@article{Storek2024,doi ={10.21105/joss.06953},url ={https://doi.org/10.21105/joss.06953},year ={2024},publisher ={The Open Journal},volume ={9},number ={101},pages ={6953},author ={Storek, Thomas and Du, Junsong and Blechmann, Sebastian and Streblow, Rita and Müller, Dirk},title ={FiLiP: A python software development kit (SDK) for accelerating the development of services based on FIWARE IoT platform},journal ={Journal of Open Source Software}}

We also want to refer to publications that presented or applied the library:

• S. Blechmann, I. Sowa, M. H. Schraven, R. Streblow, D. Müller & A. Monti. Open source platform application for smart building and smart grid controls. Automation in Construction 145 (2023), 104622. ISSN: 0926-5805.https://doi.org/10.1016/j.autcon.2022.104622

• Haghgoo, M., Dognini, A., Storek, T., Plamanescu, R, Rahe, U.,Gheorghe, S, Albu, M., Monti, A., Müller, D. (2021) A cloud-based service-oriented architecture to unlock smart energy serviceshttps://www.doi.org/10.1186/s42162-021-00143-x

• Baranski, M., Storek, T. P. B., Kümpel, A., Blechmann, S., Streblow, R.,Müller, D. et al.,(2020). National 5G Energy Hub : Application of the Open-Source Cloud PlatformFIWARE for Future Energy Management Systems.https://doi.org/10.18154/RWTH-2020-07876

• T. Storek, J. Lohmöller, A. Kümpel, M. Baranski & D. Müller (2019).Application of the open-source cloud platform FIWARE for future buildingenergy management systems.Journal of Physics:Conference Series, 1343, 12063.https://doi.org/10.1088/1742-6596/1343/1/012063

This project is licensed under the BSD License - see theLICENSE file for details.

2021-2025, RWTH Aachen University, E.ON Energy Research Center, Institute for EnergyEfficient Buildings and Indoor Climate

Institute for Energy Efficient Buildings and Indoor Climate (EBC)
E.ON Energy Research Center (E.ON ERC)
RWTH University Aachen, Germany

This project is part of the cooperation between the RWTH Aachen University andthe Research Centre Jülich.

We gratefully acknowledge the financial support of the Federal Ministry
for Economic Affairs and Climate Action (BMWK), promotional references03ET1495A, 03ET1551A, 0350018A, 03ET1561B, 03EN1030B.

This project has received funding in the framework of the joint programming initiative ERA-Net Smart Grids Plus, with support from the European Union’s Horizon 2020 research and innovation programme.