Use the operating system’s Wi-Fi stack.

Platform requirements #

The first target is Linux/OpenWrt with a compatible radio, enterprise authentication support, protected private-key storage, and access to the supported supplicant control interface.

A shared-password-only Wi-Fi implementation is insufficient. Passpoint discovery requires the relevant supplicant and firmware capabilities; an arbitrary installed package or driver must not be assumed compatible.

Linux device services #

First install the Python SDK and the unique device credential directory. The reference units expect /etc/hotspotvu-connect and interface wlan0. Install the package system-wide in your device image or adjust the ExecStart path to your chosen environment. Do not point the service at a provisioning workstation’s temporary virtual environment.

Provide DHCP with exactly one network manager. The kit includes systemd/80-hotspotvu.network as an optional systemd-networkd example; use it only when networkd owns the interface. Configure time synchronization before certificate validation.

These commands are for systemd Linux images. OpenWrt uses netifd and the separate opt-in infrastructure service; do not install these units or run a competing supplicant alongside netifd.

# Run as root after installing the SDK on the device.
# Requires full EAP-TLS wpa_supplicant, wpa_cli, OpenSSL, and reliable time.
# The supplied units expect /usr/local/bin/hotspotvu-connect and
# /sbin/wpa_supplicant. Adjust those paths if your image differs.
command -v hotspotvu-connect wpa_supplicant wpa_cli openssl
install -m 644 hotspotvu-kit/sdk/python/systemd/hotspotvu-wifi@.service /etc/systemd/system/
install -m 644 hotspotvu-kit/sdk/python/systemd/hotspotvu-connect@.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now hotspotvu-wifi@wlan0 hotspotvu-connect@wlan0
hotspotvu-connect status --directory /etc/hotspotvu-connect --interface wlan0

• Factory provisioning →

Reference adapter responsibilities #

Install an approved profile with the expected network CA and server identity checks. Load the device certificate and private key from protected local storage. Retry bounded failures with backoff.

Report authentication, site permission, local link, Internet checks, and management telemetry as separate observations. Handle rotation without logging key material or falling back to unauthenticated access.

Infrastructure adapter #

A satellite adds restricted backhaul authentication, approved AP configuration, configuration acknowledgements, and signed software management. Ordinary manufacturer clients do not receive those privileges.

An application update cannot install missing radio or enterprise-authentication capabilities by itself. Qualification and signed firmware must provide the required underlying software.

Unattended credential renewal #

hotspotvu-connect run attempts renewal when the installed certificate is within seven days of expiry. Use hotspotvu-connect renew to request renewal explicitly. The CLI signs the proof locally and installs the returned bundle without sending its private key.

The runtime renewal API requires an event UUID, Unix timestamp, CSR, and base64 SHA-256 signature. The signed bytes are event_id, device_id, decimal timestamp, and the lowercase SHA-256 digest of the exact UTF-8 CSR, separated by LF characters with no trailing LF. Sign with the private key associated with the reporting token. Fresh requests require a timestamp within 300 seconds of server time.

Keep an identical event and payload when retrying a lost response. The server returns its encrypted stored receipt instead of issuing again; reusing the identifier with different content returns 409. Earlier valid tokens remain usable until their associated certificate expires or is revoked.

hotspotvu-connect status --directory /var/lib/hotspotvu --interface wlan0
hotspotvu-connect renew --directory /var/lib/hotspotvu --interface wlan0
hotspotvu-connect run --directory /var/lib/hotspotvu --interface wlan0

Integrate and validate #

Use hotspotvu-connect keygen, enroll, configure, run, status, and renew with the documented options supplied by the Linux kit. Use the Python and TypeScript API clients for server-side automation against the published contract.

Keep manufacturer automation tokens on trusted servers; devices use their own certificate, private key, and reporting token. Before production review, test power loss, reconnects, renewal, revocation, incorrect time, weak signal, and a reachable Wi-Fi network with no Internet uplink. Embedded adapters require separate qualification.