Os desenvolvedores de apps iOS podem usar as APIs Home para gerenciar um roteador de borda Thread.
O GoogleBorderRouterDevice é implementado usando dois traços principais do dispositivo:
ThreadNetworkCapabilitiesTrait,
que fornece atributos somente leitura para inspecionar recursos do roteador de borda, e
ThreadNetworkManagementTrait,
que processa comandos de ciclo de vida da rede e compartilhamento de credenciais
usando uma chave pré-compartilhada efêmera para o comissário (ePSKc). As políticas de acesso à Internet no nível da estrutura são gerenciadas usando a característica ThreadNetworkSettingsTrait.
Sempre verifique se um dispositivo é compatível com atributos e comandos antes de usar qualquer recurso ou tentar atualizar atributos. Consulte Controlar dispositivos no iOS para mais informações.
| Tipo de dispositivo das APIs do Google Home | Características | App de exemplo do Swift | Caso de uso |
|---|---|---|---|
|
Roteador de borda
|
Traços obrigatórios google ThreadNetworkCapabilitiesTrait google ThreadNetworkManagementTrait |
Roteador de borda |
Receber informações básicas sobre um dispositivo
O traço BasicInformation
inclui informações como nome do fornecedor, ID do fornecedor, ID do produto,
nome do produto (inclui informações do modelo) e versão do software de um dispositivo:
let vendorName = basicInfoTrait.attributes.vendorName! let vendorID = basicInfoTrait.attributes.vendorID! let productID = basicInfoTrait.attributes.productID! let productName = basicInfoTrait.attributes.productName! let softwareVersion = basicInfoTrait.attributes.softwareVersion!
Inspecionar os recursos do roteador de borda
É possível examinar os recursos somente leitura de um roteador de borda (como suporte a ePSKc e configuração de acesso à Internet) usando a característica ThreadNetworkCapabilitiesTrait.
func checkBorderRouterCapabilities(device: HomeDevice) async {
// Filter for GoogleBorderRouterDevice device type
guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self) else {
print("Device is not a Google border router.")
return
}
// Retrieve the ThreadNetworkCapabilitiesTrait
guard let capabilitiesTrait = gtbrDevice.traits(Google.ThreadNetworkCapabilitiesTrait.self) else {
print("ThreadNetworkCapabilitiesTrait not found on device.")
return
}
do {
let isEpskcSupported = try await capabilitiesTrait.epskcSupported.read()
let internetAccessOption = try await capabilitiesTrait.internetAccessOption.read()
let isIasSupported = internetAccessOption != .none
print("ePSKc Supported: \(isEpskcSupported)")
print("Internet Access Setting Supported: \(isIasSupported)")
} catch {
print("Failed to read capabilities: \(error)")
}
}
Gerenciar o compartilhamento de credenciais do Thread (ePSKc)
O compartilhamento de credenciais do Thread é feito usando uma chave pré-compartilhada efêmera para o comissário (ePSKc). O modo ePSKc gera uma senha temporária e segura que dispositivos externos ou comissários podem usar para obter com segurança o conjunto de dados da rede Thread.
Ativar o modo ePSKc
func startEpskcSession(device: HomeDevice, durationSeconds: Int16) async -> Google.ThreadNetworkManagementTrait.ActivateEpskcModeResponse? {
guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
print("ThreadNetworkManagementTrait not found.")
return nil
}
do {
var request = Google.ThreadNetworkManagementTrait.ActivateEpskcModeRequest()
request.requestedDurationSeconds = durationSeconds
let response = try await mgmtTrait.activateEpskcMode(request)
print("ePSKc Session Activated!")
print("Status: \(response.status)")
print("Ephemeral PSKc: \(response.epskc)")
print("Valid Duration (s): \(response.validDurationSeconds)")
return response
} catch {
print("Failed to activate ePSKc mode: \(error)")
return nil
}
}
Desativar o modo ePSKc
func stopEpskcSession(device: HomeDevice) async {
guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
return
}
do {
try await mgmtTrait.deactivateEpskcMode(Google.ThreadNetworkManagementTrait.DeactivateEpskcModeRequest())
print("ePSKc mode deactivated.")
} catch {
print("Failed to deactivate ePSKc mode: \(error)")
}
}
Observar eventos de desativação de ePSKc
Os roteadores de borda do Thread emitem eventos quando uma sessão ePSKc termina (por exemplo, porque a chave foi usada, a sessão expirou ou foi cancelada manualmente).
func observeEpskcEvents(device: HomeDevice) async {
guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
return
}
do {
for try await event in mgmtTrait.epskcModeDeactivatedEvent.stream() {
print("ePSKc Session Ended. Reason: \(event.reason)")
switch event.reason {
case .keyUsed:
print("Key was successfully used to commission a device.")
case .expired:
print("Session timed out before the key was used.")
case .cancelled:
print("Session was manually cancelled.")
@unknown default:
print("Unknown deactivation reason.")
}
}
} catch {
print("Error streaming ePSKc events: \(error)")
}
}
Gerenciar a associação à rede Thread
Você pode comandar um roteador de borda Thread para entrar em uma nova rede Thread fornecendo os TLVs do conjunto de dados operacionais ativos ou comandar que ele saia da rede atual.
func joinNetwork(device: HomeDevice, datasetTlvs: Data) async {
guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
return
}
do {
var request = Google.ThreadNetworkManagementTrait.JoinNetworkRequest()
request.operationalDatasetTlvs = datasetTlvs
let response = try await mgmtTrait.joinNetwork(request)
print("Join network command sent. Status: \(response.status)")
} catch {
print("Join network failed: \(error)")
}
}
func leaveNetwork(device: HomeDevice) async {
guard let gtbrDevice = device.type(Google.GoogleBorderRouterDevice.self),
let mgmtTrait = gtbrDevice.traits(Google.ThreadNetworkManagementTrait.self) else {
return
}
do {
try await mgmtTrait.leaveNetwork(Google.ThreadNetworkManagementTrait.LeaveNetworkRequest())
print("Leave network command sent successfully.")
} catch {
print("Leave network failed: \(error)")
}
}
Configurar o acesso à Internet no nível da estrutura
O traço ThreadNetworkSettings é atualizável e anexado a um Structure (que representa uma casa ou um edifício). Ele permite que os desenvolvedores configurem
a política de acesso à Internet em toda a estrutura para roteadores de borda do Thread.
func updateStructureInternetAccess(structure: Structure, enableInternetAccess: Bool) async {
guard let settingsTrait = structure.traits(Google.ThreadNetworkSettingsTrait.self) else {
print("ThreadNetworkSettingsTrait not found on structure.")
return
}
let option: Google.ThreadNetworkSettingsTrait.InternetAccessOption = enableInternetAccess ? .internetAccessOptionAll : .internetAccessOptionNone
do {
try await settingsTrait.update { mutator in
mutator.internetAccessOption = option
}
print("Successfully updated Thread internet access policy.")
} catch {
print("Failed to update Thread internet access policy: \(error)")
}
}