Modularization, documentation, installation, configuration, and naming things

[amotl]

Dear @bee-mois,

thanks a stack for conceiving and contributing the temp-matrix_5x6.py program. We would like to give it a bit of love on the course of a few subsequent iterations.

We hope you appreciate corresponding improvements in order add robustness and flexibility. We plan to submit a few PRs including corresponding enhancements, or bundle a few items together into single PRs.

With kind regards,
Andreas.

[amotl]

Refactoring Proposals

Modularization

• Make it compatible with Paho MQTT Client version 2, when still needed. References:
  • mqttwarn does not like py39-paho-mqtt-2.0.0 mqtt-tools/mqttwarn#694
  • Remedy breaking change with 2.x: Use CallbackAPIVersion.VERSION1 as a default eclipse/paho.mqtt.python#831
• Refactoring: Improve modularization and invocation semantics: Never run code directly on the global module scope.
• Add software tests: After making the code only slightly more modular, and refactoring it to not invoke code directly on the module scope, the code can be made testable much easier.

Configuration

Improve configurability:

• 1. MQTT settings: https://github.com/hiveeyes/temp-matrix/blob/9d75e9a/temp-matrix_5x6.py#L66-L77
• 2. Sensor layout and mapping.

Installation

In the end, it would be sweet to be able to install this program using pip, no?

Naming Things

In order to make that work smoothly, it will make sense to rename the repository / program once more, to have a proper name that either conveys what's inside, like linksmith, or, alternatively, would be a nickname without making any reference to the content at all, like saraswati is doing it, or something in between, like terkin-datalogger. wdyt / do you have any ideas or suggestions in this regard?

[amotl]

About naming things, do you absolutely want to retain the matrix term within the canonical name, or would you be up for alternative suggestions? We'd suggest to use beehive-templogger, or, even more generic yet tuned to better convey "what's inside, technically", what do you think about ds18b20-datalogger?

We guess the program would be in a good neighbourhood when published to PyPI for example, see https://pypi.org/search/?q=ds18b20-datalogger.

[bee-mois]

go ahead, you are the coding guys. i appreciate it!

concerning names: i think multi or mapped (if not matrix) should be part of the name. because there are tons of ds18b20 projects out there. but all of them are about one or a few sensors. none are about 20+ in a mapped order. temp-map-logger? heatmap-logger? ds18b20-map-logger?

[amotl]

I see where you are coming from, but actually, I would expect from a good and canonical DS18B20 datalogger to be capable enough to handle multiple DS18B20 sensors. From my perspective, that the sensors are aligned in a matrix, and convey a heatmap, is just an implementation detail, while I see it is an important one.

Nevertheless, in order to support a canonical naming for future broader expansion capabilities, I would still like to suggest a short and canonical name. All other details which are inside should go prominently into the main feature list, where I totally agree that the conveyance of a 2D temperature matrix visualized as a heatmap is the main application use case for that datalogger, and should be made the core catchphrase to improve the description of the whole project.

That the name ds18b20-datalogger is not yet taken on PyPI, is actually a good thing, so we can use it, and save a few keystrokes by keeping the name as short as possible, still conveying the main details about what's inside.

Do you agree?

On the other hand, if we consider the use of the DS18B20 as "just an implementation detail", sure enough we'd approach the naming things differently, and use temperature-heatmap-datalogger or such. I don't like shortening labels like temperature to temp, and prefer using full label names.

Which one do you like better?

[bee-mois]

before we come to a decission, another thought conerning shortness of expression: isn't "datalogger" kind of pleonastic? what else would you log (especially in connection with a temperatur sensor)?
are ds18b20-logger and temperature-heatmap-logger taken on pypi?

[amotl]

Isn't "datalogger" kind of pleonastic?

Well, pleonastic or not, "datalogger" is an established term ¹.

Are [...] taken on PyPI?

So far, none of the enumerated variants are taken on PyPI yet.

Footnotes

1. https://en.wikipedia.org/wiki/Data_logger ↩

[amotl]

Logger vs. datalogger

TLDR; Logging usually refers to recording and keeping a log of events, while data logging usually refers to recording data over time or about location using sensors or instruments.

• https://pypi.org/search/?q=logger
• https://pypi.org/search/?q=datalogger

Details

"datalogger" is an established term.

Contrary to that, in computing, "logger" is closer to logging, in the sense of application logging, log file management, syslog, etc.

In computing, logging is the act of keeping a log of events that occur in a computer system, such as problems, errors or just information on current operations. These events may occur in the operating system or in other software. A message or log entry is recorded for each such event.

Evaluation

It is all about using well-established terms, for better discoverability, abstaining from NIH when possible, optimizing for DWIM instead. 🌻

[bee-mois]

ok, thanks for making me understand tech talk better.

and - naming - let's go and name it ds18b20-datalogger.
the angle of view is thereby decided by the superior criterium of shortness. (have a good night!)

[amotl]

Proposal

What	Content
Package Name	ds18b20-datalogger
Package Description	A data logger specializing in reading an array of DS18B20 sensors.
Project Description	A temperature sensor matrix with heatmap visualization for bee hive monitoring, using Raspberry Pi, Python, DS18B20, MQTT, Kotori DAQ, and Grafana.

[bee-mois]

i like it. go for it.

[amotl]

• ds18b20-datalogger is now available on PyPI. -- https://pypi.org/project/ds18b20-datalogger/
• Currently, it does not make much sense, because you still need to configure MQTT settings and sensor mappings within the code.
• Still, the "prepare packaging" step has been concluded already now, and the build & release pipelines are ready for subsequent steps.
• After improving the software tests, we may think about refactoring the code further, to have its configuration (MQTT settings and sensor mappings) separate from the implementation.
  Edit: Software tests enough to support the subsequent refactoring have been added per Tests: Make sensor tests work, using a fake sysfs filesystem #6.

[amotl]

ds18b20-datalogger 0.0.3 has been released and published on PyPI.

There is a general community heads-up note about the newly introduced configuration file.

• New configuration file using YAML #9

There is also a request for support, to validate the release version 0.0.3, including its documentation.

• Validate version 0.0.3 and its documentation #10