서버실 온습도(SHT30) 모니터링 시스템 v2606 — 설치 가이드

1. 시스템 개요 & 아키텍처

단일 STM32F407 보드(sht30_fw, sensor_id=2)가 SHT30 센서를 I²C로 5분마다 읽어, 본문을 HMAC-SHA256으로 서명해 TLS 1.2로 Cafe24 PHP 서버에 POST합니다. 서버가 임계를 재판정하여 고온/저온/고습/저습·결로·오프라인 상황을 SMS로 알리고 웹 대시보드/보고서를 제공합니다.

2. 설치 전 준비물

3. 서버 파일 업로드

Cafe24 FTP(또는 파일 관리자)로 웹 루트 아래에 PHP 트리를 업로드합니다.

public_html/raspi_leck_detecter/
  .htaccess              config.php            config.local.php   ← 서버에서만 생성
  config.local.example.php
  login.php              dashboard.php         setup_wizard.php
  setup_mfa.php          admin_security.php    ops_checks.php
  sms_send.php           cron_heartbeat.php    monthly_report.php
  security_evidence.php  retention_cleanup.php setup_hash.php
  blocked.php            test_mobile.php
  api/
    sensor_data.php
  var/
    .gitkeep             ← PHP가 쓰기 가능해야 함(상태/감사/카운터 파일)

4. 운영 설정 — config.local.php

config.local.example.php 를 복사해 config.local.php 를 만들고 실제 운영 값으로 교체합니다.

<?php
return [
    'DB_HOST' => 'localhost',
    'DB_PORT' => 3306,
    'DB_NAME' => 'your_db_name',
    'DB_USER' => 'your_db_user',
    'DB_PASS' => 'your_db_password',

    'API_KEY' => 'replace-with-long-random-secret',   // 펌웨어 APP_API_KEY 와 동일!
    'ALLOW_LEGACY_BODY_SIGNATURE' => false,            // HMAC 전용(레거시 RPi 없으면 false)

    'SMS_USER_ID' => 'your-cafe24-sms-user-id',
    'SMS_SECURE'  => 'your-cafe24-sms-secure-key',
    'SMS_SENDER'  => '01000000000',
    'SMS_RECIPIENTS' => ['01000000000'],
    'SMS_RECIPIENTS_TIER2' => [],                      // 미복귀 30분 시 2차(야간) 통지(opt-in)

    'ADMIN_USER' => 'admin',
    'ADMIN_PASSWORD_HASH' => '',   // setup_hash.php 출력으로 채움(빈값=로그인 차단)
    'ADMIN_TOTP_SECRET'   => '',   // setup_mfa.php 등록 후 채움(빈값=로그인 차단)
    'MFA_SETUP_TOKEN'     => 'replace-with-temporary-random-token',  // 등록 후 비울 것

    // 온습도 임계(서버 판정 → SMS). 기본값은 config.php 의 METRIC_*
    'METRIC_TEMP_HIGH_C' => 30, 'METRIC_TEMP_LOW_C' => 10,
    'METRIC_RH_HIGH' => 70,      'METRIC_RH_LOW' => 20,
];

5. 데이터베이스 설치 (phpMyAdmin)

6. 권한 · 관리자 비밀번호 · MFA 등록

상태 파일 폴더 쓰기 권한

raspi_leck_detecter/var/ 가 PHP에서 쓰기 가능해야 합니다(브루트포스/하트비트/감사로그/거부 카운터 파일 저장).

관리자 비밀번호 해시 생성(서버 CLI)

php setup_hash.php "새관리자비밀번호"

출력된 bcrypt 해시를 config.local.php 의 ADMIN_PASSWORD_HASH 에 넣습니다.

MFA(TOTP) 등록

MFA_SETUP_TOKEN 을 임시 설정한 뒤 아래 주소로 접속해 인증 앱(Google/Microsoft Authenticator, Authy)에 등록합니다.

https://your-domain.example/raspi_leck_detecter/setup_mfa.php?token=임시토큰

화면의 Base32 키를 인증 앱에 등록 → 6자리 코드 검증 → 표시된 ADMIN_TOTP_SECRET 줄을 config.local.php 에 반영 → 등록 후 MFA_SETUP_TOKEN 을 빈 값으로 바꿉니다.

설치 점검 화면 확인

https://your-domain.example/raspi_leck_detecter/setup_wizard.php

확인 항목: DB 연결 · 필수 테이블 · API 키 교체 · 관리자 해시 · 관리자 TOTP · SMS 수신자 · var/ 쓰기 권한 · 테스트 SMS 발송.

7. cron 설정 — 오프라인 감지 · 헬스 · 에스컬레이션

cron_heartbeat.php 를 1분 간격으로 실행합니다(오프라인 감지 + 일일 헬스 SMS + 미복귀 에스컬레이션).

방법 A — 서버 CLI cron

