🔍 Detailed Insights • 📦 Installation • 🐳 Container • 🚀 Usage • 🔧 Configuration • 📄 Cite us • 🔑 License • 🫂 Contributors
Do you ever find it challenging and tricky to send sensor measurements 📏, data 📊, or GPS positions from embedded devices 📱, microcontrollers, and smartwatches to a central server? 📡 Setting up the primary data collection scripts can be a time-consuming ⏳ process, involving selecting a protocol, framework, API, and testing them out. Moreover, these scripts are often tailored for specific tasks, making them difficult to adapt to different scenarios.
But fear not! Introducing succulent 🌵, a pure Python framework that simplifies the configuration, management, collection, and preprocessing of data collected via POST requests. This framework draws inspiration from real-world data collection challenges in smart agriculture 🧠🌿, specifically plant monitoring using ESP32 devices. The main goal behind succulent is to streamline the process of configuring various data parameters and provide a range of useful functions for data transformations. By leveraging succulent, you can set up your entire data collection endpoint within minutes, freeing you from the hassle of dealing with server-side scripts. 🚀🔧
- Free software: MIT license
- Documentation:https://succulent.readthedocs.io/en/latest
- Python versions: 3.8.x, 3.9.x, 3.10.x, 3.11.x, 3.12.x, 3.13.x
- Tested OS: Windows, Ubuntu, Fedora, Alpine, Arch, macOS. However, that does not mean it does not work on others
The current version of succulent comes packed with exciting features, including, but not limited to:
- Hassle-free generation of request URLs for seamless data collection 🌐
- Effortless data retrieval from POST requests 📥
- Versatile data storage options, such as CSV, JSON, SQLite, XML, and even images 🗂️📊🖼️
- Customisable boundaries for collected data, allowing you to set minimum and maximum thresholds ⚙️
With succulent, the process of collecting, managing, and preprocessing data becomes a breeze, empowering you to focus on what truly matters—gaining valuable insights from your embedded devices, microcontrollers, and smartwatches. ⌚ So why waste precious time? ⏳ Dive into the world of succulent and unlock the true potential of your data! 💪📈
To install succulent with pip, use:
pip install succulentTo install succulent on Alpine Linux, use:
$ apk add py3-succulentTo install succulent on Arch Linux, use an AUR helper:
$ yay -Syyu python-succulentTo install succulent on Fedora, use:
$ dnf install python3-succulentCreate a docker-compose.yml file with the following content in the root directory:
version: '3.8'services:
app:
image: codeberg.org/firefly-cpp/succulent:v6ports:
- "8080:8080"volumes:
- ./run.py:/succulent-app/run.py
- ./configuration.yml:/succulent-app/configuration.ymlenvironment:
- GUNICORN_WORKERS=2Next create a configuration.yml file in the root directory. Here's an example of a configuration file:
data:
- name: 'temperature'
- name: 'humidity'
- name: 'light'results:
- enable: true
- export: truetimestamp: trueMore information regarding the configuration file and its settings can be found in the configuration section.
Then create a Python file named run.py with the following content in the root directory:
fromsucculent.apiimportSucculentAPIapi=SucculentAPI(config='configuration.yml', format='csv')
# Flask app instance, called by gunicornapp=api.appOnce you have set up the configuration file and the Python file, build the Docker image with the following command:
docker compose buildFinally, run the Docker container with the following command:
docker compose upfromsucculent.apiimportSucculentAPIapi=SucculentAPI(host='0.0.0.0', port=8080, config='configuration.yml', format='csv')
api.start()In the root directory, create a configuration.yml file and define the following:
data:
- name: # Measure namemin: # Minimum value (optional)max: # Maximum value (optional)To collect images, create a configuration.yml file in the root directory and define the following:
data:
- key: # Key in POST requestTo store data collection timestamps, define the following setting in the configuration.yml file in the root directory:
timestamp: true # false by defaultTo access the URL for data collection, send a GET request (or navigate) to http://localhost:8080/measure.
To restrict access to the collected data, define the following setting in the configuration.yml file in the root directory:
password: 'password'# Password for data accessTo store data using a password, append the password parameter to the request URL: ?password=password.
To access data via the Succulent API, define the following setting in the configuration.yml file in the root directory:
results:
- enable: true # false by defaultTo access the collected data, send a GET request (or navigate) to http://localhost:8080/data. To access password-protected data, append the password parameter to the request URL: ?password=password.
To export the data, enable the export option in the configuration file:
results:
- export: true # false by defaultTo export the data, send a GET request (or navigate) to http://localhost:8080/export. To export password-protected data, append the password parameter to the request URL: ?password=password. The data will be downloaded in the format specified in the configuration file.
Fister Jr., Iztok, and Tadej Lahovnik. Succulent. 0.4.0, doi:10.5281/zenodo.10402365.
This package is distributed under the MIT License. This license can be found online at http://www.opensource.org/licenses/MIT.
This framework is provided as-is, and there are no guarantees that it fits your purposes or that it is bug-free. Use it at your own risk!
Thanks goes to these wonderful people (emoji key):
Tadej Lahovnik 💻🐛🤔📖✅ | Ayan Das 💻 | Iztok Fister Jr. 💻🤔🧑🏫 | Oromion 🐛📦 | rhododendrom 🎨 | Zala Lahovnik 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!