Tổng quan về Automation API trên Android

Quy trình tự động hoá là một cách để tự động hoá các công việc và chế độ cài đặt thiết bị trong nhà. Quy trình tự động hoá đã có trong hệ sinh thái Google Home dưới dạng Quy trình trong Google Home app (GHA) và thông qua automation script editor trên Google Home for web.

Giờ đây, bạn có thể sử dụng tính năng Tự động hoá trong hệ sinh thái Google Home thông qua Home API cho Android. Các quy trình này sử dụng cùng một khái niệm cơ bản như trong GHA Quy trình và script editor, nhưng có các tính năng và chức năng nâng cao chỉ có thể thực hiện thông qua Home API, bao gồm:

• Quyền truy cập vào tất cả các đặc điểm tiêu chuẩn của Matter và smart home cho một thiết bị, như được trình bày trong Home API.
• Hỗ trợ các luồng thực thi tuần tự, song song và chọn lọc.

Quy trình tự động hoá được viết bằng Automation DSL, một ngôn ngữ dành riêng cho miền được thiết kế để xây dựng quy trình tự động hoá trong Kotlin.

Mọi đặc điểm và loại mà bạn dự định sử dụng trong ứng dụng của mình bằng API Thiết bị và Cấu trúc hoặc API Tự động hoá đều phải được đăng ký khi khởi chạy. Hãy xem bài viết Khởi động nhà trên Android.

Hướng dẫn trong trường hợp người dùng thu hồi toàn quyền

Nếu người dùng thu hồi toàn quyền, thì tất cả quy trình tự động hoá hiện có sẽ ngừng hoạt động. Ngoài ra, nếu người dùng thu hồi quyền truy cập vào các thiết bị cụ thể, thì các điều kiện khởi động, điều kiện và hành động liên quan đến các thiết bị đó sẽ ngừng hoạt động.

Mỗi lần ứng dụng khởi động, hãy nhớ kiểm tra để đảm bảo các quyền vẫn còn hiệu lực. Nếu các quyền này đã bị thu hồi, hãy đảm bảo rằng tất cả dữ liệu trước đó đều bị xoá, bao gồm cả mọi dữ liệu được lưu vào bộ nhớ đệm trong ứng dụng.

Khi quyền truy cập vào nhà bị thu hồi, một StructureAccessRevokedEvent sẽ được gửi đến phần phụ trợ trên đám mây của bạn. Tham khảo bài viết Cấp quyền truy cập vào cấu trúc để biết quy trình thu hồi quyền truy cập vào ứng dụng di động và đám mây của đối tác từ đầu đến cuối.

Hành trình của nhà phát triển

Automation API là một phần trong hành trình phát triển lớn hơn. API này được tích hợp sau khi tích hợp API Cấu trúc và Thiết bị để đảm bảo rằng khi người dùng muốn sử dụng một quy trình tự động hoá, họ có thể làm như vậy.

1. Nhà phát triển lên kế hoạch tự động hoá và xác định quy trình tự động hoá bằng DSL tự động hoá.
2. Nhà phát triển nhúng định nghĩa tự động hoá vào một ứng dụng Android Kotlin.
3. Ứng dụng này trình bày các quy trình tự động hoá cho người dùng dựa trên thông tin về thiết bị của họ, bao gồm cả các đặc điểm, thuộc tính, lệnh và sự kiện, được thu thập bằng Discovery API hoặc Device API.
   1. Với Discovery API, ứng dụng có thể tạo một quy trình tự động hoá nháp được tuỳ chỉnh theo các loại thiết bị và đặc điểm có trong cấu trúc của người dùng, dù có hoặc không có thông tin đầu vào của người dùng.
   2. Device API có thể cung cấp hầu hết thông tin giống như Discovery API, nhưng không được tối ưu hoá cho các trường hợp tự động hoá. Hãy xem bài viết So sánh Device API và Discovery API để biết thêm thông tin chi tiết.
4. Ứng dụng tạo quy trình tự động hoá thực tế được liên kết với cấu trúc đã chọn.
5. Giờ đây, quy trình tự động hoá đã có trong cấu trúc của người dùng và có thể được thực thi hoặc xoá bằng các phương thức API Cấu trúc.

Người dùng có thể tạo các phiên bản mới của quy trình tự động hoá bất cứ lúc nào, chọn một cấu trúc khác hoặc có thể là một nhóm thiết bị khác, tuỳ thuộc vào logic của ứng dụng. Mỗi lần như vậy, ứng dụng sẽ tạo một thực thể mới của quy trình tự động hoá.

Trong trường hợp cơ bản nhất, bạn có thể đề xuất cho người dùng một quy trình tự động hoá được xác định trước để thực hiện một nhiệm vụ tương đối cơ bản. Ngoài ra, bạn có thể trình bày một bộ khung của quy trình tự động hoá mà người dùng có thể tuỳ chỉnh để đáp ứng nhu cầu của họ. Hoặc bạn có thể viết một trình chỉnh sửa tự động hoá mở, cho phép người dùng xây dựng các quy trình tự động hoá phức tạp bằng cách sử dụng tất cả các khối dựng có sẵn trong Automation API.

