Ringkasan Automation API di Android

Otomatisasi adalah cara untuk mengotomatiskan tugas dan setelan perangkat di rumah. Otomatisasi telah tersedia di ekosistem Google Home sebagai Rutinitas di Google Home app (GHA) dan melalui automation script editor di Google Home for web.

Sekarang, Otomatisasi di ekosistem Google Home tersedia melalui Home API untuk Android. Fitur ini menggunakan konsep dasar yang sama dengan yang digunakan dalam GHA Rutinitas dan script editor, tetapi dengan fitur dan kemampuan yang ditingkatkan yang hanya dapat dilakukan melalui Home API, termasuk:

• Akses ke semua standar Matter dan karakteristik smart home untuk perangkat, seperti yang ditampilkan di Home API.
• Dukungan untuk alur eksekusi berurutan, paralel, dan pilihan.

Otomatisasi ditulis menggunakan Automation DSL, bahasa khusus domain yang didesain untuk membuat otomatisasi di Kotlin.

Semua karakteristik dan jenis yang ingin Anda gunakan di aplikasi dengan Device & Structure atau Automation API harus didaftarkan saat inisialisasi. Lihat Menginisialisasi rumah di Android.

Panduan jika pengguna mencabut izin penuh

Jika pengguna mencabut izin penuh, semua otomatisasi yang ada akan berhenti berfungsi. Selain itu, jika pengguna mencabut akses ke perangkat tertentu, pemicu, kondisi, dan tindakan yang terkait dengan perangkat tersebut akan berhenti berfungsi.

Setiap kali aplikasi dimulai, pastikan untuk memeriksa bahwa izin masih berlaku. Jika akses telah dicabut, pastikan semua data sebelumnya dihapus, termasuk data yang di-cache di aplikasi.

Saat akses struktur dicabut, StructureAccessRevokedEvent akan dikirimkan ke backend cloud Anda. Lihat Memberi struktur pemberian izin untuk alur kerja pencabutan aplikasi seluler dan cloud partner menyeluruh.

Perjalanan developer

Automation API adalah salah satu bagian dari perjalanan pengembangan yang lebih besar. Hal ini dilakukan setelah mengintegrasikan Structure dan Device API untuk memastikan bahwa pengguna dapat menggunakan otomatisasi saat mereka menginginkannya.

1. Developer merencanakan otomatisasinya, dan menentukannya menggunakan DSL Otomatisasi.
2. Developer menyematkan definisi otomatisasi di aplikasi Android Kotlin.
3. Aplikasi menyajikan otomatisasi kepada pengguna berdasarkan informasi tentang perangkat mereka, termasuk sifat, atribut, perintah, dan peristiwa, yang dikumpulkan menggunakan Discovery API atau Device API.
   1. Dengan Discovery API, aplikasi dapat membuat draf otomatisasi yang disesuaikan dengan jenis dan karakteristik perangkat yang ada dalam struktur pengguna, dengan atau tanpa input pengguna.
   2. Device API dapat memberikan sebagian besar informasi yang sama dengan Discovery API, tetapi tidak dioptimalkan untuk kasus penggunaan otomatisasi. Lihat Membandingkan Device API dan Discovery API untuk mengetahui detail selengkapnya.
4. Aplikasi membuat otomatisasi sebenarnya yang dikaitkan dengan struktur yang dipilih.
5. Otomatisasi kini tersedia di struktur pengguna dan dapat dijalankan atau dihapus menggunakan metode Structure API.

Pengguna dapat membuat instance baru otomatisasi kapan saja, memilih struktur yang berbeda atau, bergantung pada logika aplikasi, mungkin serangkaian perangkat yang berbeda. Setiap kali pengguna melakukannya, aplikasi akan membuat instance baru otomatisasi.

Dalam skenario paling dasar, Anda dapat menyarankan otomatisasi yang telah ditentukan sebelumnya kepada pengguna yang melakukan tugas yang relatif sederhana. Atau, Anda dapat menampilkan kerangka otomatisasi yang disesuaikan pengguna untuk memenuhi kebutuhan mereka. Atau, Anda dapat menulis editor otomatisasi terbuka yang memungkinkan pengguna membuat otomatisasi kompleks menggunakan semua blok penyusun yang tersedia di Automation API.

