📘 OWLogger Documentation

🔍 What Is OWLogger?

OWLogger is your window into the hidden corners of your world — whether it's your attic, server rack, fermentation cellar, or chicken coop. It gives you real-time insights from 1-Wire sensors, without the complexity or security risks of traditional remote monitoring systems.

❗ The Problem with Conventional Monitoring

Modern remote monitoring often comes with serious drawbacks:

• 🔓 Digital Doorways: Inbound connections expose your network to security vulnerabilities.
• 📉 Flaky Connections: Spotty internet means gaps in your data — especially when you need it most.
• 🔄 Dynamic IPs: Your IP address can change unexpectedly, often during outages.
• 🕸️ Sensor Sprawl: Managing dozens of devices individually is a logistical nightmare.
• 📱 Untrustworthy Apps: Phone apps can be spoofed, and you never know what else they’re doing.
• 🔒 Vendor Lock-In: Proprietary systems can be abandoned or become expensive over time.

🚀 The OWLogger Solution

Forget complex network setups and risky configurations. OWLogger offers a secure, one-way data flow to a cloud server you control — giving you reliable, consolidated insights without compromising your privacy.

🌐 Key Benefits

• 🧠 You’re in Control: All devices and data are fully under your management.
• 💸 Low Cost: Even the cloud server is affordable — e.g., Kamatera offers VPS hosting from just $4/month.
• 🖥️ Virtual Private Server (VPS): Full access to a virtual cloud computer for storage, web access, and services like OWLogger or even a web store.
• 🌍 Pure Web Access: View your data from any browser — phone, tablet, computer, even a smart TV. No apps or installations required.

🧩 The Core Components

• Robust 1-Wire Sensors: Proven, reliable sensors with decades of continuous use.
• Pint-Sized Transmitter: A small device (like a Raspberry Pi) collects and forwards data securely.
• OWLogger Software: Open-source, customizable, and designed for simplicity and security.

🛡️ Why OWLogger?

OWLogger ensures a secure, outbound-only data flow to your cloud server. That means:

• No open ports
• No inbound connections
• No exposure to external threats

Just clean, reliable data — wherever and whenever you need it.

🛠️ Can you add on?

• owgeneralpost lets you send any information to the logger, not just 1-wire data
• Your data is stored in an sqlite3 file, so very readable and accessible
• The web display is simple HTML -- easily cutomizable
• All the programs are open source, well documented and in widely known python3

USE CASE

Basic premise

• Internal sensor readings to be monitored
• Internal network should not allow incoming access. Why?
  • Dynamic IP addresses are not a problem
  • Better security
  • Comply with facility policy
• An external server is available
• Simple web viewing from any device

Some monitoring scenarios:

• Aquarium
• Beer brewing
• Wine cellar
• Pipes freezing
• Chicken coop

Types of data

1-wire sensors

owpost is designed specifically for 1-wire temperature and humidity

Other logging

generalpost posted any arbitray text string to the logging database

Display

Reqirements

OWLOGGER

owlogger install

Debian / Ubuntu system

Basic system:

# use "sudo" for each line unless you are root
sudo apt update
sudo apt upgrade
sudo apt install git python3 python3-jwt

get owlogger software

git clone https://github.com/alfille/owlogger

Choose either Recommended (secure) or Basic (testing, insecure)

Recommended secure setup

sudo apt install python3-jwt caddy ufw
cd owlogger/logger
sudo . /logger_install.sh

Insecure basic setup

cd owlogger/logger
sudo . /logger_basic.sh

owlogger setup

owlogger usage

OWPOST

owpost install

owpost setup

owpost usage

ADVANCED

Database

Logged messages are stored in a database on the owlogger server in SQL format. The implementation is very simple.

Does it matter?

Knowing the actualy database internals is not required for using owlogger effectively. This information may be useful for:

• developing add-on functionality to the system
• doing more advanced data manipulation of analysis

Otherwise, consider this part of the documentation as optional

database file

• sqlite3 format
• named logger_data.db by default
• A different filename can be chosen with the -d command line option
• placed in /var/lib/owlogger if you use the installation script
• the file will be automatically created if it doesn't exist

table

• the table holds the data
• only one table is needed
• named datalog
• Created automatically if it doesn't exist
• Simple schema:

In sqlite3:

$ sqlite3 logger_data.db 
SQLite version 3.40.1 2022-12-28 14:03:47
Enter ".help" for usage hints.
sqlite> .tables
datalog
sqlite> .dump datalog
PRAGMA foreign_keys=OFF;
BEGIN TRANSACTION;
CREATE TABLE datalog (
                id INTEGER PRIMARY KEY, 
                date DATATIME DEFAULT CURRENT_TIMESTAMP, 
                value TEXT
            );
COMMIT;

indexes

• Primary index: id
  • required
  • unique
  • generated automatically
  • not used directly
• Secondary index:idx_date
  • indexes field date
  • not (necessarily) unique
  • created if not present
  • used for performance

sqlite> .indexes datalog
idx_date

Queries

Create table

            CREATE TABLE IF NOT EXISTS datalog (
                id INTEGER PRIMARY KEY, 
                date DATATIME DEFAULT CURRENT_TIMESTAMP, 
                value TEXT
                );

Create index

            CREATE INDEX IF NOT EXISTS idx_date ON datalog(date);

Data for this day

            SELECT TIME(date) as t, value FROM datalog 
               WHERE DATE(date) BETWEEN DATE(?) AND DATE(?) 
               ORDER BY t;

