Skip to content

API Reference

chumicro_wifi

chumicro_wifi

Unified wifi supervisor across CircuitPython, MicroPython, and CPython.

Exports :class:WifiService, :class:WifiConfig, and :class:WifiState.

WifiConfig

Connection configuration for WifiService.

Parameters:

Name Type Description Default
ssid str

AP SSID to associate with.

 required
password str

WPA passphrase.

 required
hostname str | None

Hostname advertised on the AP, or None to skip it.

 None
connect_timeout_ms int

Max wait for a single connect attempt, in ms (default 15 s).

 15000
first_connect_timeout_ms int | None

Longer allowance for the first connect attempt after construction, in ms, or None (default) to use connect_timeout_ms. A cold radio's first association after power-up takes longer than steady-state reconnects.

 None
reconnect_backoff_start_ms int

Initial delay between reconnect attempts (default 1 s).

 1000
reconnect_backoff_max_ms int

Cap on the exponential reconnect backoff (default 60 s).

 60000
reconnect_max int | None

Failed attempts before terminal FAILED; None (default) retries forever.

 None
power_save bool

Whether to leave the radio's power-save mode enabled (default False).

 False
tx_power_dbm int | None

Radio transmit power in dBm, or None (default) for the firmware default.

 None

from_config(config) classmethod

Build a WifiConfig from the flat runtime config.

Parameters:

Name Type Description Default
config object

A :class:chumicro_config.RuntimeConfig or plain flat dict.

 required

Raises:

Type Description
MissingConfigKey

wifi.ssid or wifi.password is absent.
InvalidConfigType

config is None or not a mapping.

try_from_config(config) classmethod

Soft-load a WifiConfig, returning None when not configured.

Parameters:

Name Type Description Default
config object

A :class:chumicro_config.RuntimeConfig, plain flat dict, or None.

 required

Returns:

Type Description
WifiConfig | None

A WifiConfig instance, or None when the section is not configured.

WifiService

Drives a wifi adapter through connect, monitor, and reconnect.

Parameters:

Name Type Description Default
config WifiConfig

A :class:WifiConfig with the credentials and tuning knobs.

 required
adapter object | None

Optional :class:WifiAdapter; None (default) selects the runtime-appropriate one.

 None
ticks object | None

Optional chumicro_timing.ticks-shaped source; defaults to the real clock.

 None

connected property

True when the substrate is currently linked.

ip property

Assigned IPv4 string, or None when not connected.

from_config(config, *, radio=None, ticks=None, **constructor_kwargs) classmethod

Build a :class:WifiService from runtime config.

The wifi.* config keys carry the deployment-varying values (credentials, timeouts, backoff, power tuning) and load through :meth:WifiConfig.from_config; any other constructor knob passes through verbatim as a keyword, and an explicit keyword wins over its config-derived value.

Parameters:

Name Type Description Default
config object

A :class:chumicro_config.RuntimeConfig or plain flat dict.

 required
radio object | None

CircuitPython radio handle for the runtime adapter; ignored on MicroPython and CPython, and unused when an explicit adapter= is passed.

 None
ticks object | None

Optional tick source, forwarded to the constructor.

 None
**constructor_kwargs object

Any other constructor knob (e.g. adapter=), passed through verbatim.

 {}

Raises:

Type Description
MissingConfigKey

wifi.ssid or wifi.password is absent.
InvalidConfigType

config is None or not a mapping.

on_state_change(callback)

Register a callback invoked on every state transition.

Parameters:

Name Type Description Default
callback object

Called as callback(old_state, new_state) in registration order.

 required

check(now_ms)

Return True when the service has work to do this tick.

handle(now_ms)

Drive the state machine forward.

WifiState

State-name constants for :class:WifiService.

← Home

Source · \ PyPI · \ Bundle · \ Experimental Bundle