* * * * * php /home/hosting_user/public_html/raspi_leck_detecter/cron_heartbeat.php

방법 B — HTTP 호출(외부 스케줄러)

https://your-domain.example/raspi_leck_detecter/cron_heartbeat.php?key=<CRON_SECRET>

CRON_SECRET = HMAC-SHA256("cron", API_KEY) 입니다(코드가 파생). 절대 경로는 Cafe24 파일 관리자/phpinfo()로 확인. 마지막 수신 후 HEARTBEAT_TIMEOUT_SEC(기본 1200초=20분) 초과 시 오프라인 판정.

8. 하드웨어 배선 (STM32F407VGT6)

LQFP-100 기준. SHT30 I²C, LAN8720 RMII, USART3 콘솔, 상태 LED를 결선합니다.

8.1 SHT30 I²C1

8.2 LAN8720 RMII (AF11)

8.3 콘솔 · 상태 LED · 클럭

• 콘솔 UART: PD8(TX)/PD9(RX), USART3 AF7, 115200 8N1, 외부 3.3V USB-UART 어댑터.
• 상태 LED: PD12 — 부팅=점등 / 정상보고=느린 토글 / 망단절·TLS실패=빠른 점멸.
• 클럭: HSE 8MHz→168MHz, RMII REF_CLK 50MHz, RTC LSE 32.768kHz(권장; 정전 시 VBAT 시간 보존), IWDG=LSI 20s.

9. 폐쇄망 펌웨어 빌드

bash firmware/scripts/vendor.sh        # 또는 vendor.ps1
# 릴리스 빌드는 핀(SHA-256) 강제:
VENDOR_STRICT=1 bash firmware/scripts/vendor.sh

cp firmware/common/secrets.h.example firmware/common/secrets.h
# APP_API_KEY 를 서버 config.local.php 의 API_KEY 와 바이트 단위로 동일하게 채운다.

openssl s_client -connect your-domain.example:443 -servername your-domain.example -showcerts </dev/null
#   → 루트 CA 를 PEM 으로 저장 후 certs/server_ca.c 의 SERVER_CA_PEM 에 반영
#   (SERVER_CA_PEM_LEN = sizeof(...) , 종결 NUL 포함)

cmake -S firmware -B firmware/build -G Ninja \
      -DCMAKE_TOOLCHAIN_FILE=firmware/cmake/arm-none-eabi-toolchain.cmake
cmake --build firmware/build --target sht30_fw   # → sht30_fw.elf / .bin / .hex

10. 에어갭 전달 · 플래시 · 콘솔 확인

무결성 해시 + 신뢰 매체 전달

sha256sum firmware/build/sht30_fw.bin > FW_HASHES.txt   # 빌드 머신
# USB 등 신뢰 매체로 격리 호스트에 전달 후 재계산 대조

ST-Link 플래시 (격리 호스트)

pwsh firmware/scripts/flash.ps1                 # 권장(자동 탐지)
# 대안:
st-flash write sht30_fw.bin 0x08000000
STM32_Programmer_CLI -c port=SWD -w sht30_fw.hex -v -rst

콘솔 로그 확인 (USART3 PD8/PD9, 115200 8N1)

외부 USB-UART 어댑터를 연결하고 부팅 시퀀스를 관찰합니다:

bsp_init → 링크업 → DHCP(또는 static) → SNTP 시간 동기
        → TLS 핸드셰이크 → 첫 startup POST → 서버 HTTP 200

I²C1 0x44 응답 · 첫 온/습도 측정 · 상태 LED(PD12) 패턴을 함께 확인. 서명 불일치(403)면 API_KEY↔APP_API_KEY, TLS 실패면 server_ca.c/SNTP를 재점검.

11. 최종 검증 (종단)

서버에서 아래 화면을 확인합니다.

https://your-domain.example/raspi_leck_detecter/setup_wizard.php
https://your-domain.example/raspi_leck_detecter/dashboard.php
https://your-domain.example/raspi_leck_detecter/monthly_report.php
https://your-domain.example/raspi_leck_detecter/security_evidence.php

12. 문제 해결

13. 운영자가 별도 보관할 값

• Cafe24 DB 이름 / 계정 / 비밀번호
• API_KEY = 펌웨어 APP_API_KEY
• Cafe24 SMS user id / secure key / 발신번호 / 수신자 번호
• 관리자 계정·원문 비밀번호·ADMIN_TOTP_SECRET
• 서버 업로드 경로, LAN NTP 서버 IP, 장비 ID(stm32-sht30-01)와 설치 위치

부록 — 저장소 내 기존 이미지 자산 (레거시 · 참고용)

본 HTML 파일은 docs/ 폴더 기준 상대경로로 아래 자산을 참조할 수 있습니다(폴더 동반 시 표시됨):

현재 시스템의 정확한 아키텍처·배선은 본문 그림 1·7(생성 SVG)을 기준으로 하세요.