Saran otomatisasi

Home API dapat menyarankan otomatisasi untuk Structure berdasarkan faktor seperti jenis perangkat yang ada di ruang.

Saran otomatisasi diwakili oleh class AutomationSuggestion.

Antarmuka Structure mencakup antarmuka HasSuggestions yang menyediakan fungsi suggestions() yang menampilkan kumpulan saran otomatisasi.

Metode likeSuggestion() dan dislikeSuggestion() ditujukan untuk terhubung ke kontrol UI thumb_up dan thumb_down yang dapat diketuk pengguna untuk memberikan masukan.

Metode ketiga, clearSuggestionFeedback(), memungkinkan pengguna menghapus masukan mereka untuk otomatisasi yang disarankan.

Masukan pengguna memengaruhi saran di masa mendatang.

Contoh ini menunjukkan cara mengambil saran otomatisasi yang tersedia untuk Structure, mengekstrak ID saran, dan merekam masukan pengguna menggunakan likeSuggestion(), clearSuggestionFeedback(), dan dislikeSuggestion().

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch

class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {

  fun loadAndGiveFeedback() {
    viewModelScope.launch {
      // 1. Fetch suggestions from structure
      val suggestions = structure.suggestions()
      val firstSuggestion = suggestions.firstOrNull() ?: return@launch

      // Extract string suggestion ID
      val suggestionId: String = firstSuggestion.id.id

      // 2. Like the suggestion (thumbs up)
      val liked = structure.likeSuggestion(suggestionId)

      // 3. Clear previous feedback if the user toggled it off
      if (liked) {
        structure.clearSuggestionFeedback(suggestionId)
      }

      // 4. Dislike the suggestion (thumbs down)
      structure.dislikeSuggestion(suggestionId)
    }
  }
}

Parameter perintah dinamis

Parameter perintah dinamis memungkinkan developer membuat parameter tindakan yang diselesaikan secara dinamis saat runtime, bukan hanya mengandalkan nilai statis dan konstan. Hal ini memungkinkan dua kemampuan utama:

• Referensi yang meneruskan nilai properti dari starter (seperti payload peristiwa) atau node pembaca status, atau dari variabel lokal yang dideklarasikan dalam alur otomatisasi.
• Ekspresi yang mengambil nilai dinamis runtime (seperti properti peristiwa atau nilai status) dan meneruskan nilai dinamis langsung ke parameter perintah.

Kasus penggunaan

Mengikat tombol putar fisik yang mengirim peristiwa multi-tekan ke lampu yang dapat diredupkan. Jumlah klik adalah nilai dinamis yang diteruskan ke perintah langkah LevelControl saat runtime.

Cara kerja parameter dinamis

Di DSL Otomatisasi di Android, parameter perintah menerima instance Expression atau Reference langsung di tempat nilai konstanta statis. DSL merangkumnya ke dalam Parameter definisi saat membuat otomatisasi.

Aturan validasi

Parameter perintah dinamis mengikuti batasan validasi berikut:

• Parameter dinamis diasumsikan valid secara struktural selama penemuan karena API penemuan hanya mengevaluasi batasan nilai konkret untuk argumen statis.
• Node referensi atau ekspresi harus muncul di hulu dalam grafik otomatisasi sebelum direferensikan dalam tindakan perintah hilir.

Menggunakan parameter perintah dinamis di Android

Meneruskan ekspresi dinamis langsung ke parameter perintah:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val keypressAutomation = automation {
  name = "Dynamic command parameters example"
  description = "Pass starter event field directly to command"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountExpr,
        )
      )
    }
  }
}

Atau, tetapkan ekspresi ke deklarasi variabel lokal dan rujuk variabel tersebut nanti dalam alur:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val myAutomationWithVariable = automation {
  name = "Dynamic command parameters with variables"
  description = "Declare a variable, assign value, and pass reference"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    val clickCountVar = variable<UInt>()
    clickCountVar.assign(clickCountExpr)

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountVar,
        )
      )
    }
  }
}

Batasan jenis

Pastikan jenis variabel dan ekspresi sesuai dengan definisi jenis skema Matter yang diperlukan parameter perintah penerima (seperti UShort, UByte, atau UInt8).

Batas resource

Batasan berikut berlaku untuk otomatisasi di Home API: