คู่มือผู้ใช้ซอฟต์แวร์ DIVUS VISION API

ซอฟต์แวร์ DIVUS VISION API

ข้อมูลจำเพาะ

• ผลิตภัณฑ์: DIVUS VISION API
• ผู้ผลิต: DIVUS GmbH
• เวอร์ชัน: 1.00 REV0 1 – 20240528
• สถานที่ตั้ง: Pillhof 51 เอปปัน (BZ) ประเทศอิตาลี

ข้อมูลสินค้า

DIVUS VISION API คือเครื่องมือซอฟต์แวร์ที่ออกแบบมาเพื่อเชื่อมต่อกับระบบ DIVUS VISION อนุญาตให้ผู้ใช้เข้าถึงและควบคุมองค์ประกอบต่างๆ ภายในระบบโดยใช้โปรโตคอล MQTT

คำถามที่พบบ่อย

ถาม: ฉันสามารถใช้ DIVUS VISION API โดยไม่ต้องมีความรู้เกี่ยวกับพีซีหรือเทคโนโลยีระบบอัตโนมัติมาก่อนได้หรือไม่

ตอบ: คู่มือนี้ได้รับการออกแบบมาสำหรับผู้ใช้ที่มีความรู้มาก่อนในด้านเหล่านี้ เพื่อให้มั่นใจว่าการใช้งาน API มีประสิทธิภาพ

ข้อมูลทั่วไป

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – อิตาลี

คู่มือการใช้งาน คู่มือ และซอฟต์แวร์ได้รับการคุ้มครองโดยลิขสิทธิ์ สงวนลิขสิทธิ์. ไม่อนุญาตให้คัดลอก ทำซ้ำ แปล แปลทั้งหมดหรือบางส่วน ข้อยกเว้นใช้กับการสร้างสำเนาสำรองของซอฟต์แวร์เพื่อการใช้งานส่วนตัว
คู่มืออาจมีการเปลี่ยนแปลงได้โดยไม่ต้องแจ้งให้ทราบล่วงหน้า เราไม่สามารถรับประกันได้ว่าข้อมูลที่อยู่ในเอกสารนี้และในสื่อจัดเก็บข้อมูลที่ให้มานั้นปราศจากข้อผิดพลาดและถูกต้อง ข้อเสนอแนะสำหรับการปรับปรุงตลอดจนคำแนะนำเกี่ยวกับข้อผิดพลาดยินดีต้อนรับเสมอ ข้อตกลงยังใช้กับภาคผนวกเฉพาะของคู่มือนี้ด้วย การกำหนดในเอกสารนี้อาจเป็นเครื่องหมายการค้าที่บุคคลที่สามนำไปใช้เพื่อวัตถุประสงค์ของตนเองอาจเป็นการละเมิดสิทธิ์ของเจ้าของ คำแนะนำสำหรับผู้ใช้: โปรดอ่านคู่มือนี้ก่อนใช้งานครั้งแรกและเก็บไว้ในที่ปลอดภัยเพื่อใช้อ้างอิงในอนาคต กลุ่มเป้าหมาย: คู่มือนี้เขียนขึ้นสำหรับผู้ใช้ที่มีความรู้เกี่ยวกับพีซีและเทคโนโลยีระบบอัตโนมัติมาก่อน

อนุสัญญาการนำเสนอ

การแนะนำ

บทนำทั่วไป

คู่มือนี้จะอธิบาย VISION API (Application Programming Interface) ซึ่งเป็นอินเทอร์เฟซที่ VISION สามารถจัดการและควบคุมจากระบบภายนอกได้
ในทางปฏิบัติ หมายความว่าคุณสามารถใช้ระบบต่างๆ เช่น

• MQTT Explorer (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 จะต้องทราบรหัสองค์ประกอบ ซึ่งจะแสดงที่ด้านล่างของแบบฟอร์มการตั้งค่าขององค์ประกอบ

ความปลอดภัย

ด้วยเหตุผลด้านความปลอดภัย การเข้าถึง API สามารถทำได้ภายในเครื่องเท่านั้น (เช่น ไม่ใช่ผ่านระบบคลาวด์) ความเสี่ยงด้านความปลอดภัยเมื่อเปิดใช้งานการเข้าถึง API จึงต่ำ อย่างไรก็ตาม ไม่ควรเปิดใช้งานหรือปฏิเสธองค์ประกอบที่เกี่ยวข้องกับความปลอดภัยอย่างชัดเจนสำหรับการเข้าถึง API

MQTT และข้อกำหนด – คำอธิบายโดยย่อ

• ใน MQTT บทบาทของการจัดการแบบรวมศูนย์และการกระจายข้อความทั้งหมดจะเป็นบทบาทของนายหน้า แม้ว่าเซิร์ฟเวอร์ MQTT และนายหน้า MQTT ไม่ใช่คำพ้องความหมาย (เซิร์ฟเวอร์เป็นคำที่กว้างกว่าสำหรับบทบาทที่ไคลเอนต์ MQTT สามารถเล่นได้เช่นกัน) นายหน้าจะมีความหมายในคู่มือนี้เสมอเมื่อมีการกล่าวถึงเซิร์ฟเวอร์ MQTT ตัว DIVUS KNX IQ นั้นมีบทบาทเป็นนายหน้า MQTT / เซิร์ฟเวอร์ MQTT ในบริบทของคู่มือนี้
• เซิร์ฟเวอร์ MQTT ใช้สิ่งที่เรียกว่าหัวข้อ: โครงสร้างแบบลำดับชั้นที่ใช้จัดหมวดหมู่ จัดการ และเผยแพร่ข้อมูล
• การเผยแพร่มีเป้าหมายหลักในการให้ข้อมูลแก่ผู้เข้าร่วมคนอื่นๆ ผ่านหัวข้อต่างๆ หากคุณต้องการเปลี่ยนค่า คุณจะต้องเขียนไปยังหัวข้อที่ต้องการพร้อมกับการเปลี่ยนแปลงค่าที่ต้องการ รวมถึงใช้การดำเนินการเผยแพร่ด้วย อุปกรณ์เป้าหมายหรือเซิร์ฟเวอร์ MQTT อ่านการเปลี่ยนแปลงที่ต้องการซึ่งส่งผลต่ออุปกรณ์ดังกล่าวและนำไปใช้ตามนั้น หากต้องการตรวจสอบว่าการเปลี่ยนแปลงมีผลหรือไม่ คุณสามารถดูหัวข้อแบบเรียลไทม์ที่สมัครเป็นสมาชิกเพื่อดูว่าการเปลี่ยนแปลงมีผลหรือไม่ หากทุกอย่างเป็นไปด้วยดี
• ลูกค้าเลือกหัวข้อที่พวกเขาสนใจ ซึ่งเรียกว่าการสมัครสมาชิก ทุกครั้งที่ค่าเปลี่ยนแปลงใน/ใต้หัวข้อ ลูกค้าที่สมัครเป็นสมาชิกทั้งหมดจะได้รับแจ้ง กล่าวคือ โดยไม่ต้องถามอย่างชัดเจนว่ามีการเปลี่ยนแปลงหรือไม่ หรือมูลค่าปัจจุบันเป็นเท่าใด
• คุณสามารถเปิด (หรือระบุที่อยู่) ช่องทางการสื่อสารแยกต่างหากกับเซิร์ฟเวอร์ MQTT ได้โดยการป้อนสตริงเฉพาะที่เรียกว่า client_id ในหัวข้อ ต้องใช้ client_id ในหัวข้อเพื่อประมวลผลค่า สิ่งนี้ทำหน้าที่ในการระบุที่มาของการเปลี่ยนแปลงแต่ละครั้ง ช่วยแก้ไขข้อผิดพลาด และไม่ส่งผลกระทบต่อไคลเอนต์อื่นๆ เนื่องจากการตอบกลับที่เกี่ยวข้องจากเซิร์ฟเวอร์ รวมถึงรหัสข้อผิดพลาดและข้อความใดๆ จะเข้าถึงเฉพาะหัวข้อที่มี client_id เดียวกันเท่านั้น (และด้วยเหตุนี้เท่านั้น ลูกค้ารายนั้น) client_id เป็นสตริงอักขระเฉพาะที่ประกอบด้วยอักขระ 0-9, az, AZ, “-“, “_”
• โดยทั่วไป หัวข้อสมัครสมาชิกของเซิร์ฟเวอร์ MQTT ของ DIVUS KNX IQ จะมีสถานะคีย์เวิร์ด ในขณะที่หัวข้อเผยแพร่จะมีคำขอคีย์เวิร์ด รายการที่มีสถานะจะได้รับการอัปเดตโดยอัตโนมัติทันทีที่มีการเปลี่ยนแปลงค่าภายนอกหรือทันทีที่ลูกค้าร้องขอการเปลี่ยนแปลงค่าเองผ่านการเผยแพร่และนำไปใช้สำเร็จ ประเภทสำหรับการเผยแพร่แบ่งออกเป็นประเภท (คำขอ/)get และประเภท (คำขอ/)ชุด
• การเปลี่ยนแปลงค่าและพารามิเตอร์ทางเลือกอื่นๆ จะถูกเพิ่มเข้ากับหัวข้อที่เรียกว่าเพย์โหลด พารามิเตอร์ของแต่ละองค์ประกอบ (รหัสองค์ประกอบ ชื่อ ประเภท ฟังก์ชัน)

ความแตกต่างที่สำคัญระหว่าง MQTT และโมเดลไคลเอ็นต์-เซิร์ฟเวอร์แบบคลาสสิก ซึ่งไคลเอ็นต์ร้องขอแล้วเปลี่ยนแปลงข้อมูล มีศูนย์กลางอยู่ที่แนวคิดในการสมัครและเผยแพร่ ผู้เข้าร่วมอาจเผยแพร่ข้อมูล ทำให้ผู้อื่นสามารถเข้าถึงได้ หากสนใจสามารถสมัครรับข้อมูลได้ สถาปัตยกรรมนี้ทำให้สามารถลดการแลกเปลี่ยนข้อมูลและยังคงให้ผู้มีส่วนได้เสียได้รับข้อมูลล่าสุด ข้อมูลเพิ่มเติมเกี่ยวกับรายละเอียดที่นี่: และต้องใช้พารามิเตอร์พิเศษ (uuid, ตัวกรอง) ที่นี่ แม้ว่าจะมีหลายตัวเลือก แต่เพย์โหลดจะแสดงอยู่ในรูปแบบ JSON ในคู่มือนี้ JSON ใช้วงเล็บและเครื่องหมายจุลภาคเพื่อแสดงข้อมูลของโครงสร้างใดๆ และลดขนาดของแพ็กเก็ตข้อมูลที่จะส่งให้เหลือน้อยที่สุด รายละเอียดเพิ่มเติมเกี่ยวกับเพย์โหลดสามารถดูได้ในภายหลังในคู่มือ

• เพื่อวัตถุประสงค์พิเศษ คุณสามารถกรองตามประเภทของฟังก์ชันได้ เช่น เพื่อระบุเฉพาะการเปิด/ปิด เช่น สวิตช์ 1 บิต พารามิเตอร์ตัวกรองในเพย์โหลดถูกใช้เพื่อจุดประสงค์นี้ ขณะนี้การกรองสามารถทำได้ตามประเภทฟังก์ชันเท่านั้น
• เพื่อให้สามารถระบุองค์ประกอบแต่ละรายการได้ จำเป็นต้องมีรหัสองค์ประกอบ ซึ่งสามารถพบได้ใน VISION ในเมนูคุณสมบัติขององค์ประกอบ หรือสามารถอ่านได้โดยตรงจากข้อมูลที่แสดงด้านหน้าองค์ประกอบที่มีอยู่แต่ละรายการในการสมัครสมาชิกทั่วไปของ MQTT Explorer (องค์ประกอบในรายการจะเรียงตามตัวอักษรตามรหัสองค์ประกอบ)

การกำหนดค่าสำหรับการเข้าถึง API

การกำหนดค่าวิสัยทัศน์สำหรับการเข้าถึงผู้ใช้ API

ใน VISION ในฐานะผู้ดูแลระบบ ให้ไปที่การกำหนดค่า – การจัดการการเข้าถึงผู้ใช้/API คลิกที่การเข้าถึงผู้ใช้/API และคลิกขวาที่ผู้ใช้ API (หรือกดค้างไว้) เพื่อเปิดหน้าต่างการแก้ไข คุณจะพบพารามิเตอร์และข้อมูลเหล่านี้ที่นั่น

• เปิดใช้งาน (ช่องทำเครื่องหมาย)
  • ผู้ใช้ถูกเปิดใช้งานเป็นครั้งแรกที่นี่ ค่าเริ่มต้นถูกปิดใช้งาน
• ชื่อผู้ใช้
  • สตริงนี้จำเป็นสำหรับการเข้าถึงผ่าน API – คัดลอกจากที่นี่
• รหัสผ่าน
  • สตริงนี้จำเป็นสำหรับการเข้าถึงผ่าน API – คัดลอกจากที่นี่
• การอนุญาต
  • สิทธิ์เริ่มต้นสำหรับการอ่านและการเขียนค่าขององค์ประกอบ VISION สามารถกำหนดได้ที่นี่ กล่าวคือ สิ่งที่กำหนดไว้ที่นี่จะนำไปใช้กับองค์ประกอบที่มีอยู่และในอนาคตทั้งหมด หากคุณต้องการอนุญาตให้เข้าถึงองค์ประกอบแต่ละรายการเท่านั้น คุณไม่ควรเปลี่ยนสิทธิ์เริ่มต้นเหล่านี้

สิทธิ์ในองค์ประกอบส่วนบุคคล

ขอแนะนำว่าคุณไม่ควรให้สิทธิ์การเข้าถึง API แก่ทั้งโปรเจ็กต์ แต่ให้สิทธิ์แก่องค์ประกอบที่ต้องการเท่านั้น ดำเนินการดังนี้

1. ล็อกอินเข้าสู่ VISION ในฐานะผู้ดูแลระบบ
2. เลือกองค์ประกอบที่ต้องการและเปิดเมนูการตั้งค่า (คลิกขวาหรือกดค้างไว้จากนั้นคลิกการตั้งค่า)
3. ภายใต้รายการเมนู ทั่วไป - การอนุญาต เปิดใช้งาน "แทนที่การอนุญาตเริ่มต้น" จากนั้นไปที่รายการย่อย การอนุญาต ซึ่งแสดงเมทริกซ์การอนุญาต
4. เปิดใช้งานการอนุญาตการควบคุมที่นี่ ซึ่งเปิดใช้งานด้วย view ได้รับอนุญาตโดยตรง หากคุณต้องการอ่านข้อมูลผ่านการเข้าถึง API เท่านั้น ก็เพียงพอแล้วที่จะเปิดใช้งาน view การอนุญาต.
5. ทำซ้ำขั้นตอนเดียวกันสำหรับองค์ประกอบทั้งหมดที่คุณต้องการเข้าถึง

การเชื่อมต่อผ่าน MQTT

การแนะนำ

ในฐานะอดีตampในตอนนี้ เราจะสาธิตการเข้าถึงผ่าน MQTT API ของ DIVUS KNX IQ ด้วยซอฟต์แวร์ฟรีที่ค่อนข้างเรียบง่ายที่เรียกว่า MQTT Explorer (ดูบทที่ 1.1) ซึ่งพร้อมใช้งานสำหรับ Windows, Mac และ Linux มีความรู้และประสบการณ์พื้นฐานเกี่ยวกับ MQTT โดยนัย

ข้อมูลที่จำเป็นสำหรับการเชื่อมต่อ

ตามที่กล่าวไว้ข้างต้น (ดูหัวข้อ 2.1) จำเป็นต้องมีชื่อผู้ใช้และรหัสผ่านของผู้ใช้ API นี่คือมากกว่าview ของข้อมูลทั้งหมดที่ต้องรวบรวมก่อนที่จะสร้างการเชื่อมต่อ:

• ชื่อผู้ใช้ อ่านในหน้ารายละเอียดของผู้ใช้ API
• รหัสผ่าน อ่านในหน้ารายละเอียดของผู้ใช้ API
• ที่อยู่ IP อ่านในการตั้งค่าตัวเรียกใช้งานภายใต้ทั่วไป - เครือข่าย - อีเธอร์เน็ต (หรือผ่าน Synchronizer)
• พอร์ต 8884 (พอร์ตนี้สงวนไว้เพื่อการนี้)

การเชื่อมต่อครั้งแรกกับ MQTT EXPLORER และการสมัครทั่วไป

โดยปกติ MQTT จะแยกความแตกต่างระหว่างกิจกรรมที่สมัครรับข้อมูลและเผยแพร่ MQTT Explorer ช่วยให้สิ่งนี้ง่ายขึ้นโดยสมัครรับหัวข้อที่มีอยู่ทั้งหมดโดยอัตโนมัติ (หัวข้อ #) เมื่อมีการเชื่อมต่อครั้งแรก ด้วยเหตุนี้ จึงสามารถเห็นแผนผังที่นำไปสู่องค์ประกอบที่มีอยู่ทั้งหมด (เช่น สิทธิ์การเข้าถึงของผู้ใช้ API) ได้โดยตรงในพื้นที่ด้านซ้ายของหน้าต่าง MQTT Explorer หลังจากการเชื่อมต่อสำเร็จ หากต้องการป้อนหัวข้อการสมัครเพิ่มเติมหรือแทนที่ # ด้วยหัวข้อที่เฉพาะเจาะจงมากขึ้น ให้ไปที่ขั้นสูงในหน้าต่างการเชื่อมต่อ หัวข้อที่แสดงทางด้านขวาบนมีลักษณะดังนี้:

โดยที่ 7f4x0607849x444xxx256573x3x9x983 คือชื่อผู้ใช้ API และ object_list มีองค์ประกอบที่มีอยู่ทั้งหมด หัวข้อนี้จะได้รับการอัปเดตอยู่เสมอ กล่าวคือ การเปลี่ยนแปลงค่าใดๆ ก็ตามจะแสดงแบบเรียลไทม์ หากคุณต้องการสมัครรับข้อมูลองค์ประกอบแต่ละรายการเท่านั้น ให้ป้อนรหัสองค์ประกอบขององค์ประกอบที่ต้องการหลัง object_list/

หมายเหตุ: การสมัครรับข้อมูลประเภทนี้สอดคล้องกับตรรกะเบื้องหลังที่อยู่ความคิดเห็นของ KNX โดยคร่าว มันแสดงสถานะปัจจุบันขององค์ประกอบและอาจใช้เพื่อตรวจสอบว่าการเปลี่ยนแปลงที่ต้องการถูกนำไปใช้สำเร็จหรือไม่ หากคุณต้องการอ่านข้อมูลแต่ไม่ต้องการเปลี่ยนแปลง การสมัครประเภทนี้ก็เพียงพอแล้ว

องค์ประกอบง่ายๆ องค์ประกอบเดียวจะมีลักษณะเช่นนี้ในรูปแบบ JSON

หมายเหตุ: ค่าทั้งหมดมีไวยากรณ์ที่แสดงด้านบน เช่น { “value”: “1” } เป็นผลลัพธ์ของหัวข้อสมัครสมาชิก ในขณะที่ค่าจะถูกเขียนโดยตรงในเพย์โหลดเพื่อเปลี่ยนค่า (เช่น สำหรับหัวข้อเผยแพร่) – วงเล็บและ "ค่า" จะถูกละเว้น เช่น "onoff": "1"

คำสั่งขั้นสูง

การแนะนำ

โดยทั่วไปมี 3 หัวข้อ:

1. สมัครสมาชิกหัวข้อเพื่อดูองค์ประกอบที่มีอยู่และรับการเปลี่ยนแปลงค่าแบบเรียลไทม์
2. สมัครสมาชิกหัวข้อเพื่อรับคำตอบ (ลูกค้า ) เผยแพร่คำขอ
3. เผยแพร่หัวข้อเพื่อรับหรือตั้งค่าองค์ประกอบด้วยค่าของพวกเขา

เราจะอ้างอิงถึงประเภทเหล่านี้ในภายหลังโดยใช้หมายเลขที่แสดงไว้ที่นี่ (เช่น หัวข้อประเภท 1, 2, 3) รายละเอียดเพิ่มเติมในส่วนต่อไปนี้และในบทที่ 4.2.

สมัครสมาชิกหัวข้อเพื่อดูองค์ประกอบที่มีอยู่และรับการเปลี่ยนแปลงมูลค่าแบบเรียลไทม์

สิ่งเหล่านี้ได้ถูกอธิบายไว้แล้ว

สมัครสมาชิกหัวข้อเพื่อรับคำตอบต่อคำขอเผยแพร่ของลูกค้า

หัวข้อประเภทนี้เป็นทางเลือก มันช่วยให้

• เปิดช่องทางการสื่อสารที่ไม่ซ้ำกับเซิร์ฟเวอร์ MQTT โดยใช้ client_id ที่กำหนดเอง เพิ่มเติมเกี่ยวกับเรื่องนั้นในบท 4.2.2
• รับผลลัพธ์ของคำขอเผยแพร่ในหัวข้อการสมัครสมาชิกที่เกี่ยวข้อง: สำเร็จหรือล้มเหลวพร้อมรหัสข้อผิดพลาดและข้อความ

มีหัวข้อต่างๆ มากมายในการรับคำตอบเพื่อรับหรือตั้งค่าคำสั่งเผยแพร่ ความแตกต่างที่สอดคล้องกันใน เมื่อคุณได้รับหัวข้อที่จำเป็นสำหรับระบบของคุณแล้ว คุณอาจตัดสินใจลบขั้นตอนนี้และใช้หัวข้อเผยแพร่โดยตรง

 เผยแพร่หัวข้อเพื่อรับหรือกำหนดองค์ประกอบด้วยค่าของพวกเขา

หัวข้อเหล่านี้ใช้เส้นทางที่คล้ายคลึงกับหัวข้อในการสมัคร – การเปลี่ยนแปลงเพียงอย่างเดียวคือคำว่า “คำขอ” แทนที่ “สถานะ” ที่ใช้ในการสมัคร เส้นทางหัวข้อที่สมบูรณ์จะแสดงในภายหลังในบท 4.2.2\ หัวข้อรับจะขออ่านองค์ประกอบและค่าของเซิร์ฟเวอร์ MQTT เพย์โหลดอาจใช้เพื่อกรองตามประเภทฟังก์ชันขององค์ประกอบ หัวข้อที่กำหนดจะขอเปลี่ยนแปลงบางส่วนขององค์ประกอบ ตามรายละเอียดในเพย์โหลด

คำนำหน้าสำหรับคำสั่งและการตอบสนองที่สอดคล้องกัน

 คำอธิบายสั้น ๆ

คำสั่งทั้งหมดที่ส่งไปยังเซิร์ฟเวอร์ MQTT มีส่วนเริ่มต้นร่วมกัน กล่าวคือ:

คำอธิบายโดยละเอียด

หัวข้อเรียลไทม์ (ประเภท 1) จะมีคำนำหน้าทั่วไป (ดูด้านบน) แล้วตามด้วย

or

สำหรับคำสั่ง set เพย์โหลดมีบทบาทหลักอย่างเห็นได้ชัด เนื่องจากจะมีการเปลี่ยนแปลงที่ต้องการ (เช่น ค่าที่เปลี่ยนแปลงสำหรับฟังก์ชันขององค์ประกอบ) คำเตือน: ห้ามใช้ตัวเลือกการเก็บรักษาในคำสั่งประเภท 3 ของคุณ เนื่องจากอาจทำให้เกิดปัญหาในด้าน KNX

EXAMPLE: เผยแพร่เพื่อเปลี่ยนแปลงค่าขององค์ประกอบเดียว

กรณีที่ง่ายที่สุดคือต้องการเปลี่ยนค่าขององค์ประกอบใดองค์ประกอบหนึ่งที่แสดงโดยการสมัครรับข้อมูลทั่วไป
โดยทั่วไปแล้ว การเปลี่ยน/สลับฟังก์ชันของ VISION ผ่าน MQTT ประกอบด้วย 3 ขั้นตอน ซึ่งไม่ใช่ทั้งหมดที่จำเป็นอย่างยิ่ง แต่อย่างไรก็ตาม เราแนะนำให้ดำเนินการตามที่อธิบายไว้

1. หัวข้อที่มีฟังก์ชันที่เราต้องการแก้ไขสมัครสมาชิกโดยใช้ client_id ที่กำหนดเอง
2. หัวข้อสำหรับการแก้ไขจะถูกเผยแพร่พร้อมกับเพย์โหลดพร้อมการเปลี่ยนแปลงที่ต้องการโดยใช้ client_id ที่เลือกใน 1
3. หากต้องการตรวจสอบ คุณสามารถดูคำตอบได้ในหัวข้อ (1.) เช่น (2.) ได้ผลหรือไม่
4. ในการสมัครสมาชิกทั่วไป ซึ่งค่าทั้งหมดจะได้รับการอัปเดตเมื่อมีการเปลี่ยนแปลง คุณสามารถดูการเปลี่ยนแปลงค่าที่ต้องการได้หากทุกอย่างทำงานได้ดี

ขั้นตอนในการทำสิ่งนี้มีดังนี้:

1. เลือก client_id เช่น “Divus” และแทรกลงในเส้นทางหลังชื่อผู้ใช้ API
   นี่คือหัวข้อที่สมบูรณ์สำหรับการสมัครช่องทางการสื่อสารของคุณเองกับเซิร์ฟเวอร์ MQTT ซึ่งจะแจ้งให้เซิร์ฟเวอร์ทราบถึงตำแหน่งที่คุณคาดหวังการตอบสนองต่อการเปลี่ยนแปลงที่คุณตั้งใจจะส่ง สังเกตสถานะ/ส่วนที่กำหนดซึ่งกำหนด ว่าเป็นหัวข้อสมัครสมาชิกและข ว่าจะได้คำตอบมาตั้งคำสั่งประเภท
2. หัวข้อการเผยแพร่จะเหมือนกันยกเว้นการสลับคีย์เวิร์ดคำขอสถานะ
3. สิ่งที่การเปลี่ยนแปลงควรประกอบด้วยจะเขียนไว้ในเพย์โหลด นี่คืออดีตบางส่วนampเลส.
   • การปิดองค์ประกอบที่มีฟังก์ชันเปิด/ปิด (1 บิต):
   • การเปิดองค์ประกอบที่มีฟังก์ชันเปิด/ปิด (1 บิต) นอกจากนี้ หากคำสั่งดังกล่าวหลายคำสั่งเริ่มต้นจากไคลเอนต์เดียวกัน พารามิเตอร์ uuid (“unique ID” ซึ่งโดยปกติจะเป็นสตริง 128 บิตที่จัดรูปแบบเป็นฐานสิบหก 8-4-4-4-12 หลัก) สามารถใช้ในการกำหนด ตอบสนองต่อแบบสอบถามที่เกี่ยวข้อง เนื่องจากพารามิเตอร์นี้ (หากมีอยู่ในแบบสอบถาม) ก็สามารถพบได้ในการตอบกลับเช่นกัน
   • การเปิดและตั้งค่าความสว่างของสวิตช์หรี่ไฟเป็น 50%
   • คำตอบสำหรับหัวข้อที่แสดงและสมัครรับข้อมูลด้านบน (ถ้าให้เจาะจงคือเพย์โหลด) คือคำตอบ เช่นampเล.
     คำตอบข้างต้นคืออดีตampในกรณีของเพย์โหลดที่ถูกต้อง แม้ว่าองค์ประกอบจะไม่มีฟังก์ชันลดแสงก็ตาม หากมีปัญหาร้ายแรงที่ทำให้ไม่สามารถตีความเพย์โหลดได้อย่างถูกต้อง การตอบสนองจะมีลักษณะดังนี้ (เช่น):
     สำหรับคำอธิบายรหัสข้อผิดพลาดและข้อความ โดยทั่วไป เช่น http รหัส 200 รหัสเป็นคำตอบเชิงบวก ในขณะที่ 400 รหัสเป็นค่าลบ

EXAMPLE: เผยแพร่เพื่อเปลี่ยนแปลงค่าองค์ประกอบหลายรายการ

ขั้นตอนจะคล้ายกับขั้นตอนที่แสดงไว้ก่อนหน้าเพื่อเปลี่ยนองค์ประกอบเดียว ข้อแตกต่างคือคุณละเว้น element_id ออกจากหัวข้อ จากนั้นระบุชุดของ element_ids หน้าข้อมูลภายในเพย์โหลด ดูไวยากรณ์และโครงสร้างด้านล่าง

กรองตามประเภทฟังก์ชันในแบบสอบถาม

พารามิเตอร์ตัวกรองในเพย์โหลดอนุญาตให้ระบุเฉพาะฟังก์ชันที่ต้องการขององค์ประกอบเท่านั้น ฟังก์ชั่นเปิด/ปิดของสวิตช์หรือสวิตช์หรี่ไฟเรียกว่า “เปิดปิด” เช่นample และตัวกรองที่เกี่ยวข้องถูกกำหนดในลักษณะนี้:

คำตอบจะมีลักษณะเช่นนี้ เช่นample

วงเล็บเหลี่ยมแสดงว่าคุณสามารถกรองตามฟังก์ชันต่างๆ ได้ เช่น

นำไปสู่คำตอบเช่นนี้:

ภาคผนวก

รหัสข้อผิดพลาด

ข้อผิดพลาดในการสื่อสาร MQTT ส่งผลให้เกิดรหัสตัวเลข ตารางต่อไปนี้ช่วยในการแยกย่อย

พารามิเตอร์ของเพย์โหลด

เพย์โหลดรองรับพารามิเตอร์ที่แตกต่างกันขึ้นอยู่กับบริบท ตารางต่อไปนี้แสดงพารามิเตอร์ที่สามารถเกิดขึ้นได้ในหัวข้อใด

หมายเหตุเกี่ยวกับเวอร์ชัน

• รุ่น 1.00

ข่าว:

• ตีพิมพ์ครั้งแรก