Phần mềm API DIVUS VISION

Thông số kỹ thuật

• Sản phẩm: API DIVUS VISION
• Nhà sản xuất: DIVUS GmbH
• Phiên bản: 1.00 REV0 1 – 20240528
• Địa điểm: Pillhof 51, Eppan (BZ), Ý

Thông tin sản phẩm

API DIVUS VISION là một công cụ phần mềm được thiết kế để giao tiếp với các hệ thống DIVUS VISION. Nó cho phép người dùng truy cập và kiểm soát các yếu tố khác nhau trong hệ thống bằng giao thức MQTT.

Câu hỏi thường gặp

Câu hỏi: Tôi có thể sử dụng API DIVUS VISION mà không cần có kiến ​​thức trước về PC hoặc công nghệ tự động hóa không?

Trả lời: Hướng dẫn này được thiết kế riêng cho người dùng có kiến ​​thức trước đây về các lĩnh vực này để đảm bảo sử dụng API hiệu quả.

THÔNG TIN CHUNG

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – Ý

Hướng dẫn vận hành, sổ tay và phần mềm được bảo vệ bản quyền. Đã đăng ký Bản quyền. Không được phép sao chép, sao chép, dịch, dịch toàn bộ hoặc một phần. Một ngoại lệ áp dụng cho việc tạo bản sao lưu của phần mềm để sử dụng cá nhân.
Hướng dẫn sử dụng có thể thay đổi mà không cần thông báo trước. Chúng tôi không thể đảm bảo rằng dữ liệu trong tài liệu này và trên phương tiện lưu trữ được cung cấp là không có lỗi và chính xác. Đề xuất cải tiến cũng như gợi ý về lỗi luôn được hoan nghênh. Các thỏa thuận cũng áp dụng cho các phụ lục cụ thể của sổ tay này. Các ký hiệu trong tài liệu này có thể là nhãn hiệu mà việc sử dụng của bên thứ ba cho mục đích riêng của họ có thể vi phạm quyền của chủ sở hữu. Hướng dẫn sử dụng: Vui lòng đọc hướng dẫn này trước khi sử dụng lần đầu tiên và giữ nó ở nơi an toàn để tham khảo sau này. Nhóm đối tượng: Sách hướng dẫn được viết dành cho người dùng có kiến ​​thức trước đây về PC và công nghệ tự động hóa.

QUY ĐỊNH TRÌNH BÀY

Giới thiệu

GIỚI THIỆU CHUNG

Sách hướng dẫn này mô tả VISION API (Giao diện lập trình ứng dụng) - một giao diện mà qua đó VISION có thể được xử lý và kiểm soát từ các hệ thống bên ngoài.
Về mặt thực tế, điều này có nghĩa là bạn có thể sử dụng các hệ thống như

