Merge branch 'main' into gh-pages

ferramental/README.md

@@ -0,0 +1,11 @@
+# Ferramental   
+
+Além do código do NAO, nosso repositorio contém um ferramental para facilitar o desenvolvimento, manutenção do e testes do código. Estas são algumas das ferramentas que utilizamos:   
+
+- [Pepsi](./pepsi.md): Multi-ferramenta para automatizar tasks repetitivas, como compilação e deploy
+- [Twix](./twix.md): Ferramenta de Debugging para visualizar dados ao vivo do NAO ou Webots
+- [Recording & Replay](./recording.md): Ferramenta para análise de dados de jogo post-mortem
+- [Behaviour Simulator](./behaviour-sim.md): Ferramenta para simular e debugar comportamentos do NAO
+- [Aliveness](./aliveness.md): Ferramenta para status dos NAOs
+
+**No futuro planejamos renomear as ferramentas para dar um toque mais latino-brasileiro**

ferramental/aliveness.md

@@ -0,0 +1,40 @@
+# Aliveness
+É um sistema para buscar informações de status dos NAOs na rede. Ele consiste de duas partes: O service rodando no NAO e o client rodando no computador.
+
+## Informações Disponíveis via Aliveness
+As seguintes informações estão disponíveis via Aliveness:
+- Hostname
+- Versão atual do HULKs-OS
+- Estados dos serviços do sistema: HAL (Hardware Abstraction Layer), HuLA, HULK e LoLA
+- Estado da carga da bateria e corrente
+- ID da cabeça
+- ID do corpo
+- Nome na rede Wireless
+- Temperatura de juntas
+- Nome da interface da qual o beacon é recebido (atualmente sempre *enp4s0*)
+
+## Serviço de Aliveness
+O serviço de Aliveness é compilado junto com a imagem do HULKs-OS e é incluso nele. É iniciado com a primeira conexão com a rede via Ethernete escuta todas as mensagens enviadas ao endereço de multicast `224.0.0.42` assim como o próprio endereço de IP.
+
+Quando recebe um pacote UDP com o conteúdo `BEACON`, ele responde com as informações a cima. O pacote de resposta é um JSON com as informações.
+
+## Client de Aliveness
+O [Pepsi](./pepsi.md) possui um client de aliveness completo com diferentes níveis de verbosidade e opções de exportação.
+
+Exemplo de uso:
+```bash
+    ./pepsi aliveness
+    ./pepsi aliveness 27 32
+    ./pepsi aliveness --json
+    ./pepsi aliveness --timeout 500 -v
+```
+
+Quando executando qualquer um dos subcomandos no pepsi, ele irá mandar a mensagem de beacon citada anteriomente para o endereço de multicast ou aos endereços de IP dos NAOs. Então ele coleta todos as respostas dentro do timeout e filtros de acordo com o nível de verbosidade escolhido.
+
+## Possíveis problemas com Firewall
+Quando não há endereço do NAO especificado, o beacon é mandado via multicast e as respostas são recebidas via unicast. Como as respostas são de diferentes IPs, o firewall pode bloquear as respostas (confunde com um ataque de DDOS).
+
+Nesse caso, é possível abrir uma permissão no firewall, como exemplo temos o ufw, que é o firewall mais comum em sistemas unix:
+```bash
+    ufw allow proto udp from 10.1.24.0/24
+```

ferramental/behaviour-sim.md

@@ -0,0 +1,2 @@
+# Behaviour Simulation
+**TODO**

ferramental/pepsi.md

@@ -0,0 +1,63 @@
+# Pepsi
+Pepsi é uma multiferramenta utilizada pra tudo que está no contexto do código para o NAO. Ela pode ser usada para compilar, modificar parâmetros, fazer deploy no robô, abrir um shell remoto com os jogadores, entre outras coisas.
+
+Essa página é um resumo das funcionalidades do `pepsi`. Para instruções detalhadas utilize o comando `pepsi --help` ou `pepsi <subcomando> --help`.
+
+## Webots workflow
+É bem tranquilo. Abra o Webots, carregue o arquivo de mundo `webots/worlds/penalized_extern.wbt` e execute:
+
+```bash
+    ./pepsi run
+```
+Ele irá compilar (se necessário) e repois rodar o binário do webots. A simulação é pausada automaticamente até que o binário inicie.
+
+## NAO workflow
+```bash
+    ./pepsi uplodad <número / IP>
+```
+Esse comando faz o seguinte:
+- Checa se a toolchain está instalado, faz download e instala se for necessário
+- Compila o código para o target NAO (`pepsi build --target nao`)
+- Faz upload do binário, parâmetros de configuração, arquivo de motion, redes neurais, etc. para o robô (deploy)
+- Reinicia o serviço HULKs nos NAOs
+
+## Interação com os NAOs
+NAOs podem ser identificados tanto por IP quanto por número, números são convertidos por IP assim:
+- `{número}` -> `10.1.24.{número}`
+- `{número}w` -> `10.0.24.{número}`
+Muitos subcomandos podem agir em múltiplos NAOs concorrentemente.
+
+`upload` compila o código e faz o deploy de todos os arquivos binários e de configuração para um ou mais robôs.
+
+`wireless`, `reboot`, `poweroff` e `hulk` interagem diretamente com o robô. Enquanto `communication` e `playernumber` só alteram parâmetros de configuração locais.
+
+`pregame` combina desativação das comunicações (para evitar a emissão de mensagens ilegais), atribuição dos números dos jogadores, configuração das redes de wifi, upload e reinicialização do *HULK service*.
+
+`logs` e/ou `postgame` podem ser usados no pós-jogo para coletar logs e reiniciar o serviço HULK.
+
+`gammaray` é utilizado para fazer o flash da imagem do HULKs-OS para um ou mais robôs.
+
+## Opções de build
+Para subcomandos que compilam binários, é possível especificar o alvo e perfil de build. Incluindo `build`, `run`, `check` e `clippy`.
+
+## Aliveness
+Utilizando o subcomando `aliveness`, a pepsi pode recolher informações dos NAOs conectados via ethernet. Por padrão, somente informações irregulares como sistemas inativos, versões desatualizadas do HULKs-OS e nivel de carga de bateria abaixo de 95% são informados. Usando as flags `-v` / `--verbose` ou `-j` / `--json` é possível obter informações mais detalhadas em formato legível para humanos ou computadores.
+
+Também é possível configurar timeouts via `t` / `--timeout` (padrão de 200ms) e especificar endereços (número ou IPs) para verificar robõs específicos.
+
+Para mais informações, utilize leia esse [documento](./aliveness.md).
+
+## Shell Completion
+Shell completions são configurações do seu ambiente de shell para que ele complete comandos automaticamente. Para habilitar o shell completion para o `pepsi`, execute o seguinte comando:
+
+Exemplo para zshell
+```bash
+    ./pepsi completions zsh > _pepsi 
+```
+Consulte a documentação do seu ambiente de shell caso use outro (fish, tmux, etc).
+
+Para incluir sugestões dinânmicas é necessário adicionar ao *PATH*, para isso utilize este comando:   
+```bash
+    cargo install --path tools/pepsi
+``` 
+e adicionar `~/.cargo/bin` ao *PATH*.

ferramental/recording.md

@@ -0,0 +1,24 @@
+# Recording and Replay
+A framework suporta gravação de dados e o replay deles depois de uma partida para melhor análise. Para cada instância do cycler, somente os inputs e estados dos nós no inicio do ciclo são gravados. Durante o replay, esses estados e inputs são usados para recalcular todos os outputs. Um servidor de comunicação durante o replay pode ser usado para investigar os dados gravados via [Twix](./twix.md).
+
+## Gravação
+- Upload manual para o robô
+    - Use `./pepsi recording ...` para habilitar a gravação em diferentes taxas
+        - Os parâmetros padrão são encontrados em `etc/parameters/framework.json`
+    - Use `./pepsi upload ...` para fazer o upload normalmente
+- Pregame
+    - Use `./pepsi pregame --recording-intervals ... ...` para permitir a gravação em diferentes taxas em um passo
+        - Isso vai setar os parâmetros de gravação para os padrões do `etc/parameters/framework.json`
+
+Seja cauteloso habilitando os cyclers de visão, pois isso resulta em muitos dados sendo gravados. Cyclers de Top e Bottom podem ocupar todo o disco em aproximadamente 10 minutos.
+
+Dados são gravados somente durante `PrimaryState::Ready`, `PrimaryState::Set` e `PrimaryState::Play`.
+
+## Replayer
+Assumindo que você já gravou alguns dados em um robô, é possivel utilizar o *replayer* para revisitar dados gravados.
+- Faça download dos logs em um diretório `logs` dentro do repositório via `./pepsi postgame ... meu_replay_gamer ...`
+- O diretório `meu_replay_gamer` agora contém diretórios com logs de cada robô. Cada diretório de robô contém um diretório com dados de replay de uma execução do binário `hulk`. Todos os arquivos de instâncias de cyclers precisam estar presentes, independente de se estão ativos ou não durante a gravação (neste caso estarão vazios)
+- Inicie a ferramenta de replay apontando pro diretório do log que você quer revisitar: `./pepsi run --target replayer --meu_replay_gamer/robot1/10.1.24.42/123321`
+- Conecte seu Twix ao `localhost` e abra os painéis
+- Mova o slider para fazer os dados disponíveis para o Twix *Dica: Clique na caixa de texto e use as setas do teclado para "animar"*
+- Tá pronto o sorvetinho

ferramental/twix.md

@@ -0,0 +1,2 @@
+# Twix
+**TODO**