API ubus para o SIMETBox (OpenWRT)#

Nota

Seção àqueles que buscam adicionar informações de estados e comandos do motor de medição SIMET em uma interface de gerência própria (por exemplo, web).

O empacotamento openwrt padrão (simetbox-openwrt-feed/*) contém um pacote simetbox-openwrt-luci que estende a interface web LuCI do OpenWRT para interagir com o motor de medição SIMET.

O motor de medição SIMET disponibiliza uma extensão da API ubus do OpenWRT através do mecanismo de rpcd, disponibilizando acesso a diversas informações e comandos do motor de medição.

Esta API é utilizada, por exemplo, pelo pacote simetbox-openwrt-luci, que estende a interface Web LuCI do OpenWRT com telas referentes às medições SIMET e estado do motor de medição SIMET.

O uso do ubus via JSON-RPC tem vários quirks, e seu uso nos modos CLI (utilitário ubus) e via sockets está fora do escopo deste documento. O OpenWRT e o LuCI disponibilizam APIs JavaScript e Lua para acessar o ubus.

Atenção

A autenticação DEVE ser realizada para acessar a API simet-ma.

Para a CLI, são instaladas ACLs pelo pacote simetbox-openwrt-simet-ma que permitem acesso aos usuários root e nicbr-simet. Para acesso via JSON-RPC, o LuCI instala as ACLs necessárias, e DEVE-SE criar uma sessão ubus autenticada para conseguir chamar os diversos métodos / comandos das APIs abaixo.

OpenWRT UBUS: session#

API do OpenWRT utilizada para controle de acesso ao ubus via JSON-RPC. Nativa do OpenWRT e implementada pelo subsistema rpcd. A descrição do wiki do OpenWRT da maiores informações de como utilizar essa API.

Notas:

Para acessar as APIs simetbox e simet_ma, DEVE-SE usar os métodos “login”, “destroy”, “access”. Os outros não estão liberados nas ACLs.
Métodos “get” e “set” armazenam dados em memória dentro da sessão de login (serão perdidos no logout, inclusive devido a timeout, bem como se houver restart do rpcd ou reboot do equipamento). São visíveis apenas para aquela sessão.
login com senha incorreta retorna status UBUS_STATUS_PERMISSION_DENIED (status 6).

OpenWRT UBUS: códigos de status#

Estes são os status retornados por ubus session e ubus uci, com explicações.

Valor	Nome	Descrição/observação
0	UBUS_STATUS_OK	Esse status não significa que o método executou alguma função. Por exemplo “ubus uci commit” sem nenhuma alteração retorna OK (em lugar de retornar NO_DATA)
1	UBUS_STATUS_INVALID_COMMAND
2	UBUS_STATUS_INVALID_ARGUMENT	Refere-se aos “params” da JSON-RPC, específico para cada método. Tipo JSON dos argumentos errado, ou sintaticamente correto, mas semanticamente inválido, ou argumentos faltando.
3	UBUS_STATUS_METHOD_NOT_FOUND
4	UBUS_STATUS_NOT_FOUND	Exemplo: get em algo que não existe
5	UBUS_STATUS_NO_DATA	Depende do método. Para módulos baseados em plugin rpcd (que é o caso do “simet_ma”) pode ser também timeout: o plugin demorou demais para responder com resultados.
6	UBUS_STATUS_PERMISSION_DENIED	Acesso negado ao recurso
7	UBUS_STATUS_TIMEOUT	Timeout na camada UBUS, ou dentro do método
8	UBUS_STATUS_NOT_SUPPORTED
9	UBUS_STATUS_UNKNOWN_ERROR
10	UBUS_STATUS_CONNECTION_FAILED

OpenWRT (SIMETBox): Motor de Medição SIMET-MA#

API utilizada para comunicar-se com o motor de medição SIMET. Implementado através de um plugin do subsistema rpcd do OpenWRT. Exportada através do caminho/namespace ubus "simet_ma".

ubus call simet_ma <método> <parâmetros>

Os métodos do namespace "simet_ma" estão descritos a seguir.

simet_engine_status#

Retorna status e configuração do motor de medição. Se retornar “enabled”:false, o motor de medição está desabilitado, e não irá realizar medições.

Retorna a identificação do motor de medição (versão, agent-id), e no caso de SIMETBox, retorna o MAC principal (simetbox-id).

Na interface com o usuário, o agent-id é “Id. do agente SIMET” ou “Identificação do agente SIMET”. O MAC é “Id. da SIMETBox” ou “Identificação da SIMETBox”.

saída

simet_engine_status

{
    "enabled": true,
    "version": "simet-ma/v0.17.1",
    "main_measurement_running": "true",
    "local_measurement_config": {
        "basic": {
            "period_minutes": "720"
        },
        "gw_ping": {
            "period_minutes": "180"
        }
    },
    "agent-id": "<uuid>",
    "simetbox-id": "<mac, 0-9a-f>"
}

simet_pairing_status#

Retorna status da associação do medidor com o portal SIMET e, caso disponíveis, metadados sobre a associação do medidor (pareamento).

saída

Nome do campo	Descrição
status	0 : informação no objeto “result"; 4 : agent-registry ainda contactada neste boot, ou medidor não registrado, ou erro nas informações em cache local
result	objeto contendo o resultado abaixo
error	descrição textual do problema

saída: objeto result

Nome do campo	Descrição
paired	true: pareado a um usuário/entidade no portal simet false: não pareado.
name	Nome do participante, se disponível. Projeto Escola Conectada: nome da escola. Projeto Saúde Conectada: nome da entidade de Saúde.
short_name	Identificador do participante, se disponível. Projeto Escola Conectada: INEP#####. Projeto Saúde Conectada: CNES#####. Provedores: ASN#####.

results_credentials#

Retorna as credenciais necessárias para acessar o backend de resultados das medições desse medidor (via backend dashboard.simet.nic.br): agent-id e token para visualização/recuperação dos resultados das medições.

Retorna também a URL já montada para o dashboard com os parâmetros necessários.

Se o medidor não estiver registrado, retorna um erro da camada ubus rpcd.

saída:

Nome do campo	Descrição
agent-id	identificação do agente (agent-id).
results_token	Token (opaco) para acesso às APIs de recuperação de resultados de medições desse medidor. Em geral utilizada em conjunto com o agent-id. Atenção: “quoting” JSON precisa ser processado.
results_interactive_url	URL para acesso à página interativa de relatórios de medições deste medidor. Contém os parâmetros necessários para acesso (token, etc). Atenção: “quoting” JSON precisa ser processado. O resultado pode precisar passar por URL-encoding para ser incluído como destino de link em uma página web.

renew_registration#

Renova o registro do medidor e substitui o token de acesso aos resultados de medições que é retornado pelo método results_credentials.

refresh_schedule#

Contacta o LMAP controller e pede um novo schedule. Caso não receba ou receba um schedule inválido, atualiza o schedule local utilizando as configurações de frequência de medição locais do motor de medição.

DEVE-SE chamar esse método caso as configurações sejam alteradas diretamente (uci sections do tipo “simet_measurement”, do config simet_ma).

wan_status#

Retorna o status das interfaces wan e wan6 do OpenWRT e faz um teste de ping no default gateway delas. Sabe detectar wwan (wan via 3g/4g), etc.

Use para saber se a SIMETBox está “online”.

start_measurement_run#

Inicia um ciclo de medição “básico” do motor de medição, caso já não esteja medindo.

É possível verificar se o medidor já está medindo ou não através da saída do método simet_engine_status.

geolocate#

Retorna a geolocalização da SIMETBox. Como geolocalizar na SIMETBox consome recursos potencialmente pagos, ela evita geolocalizar frequentemente (tipicamente no boot e uma vez a cada vários dias).

Se não houver geolocalização disponível, retorna um objeto vazio.

parâmetros#

nome do parâmetro	Descrição
force	true: não utiliza resultados mais velhos que 1 hora. false (padrão): segue a política padrão de renovação de geolocalização
fast	true (padrão): retorna apenas resultado armazenado, sem tentar uma geolocalização imediata. false: permite que o medidor geolocalize se o resultado armazenado for muito antigo ou não existir. Geolocalizar pode demorar vários segundos, inclusive sofrer timeout da camada UBUS.

saída

Nome do campo	Descrição
timestamp	inteiro em formato string UNIX time (segundos desde 01-01-1970) de quando realizou a geolocalização.
latitude	ponto flutuante em formato string graus decimais, positivo: norte, negativo: sul
longitude	ponto flutuante em formato string graus decimais, positivo: leste, negativo: oeste