Vertical sampler

Vertical Sampler

Firmware, hardware and host software for a balloon-borne vertical air sampler for Ice Nucleating Particle (INP) collection.

Payload and ground-station Raspberry Pi Pico W boards run CircuitPython and communicate over LoRa at 868 MHz. The system supports two payload identities: kenttarova and matorova.

System Overview

┌─────────────────────────┐        LoRa 868 MHz         ┌─────────────────────────┐
│        PAYLOAD          │◄───────────────────────────►│    GROUND STATION       │
│  Raspberry Pi Pico W    │                             │  Raspberry Pi Pico W    │
│                         │                             │                         │
│  - GPS (+ RTC sync)     │                             │  - Receives telemetry   │
│  - SHT85 RH/temp sensor │                             │  - Relays to PC via USB │
│  - LPS25H pressure      │                             │  - Forwards commands    │
│  - Pumps + electrovalve │                             └─────────────────────────┘
│  - SD logging           │                                         │
│  - Battery + flow meter │                                    USB Serial
│  - Watchdog             │                                         │
└─────────────────────────┘                             ┌─────────────────────────┐
                                                        │       Host computer     │
                                                        │ host/cli.py             │
                                                        │ host/quickview.py       │
                                                        └─────────────────────────┘

Repository Structure

vertical_sampler/
├── firmware/                    # CircuitPython code deployed to Pico boards
│   ├── common/                  # Copied flat to every CIRCUITPY drive
│   │   ├── config.py            # PCB v1 GPIOs, calibration, limits, LoRa addresses
│   │   ├── payload.py           # Active payload drivers and mission loop
│   │   ├── lora.py              # RFM9x wrapper
│   │   ├── pressure_sensor.py   # LPS25H driver
│   │   ├── sdcard.py            # SD mount, JSONL data and log writes
│   │   ├── logging.py
│   │   ├── pack.py              # Binary LoRa telemetry format
│   │   ├── led.py
│   │   ├── adafruit_gps.py      # Vendored CircuitPython dependency
│   │   └── adafruit_rfm9x.py    # Vendored CircuitPython dependency
│   ├── kenttarova_main.py       # kenttarova payload entry point
│   ├── matorova_main.py         # matorova payload entry point
│   └── ground_main.py           # Ground-station entry point
├── host/                        # Python 3 programs running on the control PC
│   ├── cli.py
│   └── quickview.py
├── pcb/                         # KiCad PCB v1 project
├── docs/
│   └── TROUBLESHOOTING.md
├── Makefile
└── README.md

firmware/common/ is copied as flat modules to the root of CIRCUITPY. CircuitPython imports therefore remain simple:

import config
import lora
import pack

Payload Identities

Addresses, GPIO assignments, calibration constants and safety limits are defined centrally in firmware/common/config.py.

Quick Start

1. Flash CircuitPython

make download-circuitpython-image

Copy the resulting .uf2 to the Pico W while it is in BOOTSEL mode.

2. Install dependencies

The repository vendors adafruit_gps.py and adafruit_rfm9x.py. Install the remaining required CircuitPython libraries in the Pico lib/ directory, including the dependencies required by the RFM9x driver such as adafruit_bus_device.

3. Deploy firmware

Set the CircuitPython mount point if needed:

export CIRCUITPY_PATH=/media/$USER/CIRCUITPY

Deploy the required device image:

make update-kenttarova
make update-matorova
make update-ground

Each target:

1. Removes stale code.py.
2. Copies all firmware/common/*.py modules to the Pico.
3. Copies the selected entry point as main.py.

4. Control a payload

Run commands from the host computer:

python host/cli.py kenttarova data
python host/cli.py kenttarova pump front on
python host/cli.py kenttarova pump back off
python host/cli.py kenttarova valve on
python host/cli.py matorova data

host/quickview.py is available for local data inspection and visualization.

The host dashboards automatically use the latest sea-level pressure observation from FMI station Kittilä Matorova (fmisid=101985) as QNH. The value is refreshed every 10 minutes through the public FMI WFS API. If FMI is unavailable, the last fresh FMI value is retained and then the manual/default value of 1013.25 hPa is used. Pass --qnh VALUE to select a different fallback, or --no-auto-qnh to disable automatic updates. Logged monitor samples include _qnh_hpa, _qnh_source and _qnh_observation_time so derived altitude remains traceable.

Telemetry Format

Each payload sample is logged as JSONL when an SD card is available and sent over LoRa as a packed binary packet defined in firmware/common/pack.py.

RTC synchronization: on the first valid GPS fix, the payload sets the onboard RTC to GPS UTC. Subsequent rtc_time values remain valid even if the GPS temporarily loses its fix.

SD Logging

The SD-card handler writes:

If the SD card is unavailable or fails while operating, the payload continues running and transmitting telemetry over LoRa. Logging degrades to the serial console instead of stopping the mission.

Safety Features

The watchdog is fed in the main loop, GPS wait loop, LoRa receive loop and failure-report loops.

PCB v1 Pin Map

The RFM9x reset line is not routed on PCB v1. config.LORA_RESET_DUMMY remains because the CircuitPython RFM9x driver requires a reset-pin argument.

Calibration

Flowmeter

The TSI 4121 flowmeter is configured as:

• Signal range: 0–4 V corresponding to 0–20 Std L/min.
• ADC divider: 10 kΩ series resistor and 32.6 kΩ to ground.
• Divider ratio: (32.6 / (10.0 + 32.6)).
• Zero offset: FLOW_OFFSET_LMIN in firmware/common/config.py.

Battery monitor

BATTERY_CAL_FACTOR in firmware/common/config.py converts the Pico ADC voltage to the measured 6S battery voltage. Recalibrate against a multimeter if the divider or analog front-end changes.

Development Notes

• firmware/common/payload.py contains the active, hardware-validated payload drivers and mission loop.
• firmware/common/config.py is the single source of truth for PCB pins, calibration, operating limits and LoRa addresses.
• The old breadboard firmware is preserved in the old_hardware branch.
• See docs/TROUBLESHOOTING.md for deployment and communication diagnostics.