• Trình khám phá MQTT (https://www.microsoft.com/store/… - để thử nghiệm),
• Trợ lý tại nhà (https://www.home-assistant.io/) hoặc
• Nút-ĐỎ (https://nodered.org/)

để kiểm soát các phần tử do VISION quản lý hoặc đọc trạng thái của chúng. Việc truy cập và liên lạc diễn ra thông qua giao thức MQTT, sử dụng cái gọi là chủ đề để giải quyết các chức năng hoặc bộ chức năng riêng lẻ hoặc để được thông báo về những thay đổi đối với chúng. Máy chủ MQTT (nhà môi giới) được sử dụng cho mục đích này, xử lý bảo mật và quản lý/phân phối tin nhắn cho người tham gia. Trong trường hợp này, máy chủ MQTT được đặt trực tiếp trên DIVUS KNX IQ và được cấu hình đặc biệt cho mục đích này. Mặc dù API VISION cũng có thể được sử dụng mà không cần kiến ​​thức lập trình nhưng chức năng này phù hợp với người dùng nâng cao.

QUYỀN SỞ H PRU

Như đã giải thích trong hướng dẫn sử dụng VISION, theo mặc định, người dùng API trước tiên phải được kích hoạt để có thể sử dụng nó. Quyền truy cập API chỉ hoạt động khi sử dụng dữ liệu xác thực người dùng Api. Liên quan đến quyền của người dùng, việc kích hoạt chức năng này sau đó có thể được định cấu hình trên tất cả hoặc trên từng thành phần riêng lẻ. Xem Chương.0. Tất nhiên, bạn cũng cần một dự án VISION trong đó các thành phần mà bạn muốn kiểm soát từ bên ngoài đã được cấu hình đầy đủ và kết nối với chúng đã được thử nghiệm thành công. Để có thể giải quyết các thành phần riêng lẻ thông qua API, ID thành phần của chúng phải được biết: ID này được hiển thị ở cuối biểu mẫu cài đặt của thành phần

BẢO VỆ

Vì lý do bảo mật, quyền truy cập API chỉ có thể thực hiện cục bộ (tức là không qua đám mây). Do đó, rủi ro bảo mật khi kích hoạt quyền truy cập API là thấp. Tuy nhiên, không được bật hoặc từ chối rõ ràng các yếu tố liên quan đến bảo mật đối với quyền truy cập API.

MQTT VÀ CÁC ĐIỀU KHOẢN CỦA NÓ – GIẢI THÍCH NGẮN

• Trong MQTT, vai trò quản lý và phân phối tập trung tất cả các tin nhắn là của nhà môi giới. Mặc dù máy chủ MQTT và nhà môi giới MQTT không phải là từ đồng nghĩa (máy chủ là thuật ngữ rộng hơn cho vai trò mà máy khách MQTT cũng có thể đóng), nhà môi giới luôn được nhắc đến trong hướng dẫn này khi máy chủ MQTT được đề cập. Bản thân DIVUS KNX IQ đóng vai trò là nhà môi giới MQTT/máy chủ MQTT trong bối cảnh của hướng dẫn này.
• Máy chủ MQTT sử dụng cái gọi là chủ đề: cấu trúc phân cấp trong đó dữ liệu được phân loại, quản lý và xuất bản.
• Việc xuất bản có mục tiêu chính là cung cấp dữ liệu cho những người tham gia khác thông qua các chủ đề. Nếu bạn muốn thay đổi một giá trị, bạn viết vào chủ đề mong muốn cùng với thay đổi giá trị mong muốn, đồng thời sử dụng hành động xuất bản. Thiết bị mục tiêu hoặc máy chủ MQTT đọc thay đổi mong muốn ảnh hưởng đến nó và áp dụng nó cho phù hợp. Để kiểm tra xem thay đổi đã được áp dụng hay chưa, bạn có thể xem chủ đề thời gian thực đã đăng ký để xem liệu thay đổi có được phản ánh ở đó hay không – liệu mọi thứ có diễn ra tốt đẹp hay không.
• Khách hàng chọn chủ đề mà họ quan tâm: việc này được gọi là đăng ký. Mỗi khi một giá trị thay đổi trong/bên dưới một chủ đề, tất cả khách hàng đã đăng ký đều được thông báo – tức là không cần phải hỏi rõ ràng liệu có điều gì đó đã thay đổi hay giá trị hiện tại là bao nhiêu.
• Bạn có thể mở (hoặc giải quyết) một kênh liên lạc riêng với máy chủ MQTT bằng cách nhập bất kỳ chuỗi duy nhất nào có tên client_id vào một chủ đề. client_id phải được sử dụng trong chủ đề để xử lý các giá trị. Điều này dùng để xác định nguồn gốc của mỗi thay đổi, giúp khắc phục mọi lỗi và không ảnh hưởng đến các máy khách khác, vì các phản hồi tương ứng từ máy chủ, bao gồm mọi mã lỗi và thông báo, cũng chỉ đến chủ đề có cùng client_id (và do đó chỉ khách hàng đó). client_id là một chuỗi ký tự duy nhất bao gồm bất kỳ sự kết hợp nào của các ký tự 0-9, az, AZ, “-“, “_”.
• Nói chung, các chủ đề đăng ký của máy chủ MQTT của DIVUS KNX IQ chứa trạng thái từ khóa, trong khi các chủ đề xuất bản chứa yêu cầu từ khóa. Những giá trị có trạng thái sẽ được cập nhật tự động ngay khi có thay đổi giá trị bên ngoài hoặc ngay khi thay đổi giá trị được chính khách hàng yêu cầu thông qua xuất bản và đã được áp dụng thành công. Những thứ để xuất bản còn được chia thành loại (request/)get và loại (request/)set.
• Các thay đổi về giá trị và các tham số tùy chọn khác được thêm vào chủ đề với cái gọi là tải trọng. Các tham số của các phần tử riêng lẻ (id phần tử, tên, loại, hàm)

Sự khác biệt chính giữa MQTT và mô hình máy khách-máy chủ cổ điển, trong đó máy khách yêu cầu và sau đó thay đổi dữ liệu, tập trung vào các khái niệm đăng ký và xuất bản. Những người tham gia có thể xuất bản dữ liệu, cung cấp dữ liệu đó cho những người khác, những người nếu quan tâm có thể đăng ký nhận dữ liệu đó. Kiến trúc này giúp giảm thiểu việc trao đổi dữ liệu và vẫn cập nhật cho tất cả các bên quan tâm. Tìm hiểu thêm chi tiết tại đây: và các tham số đặc biệt (uuid, bộ lọc) sẽ được sử dụng tại đây. Mặc dù có một số tùy chọn nhưng tải trọng được hiển thị ở định dạng JSON trong hướng dẫn này. JSON sử dụng dấu ngoặc và dấu phẩy để biểu thị dữ liệu của bất kỳ cấu trúc nào và do đó giảm thiểu kích thước của gói dữ liệu được truyền đi. Thông tin chi tiết hơn về tải trọng có thể được tìm thấy sau trong hướng dẫn sử dụng.

• Đối với các mục đích đặc biệt, có thể lọc theo loại chức năng, ví dụ: chỉ bật/tắt địa chỉ, tức là các công tắc 1 bit. Tham số bộ lọc trong tải trọng được sử dụng cho mục đích này. Hiện tại chỉ có thể lọc theo loại chức năng.
• Để có thể giải quyết các phần tử riêng lẻ, cần có ID phần tử của chúng. Điều này có thể được tìm thấy trong VISION trong menu thuộc tính phần tử hoặc cũng có thể được đọc trực tiếp từ dữ liệu được hiển thị trước mỗi phần tử có sẵn trong đăng ký chung của MQTT Explorer (các phần tử được liệt kê theo thứ tự bảng chữ cái theo ID phần tử).

Cấu hình truy cập API

CẤU HÌNH TẦM NHÌN ĐỂ TRUY CẬP NGƯỜI DÙNG API

Trong VISION với tư cách quản trị viên, đi tới Cấu hình – Quản lý quyền truy cập người dùng/API, nhấp vào quyền truy cập Người dùng/API và nhấp chuột phải vào Người dùng API (hoặc nhấn và giữ) để mở cửa sổ chỉnh sửa. Ở đó bạn sẽ tìm thấy các thông số và dữ liệu này

• Bật (hộp kiểm)
  • Người dùng được kích hoạt lần đầu tiên ở đây. Mặc định bị tắt
• Tên người dùng
  • Chuỗi này là bắt buộc để truy cập qua API - sao chép nó từ đây
• Mật khẩu
  • Chuỗi này là bắt buộc để truy cập qua API - sao chép nó từ đây
• Quyền
  • Quyền mặc định để đọc và ghi các giá trị của phần tử VISION có thể được xác định ở đây, tức là những gì được xác định ở đây áp dụng cho tất cả các phần tử hiện tại và tương lai. Nếu bạn chỉ muốn cho phép truy cập vào các phần tử riêng lẻ thì không nên thay đổi các quyền mặc định này

QUYỀN VỀ CÁC YẾU TỐ RIÊNG

Bạn không nên cấp quyền truy cập API cho toàn bộ dự án mà chỉ cấp cho các thành phần mong muốn. Tiến hành như sau

1. đăng nhập vào VISION với tư cách quản trị viên
2. chọn thành phần mong muốn và mở menu cài đặt của nó (nhấp chuột phải hoặc nhấn giữ, sau đó Cài đặt)
3. trong mục menu Chung – Quyền, kích hoạt “Ghi đè quyền mặc định” và sau đó chuyển đến mục phụ Quyền, hiển thị ma trận quyền.
4. kích hoạt quyền kiểm soát ở đây, điều này cũng cho phép view phép trực tiếp. Nếu bạn chỉ muốn đọc dữ liệu thông qua quyền truy cập API, chỉ cần kích hoạt view sự cho phép.
5. lặp lại quy trình tương tự cho tất cả các phần tử bạn muốn truy cập

Kết nối qua MQTT

GIỚI THIỆU

Là một cựuample, chúng tôi sẽ chứng minh quyền truy cập thông qua API MQTT của DIVUS KNX IQ bằng một phần mềm miễn phí, tương đối đơn giản có tên là MQTT Explorer (xem chương 1.1), có sẵn cho Windows, Mac và Linux. Kiến thức và kinh nghiệm cơ bản về MQTT được ngụ ý.

DỮ LIỆU BẮT BUỘC CHO KẾT NỐI

Như đã đề cập trước đó (xem phần 2.1), cần phải có tên người dùng và mật khẩu của người dùng API. Đây là một kết thúcview trong số tất cả dữ liệu phải được thu thập trước khi thiết lập kết nối:

• Tên người dùng Đọc trên trang chi tiết của người dùng API
• Đọc mật khẩu trên trang chi tiết của người dùng API
• Địa chỉ IP Đọc trong cài đặt trình khởi chạy trong phần Chung – Mạng – Ethernet (hoặc qua Bộ đồng bộ hóa)
• Cổng 8884 (cổng này được dành riêng cho mục đích này)

KẾT NỐI ĐẦU TIÊN VỚI MQTT EXPLORER VÀ ĐĂNG KÝ CHUNG

Thông thường, MQTT phân biệt giữa hoạt động đăng ký và xuất bản. MQTT Explorer đơn giản hóa việc này bằng cách tự động đăng ký tất cả các chủ đề có sẵn (topic #) khi kết nối đầu tiên được thực hiện. Do đó, cây dẫn đến tất cả các thành phần có sẵn (tức là quyền truy cập của người dùng API được cấp) có thể được nhìn thấy trực tiếp ở khu vực bên trái của cửa sổ MQTT Explorer sau khi kết nối thành công. Để nhập thêm các chủ đề đăng ký hoặc thay thế # bằng một chủ đề cụ thể hơn, hãy đi tới Nâng cao trong cửa sổ kết nối. Chủ đề hiển thị ở phía trên bên phải trông giống như thế này:

trong đó 7f4x0607849x444xxx256573x3x9x983 là tên người dùng API và object_list chứa tất cả các phần tử có sẵn. Chủ đề này luôn được cập nhật, tức là mọi thay đổi về giá trị đều được phản ánh trong thời gian thực. Nếu bạn chỉ muốn đăng ký các phần tử riêng lẻ, hãy nhập ID phần tử của phần tử mong muốn sau object_list/.

Lưu ý: Kiểu đăng ký này gần tương ứng với logic đằng sau các địa chỉ phản hồi KNX; nó hiển thị trạng thái hiện tại của các phần tử và có thể được sử dụng để kiểm tra xem các thay đổi mong muốn đã được áp dụng thành công hay chưa. Nếu bạn chỉ muốn đọc dữ liệu mà không muốn thay đổi dữ liệu thì kiểu đăng ký này là đủ.

Một phần tử đơn giản trông giống như thế này trong ký hiệu JSON

Lưu ý: Tất cả các giá trị đều có cú pháp hiển thị ở trên, ví dụ: { “value”: “1” } là đầu ra của chủ đề đăng ký, trong khi giá trị được ghi trực tiếp vào tải trọng để thay đổi giá trị (tức là đối với chủ đề xuất bản) – dấu ngoặc và “giá trị” được bỏ qua, ví dụ: “onoff”: “1”.

Lệnh nâng cao

GIỚI THIỆU

Có 3 loại chủ đề nói chung:

1. Đăng ký (các) chủ đề để xem các yếu tố có sẵn và nhận các thay đổi về giá trị theo thời gian thực
2. Đăng ký (các) chủ đề để nhận được câu trả lời cho (các khách hàng ) công bố yêu cầu
3. Xuất bản (các) chủ đề để nhận hoặc đặt các phần tử có giá trị của chúng

Sau này chúng ta sẽ đề cập đến những loại này bằng cách sử dụng cách đánh số được hiển thị ở đây (ví dụ: các chủ đề thuộc loại 1, 2, 3). Thông tin chi tiết trong các phần sau và trong chương. 4.2.

ĐĂNG KÝ CHỦ ĐỀ ĐỂ XEM CÁC YẾU TỐ CÓ SẴN VÀ NHẬN THAY ĐỔI GIÁ TRỊ THỜI GIAN THỰC

Những điều này đã được mô tả rồi

ĐĂNG KÝ CHỦ ĐỀ ĐỂ NHẬN TRẢ LỜI CHO YÊU CẦU XUẤT BẢN CỦA KHÁCH HÀNG

Loại chủ đề này là tùy chọn. Nó cho phép

• mở một kênh liên lạc duy nhất với máy chủ MQTT bằng cách sử dụng client_id tùy ý. Thông tin thêm về điều đó trong chap. 4.2.2
• nhận được kết quả của yêu cầu xuất bản về chủ đề đăng ký tương ứng: thành công hay thất bại với mã lỗi và thông báo.

Có nhiều chủ đề khác nhau để nhận câu trả lời hoặc đặt lệnh xuất bản. Sự khác biệt tương ứng trong Sau khi có được các chủ đề cần thiết cho hệ thống của mình, bạn có thể quyết định xóa bước này và trực tiếp sử dụng các chủ đề xuất bản.

 XUẤT BẢN CHỦ ĐỀ ĐỂ NHẬN HOẶC THIẾT LẬP CÁC YẾU TỐ VỚI GIÁ TRỊ CỦA CHÚNG

Các chủ đề này sử dụng đường dẫn tương tự như đường dẫn để đăng ký – thay đổi duy nhất là từ “yêu cầu” thay cho “trạng thái” được sử dụng để đăng ký. Đường dẫn chủ đề hoàn chỉnh được hiển thị sau trong chương. 4.2.2\ Chủ đề get sẽ yêu cầu đọc các thành phần và giá trị của máy chủ MQTT. Tải trọng có thể được sử dụng để lọc dựa trên loại chức năng của các phần tử. Một chủ đề đã đặt sẽ yêu cầu thay đổi một số phần của một phần tử, như được nêu chi tiết trong tải trọng của nó.

TIỀN TỐ CHO LỆNH VÀ PHẢN HỒI TƯƠNG ỨNG

 GIẢI THÍCH NGẮN

Tất cả các lệnh được gửi đến máy chủ MQTT đều có phần khởi đầu chung, đó là:

GIẢI THÍCH CHI TIẾT

Các chủ đề thời gian thực (loại 1) sẽ có tiền tố chung (xem ở trên) sau đó là

or

Đối với các lệnh set, tải trọng rõ ràng đóng vai trò chính vì nó sẽ chứa các thay đổi mong muốn (tức là các giá trị đã thay đổi cho các chức năng của phần tử). Cảnh báo: Không bao giờ sử dụng tùy chọn giữ lại trong các lệnh loại 3 của bạn vì nó có thể gây ra sự cố ở phía KNX.

EXAMPLE: XUẤT BẢN ĐỂ THAY ĐỔI GIÁ TRỊ CỦA MỘT PHẦN TỬ

Trường hợp đơn giản nhất là muốn thay đổi giá trị của một trong các phần tử được hiển thị bởi subscribe chung.
Nói chung, việc thay đổi/chuyển đổi chức năng của VISION thông qua MQTT bao gồm 3 bước, không phải tất cả các bước đó đều thực sự cần thiết, tuy nhiên chúng tôi khuyên bạn nên thực hiện chúng như mô tả.

1. Chủ đề chứa chức năng chúng tôi muốn chỉnh sửa được đăng ký bằng client_id tùy chỉnh
2. Chủ đề để chỉnh sửa được xuất bản cùng với tải trọng với những thay đổi mong muốn bằng cách sử dụng client_id đã chọn trong 1.
3. Để kiểm tra, bạn có thể xem câu trả lời trong chủ đề (1.) – tức là liệu (2.) có hiệu quả hay không
4. Trong phần đăng ký chung, nơi tất cả các giá trị được cập nhật khi thực hiện thay đổi, bạn có thể thấy (các) thay đổi giá trị mong muốn nếu mọi thứ đều diễn ra tốt đẹp.

Các bước để thực hiện điều này là:

1. chọn client_id, ví dụ: Divus, và chèn nó vào đường dẫn sau tên người dùng API
   Đây là chủ đề hoàn chỉnh để đăng ký kênh liên lạc của riêng bạn với máy chủ MQTT. Điều này cho máy chủ biết nơi bạn mong đợi phản hồi đối với những thay đổi bạn định gửi. Lưu ý phần trạng thái/bộ xác định a. đó là một chủ đề đăng ký và b. rằng nó sẽ nhận được câu trả lời cho các lệnh thiết lập.
2. Chủ đề xuất bản sẽ giống nhau ngoại trừ việc chuyển từ khóa yêu cầu trạng thái
3. nội dung thay đổi sẽ bao gồm được ghi trong tải trọng. Dưới đây là một số cựuampđồng nghiệp.
   • Tắt phần tử có chức năng bật/tắt (1 bit):
   • Bật phần tử có chức năng bật/tắt (1 bit). Ngoài ra, nếu một số lệnh như vậy được bắt đầu từ cùng một máy khách, tham số uuid (“ID duy nhất”, thường là chuỗi 128 bit được định dạng là 8-4-4-4-12 chữ số hex) có thể được sử dụng để gán phản hồi cho truy vấn tương ứng, vì tham số này – nếu có trong truy vấn – cũng có thể được tìm thấy trong phản hồi.
   • Bật và đặt độ sáng của bộ điều chỉnh độ sáng thành 50%
   • Câu trả lời cho chủ đề được hiển thị và đăng ký ở trên (chính xác là tải trọng của nó), ví dụ:amplà.
     Câu trả lời trên là một cựuamptập tin trong trường hợp tải trọng chính xác, mặc dù phần tử không có chức năng làm mờ. Nếu có vấn đề nghiêm trọng hơn khiến tải trọng không được diễn giải chính xác thì phản hồi sẽ như thế này (ví dụ):
     để biết giải thích về mã lỗi và thông báo nhưng nói chung, giống như đối với http, 200 mã là câu trả lời tích cực trong khi 400 là câu trả lời tiêu cực.

EXAMPLE: XUẤT BẢN ĐỂ THAY ĐỔI GIÁ TRỊ NHIỀU YẾU TỐ

Quy trình tương tự như quy trình được hiển thị trước đây để thay đổi một phần tử. Sự khác biệt là bạn bỏ qua element_id khỏi các chủ đề, sau đó chỉ ra tập hợp element_id ở phía trước dữ liệu bên trong tải trọng. Xem cú pháp và cấu trúc bên dưới.

LỌC THEO LOẠI CHỨC NĂNG TRONG TRUY VẤN

Tham số bộ lọc trong tải trọng chỉ cho phép (các) chức năng mong muốn của một phần tử được giải quyết. Chức năng bật/tắt của công tắc hoặc bộ điều chỉnh độ sáng được gọi là “bật”, ví dụ:amptập tin và bộ lọc tương ứng được xác định theo cách này:

Câu trả lời sẽ như thế này, ví dụ nhưample

Dấu ngoặc vuông cho biết bạn cũng có thể lọc theo một số hàm, ví dụ:

dẫn đến một câu trả lời như thế này:

Phụ lục

MÃ LỖI

Lỗi trong giao tiếp MQTT dẫn đến mã số. Bảng sau đây giúp phân tích nó.

THÔNG SỐ CỦA TẢI TRỌNG

Tải trọng hỗ trợ các tham số khác nhau tùy thuộc vào ngữ cảnh. Bảng sau đây cho thấy những tham số nào có thể xuất hiện trong chủ đề nào

LƯU Ý VỀ PHIÊN BẢN

• 1.00 VERSION

Tin tức:

• Xuất bản lần đầu

Tài liệu / Tài nguyên

	Phần mềm API DIVUS VISION [tập tin pdf] Hướng dẫn sử dụng Phần mềm API VISION, Phần mềm API, Phần mềm
	Phần mềm API DIVUS Vision [tập tin pdf] Hướng dẫn sử dụng Phần mềm Vision API, Vision, Phần mềm API, Phần mềm

Tài liệu tham khảo

• Hướng dẫn sử dụng