Perisian s HALO Smart Sensor API Perisian Asas
ke hadapan
Dokumen ini menerangkan kumpulan kemudahan Sensor Pintar Halo yang dikenali secara kolektif sebagai API BASIC, atau Antara Muka Pengaturcaraan Aplikasi. Perbincangan ini bertujuan untuk digunakan oleh pengaturcara atau penyepadu yang berminat untuk menyepadukan satu atau lebih Penderia Pintar HALO (HALO) dengan komponen atau sistem perisian pihak ketiga (bukan IPVideo). Secara umum, API HALO bertujuan untuk memindahkan maklumat dengan cekap daripada HALO melalui rangkaian Ethernet konvensional kepada program luaran. Untuk mencapai matlamat ini, API dibahagikan kepada tiga bahagian: Sambungan Soket Didorong Peristiwa, Sambungan Soket Denyutan Jantung dan Data Acara URL. Antara muka BACnet juga terdapat dan diliputi dalam dokumen yang berasingan.
Reka Bentuk API
API direka bentuk menggunakan format standard industri seperti TCP/IP. HTTP, HTTPS dan JSON. Reka bentuk tidak memerlukan sebarang teknik atau perpustakaan khas atau proprietari untuk digunakan dalam pembangunan program atau aplikasi luaran. API adalah fleksibel dan boleh dikonfigurasikan serta diprogramkan untuk menyampaikan data yang diperlukan dengan tepat dan dengan cara yang paling cekap. Butiran operasi setiap bahagian di atas diliputi dalam bahagian berikut panduan ini.
Pemesejan Luaran
Kemudahan ini digunakan untuk menyampaikan makluman atau penggera dan data Acara kepada program luaran, sistem VMS, pelayan, dll. apabila Acara dicetuskan (ditetapkan). Mesej pilihan juga boleh didayakan untuk memberi isyarat apabila Acara dikosongkan (ditetapkan semula). Penghantaran ini boleh dibuat ke soket TCP/IP atau pelayan HTTP/S dalam masa nyata. Terdapat pelbagai protokol yang boleh dikonfigurasikan dengan kandungan yang boleh disesuaikan. Pengesahan dan penyulitan tersedia.
Degupan jantung
Mesej degupan jantung dihantar pada selang masa yang boleh dikonfigurasikan (bukannya apabila Peristiwa dicetuskan) untuk memberikan bukti langsung/ketersediaan. Mereka mempunyai julat keupayaan yang sama seperti Pemesejan Luaran tetapi biasanya akan dikonfigurasikan untuk mengandungi maklumat keadaan umum dan bukannya butiran tentang acara tertentu.
Data Peristiwa URL
Kemudahan ini hanya tersedia di bawah NDA dan hanya boleh digunakan apabila program luaran memerlukan akses kepada mana-mana dan semua nilai Acara, ambang dan bendera keadaan. Data ini biasanya diambil atas permintaan oleh program luaran tetapi bukan pada frekuensi yang sangat tinggi. Kaedah ini biasanya menimbulkan sedikit kependaman apabila kadar pengundian sederhana digunakan. Kadar pengundian biasa berjulat dari sekali seminit hingga sekali setiap 5 saat dengan kadar maksimum mutlak sekali sesaat. Kaedah ini juga boleh digunakan untuk mendapatkan data sokongan tambahan apabila Peristiwa (makluman) diterima.
Butiran Pemesejan Luaran
Satu bahagian daripada HALO web pop timbul integrasi antara muka menyediakan konfigurasi sambungan pihak ke-3 tunggal di mana pelbagai nilai boleh dihantar ke soket TCP jauh atau pelayan HTTP/HTTPS. Pemegang tempat (token) digunakan untuk memasukkan nilai langsung ke dalam teks yang dihantar. Walaupun berlabel "Pemesejan Luaran", saluran ini boleh digunakan untuk hampir semua tujuan yang memerlukan pencetus Peristiwa masa nyata, yang dihantar secara aktif oleh HALO. Susunan ini agak fleksibel kerana pilihan pada "Tindakan" menentukan Acara HALO yang dihantar melalui saluran ini.
Dalam mod HTTP, Tetapkan dan Tetapkan Semula Rentetan ialah URLs yang mesti dimasukkan dan diformatkan seperti yang diperlukan oleh pelayan destinasi yang dikehendaki. Medan Pengguna dan Kata Laluan boleh digunakan untuk pengesahan. Lihat mod HTTP di bawah.
Dalam mod TCP, Tetapkan dan Tetapkan Semula Rentetan hanyalah data bagi satu mesej yang dihantar ke soket TCP penerima. Mereka boleh diformatkan mengikut keperluan oleh destinasi. Destinasi ditentukan dalam medan Alamat dan Pelabuhan. Lihat Mod TCP di bawah.
Untuk mana-mana mod, status daripada mesej terbaharu dipaparkan yang boleh membantu membetulkan sambungan atau isu lain. Anda boleh menggunakan butang UJIAN Acara pada pop timbul Tindakan untuk memaksa mesej:
Hidup/Mati Global untuk Set atau Set Semula mestilah Hidup untuk mendayakan jenis mesej tersebut. Tetapan semula selalunya tidak digunakan kerana hanya permulaan Peristiwa yang menarik, tetapi itu boleh berbeza-beza. Setiap Peristiwa boleh menentukan secara bebas sama ada ia akan menggunakan sama ada Set atau mesej Reset pada pop timbul Tindakan. Butang bola mata akan memaparkan gambaran kasar tentang perkara yang dihantar selepas penggantian kata kunci dan pemformatan. Repeat Holdoff boleh digunakan untuk mendikit mesej yang kerap dengan menangguhkan sebelum mesej lain boleh dihantar. Ini dilakukan secara bebas setiap Acara. HALO mempunyai masa penahanan terbina dalam untuk acara selama 15 saat untuk mengelakkan mencetuskan semula Peristiwa dengan pantas. Jika anda ingin memastikan tidak lebih daripada 1 Peristiwa jenis dihantar seminit, anda boleh menetapkan Repeat Holdoff kepada 60 (saat).
Butiran degupan jantung
Penghantaran Degupan Jantung berfungsi dengan cara yang sama seperti di atas kecuali tiada interaksi dengan halaman Tindakan. Sebaliknya, penghantaran Denyutan Jantung berlaku secara tetap seperti yang dikonfigurasikan dengan medan Selang, Dalam mod HTTP, Tetapkan dan Tetapkan Semula Rentetan ialah URLs yang mesti dimasukkan dan diformatkan seperti yang diperlukan oleh pelayan destinasi yang dikehendaki. Medan Pengguna dan Kata Laluan boleh digunakan untuk pengesahan. Lihat mod HTTP di bawah.
Walaupun tujuan utama Denyutan Jantung adalah untuk memberikan bukti hayat Penderia Pintar HALO kepada aplikasi jauh, mesej ini juga boleh digunakan untuk menghantar penderia terpilih atau maklumat keadaan Acara semasa. bekas ituample di atas menghantar parameter rentetan panjang dengan URL yang termasuk nama Halo, majoriti nilai penderia, dan terakhir Dicetuskan=%ACTIVE% yang mungkin kosong atau senarai Peristiwa yang dicetuskan pada masa ini.
Mod HTTP (dan HTTPS).
Rentetan Pemesejan Luaran dan Denyutan Jantung boleh menjadi http: atau https: URLs mengikut keperluan. Laluan dan parameter boleh dimasukkan seperti yang diperlukan oleh pelayan destinasi. Kata kunci seperti %NAME% (nama peranti HALO) atau %EID% (id Acara) boleh dimasukkan mengikut keperluan dan akan digantikan dengan data masing-masing apabila mesej dihantar. Senarai kata kunci yang biasa digunakan ditunjukkan untuk rujukan cepat.
The URL laluan boleh mengandungi kata kunci serta parameter kepada URL. Parameter mungkin NAME=VALUE pasangan atau objek JSON, atau format tersuai bergantung pada pelayan destinasi. Cthamples untuk Pemesejan Luaran akan termasuk %EID% untuk menunjukkan Peristiwa yang mencetuskan:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Examples untuk Denyutan Jantung mungkin menambah %ACTIVE% (Peristiwa yang dicetuskan pada masa ini) atau nilai penderia:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Nilai %SENSOR:…% menggunakan nama yang terdapat dalam tajuk lajur sensor sebelah kanan dalam log evtYYYYMMDD.csv files. Mereka biasanya:
Jika pelayan destinasi lebih suka HTTP PUT atau POST daripada permintaan GET, anda boleh awalan URL dengan PUT: atau POST:. Secara bebas, anda boleh menambah muatan JSON yang popular dengan banyak pelayan dengan menambahkan kata kunci [JSONBODY] diikuti dengan objek berformat JSON. Cthample:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
The URL menyokong pilihan alamat IP biasa (dan IPv6) dan port dan kata laluan pengguna, atau anda boleh menggunakan medan Pengguna dan Kata Laluan jika perlu menjadi pelayan destinasi untuk kaedah pengesahan seperti Asas atau Digest:
https://username:password@123.321.123.321:9876/event…
Mod TCP
Rentetan Pemesejan Luaran dan Denyutan Jantung hanyalah untuk data memandangkan medan Alamat dan Pelabuhan menentukan destinasi. Alamat menyokong nama, IPv4 dan IPv6.
Rentetan boleh diformatkan seperti bahagian data mesej HTTP yang diterangkan di atas, atau seperti yang diperlukan oleh pelayan destinasi.
Examples untuk Pemesejan Luaran akan termasuk %EID% untuk menunjukkan Peristiwa yang mencetuskan:
lokasi=%NAME%,acara=%EID%
{“lokasi”:”:%NAME%”,”acara”:”%EID%”}
Examples untuk Denyutan Jantung mungkin menambah %ACTIVE% (Peristiwa yang dicetuskan pada masa ini) atau nilai penderia:
lokasi=%NAME%&Dicetuskan=%ACTIVE%
{“lokasi”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Kotak pilihan dalam lajur "Set Penyepaduan" dan "Tetapan Semula Penyepaduan" menentukan Peristiwa yang mencetuskan penghantaran. Lebih lanjut mengenai persediaan Acara dan Tindakan tersedia dalam Panduan Pentadbir HALO.
Penghantaran Mesej Acara JSON
Sesetengah pembangun lebih suka menerima data Peristiwa yang diformatkan sebagai JSON berlabel sendiri standard industri berbanding teks ASCII biasa kerana yang pertama lebih dipercayai dan lebih mudah dihuraikan. Pada HALO web halaman "Pemesejan", anda boleh membekalkan mesej JSON dalam tetapan "Pemesejan Luaran" "Tetapkan Rentetan" dan "Tetapkan Semula Rentetan" dan dalam "Degupan Jantung" "Mesej".
Examples:
Tetapan "Pemesejan Luaran" Tetapkan Rentetan:
{ “peranti”:”%NAME%”, “acara”:”%EID%”, “penggera”:”ya” }
Ini akan menghantar satu mesej TCP atau UDP JSON kepada pelayan tertentu yang melaporkan nama peranti mesra, nama acara dan ia baru sahaja bermula.
Tetapan "Pemesejan Luaran" Tetapkan Semula Rentetan:
{ “peranti”:”%NAME%”, “acara”:”%EID%”, “penggera”:”tidak” }
Ini akan menghantar satu mesej TCP atau UDP JSON kepada pelayan yang ditentukan yang melaporkan nama peranti mesra, nama acara dan bahawa keadaan kini telah berhenti.
Mesej "Denyutan Jantung":
{ “peranti”:”%NAME%”, “hidup”:”%DATE% %TIME%” }
Ini secara berkala akan menghantar mesej TCP atau UDP JSON kepada pelayan yang dinyatakan melaporkan bahawa HALO masih hidup pada masa yang dinyatakan.
Dokumen / Sumber
 |
Perisian s HALO Smart Sensor API Perisian Asas [pdf] Panduan Pengguna Perisian Asas API Sensor Pintar HALO |
