Referência

WiFi simulado

A rede à qual um sketch se conecta: o que é fiel, o que é criação do Mokxi e o que não existe de jeito nenhum.

O contrato da rede do Mokxi: o que um sketch pode fazer, o que é fiel e o que não existe de jeito nenhum. O contrato de cada placa tem a tabela de registradores (docs/esp32c3.md 3.8, docs/esp32c6.md 3.8, docs/esp32.md 3.8, docs/esp32s3.md 3.10, docs/esp8266.md 3.9, docs/picow.md 3.8). crates/net é o modelo; este arquivo prevalece sobre todos eles.

A frase que resume

The radio is simulated. There is no 802.11, there is no real internet, and the WiFi runtime is Mokxi's own. Nothing in Mokxi transmits, receives, scans, associates, encrypts or opens a socket to the outside (boards of one project can open TCP connections to each other, below). A password is compared as a string. The only names that resolve are four made-up ones under .mokxi and the board's own address, and nothing a sketch does can reach the network the browser is on. Every page that mentions WiFi says this, in the properties panel, in the Web and Cloud panels' first line, in the help article, on the board page, and in the examples themselves.

A única exceção é opcional e fica desativada a cada carregamento de página: o modo internet real (abaixo), em que a página, não o motor, envia as requisições de um sketch por nomes fora de .mokxi através do nosso gateway, para quem está conectado (uma pequena cota no Grátis, mais com o Pro). Com ele desligado, que é o padrão e o único modo sem login, tudo que foi dito acima vale exatamente. Uma placa que se conecta a Wokwi-GUEST o ativa quando uma execução começa.

Por que um mailbox, e por que isso é honesto

Num ESP32 de verdade, o hardware de WiFi não é um conjunto de registradores documentados. É um blob binário fechado com uma interface de comandos, e cada linha do WiFi.h do Arduino acaba do outro lado de um deles. Então o modelo é um mailbox: um registrador de comando, um registrador de status, um buffer em anel em cada direção e um bit de interrupção, em 0x6FFF_E000 no ESP32-C3: um bloco próprio do Mokxi, não do chip, acima de todos os periféricos reais, num endereço que um C3 real deixa não mapeado, para que uma imagem que o use falhe no silício em vez de ler o registrário de outro.

Essa é toda a mentira, e ela tem a mesma forma que a verdade. O que ela não é: um MAC 802.11 falso. Não há quadros, canais, taxas nem intervalo de beacon em nenhum lugar deste código, porque um modelo disso seria uma invenção sem nada contra o que verificá-lo.

As seis placas, e o único número que difere

O bloco é independente da placa. crates/net não sabe nada sobre nenhuma placa; o SoC escolhe um número, o endereço base, e repassa os acessos de palavra. Seis placas o fazem, e são exatamente as seis que têm rádio no hardware real:

placa o mailbox está em o que a peça real tem aí
ESP32-C3 DevKitM-1 0x6FFF_E000 nada: seus periféricos param bem antes
ESP32-C6-DevKitC-1 0x6FFF_E000 nada: o mesmo lugar também está vazio neste componente
ESP32 DevKit (WROOM-32) 0x3FEF_E000 um espaço reservado entre as janelas de memória externa e a janela de periféricos
ESP32-S3-DevKitC-1 0x6FFF_E000 nada: os periféricos terminam em 0x600D_0FFF e a memória RTC FAST em 0x600F_FFFF
ESP8266 NodeMCU 0x6FFF_E000 nada: seus blocos reais estão todos nos primeiros kilobytes daquela janela
Raspberry Pi Pico W 0x4FFF_E000 nada: acima de todos os periféricos APB, abaixo do AHB-Lite

Num Pico W a costura tem a mesma forma por um motivo diferente: a parte sem fio é uma CYW43439 do outro lado de um link SPI de três pinos dirigido por um blob binário fechado, que não é mais um conjunto de registradores documentados no RP2040 do que o rádio de um ESP32 é no próprio die dele. Uma interface de comandos é o que realmente existe ali. (Os firmwares oficiais de MicroPython e CircuitPython para o Pico W dirigem o chip eles mesmos, e para eles ele é modelado a partir de seus pinos, com o mailbox não mapeado: docs/cyw43.md.)

firmware/include/mokxi_net.h é a única definição de cada registrador, bit e código de comando; o cabeçalho de cada placa define o endereço base e o inclui, e firmware/tools/check_registers.py mantém os seis cabeçalhos fiéis às tabelas de seus contratos, endereço base incluído. Um periférico inventado é justamente o que mais precisa das duas metades amarradas uma à outra.

Every other board refuses. A plain Raspberry Pi Pico, the Uno, the Nano, the Mega, the Leonardo, the ATtiny85, the XIAO SAMD21, the Uno R4, the STM32s and the micro:bit have no wireless part on them, so WiFi.h, HTTPClient.h and WebServer.h fail to compile with a sentence pointing here, rather than letting a sketch write to an address its chip does not have. A stub that answered "not connected" would be a lie with a plausible shape; a compile error is not. The Pico and the Pico W therefore carry different program strings (elf32 arm rp2040 and elf32 arm rp2040 picow), as the Uno's and the Nano's do, so the editor offers each board its own examples.

O que um aluno pode fazer

Join the network

O mesmo código em todas as seis placas; o cabeçalho é WiFi.h em todas, porque é assim que a API do Arduino se chama na família ESP32 e no Pico W.

#include <WiFi.h>

WiFi.mode(WIFI_STA);
WiFi.begin("Mokxi-Lab", "breadboard");
while (WiFi.status() != WL_CONNECTED) { Serial.print("."); delay(250); }
Serial.println(WiFi.localIP());

O SSID e a senha são propriedades da placa: clique na placa no editor e defina wifiSsid, wifiPassword e wifiRssi. Todas as seis placas carregam os mesmos três, vindos de crates/parts/src/wifi.rs, com os mesmos padrões e a mesma validação. Sem rádio não há nada para escanear nem nada que carregue as configurações de um componente separado, então o único ponto de acesso que uma placa vê é uma configuração na placa. O painel Cloud edita os mesmos três valores enquanto o sketch roda.

WiFi.status() passa por WL_IDLE_STATUS, depois WL_DISCONNECTED enquanto associa, e então WL_CONNECTED, que é a sequência do próprio Arduino, porque o Arduino não tem WL_CONNECTING e um componente que está associando reporta WL_DISCONNECTED. WiFi.localIP() é 192.168.4.2, gatewayIP() é 192.168.4.1, RSSI() é a propriedade wifiRssi, SSID() é o nome do ponto de acesso e macAddress() é o próprio MAC da placa: a configuração wifiMac, ou, se deixada vazia, um que o motor calcula a partir do id do componente (02:4D:4F: e três bytes), igual em toda execução e diferente para cada placa no canvas, para que o ESP-NOW consiga distingui-las (docs/help/editor/esp-now.md).

Erre a senha e WiFi.status() vira WL_CONNECT_FAILED. Erre o nome e vira WL_NO_SSID_AVAIL. WiFi.disconnect() volta para idle, e o próximo begin() aluga o mesmo endereço de novo.

Buscar algo

#include <HTTPClient.h>
WiFiClient client;
HTTPClient http;
http.begin(client, "http://weather.mokxi/");
int code = http.GET();
String body = http.getString();
http.end();

Existem quatro origens, e nenhuma outra:

nome respostas
http://time.mokxi/ o relógio do kernel como uma string ISO, text/plain
http://weather.mokxi/ JSON com uma temperatura e uma umidade que o painel Cloud define
http://echo.mokxi/ o corpo que você enviou, de volta; também o servidor de eco WebSocket simulado para WebSocketsClient
http://api.mokxi/ o status, o tipo de conteúdo e o corpo da resposta configurados no painel Cloud

http://192.168.4.2/ (e http://board.mokxi/) é o próprio servidor do sketch, o único endereço que um sketch não consegue chamar de forma útil, porque teria que responder a si mesmo; ele recebe um 404 dizendo isso.

Qualquer outro .mokxi nome é um 404. Qualquer coisa que não esteja sob .mokxi não resolve de jeito nenhum: http.GET() retorna HTTPC_ERROR_CONNECTION_REFUSED e HTTPClient::errorToString() devolve a única frase em torno da qual todo este recurso foi construído: sem internet real: apenas nomes sob .mokxi. https:// retorna HTTPC_ERROR_NO_TLS.

Servir algo

#include <WebServer.h>
WebServer server(80);

server.on("/", [](){ server.send(200, "text/html", "<h1>hello</h1>"); });
server.begin();
// in loop():
server.handleClient();

on(path, handler), onNotFound(), send(code, type, body), arg(name), hasArg(), uri(), method() e handleClient(). Sem nenhuma requisição aguardando, handleClient() espera 1 ms, como fazem o do core do ESP32 e o do arduino-pico (o do ESP8266 não), então um loop() que só serve fica ocioso em delay() e roda mais rápido que o tempo real; enableDelay(false) faz ele girar, como lá. Um loop que faz polling de WiFiServer::available() gira no chip real e aqui. Os handlers são o seu código no core da placa, no clock da placa. O painel Web na parte de baixo é o navegador para eles: uma barra de endereço em http://192.168.4.2/, um botão de atualizar e a página renderizada em um quadro isolado com scripts desativados. Links e envios de formulário dentro dele são capturados e roteados de volta para a rede simulada, então "acender o LED a partir de uma página web" funciona de ponta a ponta.

Nada fora da aba do navegador consegue alcançar esse servidor. Não há socket em escuta. O painel Web é o único cliente que existe.

Rodar o próprio ponto de acesso da placa (soft AP)

#include <WiFi.h>
#include <WebServer.h>
WebServer server(80);

WiFi.mode(WIFI_AP);
WiFi.softAP("MyESP", "12345678");      // true: the access point is up
Serial.println(WiFi.softAPIP());       // 192.168.4.1
server.on("/", [](){ server.send(200, "text/html", "<h1>hello from MyESP</h1>"); });
server.begin();
// in loop(): server.handleClient();

