Software¶
This section covers the software components of the OSECHI cosmic ray detector.
Components¶
| Component | Technology | Role |
|---|---|---|
| Firmware | C++ (Arduino / PlatformIO) | Cosmic ray detection, sensor readout, serial communication |
| Build System | PlatformIO | Cross-compilation, library management, device upload |
| Task Automation | Taskfile | Unified CLI for build, upload, monitor, docs, versioning |
| Serial Communication | pyserial | Read detection data and send commands from Python |
| Documentation | MkDocs (Material theme) | Static site generation from Markdown |
| Version Management | commitizen | Semantic versioning via conventional commits |
| Python Tools | uv | Package management, data analysis scripts |
Firmware Architecture¶
The firmware handles detection, sensor readout, and serial output in an event-driven loop:
- Three scintillator channels are sampled continuously — a detection is recorded when any channel exceeds its threshold
- On each detection, environmental sensors (temperature, pressure, humidity) are read
- The result is serialized as a JSONL line and sent over USB serial
- Text commands from the host are received and processed between detection cycles
All output uses the unified device response protocol: every line is a JSON object with type, status, and sent_us fields.
Pages¶
- PlatformIO — Build, upload, and monitor firmware
- pyserial — Read detection data from Python
Dependencies¶
Arduino Libraries¶
| Library | Version | Purpose |
|---|---|---|
| Adafruit BME280 Library | 2.3.0 | Environmental sensor (temperature, pressure, humidity) |
| ArduinoJson | ^7.1.0 | JSON serialization for JSONL output |
| WiFi | built-in | ESP32 WiFi AP mode (optional) |
Python Tools¶
| Tool | Purpose |
|---|---|
| uv | Python package and environment management |
| pyserial | Serial communication with OSECHI |
| mkdocs + mkdocs-material | Documentation site generation |