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 quesoftAPConfig()definiu), e a barra de endereço vai para lá sozinha: aperte Ir.WebServer, umWiFiServerescrito à mão,AsyncWebServere os servidores do ESP8266 e do Pico W respondem a ele, eserver.hostHeader()é o endereço (ou nome) que o painel pediu; WiFi.softAPgetStationNum()(andWiFi.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_STARTdepois desoftAP(), depoisARDUINO_EVENT_WIFI_AP_STACONNECTED(o MAC do celular,02:50:48:4F:4E:45, aid 1) eARDUINO_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, eARDUINO_EVENT_WIFI_AP_STOPdepois desoftAPdisconnect()ou de um modo sem a parte de AP. Como os da estação, eles rodam a partir dedelay(), cerca de 100 ms após a mudança, então um laço que consultasoftAPgetStationNum()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 noWiFiServeron 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()andstop()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
WiFiClienthas no destructor here, so one that goes out of scope withoutstop()keeps its connection until its other end closes and a new connection needs the slot. Callstop(). - 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 HTTPWebServerserves is refused, as is a station'sHTTPClientrequest to another station'sWebServer.
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/{}")compathArg(0)eUriGlob("/files/*")(uri/UriBraces.h,uri/UriGlob.h; semUriRegex). - Os códigos de status. O
wl_status_té o enum do Arduino, valor por valor. Os códigos negativos doHTTPClientsão os do Arduino onde o Mokxi tem a mesma falha (-1recusado,-4não conectado,-11expirado). - 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 ohandleClient()realmente nunca responde. Umhttp.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
HTTPClientguarda a sua própria resposta. Dois clientes que cada umGET()antes de qualquer um ler recebem de volta os seus próprios corpos, egetString()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 seuwifiSsid, 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
WiFiClientSecurecompila e então falha:connect()retorna 0 ewhyNot()diz TLS não é simulado no Mokxi: não há https aqui, só http:// sob .mokxi. UmHTTPClientque recebe um, ou que recebe qualquer URLhttps://, retornaHTTPC_ERROR_NO_TLScom 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 whathttp.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 atecho.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-writtenWiFiServer(the Random Nerd Tutorials web server, on the ESP32 and the ESP8266 alike) gets each Web panel request fromserver.available()as the bytes a browser sends, and what it prints untilstop()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,hiddene 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)semsoftAP()não levanta nada. Owifi.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), withHTTPClientto the access point'sWebServerand 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 propriedadewifiRssidisser; 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 de2026-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 dizsimulatedtambém, econfigTime(),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:HTTPClientcontraweather.mokxi, o valor extraído do JSON, e uma requisição deliberada paraexample.compara o aluno ler a recusa no próprio monitor serial.wifiapi: um GET normal paraapi.mokxi, com o status e o JSON impressos na Serial. Mude a resposta no painel Nuvem e rode a requisição de novo.wifilamp:WebServercom 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ê.