Interações com a Alexa

Introdução

Nesta seção do documento, apresentamos as interações entre o sistema embarcado e a Alexa. A Alexa é uma assistente virtual desenvolvida pela Amazon que permite a interação por voz com dispositivos inteligentes.

A integração com a Alexa permite que o usuário acesse informações sobre a cadeira de rodas motorizada, receba alertas e notificações, e realize ações específicas por meio de comandos de voz. Ao receber uma notificação, a Alexa acende uma luz amarela, para indicar que há uma notificação para o usuário.

Para iniciar qualquer interação com a Alexa do módulo "Assistente Cadeira" é necessário iniciar a alexa com a seguinte interação, apresentada na tabela 1.

Tabela 1: Iniciar interação com a Alexa.

Comando de Voz	Ação	Resposta
"Alexa, abrir assistente cadeira"	Alexa ativa o assistente da cadeira	"Bem-vindo! O que você gostaria de fazer?"

Fonte: Thiago Freitas, Caio Berg

Fluxos Certos (Entrada Esperada)

A tabela 2 apresenta todas as frases para ativação das interações com a Alexa e a respostas em caso de sucesso.

Tabela 2: Outras interações com a Alexa.

Intent	Samples (Exemplos de Frases)	Retorno / Resposta Esperada
GenerateReportIntent	- “Eu quero um relatório dos últimos {dias} dias” - “Gere um relatório para os últimos {dias} dias” - "Relatório dos últimos {dias} dias" - "Me envie um relatório de {dias} dias"	Tenta obter o e-mail do usuário (se autorizado) e envia relatório via API, ex.: “O relatório dos últimos 7 dias foi enviado para o seu e-mail.”
GenerateReportWeekIntent	- “Eu quero um relatório de uma semana” - “Eu quero um relatório semanal”	Mesmo comportamento de GenerateReportIntent, porém com {dias} = 7.
GenerateReportMonthIntent	- “Eu quero um relatório mensal”	Mesmo comportamento de GenerateReportIntent, porém com {dias} = 30.
GetBatteryAutonomyIntent	- “Qual é a autonomia da bateria” - “Quanto tempo dura a bateria”	Retorna a autonomia estimada, ex.: “A bateria dura em média 8 horas.”
CheckAverageTimeBatteryCriticalIntent	- “Quando a bateria atinge trinta por cento” - “Qual o horário médio para a bateria atingir trinta por cento” - "Me fale o horario padrao que a bateria chega em trinta por cento"	Retorna o horário médio (ex.: “A bateria normalmente atinge 30% por volta das 14h30.”).
CheckFrequencyLowBatteryIntent	- “Quantas vezes a bateria da cadeira ficou abaixo do nível crítico” - “Quanto tempo a bateria da cadeira ficou em nível baixo”	Retorna quantidade de vezes e total de horas em nível crítico, ex.: “A bateria ficou em nível crítico 3 vezes, somando 2 horas e 30 minutos.”
GetMostCommonEmergencyTimeIntent	- “Qual é o horário mais comum de emergências” - “Em que horário as emergências ocorrem mais”	Indica o horário com maior incidência de emergências, ex.: “O horário mais comum de emergências é 14h.”
GetLastBatteryIntent	- “Qual é a bateria?” - “Qual é a bateria atual da cadeira?” - “Qual é a bateria atual?”	Retorna o nível de bateria atual, ex.: “O nível da bateria é 75%.”
GetHigherConsumptionIntent	- “Qual foi o maior consumo de bateria entre {inicio} e {fim}” - “Quando foi o pico de consumo entre {inicio} e {fim}” - "Me fale o período de maior consumo entre {inicio} e {fim}"	Retorna dados do maior consumo em um intervalo, ex.: “O maior consumo entre 2023-02-01 e 2023-02-10 foi 45% em uma única sessão.”
GetEmergencyResponseTimeIntent	- “Qual o tempo médio de resposta em caso de emergência” - “Quanto tempo leva para responder uma emergência”	Retorna o tempo médio de resposta, ex.: “O tempo médio de resposta é de 120 segundos.”
AMAZON.CancelIntent / StopIntent	(Padrão da Alexa)	Geralmente finaliza a conversa, ex.: “Tudo bem, até logo!”

Fonte: Thiago Freitas, Caio Berg

Fluxos Inesperados (Entrada Inválida ou Fora de Escopo)

A tabela 3 apresenta os fluxos de erros mapeados pela Alexa.

Tabela 3: Fluxos de erros mapeados.

Situação / Cenário	Exemplo de Fala do Usuário	Retorno / Comportamento
Usuário faz pedido fora do escopo do skill	“Alexa, me ensine a fazer sopa de pedra.”	Caso nenhuma Intent mapeie essa fala, o skill cairá no IntentReflectorHandler (se ativado) ou em outro fallback. A resposta típica: “You just triggered IntentRequest.” ou “Desculpe, não entendi.”
Usuário fornece slot inválido	“Gere um relatório dos últimos 150 dias” (hipoteticamente inválido)	O handler pode falhar ao processar o número (ex.: valor muito grande), a skill responde: “Houve um erro ao gerar o relatório. Por favor, tente novamente.”
Usuário pede relatório sem conceder permissão de e-mail	“Gere um relatório para os últimos 7 dias.”	Como não há consent_token, o skill retorna mensagem pedindo para habilitar permissões, ex.: “Eu preciso de permissão para acessar seu e-mail. Por favor, habilite no aplicativo Alexa.”
Erro de conexão com API externa	(Qualquer intenção que faça request e a API esteja offline)	O skill chama a API e recebe erro de rede. É capturado pelo requests.exceptions.RequestException, retornando algo como: “Houve um problema ao acessar as informações. Tente novamente mais tarde.”
Slot duplicado ou não reconhecido	“Quantas vezes a bateria ficou abaixo de 30% de segunda a sexta”	Se a skill não tratar o slot adequadamente ou se a Alexa não identificar start_date e end_date, pode cair em fallback. Resposta: “Desculpe, não entendi as datas informadas. Tente novamente.”
Usuário fala algo incompleto	“Eu quero um relatório dos últimos” (sem falar quantos dias)	A Alexa pode não preencher o slot dias, então a skill pode precisar de fallback. Pode responder: “Desculpe, eu preciso saber quantos dias para gerar o relatório. Quantos dias você deseja?” (diálogo de slot).

Fonte: Thiago Freitas, Caio Berg

Fluxos Inesperados

A tabela 4 apresetnada os fluxos de erros da interação com a API.

Tabela 4: Fluxos de erros da interação com a API

Handler / Intent	Interpretação do Erro	Mensagem Falada
LaunchRequestHandler (abertura do skill)	Usuário não concedeu permissão para acessar e-mail.	“Eu preciso de permissão para acessar seu e-mail para gerar o relatório. Por favor, habilite as permissões no aplicativo Alexa.”
GenerateReportIntentHandler	Falha ao obter o e-mail (problema de rede/endpoint).	“Houve um problema ao acessar seu e-mail. Por favor, tente novamente mais tarde.”
CheckAverageTimeBatteryCriticalIntentHandler	A cadeira (API) não foi encontrada / comunicação indisponível.	“Não foi possível se comunicar com a cadeira.”
	API retornou erro interno (sem dados).	“Não há informações disponíveis sobre o horário médio.”
	Não há registros para calcular horário médio.	“Nenhum registro encontrado para calcular o horário médio de bateria crítica.”
CheckFrequencyLowBatteryIntentHandler	A cadeira (API) não foi encontrada / comunicação indisponível.	“Não foi possível se comunicar com a cadeira.”
	API retornou erro interno (sem dados).	“Não existem dados para as datas informadas.”
GetBatteryAutonomyIntentHandler	A cadeira (API) não foi encontrada / comunicação indisponível.	“Não foi possivel se comunicar com a cadeira.”
	API retornou erro interno (sem dados).	“Não existe dados para as datas informadas.”
GetEmergencyResponseTimeIntentHandler	A cadeira (API) não foi encontrada / comunicação indisponível.	“Não foi possivel se comunicar com a cadeira.”
	API retornou erro interno (sem dados).	“Não existe dados para as datas informadas.”
GetLastBatteryHandler	A cadeira (API) não foi encontrada / comunicação indisponível.	“Não foi possivel se comunicar com a cadeira.”
	API retornou erro interno (sem dados).	“Não existe dados.”
	Não há informações sobre bateria no retorno da API.	“Não há informações sobre a bateria no momento.”
	Erro de rede geral ao obter dados.	“Houve um erro ao obter as informações da bateria.”
GetMostCommonEmergencyTimeIntentHandler	A cadeira (API) não foi encontrada / comunicação indisponível.	“Não foi possivel se comunicar com a cadeira.”
	API retornou erro interno (sem dados).	“Não existe dados para as datas informadas.”
GetHigherConsumptionIntentHandler	O usuário não informou (ou a Alexa não entendeu) datas válidas.	“Desculpe, não entendi as datas.”
	A cadeira (API) não foi encontrada / comunicação indisponível.	“Não foi possível se comunicar com a cadeira.”
	API retornou erro interno (sem dados).	“Não existe dados para as datas informadas.”
CatchAllExceptionHandler	Erro genérico no skill.	“Sorry, I had trouble doing what you asked. Please try again.”

Fonte: Thiago Freitas, Caio Berg

Tabela de Alertas

A tabela 5 a seguir apresenta os alertas que a Alexa pode emitir para o usuário, informando sobre situações de risco ou emergência. Ao um alerta, a Alexa acende uma luz amarela, para indicar que há uma notificação para o usuário.

Tabela 5: Alertas emitidos pela Alexa.

Comando de Voz	Alerta	Descrição
"Alexa, quais são as notificações"	"O botão de emergência foi ativado na cadeira"	É emitido quando o sistema embarcado detecta que o usuário pressiona o botão de emergência da cadeira.
"Alexa, quais são as notificações"	"A bateria da cadeira está abaixo de 20%, por favor, coloque para carregar"	É emitido quando o sistema embarcado detecta que a bateria está abaixo do nível definido de 20%.

Fonte: Thiago Freitas, Caio Berg

Vídeos de Demonstração

Vídeo 1 - Envio de Relatório

Link para o vídeo 1

Vídeo 2 - Leitura de Alertas

Link para o vídeo 2

Tabela de Versionamento

Versão	Versão	Descrição	Responsável
1.0	20/01/2025	Criação do Documento	Thiago Freitas, Caio Berg e Arthur Gabriel
1.1	18/02/2025	Atualização dos Fluxos	Thiago Freitas, Caio Berg
1.2	18/02/2025	Revisão e correção do documento	Ester Lino