---
title: Sensor telemetry extensions should keep status and measurements separate
date: 2026-05-21
category: docs/solutions/best-practices
module: raspberry_pi/php sensor telemetry
problem_type: best_practice
component: database
severity: medium
applies_when:
  - Adding a non-leak sensor to the leak monitoring system
  - Reporting environmental readings such as SHT30 temperature and humidity
  - Extending Raspberry Pi hardware while preserving existing heartbeat behavior
tags: [sensor-telemetry, sht30, raspberry-pi, monitoring]
---

# Sensor telemetry extensions should keep status and measurements separate

> 참고: 이 문서는 누수감지 시절의 기록(레거시)이며, 현재 시스템은 SHT30 온습도 전용으로 전환되었습니다.

## Context

The second Raspberry Pi uses an SHT30 temperature/humidity sensor instead of a leak contact sensor. The existing API and dashboard already track `sensor_status` and heartbeat, but the original schema had no place to persist temperature/humidity readings.

## Guidance

Keep the device online/offline state in `sensor_status`, and store changing environmental readings in a separate metric table such as `sensor_metric`.

For SHT30 sensor2, the Pi should continue sending the existing required fields:

```json
{
  "device_id": "rpi-sht30-01",
  "sensor_id": 2,
  "event_type": "periodic",
  "is_leak": 0,
  "timestamp": 1779290000
}
```

Add telemetry fields before generating the API signature:

```json
{
  "metric_type": "sht30",
  "temperature_c": 24.35,
  "humidity_percent": 48.1,
  "metric_status": "normal"
}
```

The API should update `sensor_status` on every accepted report and insert measurement rows into `sensor_metric` when the table exists. This lets heartbeat/offline monitoring keep working even if metric storage has not yet been migrated.

## Why This Matters

Mixing environmental readings into `sensor_log` would make normal reports noisy and would not model temperature/humidity as time-series data. A separate metric table keeps device status and environmental telemetry clear enough for dashboard display, monthly reports, and threshold alerts (이번 전환에서 서버측 온습도 임계 SMS로 구현됨).

The Raspberry Pi source should also support both `smbus2` and Raspberry Pi OS `python3-smbus`. `smbus2` can be used as a context manager, but legacy `smbus` may require explicit `close()` handling.

## When to Apply

- Add sensor2 or later environmental sensors.
- Add readings that are not leak events but need history.
- Add Pi hardware that should participate in the existing offline heartbeat.
- Add I2C hardware where distro packages and pip packages may expose different Python APIs.

## Examples

For SHT30:

```text
SHT30 VCC -> Raspberry Pi 3.3V
SHT30 GND -> Raspberry Pi GND
SHT30 SDA -> GPIO2 / SDA1 / pin 3
SHT30 SCL -> GPIO3 / SCL1 / pin 5
```

For deployment:

```text
1. Apply sql/migration_sensor_metric.sql.
2. Configure /etc/sht30-sensor.env with SHT30_SENSOR_ID=2.
3. Run python3 sht30_monitor.py --read-once.
4. Run python3 sht30_monitor.py --once.
5. Confirm sensor_id=2 appears on dashboard.php with latest temperature/humidity.
```

## Related

- `docs/SHT30_SENSOR2_SETUP.md`
- `raspberry_pi/sht30_monitor.py`
- `sql/migration_sensor_metric.sql`
- `php/api/sensor_data.php`