Để hỗ trợ phương thức thực hiện cục bộ, bạn cần xây dựng một ứng dụng để xử lý các ý định nhà thông minh sau đây:
IDENTIFY
: Hỗ trợ khám phá các thiết bị thông minh có thể điều khiển cục bộ. Trình xử lý ý định trích xuất dữ liệu mà thiết bị thông minh của bạn trả về trong quá trình khám phá và gửi dữ liệu này trong một phản hồi cho Google.EXECUTE
: Hỗ trợ thực thi các lệnh.QUERY
: Hỗ trợ truy vấn trạng thái thiết bị.REACHABLE_DEVICES
: (Không bắt buộc) Hỗ trợ việc khám phá các thiết bị cuối có thể điều khiển cục bộ sau một thiết bị trung tâm (hoặc cầu nối).
Ứng dụng này chạy trên các thiết bị Google Home hoặc Google Nest của người dùng và kết nối thiết bị thông minh của bạn với Trợ lý. Bạn có thể tạo ứng dụng bằng cách sử dụng TypeScript (ưu tiên) hoặc JavaScript.
Bạn nên dùng TypeScript vì bạn có thể tận dụng liên kết để đảm bảo tĩnh rằng dữ liệu mà ứng dụng của bạn trả về khớp với các kiểu mà nền tảng dự kiến.
Để biết thêm thông tin chi tiết về API, hãy xem Tài liệu tham khảo API Local Home SDK.
Các đoạn mã sau đây cho thấy cách bạn có thể khởi chạy ứng dụng phương thức thực hiện cục bộ và đính kèm trình xử lý.
import App = smarthome.App; const localHomeApp: App = new App("1.0.0"); localHomeApp .onIdentify(identifyHandler) .onExecute(executeHandler) .listen() .then(() => { console.log("Ready"); });
import App = smarthome.App; const localHomeApp: App = new App("1.0.0"); localHomeApp .onIdentify(identifyHandler) .onReachableDevices(reachableDevicesHandler) .onExecute(executeHandler) .listen() .then(() => { console.log("Ready"); });
Tạo dự án
Để triển khai ứng dụng phương thức thực hiện cục bộ, bạn cần tạo gói JavaScript cho mã và mọi phần phụ thuộc của mã đó.
Sử dụng trình khởi động dự án của ứng dụng phương thức thực hiện cục bộ để khởi động cấu trúc dự án phù hợp với cấu hình trình gói ưu tiên của bạn.
Mẫu dự án
Để chọn cấu hình trình đóng gói, hãy chạy lệnh npm init
như trong ví dụ sau:
TypeScript không có cấu hình trình đóng gói:
npm init @google/local-home-app project-directory/ --bundler none
Cấu trúc dự án:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json └── serve.js
Thay thế project-directory bằng một thư mục mới chứa dự án ứng dụng phương thức thực hiện cục bộ.
TypeScript có cấu hình trình đóng gói webpack:
npm init @google/local-home-app project-directory/ --bundler webpack
Cấu trúc dự án:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json ├── webpack.config.web.js ├── webpack.config.node.js └── serve.js
Thay thế project-directory bằng một thư mục mới chứa dự án ứng dụng phương thức thực hiện cục bộ.
TypeScript với cấu hình gói Rollup:
npm init @google/local-home-app project-directory/ --bundler rollup
Cấu trúc dự án:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json ├── rollup.config.js └── serve.js
Thay thế project-directory bằng một thư mục mới chứa dự án ứng dụng phương thức thực hiện cục bộ.
TypeScript với cấu hình gói Parcel:
npm init @google/local-home-app project-directory/ --bundler parcel
Cấu trúc dự án:
project-directory/ ├── node_modules/ ├── package.json ├── .gitignore ├── index.ts ├── test.ts ├── tsconfig.json ├── tslint.json └── serve.js
Thay thế project-directory bằng một thư mục mới chứa dự án ứng dụng phương thức thực hiện cục bộ.
Thực hiện các thao tác phổ biến ở cấp dự án
Dự án đã tạo hỗ trợ các tập lệnh npm sau:
cd project-directory/ npm run build
Tập lệnh này biên dịch nguồn TypeScript và gói ứng dụng cùng với các phần phụ thuộc của ứng dụng đó cho môi trường thời gian chạy Chrome trong thư mục con dist/web
và môi trường thời gian chạy Node.js trong thư mục con dist/node
.
cd project-directory/ npm run lint npm run compile npm test
Tập lệnh này xác minh cú pháp của mã TypeScript, biên dịch mã mà không tạo ra bất kỳ đầu ra nào trong thư mục con dist/
và chạy kiểm thử tự động từ test.ts
.
cd project-directory/ npm run start
Trong quá trình phát triển, tập lệnh này sẽ phân phát các gói ứng dụng của bạn cho môi trường thời gian chạy Chrome và Node.js cục bộ.
Triển khai trình xử lý IDENTIFY
Trình xử lý IDENTIFY
sẽ được kích hoạt khi thiết bị Google Home hoặc Google Nest khởi động lại và thấy các thiết bị cục bộ chưa được xác minh (bao gồm cả các thiết bị cuối được kết nối với một thiết bị trung tâm). Nền tảng Local Home sẽ quét tìm các thiết bị cục bộ bằng cách sử dụng thông tin cấu hình quét mà bạn đã chỉ định trước đó và gọi trình xử lý IDENTIFY
kèm theo kết quả quét.
IdentifyRequest
từ nền tảng Local Home chứa dữ liệu quét của một thực thể LocalIdentifiedDevice
. Chỉ một thực thể device
được điền sẵn, dựa trên cấu hình quét giúp phát hiện thiết bị.
Nếu kết quả quét khớp với thiết bị của bạn, thì trình xử lý IDENTIFY
sẽ trả về đối tượng IdentifyResponsePayload
, bao gồm đối tượng device
có siêu dữ liệu của nhà thông minh (chẳng hạn như loại, đặc điểm và trạng thái báo cáo).
Google sẽ thiết lập mối liên kết với thiết bị nếu verificationId
trong phản hồi IDENTIFY
khớp với một trong các giá trị otherDeviceIds
mà phản hồi SYNC
trả về.
Ví dụ:
Các đoạn mã sau đây cho biết cách bạn có thể tạo trình xử lý IDENTIFY
cho các thiết bị độc lập tích hợp và thiết bị trung tâm, tương ứng với quá trình tích hợp.
const identifyHandler = (request: IntentFlow.IdentifyRequest): IntentFlow.IdentifyResponse => { // Obtain scan data from protocol defined in your scan config const device = request.inputs[0].payload.device; if (device.udpScanData === undefined) { throw Error("Missing discovery response"); } const scanData = device.udpScanData.data; // Decode scan data to obtain metadata about local device const verificationId = "local-device-id"; // Return a response const response: IntentFlow.IdentifyResponse = { intent: Intents.IDENTIFY, requestId: request.requestId, payload: { device: { id: device.id || "", verificationId, // Must match otherDeviceIds in SYNC response }, }, }; return response; };
const identifyHandler = (request: IntentFlow.IdentifyRequest): IntentFlow.IdentifyResponse => { // Obtain scan data from protocol defined in your scan config const device = request.inputs[0].payload.device; if (device.udpScanData === undefined) { throw Error("Missing discovery response"); } const scanData = device.udpScanData.data; // Decode scan data to obtain metadata about local device const proxyDeviceId = "local-hub-id"; // Return a response const response: IntentFlow.IdentifyResponse = { intent: Intents.IDENTIFY, requestId: request.requestId, payload: { device: { id: proxyDeviceId, isProxy: true, // Device can control other local devices isLocalOnly: true, // Device not present in `SYNC` response }, }, }; return response; };
Xác định các thiết bị trong một thiết bị trung tâm
Nếu xác định được một thiết bị trung tâm, Google sẽ coi trung tâm này là đường dẫn đến các thiết bị cuối được kết nối của trung tâm đó và cố gắng xác minh các thiết bị cuối đó.
Để cho phép Google xác nhận rằng có thiết bị trung tâm, hãy làm theo các hướng dẫn sau đây dành cho trình xử lý IDENTIFY
:
- Nếu phản hồi
SYNC
của bạn báo cáo mã nhận dạng của các thiết bị cuối cục bộ được kết nối với trung tâm, hãy đặtisProxy
làmtrue
trongIdentifyResponsePayload
. - Nếu phản hồi của
SYNC
không báo cáo thiết bị trung tâm, hãy đặtisLocalOnly
làmtrue
trongIdentifyResponsePayload
. - Trường
device.id
chứa mã thiết bị cục bộ cho chính thiết bị trung tâm đó.
Triển khai trình xử lý REACHABLE_devices (chỉ dành cho các sản phẩm tích hợp trung tâm)
Google gửi ý định REACHABLE_DEVICES
để xác nhận xem thiết bị cuối nào có thể điều khiển cục bộ. Ý định này được kích hoạt mỗi khi Google chạy quy trình quét khám phá (khoảng 1 lần mỗi phút), miễn là trung tâm được phát hiện là có kết nối mạng.
Bạn triển khai trình xử lý REACHABLE_DEVICES
tương tự như trình xử lý IDENTIFY
, ngoại trừ việc trình xử lý này cần thu thập các mã thiết bị bổ sung mà thiết bị proxy cục bộ (tức là thiết bị trung tâm) có thể tiếp cận. Trường device.verificationId
chứa mã thiết bị cục bộ của một thiết bị cuối được kết nối với trung tâm.
ReachableDevicesRequest
từ nền tảng Local Home chứa một thực thể của LocalIdentifiedDevice
.
Thông qua phiên bản này, bạn có thể lấy được mã thiết bị proxy cũng như dữ liệu từ kết quả quét.
Trình xử lý REACHABLE_DEVICES
phải trả về một đối tượng ReachableDevicesPayload
bao gồm đối tượng devices
chứa một mảng các giá trị verificationId
đại diện cho các thiết bị cuối mà trung tâm điều khiển. Các giá trị verificationId
phải khớp với một trong các otherDeviceIds
trong phản hồi SYNC
.
Đoạn mã sau đây cho biết cách bạn có thể tạo trình xử lý REACHABLE_DEVICES
.
const reachableDevicesHandler = (request: IntentFlow.ReachableDevicesRequest): IntentFlow.ReachableDevicesResponse => { // Reference to the local proxy device const proxyDeviceId = request.inputs[0].payload.device.id; // Gather additional device ids reachable by local proxy device // ... const reachableDevices = [ // Each verificationId must match one of the otherDeviceIds // in the SYNC response { verificationId: "local-device-id-1" }, { verificationId: "local-device-id-2" }, ]; // Return a response const response: IntentFlow.ReachableDevicesResponse = { intent: Intents.REACHABLE_DEVICES, requestId: request.requestId, payload: { devices: reachableDevices, }, }; return response; };
Triển khai trình xử lý EXECUTE
Trình xử lý EXECUTE
trong ứng dụng sẽ xử lý các lệnh của người dùng và dùng Local Home SDK để truy cập vào các thiết bị thông minh của bạn thông qua một giao thức hiện có.
Nền tảng Local Home sẽ truyền cùng một tải trọng đầu vào cho hàm xử lý EXECUTE
như đối với ý định EXECUTE
đến phương thức thực hiện trên đám mây của bạn. Tương tự, trình xử lý EXECUTE
sẽ trả về dữ liệu đầu ra ở cùng định dạng như khi xử lý ý định EXECUTE
.
Để đơn giản hoá việc tạo phản hồi, bạn có thể sử dụng lớp Execute.Response.Builder
mà SDK Local Home cung cấp.
Ứng dụng của bạn không có quyền truy cập trực tiếp vào địa chỉ IP của thiết bị. Thay vào đó, hãy sử dụng giao diện CommandRequest
để tạo các lệnh dựa trên một trong các giao thức sau: UDP, TCP hoặc HTTP. Sau đó, hãy gọi hàm deviceManager.send()
để gửi các lệnh.
Khi nhắm mục tiêu lệnh đến thiết bị, hãy sử dụng mã thiết bị (và các tham số từ trường customData
, nếu có) từ phản hồi SYNC
để giao tiếp với thiết bị.
Ví dụ:
Đoạn mã sau đây cho biết cách bạn có thể tạo trình xử lý EXECUTE
.
const executeHandler = (request: IntentFlow.ExecuteRequest): Promise<IntentFlow.ExecuteResponse> => { // Extract command(s) and device target(s) from request const command = request.inputs[0].payload.commands[0]; const execution = command.execution[0]; const response = new Execute.Response.Builder() .setRequestId(request.requestId); const result = command.devices.map((device) => { // Target id of the device provided in the SYNC response const deviceId = device.id; // Metadata for the device provided in the SYNC response // Use customData to provide additional required execution parameters const customData: any = device.customData; // Convert execution command into payload for local device let devicePayload: string; // ... // Construct a local device command over TCP const deviceCommand = new DataFlow.TcpRequestData(); deviceCommand.requestId = request.requestId; deviceCommand.deviceId = deviceId; deviceCommand.data = devicePayload; deviceCommand.port = customData.port; deviceCommand.operation = Constants.TcpOperation.WRITE; // Send command to the local device return localHomeApp.getDeviceManager() .send(deviceCommand) .then((result) => { response.setSuccessState(result.deviceId, state); }) .catch((err: IntentFlow.HandlerError) => { err.errorCode = err.errorCode || IntentFlow.ErrorCode.INVALID_REQUEST; response.setErrorState(device.id, err.errorCode); }); }); // Respond once all commands complete return Promise.all(result) .then(() => response.build()); };
Triển khai trình xử lý QUERY
Trình xử lý QUERY
trong ứng dụng sẽ xử lý yêu cầu của người dùng và sử dụng Local Home SDK để báo cáo trạng thái của các thiết bị thông minh.
Nền tảng Local Home truyền tải trọng yêu cầu tương tự sang hàm của trình xử lý "QUERY" như đối với ý định QUERY
đến phương thức thực hiện trên đám mây của bạn. Tương tự, trình xử lý QUERY
sẽ trả về dữ liệu ở cùng định dạng như khi xử lý ý định QUERY
.
Gửi lệnh đến các thiết bị ở sau một thiết bị trung tâm
Để điều khiển các thiết bị cuối sau một trung tâm, bạn có thể cần cung cấp thêm thông tin về tải trọng lệnh dành riêng cho giao thức được gửi tới trung tâm đó để trung tâm xác định được lệnh đó nhắm đến thiết bị nào. Trong một số trường hợp, bạn có thể suy ra trực tiếp điều này từ giá trị device.id
. Tuy nhiên, nếu không phải như vậy, bạn nên đưa dữ liệu bổ sung này vào trường customData
.
Nếu bạn đã tạo ứng dụng bằng TypeScript, hãy nhớ biên dịch ứng dụng thành JavaScript. Bạn có thể sử dụng hệ thống mô-đun mà bạn chọn để viết mã. Đảm bảo trình duyệt Chrome hỗ trợ mục tiêu của bạn.