Tạo và quản lý quy trình tự động hoá

Cách tạo và quản lý quy trình tự động hoá trên Android:

1. Đăng ký tất cả các loại thiết bị và đặc điểm mà quy trình tự động hoá của bạn tham chiếu trong FactoryRegistry được truyền đến HomeConfig trong quá trình khởi chạy SDK. Để biết thông tin chi tiết về việc đăng ký, hãy xem phần Khởi động nhà trên Android.
2. Tạo DraftAutomation (BaseAutomation) bằng DSL automation() và gọi các phương thức HasAutomations chuẩn trên đối tượng Structure:
   • Gọi createAutomation() để tạo một quy trình tự động hoá trong nhà.
   • Gọi automations() để liệt kê hoặc truy xuất các quy trình tự động do ứng dụng của bạn tạo trong nhà.
   • Gọi update() trên một thực thể Automation để cập nhật siêu dữ liệu hoặc thay thế automationGraph của thực thể đó.
   • Gọi deleteAutomation() để xoá một quy trình tự động hoá theo mã nhận dạng.

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)

Để biết cú pháp DSL hoàn chỉnh và các ví dụ về mã CRUD, hãy xem bài viết Xây dựng quy trình tự động hoá trên Android.

Đề xuất về quy trình tự động hoá

   Được triển khai trong Ứng dụng mẫu cho Android   

Home API có thể đề xuất quy trình tự động hoá cho một Structure dựa trên các yếu tố như loại thiết bị có trong không gian.

Đề xuất tự động hoá được biểu thị bằng lớp AutomationSuggestion.

Giao diện Structure bao gồm giao diện HasSuggestions, cung cấp hàm suggestions() trả về một tập hợp các đề xuất tự động hoá.

Các phương thức likeSuggestion() và dislikeSuggestion() được thiết kế để kết nối với các thành phần điều khiển trên giao diện người dùng thumb_up và thumb_down mà người dùng có thể nhấn vào để đưa ra ý kiến phản hồi.

Phương thức thứ ba, clearSuggestionFeedback(), cho phép người dùng xoá ý kiến phản hồi của họ về một quy trình tự động hoá được đề xuất.

Ý kiến phản hồi của người dùng sẽ ảnh hưởng đến các đề xuất trong tương lai.

Ví dụ này minh hoạ cách truy xuất các đề xuất tự động hoá có sẵn cho một Structure, trích xuất mã đề xuất và ghi lại ý kiến phản hồi của người dùng bằng likeSuggestion(), clearSuggestionFeedback() và 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)
    }
  }
}

Tham số lệnh động

Tham số lệnh động cho phép nhà phát triển tạo các tham số hành động phân giải động trong thời gian chạy thay vì chỉ dựa vào các giá trị tĩnh, không đổi. Điều này cho phép hai chức năng chính:

• Tham chiếu truyền giá trị của một thuộc tính từ một nút khởi động (chẳng hạn như tải trọng sự kiện) hoặc nút đọc trạng thái, hoặc từ các biến cục bộ được khai báo trong quy trình tự động hoá.
• Biểu thức thu thập giá trị động trong thời gian chạy (chẳng hạn như thuộc tính sự kiện hoặc giá trị trạng thái) và truyền trực tiếp giá trị động vào tham số lệnh.

Trường hợp sử dụng

Liên kết một công tắc xoay vật lý gửi sự kiện nhấn nhiều lần với một đèn có thể điều chỉnh độ sáng. Số lượt nhấp là giá trị động được truyền vào lệnh bước LevelControl trong thời gian chạy.

Cách hoạt động của tham số động

Trong Automation DSL trên Android, các tham số lệnh chấp nhận trực tiếp các thực thể Expression hoặc Reference thay cho các giá trị hằng số tĩnh. DSL đóng gói các định nghĩa này vào định nghĩa Parameter khi xây dựng quy trình tự động hoá.

Các quy tắc xác thực

Các tham số lệnh động tuân theo các quy tắc ràng buộc xác thực sau:

• Các tham số động được giả định là hợp lệ về mặt cấu trúc trong quá trình khám phá vì API khám phá chỉ đánh giá các quy tắc ràng buộc về giá trị cụ thể cho các đối số tĩnh.
• Các nút tham chiếu hoặc biểu thức phải xuất hiện ở đầu nguồn trong biểu đồ tự động hoá trước khi được tham chiếu trong một hành động lệnh ở cuối nguồn.

Sử dụng tham số lệnh động trên Android

Truyền trực tiếp biểu thức động đến tham số lệnh:

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

Ngoài ra, hãy chỉ định một biểu thức cho nội dung khai báo biến cục bộ và tham chiếu biến đó sau này trong quy trình:

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

Các quy tắc ràng buộc về loại

Đảm bảo rằng các loại biến và biểu thức phù hợp với định nghĩa loại giản đồ Matter bắt buộc của tham số lệnh nhận (chẳng hạn như UShort, UByte hoặc UInt8).

Giới hạn tài nguyên

Các giới hạn sau đây áp dụng cho quy trình tự động hoá trong Home API: