DIVUS VISION API 소프트웨어

명세서

• 제품: DIVUS VISION API
• 제조사: DIVUS GmbH
• 버전: 1.00 REV0 1 – 20240528
• 위치: Pillhof 51, Eppan (BZ), 이탈리아

제품 정보

DIVUS VISION API는 DIVUS VISION 시스템과의 인터페이스를 위해 설계된 소프트웨어 도구입니다. 이를 통해 사용자는 MQTT 프로토콜을 사용하여 시스템 내의 다양한 요소에 액세스하고 제어할 수 있습니다.

자주 묻는 질문

Q: PC나 자동화 기술에 대한 사전 지식 없이도 DIVUS VISION API를 사용할 수 있나요?

A: 이 매뉴얼은 API의 효율적인 사용을 보장하기 위해 해당 분야에 대한 사전 지식을 갖춘 사용자를 위해 맞춤화되었습니다.

일반 정보

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – 이탈리아

사용 설명서, 설명서 및 소프트웨어는 저작권으로 보호됩니다. 판권 소유. 전체 또는 일부를 복사, 복제, 번역, 번역하는 것은 허용되지 않습니다. 개인적인 용도로 소프트웨어의 백업 사본을 생성하는 경우에는 예외가 적용됩니다.
설명서는 예고 없이 변경될 수 있습니다. 당사는 본 문서와 제공된 저장 매체에 포함된 데이터에 오류가 없고 정확하다는 점을 보장할 수 없습니다. 개선을 위한 제안이나 오류에 대한 힌트는 언제나 환영합니다. 계약은 본 매뉴얼의 특정 부록에도 적용됩니다. 본 문서의 명칭은 제3자가 자신의 목적으로 사용하는 경우 해당 소유자의 권리를 침해할 수 있는 상표일 수 있습니다. 사용자 지침: 처음 사용하기 전에 이 설명서를 읽고 나중에 참조할 수 있도록 안전한 장소에 보관하십시오. 대상 그룹: 이 매뉴얼은 PC 및 자동화 기술에 대한 사전 지식이 있는 사용자를 위해 작성되었습니다.

프레젠테이션 컨벤션

소개

일반 소개

이 매뉴얼은 외부 시스템에서 VISION을 처리하고 제어할 수 있는 인터페이스인 VISION API(응용 프로그래밍 인터페이스)에 대해 설명합니다.
실제로 이는 다음과 같은 시스템을 사용할 수 있음을 의미합니다.

