Android'deki Otomasyon API'sine genel bakış

Otomasyonlar, evdeki görevleri ve cihaz ayarlarını otomatikleştirmenin bir yoludur. Otomasyonlar, Google Home ekosisteminde Google Home app (GHA) uygulamasında ve Google Home for web cihazlarındaki automation script editor üzerinden rutinler olarak kullanılabilir.

Google Home ekosistemindeki otomasyonlar artık Android için Home API'leri üzerinden kullanılabilir. GHA rutinleri ve script editor ile aynı temel kavramları kullanırlar ancak yalnızca Home API'leri aracılığıyla kullanılabilen gelişmiş özellikler ve işlevler sunarlar. Örneğin:

• Home API'lerinde sunulan tüm Matter standart ve smart home özelliklerine erişim.
• Sıralı, paralel ve seçmeli yürütme akışları için destek.

Otomasyonlar, Kotlin'de otomasyon oluşturmak için tasarlanmış, alana özel bir dil olan Automation DSL kullanılarak yazılır.

Uygulamanızda Device & Structure veya Automation API'leri ile kullanmak istediğiniz tüm özellikler ve türler, başlatma sırasında kaydedilmelidir. Android'de Ana Sayfa'yı ilk kullanıma hazırlama başlıklı makaleyi inceleyin.

Kullanıcı tam izinleri iptal ederse ne yapılmalı?

Kullanıcı tam izinleri iptal ederse mevcut tüm otomasyonlar çalışmayı durdurur. Ayrıca, kullanıcı belirli cihazlara erişimi iptal ederse bu cihazlarla ilişkili başlatıcılar, koşullar ve işlemler çalışmayı durdurur.

Uygulama her başlatıldığında izinlerin hâlâ geçerli olup olmadığını kontrol edin. İptal edilmişse uygulamada önbelleğe alınmış veriler de dahil olmak üzere önceki tüm verilerin kaldırıldığından emin olun.

Yapı erişimi iptal edildiğinde bulut arka ucunuza bir StructureAccessRevokedEvent gönderilir. Uçtan uca iş ortağı bulutu ve mobil uygulama iptal iş akışı için İzinleri yapılandırma bölümüne bakın.

Geliştirici yolculuğu

Automation API, daha büyük bir geliştirme yolculuğunun bir parçasıdır. Bu adım, kullanıcının otomasyon kullanmak istediğinde bunu yapabilmesi için Structure ve Device API'leri entegre edildikten sonra gerçekleştirilir.

1. Geliştirici, otomasyonunu planlar ve Automation DSL'yi kullanarak tanımlar.
2. Geliştirici, otomasyon tanımını bir Kotlin Android uygulamasına yerleştirir.
3. Uygulama, Discovery API veya Device API kullanılarak toplanan özellikler, nitelikler, komutlar ve etkinlikler de dahil olmak üzere cihazlarıyla ilgili bilgilere göre kullanıcıya otomasyonlar sunar.
   1. Discovery API sayesinde uygulama, kullanıcının yapısında bulunan cihaz türlerine ve özelliklerine göre özelleştirilmiş bir otomasyon taslağı oluşturabilir. Bu işlem, kullanıcının girişiyle veya girişi olmadan yapılabilir.
   2. Device API, Discovery API ile hemen hemen aynı bilgileri sağlayabilir ancak otomasyon kullanım alanları için optimize edilmemiştir. Daha fazla bilgi için Device API ile Discovery API'yi karşılaştırma başlıklı makaleyi inceleyin.
4. Uygulama, seçilen yapıya göre asıl otomasyonu oluşturur.
5. Otomasyon artık kullanıcının yapısında kullanılabilir ve Structure API yöntemleri kullanılarak yürütülebilir veya silinebilir.

Kullanıcı, farklı bir yapı veya uygulama mantığına bağlı olarak farklı bir cihaz grubu seçerek istediği zaman otomasyonun yeni örneklerini oluşturabilir. Kullanıcılar her seferinde otomasyonun yeni bir örneğini oluşturur.

En basit senaryoda, kullanıcılarınıza nispeten basit bir görevi yerine getiren önceden tanımlanmış bir otomasyon önerebilirsiniz. Alternatif olarak, kullanıcının ihtiyaçlarına göre özelleştirebileceği bir otomasyon taslağı sunabilirsiniz. Dilerseniz kullanıcının Automation API'deki tüm yapı taşlarını kullanarak karmaşık otomasyonlar oluşturmasına olanak tanıyan açık uçlu bir otomasyon düzenleyici de yazabilirsiniz.

Otomasyon oluşturma ve yönetme

Android'de otomasyon oluşturmak ve yönetmek için:

1. SDK başlatma sırasında HomeConfig öğesine iletilen FactoryRegistry içinde otomasyonlarınız tarafından referans verilen tüm cihaz türlerini ve özelliklerini kaydedin. Kayıt ayrıntıları için Android'de evi ilk kullanıma hazırlama başlıklı makaleyi inceleyin.
2. automation() DSL'yi kullanarak DraftAutomation (BaseAutomation) oluşturun ve Structure nesnesinde standart HasAutomations yöntemlerini çağırın:
   • Yapıda otomasyon oluşturmak için createAutomation() öğesini çağırın.
   • Uygulamanız tarafından yapıda oluşturulan otomasyonları listelemek veya almak için automations() yöntemini çağırın.
   • Meta verilerini güncellemek veya automationGraph değerini değiştirmek için bir Automation örneğinde update() yöntemini çağırın.
   • Bir otomasyonu kimliğe göre kaldırmak için deleteAutomation() yöntemini çağırın.

val draft = automation {
  name = "Turn on light"
  description = "Turn on light2 when light1 turns on."
  sequential {
    val starterNode = starter<_>(light1, OnOffLightDevice, OnOff)
    condition { expression = starterNode.onOff equals true }
    action(light2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

val createdAutomation = structure.createAutomation(draft)

DSL söz diziminin tamamı ve CRUD kodu örnekleri için Android'de otomasyon oluşturma başlıklı makaleyi inceleyin.

Otomasyon önerileri

   Android için örnek uygulamada uygulanır   

Home API'leri, alanda bulunan cihaz türleri gibi faktörlere göre Structure için otomasyonlar önerebilir.

Otomasyon önerileri AutomationSuggestion sınıfıyla temsil edilir.

Structure arayüzü, otomasyon önerileri koleksiyonu döndüren suggestions() işlevini sağlayan HasSuggestions arayüzünü kapsar.

likeSuggestion() ve dislikeSuggestion() yöntemleri, kullanıcının geri bildirim vermek için dokunabileceği thumb_up ve thumb_down kullanıcı arayüzü kontrollerine bağlanmak üzere tasarlanmıştır.

Üçüncü yöntem olan clearSuggestionFeedback(), kullanıcının önerilen bir otomasyonla ilgili geri bildirimini kaldırmasına olanak tanır.

Kullanıcı geri bildirimleri gelecekteki önerileri etkiler.

Bu örnekte, Structure için mevcut otomasyon önerilerinin nasıl alınacağı, öneri kimliğinin nasıl ayıklanacağı ve likeSuggestion(), clearSuggestionFeedback() ve dislikeSuggestion() kullanılarak kullanıcı geri bildirimlerinin nasıl kaydedileceği gösterilmektedir.

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)
    }
  }
}

Dinamik komut parametreleri

Dinamik komut parametreleri, geliştiricilerin kesinlikle statik, sabit değerlere güvenmek yerine çalışma zamanında dinamik olarak çözümlenen işlem parametreleri oluşturmasına olanak tanır. Bu sayede iki temel özellikten yararlanabilirsiniz:

• Bir başlatıcıdan (ör. etkinlik yükü) veya durum okuyucu düğümünden ya da otomasyon akışında tanımlanan yerel değişkenlerden bir özelliğin değerini ileten referanslar.
• Çalışma zamanı dinamik değerlerini (ör. etkinlik mülkü veya durum değeri) yakalayan ve dinamik değeri doğrudan bir komut parametresine ileten ifadeler.

Kullanım alanı

Çoklu basma etkinliği gönderen fiziksel bir döner anahtarı, kısılabilir bir ışığa bağlayın. Tıklama sayısı, çalışma zamanında bir LevelControl adım komutuna iletilen dinamik değerdir.

Dinamik parametrelerin işleyiş şekli

Android'deki Otomasyon DSL'de komut parametreleri, statik sabit değerler yerine doğrudan Expression veya Reference örneklerini kabul eder. DSL, otomasyonu oluştururken bunları Parameter tanımlarına dahil eder.

Doğrulama kuralları

Dinamik komut parametreleri aşağıdaki doğrulama kısıtlamalarına tabidir:

• Keşif API'leri yalnızca statik bağımsız değişkenler için somut değer kısıtlamalarını değerlendirdiğinden, dinamik parametrelerin keşif sırasında yapısal olarak geçerli olduğu varsayılır.
• Referans veya ifade düğümleri, otomasyon grafiğinde bir alt komut işleminde referans verilmeden önce üstte görünmelidir.

Android'de dinamik komut parametrelerini kullanma

Dinamik ifadeleri doğrudan komut parametrelerine iletme:

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,
        )
      )
    }
  }
}

Alternatif olarak, bir ifadeyi yerel değişken bildirimine atayabilir ve değişkene akışın ilerleyen kısımlarında başvurabilirsiniz:

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,
        )
      )
    }
  }
}

Tür kısıtlamaları

Değişken ve ifade türlerinin, alıcı komut parametresinin gerekli Matter şema türü tanımıyla (ör. UShort, UByte veya UInt8) uyumlu olduğundan emin olun.

Kaynak sınırları

Home API'lerindeki otomasyonlar için aşağıdaki sınırlar geçerlidir: