POSA_LEAKSMS/docs/SHT30_SENSOR2_SETUP.md

SHT30 온습도 센서 설치 가이드 (2번 모듈, sensor_id=2)

서버실 온습도 모니터링을 위해 Sensirion SHT30(한진데이터 P4422-3, I2C) 센서를 설치하고 서버에 연동하는 가이드입니다. 현재 배포 구성은 Raspberry Pi 4 Model B + Python(raspberry_pi4_sht30/ = deploy/03_pi_b_sht30_id2/, device_id=rpi4-sht30-01)입니다. STM32F407 펌웨어(firmware/)는 별도의 마이그레이션 트랙(하드웨어 미검증)으로, 실제 필드 배포와 무관합니다 — §3 참고.

기준 문서: 루트 README.md, SYSTEM_OVERVIEW.md, docs/DEPLOYMENT_PLAN_RPI4x3.md §5. 현장 인쇄용 배선·핀맵 도해: deploy/03_pi_b_sht30_id2/WIRING.html (브라우저로 열람 — 자체 완결형, 오프라인 가능).

1. 서버 준비

1. 웹 서버 DB에 통합 스키마를 적용합니다(신규 설치).

   SOURCE sql/schema_sht30.sql;
   

2. 서버 파일을 배포합니다.

   php/api/sensor_data.php
   php/dashboard.php
   php/ops_checks.php
   php/config.php
   sql/schema_sht30.sql
   

   API는 sht30 측정을 수신하면 leak_sensor_status를 갱신하고 측정값을 leak_sensor_metric에 저장합니다. 서버가 METRIC_* 임계로 고온/저온/고습/저습을 판정하고, 초과 시 종류별 30분 쿨다운으로 SMS를 발송합니다.

   서버는 수집 시 device_id/app_version/metric_type 문자열을 검증하지 않습니다(HMAC 서명 + 필수필드 + sensor_id 범위 1..255 + 타임스탬프 신선도만 확인). 따라서 라즈베리파이 클라이언트(rpi4-sht30-01, app_version=v2606-sht30-rpi4)가 그대로 수용됩니다.

2. 기본 구성 — Raspberry Pi 4 (I2C)

소스: deploy/03_pi_b_sht30_id2/(= raspberry_pi4_sht30/). 근거는 해당 README.md, SETUP.md, WIRING.html, config.py, install.sh, systemd/sht30-sensor.service.

2.1 I2C 배선 (Pi 4 40핀 헤더, 버스 1)

상세 도해는 deploy/03_pi_b_sht30_id2/WIRING.html(SVG 핀맵 + 스키매틱 + 체크리스트)을 브라우저로 여십시오.

SHT30 VCC  -> Raspberry Pi 3.3V (물리 핀 1)   ★ Pi 에서는 5V(핀 2·4) 금지 (모듈은 2.4~5.5V OK나, 5V 전원 시 SDA/SCL 5V → 3.3V 전용 Pi GPIO 손상)
SHT30 GND  -> Raspberry Pi GND (핀 6; 대체 9·14·20·25·30·34·39)
SHT30 SDA  -> Raspberry Pi GPIO2 / SDA1 (물리 핀 3)  + 4.7kΩ 풀업 -> 3.3V
SHT30 SCL  -> Raspberry Pi GPIO3 / SCL1 (물리 핀 5)  + 4.7kΩ 풀업 -> 3.3V
SHT30 ADDR -> GND (주소 0x44; VDD면 0x45)

• 7-bit 주소 0x44(ADDR→GND). config.py의 I2C_ADDR와 반드시 일치.
• I2C 풀업 4.7kΩ ×2 — SHT30 모듈에 온보드 풀업이 있으면 생략.
• 명령 0x2C06(high-repeatability) → 약 20ms 대기 → 6바이트 read (드라이버 sht30_driver.py).

2.2 설정값 준비 (config_local.py)

cd /home/pi/raspberry_pi4_sht30
cp config_local.example.py config_local.py
# config_local.py 를 열어 채운다:
#   API_URL         = https://<서버>/raspi_leck_detecter/api/sensor_data.php  (1번 모듈과 동일 엔드포인트)
#   API_KEY         = 서버 config.local.php 의 API_KEY 와 바이트 단위로 동일
#   DEVICE_ID       = rpi4-sht30-01
#   DEVICE_LOCATION = 온습도 측정 위치(예: 서버실)