Days with any data in a range

            SELECT DISTINCT DATE(date) as d FROM datalog 
               WHERE DATE(date) BETWEEN DATE(?) AND DATE(?) 
               ORDER BY d;

Months with any data (this year)

            SELECT DISTINCT strftime('%m', date) AS m FROM datalog 
               WHERE strftime('%Y', date)=?  
               ORDER BY m;

Years with any data

            SELECT DISTINCT strftime('%Y', date) AS y FROM datalog 
               ORDER BY y;

Accessing data

Python

Access directly with built-in python sqlite3 module

Web interface

owlogger provides a native web interface. default port:8001

Command line

sqlite3 official, rather bare-bones command line tool. Example:

sqlite> .tables
datalog

Graphical

DB browser for sqlite is cross-platform and pretty intuitive

Customize

DETAILS

Credit and Acknowledgment

owlogger is a system of multiple components, and leverages several open-source projects:

Python

Python3, and many modules:

• The standard lib: argparse, datetime, http.server, io.BytesIO, json, math, os, sys, time, urllib, urllib.parse
• Also the standard database module: sqlite3
• The requests module for sending data to a remote server

pyownet

• pyownet by Stefanno Micccoli is python module that communicates directly woth owserver. The version here is slightly modified.
  • update to Python3
  • use f-string formatting
  • included directly in the owlogger repository

owserver

Part of the owfs -- 1-wire file system maintained by a group of developers.

1-wire

1-wire is a simple protocol for communication with external enumerated devices, like memory, temperature and voltage. The protocol actually uses 2 wires, but data and power are combined on a simegle line that multiple sensors can share. Originally Designed by Dallas Semiconductor, it's now produt of Analog Devices

Javascript

Basic code is embeddd in owlogger but a nice calendar function comes from air-datepicker by T1m0n (Timofey).

The air-datepicker code is slightly modified to default to english text and hosted directly in this repository.

caddy

Best practice is to use a reverse-proxy in frnt of owlogger likw caddy by Matt Holt

firewall

ufw is used by Debian and Ubuntu and helps limit external attacks.

sqlite3

The database used is the sqlite3 library by D Richard Hipps. Not only is it imbedded in python, but it can be used as stand-alone program on the database file.

mdbook

This documentation on owlogger os arranged using mdbook -- a documentation system from the Rust Language project.

Security

General Notes

owlogger is a systems of components, so the security aspect needs to be analyzed in parts. In general, this collects low-value data, so collateral damage is a consideration.

Programs

Best practice:

owserver

Well tested. Read-only of data from physical sensors. communication is via owserver protocol but typically will be internal to the posting station.

owpost

Send-only externally, potentially via https if a reverse proxy is employed.

owlogger

Uses http.server python module, which is advertised as not hardened. The accepted HTTP messages are restricted, specifically no arbitrary file reading or external program use. Using a reverse proxy to keep communication internal is advisable, however.

Browser

Data on the display device is performed via HTML with a non-persistent javascript component. The air-datepicker module is used, but not loaded from an external source.

Logging data

Encryption

Data is sent in clear text via http by default. Using https by adding a proxy agent (e.g. caddy) to the server is easily accomplished and implementation of that scheme is detailed.

Injection

All data is logged by default, potentially including malicious spam. A simple form of authentification using an arbitrary text string (token) is available. This only makes sense if the traffic is also encrypted. This token must be added at both ends at startup and requires that both ends are secure from inspection.

Access to data

Access (to owlogger web display) is read-only, but web-available -- the point of the system. Communication is via http by default.

Encryption

https (TLS encryption) is easily added with a proxy agent (e.g.caddy) and implementation of that is encouraged and detailed with design and scripts.

Authentification

Authetification for access is not implemented.

Database

The database is stored on the server, and so requires that the server's file system is not compromised.

• Data entry is via sqlite3 with protection against SQL injection attack
• Data is managed in a write-only mode
• There is a potential for spam data to be sent to the system, filling up the file space (see tokens).

Physical

Phyisical access, compromise and damage is generally out of scope.

data collectors

Sensors, wires and the owputter component may be in a vulnerable area to intentional or unintentional damage, so robust installation is advisable. These components are generally inexpensive, fortunately.

License

There are several components used (but included directly) with slightly different licences.

Summary

Open source, and may be employed as you wish. Licensing cannot change. Some parts require that distributing derived software must also offer the source code be available

Details

owlogger.py owpost.py

MIT license -- basically code may be used for any purpose, but should stay under that license and offers no warrantees.

air-datepicker

MIT licence

pyownet

LGPL-3.0 -- read the details here.

So the licensing is quite permissive. Treating the entirety as LGPL-3.0 is probably the safest course, but the individual components are licensed as stated above.

Repository

owlogger source code is available in a github repository

• The Issues tab is a good place to ask questions and report problems.
• Skilled coders can fork the code, and hopefully offer useful additions back in Pull requests
• This documentation is also in the repository
  • Markup files in the /src directory
  • Uses mdbook

Support

Issues tab

The best place to bring questions, issues and plaudits is the issies tab of the owlogger github site.

Open Source

As for any free open-source program the avenues for assistance are:

• The on-line forum (in this case the issues tab noted above
• Experimentation and looking at the source code

Of course there is no guarantee that help will be available or timely, but help courteous people use your creation is one of the rewards of oen-source software.

owfs and python

The author's expertise is the owfs system (he's the original author) and the specific python programs used here. Some of hte other components (python modules, caddy, TSL certificates) may need to be answered elsewhere.