תוכנת API של DIVUS VISION

מפרטים

• מוצר: DIVUS VISION API
• יצרן: DIVUS GmbH
• גרסה: 1.00 REV0 1 – 20240528
• מיקום: Pillhof 51, Eppan (BZ), איטליה

מידע על המוצר

ה-API של DIVUS VISION הוא כלי תוכנה המיועד להתממשקות עם מערכות DIVUS VISION. זה מאפשר למשתמשים לגשת ולשלוט באלמנטים שונים בתוך המערכת באמצעות פרוטוקולי MQTT.

שאלות נפוצות

ש: האם אוכל להשתמש ב-DIVUS VISION API ללא ידע מוקדם במחשב או בטכנולוגיית אוטומציה?

ת: המדריך מותאם למשתמשים בעלי ידע קודם בתחומים אלה כדי להבטיח שימוש יעיל ב-API.

מידע כללי

• DIVUS GmbH Pillhof 51 I-39057 Eppan (BZ) – איטליה

הוראות הפעלה, מדריכים ותוכנה מוגנים בזכויות יוצרים. כל הזכויות שמורות. העתקה, שכפול, תרגום, תרגום כולו או חלקו אינם מותרים. חריג חל על יצירת עותק גיבוי של התוכנה לשימוש אישי.
המדריך נתון לשינויים ללא הודעה מוקדמת. איננו יכולים להבטיח שהנתונים הכלולים במסמך זה ובאמצעי האחסון המסופקים נקיים משגיאות ונכונים. הצעות לשיפורים כמו גם רמזים על שגיאות יתקבלו תמיד בברכה. ההסכמים חלים גם על הנספחים הספציפיים למדריך זה. הסימנים במסמך זה עשויים להיות סימנים מסחריים שהשימוש בהם על ידי צדדים שלישיים למטרותיהם עלול להפר את זכויות בעליהם. הוראות משתמש: אנא קרא מדריך זה לפני השימוש בו בפעם הראשונה ושמור אותו במקום בטוח לעיון עתידי. קבוצת יעד: המדריך נכתב עבור משתמשים בעלי ידע קודם בטכנולוגיית PC ואוטומציה.

אמנות מצגת

מָבוֹא

מבוא כללי

מדריך זה מתאר את VISION API (ממשק תכנות יישומים) - ממשק שדרכו ניתן לטפל ב-VISION ולשלוט בו ממערכות חיצוניות.
מבחינה מעשית, זה אומר שאתה יכול להשתמש במערכות כגון

• MQTT Explorer (https://www.microsoft.com/store/… - לבדיקה),
• עוזר בית (https://www.home-assistant.io/) או
• צומת-אדום (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 מכילים את סטטוס מילת המפתח, בעוד נושאי הפרסום מכילים את בקשת מילת המפתח. בעלי סטטוס מתעדכנים אוטומטית ברגע שיש שינוי ערך חיצוני או ברגע ששינוי ערך התבקש על ידי הלקוח עצמו באמצעות פרסום והוחל בהצלחה. אלה לפרסום מחולקים עוד יותר לאלו של סוג (request/)get ואלה של סוג (request/)set.
• שינויי ערך ופרמטרים אופציונליים נוספים מתווספים לנושא עם המטען שנקרא. הפרמטרים של האלמנטים הבודדים (מזהה אלמנט, שם, סוג, פונקציות)

ההבדל העיקרי בין MQTT למודל שרת-לקוח הקלאסי, שבו הלקוח מבקש ולאחר מכן משנה נתונים, מתרכז במושגים של מנוי ופרסום. המשתתפים רשאים לפרסם נתונים, ולהפוך אותם לזמינים לאחרים, שאם מעוניינים יוכלו להירשם אליהם. ארכיטקטורה זו מאפשרת למזער את חילופי הנתונים ועדיין לעדכן את כל בעלי העניין. עוד על הפרטים כאן: ופרמטרים מיוחדים (uuid, פילטרים) ישמשו כאן. למרות שישנן מספר אפשרויות, המטען מוצג בפורמט כ-JSON במדריך זה. JSON משתמש בסוגריים ופסיקים כדי לייצג נתונים מכל מבנה ובכך ממזער את גודל מנות הנתונים שיש להעביר. פרטים נוספים על מטענים ניתן למצוא בהמשך המדריך.

• למטרות מיוחדות, ניתן לסנן לפי סוג הפונקציה, למשל להתייחס רק להפעלה/כיבוי, כלומר למתגים של 1-bit. פרמטר המסננים במטען משמש למטרה זו. סינון אפשרי כרגע רק לפי סוג פונקציה.
• כדי להיות מסוגל להתייחס לאלמנטים בודדים, נדרש מזהה הרכיב שלהם. ניתן למצוא זאת ב-VISION בתפריט מאפייני האלמנטים או שניתן לקרוא אותו ישירות מהנתונים המוצגים מול כל רכיב זמין במנוי הכללי של ה-MQTT Explorer (האלמנטים שם מופיעים בסדר אלפביתי לפי מזהה אלמנט).

תצורה עבור גישת ה-API

הגדרת VISION עבור גישת משתמש API

ב-VISION כמנהל, עבור אל תצורה – ניהול גישת משתמש/API, לחץ על Users/API access ולחץ באמצעות לחצן העכבר הימני על API User (או לחץ והחזק) כדי לפתוח את חלון העריכה. שם תמצאו את הפרמטרים והנתונים הללו

• הפעל (תיבת סימון)
  • המשתמש מופעל כאן לראשונה. ברירת המחדל מושבתת
• שם משתמש
  • מחרוזת זו נדרשת לגישה דרך API - העתק אותה מכאן
• סִיסמָה
  • מחרוזת זו נדרשת לגישה דרך API - העתק אותה מכאן
• הרשאות
  • ניתן להגדיר כאן את זכויות ברירת המחדל לקריאה ולכתיבה של הערכים של רכיבי VISION, כלומר מה שמוגדר כאן חל על כל האלמנטים הקיימים והעתידיים. אם ברצונך לאפשר גישה רק לרכיבים בודדים, אל תשנה את זכויות ברירת המחדל הללו

הרשאות על אלמנטים בודדים

מומלץ לא להעניק גישת API לכל הפרויקט, אלא רק לאלמנטים הרצויים. בצע את הפעולות הבאות

1. היכנס ל-VISION כמנהל
2. בחר את הרכיב הרצוי ופתח את תפריט ההגדרות שלו (לחץ לחיצה ימנית או המשך לחוץ, ואז הגדרות)
3. תחת ערך התפריט כללי - הרשאות, הפעל את "עקוף הרשאות ברירת מחדל" ולאחר מכן עבור לפריט המשנה הרשאות, המציג את מטריצת ההרשאות.
4. הפעל כאן את הרשאת השליטה, המאפשרת גם את view רשות ישירות. אם ברצונך לקרוא נתונים רק באמצעות גישת ה-API, זה מספיק כדי להפעיל את view רְשׁוּת.
5. חזור על אותו הליך עבור כל האלמנטים שאליהם ברצונך לגשת

חיבור באמצעות MQTT

מָבוֹא

בתור אקסיתampלהלן, נדגים גישה דרך ה-API MQTT של DIVUS KNX IQ עם תוכנה פשוטה יחסית וחינמית בשם MQTT Explorer (ראה פרק 1.1), הזמינה עבור Windows, Mac ו-Linux. ידע וניסיון בסיסיים עם MQTT משתמע.

נתונים נדרשים עבור החיבור

כפי שהוזכר קודם לכן (ראה סעיף 2.1), שם המשתמש והסיסמה של משתמש ה-API נדרשים. הנה סיוםview מכל הנתונים שיש לאסוף לפני יצירת חיבור:

• שם משתמש קרא בדף הפרטים של משתמש ה-API
• קרא את הסיסמה בדף הפרטים של משתמש ה-API
• כתובת IP קראו בהגדרות המשגר ​​תחת כללי – רשת – Ethernet (או באמצעות סינכרון)
• נמל 8884 (נמל זה שמור למטרה זו)

חיבור ראשון עם MQTT EXPLORER ו-General Subscribe

בדרך כלל, MQTT מבחין בין הפעילויות המנויים והפרסום. MQTT Explorer מפשט זאת על ידי הרשמה אוטומטית לכל הנושאים הזמינים (נושא מס') כאשר החיבור הראשון מתבצע. כתוצאה מכך, העץ שמוביל לכל האלמנטים הזמינים (כלומר גישת משתמש API שניתנה) ניתן לראות ישירות באזור השמאלי של חלון MQTT Explorer לאחר חיבור מוצלח. כדי להזין נושאי הרשמה נוספים או כדי להחליף את ה-# בנושא ספציפי יותר, עבור אל מתקדם בחלון החיבור. הנושא המוצג בצד ימין למעלה נראה בערך כך:

כאשר 7f4x0607849x444xxx256573x3x9x983 הוא שם המשתמש של ה-API ו-objects_list מכיל את כל האלמנטים הזמינים. נושא זה תמיד מעודכן, כלומר כל שינויי ערך משתקפים שם בזמן אמת. אם אתה רוצה להירשם רק לאלמנטים בודדים, הזן את מזהה האלמנט של האלמנט הרצוי אחרי objects_list/.

הערה: סוג זה של מנוי תואם בערך את ההיגיון מאחורי כתובות המשוב של KNX; הוא מציג את המצב הנוכחי של הרכיבים וניתן להשתמש בו כדי לבדוק אם השינויים הרצויים הוחלו בהצלחה. אם אתה רוצה רק לקרוא נתונים אבל לא לשנות אותם, סוג זה של מנוי מספיק.

אלמנט פשוט אחד נראה בערך כך בסימון JSON

הערה: לכל הערכים יש את התחביר המוצג לעיל, למשל { "ערך": "1" } בתור הפלט של נושאי המנוי, בעוד שהערך נכתב ישירות במטען כדי לשנות ערך (כלומר עבור נושאים לפרסום) - הסוגריים ו "ערך" מושמט, למשל "onoff": "1".

פקודות מתקדמות

מָבוֹא

ישנם 3 סוגי נושאים באופן כללי:

1. הירשם לנושאים כדי לראות את הרכיבים הזמינים וכדי לקבל שינויים בערך בזמן אמת
2. הירשם לנושאים כדי לקבל את התשובות ל (את הלקוחות ) לפרסם בקשות
3. פרסם נושאים כדי לקבל או להגדיר אלמנטים עם הערכים שלהם

בהמשך נתייחס לסוגים אלה באמצעות המספור המוצג כאן (למשל נושאים מסוג 1, 2, 3). פרטים נוספים בסעיפים הבאים ובפרק. 4.2.

הירשמו לנושאים כדי לראות את האלמנטים הזמינים וכדי לקבל שינויי ערך בזמן אמת

אלה כבר תוארו

הירשמו לנושאים כדי לקבל את התשובות לבקשות הפרסום של הלקוח

נושאים מסוג זה הם אופציונליים. זה מאפשר

• פתח ערוץ תקשורת ייחודי עם שרת MQTT על ידי שימוש ב-client_id שרירותי. עוד על כך בפרק. 4.2.2
• קבל את התוצאה של בקשות פרסום בנושא הרשמה המתאים: הצלחה או כישלון עם קוד שגיאה והודעה.

ישנם נושאים שונים לקבל תשובות לקבל או להגדיר פקודות פרסום. ההבדל המקביל ב ברגע שתקבלו את הנושאים הדרושים למערכת שלכם ישר, אתם עשויים להחליט להסיר שלב זה ולהשתמש ישירות בנושאים לפרסם.

 פרסם נושאים כדי לקבל או להגדיר אלמנטים עם הערכים שלהם

נושאים אלו משתמשים בנתיב דומה לאלו של הרשמה - השינוי היחיד הוא המילה "בקשה" במקום ה"סטטוס" המשמש להרשמה. נתיבי נושא מלאים מוצגים בהמשך פרק. 4.2.2\ נושא get יבקש לקרוא את האלמנטים והערכים של שרת MQTT. ניתן להשתמש במטען כדי לסנן על סמך סוג הפונקציה של האלמנטים. נושא מוגדר יבקש לשנות חלקים מסוימים של אלמנט, כמפורט במטען שלו.

תחילית לפקודות ולתגובות מתאימות

 הסבר קצר

לכל הפקודות שנשלחות לשרת MQTT יש חלק ראשוני משותף, כלומר:

הסבר מפורט

לנושאים בזמן אמת (סוג 1) תהיה הקידומת הכללית (ראה למעלה) ולאחר מכן

or

עבור פקודות מוגדרות, המטען ממלא כמובן את התפקיד העיקרי שכן הוא יכיל את השינויים הרצויים (כלומר השתנו ערכים עבור פונקציות האלמנט). אזהרה: לעולם אל תשתמש באפשרות השמירה בפקודות מסוג 3 שלך מכיוון שהיא עלולה לגרום לבעיות בצד KNX.

EXAMPLE: פרסם לשינוי ערכי/ים של רכיב בודד

המקרה הפשוט ביותר הוא לרצות לשנות את הערך של אחד האלמנטים המוצגים על ידי המנוי הכללי.
באופן כללי, שינוי/החלפה של פונקציה של VISION באמצעות MQTT מורכב מ-3 שלבים, שלא כולם נחוצים לחלוטין, אך בכל זאת אנו ממליצים לבצע אותם כמתואר.

1. הנושא המכיל את הפונקציה שאנו רוצים לערוך נרשם באמצעות זיהוי לקוח מותאם אישית
2. הנושא לעריכה מתפרסם יחד עם המטען עם השינויים הרצויים באמצעות ה-client_id שנבחר ב-1.
3. כדי לבדוק, לאחר מכן תוכל לראות את התשובה בנושא (1.) – כלומר האם (2.) עבד או לא
4. במנוי הכללי, שבו כל הערכים מתעדכנים בעת ביצוע שינויים, ניתן לראות את שינויי הערך הרצויים אם הכל הסתדר.

השלבים לעשות זאת הם:

1. בחר client_id למשל "Divus" והכנס אותו לנתיב אחרי שם המשתמש של ה-API
   זהו הנושא המלא להרשמה לערוץ תקשורת משלך עם שרת MQTT. זה אומר לשרת לאן אתה מצפה לתגובות לשינויים שאתה מתכוון לשלוח. שימו לב לחלק הסטטוס/סט שמגדיר את א. שזה נושא הרשמה וב. שהוא יקבל את התשובות לפקודות הגדרת סוג.
2. נושא הפרסום יהיה זהה למעט החלפת מילות המפתח של בקשת הסטטוס
3. ממה השינוי צריך להיות כתוב במטען. הנה כמה לשעברamples.
   • כיבוי של רכיב בעל פונקציית הפעלה/כיבוי (ביט אחד):
   • הפעלת אלמנט בעל פונקציית הדלקה/כיבוי (1 ביט). בנוסף, אם מספר פקודות כאלה מופעלות מאותו לקוח, ניתן להשתמש בפרמטר uuid ("מזהה ייחודי", הוא בדרך כלל מחרוזת של 128 סיביות בפורמט כ-8-4-4-4-12 ספרות hex) כדי להקצות את תגובה לשאילתה המתאימה, שכן פרמטר זה - אם קיים בשאילתה - ניתן למצוא גם בתגובה.
   • הפעלה והגדרת בהירות של דימר ל-50%
   • התשובה לנושא המוצג ומנוי לעיל (המטען שלו, ליתר דיוק) היא אז, למשלample.
     התגובה לעיל היא אקסample במקרה של מטען נכון, למרות שלאלמנט אין פונקציית עמעום. אם יש בעיות חמורות יותר המובילות את המטען לא להתפרש כהלכה, התגובה תיראה כך (למשל):
     להסבר על קודי השגיאה וההודעות אבל באופן כללי, כמו עבור http, 200 קודים הם תשובות חיוביות בעוד 400 הם שליליים.

EXAMPLE: פרסם לשינוי ערכי רכיבים מרובים

ההליך דומה לזה שהוצג לפני כדי לשנות אלמנט בודד. ההבדל הוא שאתה משמיט את ה-element_id מהנושאים ואז מציין את קבוצת ה-element_ids מול הנתונים בתוך המטען. ראה את התחביר והמבנה שלהלן.

סנן לפי סוג פונקציה בשאילתות

פרמטר המסננים במטען מאפשר לטפל רק בפונקציות הרצויות של אלמנט. פונקציית ההפעלה/כיבוי של מתג או דימר נקראת "onoff", למשלample, והמסנן המתאים מוגדר בצורה זו:

התשובה נראית כך, למשלample

הסוגריים המרובעים מציינים שניתן לסנן גם לפי מספר פונקציות, למשל

מוביל לתשובה כזו:

נִספָּח

קודי שגיאה

שגיאות בתקשורת MQTT גורמות לקוד מספרי. הטבלה הבאה עוזרת לפרק אותה.

פרמטרים של המטען

המטען תומך בפרמטרים שונים בהתאם להקשר. הטבלה הבאה מראה אילו פרמטרים יכולים להופיע באילו נושאים

הערות גרסה

• גרסת 1.00

חֲדָשׁוֹת:

• פרסום ראשון

מסמכים / משאבים

	תוכנת API של DIVUS VISION [pdfמדריך למשתמש תוכנת VISION API, תוכנת API, תוכנה
	תוכנת DIVUS Vision API [pdfמדריך למשתמש Vision API Software, Vision, API Software, Software

הפניות

• מדריך למשתמש