docs: Add manuscript

.github/workflows/publication.yml

@@ -0,0 +1,23 @@
+name: Publication
+on:
+  push:
+    paths:
+      - publication/**
+      - .github/workflows/publication.yml
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Build PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          paper-path: publication/paper.md
+      - name: Upload artifact
+        uses: actions/upload-artifact@v1
+        with:
+          name: paper
+          path: publication/paper.pdf

publication/paper.bib

@@ -0,0 +1,201 @@
+@article{dietrich2021muccnet,
+  title={MUCCnet: Munich urban carbon column network},
+  author={Dietrich, Florian and Chen, Jia and Voggenreiter, Benno and Aigner, Patrick and Nachtigall, Nico and Reger, Bj{\"o}rn},
+  journal={Atmospheric Measurement Techniques},
+  volume={14},
+  number={2},
+  pages={1111--1126},
+  year={2021},
+  publisher={Copernicus GmbH}
+}
+@proceedings{midcost,
+  title={Advancing Urban Greenhouse Gas Monitoring: Development and Evaluation of a High-Density CO2 Sensor Network in Munich},
+  author={Aigner, Patrick and K{\"u}bacher, Daniel and Wenzel, Adrian and Schmitt, Adrian and B{\"o}hm, Felix and Makowski, Moritz and Angleitner, Moritz and K{\"u}rzinger, Klaus and Laurent, Olivier and Rubli, Pascal and Grange, Stuart and Emmenegger, Lukas and Chen, Jia},
+  booktitle={ICOS Science Conference},
+  year={2024},
+}
+@article{muller2020integration,
+  title={Integration and calibration of non-dispersive infrared (NDIR) CO\textsubscript{2} low-cost sensors and their operation in a sensor network covering Switzerland},
+  author={M{\"u}ller, Michael and Graf, Peter and Meyer, Jonas and Pentina, Anastasia and Brunner, Dominik and Perez-Cruz, Fernando and H{\"u}glin, Christoph and Emmenegger, Lukas},
+  journal={Atmospheric Measurement Techniques},
+  volume={13},
+  number={7},
+  pages={3815--3834},
+  year={2020},
+  publisher={Copernicus GmbH}
+}
+@article{zweifel2021trees,
+  title={Why trees grow at night},
+  author={Zweifel, Roman and Sterck, Frank and Braun, Sabine and Buchmann, Nina and Eugster, Werner and Gessler, Arthur and H{\"a}ni, Matthias and Peters, Richard L and Walthert, Lorenz and Wilhelm, Micah and others},
+  journal={New Phytologist},
+  volume={231},
+  number={6},
+  pages={2174--2185},
+  year={2021},
+  publisher={Wiley Online Library}
+}
+@inproceedings{zhang2004hardware,
+  title={Hardware design experiences in ZebraNet},
+  author={Zhang, Pei and Sadler, Christopher M and Lyon, Stephen A and Martonosi, Margaret},
+  booktitle={Proceedings of the 2nd international conference on Embedded networked sensor systems},
+  pages={227--238},
+  year={2004}
+}
+@article{werner2006deploying,
+  title={Deploying a wireless sensor network on an active volcano},
+  author={Werner-Allen, Geoffrey and Lorincz, Konrad and Ruiz, Mario and Marcillo, Omar and Johnson, Jeff and Lees, Jonathan and Welsh, Matt},
+  journal={IEEE internet computing},
+  volume={10},
+  number={2},
+  pages={18--25},
+  year={2006},
+  publisher={IEEE}
+}
+@inproceedings{wenzel2021stand,
+  title={Stand-alone low-cost sensor network in the inner city of Munich for modeling urban air pollutants},
+  author={Wenzel, Adrian and Chen, Jia and Dietrich, Florian and Thekkekara, Sebastian T and Zollitsch, Daniel and Voggenreiter, Benno and Setili, Luca and Wenig, Mark and Keutsch, Frank N},
+  booktitle={EGU General Assembly Conference Abstracts},
+  pages={EGU21--15182},
+  year={2021}
+}
+@software{frost,
+  title = {FROST Server},
+  author = {van der Schaaf, Hylke},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/FraunhoferIOSB/FROST-Server},
+  version = {2.3.1},
+  date = {2024-03-08},
+}
+@software{polars,
+  title = {polars},
+  author = {Ritchie Vink},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/pola-rs/polars},
+  version = {0.20.17},
+  date = {2024-03-28}
+}
+@software{grafana,
+  title = {Grafana},
+  author = {Torkel {\"O}degaard},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/grafana/grafana},
+  version = {10.4.1},
+  date = {2024-03-21}
+}
+@software{timescale,
+  title = {TimescaleDB},
+  author = {{Timescale}},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/timescale/timescaledb},
+  version = {2.14.2},
+  date = {2024-02-20}
+}
+@software{thingsboard,
+  title = {ThingsBoard},
+  author = {{ThingsBoard}},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/thingsboard/thingsboard},
+  version = {3.6.3},
+  date = {2024-03-18}
+}
+@software{thingspeak,
+  title = {ThingSpeak},
+  author = {Lee Lawlor},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/iobridge/thingspeak},
+  year = {2011}
+}
+@software{pahoj,
+  title = {paho.mqtt.java},
+  author = {{Eclipse Foundation}},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/eclipse/paho.mqtt.java},
+  version = {1.2.5},
+  date = {2020-07-15}
+}
+@software{pahoc,
+  title = {paho.mqtt.c},
+  author = {{Eclipse Foundation}},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/eclipse/paho.mqtt.c},
+  version = {1.3.13},
+  date = {2023-10-19}
+}
+@software{pahop,
+  title = {paho.mqtt.python},
+  author = {{Eclipse Foundation}},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/eclipse/paho.mqtt.python},
+  version = {2.0.0},
+  date = {2024-02-10}
+}
+@software{mqttjs,
+  title = {MQTT.js},
+  author = {Adam Rudd},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/mqttjs/MQTT.js},
+  version = {5.5.3},
+  date = {2024-04-19}
+}
+@software{postgres,
+  title = {PostgreSQL},
+  author = {{PostgreSQL Global Development Group}},
+  journal = {GitHub repository},
+  publisher = {GitHub},
+  url = {https://github.com/postgres/postgres},
+  version = {16.2.0},
+  date = {2024-02-08}
+}
+@article{bart2014high,
+  title={High density ozone monitoring using gas sensitive semi-conductor sensors in the Lower Fraser Valley, British Columbia},
+  author={Bart, Mark and Williams, David E and Ainslie, Bruce and McKendry, Ian and Salmond, Jennifer and Grange, Stuart K and Alavi-Shoshtari, Maryam and Steyn, Douw and Henshaw, Geoff S},
+  journal={Environmental science \& technology},
+  volume={48},
+  number={7},
+  pages={3970--3977},
+  year={2014},
+  publisher={ACS Publications}
+}
+@inproceedings{tolle2005design,
+  title={Design of an application-cooperative management system for wireless sensor networks},
+  author={Tolle, Gilman and Culler, David},
+  booktitle={Proceeedings of the Second European Workshop on Wireless Sensor Networks, 2005.},
+  pages={121--132},
+  year={2005},
+  organization={IEEE}
+}
+@article{burri2019did,
+  title={How did Swiss forest trees respond to the hot summer 2015?},
+  author={Burri, Susanne and Haeler, Elena and Eugster, Werner and Haeni, Matthias and Etzold, Sophia and Walthert, Lorenz and Braun, Sabine and Zweifel, Roman},
+  journal={Die Erde},
+  volume={150},
+  number={4},
+  pages={214--229},
+  year={2019},
+  publisher={Gesellschaft f{\"u}r Erdkunde zu Berlin}
+}
+@article{tavakolizadeh2021thing,
+  title={Thing Directory: Simple and lightweight registry of IoT device metadata},
+  author={Tavakolizadeh, Farshid and Devasya, Shreekantha},
+  journal={Journal of Open Source Software},
+  volume={6},
+  number={60},
+  pages={3075},
+  year={2021}
+}
+@software{ivy,
+  title = {Ivy},
+  author = {Makowski, Moritz},
+  version = {0.1.0},
+  year = {2024}
+}

publication/paper.md

@@ -0,0 +1,103 @@
+---
+title: "Tenta: Remote and Real-Time Sensor Network Management"
+tags:
+  - Internet of Things
+  - IoT
+  - TimescaleDB
+  - MQTT
+  - Sensor network
+  - Wireless sensor network
+  - Monitoring
+  - REST
+  - Python
+  - PostgreSQL
+  - Sensor management
+  - Real-time
+  - Measurement
+  - HTTP
+  - Aggregation
+  - Sensor
+  - Reproducible research
+  - WSN
+  - Geospatial data
+  - AsyncIO
+  - SQL
+  - Automation
+  - Time series data
+  - Publish-Subscribe
+  - Pub/Sub
+  - Remote sensing
+  - Environmental sensing
+  - Server
+  - Configuration
+authors:
+  - name: Felix Böhm
+    orcid: 0009-0002-2179-9934
+    corresponding: true
+    affiliation: 1
+  - name: Moritz Makowski
+    orcid: 0000-0002-2948-2993
+    affiliation: 1
+  - name: Patrick Aigner
+    orcid: 0000-0002-1530-415X
+    affiliation: 1
+  - name: Jia Chen
+    orcid: 0000-0002-6350-6610
+    corresponding: true
+    affiliation: 1
+affiliations:
+  - name: Professorship of Environmental Sensing and Modeling, Technical University of Munich (TUM), Munich, Germany
+    index: 1
+date: 25 March 2024
+bibliography: paper.bib
+---
+
+# Summary
+
+In many domains, sensor networks have become indispensable to drive effective decisions: They monitor greenhouse gases and air pollutants [@dietrich2021muccnet; @wenzel2021stand], record volcanic activity [@werner2006deploying], and track animal migrations [@zhang2004hardware]. However, when these networks are more than a few sensors in scale and/or their locations difficult to access, manual inspection of sensors to retrieve their data and check their status gets prohibitively time-intensive. Simultaneously, scale renders the occurrence of sensor failures practically unavoidable. Failures that stay undetected lead to data loss [@bart2014high; @tolle2005design] and skewed results, and thus, potentially, to erroneous conclusions.
+
+Tenta is a lightweight server application to manage sensor networks remotely and in real-time. The system receives and stores measurements transmitted by sensors and allows users to monitor sensors via an intuitive dashboard. Additionally, Tenta uses versionized configurations to adapt sensors to changes in requirements. Configurations are schemaless JSON documents that represent a sensor's state. They allow requests to sensors e.g. to update their measurement interval or even their software, as for instance implemented in Ivy [@ivy]. Tenta associates each measurement with the sensor's currently active configuration, which results in highly reproducible datasets. Sensors communicate with Tenta over the widely adopted MQTT protocol. The system exposes a REST API for straightforward task automation. Data is stored in a time series-optimized PostgreSQL+TimescaleDB [@postgres; @timescale] database.
+
+\begin{figure}
+\makebox[\textwidth][c]{\includegraphics[width=1.025\textwidth]{images/architecture.png}}%
+\caption{Tenta communicates with sensors via the MQTT protocol and exposes an intuitive dashboard and a REST API to manage them remotely. The time series-optimized database can be accessed directly to allow for elaborate processing and visualization e.g. with Polars or Grafana.}
+\label{fig:architecture}
+\end{figure}
+
+Starting in 2022, our research group deployed a network of 20 mid-precision CO2 sensors on rooftops in and around Munich [@midcost]. To date, Tenta has reliably processed half a billion of this network's measurements as well as hundreds of configuration updates. Tenta's test suite currently stands at a statement coverage of 94%.
+
+# Statement of need
+
+The IoT space is dominated by proprietary services e.g. from Amazon and Microsoft Azure. These platforms offer a holistic suite of message brokers, monitoring, device management, data storage, and analytics. Several research projects [@muller2020integration; @zweifel2021trees; @burri2019did] use the sensors and infrastructure of the Swiss company Decentlab. Measurements are transmitted via LoRaWAN to gateways that relay them to Decentlab's infrastructure over the Internet. Other projects [@werner2006deploying; @zhang2004hardware] implement custom solutions e.g. based on flooding protocols. Smaller networks sometimes forgo connectivity entirely and instead rely on physical visits to the sites.
+
+ThingsBoard [@thingsboard] is an IoT platform to collect and visualize data and configure sensors via remote procedure calls. Multiple communication protocols are supported, including HTTP, MQTT, and CoAP. Furthermore, ThingsBoard allows data manipulation via so-called rule chains. A subset of ThingsBoard's functionality is available under an open-source license. Other open-source projects communicate only unidirectionally — from sensor to server — without the possibility of managing devices remotely: ThingSpeak [@thingspeak] provides an HTTP API to store and retrieve data from IoT devices. Users can analyze and visualize data via the integrated MATLAB environment. The FROST Server [@frost] implements the OGC SensorThings API and provides both HTTP and MQTT interfaces to collect and query IoT data. ThingDirectory [@tavakolizadeh2021thing] allows storing and querying IoT metadata (e.g. location, measurement type) via its REST API.
+
+# System design
+
+Tenta follows the Unix philosophy and aims to be fast, flexible, and scalable. The project focuses on real-time sensor management and reliable data collection and storage. Tenta provides seamless interfaces, such that related tasks like data processing and custom visualizations can be accomplished with the array of great existing tools e.g. Polars [@polars] or Grafana [@grafana]. Each of Tenta's features is designed to be optional. This makes it easy to connect the first sensor and allows Tenta to be used solely as a data sink for measurements on the one extreme or solely as a management system on the other. \autoref{fig:screenshot} shows Tenta's dashboard with real-time charts of collected measurements.
+
+\begin{figure}
+\makebox[\textwidth][c]{\includegraphics[width=1.093\textwidth]{images/screenshot.png}}%
+\caption{Tenta's dashboard shows real-time charts of collected measurements, here with data from our research group's CO2 sensor network. Users can furthermore manage configurations and inspect measurements, logs, and status metrics via the dashboard.}
+\label{fig:screenshot}
+\end{figure}
+
+Tenta imposes minimal restrictions on measurements and configurations. Their format can differ between sensors and can change over time without needing to notify the server beforehand, which allows Tenta to support sensor networks of almost arbitrary structure and simplifies software and hardware migrations on the sensor side. Individual sensors can even operate multiple different measurement formats at the same time. Despite this flexibility, Tenta persists measurements in a relational way, which keeps further processing straightforward.
+
+\begin{figure}
+\makebox[\textwidth][c]{\includegraphics[width=1.025\textwidth]{images/configurations.png}}%
+\caption{When a new configuration is created, it is assigned a unique identifier and relayed to the sensor over MQTT. The sensor positively or negatively acknowledges the configuration and can subsequently associate outgoing messages (e.g. measurements) with that identifier.}
+\label{fig:configurations}
+\end{figure}
+
+Configurations are schemaless JSON documents that represent sensor state. \autoref{fig:configurations} shows how Tenta assigns each configuration an incremental revision number before relaying it to the sensor. To increase observability, configurations are positively or negatively acknowledged. Subsequently, sensors can associate their outgoing messages (e.g. measurements) with the revision number of the relevant configuration.
+
+Sensors communicate with Tenta over the widely adopted MQTT protocol. MQTT is designed for resource-constrained devices and consumes little bandwidth, which is vital for sensors connected via the mobile network. Client libraries are available in most programming languages, which maximizes flexibility with regard to sensor software and hardware.
+
+Tenta leverages concurrency to achieve high throughput. Database and HTTP requests as well as MQTT message sending and receiving execute asynchronously. Tenta supports multiple sensor networks on a single instance as well as multiple users with different permissions.
+
+# Author contributions
+
+FB: Designed and developed the software, wrote the tests, wrote the documentation, wrote the manuscript; MM: Developed the software running on the sensors, developed the dashboard, reviewed the manuscript; PA: Supervised the project, extracted the requirements, reviewed the manuscript; JC: Principle investigator, supervised the project, reviewed the manuscript;
+
+# References