The soft AP is simulated the same way the station is: no beacon goes out, nothing associates, and the password is compared as a string. What is there is the board's own network, the Web panel's phone and any other ESP boards in the project that join it (below). When the access point comes up, the phone joins it 1.5 s later (a phone that has the network saved), and the Web panel shows a row under its address bar, Phone joined MyESP as 192.168.4.2, with Leave; left, the row has the password a phone would type (the sketch's, to start with) and Join. A wrong password is refused, wrong password for MyESP; an open network takes any. While the phone is joined:

  • o painel alcança o servidor do sketch no endereço do ponto de acesso (http://192.168.4.1/, ou o que softAPConfig() definiu), e a barra de endereço vai para lá sozinha: aperte Ir. WebServer, um WiFiServer escrito à mão, AsyncWebServer e os servidores do ESP8266 e do Pico W respondem a ele, e server.hostHeader() é o endereço (ou nome) que o painel pediu;
  • WiFi.softAPgetStationNum() (and WiFi.AP.stationCount()) counts the phone, one less once it leaves (boards that joined count too);
  • WiFi.onEvent() recebe os eventos do core na ordem dele: ARDUINO_EVENT_WIFI_AP_START depois de softAP(), depois ARDUINO_EVENT_WIFI_AP_STACONNECTED (o MAC do celular, 02:50:48:4F:4E:45, aid 1) e ARDUINO_EVENT_WIFI_AP_STAIPASSIGNED (192.168.4.2, o endereço logo após o do ponto de acesso, já que o servidor DHCP do ESP-IDF distribui nesta ordem) a cada conexão, ARDUINO_EVENT_WIFI_AP_STADISCONNECTED (motivo 8) a cada desconexão, e ARDUINO_EVENT_WIFI_AP_STOP depois de softAPdisconnect() ou de um modo sem a parte de AP. Como os da estação, eles rodam a partir de delay(), cerca de 100 ms após a mudança, então um laço que consulta softAPgetStationNum() pode ver a contagem primeiro.

O que segue os cores: softAP() recusa um nome vazio e uma senha de um a sete caracteres (ou mais de 63), retorna false e diz o porquê uma vez no monitor serial; softAPIP() é 0.0.0.0 enquanto o ponto de acesso está desligado; softAPConfig() antes ou depois softAP() move ele (e a concessão do celular para o endereço seguinte), e softAPSubnetMask(), softAPBroadcastIP(), softAPNetworkID() e softAPSubnetCIDR() segue; WiFi.getMode() é WIFI_AP depois de softAP() sozinho, WIFI_AP_STA com begin() também. Outras placas no canvas entram nela também. As placas ESP de um projeto compartilham um mesmo ar simulado (o mesmo que o ESP-NOW usa), então uma estação em uma placa entra no soft AP de outra: WiFi.begin("MyESP", "12345678") com o nome e a senha que a outra placa definiu softAP() termina em WL_CONNECTED, com um endereço da sub-rede do ponto de acesso (192.168.4.2, depois .3, na ordem em que pediram), e softAPgetStationNum() conta cada uma. Uma senha errada termina em WL_CONNECT_FAILED; uma estação que pede antes de o ponto de acesso subir continua procurando e entra quando ele sobe. HTTPClient reaches the access point's WebServer at its address (192.168.4.1); an HTTPClient request for any other address on that network, or for a board with no server, is a refused connection (-1). WiFiClient e WiFiServer carry TCP from board to board, stations included (next section). The Web panel's phone still joins by itself and gets its own address, so it counts as one more station. Not simulated: the access point board's own events carrying the joined station's MAC and address (they still carry the phone's). A name that is the board's own wifiSsid setting still joins that built-in network, and sends nothing over the air. WIFI_AP_STA runs both: the station keeps its lease at 192.168.4.2 and the simulated internet (HTTPClient, Blynk, real internet mode), and the panel reaches the board at either address. On the Pico W, o do arduino-pico WiFi.beginAP() é softAP() (WL_CONNECTED quando ativo) e o ponto de acesso fica em 192.168.42.1, or 192.168.4.1 when the station is on too (WIFI_AP_STA), as arduino-pico's beginAP chooses (libraries/WiFi/src/WiFiClass.cpp), unless softAPConfig() tenha definido um; WiFi.localIP() responde aí. Na Uno R4 WiFi, WiFiS3's WiFi.beginAP() retorna WL_AP_LISTENING, WiFi.config(ip) antes de nomear o endereço, e WiFi.status() é WL_AP_CONNECTED while the phone is joined, as its AP_SimpleWebServer example waits for. The ESP8266's ESP8266WiFi o AP em modo soft usa as mesmas chamadas.

Um portal cativo funciona como em um celular. DNSServer (dns.start(53, "*", WiFi.softAPIP())) diz à rede quais nomes o servidor dele responde; enquanto está rodando, o celular resolve todo nome que ele cobre para esse endereço, e quando o celular se conecta, o painel Web abre o portal sozinho, como um celular mostra sua tela de login: ele pede http://connectivitycheck.gstatic.com/generate_204, que o onNotFound() do sketch (ou seu redirecionamento para o próprio endereço) responde. Qualquer nome digitado na barra de endereços também vai para a placa. Não existe pacote DNS, então os nomes resolvem com ou sem loop() chamar processNextRequest(). Os nomes .mokxi ainda chegam aos sites simulados quando nenhum servidor DNS os cobre, o que um celular real na rede da placa não conseguiria fazer.

Under MicroPython (the ESP32, ESP32-S3, ESP32-C3 and ESP32-C6 builds, and the Pico W's) network.WLAN(network.AP_IF) is the same access point, carried the way the station is: the firmware's own lwIP and DHCP server run as built, and the phone is a second IP end in crates/net/src/lan.rs that answers ARP and opens TCP connections to the board's port 80. ap.config(essid=..., password=..., authmode=...) (ssid and key on the Pico W) and ap.active(True) bring it up at 192.168.4.1; ap.status('stations') lists the phone while it is joined; a socket server on port 80 shows in the Web panel and sees the phone at 192.168.4.2. The phone finds the access point's address from what the board sends, so ap.ifconfig() moving it is followed. The station's network is 192.168.4.0/24 too, so to run both under MicroPython give the access point another address with ap.ifconfig(), as a home router at 192.168.4.1 would make you do on a desk.

Boards talking to each other (TCP between boards)

Boards in one project that share a soft AP can open TCP connections to each other, as ESP32s on one access point do. One board runs a WiFiServer, another calls WiFiClient::connect(ip, port) with the address that board holds, and the two exchange bytes both ways until one of them closes. The server can be a station or the access point's own board, and the client can be either too. Two stations reach each other through the access point's board, which passes on what is meant for one of its other stations, as an access point does.

Server station (the second board in the project):

#include <WiFi.h>
WiFiServer server(5000);
void setup() {
  Serial.begin(115200);
  WiFi.begin("MyESP", "12345678");        // the name and password the access point board gave softAP()
  while (WiFi.status() != WL_CONNECTED) delay(100);
  Serial.println(WiFi.localIP());          // for example 192.168.4.2: the client connects here
  server.begin();
}
void loop() {
  WiFiClient client = server.available();
  if (client) {
    while (client.connected()) {
      if (client.available()) {
        String line = client.readStringUntil('\n');
        line.trim();
        Serial.println("got: " + line);
        client.println("echo: " + line);
      }
    }
    client.stop();
  }
}

Client station (the third board):

#include <WiFi.h>
void setup() {
  Serial.begin(115200);
  WiFi.begin("MyESP", "12345678");
  while (WiFi.status() != WL_CONNECTED) delay(100);
  WiFiClient client;
  // Use the address the server station printed. Stations get 192.168.4.2,
  // then .3, in the order they joined.
  if (client.connect(IPAddress(192, 168, 4, 2), 5000)) {
    client.println("hello");
    while (!client.available()) delay(10);
    Serial.println(client.readStringUntil('\n'));   // echo: hello
    client.stop();
  } else {
    Serial.println("connect failed");
  }
}
void loop() {}

What a sketch sees matches the Arduino-ESP32 core:

  • connect() returns 1 when the server accepts. It returns 0 at once when the address is a board with no WiFiServer on that port, and after the core's three seconds (connect(ip, port, timeout) takes another) when nobody holds the address. A name is not looked up: only a dotted address connects.
  • server.available() returns a client for the next waiting connection, or one that is false. client.connected(), available(), read(), peek(), readStringUntil(), readBytes(), print(), println(), write(), remoteIP(), remotePort(), localPort() and stop() work on it.
  • When one end closes, the other reads what was sent before the close, then connected() goes false, as the core's does. A station that leaves its network (WiFi.disconnect()), or that the access point drops, ends its connections the same way.
  • Bytes arrive in order and none are lost while the link holds. A write waits (up to five seconds) while the radio has a great deal queued, as a full send buffer does.
  • The board holds eight sockets. A WiFiClient has no destructor here, so one that goes out of scope without stop() keeps its connection until its other end closes and a new connection needs the slot. Call stop().
  • The same ports serve the Web panel as before: its request reaches server.available() as the bytes of an HTTP request. A raw connection to a port that only an HTTP WebServer serves is refused, as is a station's HTTPClient request to another station's WebServer.

What is not carried: UDP (WiFiUDP still sends nothing, below), a connection to a name, TLS, and TCP to anything outside the project's boards. Two boards that did not join the same soft AP have no way to reach each other.

Veja o que aconteceu

O painel Cloud é a aba de rede: cada requisição que a placa fez e cada requisição que a página fez para a placa, com o método, a URL, o status, os corpos e, quando uma requisição falha, uma linha dizendo por quê. Ele também carrega as três configurações do ponto de acesso e os dois valores de weather.mokxi. E ainda tem um laboratório de API: escolha o status HTTP, o tipo de conteúdo e o corpo da resposta para api.mokxi, e depois veja a próxima requisição trazer exatamente essa resposta de volta. Um professor pode simular sucesso, entrada inválida, dados ausentes e erros de servidor sem chave de API nem dependência fora da aula.

Usar o Blynk

#define BLYNK_TEMPLATE_ID "TMPLxxxxxx"
#define BLYNK_TEMPLATE_NAME "Light Intensity Monitor"
#define BLYNK_PRINT Serial
#include <ESP8266WiFi.h>
#include <BlynkSimpleEsp8266.h>   // BlynkSimpleEsp32.h, or BlynkSimpleWifi.h on a Pico W or UNO R4 WiFi

BlynkTimer timer;
BLYNK_WRITE(V1) { digitalWrite(D1, param.asInt()); }
void sendLight() { Blynk.virtualWrite(V0, analogRead(A0)); }
void setup() {
  Blynk.begin("token", "Mokxi-Lab", "breadboard");
  timer.setInterval(1000L, sendLight);
}
void loop() { Blynk.run(); timer.run(); }

Real Blynk keeps a TCP connection to blynk.cloud, which this network does not have, so the Blynk server is simulated (crates/net/src/blynk.rs), and the library is Mokxi's own (firmware/lib/mokxi_blynk.h, the Blynk IoT library's calls, v1.3). The sketch reaches the server through one mailbox command, BLYNK, answered at once: there is no wire format and no latency to model, because there is no wire. The Cloud panel's Blynk section, drawn once a sketch logs in, is its console: each virtual pin the sketch wrote or has a BLYNK_WRITE for, its value, who wrote it and when, and a box that sends a value to it, as the Blynk app's switch or slider would. Blynk.logEvent's events are listed under it.

O que a biblioteca determina: Blynk.begin() bloqueia até a placa estar na rede e conectada; BLYNK_WRITE roda dentro de Blynk.run(), nunca entre duas linhas de loop(); BLYNK_CONNECTED roda a cada login; Blynk.syncVirtual() e syncAll() devolvem os valores guardados do servidor para dentro de BLYNK_WRITE; uma escrita enquanto a placa está offline é descartada, e um valor enviado do painel enquanto ele está offline é guardado mas não entregue; um float sai com três casas decimais e um double com sete; uma placa que sai da rede perde seu servidor, e Blynk.run() faz login de novo cinco segundos depois de voltar. Os datastreams sobrevivem a um reset da placa, como sobrevivem num servidor real. BlynkTimer é o da biblioteca: dezesseis temporizadores a partir de timer.run(). WidgetLED, WidgetTerminal e WidgetLCD escrevem seus pinos como a biblioteca faz (WidgetLCD.h e os outros cabeçalhos de widget que sketches antigos incluem pelo nome também estão lá); o LCD não é desenhado, seu pino mostra o último clr ou p, x, y, text.

O que não segue: o token, o ID do template e o nome do servidor são mostrados, nunca verificados nem consultados (não há conta Blynk aqui); BLYNK_APP_CONNECTED compila e nunca roda, já que nada abre um app (BLYNK_READ saiu do Blynk 1.4.0, então um sketch que o usa recebe um erro de compilação indicando Blynk.virtualWrite() a partir de um BlynkTimer); Blynk.Edgent, OTA e os cabeçalhos _SSL não estão aqui. Os valores são limitados a 1024 bytes, 64 escritas esperam por uma placa que não está consultando, e o painel guarda os últimos 20 eventos. O tráfego do Blynk não está no log de requisições, que ele encheria.

Usar WebSockets (o servidor de echo)

#include <WiFi.h>
#include <WebSocketsClient.h>   // the WebSockets library, Markus Sattler

WebSocketsClient webSocket;
void webSocketEvent(WStype_t type, uint8_t *payload, size_t length) {
  if (type == WStype_CONNECTED) webSocket.sendTXT("Connected");
  if (type == WStype_TEXT) Serial.printf("[WSc] get text: %s\n", payload);
}
void setup() {
  // join Mokxi-Lab first
  webSocket.begin("echo.mokxi", 80, "/");
  webSocket.onEvent(webSocketEvent);
}
void loop() { webSocket.loop(); }

This is not a WebSocket on a wire. A WebSocket is a TCP connection that outlives its opening HTTP request, and this network has no TCP to a server on the internet. So the library (firmware/lib/WebSocketsClient.h, the calls of 2.6.1) gives echo.mokxi one more job: it is the simulated echo server. The first loop() after begin() makes an HTTP GET to http://echo.mokxi<url>, and its answer raises WStype_CONNECTED. Each sendTXT() is then an HTTP POST of the text to that URL, and what the echo site sends back is handed to the callback from the next loop() as WStype_TEXT, in the order sent; sendBIN() travels as base64 text and comes back as WStype_BIN, decoded; sendPing() comes back as WStype_PONG, so enableHeartbeat() keeps the connection. Every message is a request in the Cloud panel's log, because that is all it is. A send blocks for the request's 60 ms, where upstream's returns once the frame is buffered.

Qualquer outro host, e beginSSL() para qualquer host, nunca conecta e não faz requisição nenhuma: loop() levanta WStype_DISCONNECTED, tenta de novo a cada setReconnectInterval(), e o monitor serial diz uma vez que WebSockets para esse host precisam de uma placa de verdade. O modo internet real não muda isso: o gateway carrega uma requisição HTTP e uma resposta. WebSocketsServer compila e roda, e nenhum cliente nunca conecta a ele, já que o painel Web mostra as páginas com scripts desligados; ele também diz isso uma vez.

Pedir a hora

#include <WiFiUdp.h>
#include <NTPClient.h>
WiFiUDP ntpUDP;
NTPClient timeClient(ntpUDP, "europe.pool.ntp.org", 3600, 60000);
// after WiFi.begin() has connected:
timeClient.begin();
timeClient.update();
Serial.println(timeClient.getFormattedTime());   // "01:00:03"

Esta não é a hora real. NTP é uma troca UDP com um servidor na internet, e esta rede não carrega UDP nenhum e não alcança servidor nenhum; a simulação também não sabe a data de hoje, e inventar uma seria uma mentira que o aluno não poderia conferir. Então o NTP é simulado, do mesmo jeito em toda placa WiFi: configTime() nas placas ESP32 e ESP8266, NTP.begin() na Pico W e o NTPClient (firmware/lib/NTPClient.h, a versão 3.2.1 das arduino-libraries) definem todos o relógio para o da própria simulação: 2026-01-01 00:00:00 UTC (epoch 1767225600) na energização, mais os segundos em que a placa rodou, que é também o que http://time.mokxi/ informa. Cada um avisa isso uma vez no monitor serial. O getEpochTime() do NTPClient é isso, mais o seu offset; update() pergunta quando o intervalo passa e forceUpdate() pergunta na hora, e ambos são respondidos enquanto a placa está na rede e expiram depois de cerca de um segundo quando não está. Nenhum pacote é enviado: o WiFiUDP que ele recebe não é usado.

Usar Ethernet com cabo (ETH.h, as placas ESP32)

#include <ETH.h>
Network.onEvent(onEvent);   // ARDUINO_EVENT_ETH_START, _CONNECTED, _GOT_IP
ETH.begin();                // or the core 2.x / 3.x RMII and W5500 forms

Não há PHY, não há RMII, não há W5500 e não há cabo. ETH.begin() é o NET_CMD_ETH do mailbox (operação 1): a máquina de estados da estação conecta sem SSID e sem senha, WIRED_PS (1,5 s) depois, com o mesmo lease, e tudo o que passa pela estação (HTTP, o servidor do sketch, Blynk, o gateway Real da internet e seus limites) continua igual, sem mudanças. Existe um único link, então WiFi.status() o lê independentemente de como ele surgiu, e WiFi.begin() o devolve ao WiFi. Enquanto o link for o cabeado, os handlers de WiFi.onEvent() e Network.onEvent() recebem os eventos ETH do core, em vez dos da estação. ETH.config() é mantido para localIP() informar; a placa ainda responde ao painel Web em 192.168.4.2. O cabo está sempre conectado.

O que é fiel

  • A API. As chamadas e suas assinaturas são as que um estudante copia de um tutorial de ESP32: WiFi.begin/status/localIP/gatewayIP/RSSI/SSID/ macAddress/disconnect/mode, WiFiClient, HTTPClient::begin/GET/POST/ addHeader/getString/getStream/getSize/end/errorToString, WebServer::on/onNotFound/ begin/handleClient/send/arg/hasArg/uri/method, e rotas com padrões dentro delas: UriBraces("/toggle/{}") com pathArg(0) e UriGlob("/files/*") (uri/UriBraces.h, uri/UriGlob.h; sem UriRegex).
  • Os códigos de status. O wl_status_t é o enum do Arduino, valor por valor. Os códigos negativos do HTTPClient são os do Arduino onde o Mokxi tem a mesma falha (-1 recusado, -4 não conectado, -11 expirado).
  • A faixa de tempos. Uma associação leva entre um e três segundos, e uma senha errada falha depois de cinco. Ambos estão dentro do que um ESP32-C3 real faz numa rede tranquila, e ambos são mantidos nesse intervalo por um teste.
  • A ordem dos estados, que é aquilo contra o qual um laço de conexão é escrito.
  • O custo. Um http.GET() bloqueado realmente custa ao sketch os seus 60 ms de tempo simulado, porque o resto do circuito passa por ele. Um sketch que esquece o handleClient() realmente nunca responde. Um http.setTimeout() mais curto que isso expira (-11), e a requisição abandonada é descartada e registrada quando a próxima começa, como um cliente real fecha a conexão em que parou de esperar; a próxima requisição não é recusada.
  • Cada HTTPClient guarda a sua própria resposta. Dois clientes que cada um GET() antes de qualquer um ler recebem de volta os seus próprios corpos, e getString() duas vezes dá o corpo duas vezes, como o do core do ESP32 dá.

O que não é

  • Sem rádio, e portanto sem 802.11 nenhum. Sem canal, sem scan real, sem beacon, sem quadros de associação, sem WPA2, sem PMK, sem criptografia em lugar nenhum. A senha é uma comparação de strings. O WiFi.scanNetworks() compila e "encontra" o único ponto de acesso que a placa consegue ver, o seu wifiSsid, e diz no monitor serial que o scan é simulado (firmware/include/WiFi.h).
  • No real internet. No DNS protocol, no IP stack, no sockets to anything outside the project's boards. The four origins are Rust functions. No request in Mokxi ever leaves the tab, and the Web panel's frame is served with default-src 'none' so it cannot fetch an image from outside either.
  • Sem TLS. O WiFiClientSecure compila e então falha: connect() retorna 0 e whyNot() diz TLS não é simulado no Mokxi: não há https aqui, só http:// sob .mokxi. Um HTTPClient que recebe um, ou que recebe qualquer URL https://, retorna HTTPC_ERROR_NO_TLS com a mesma frase. Um TLS que confiasse em tudo ensinaria ao aluno que https é de graça.
  • No raw TCP to the internet. WiFiClient::connect() reaches another board of the project (above) and nothing else: to a name or to an address outside the project's boards it returns 0. The type is also what http.begin(client, url) takes, the spelling every modern tutorial uses. So no WebSocket either: the WebSockets library's client reaches only the simulated echo server at echo.mokxi, each message carried as one HTTP request (above), and nothing can connect to its server. The server side works for HTTP too: a hand-written WiFiServer (the Random Nerd Tutorials web server, on the ESP32 and the ESP8266 alike) gets each Web panel request from server.available() as the bytes a browser sends, and what it prints until stop() is read back as the HTTP response the panel shows.
  • Um celular no soft AP, e ele é o painel Web. Nenhum outro aparelho e nenhum segundo celular pode entrar no ponto de acesso da placa; maxConnections, hidden e o canal são aceitos e não mudam nada que um sketch possa perceber. O celular pega seu lease sem consultar o servidor DHCP da placa, não envia tráfego próprio além das requisições do painel, e nada chega à internet pela placa (WiFi.AP.enableNAPT() diz sim e não roteia nada). WiFi.mode(WIFI_AP) sem softAP() não levanta nada. O wifi.radio.start_ap() do CircuitPython não é simulado.
  • A second board joins a network only through a soft AP. Every board has its own private simulated network, and the Web and Cloud panels follow the first one they find. What connects boards is the air every ESP board on the canvas shares: ESP-NOW (docs/help/editor/esp-now.md) and a station joining another board's soft AP (above), with HTTPClient to the access point's WebServer and TCP between boards. Two boards that joined the same access point reach each other; nothing else routes between them.
  • O Bluetooth é uma simulação separada com a mesma honestidade (docs/bluetooth.md): o Bluetooth Classic e LE das placas ESP32 conversam com um celular no painel de Bluetooth do editor, por meio de registradores próprios nesse mesmo bloco. O Bluetooth do Pico W não é modelado.
  • Sem interrupção em quatro das seis placas. No ESP32 clássico, no ESP32-S3, no ESP8266 e na Pico W a caixa de correio não levanta interrupção de CPU nenhuma: um número de origem na matriz de interrupções e um número de IRQ da NVIC são da placa, e este bloco não é a placa, então não há número honesto para dar a ele. O runtime faz polling, e um núcleo estacionado ainda é acordado quando a rede tem algo a dizer.
  • Os números são configurações, não medições. RSSI() é o que a propriedade wifiRssi disser; nada calcula uma perda de sinal, e mover a placa no canvas não muda nada.
  • O relógio em time.mokxi é o do kernel, contado a partir de 2026-01-01T00:00:00Z, e não a hora do dia. A simulação não sabe que dia é, e inventar um seria uma mentira que um aluno não poderia conferir. O corpo diz simulated também, e configTime(), NTP.begin() e NTPClient ajustam o mesmo relógio ("Perguntar as horas", acima).
  • String é a do Arduino, do core compartilhado (firmware/lib/WString.h), com seu texto no heap. Os corpos ainda são limitados pelos tamanhos abaixo.
  • Os tamanhos têm limite. Cada fila circular de mailbox tem 4096 bytes, um corpo de requisição tem no máximo 2048 e uma resposta 4096; o painel Cloud guarda 512 bytes de cada corpo e as últimas 100 requisições. Uma página enviada pelo servidor do sketch divide sua fila com o tipo de conteúdo, então ela é cortada alguns bytes antes de 4096, e quando é cortada os painéis Web e Cloud avisam.

O fim da página

Os painéis chegam à rede por Component::ask, o terceiro canal genérico do kernel ao lado de poke e debug: uma string JSON opaca para baixo, uma string JSON opaca de volta, e um kernel que não lê nenhuma das duas. As operações são state, log, setAp, setWeather, setApi, blynkWrite, clearLog, fetch, result, e apJoin e apLeave (o celular do painel Web no soft AP); state e log respondem com "simulated": true dentro, então um painel não consegue renderizar sem isso. crates/net/src/lib.rs é a lista.

Modo internet real

Um modo opcional (worker/pro-pack.ts): o interruptor Internet real do painel Cloud, que só liga depois de GET /api/gateway dizer que a conta pode, e responde quais limites se aplicam. Grátis, logado com um e-mail confirmado, recebe FREE_GATEWAY; o pacote Pro (Pro, Estudante, Professor, Sala de aula, uma turma paga, o teste do Pro) recebe GATEWAY; um aluno de turma ou uma criança menor de 13 anos só onde um professor com as ferramentas de turma ativadas ligou para a turma dele (classes.real_internet, desligado por padrão), com GATEWAY; contas desconectadas e suspensas, nunca. Uma placa cujo wifiSsid é Wokwi-GUEST, o ponto de acesso que o Wokwi dá a uma placa e que uma importação do Wokwi nomeia, liga o interruptor sozinho quando uma execução começa (autoFor), porque no Wokwi esse ponto de acesso chega à internet; desligado à mão, fica desligado pela sessão.

No motor (crates/net): setReal {on} define o modo. Enquanto está ligado, uma CMD_REQUEST cuja URL roteia para fora (http::routes_out: qualquer host fora de .mokxi, https:// incluído, e mqtt.mokxi) não é atendida depois de HTTP_LATENCY_PS. Ela espera, sem relógio próprio, pela página: outbound responde a única requisição em espera (id, method, url, contentType, body), e outboundResult {id, status, contentType, body, note} a conclui pelo mesmo caminho que uma resposta simulada segue (fila, log, CMD_POLL). Status 0 é uma recusa e chega ao sketch como HTTPC_ERROR_CONNECTION_REFUSED. Um sketch que desiste (seu próprio timeout de HTTPClient, cinco segundos por padrão) e pede de novo descarta a requisição antiga em vez de receber BUSY, e uma resposta atrasada não encontra ninguém esperando. As origens simuladas e o endereço da própria placa nunca roteiam para fora.

Na página (web/src/ui/real-internet.ts): uma bomba consulta outbound a cada 80 ms, envia o que encontra para POST /api/gateway, e devolve a resposta.

No Worker (worker/gateway.ts): uma requisição entra, uma resposta sai. Apenas GET e POST, http e https nas portas 80, 443, 8080 e 8443, sem credenciais na URL; hosts recusados por faixa de IP (privado, loopback, link-local, CGNAT, documentação, benchmarking, multicast, reservado; IPv6 fora de global unicast, e endereços mapeados ou NAT64 julgados pela parte IPv4), por nome (um rótulo só, localhost, .local, .internal e os outros sufixos locais, os nomes de plataforma da Cloudflare, mokxi.com), e de novo pelo que o nome resolve via DNS over HTTPS, e a lista de bloqueio do dono (GATEWAY_DENY_HOSTS, uma var pública: cada nome recusa a si mesmo e todo nome abaixo dele, brokers incluídos). Redirecionamentos nunca são seguidos. Apenas o tipo de conteúdo do sketch sai como cabeçalho. Os corpos têm limite: no Pro nos próprios tamanhos da mailbox, 2048 bytes na saída e 4096 na volta, no Grátis metade disso; um corpo que não é texto fica de fora. O host tem quatro segundos. Por conta e por projeto: um minuto de rajada em memória (Pro 30 e 20, Grátis 10 e 10) e o total de um dia UTC em gateway_counts (Pro 1000 e 500, Grátis 100 e 50). O Grátis também é limitado por endereço (FREE_GATEWAY_PER_IP: 20 por minuto em memória, 300 por dia), então uma pilha de contas descartáveis numa conexão não soma; o Pro não, então uma sala de aula atrás de um endereço continua funcionando. Essa tabela é a única coisa gravada: contagens por dia por escopo, o escopo do endereço um hash com sal que muda todos os dias, nunca uma URL, host, corpo ou endereço.

MQTT: POST http://mqtt.mokxi/publish?broker=<name>&topic=<topic> com a mensagem como corpo. O gateway publica em QoS 0 via MQTT sobre WebSockets (worker/mqtt.ts) para um de test.mosquitto.org, broker.hivemq.com ou broker.emqx.io; um Worker não consegue abrir um socket TCP na porta 1883, então PubSubClient e TCP puro ainda não funcionam, e nada é assinado nem trazido de volta. Tópicos com curinga são recusados; uma mensagem tem no máximo 1024 bytes no Pro e 512 no Grátis.

WiFiClientSecure ainda é recusado pelo runtime; http.begin("https://...") e um WiFiClient comum chegam ao gateway, que faz o TLS.

Telegram (UniversalTelegramBot.h, Brian Lough's library, 1.3.0) is the one library built on that path. Telegram is a real service, so a bot reaches it only in this mode: each call (getMe, getUpdates?offset=...&limit=1, sendMessage and the rest as a POST of JSON) is one HTTPClient request to https://api.telegram.org/bot<token>/<method>, which the gateway sends and answers. The WiFiClientSecure a sketch hands the bot, and the TELEGRAM_CERTIFICATE_ROOT it gives that client, carry nothing: the gateway checks Telegram's certificate. With real internet off, every call fails at once (false, 0 or "") and the serial monitor says once: Telegram needs the real internet: switch on Real internet in the Cloud panel (signed in), or run this on a real board. A refusal, a 429 from the caps above, a wrong token and an answer cut at the size cap each say what they were, once. The caps shape a bot: the upstream EchoBot polls every second, which is twice Pro's minute and six times Free's, so Mokxi's copy of it polls every ten seconds, and on Free a project's 50 a day last about eight minutes of that. longPoll is held to three seconds, since the host gets four. Photos and files sent as bytes are not carried (the gateway takes text). The library reads Telegram's answers with a small reader of its own rather than an ArduinoJson document, which keeps the EchoBot small on every board.

Os exemplos

  • wificonnect: o laço de conexão, o endereço, o sinal e a senha errada de propósito.
  • wifiweather: HTTPClient contra weather.mokxi, o valor extraído do JSON, e uma requisição deliberada para example.com para o aluno ler a recusa no próprio monitor serial.
  • wifiapi: um GET normal para api.mokxi, com o status e o JSON impressos na Serial. Mude a resposta no painel Nuvem e rode a requisição de novo.
  • wifilamp: WebServer com dois links e um formulário, ligando o LED no GPIO 8 pelo painel Web.
  • softapserver (o ESP32 clássico, o da galeria servidor web com ponto de acesso no ESP32): WiFi.softAP("MyESP", "12345678"), uma página que conta as estações, com botões ON e OFF para o LED no GPIO 26, acessada pelo telefone do painel Web em 192.168.4.1.

wificonnect, wifiweather e wifilamp vêm para as seis placas e wifiapi para o ESP32-C3, o ESP32-C6, o ESP32-S3 e o Pico W, vinte e dois sketches, cada um acionando o pino que o exemplo blink da própria placa aciona, de modo que o circuito que observa um observa o outro. No Pico W isso é o LED_BUILTIN e o GP15, porque o LED embutido fica no CYW43439 e não está no header. No ESP32-S3 é o LED RGB embutido, aceso em branco, e o GPIO 2.

Toda placa com WiFi compila eles no navegador: os cabeçalhos estão nos pacotes do runtime, reconstruídos com node web/scripts/bundle-runtime.mjs. O ESP32 clássico, o ESP32-S3 e o ESP8266 compilam com clang-v3, o build wasm do fork da LLVM da Espressif, desde 2026-09-28. Os exemplos intocados deles ainda rodam os ELFs pré-construídos que o GCC da Espressif gera (deploy/fetch-xtensa.sh); o docs/compile.md explica o porquê.