Skip to content

TN-006: Workspace and Timezone via Environment Variables

Summary

Output directory and timezone are resolved from KAZUNOKO_WORKSPACE and KAZUNOKO_TZ environment variables, falling back to the current directory and system timezone respectively. This allows long-running measurement setups to be configured once without modifying scripts.

Background

OSECHI detectors are often deployed on single-board computers (Raspberry Pi, etc.) running unattended for extended periods. Multiple measurement runs accumulate JSONL files organized by date:

/data/measurements/
└── 20241216/
    ├── events_aabbccdd_20241216T120000_0000001.jsonl
    └── events_aabbccdd_20241216T130000_0000002.jsonl

Two configuration values recur across all scripts:

  1. Output root directory — where to write files. Changes per deployment (laptop vs Raspberry Pi vs NAS).
  2. Timezone — for timestamp generation and daily directory naming. Raspberry Pi may report UTC even when deployed in JST.

Hardcoding these in scripts means editing every script per deployment. Passing them as CLI arguments every invocation is error-prone.

Decision

workspace.py provides three functions exported from the top-level package:

  • get_workspace() — reads KAZUNOKO_WORKSPACE, falls back to Path(".")
  • get_timezone() — reads KAZUNOKO_TZ, falls back to pendulum.local_timezone().name
  • generate_filename(mac_address, file_id) — composes the standardized output path using both

Set once in the shell environment or .env file:

export KAZUNOKO_WORKSPACE=/data/measurements
export KAZUNOKO_TZ=Asia/Tokyo

All scripts then call get_workspace() and get_timezone() without any per-script configuration.

pendulum is used for timezone detection (rather than datetime.timezone) because it reliably identifies the IANA timezone name (e.g., "Asia/Tokyo") from the system locale, which is required for correct daily directory naming across DST boundaries.

Alternatives Considered

Alternative Reason Not Chosen
CLI --workspace / --timezone flags on every command Repeated per invocation; easy to forget; inconsistent across scripts
Config file (TOML/JSON) More infrastructure to manage; env vars are simpler for deployment
Hardcode in each script Requires editing every script per deployment
datetime.timezone for system tz Returns UTC offset only, not IANA name; breaks at DST boundaries

Consequences

  • Deployment configuration is separated from script logic — scripts are portable across environments.
  • KAZUNOKO_WORKSPACE unset → output goes to the current directory (safe default for interactive use).
  • KAZUNOKO_TZ unset → system timezone is used (correct on most desktops; may need to be set explicitly on embedded Linux boards configured to UTC).
  • generate_filename() produces deterministic paths given the same MAC, timestamp, and file_id, making output filenames predictable and sortable.
  • pendulum becomes a runtime dependency (not dev-only) due to get_timezone().