• MQTT 탐색기(https://www.microsoft.com/store/… - 시험용),
• 홈어시스턴트(https://www.home-assistant.io/) 또는
• 노드-RED(https://nodered.org/)

VISION에서 관리하는 요소를 제어하거나 상태를 읽어옵니다. 액세스 및 통신은 소위 주제를 사용하여 개별 기능 또는 기능 세트를 처리하거나 해당 기능의 변경 사항에 대한 정보를 받는 MQTT 프로토콜을 통해 이루어집니다. 이러한 목적으로 MQTT 서버(브로커)가 사용되며, 보안 및 참가자에 대한 메시지 관리/배포를 처리합니다. 이 경우 MQTT 서버는 DIVUS KNX IQ에 직접 위치하며 이 목적을 위해 특별히 구성됩니다. VISION API는 프로그래밍 지식 없이도 사용할 수 있지만 이 기능은 고급 사용자에게 적합합니다.

전제 조건

VISION 매뉴얼에 설명된 대로 API 사용자는 기본적으로 먼저 활성화되어야 API 액세스가 API 사용자 인증 데이터를 통해서만 작동합니다. 사용자 권한과 관련하여 이 기능에 대한 활성화는 모든 요소 또는 개별 요소에 대해 구성될 수 있습니다. 0장을 참조하세요. 물론 외부에서 제어하려는 요소가 완전히 구성되고 해당 요소에 대한 연결이 성공적으로 테스트된 VISION 프로젝트도 필요합니다. API를 통해 개별 요소를 처리하려면 해당 요소 ID를 알아야 합니다. 이는 요소 설정 양식 하단에 표시됩니다.

보안

보안상의 이유로 API 액세스는 로컬에서만 가능합니다(예: 클라우드를 통하지 않음). 따라서 API 액세스 활성화 시 보안 위험은 낮습니다. 그럼에도 불구하고 API 액세스에 대해 보안 관련 요소를 활성화하거나 명시적으로 거부해서는 안 됩니다.

MQTT 및 해당 용어 – 간단한 설명

• MQTT에서 모든 메시지의 중앙 집중식 관리 및 배포 역할은 브로커의 역할입니다. MQTT 서버와 MQTT 브로커는 동의어가 아니지만(서버는 MQTT 클라이언트도 수행할 수 있는 역할을 가리키는 더 넓은 용어임), 이 설명서에서 MQTT 서버가 언급될 때 항상 브로커를 의미합니다. DIVUS KNX IQ 자체는 이 매뉴얼의 맥락에서 MQTT 브로커/MQTT 서버 역할을 수행합니다.
• MQTT 서버는 데이터가 분류, 관리 및 게시되는 계층 구조인 소위 주제를 사용합니다.
• 게시의 주요 목표는 주제를 통해 다른 참가자가 데이터를 사용할 수 있도록 하는 것입니다. 값을 변경하려면 게시 작업을 사용하여 원하는 값 변경과 함께 원하는 주제에 씁니다. 대상 장치 또는 MQTT 서버는 영향을 미치는 원하는 변경 사항을 읽고 그에 따라 채택합니다. 변경 사항이 적용되었는지 확인하려면 구독한 실시간 주제를 살펴보고 변경 사항이 반영되었는지, 즉 모든 것이 제대로 작동했는지 확인할 수 있습니다.
• 고객은 관심 있는 주제를 선택합니다. 이를 구독이라고 합니다. 주제 내/하위에서 값이 변경될 때마다 구독한 모든 클라이언트에 알림이 전달됩니다. 즉, 변경된 내용이 있는지 또는 현재 값이 무엇인지 명시적으로 묻지 않고도 알 수 있습니다.
• 주제에 client_id라는 고유 문자열을 입력하여 MQTT 서버와의 별도 통신 채널을 열거나 주소를 지정할 수 있습니다. 값을 처리하려면 주제에서 client_id를 사용해야 합니다. 이는 각 변경 사항의 출처를 식별하고, 오류를 해결하는 데 도움이 되며, 오류 코드 및 메시지를 포함하여 서버의 해당 응답도 동일한 client_id를 가진 주제에만 도달하므로 다른 클라이언트에 영향을 주지 않습니다. 그 클라이언트). client_id는 0-9, az, AZ, "-", "_" 문자의 조합으로 구성된 고유한 문자열입니다.
• 일반적으로 DIVUS KNX IQ MQTT 서버의 구독 주제에는 키워드 상태가 포함되고 게시 주제에는 키워드 요청이 포함됩니다. 상태가 있는 항목은 외부 값이 변경되거나 게시를 통해 클라이언트 자체에서 값 변경을 요청하고 성공적으로 적용되는 즉시 자동으로 업데이트됩니다. 게시용 항목은 (request/)get 유형과 (request/)set 유형으로 더 구분됩니다.
• 값 변경 및 기타 선택적 매개변수가 소위 페이로드와 함께 주제에 추가됩니다. 개별 요소의 매개변수(요소 ID, 이름, 유형, 기능)

MQTT와 클라이언트가 데이터를 요청한 후 변경하는 클래식 클라이언트-서버 모델의 주요 차이점은 구독 및 게시 개념에 있습니다. 참가자는 데이터를 게시하여 다른 사람이 사용할 수 있도록 하고 관심이 있는 경우 구독할 수 있습니다. 이 아키텍처를 사용하면 데이터 교환을 최소화하고 모든 이해관계자를 최신 상태로 유지할 수 있습니다. 자세한 내용은 여기를 참조하세요. 특수 매개변수(uuid, 필터)가 여기에서 사용됩니다. 여러 가지 옵션이 있지만 이 매뉴얼에서는 페이로드가 JSON 형식으로 표시됩니다. JSON은 대괄호와 쉼표를 사용하여 모든 구조의 데이터를 나타내므로 전송되는 데이터 패킷의 크기를 최소화합니다. 페이로드에 대한 자세한 내용은 설명서 뒷부분에서 확인할 수 있습니다.

• 특별한 목적을 위해 기능 유형에 따라 필터링하는 것이 가능합니다(예: 1비트 스위치 등 on/off만 주소 지정). 페이로드의 필터 매개변수는 이 목적으로 사용됩니다. 필터링은 현재 함수 유형별로만 가능합니다.
• 개별 요소를 처리하려면 해당 요소 ID가 필요합니다. 이는 요소 속성 메뉴의 VISION에서 찾을 수도 있고 MQTT 탐색기의 일반 구독에서 사용 가능한 각 요소 앞에 표시되는 데이터에서 직접 읽을 수도 있습니다(요소는 요소 ID별로 알파벳순으로 나열되어 있음).

API 액세스 구성

API 사용자 액세스를 위한 비전 구성

VISION에서 관리자로 구성 – 사용자/API 액세스 관리로 이동하여 사용자/API 액세스를 클릭한 후 API 사용자를 마우스 오른쪽 버튼으로 클릭하거나 길게 눌러 편집 창을 엽니다. 거기에서 다음 매개변수와 데이터를 찾을 수 있습니다.

• 활성화(확인란)
  • 사용자는 여기에서 먼저 활성화됩니다. 기본값은 비활성화되어 있습니다.
• 사용자 이름
  • 이 문자열은 API를 통해 액세스하는 데 필요합니다. 여기에서 복사하세요.
• 비밀번호
  • 이 문자열은 API를 통해 액세스하는 데 필요합니다. 여기에서 복사하세요.
• 권한
  • VISION 요소의 값을 읽고 쓰기 위한 기본 권한은 여기에서 정의할 수 있습니다. 즉, 여기에 정의된 내용은 모든 기존 요소와 향후 요소에 적용됩니다. 개별 요소에 대한 액세스만 허용하려면 이러한 기본 권한을 변경하면 안 됩니다.

개별 요소에 대한 권한

전체 프로젝트에 API 액세스 권한을 부여하지 않고 원하는 요소에만 API 액세스 권한을 부여하는 것이 좋습니다. 다음과 같이 진행하세요

1. VISION에 관리자로 로그인
2. 원하는 요소를 선택하고 해당 설정 메뉴를 엽니다(마우스 오른쪽 버튼을 클릭하거나 길게 누른 다음 설정).
3. 일반 - 권한 메뉴 항목에서 "기본 권한 재정의"를 활성화한 다음 권한 매트릭스를 표시하는 권한 하위 항목으로 이동합니다.
4. 여기에서 제어 권한을 활성화하면 view 직접 허가. API 액세스를 통해서만 데이터를 읽으려면 view 허가.
5. 액세스하려는 모든 요소에 대해 동일한 절차를 반복하십시오.

MQTT를 통한 연결

소개

전직으로서amp여기에서는 Windows, Mac 및 Linux에서 사용할 수 있는 MQTT Explorer(1.1장 참조)라는 비교적 간단한 무료 소프트웨어를 사용하여 DIVUS KNX IQ의 MQTT API를 통한 액세스를 시연합니다. MQTT에 대한 기본 지식과 경험이 암시됩니다.

연결에 필요한 데이터

앞에서 언급한 것처럼(섹션 2.1 참조) API 사용자의 사용자 이름과 비밀번호가 필요합니다. 여기 오버가 있어요view 연결이 설정되기 전에 수집해야 하는 모든 데이터:

• 사용자 이름 API 사용자의 세부정보 페이지에서 읽습니다.
• API 사용자의 세부정보 페이지에서 비밀번호 읽기
• IP 주소 일반 – 네트워크 – 이더넷(또는 동기화 장치를 통해)의 실행 프로그램 설정에서 읽습니다.
• 포트 8884(이 포트는 이 용도로 예약되어 있음)

MQTT EXPLORER 및 일반 구독과의 첫 번째 연결

일반적으로 MQTT는 구독 활동과 게시 활동을 구별합니다. MQTT Explorer는 첫 번째 연결이 이루어질 때 사용 가능한 모든 주제(주제 #)를 자동으로 구독하여 이를 단순화합니다. 결과적으로, 사용 가능한 모든 요소(예: API 사용자 액세스 권한 부여)로 연결되는 트리는 성공적인 연결 후 MQTT Explorer 창의 왼쪽 영역에서 직접 볼 수 있습니다. 추가 구독 주제를 입력하거나 #을 보다 구체적인 주제로 바꾸려면 연결 창에서 고급으로 이동하세요. 오른쪽 상단에 표시된 주제는 다음과 같습니다.

여기서 7f4x0607849x444xxx256573x3x9x983은 API 사용자 이름이고 object_list에는 사용 가능한 모든 요소가 포함되어 있습니다. 이 주제는 항상 최신 상태로 유지됩니다. 즉, 모든 값 변경 사항이 실시간으로 반영됩니다. 개별 요소만 구독하려면 object_list/ 뒤에 원하는 요소의 요소 ID를 입력하세요.

참고: 이 유형의 구독은 대략 KNX 피드백 주소 뒤에 있는 논리에 해당합니다. 이는 요소의 현재 상태를 표시하며 원하는 변경 사항이 성공적으로 적용되었는지 확인하는 데 사용될 수 있습니다. 데이터를 읽기만 하고 변경하지 않으려면 이 유형의 구독이면 충분합니다.

단일 단순 요소는 JSON 표기법에서 다음과 같습니다.

참고: 모든 값은 위에 표시된 구문을 갖습니다. 예를 들어 구독 주제의 출력인 { “value”: “1” }은 값을 변경하기 위해 페이로드에 직접 기록되는 반면(예: 게시 주제의 경우) 대괄호 및 "value"는 생략됩니다. 예: "onoff": "1".

고급 명령

소개

일반적으로 3가지 종류의 주제가 있습니다.

1. 사용 가능한 요소를 확인하고 실시간 값 변경을 확인하려면 주제를 구독하세요.
2. 주제를 구독하면 (에 대한 답변을 얻을 수 있습니다.클라이언트 ) 게시 요청
3. 해당 값으로 요소를 가져오거나 설정하려면 주제를 게시하세요.

나중에 여기에 표시된 번호를 사용하여 이러한 종류를 참조할 것입니다(예: 유형 1, 2, 3의 주제). 자세한 내용은 다음 섹션과 챕터에서 확인하세요. 4.2.

사용 가능한 요소를 확인하고 실시간 가치 변화를 확인하려면 주제를 구독하세요.

이것들은 이미 설명되었습니다

고객의 게시 요청에 대한 답변을 얻으려면 주제를 구독하세요.

이런 종류의 주제는 선택 사항입니다. 이는 다음을 허용합니다.

• 임의의 client_id를 사용하여 MQTT 서버와의 고유한 통신 채널을 엽니다. 이에 대한 자세한 내용은 챕터에서 확인하세요. 4.2.2
• 해당 구독 주제에 대한 게시 요청 결과(오류 코드 및 메시지와 함께 성공 또는 실패)를 가져옵니다.

게시 명령을 얻거나 설정하기 위한 답변을 얻을 수 있는 다양한 주제가 있습니다. 이에 상응하는 차이는 시스템에 필요한 주제를 바로 얻은 후에는 이 단계를 제거하고 게시 주제를 직접 사용하기로 결정할 수 있습니다.

 해당 값으로 요소를 얻거나 설정하기 위한 주제 게시

이러한 주제는 구독과 유사한 경로를 사용합니다. 유일한 변경 사항은 구독에 사용되는 "상태" 대신 "요청"이라는 단어입니다. 전체 주제 경로는 나중에 챕터에 표시됩니다. 4.2.2\ get 주제는 MQTT 서버의 요소 및 값 읽기를 요청합니다. 페이로드는 요소의 기능 유형을 기반으로 필터링하는 데 사용될 수 있습니다. 설정된 주제는 페이로드에 자세히 설명된 대로 요소의 일부 부분을 변경하도록 요청합니다.

명령 및 해당 응답의 접두사

 간단한 설명

MQTT 서버로 전송되는 모든 명령에는 다음과 같은 공통된 초기 부분이 있습니다.

상해

실시간 주제(유형 1)에는 일반 접두사(위 참조)가 붙고 그 뒤에

or

set 명령의 경우 페이로드는 원하는 변경 사항(즉, 요소 ​​기능에 대한 변경된 값)을 포함하므로 분명히 주요 역할을 합니다. A 경고: KNX 측에서 문제가 발생할 수 있으므로 유형 3 명령에 보유 옵션을 사용하지 마십시오.

EXAMPLE: 단일 요소의 값 변경을 위해 게시

가장 간단한 경우는 일반 subscribe 에 표시된 요소 중 하나의 값을 변경하려는 것입니다.
일반적으로 MQTT를 통한 VISION의 기능 변경/전환은 3단계로 구성되며, 모든 단계가 반드시 필요한 것은 아니지만 설명된 대로 수행하는 것이 좋습니다.

1. 편집하려는 함수가 포함된 주제는 사용자 정의 client_id를 사용하여 구독됩니다.
2. 편집할 주제는 1에서 선택한 client_id를 사용하여 원하는 변경 사항이 포함된 페이로드와 함께 게시됩니다.
3. 확인하려면 주제 (1.)에서 답변을 볼 수 있습니다. 즉, (2.)가 작동했는지 여부입니다.
4. 변경 사항이 있을 때 모든 값이 업데이트되는 일반 구독에서는 모든 것이 제대로 작동하면 원하는 값 변경을 볼 수 있습니다.

이를 위한 단계는 다음과 같습니다.

1. client_id(예: "Divus")를 선택하고 API 사용자 이름 뒤의 경로에 삽입하세요.
   이는 MQTT 서버를 사용하여 자체 통신 채널을 구독하기 위한 전체 주제입니다. 이는 보내려는 변경 사항에 대한 응답이 예상되는 위치를 서버에 알려줍니다. a를 정의하는 상태/설정 부분을 확인하세요. 그것이 구독 주제라는 것과 b. set type 명령에 대한 답을 얻게 될 것입니다.
2. 게시 주제는 상태 요청 키워드 전환을 제외하고 동일합니다.
3. 변경 사항이 무엇으로 구성되어야 하는지는 페이로드에 기록됩니다. 여기 몇 가지 전이 있습니다.amp레.
   • 켜기/끄기 기능(1비트)이 있는 요소 끄기:
   • 켜기/끄기 기능(1비트)이 있는 요소를 켭니다. 또한 이러한 명령이 동일한 클라이언트에서 여러 개 시작되는 경우 uuid 매개변수("고유 ID", 일반적으로 128-8-4-4-4자리 12진수 형식의 XNUMX비트 문자열)를 사용하여 해당 쿼리에 대한 응답입니다. 이 매개변수가 쿼리에 있는 경우 응답에서도 찾을 수 있기 때문입니다.
   • 조광기의 밝기를 50%로 켜고 설정하기
   • 예를 들어 위에 표시되고 구독된 주제(정확히 말하면 해당 페이로드)에 대한 답변은 다음과 같습니다.amp르.
     위의 응답은 전직입니다.amp요소에 디밍 기능이 없지만 올바른 페이로드의 경우 파일입니다. 페이로드가 올바르게 해석되지 않는 더 심각한 문제가 있는 경우 응답은 다음과 같습니다(예:).
     오류 코드 및 메시지에 대한 설명은 일반적으로 http의 경우와 같이 200개 코드는 긍정적인 답변이고 400개는 부정적인 답변입니다.

EXAMPLE: 여러 요소 값 변경을 위해 게시

절차는 단일 요소를 변경하기 위해 이전에 표시된 절차와 유사합니다. 차이점은 주제에서 element_id를 생략한 다음 페이로드 내부의 데이터 앞에 element_id 집합을 표시한다는 것입니다. 아래 구문과 구조를 참조하세요.

쿼리에서 함수 유형별로 필터링

페이로드의 필터 매개변수를 사용하면 요소의 원하는 기능만 처리할 수 있습니다. 스위치나 조광기의 켜기/끄기 기능을 "onoff"라고 합니다. 예를 들어ample이고 해당 필터는 다음과 같이 정의됩니다.

그러면 대답은 다음과 같습니다. 예를 들어ample

대괄호는 여러 기능으로 필터링할 수도 있음을 나타냅니다.

다음과 같은 대답이 나옵니다.

충수

오류 코드

MQTT 통신 오류로 인해 숫자 코드가 발생합니다. 다음 표는 이를 분석하는 데 도움이 됩니다.

페이로드의 매개변수

페이로드는 상황에 따라 다양한 매개변수를 지원합니다. 다음 표는 어떤 주제에서 어떤 매개변수가 발생할 수 있는지 보여줍니다.

버전 참고 사항

• 1.00 VERSION

소식:

• 첫 출판

문서 / 리소스

	DIVUS VISION API 소프트웨어 [PDF 파일] 사용자 매뉴얼 VISION API 소프트웨어, API 소프트웨어, 소프트웨어
	DIVUS Vision API 소프트웨어 [PDF 파일] 사용자 가이드 Vision API 소프트웨어, Vision, API 소프트웨어, 소프트웨어

참고문헌

• 사용자 설명서