FiLiP (Fiware Library for Python) is a python software development kit (SDK) for accelerating the development of web services that use Fiware's Generic Enablers (GEs) as backend.
Why implement a client library when clients can be auto-generated from openapi documentation? A general prerequisite to do so is that the documentation is in depth and of good quality. While FIWARE generally provides openapi documentation, here are some thoughts on the challenges of auto-generating client code from these documents:
- Auto-generated code tends to become rather bulky and its quality strongly depends on the provided input data.
- Manipulating generated code can result in a big hassle for maintenance if additional features need to be integrated.
- The underlying NGSI (New Generation Service Interface) for FIWARE is a rather generic specification. Hence, generated models may also be of generic types as lists and 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 use of the library.
Since FiLiP is designed as a client library, it requires a server that provides the 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 check here for a tutorial on this. If this is not an option for you, FIWARE also provides a testing server. You can register for a testing account here.
The easiest way to install the library is via pip:
pip install -U git+git://github.com/RWTH-EBC/filip
If you want to benefit from the latest changes, use the development branch:
pip install -U git+git://github.com/RWTH-EBC/filip@development
We are still working on the documentation. You can find our current documentation here.
Once you have installed the library, you can check the examples to learn how to use the different components.
Currently, we provide basic examples for the usage of FiLiP for the FIWARE GEs mentioned above. We suggest to start with the config-example in order to understand the configuration of clients (Note: This may change in the future). Also, we provide more advanced examples for the semantic context data modeling within a context broker using relationships. Furthermore, the context broker provides a mechanism for an event-based http-notification. Using this mechanism is shown here.
NOTE: Currently, we are refactoring the library in order to provide a better validation mechanism. After this big step we will work on further examples, and on the integration of further advanced functions supporting effective context data modeling using validated data model structures.
Currently, we are working on a CI workflow for continuous testing of the library.
The following section introduces FIWARE. If you are already familiar with FIWARE, you can skip this section and go straight to Getting Started.
FIWARE is a framework of open-source cloud platform components, created to facilitate the development of smart solutions within various application domains. At the moment, the FIWARE catalogue contains over 30 interoperable 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 recommend checking the step-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 their academy.
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 are open-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 small tutorial explaining how to set up a platform suited for most use cases within the energy domain.
FiLiP is a library developed on demand. Hence, we do not aim to cover the APIs of all GEs that are included in the catalogue. 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 its reference implementation ORION for testing.
-
IoT-Agents for managing IoT Devices. IoT agents are implemented using the FIWARE IoT Agent Node Lib as a common framework.
-
IoT-Agent-JSON for managing devices using a JSON message payload protocol format.
- documentation
- github
- apiary (partly deprecated)
Example payload:
{ "humidity": "45%", "temperature": "23", "luminosity": "1570" } -
IoT-Agent-Ultralight for managing devices using an Ultralight 2.0 message payload 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 (not up to date, newest API version is 8.0)
- Thomas Storek (corresponding)
- Saira Bano
- Stephan Göbel
- Sebastian Borges
- Felix Rehmann
We presented the library in the following publications:
-
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 Platform FIWARE 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 building energy 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 the LICENSE file for details.
2021, RWTH Aachen University, E.ON Energy Research Center, Institute for Energy Efficient 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
We gratefully acknowledge the financial support of the Federal Ministry
for Economic Affairs and Energy (BMWi), promotional reference 03ET1561B.