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.

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

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

Otomatisasi ditulis menggunakan DSL Otomatisasi, bahasa khusus domain yang dirancang untuk membangun otomatisasi di Kotlin.

Setiap karakteristik dan jenis yang ingin Anda gunakan di aplikasi dengan Device & Structure API atau Automation API harus didaftarkan saat inisialisasi. Lihat Melakukan inisialisasi 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 apakah izin masih berlaku. Jika izin telah dicabut, pastikan semua data sebelumnya dihapus, termasuk data yang di-cache dalam aplikasi.

Saat akses struktur dicabut, StructureAccessRevokedEvent akan dikirim ke backend cloud Anda. Lihat Izin struktur untuk alur kerja pencabutan aplikasi seluler dan cloud partner secara menyeluruh.

Perjalanan developer

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

1. Developer merencanakan otomatisasi dan menentukannya menggunakan DSL Otomatisasi.
2. Developer menyematkan definisi otomatisasi di aplikasi Android Kotlin.
3. Aplikasi ini menyajikan otomatisasi kepada pengguna berdasarkan informasi tentang perangkat mereka, termasuk karakteristik, 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 seperti Discovery API, tetapi tidak dioptimalkan untuk kasus penggunaan otomatisasi. Lihat Membandingkan Device API dan Discovery API untuk mengetahui detail selengkapnya.
4. Aplikasi akan membuat otomatisasi sebenarnya yang dikaitkan dengan struktur yang dipilih.
5. Otomatisasi kini tersedia dalam 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 kumpulan perangkat yang berbeda. Setiap kali mereka melakukannya, aplikasi akan membuat instance baru dari otomatisasi.

Dalam skenario paling dasar, Anda dapat menyarankan otomatisasi yang telah ditentukan kepada pengguna yang melakukan tugas yang relatif dasar. 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 elemen penyusun yang tersedia di Automation API.

Saran otomatisasi

   Diimplementasikan di Aplikasi Contoh untuk Android   

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() dimaksudkan untuk dihubungkan 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 mencatat 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 pemicu (seperti payload peristiwa) atau node pembaca status, atau dari variabel lokal yang dideklarasikan dalam alur otomatisasi.
• Ekspresi yang menangkap nilai dinamis runtime (seperti properti peristiwa atau nilai status) dan meneruskan nilai dinamis langsung ke parameter perintah.

Kasus penggunaan

Mengikat sakelar putar fisik yang mengirimkan 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

Dalam DSL Otomatisasi di Android, parameter perintah menerima instance Expression atau Reference langsung sebagai pengganti nilai konstanta statis. DSL merangkumnya ke dalam definisi Parameter 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 upstream dalam grafik otomatisasi sebelum direferensikan dalam tindakan perintah downstream.

Menggunakan parameter perintah dinamis di Android

Teruskan 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 referensikan 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: