AOL PD 2

Wearable UV dosimeter

Wearable device for measuring UV irradiance with multiplatform companion app with dose warnings based on Fitzpatrick phototypes.

This repository is a mirror of Jan Vodstrčil's and Ondřej Pokovič's project made for the Applied Optoelectronics in Medicine subject at CTU FEE. The source repository can be found at CTU FEE's GitLab. The README, docs/ and licenses (see License) have been updated for this public mirror.

Measures UV irradiance with an ML8511, estimates the angle between the sensor face and the sun from four edge-mounted BPW34 photodiodes, and divides the reading by cos(theta) to recover the irradiance that a sun-facing sensor would have measured. The corrected value is integrated over time into an erythema-weighted dose and compared against the minimal erythema dose for the wearer's skin phototype.

Custom KiCad PCB, ESP32-H2 firmware, and a Flet/Bleak companion app.

Repository layout

Angle correction

A flat sensor tilted away from the sun by angle theta reads E * cos(theta) instead of E. On a wrist the tilt is arbitrary and changes constantly, so theta has to be measured rather than assumed.

The four BPW34 diodes are tilted 20 deg outward from the PCB normal, one per edge. Their normals are (+/-sin20, 0, cos20) and (0, +/-sin20, cos20). Weighting each normal by its photocurrent and summing approximates the sun direction:

s          = ( (R - L) * sin20,  (T - B) * sin20,  (L + R + T + B) * cos20 )
cos(theta) = s_z / |s|

Implemented in sensors.cpp with sin20 = 0.342, cos20 = 0.940. Two consequences of the form of the expression:

• The dark-current baseline subtracted from each channel cancels in s_x and s_y, and s_z appears in both numerator and denominator, so PD_DARK_OFFSET only needs to be approximately right.
• |s| is undefined at zero illumination. The implementation returns cos(theta) = 1 when the magnitude is zero.

Below cos(theta) = 0.05 the division is ill-conditioned, so uvCorrected is set to NaN rather than a large number. This propagates through the BLE packet and is treated as zero irradiance by the dose tracker.

Hardware

Two-layer PCB with ground pours on both copper layers and components populated on both sides, built around the ESP32-H2-Zero module and designed in KiCad 9. Schematic: AOL_PD_2.kicad_sch.

GPIO0 drives both the ML8511 EN pin and the divider that biases the photodiode amplifiers, so a single digitalWrite(PIN_UV_EN, HIGH) in setup() brings up the entire analog front end.

ML8511 transfer function. Linear, 0.99 V at 0 mW/cm^2 and 2.8 V at 15 mW/cm^2, giving E = max((V - 0.99) * 15 / 1.81, 0).

Photodiode channels are inverted. The TLV9064 stages are inverting transimpedance amplifiers with the non-inverting input biased to Vb ~= 97 mV, generated by a 330k/10k divider off GPIO0 and buffered by a fifth op-amp section. Increasing photocurrent pulls the output toward GND, so a lower ADC count means more light. Firmware converts with light = max(0, PD_DARK_OFFSET - raw).

The UV channel needs the calibrated ADC read. ESP32 ADC non-linearity near the bottom of the range causes analogRead() to underestimate voltages around the ML8511's 0.99 V floor, which clipped all low readings to zero. analogReadMilliVolts() applies the factory calibration and corrects this. The raw count is still reported over BLE for diagnostics.

PD_DARK_OFFSET in config.h is per-board: cover all four diodes, read the peak count, add margin. Default 110.

Firmware

PlatformIO with the pioarduino platform fork, which supplies arduino-esp32 3.x (ESP-IDF 5.x) for the H2.

cd firmware
pio run -t upload && pio device monitor

On Linux, install 99-platformio-udev.rules first.

The main loop samples all five channels, then either notifies the connected client or appends to the ring buffer, and sleeps 500 ms.

Power management. esp_pm_configure() sets 96 MHz max / 32 MHz min with automatic light sleep, so FreeRTOS sleeps during delay() while the BLE controller schedules its own wake-ups for connection events. This avoids calling esp_light_sleep_start() manually against running BLE tasks. Requires arduino-esp32 3.x, which enables CONFIG_PM_ENABLE and CONFIG_FREERTOS_USE_TICKLESS_IDLE by default; on 2.x the call fails silently and delay() behaves normally.

Offline buffer. While disconnected, one {dt_s, uvCorrected} record is written every 10 s to a LittleFS-backed ring buffer, with head/tail/count indices mirrored in NVS so the buffer survives reset. Records are 6 bytes; 2048 of them cover about 5.7 hours. clear() resets the logical indices without erasing file data, and iteration is deliberately not invalidated by it.

BLE protocol

Advertises as UV Sensor with the service UUID in the advertisement payload; the app connects by service UUID rather than by name.

Live notification, 22 bytes packed little-endian (struct.unpack('<HfffHHHH', data)):

History transfer, on the second characteristic:

1. On connect, the firmware waits 4 s for the client to finish GATT discovery and subscribe.
2. It snapshots the read cursor and clears the buffer before draining it, so a disconnect mid-transfer cannot replay records on the next connection.
3. Each record is sent as a 6-byte notification (<Hf), paced 20 ms apart to avoid overflowing the stack's notify queue.
4. End of stream is a single 0x00 byte. The client treats any payload whose length is not 6 bytes as the terminator.

While a client is connected the buffer is not written to, and the record timer is reset on every live packet so the first offline record after disconnect carries a correct dt_s.

App

cd app
pip install -r requirements.txt
python main.py

Home shows UV index, angle-corrected irradiance, and accumulated dose as a percentage of MED. The progress bar transitions green to orange at 50 % and to red at 80 %, with a subtitle estimating time remaining at the current rate. Dose is persisted to client storage along with the date it was accumulated, and restored on launch only if that date is today, so a new calendar day starts from zero.

Settings holds the connect button, a last-sync timestamp, and the Fitzpatrick phototype selector (I-VI, with a reference card sourced from NCBI StatPearls; changing the phototype resets the dose). An "Advanced" switch reveals a developer panel, hidden by default, exposing the five raw ADC counts, cos(theta), uncorrected irradiance, and manual scan/connect/disconnect/reset controls.

On connect, buffered history is replayed through update_historical() before live streaming starts, and a snack bar reports how much offline time was synced. A dose reset performed while disconnected sets a persisted pending_reset flag that suppresses the next replay.

Dose model

K = 0.001719 is computed in sem_project.m as the ratio of two integrals over the ASTM G-173 solar spectrum: irradiance weighted by the McKinlay-Diffey erythema action spectrum, divided by irradiance weighted by the ML8511's spectral response. It therefore converts what this specific sensor measures into what skin responds to.

Per sample, with the factor 10 converting mW/cm^2 to W/m^2:

E_ery [W/m^2] = uvCorrected * 10 * K
dose  [J/m^2] = sum(E_ery * dt)
UVI           = E_ery * 40

Dose is compared against the lower bound of the MED range for each phototype (200 / 250 / 300 / 450 / 600 / 1000 J/m^2 for types I-VI). NaN samples are treated as zero irradiance, and accumulation pauses on disconnect rather than integrating across the gap.

Status

Working prototype; firmware and app function end to end.

Toolchain notes for the original ESP8266 prototype are kept in docs/esp8266-rtos-sdk-linux.md.

License

Copyright (C) 2026 Jan Vodstrčil and Ondřej Pokovič.

Different parts of this project are released under different reciprocal licenses, each carrying its full text in the directory it applies to.

A file's license is determined by the directory it lives in. math/astmg173.xls is third-party ASTM G-173 reference spectrum data distributed by NREL and is not covered by these terms. See LICENSE for the full breakdown.