Using Wi-Fi
lwIP-CE can reach a Wi-Fi network through the lwIP-CE Wi-Fi bridge, an
ESP32-S3 or ESP32-P4 board running the firmware from
lwIP-CE-WiFi-bridge, checked
out in wifi_bridge/ as a submodule. The calculator plugs
into the bridge with its stock USB cable and gets an ordinary Ethernet
interface. Everything that works over a USB Ethernet adapter (DHCP, TCP, UDP,
TLS, DNS) works the same way over the bridge.
On top of the link, the bridge exposes a control channel. Programs use it
through <lwip/wireless/wifi.h> to read the connection state, scan, and
manage saved networks. The lwIP-CE app uses the same API for its Wi-Fi screen.
┌────────────┐ USB ┌──────────────────┐ 802.11 ┌──────────┐
│ Calculator │────────▶│ lwIP-CE Wi-Fi │ · · · · │ Wi-Fi │
│ (device) │ stock │ bridge (host) │ │ network │
└────────────┘ cable └──────────────────┘ └──────────┘
Hardware
One of these boards:
The lwIP-CE bridge board (firmware target
esp32s3, the default). The design is inwifi_bridge/hardware: KiCad project, BOM and placement files infab/, and a printable enclosure. It is built around an ESP32-S3-WROOM-1-N16R8. The USB-C port powers the board and carries the console through a CH340K, which also handles reset and boot for flashing. The S3’s own USB drives the USB-A port for the calculator. The red LED blinks quickly while the bridge boots, blinks once a second while it joins a network, and stays lit while it is on Wi-Fi. Otherwise it flashes briefly every 3 seconds.A Waveshare ESP32-P4 Module Dev Kit (target
esp32p4), which reaches its ESP32-C6 Wi-Fi co-processor over SDIO. It works as is.
You also need:
The cable that came with the calculator, plugged into the board’s USB-A port. No OTG adapter is needed: the calculator is the USB device and the bridge is the USB host.
A 5 V supply for the board. The bridge powers the calculator’s USB port, so the calculator charges while it is connected.
Setting Up
Flash the bridge once, then install lwIP-CE on the calculator as usual (see
Getting Started). Fetch the firmware first if the checkout lacks it
(git submodule update --init wifi_bridge). It builds for the bridge board
by default.
For the ESP32-P4 kit, switch the target once (this resets
wifi_bridge/sdkconfig; set-target esp32s3 switches back):
idf.py -C wifi_bridge set-target esp32p4
The bridge board’s console shows up as /dev/ttyUSB0 (CH340K); the ESP32-P4
kit’s as /dev/ttyACM0.
idf.py -C wifi_bridge -p /dev/ttyUSB0 build flash # build and flash the bridge
idf.py -C wifi_bridge -p /dev/ttyUSB0 monitor # bridge log
Building the firmware needs ESP-IDF v6.1. The firmware has its own
Semantic Versioning version. Its
releases ship
lwip_wifi_bridge-<target>-<version>-merged.bin, which flashes at offset
0x0:
esptool.py --chip esp32s3 write_flash 0x0 lwip_wifi_bridge-esp32s3-<version>-merged.bin
The bridge board can also be flashed from the browser with a released firmware: see Flashing the Bridge.
The bridge starts with no saved networks. Open the lwIP-CE app on the calculator, choose Wi-Fi, then Scan for networks or Add a network. The bridge stores up to 8 networks and joins the best saved one in range on its own. When a working connection drops it looks for a network right away; after a failed join it retries every 15 seconds. A network typed in by name is marked hidden, so the bridge also tries it when it does not show up in a scan.
How the Link Behaves
The calculator’s interface comes up when the bridge attaches over USB, but its link is only up while the bridge is connected to Wi-Fi. When Wi-Fi drops, the link goes down and DHCP runs again once Wi-Fi is back, exactly like unplugging an Ethernet cable.
The calculator is directly on the Wi-Fi network: it gets its address from the network’s DHCP server and is reachable by other devices on that network. There is no NAT on the bridge, so a server running on the calculator can be reached at the calculator’s address.
The calculator uses the bridge’s Wi-Fi MAC address, because a Wi-Fi station may only send frames from its own address. As a result, the calculator usually gets the same address every time from the same network.
Crypto Offload
The bridge can also take over the slow parts of TLS. Two settings in the lwIP-CE app’s Security section control it, and both are on by default:
- Crypto offload
The bridge computes the X25519 and P-256 key exchanges and checks the RSA and ECDSA P-256 signatures on the server’s certificate chain and CertificateVerify, using its hardware accelerators. The calculator still runs the rest of TLS (key schedule, record encryption, certificate parsing and policy) itself. P-256 is slow enough on the calculator alone that some servers give up, so without offload it only offers X25519 for the key exchange.
- Bridge TRNG
The bridge’s hardware random number generator becomes the main entropy source. Once the calculator’s own generator is seeded, the bridge’s output is mixed with it into a fresh 192-bit generator, and each new TLS handshake reseeds it with fresh bridge output. Because the calculator’s own state is part of the mix, a faulty bridge cannot make the output predictable. The calculator stops collecting its own entropy in the background meanwhile. Until the bridge answers (and whenever it is unplugged) the calculator’s own source is used alone.
Offloading never changes a verdict. Signature checks run in parallel with the rest of the handshake, and the handshake waits for all of them before it sends its Finished message or hands any data to the program. If the bridge does not answer within two seconds, or cannot decide (for example, an unusual key), the calculator runs that operation itself. With an older bridge firmware, or with another USB Ethernet adapter, nothing is offloaded.
The key exchange’s ephemeral private key and the random bytes cross the USB cable to and from the bridge, so the bridge is part of the trusted hardware.
Programs can use the same operations directly: lwip_wifi_x25519(),
lwip_wifi_rsa_verify() and lwip_wifi_random() wait for the bridge’s
answer, and lwip_wifi_crypto_caps() reports which ones are available. Call
them from the main loop, not from a socket callback.
Wi-Fi Control API
Include the header:
#include <lwip/wireless/wifi.h>
The calls work while lwip_network_up() is active. Each one sends a
request to the bridge, keeps servicing USB and lwIP timers while it waits, and
returns once the bridge answers or the call times out. They can be called from
your main loop like any other blocking helper; do not call them from inside an
lwIP or USB callback.
Requests never reach the wireless network and work while Wi-Fi is down, so
they are also how a program gets the calculator online in the first place.
Saved passwords stay on the bridge: no call can read one back. Do not call
them from the event callback either: a call made while another one is waiting
returns LWIP_WIFI_ERR_BUSY.
Function |
Purpose |
|---|---|
|
|
|
Connection state: connected or not, SSID, RSSI, channel, BSSID, the
slot of the joined network, how many networks are saved, and why the
bridge last left a network ( |
|
Saved networks in preference order: slot, SSID, security, flags. |
|
Networks in range: SSID, RSSI, channel, security. Takes a few seconds. |
|
Adds a network ( |
|
The same for a WPA2/WPA3-Enterprise network. When editing, an empty username or password keeps the stored one. |
|
Deletes a saved network. |
|
A disabled network is skipped when the bridge picks one to join. |
|
Moves a saved network to the top of the preference order. |
|
Joins a saved network now. |
|
Leaves the current network and stops automatic joining until the next
|
|
The bridge firmware’s version string. Empty when the firmware is too old to report one; the lwIP-CE app’s Wi-Fi screen then asks you to update it. |
|
Registers a callback that receives the new state whenever the bridge
joins or leaves a network. Pass |
lwip_wifi_connect() returns once the bridge has started joining. Joining
takes a few seconds; wait for the event callback (or poll
lwip_wifi_get_state()) to learn whether it worked. A wrong password shows
up as the bridge never reporting connected.
Return codes:
Code |
Meaning |
|---|---|
|
The bridge carried out the request. |
|
No bridge is attached (for example, a USB Ethernet adapter is in use, or nothing is plugged in). |
|
The bridge did not answer in time. Requests that change the connection wait up to 6 seconds, a scan up to 10 seconds, others 2 seconds. |
|
The request was malformed, for example an empty or over-long SSID. |
|
The slot does not hold a saved network. |
|
All 8 slots are in use. |
|
lwIP could not allocate a buffer for the request. |
|
Another request is still waiting, or the bridge cannot scan right now (for example while it is joining a network). Try again shortly. |
Security values are the LWIP_WIFI_SEC_* constants: open, WEP, WPA, WPA2,
WPA3, WPA2/WPA3 and Enterprise. Profile flags are
LWIP_WIFI_PROFILE_ENABLED, LWIP_WIFI_PROFILE_HIDDEN (tried even when a
scan does not see it), LWIP_WIFI_PROFILE_ACTIVE (the network the bridge
is joined to) and LWIP_WIFI_PROFILE_CHECK_SERVER (Enterprise only, see
below). A profile saved without LWIP_WIFI_PROFILE_ENABLED is stored
disabled.
Enterprise networks (eduroam and most school and office networks) sign in with
a username and password over PEAP or TTLS, whichever the network offers. The
username is sent as the outer identity too. With
LWIP_WIFI_PROFILE_CHECK_SERVER the bridge only joins if the network’s
certificate chains to a CA in ESP-IDF’s built-in bundle. Many enterprise
networks use a private CA, so this check can fail on them. Without it, the
bridge cannot tell the real network from a look-alike, and a look-alike can
capture enough of the sign-in to attack the password offline.
Example
Join a network if the bridge is offline, then wait for it to connect:
#include <lwip.h>
#include <lwip/wireless/wifi.h>
static volatile bool online;
static void on_wifi(const lwip_wifi_state_t *state, void *arg)
{
(void)arg;
online = state->connected;
}
static bool go_online(const char *ssid, const char *password)
{
lwip_wifi_state_t state;
uint8_t slot;
uint32_t start;
while (!lwip_wifi_available())
lwip_service_events();
lwip_wifi_set_event_cb(on_wifi, NULL);
if (lwip_wifi_get_state(&state) == LWIP_WIFI_OK && state.connected)
return true;
if (lwip_wifi_save_profile(LWIP_WIFI_SLOT_NONE, ssid, password, LWIP_WIFI_SEC_WPA2,
LWIP_WIFI_PROFILE_ENABLED, &slot) != LWIP_WIFI_OK)
return false;
if (lwip_wifi_connect(slot) != LWIP_WIFI_OK)
return false;
start = lwip_now_ms();
while (!online && lwip_now_ms() - start < 15000)
lwip_service_events();
return online;
}
Once the bridge is connected, the interface behaves like any other: wait for a DHCP lease and use sockets as described in Using the Network.
The release examples are intentionally transport-neutral. Start from
examples/template for a new application, examples/pcb for lwIP’s
native callback API, or examples/socket for the higher-level lwIP-CE
socket API. The same socket and PCB interfaces work over either supported
network adapter. examples/wifi_api demonstrates bridge discovery, scanning,
and saved-profile management and writes its complete results to the
WIFILOG AppVar.
The Wi-Fi Screen
Running the lwIP-CE app directly opens its settings; Wi-Fi shows the bridge’s state at the top and the saved networks below, followed by Scan for networks, Add a network and Join automatically / Disconnect. Opening a saved network offers connect, change password, rename, change security, skip or use when joining, move to top, and forget. The screen updates on its own when the bridge joins or leaves a network.
Text entry cycles through four key sets with alpha: lower case, upper case, digits, and symbols. In password fields, mode shows or hides the text.