마르스텍 배터리 커넥터

# 마르스텍 비너스 커넥터 이 Homey 앱은 로컬 네트워크 또는 마르스텍 클라우드 서비스를 통해 마르스텍 비너스 배터리 시스템에 연결하고 배터리 통계를 수집합니다. 이를 통해 Homey 스마트 홈 시스템에서 배터리 상태, 충전 수준 및 기타 관련 정보를 직접 모니터링할 수 있습니다. 플로우를 사용하면 배터리 모드를 변경하는 명령을 보낼 수 있습니다(로컬 API만 해당). 마르스텍 비너스 배터리를 찾으려는 자동 감지 알고리즘이 있습니다. ## 기능 장치가 감지되고 통신이 작동할 때, 장치는 다음과 같은 다양한 통계를 표시합니다: - 배터리 충전 수준 - 상태(충전 중, 방전 중, 대기) - 남은 전력(킬로와트/시간) - 그리드/비그리드 전력 - 현재 전력 출력 또는 섭취량(와트) - 배터리 온도 - 충전 및 방전 총계(kWh) '수동', 'AI', '수동', '자동' 모드로 작동 모드를 변경하기 위해 배터리에 명령을 보낼 수도 있습니다. 이러한 명령은 Homey 플로우를 사용하여 전송할 수 있습니다('그러면...'). ## 요구 사항 이 앱은 Homey와 마르스텍 비너스 배터리 시스템이 필요합니다. - **로컬 API 드라이버**를 사용할 때 Homey와 배터리는 로컬 API가 활성화된 동일한 네트워크에 연결되어야 합니다(아래 참조). 마르스텍 비너스 배터리는 동일한 로컬 네트워크에서 자동으로 감지되며 IP 범위가 192.168.x.y 일 때 마지막 옥텟(y) 내에서 1에서 254까지 검색합니다. - **클라우드 드라이버**를 사용할 때는 활성화된 마르스텍 클라우드/앱 계정이 필요합니다. 페어링 중에 Homey는 마르스텍 클라우드 서비스와 인증하기 위해 사용자 이름과 비밀번호를 묻습니다. ### 장치 페어링 (클라우드) 페어링 중 "Marstek Venus (Cloud)" 장치를 선택하고 마르스텍 클라우드 인증 정보로 로그인한 후 추가할 사이트/장치를 선택하세요. 인증 정보는 장치 저장소에 안전하게 저장되며 마르스텍 클라우드 엔드포인트에서 배터리 통계를 새로 고치는 데에만 사용됩니다. ### 장치 페어링 (로컬 API) 로컬 API는 기본적으로 비활성화되어 있으며, 마르스텍 비너스 배터리 시스템에서 활성화해야 합니다. 이는 다음 두 가지 방법으로 할 수 있습니다: - 배터리 근처에서 스마트폰(또는 노트북)으로 BLE 테스트 툴(https://rweijnen.github.io/marstek-venus-monitor/latest/) 사용. '시스템' 탭에서 'Enable Local API (30000)' 버튼을 사용하여 연결 및 사용. - 마르스텍 지원팀에 연락하여 로컬 API를 활성화 요청. 처리에 며칠이 걸릴 수 있습니다. *로컬 API는 각 장치의 포트 번호 30000에서 활성화되어야 합니다. 현재 다른 포트 번호는 지원되지 않습니다.* ## 단계별 안내 1. Homey 앱 스토어에서 Marstek Homey 앱을 설치하세요. 2. Marstek 배터리 커넥터를 사용하여 새 장치를 추가하세요. 3. 연결할 유형을 선택하세요: - API용: 시스템이 자동으로 감지합니다. - 클라우드용: 앱/클라우드 인증 정보를 입력하고 자동으로 감지하도록 하세요. 4. 추가할 모든 장치를 선택/확인하고 계속 클릭하여 Homey에 추가하세요. 5. 배터리 통계가 검색되어 장치 카드에 표시되는 마법을 확인하세요. API 및 클라우드에서 장치를 사용할 수 있습니다. 각 배터리의 설정에서 추가 세부사항을 확인하세요. ## 버전 기록 - 0.8.10 - 커뮤니티 피드백에 기반하여 하드웨어/펌웨어 조합에 대한 기본 요인 수정 적용. 장치 검색 중에 기본적으로 true로 설정된 방송 설정. 앱 업데이트 시 누락된 요인은 기본값으로 설정됩니다. - 0.8.9 - API 데이터를 받을 때 적용되는 모든 요인을 구성 가능하게 함. 서로 다른 하드웨어 및 펌웨어 버전을 위한 기본 요인도 포함. - 0.8.8 - UDP 방송 또는 개별 배터리에 개별 UDP 패키지 전송이 구성 가능(기본값은 방송으로 설정). - 0.8.7 - 'ES.GetStatus' 메시지는 더 이상 UDP 방송을 사용하지 않고 장치의 IP 주소로 직접 타겟팅하여 장치 당 하나의 요청을 보냄. - 0.8.6 - 메시지 세부사항의 소스가 구성된 소스와 일치하지 않을 때 디버깅 추가. - 0.8.5 - Marstek Venus 호환성을 개선하기 위해 추가 디버깅 로그가 추가됨. 이 앱의 TEST 버전에서만. - 0.8.4 - 이전 버전에서 Homey 앱을 업그레이드할 때 항상 폴링 간격을 결정할 수 없으며, 기본 간격 값을 추가함. - 0.8.3 - 로컬 API에서 데이터가 처리되지 않게 하는 버그 제거. 앱의 테스트 버전은 항상 디버그 플래그 설정. - 0.8.2 - 로컬 API 장치의 페어링 중 기본 설정을 제공할 수 있음. 클라우드 로그인 시 문자열 이스케이핑 추가. 메시지에 대한 고유 id는 16비트 정수로 제한. - 0.8.1 - **[현재 라이브 릴리스]** 로컬 API에서 데이터 폴링을 비활성화하기 위한 설정 추가, 하지만 배터리 명령을 보내는 플로우는 여전히 가능하여 CT002/CT003과 함께 사용할 때 통신 문제를 완화하기 위한 것. - 0.8.0 - 코드 구조 변경 및 깃허브 정리. 소스를 TypeScript로 전환. - 0.7.6 - Marstek 클라우드 서비스의 초기 응답이 느릴 때 클라우드 데이터가 업데이트 중단됨, 동시성 문제 초래. - 0.7.5 - 잘못된 Marstek 클라우드 비밀번호는 앱을 먼저 제거하지 않으면 수정할 수 없음. Marstek 클라우드 서비스의 기술적 오류가 정확히 잡히지 않음. - 0.7.4 - 같은 펌웨어에서 보고된 온도가 다른 곱셈기로 보고됨, 정신계산 추가. Marstek 클라우드 로그인 문제는 정상적으로 처리되지 않음. - 0.7.3 - 여러 장치가 있는 사용자의 경우 클라우드 로그인이 실패할 수 있음. 몇 가지 번역 추가. - 0.7.2 - 펌웨어 154의 온도가 잘못 보고됨. 배터리 모드를 설정하는 플로우 카드에 재시도 메커니즘 추가. 일부 라이브러리 클래스의 가독성 개선. - 0.7.1 - 로컬 API를 통해 배터리 충전 모드를 변경하는 플로우 카드 추가. - 0.7.0 - 마르스텍 클라우드 계정 자격 증명을 사용하여 배터리 통계를 가져오는 마르스텍 클라우드 드라이버 지원 추가. - 0.6.3 - 배터리에서 마지막 메시지를 받은 초 수를 모니터링하는 속성 추가. 사용자 정의 기능에 대한 아이콘 추가. - 0.6.2 - 펌웨어 설정이 잘못된 설정 유형으로 저장되었음. - 0.6.1 - 펌웨어 154가 다른 곱셈기로 값을 통신하는 것 같음. 앱은 이제 펌웨어를 감지하고 이를 수정합니다. - 0.6.0 - 자동 재연결 및 브로드캐스트 시 리스너가 더 이상 사용할 수 없을 때 포트 바인딩을 재시도 구현. 동시에 연결을 시도하는 여러 장치의 에러 수정. 여러 곳에서 발생한 기타 사소한 버그 수정. - 0.5.7 - Homey 기능 설정을 비동기 호출로 올바르게 구현. - 0.5.6 - 종료 이벤트 처리 중 스코프가 더 이상 사용 가능하지 않은 것 같음, 따라서 종료 이벤트 로그는 이제 콘솔에 하드코딩됨. - 0.5.5 - 소켓 UDP dgram에 파괴 함수가 없어 앱 제거 중 충돌을 유발함. - 0.5.4 - 연결성 문제를 잡아내기 위해 로그 구조 변경. 클린업 함수 문제 해결. - 0.5.3 - 브로드캐스트 IP 주소 검색에 버그 수정 적용(주소가 발견되지 않았을 때 문제 유발). - 0.5.2 - 배터리에 모든 메시지에 고유 증가 id 추가. 메시지에서 세부사항을 홈이 기능값으로 가져오는 방식 재구조화. UDP 리스너 제거를 위한 추가 onUninit 처리. 배터리에서 받은 더 많은 기능 추가(확인되지 않음). - 0.5.1 - 소켓 바인딩 및 브로드캐스트 플래그 설정에서의 오류를 패치하여 향후 포트 바인딩 오류 디버깅을 용이하게 함. 발견 중 문제를 유발한 일부 필수 설정 제거. - 0.5.0 - 배터리 API 및 에너지 시스템에서 추가 읽기 추가, 이제 홈이에 가이드라인으로 시각화됩니다. (이전 역사 세부정보는 생략함) ## 노트 - 이 앱은 API 문서에 언급된 'UDP 기반 API' 기능을 사용합니다. - 이 앱은 비너스 E v2.0 배터리 시스템(펌웨어 v153, 커뮤니케이션 모듈 202409090159)으로 개발 및 테스트되었습니다. 다른 모델도 작동하면 알려주세요! - 장치가 자동으로 감지되지 않을 경우, 마르스텍 비너스 배터리가 켜져 있으며 Homey와 동일한 네트워크에 연결되어 있는지 확인하세요. - 여러 마르스텍 비너스 배터리에 대한 지원이 구현되었지만, 테스트할 배터리가 하나밖에 없어 일부는 미지의 영역입니다. - 로컬 API에서는 현재 UDP 포트 30000만 지원됩니다. - 앱을 업그레이드할 때 처음에 추가된 배터리 장치를 제거한 후 다시 추가해야 할 수도 있습니다. - 마르스텍 클라우드 API는 문서화되지 않아, 사전 고지 없이 변경될 수 있습니다. - 배터리 모드 변경에는 최대 5회 재시도 및 15초의 타임아웃이 자동으로 있습니다. ## 알려진 문제 - 간혹 UDP 통신이 경고 없이 멈춥니다. - 전송된 모든 UDP 패키지가 배터리에서 응답을 받지는 않습니다(배터리가 이를 침묵 속에서 무시함). - CT002 또는 CT003과 같이 사용할 때 배터리가 통신을 중단하는 것처럼 보입니다. - 클라우드 데이터가 백업 전원 포트를 제대로 고려하지 않음(1와트로 표시됨). - 클라우드 장치를 사용할 때 앱이 로그아웃되는 것처럼 보입니다(마르스텍에서 단일 로그인 토큰만 허용됨). # 문제 해결 배터리의 로컬 API는 약간의 통신 문제가 있습니다. 모든 UDP 메시지에 응답하지 않으며 동시에 배터리와 통신하기 위한 다른 방법을 사용할 때 충돌이 발생하는 것 같습니다. 시간이 지남에 따라 통신이 저하되어 완전히 중단되는 경우가 있습니다. 펌웨어 154를 사용하는 사용자는 문제를 덜 보고하고 있습니다. 통신은 BLE 테스트 툴(https://rweijnen.github.io/marstek-venus-monitor/latest/) v2.0을 '고급' 탭의 '시스템 재설정' 기능을 사용하여 재시작할 수 있습니다. 전력 공급이 짧은 순간 동안 중단되며, 이후 통신 스택이 다시 모든 메시지에 응답합니다.