만들기
Home Assistant 센서를 내 정원에 연결하기
Home Assistant에 이미 연결된 온습도·토양수분·CO₂ 센서를 SeasonsInGarden 통합 구성요소로 Open API에 전송하는 방법입니다.
집에 Home Assistant를 쓰고 있다면 이미 온습도계나 토양수분 센서 몇 개쯤은 연결되어 있을 겁니다. 이 센서들을 내정원의 사계절로 보내려고 보드를 새로 만들 필요는 없습니다. SeasonsInGarden 통합 구성요소를 설치하면 Home Assistant가 고른 센서의 값을 5분마다 Open API로 전송합니다.
완성하면 앱의 센서 관리 화면에 센서가 나타나고, 구역과 식물에 연결해 아두이노나 Ecowitt 센서와 똑같이 쓸 수 있습니다. 코드는 한 줄도 쓰지 않고 Home Assistant 화면에서 설정만 하면 됩니다.
직접 보드를 만들고 싶다면 아두이노로 만든 센서를 내 정원에 연결하기를 참고하세요. 전송 형식과 서명 규칙은 같습니다.
통합 구성요소의 코드는 GitHub에 공개되어 있습니다 — four-seasons-of-mygarden/ha-seasonsingarden
준비물
| 항목 | 설명 |
|---|---|
| Home Assistant | 2025.8 이상. 설정 → 정보에서 버전을 확인할 수 있습니다. |
| HACS | Home Assistant 커뮤니티 스토어입니다. 없으면 수동으로 설치할 수도 있습니다. |
| Open API 키 | 앱에서 발급하는 Access Key와 Secret Key입니다. |
| 보낼 센서 | Home Assistant에 연결된 온도·습도·토양수분·CO₂ 센서 등 |
1. API 키 발급
앱에서 다음 순서로 이동합니다.
MY → 설정 → 센서 관리 → 오른쪽 위 + 버튼OpenAPI를 선택하고 Key 이름을 입력한 뒤 저장합니다. 거실 Home Assistant처럼 알아보기 쉽게 지으면 됩니다. 저장하면 Access Key와 Secret Key가 발급됩니다.
Secret Key는 발급 시점에 한 번만 제공됩니다. CSV 파일을 반드시 저장해 두세요. 자세한 내용은 나만의 센서 데이터를 Open API로 전송하기에 정리되어 있습니다.
키 발급은 기기를 등록하는 단계입니다. 아두이노 보드 등 다른 기기에 쓰고 있는 키가 있더라도 Home Assistant용 키를 따로 발급받으세요.
2. 통합 구성요소 설치
HACS로 설치하기
HACS가 설치된 Home Assistant라면 아래 버튼을 누릅니다. 처음 한 번은 Home Assistant 주소를 묻고, 이후에는 HACS의 SeasonsInGarden 페이지가 바로 열립니다.
- 열린 페이지에서 오른쪽 아래 Download를 누릅니다.
- 설치가 끝나면 Home Assistant를 재시작합니다. 설정 → 시스템 → 오른쪽 위 전원 아이콘 → 재시작
버튼을 쓸 수 없다면 직접 추가합니다.
- HACS → 오른쪽 위 ⋮ → Custom repositories
- Repository에
https://github.com/four-seasons-of-mygarden/ha-seasonsingarden, Type은 Integration을 선택하고 Add - HACS 검색창에
SeasonsInGarden을 입력해 설치하고 재시작합니다.
SeasonsInGarden은 HACS 기본 스토어 등록을 기다리고 있습니다. 등록이 끝나면 저장소 주소를 넣지 않고 HACS에서 바로 검색할 수 있습니다.
수동으로 설치하기
HACS를 쓰지 않는다면 저장소의 custom_components/seasonsingarden 폴더를 Home Assistant 설정 폴더(configuration.yaml이 있는 곳)의 custom_components/ 아래에 복사하고 재시작합니다.
config/
├── configuration.yaml
└── custom_components/
└── seasonsingarden/3. 연결 설정
재시작한 뒤 설정 → 기기 및 서비스 → 통합 구성요소 추가에서 SeasonsInGarden을 검색합니다. 아래 버튼으로 바로 시작할 수도 있습니다.
설정은 세 화면으로 끝납니다.
키 입력
| 항목 | 입력할 값 |
|---|---|
| 기기 이름 | 전송할 때 함께 보내는 이름입니다. 거실 Home Assistant처럼 씁니다. |
| Access Key | CSV의 Access Key |
| Secret Key | CSV의 Secret Key |
제출을 누르면 입력한 키로 서버에 확인 요청을 보냅니다. 키가 틀리면 이 화면에서 바로 알려 줍니다.
전송할 센서 고르기
Home Assistant의 센서 중 보낼 수 있는 센서만 목록에 나타납니다. 최대 10개까지 고를 수 있습니다. 전송 주기는 5~60분 사이로 정하며 기본값은 5분입니다.
목록에 무엇이 나오고 무엇이 빠지는지는 4. 전송할 수 있는 센서에서 설명합니다.
측정 항목과 필드 이름 정하기
고른 센서가 한 화면에 모두 나오고, 센서마다 두 가지를 정합니다.
| 항목 | 설명 |
|---|---|
| 측정 항목 | 온도, 습도, 토양습도 등. 센서 종류와 단위를 보고 미리 채워집니다. |
| 필드 이름 | 앱에서 센서를 구분하는 이름입니다. 영문, 숫자, _, -로 50자까지 씁니다. |
필드 이름은 엔티티 ID로 미리 채워지니 그대로 둬도 됩니다. 다만 한 번 정한 필드 이름은 바꾸지 않는 것이 좋습니다. 이름을 바꾸면 앱에는 새 센서로 등록되고, 이전 기록은 원래 센서에 남습니다. 앱에 보이는 이름만 바꾸고 싶다면 앱의 센서 설정에서 표시 이름을 고치세요.
나중에 센서를 추가하거나 빼려면 통합 구성요소의 구성 버튼을 누르면 같은 화면이 다시 열립니다.
4. 전송할 수 있는 센서
Home Assistant 센서에는 **종류(device class)**와 단위가 붙어 있습니다. 통합 구성요소는 이 두 가지를 보고 서버가 받는 측정 항목에 맞는 센서만 보여 줍니다.
| 측정 항목 | 서버 단위 | 목록에 나오는 Home Assistant 센서 |
|---|---|---|
| 온도 | °C | 온도 센서 (°C, °F, K) |
| 습도 | % | 습도·수분 센서 |
| 토양습도 | % | 수분·습도 센서 |
| 광량(PPFD) | μmol/m²/s | 단위가 μmol/m²/s인 센서, 조도 센서 (lx) |
| 물온도 | °C | 온도 센서 (°C, °F, K) |
| 이산화탄소 | ppm | CO₂ 센서 |
| 토양온도 | °C | 온도 센서 (°C, °F, K) |
| VPD | kPa | 압력 단위 센서 (kPa, hPa, Pa, psi 등) |
| EC | dS/m | 전도도 센서 (μS/cm, mS/cm, dS/m) |
단위가 달라도 전송할 때마다 서버 단위로 바꿔서 보냅니다. 화씨로 표시하는 온도계는 섭씨로, μS/cm로 표시하는 EC 센서는 dS/m로 환산됩니다.
몇 가지 알아 둘 점이 있습니다.
- 온도 센서는 기본값이 ’온도’입니다. 수조에 넣은 온도계나 흙에 꽂은 온도계라면 ’물온도’나 ’토양온도’로 바꿔 주세요. Home Assistant는 이 셋을 구분하지 않습니다.
- % 단위는 습도·수분 센서만 나옵니다. 배터리 잔량이나 공기청정기 필터 잔량도 %를 쓰기 때문에 종류가 없는 % 센서는 목록에서 뺐습니다. 많은 토양 센서가 토양수분을 ’습도’로 보고하므로, 두 종류 모두 습도와 토양습도 중에서 고를 수 있습니다.
- 조도(lx) 센서는 광원을 골라 PPFD로 바꿔 보냅니다. 같은 밝기라도 광원에 따라 PPFD가 달라서, 센서 이름 정하기 화면에서 조도 센서에만 광원 칸이 더 나옵니다. 광원별 계수와 그 이유는 광 센서 글의 광원 프로필과 같습니다. 자연광과 식물등이 섞이는 자리라면 사용자 보정을 고르고 PAR 센서로 잰
PPFD ÷ lux값을 직접 넣으세요. - 식물 센서의 ’전도도’는 조심하세요. Mi Flora 같은 식물 센서의 전도도는 흙의 비옥도를 나타내는 지표라, 양액의 EC와 같은 값으로 읽으면 안 됩니다.
원하는 센서가 목록에 없다면 Home Assistant의 개발자 도구 → 상태에서 그 센서의 unit_of_measurement와 device_class를 확인해 보세요. 단위가 위 표와 다르거나 % 센서에 종류가 비어 있다면, 템플릿 센서로 단위와 종류를 붙여 주면 목록에 나타납니다.
5. 전송이 동작하는 방식
정한 주기마다 고른 센서의 그 순간 값을 모아 요청 하나로 보냅니다.
{
"device_name": "거실 Home Assistant",
"date": "2026-09-29 03:00:00",
"sensors": [
{ "field_nm": "living_temperature", "category": "01", "data": "24.5" },
{ "field_nm": "living_humidity", "category": "02", "data": "58" },
{ "field_nm": "pot_moisture", "category": "07", "data": "41" }
]
}date는 한국 시간이 아닌 UTC입니다. 서명 규칙은 아두이노 예제와 같습니다.- 센서가 사용 불가 상태이거나 숫자가 아닌 값이면 그 센서만 빼고 보냅니다.
- 전송에 실패하면 다음 주기에 다시 보냅니다. 실패한 값을 쌓아 두었다가 한꺼번에 보내지는 않습니다.
- 키가 거부되면 전송을 멈추고 Home Assistant에 재인증 알림을 띄웁니다. 새 키를 입력하면 다시 전송을 시작합니다.
- Home Assistant를 재시작하면 한 주기가 지난 뒤 첫 전송을 합니다.
5분보다 짧은 주기로 보내면 서버에서 받지 않으므로 주기는 5분 이상으로만 정할 수 있습니다.
평균값을 보내고 싶을 때
온도나 토양수분처럼 천천히 변하는 값은 순간값으로 충분합니다. 하지만 구름이 지날 때마다 크게 출렁이는 광량은 순간값보다 5분 평균이 정확합니다.
이럴 때는 Home Assistant 기본 기능인 통계 도우미로 평균 센서를 만들어 그 센서를 대신 보내면 됩니다.
- 설정 → 기기 및 서비스 → 도우미 → 도우미 만들기 → 통계
- 원본 센서를 고르고, 특성은 평균(선형), 최대 기간은 5분으로 정합니다.
- SeasonsInGarden의 구성에서 새로 만든 통계 센서를 고릅니다.
6. 동작 확인하기
통합 구성요소를 추가하면 전송 상태를 보여 주는 센서 세 개가 함께 생깁니다. 설정 → 기기 및 서비스 → SeasonsInGarden → 기기에서 볼 수 있습니다.
| 센서 | 내용 |
|---|---|
| 마지막 전송 성공 | 마지막으로 전송에 성공한 시각 |
| 마지막 전송 결과 | 성공, 보낼 값 없음, 인증 실패, 요청 거부, 오류 |
| 전송한 센서 수 | 마지막 전송에 포함된 센서 수 |
첫 주기가 지나 마지막 전송 결과가 ’성공’이 되면, 앱의 센서 관리 화면에서 발급한 키 아래로 센서가 나타납니다. 센서마다 표시 이름과 설치한 구역을 지정하고 식물과 연결하면 식물 상세 화면에서 값을 볼 수 있습니다.
상태 센서는 자동화에도 쓸 수 있습니다. 예를 들어 ’마지막 전송 결과’가 ’성공’이 아닌 상태로 30분 넘게 유지되면 휴대폰으로 알림을 보내도록 만들어 두면, Wi-Fi나 키 문제를 빨리 알아챌 수 있습니다.
요청과 응답을 자세히 보고 싶다면 configuration.yaml에 다음을 추가하고 재시작합니다. 로그는 설정 → 시스템 → 로그에서 볼 수 있습니다.
logger:
logs:
custom_components.seasonsingarden: debug자주 막히는 곳
통합 구성요소 추가에서 검색되지 않습니다
설치한 뒤 Home Assistant를 재시작했는지 먼저 확인하세요. 새로고침만으로는 인식되지 않습니다. 재시작한 뒤에도 보이지 않으면 브라우저를 강력 새로고침하거나, 앱이라면 완전히 종료했다가 다시 여세요. Home Assistant 버전이 2025.8보다 낮아도 설치되지 않습니다.
‘Access Key 또는 Secret Key가 올바르지 않습니다’
같은 CSV 파일의 Access Key와 Secret Key인지, 앱에서 키를 삭제하지 않았는지 확인하세요. 붙여 넣을 때 앞뒤 공백이나 CSV의 따옴표가 섞여 들어가는 경우도 흔합니다.
인증 오류가 계속 납니다
Home Assistant가 돌아가는 기기의 시각을 확인하세요. 요청 시각이 서버 시각과 5분 넘게 차이 나면 서명이 맞아도 거부됩니다.
결과가 ’보낼 값 없음’입니다
고른 센서가 모두 사용 불가 상태이거나, 설정한 뒤 센서의 단위가 바뀐 경우입니다. 개발자 도구 → 상태에서 센서 값과 단위를 확인하세요.
전송은 성공하는데 앱에 센서가 없습니다
키를 발급한 장소를 앱에서 선택하고 있는지 확인하고 센서 관리 목록을 새로고침하세요.
더 해볼 것
Home Assistant에는 Zigbee, Wi-Fi, 블루투스로 연결되는 저렴한 센서가 많습니다. 토양수분 센서 하나를 화분마다 꽂아 두고 이 통합 구성요소로 보내면, 보드를 만들지 않고도 화분별 물주기 기록을 앱에서 볼 수 있습니다. 물주기 알림을 함께 쓰려면 토양수분 물주기 알림 가이드를 참고하세요.