Konsep DSL

Ini adalah ringkasan konsep dasar Automation DSL.

Komponen otomatisasi

Otomatisasi terdiri dari komponen dasar berikut, yang biasanya dievaluasi dalam urutan ini:

1. Pemicu — Menentukan kondisi awal yang mengaktifkan otomatisasi, seperti perubahan pada karakteristik. Otomatisasi harus memiliki pemicu.
2. Condition — Batasan tambahan apa pun yang akan dievaluasi setelah otomatisasi diaktifkan. Ekspresi dalam Kondisi harus dievaluasi ke true agar tindakan otomatisasi dapat dilanjutkan.
3. Tindakan — Perintah atau pembaruan status yang dilakukan saat semua kondisi telah terpenuhi.

Misalnya, Anda mungkin memiliki otomatisasi yang meredupkan lampu di ruangan saat TV di ruangan tersebut dinyalakan antara matahari terbenam dan terbit. Dalam contoh ini:

1. Starter — TV dinyalakan, yang merupakan perubahan status pada karakteristik TV.
2. Kondisi— Waktu saat ini untuk rumah tempat TV berada dievaluasi.
3. Tindakan — Lampu di ruangan yang sama dengan TV akan diredupkan.

Otomatisasi akan diaktifkan saat TV di ruangan dinyalakan, tetapi otomatisasi hanya dijalankan jika kondisi "waktu antara matahari terbenam dan matahari terbit" terpenuhi.

Selain struktur dasar, otomatisasi di Home API juga berisi metadata, seperti name dan description, yang dapat digunakan untuk mengidentifikasi otomatisasi bagi developer dan pengguna.

Node

Di Home API, struktur logis otomatisasi terdiri dari nodes. Node adalah unit abstrak yang dapat digunakan kembali dan mewakili perilaku entitas atau alur eksekusi. Setiap node dapat memiliki variabel input, serta variabel output yang dapat digunakan oleh node lain.

Node perilaku

Node seperti pemicu dan tindakan adalah node perilaku. Pemicu mengaktifkan otomatisasi berdasarkan perubahan atribut perangkat. Tindakan mengeluarkan perintah perangkat atau memperbarui atribut.

Node perilaku biasanya terikat dengan karakteristik perangkat dan status karakteristik output untuk digunakan sebagai input di node lain.

Node alur eksekusi

Beberapa node mewakili alur eksekusi, seperti berurutan dan paralel. Setiap node ini berisi node perilaku yang menentukan otomatisasi.

Misalnya, alur berurutan dapat berisi node yang dieksekusi dalam urutan berurutan. Biasanya, ini adalah pemicu, kondisi, dan tindakan.

Alur paralel dapat memiliki beberapa node tindakan yang dijalankan secara bersamaan, seperti menyalakan beberapa lampu secara bersamaan. Node yang mengikuti alur paralel tidak akan dieksekusi hingga semua cabang alur paralel selesai.

Jenis alur eksekusi lainnya adalah alur kondisi, yang dapat mengubah alur eksekusi berdasarkan evaluasi ekspresi.

Misalnya, Anda mungkin memiliki otomatisasi yang melakukan tindakan berdasarkan apakah saat ini malam hari. Node kondisi memeriksa waktu, lalu mengikuti jalur eksekusi yang sesuai berdasarkan evaluasi tersebut.

Flow pilih berguna jika Anda ingin memiliki lebih dari satu pemicu yang dapat mengaktifkan otomatisasi. Saat Anda menyertakan dua pemicu atau lebih dalam alur select, salah satu pemicu dapat mengaktifkan otomatisasi.

Misalnya, Anda dapat menulis otomatisasi yang menurunkan tirai saat matahari terbenam, jika suhu naik di atas nilai minimum tertentu, atau jika kecerahan melebihi nilai minimum. Tiga pemicu terpisah menangani setiap skenario ini, dan ketiganya akan digabungkan dalam alur select.

Alur bertingkat

Dalam otomatisasi yang kompleks, node alur eksekusi juga dapat disusun bertingkat. Misalnya, Anda mungkin memiliki alur berurutan yang menjalankan alur paralel.

Node DSL dapat disusun bertingkat dan digabungkan dengan berbagai cara untuk memenuhi kebutuhan khusus Anda, sesuai dengan batasan yang diuraikan dalam tabel berikut. Kolom Builder tertaut ke dokumentasi builder typesafe Kotlin, yang menjelaskan apa saja yang diizinkan untuk digunakan di setiap jenis node.

DSL Otomatisasi

Di Home API, otomatisasi ditentukan menggunakan Automation DSL (Domain-Specific Language). DSL Otomatisasi diimplementasikan sebagai DSL Kotlin (bahasa khusus domain), menggunakan builder jenis aman Kotlin dan dirancang khusus untuk menentukan template otomatisasi.

Saat otomatisasi dikompilasi, builder aman jenis Kotlin akan menghasilkan class data Kotlin yang kemudian diserialisasi ke JSON buffering protokol, yang digunakan untuk melakukan panggilan ke Layanan Otomatisasi Google.

Automation DSL menyederhanakan dan menyederhanakan proses pembuatan otomatisasi. API ini secara native menggunakan model data yang sama dari sifat standar Matter dan sifat smart home yang ditampilkan di Device API.

DSL Otomatisasi juga menentukan logika otomatisasi dalam hal jenis perangkat abstrak, bukan instance perangkat tertentu yang berada di rumah pengguna. Hal ini memungkinkan developer memberikan parameter input yang dapat digunakan saat runtime untuk menentukan instance perangkat yang sebenarnya, serta nilai parameter penting lainnya.

Sintaksis DSL mirip dengan Kotlin, dan sama-sama aman jenis, tetapi otomatisasi yang ditulis dalam Automation DSL lebih sederhana dan lebih ringkas daripada otomatisasi yang sama yang ditulis dalam Kotlin murni.

Contoh

Berikut adalah contoh otomatisasi yang mengaktifkan perangkat, yang ditulis menggunakan Automation DSL:

val automation = automation {
  name = "MyFirstAutomation"
  description = "If light1 is on, turn on light2."
  isActive = true
  sequential {
    val onOffTrait = starter<_>(device1, OnOffLightDevice, OnOff)
    condition() { expression = onOffTrait.onOff equals true }
    action(device2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

Otomatisasi ini sangat mendasar: saat device1, lampu, menyala (atribut onOff berubah menjadi true), lalu mengirim perintah on() untuk mengaktifkan device2.

Otomatisasi menggunakan node sequential, yang menunjukkan bahwa node-nya akan berjalan dalam urutan berurutan.

Dalam node sequential terdapat node perilaku seperti starter, condition, dan action. Output node starter ditetapkan ke variabel untuk digunakan di node condition.