config_local.py가 없으면 실행 시 명확한 오류로 즉시 중단(fail closed)됩니다. config_local.py·API_KEY는 절대 커밋하지 마세요(.gitignore 처리됨). sensor_id(=2)/sensor_name은 config.py 기본값을 씁니다.

⚠️ 설정은 Python config_local.py 로만 합니다. 과거 문서에 있던 /etc/sht30-sensor.env 환경파일 방식은 이 라즈베리파이 모듈에서 사용하지 않습니다.

2.3 설치 (폐쇄망 오프라인 + 온라인 폴백)

원샷:

cd /home/pi/raspberry_pi4_sht30 && bash setup.sh   # 설치→서비스 등록→검증→하드닝 (sudo 붙이지 말 것)

또는 단계별:

chmod +x install.sh && ./install.sh   # apt(i2c-tools 등) + I2C 자동 활성화 + venv(requests/smbus2) + 로그
sudo reboot                           # I2C 를 새로 켠 경우 1회 (usermod -aG i2c 반영에도 필요)

• 폐쇄망: 인터넷 되는 동일 aarch64 머신에서 ./vendor.sh로 wheelhouse/+debs/ 번들 → 타깃 Pi로 복사 후 ./install.sh(자동 오프라인).

2.4 systemd 자동 실행

sudo cp systemd/sht30-sensor.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sht30-sensor
sudo systemctl status sht30-sensor
journalctl -u sht30-sensor -f

유닛 특성: User=pi, SupplementaryGroups=i2c(/dev/i2c-1 접근), Restart=always. install.sh는 유닛을 자동 설치하지 않으므로 이 단계 누락 금지.

2.5 동작 확인

i2cdetect -y 1                 # 0x44(또는 0x45)가 보여야 함
source venv/bin/activate
python3 test_sensor.py         # CRC/포맷 자가점검 + 측정 1회
python3 test_connection.py     # 서명 POST 200(연결/서명), 403=API_KEY 불일치, 400=NTP/타임스탬프

⚠️ test_sensor.py는 하드웨어 없이도 시뮬레이션으로 통과합니다. 반드시 i2cdetect로 0x44를 먼저 확인하고, 서비스 로그에 시뮬레이션 WARN이 없는지 점검하세요(시뮬레이션 폴백이 배선 오류를 가릴 수 있음).

• Pi 시각은 NTP 동기 필수(서버 timestamp 신선도 ±600초 — Raspberry Pi OS 기본 활성).
• 이후 5분 주기 periodic 측정 보고.

3. 대안(계획) 구성 — STM32F407VGT6 (sht30_fw)

STM32F407 베어메탈 펌웨어(firmware/)는 RPi → STM32 전환을 목표로 한 별도 마이그레이션 트랙입니다. docs/stm32f407_migration_plan.md 기준 코드는 완성되었으나 실제 보드 빌드·플래시·HIL 시험은 미검증(서버 host/CA/API키/SNTP가 모두 placeholder)이며, 현재 필드에는 배포되어 있지 않습니다. 이 경로를 실제로 채택하려면 firmware/docs/HARDWARE.md·firmware/docs/BUILD_OFFLINE.md를 따라 하드웨어를 확정·검증해야 합니다.

• I2C1 배선(참고): SHT30 SCL → STM32 PB6(I2C1_SCL, AF4), SDA → PB7(I2C1_SDA, AF4), 각 4.7kΩ 풀업 → 3.3V, ADDR → GND(0x44). VCC는 3.3V(5V 금지).
• 보고 식별자: device_id=stm32-sht30-01, app_version=v2606-sht30, sensor_id=2. 서버는 이 문자열을 검증하지 않으므로 Pi/STM32 어느 쪽이든 유효 서명이면 동일하게 수용합니다.

4. 대시보드 결과

첫 정상 보고 후:

• leak_sensor_status에 sensor_id=2 항목이 생성됩니다.
• leak_sensor_metric에 온도/습도 이력이 누적됩니다.
• dashboard.php가 센서 카드에 최신 온도/습도와 임계 상태를 표시합니다.

장비가 HEARTBEAT_TIMEOUT_SEC(기본 1200초=20분)을 초과해 보고를 멈추면 서버가 오프라인으로 판정하고 SMS를 발송합니다.