Skip to content

Onboarding

lifx.onboard takes a LIFX device that is not on your network, joins its own setup access point (SoftAP), hands it your home network's credentials, and confirms it arrived. Import it explicitly: nothing here is exported from the top-level lifx namespace. The onboarding guide explains the sequence and how the pieces fit together; this page is the reference.

from lifx.onboard import HomeNetwork, onboard

lifx-async ships no implementation of Scanner or Joiner. Joining a host to a WiFi network needs subprocesses, ctypes or an app bundle, so those live outside this library.

Entry points

onboard async

onboard(
    network: HomeNetwork,
    *,
    scanner: Scanner | None,
    joiner: Joiner,
    target: str | Serial | None = None,
    softap: SoftApClient | None = None,
    verify: DeviceWatcher | bool = True,
    on_event: EventCallback | None = None,
    events: OnboardEventQueue | None = None,
    rejoin_ssid: str | None = None,
    rejoin_password: str = "",
    min_rssi: float = 0.0,
    include_non_lifx: bool = False,
    legacy_tls: bool = False,
    softap_address: str = SOFTAP_ADDRESS,
    softap_port: int = SOFTAP_PORT,
    find_timeout: float = FIND_TIMEOUT,
    find_poll: float = FIND_POLL,
    wait_timeout: float = WAIT_TIMEOUT,
    wait_poll: float = WAIT_POLL,
    dial_timeout: float = DIAL_TIMEOUT,
    rejoin_timeout: float = REJOIN_TIMEOUT,
    rejoin_poll: float = REJOIN_POLL,
    auto_join_wait: float = AUTO_JOIN_WAIT,
    verify_timeout: float = VERIFY_TIMEOUT,
    verify_poll: float = VERIFY_POLL,
) -> Result

Onboard one device from its SoftAP onto network.

The sequence is scan, join, wait, dial, configure, rejoin and verify. Progress is reported through on_event (called synchronously) and events (a bounded queue that never blocks the sequence).

PARAMETER DESCRIPTION
network

The home network to hand the device.

TYPE: HomeNetwork

scanner

Lists visible networks; may be None only when target is a full SoftAP name, which skips the scan.

TYPE: Scanner | None

joiner

Joins the host to networks. Its optional capabilities (CurrentNetworkReporter, NetworkForgetter, Disassociator) are used when present and win over the scanner's.

TYPE: Joiner

target

A SoftAP name such as "LIFX Candle Color 8274eb", a serial, its six-hex suffix, or None for the first LIFX SoftAP seen.

TYPE: str | Serial | None DEFAULT: None

softap

The control channel; a SoftApConnection is built from softap_address, softap_port, dial_timeout and legacy_tls when omitted.

TYPE: SoftApClient | None DEFAULT: None

verify

A running DeviceWatcher to verify through, True to open one for the verification window, False to skip it.

TYPE: DeviceWatcher | bool DEFAULT: True

on_event

Called with each OnboardEvent; exceptions are logged.

TYPE: EventCallback | None DEFAULT: None

events

A queue every event is put on.

TYPE: OnboardEventQueue | None DEFAULT: None

rejoin_ssid

A network to return the host to in preference to the one it was on; rejoin_password defaults to the home password when this is the home SSID.

TYPE: str | None DEFAULT: None

rejoin_password

The password for rejoin_ssid.

TYPE: str DEFAULT: ''

min_rssi

Passed to the scanner.

TYPE: float DEFAULT: 0.0

include_non_lifx

Passed to the scanner.

TYPE: bool DEFAULT: False

legacy_tls

Pin TLS 1.0 for pre-2020 firmware.

TYPE: bool DEFAULT: False

softap_address

Where the device's SoftAP listens.

TYPE: str DEFAULT: SOFTAP_ADDRESS

softap_port

The port it listens on.

TYPE: int DEFAULT: SOFTAP_PORT

find_timeout

Budget for the scan, and separately for the join.

TYPE: float DEFAULT: FIND_TIMEOUT

find_poll

Interval between scan attempts and between join attempts.

TYPE: float DEFAULT: FIND_POLL

wait_timeout

Budget for the SoftAP to accept a probe.

TYPE: float DEFAULT: WAIT_TIMEOUT

wait_poll

Interval between probes; each probe is bounded by it.

TYPE: float DEFAULT: WAIT_POLL

dial_timeout

Budget for the TLS dial.

TYPE: float DEFAULT: DIAL_TIMEOUT

rejoin_timeout

Budget per rejoin target.

TYPE: float DEFAULT: REJOIN_TIMEOUT

rejoin_poll

Interval between rejoin attempts and host network polls.

TYPE: float DEFAULT: REJOIN_POLL

auto_join_wait

How long the OS auto-join gets once the host has left the SoftAP.

TYPE: float DEFAULT: AUTO_JOIN_WAIT

verify_timeout

Budget for the device to appear on the LAN.

TYPE: float DEFAULT: VERIFY_TIMEOUT

verify_poll

Discovery sweep interval while verifying.

TYPE: float DEFAULT: VERIFY_POLL

RETURNS DESCRIPTION
Result

The Result of a successful run.

RAISES DESCRIPTION
InvalidSoftApTargetError

If target is none of the accepted forms.

ValueError

If scanner is None and a scan is needed.

LifxOnboardError

The typed error of the phase that failed; its result carries the same fields a success would.

CancelledError

After host recovery, when cancelled.

Source code in src/lifx/onboard/machine.py
async def onboard(
    network: HomeNetwork,
    *,
    scanner: Scanner | None,
    joiner: Joiner,
    target: str | Serial | None = None,
    softap: SoftApClient | None = None,
    verify: DeviceWatcher | bool = True,
    on_event: EventCallback | None = None,
    events: OnboardEventQueue | None = None,
    rejoin_ssid: str | None = None,
    rejoin_password: str = "",
    min_rssi: float = 0.0,
    include_non_lifx: bool = False,
    legacy_tls: bool = False,
    softap_address: str = SOFTAP_ADDRESS,
    softap_port: int = SOFTAP_PORT,
    find_timeout: float = FIND_TIMEOUT,
    find_poll: float = FIND_POLL,
    wait_timeout: float = WAIT_TIMEOUT,
    wait_poll: float = WAIT_POLL,
    dial_timeout: float = DIAL_TIMEOUT,
    rejoin_timeout: float = REJOIN_TIMEOUT,
    rejoin_poll: float = REJOIN_POLL,
    auto_join_wait: float = AUTO_JOIN_WAIT,
    verify_timeout: float = VERIFY_TIMEOUT,
    verify_poll: float = VERIFY_POLL,
) -> Result:
    """Onboard one device from its SoftAP onto ``network``.

    The sequence is scan, join, wait, dial, configure, rejoin and verify.
    Progress is reported through ``on_event`` (called synchronously) and
    ``events`` (a bounded queue that never blocks the sequence).

    Args:
        network: The home network to hand the device.
        scanner: Lists visible networks; may be ``None`` only when ``target``
            is a full SoftAP name, which skips the scan.
        joiner: Joins the host to networks. Its optional capabilities
            (``CurrentNetworkReporter``, ``NetworkForgetter``,
            ``Disassociator``) are used when present and win over the
            scanner's.
        target: A SoftAP name such as ``"LIFX Candle Color 8274eb"``, a
            serial, its six-hex suffix, or ``None`` for the first LIFX SoftAP
            seen.
        softap: The control channel; a ``SoftApConnection`` is built from
            ``softap_address``, ``softap_port``, ``dial_timeout`` and
            ``legacy_tls`` when omitted.
        verify: A running ``DeviceWatcher`` to verify through, ``True`` to
            open one for the verification window, ``False`` to skip it.
        on_event: Called with each ``OnboardEvent``; exceptions are logged.
        events: A queue every event is put on.
        rejoin_ssid: A network to return the host to in preference to the
            one it was on; ``rejoin_password`` defaults to the home password
            when this is the home SSID.
        rejoin_password: The password for ``rejoin_ssid``.
        min_rssi: Passed to the scanner.
        include_non_lifx: Passed to the scanner.
        legacy_tls: Pin TLS 1.0 for pre-2020 firmware.
        softap_address: Where the device's SoftAP listens.
        softap_port: The port it listens on.
        find_timeout: Budget for the scan, and separately for the join.
        find_poll: Interval between scan attempts and between join attempts.
        wait_timeout: Budget for the SoftAP to accept a probe.
        wait_poll: Interval between probes; each probe is bounded by it.
        dial_timeout: Budget for the TLS dial.
        rejoin_timeout: Budget per rejoin target.
        rejoin_poll: Interval between rejoin attempts and host network polls.
        auto_join_wait: How long the OS auto-join gets once the host has
            left the SoftAP.
        verify_timeout: Budget for the device to appear on the LAN.
        verify_poll: Discovery sweep interval while verifying.

    Returns:
        The ``Result`` of a successful run.

    Raises:
        InvalidSoftApTargetError: If ``target`` is none of the accepted forms.
        ValueError: If ``scanner`` is ``None`` and a scan is needed.
        LifxOnboardError: The typed error of the phase that failed; its
            ``result`` carries the same fields a success would.
        asyncio.CancelledError: After host recovery, when cancelled.
    """
    if softap is None:
        softap = _default_softap(
            softap_address,
            softap_port,
            dial_timeout=dial_timeout,
            legacy_tls=legacy_tls,
        )
    run = _Run(
        network,
        scanner=scanner,
        joiner=joiner,
        softap=softap,
        verify=verify,
        on_event=on_event,
        events=events,
        rejoin_ssid=rejoin_ssid,
        rejoin_password=rejoin_password,
        min_rssi=min_rssi,
        include_non_lifx=include_non_lifx,
        find_timeout=find_timeout,
        find_poll=find_poll,
        wait_timeout=wait_timeout,
        wait_poll=wait_poll,
        dial_timeout=dial_timeout,
        rejoin_timeout=rejoin_timeout,
        rejoin_poll=rejoin_poll,
        auto_join_wait=auto_join_wait,
        verify_timeout=verify_timeout,
        verify_poll=verify_poll,
    )
    return await run.run(target)

bulk_onboard async

bulk_onboard(
    network: HomeNetwork,
    *,
    scanner: Scanner,
    joiner: Joiner,
    targets: Iterable[Serial | str] = (),
    max_devices: int | None = None,
    scan_interval: float = SCAN_INTERVAL,
    stop_when_idle_for: float | None = None,
    softap: SoftApClient | None = None,
    verify: DeviceWatcher | bool = True,
    on_event: EventCallback | None = None,
    events: OnboardEventQueue | None = None,
    rejoin_ssid: str | None = None,
    rejoin_password: str = "",
    min_rssi: float = 0.0,
    include_non_lifx: bool = False,
    legacy_tls: bool = False,
    softap_address: str = SOFTAP_ADDRESS,
    softap_port: int = SOFTAP_PORT,
    find_timeout: float = FIND_TIMEOUT,
    find_poll: float = FIND_POLL,
    wait_timeout: float = WAIT_TIMEOUT,
    wait_poll: float = WAIT_POLL,
    dial_timeout: float = DIAL_TIMEOUT,
    rejoin_timeout: float = REJOIN_TIMEOUT,
    rejoin_poll: float = REJOIN_POLL,
    auto_join_wait: float = AUTO_JOIN_WAIT,
    verify_timeout: float = VERIFY_TIMEOUT,
    verify_poll: float = VERIFY_POLL,
) -> AsyncIterator[Result]

Onboard every new LIFX SoftAP the scanner sees, one device at a time.

Scans every scan_interval seconds. Each round that shows a LIFX SoftAP not yet attempted (and, when targets is given, on the allow-list) runs join, wait, dial, configure and rejoin for it exactly as onboard() does, with host recovery on failure, then scans again. A serial is attempted once however often it recurs. A failed attempt yields a Result with phase and error set; the loop goes on.

Verification is interleaved. With verify set, one watcher serves the whole run: a caller's DeviceWatcher is used as is and left running, while True opens a library-owned watcher (sweep_interval of verify_poll, UDP only) before the first attempt and closes it when the run ends, also on cancellation. As soon as a device is configured it starts listening for that serial on the LAN, and once the host has rejoined its network the wait of up to verify_timeout runs in the background while the loop scans for the next device. Results are therefore yielded in completion order: a device verified while a later one was being configured is yielded as soon as the generator is resumed, and every pending verification is drained after the loop ends. With verify=False each Result is yielded right after its rejoin.

The loop ends when every allow-listed target has been attempted, when max_devices attempts (successful or not) have been made, when stop_when_idle_for seconds of scanning have passed without a new serial (the clock restarts when a device is attempted and again when scanning resumes after it, so time spent onboarding never counts as idle, while a scan that shows nothing new does not reset it), or when the consumer's task is cancelled, in which case host recovery runs for the device in flight, pending verifications are cancelled, the owned watcher is closed and the CancelledError propagates. Allow-listed targets never seen are yielded last as SCAN-phase SoftApNotFoundError results. Without targets, max_devices or stop_when_idle_for the loop runs until cancelled.

Events reach on_event and events as they do from onboard(). SCANNING is emitted when scanning starts and again after each attempt, not on every round; DISCOVERED once per device attempted, carrying every network that round's scan returned; the per-device events are those of onboard().

Early exit: an async for that breaks leaves the generator open until it is garbage collected; wrap it in contextlib.aclosing() to close the owned watcher and cancel pending verifications at once.

PARAMETER DESCRIPTION
network

The home network to hand every device.

TYPE: HomeNetwork

scanner

Lists visible networks; required, since every device is found by scanning.

TYPE: Scanner

joiner

Joins the host to networks, as for onboard().

TYPE: Joiner

targets

Serials or six-hex suffixes to onboard; every other LIFX SoftAP is ignored. Empty means every LIFX SoftAP seen.

TYPE: Iterable[Serial | str] DEFAULT: ()

max_devices

Stop after this many attempts.

TYPE: int | None DEFAULT: None

scan_interval

Seconds between scan rounds that found nothing new.

TYPE: float DEFAULT: SCAN_INTERVAL

stop_when_idle_for

Stop once this many seconds of scanning have passed without a new serial being seen.

TYPE: float | None DEFAULT: None

softap

The control channel, reused for every device; a SoftApConnection is built when omitted.

TYPE: SoftApClient | None DEFAULT: None

verify

A running DeviceWatcher to verify through, True to open one for the run, False to skip verification.

TYPE: DeviceWatcher | bool DEFAULT: True

on_event

Called with each OnboardEvent; exceptions are logged.

TYPE: EventCallback | None DEFAULT: None

events

A queue every event is put on.

TYPE: OnboardEventQueue | None DEFAULT: None

rejoin_ssid

As for onboard().

TYPE: str | None DEFAULT: None

rejoin_password

As for onboard().

TYPE: str DEFAULT: ''

min_rssi

Passed to the scanner.

TYPE: float DEFAULT: 0.0

include_non_lifx

Passed to the scanner.

TYPE: bool DEFAULT: False

legacy_tls

Pin TLS 1.0 for pre-2020 firmware.

TYPE: bool DEFAULT: False

softap_address

Where each device's SoftAP listens.

TYPE: str DEFAULT: SOFTAP_ADDRESS

softap_port

The port it listens on.

TYPE: int DEFAULT: SOFTAP_PORT

find_timeout

Budget for each join, and the most one scan may take.

TYPE: float DEFAULT: FIND_TIMEOUT

find_poll

Interval between join attempts.

TYPE: float DEFAULT: FIND_POLL

wait_timeout

Budget for the SoftAP to accept a probe.

TYPE: float DEFAULT: WAIT_TIMEOUT

wait_poll

Interval between probes; each probe is bounded by it.

TYPE: float DEFAULT: WAIT_POLL

dial_timeout

Budget for the TLS dial.

TYPE: float DEFAULT: DIAL_TIMEOUT

rejoin_timeout

Budget per rejoin target.

TYPE: float DEFAULT: REJOIN_TIMEOUT

rejoin_poll

Interval between rejoin attempts and host network polls.

TYPE: float DEFAULT: REJOIN_POLL

auto_join_wait

How long the OS auto-join gets once the host has left the SoftAP.

TYPE: float DEFAULT: AUTO_JOIN_WAIT

verify_timeout

Budget for each device to appear on the LAN.

TYPE: float DEFAULT: VERIFY_TIMEOUT

verify_poll

Discovery sweep interval of the owned watcher.

TYPE: float DEFAULT: VERIFY_POLL

YIELDS DESCRIPTION
AsyncIterator[Result]

One Result per attempted device, in completion order, then one

AsyncIterator[Result]

per allow-listed target never seen.

RAISES DESCRIPTION
InvalidSoftApTargetError

If a target is neither a serial nor a suffix.

CancelledError

After host recovery, when cancelled.

Source code in src/lifx/onboard/bulk.py
async def bulk_onboard(
    network: HomeNetwork,
    *,
    scanner: Scanner,
    joiner: Joiner,
    targets: Iterable[Serial | str] = (),
    max_devices: int | None = None,
    scan_interval: float = SCAN_INTERVAL,
    stop_when_idle_for: float | None = None,
    softap: SoftApClient | None = None,
    verify: DeviceWatcher | bool = True,
    on_event: EventCallback | None = None,
    events: OnboardEventQueue | None = None,
    rejoin_ssid: str | None = None,
    rejoin_password: str = "",
    min_rssi: float = 0.0,
    include_non_lifx: bool = False,
    legacy_tls: bool = False,
    softap_address: str = SOFTAP_ADDRESS,
    softap_port: int = SOFTAP_PORT,
    find_timeout: float = FIND_TIMEOUT,
    find_poll: float = FIND_POLL,
    wait_timeout: float = WAIT_TIMEOUT,
    wait_poll: float = WAIT_POLL,
    dial_timeout: float = DIAL_TIMEOUT,
    rejoin_timeout: float = REJOIN_TIMEOUT,
    rejoin_poll: float = REJOIN_POLL,
    auto_join_wait: float = AUTO_JOIN_WAIT,
    verify_timeout: float = VERIFY_TIMEOUT,
    verify_poll: float = VERIFY_POLL,
) -> AsyncIterator[Result]:
    """Onboard every new LIFX SoftAP the scanner sees, one device at a time.

    Scans every ``scan_interval`` seconds. Each round that shows a LIFX SoftAP
    not yet attempted (and, when ``targets`` is given, on the allow-list)
    runs join, wait, dial, configure and rejoin for it exactly as
    ``onboard()`` does, with host recovery on failure, then scans again. A
    serial is attempted once however often it recurs. A failed attempt yields
    a ``Result`` with ``phase`` and ``error`` set; the loop goes on.

    Verification is interleaved. With ``verify`` set, one watcher serves the
    whole run: a caller's ``DeviceWatcher`` is used as is and left running,
    while ``True`` opens a library-owned watcher (``sweep_interval`` of
    ``verify_poll``, UDP only) before the first attempt and closes it when
    the run ends, also on cancellation. As soon as a device is configured it
    starts listening for that serial on the LAN, and once the host has
    rejoined its network the wait of up to ``verify_timeout`` runs in the
    background while the loop scans for the next device. Results are
    therefore yielded in completion order: a device verified while a later
    one was being configured is yielded as soon as the generator is resumed,
    and every pending verification is drained after the loop ends. With
    ``verify=False`` each ``Result`` is yielded right after its rejoin.

    The loop ends when every allow-listed target has been attempted, when
    ``max_devices`` attempts (successful or not) have been made, when
    ``stop_when_idle_for`` seconds of scanning have passed without a new
    serial (the clock restarts when a device is attempted and again when
    scanning resumes after it, so time spent onboarding never counts as
    idle, while a scan that shows nothing new does not reset it), or when
    the consumer's task is cancelled,
    in which case host recovery runs for the device in flight, pending
    verifications are cancelled, the owned watcher is closed and the
    ``CancelledError`` propagates. Allow-listed targets never seen are
    yielded last as ``SCAN``-phase ``SoftApNotFoundError`` results. Without
    ``targets``, ``max_devices`` or ``stop_when_idle_for`` the loop runs
    until cancelled.

    Events reach ``on_event`` and ``events`` as they do from ``onboard()``.
    ``SCANNING`` is emitted when scanning starts and again after each
    attempt, not on every round; ``DISCOVERED`` once per device attempted,
    carrying every network that round's scan returned; the per-device
    events are those of ``onboard()``.

    Early exit: an ``async for`` that ``break``s leaves the generator open
    until it is garbage collected; wrap it in ``contextlib.aclosing()`` to
    close the owned watcher and cancel pending verifications at once.

    Args:
        network: The home network to hand every device.
        scanner: Lists visible networks; required, since every device is
            found by scanning.
        joiner: Joins the host to networks, as for ``onboard()``.
        targets: Serials or six-hex suffixes to onboard; every other LIFX
            SoftAP is ignored. Empty means every LIFX SoftAP seen.
        max_devices: Stop after this many attempts.
        scan_interval: Seconds between scan rounds that found nothing new.
        stop_when_idle_for: Stop once this many seconds of scanning have
            passed without a new serial being seen.
        softap: The control channel, reused for every device; a
            ``SoftApConnection`` is built when omitted.
        verify: A running ``DeviceWatcher`` to verify through, ``True`` to
            open one for the run, ``False`` to skip verification.
        on_event: Called with each ``OnboardEvent``; exceptions are logged.
        events: A queue every event is put on.
        rejoin_ssid: As for ``onboard()``.
        rejoin_password: As for ``onboard()``.
        min_rssi: Passed to the scanner.
        include_non_lifx: Passed to the scanner.
        legacy_tls: Pin TLS 1.0 for pre-2020 firmware.
        softap_address: Where each device's SoftAP listens.
        softap_port: The port it listens on.
        find_timeout: Budget for each join, and the most one scan may take.
        find_poll: Interval between join attempts.
        wait_timeout: Budget for the SoftAP to accept a probe.
        wait_poll: Interval between probes; each probe is bounded by it.
        dial_timeout: Budget for the TLS dial.
        rejoin_timeout: Budget per rejoin target.
        rejoin_poll: Interval between rejoin attempts and host network polls.
        auto_join_wait: How long the OS auto-join gets once the host has
            left the SoftAP.
        verify_timeout: Budget for each device to appear on the LAN.
        verify_poll: Discovery sweep interval of the owned watcher.

    Yields:
        One ``Result`` per attempted device, in completion order, then one
        per allow-listed target never seen.

    Raises:
        InvalidSoftApTargetError: If a target is neither a serial nor a suffix.
        asyncio.CancelledError: After host recovery, when cancelled.
    """
    if softap is None:
        softap = _default_softap(
            softap_address,
            softap_port,
            dial_timeout=dial_timeout,
            legacy_tls=legacy_tls,
        )
    run = _BulkRun(
        network,
        scanner=scanner,
        joiner=joiner,
        targets=targets,
        max_devices=max_devices,
        scan_interval=scan_interval,
        stop_when_idle_for=stop_when_idle_for,
        softap=softap,
        verify=verify,
        on_event=on_event,
        events=events,
        min_rssi=min_rssi,
        include_non_lifx=include_non_lifx,
        verify_timeout=verify_timeout,
        verify_poll=verify_poll,
        run_kwargs={
            "rejoin_ssid": rejoin_ssid,
            "rejoin_password": rejoin_password,
            "find_timeout": find_timeout,
            "find_poll": find_poll,
            "wait_timeout": wait_timeout,
            "wait_poll": wait_poll,
            "dial_timeout": dial_timeout,
            "rejoin_timeout": rejoin_timeout,
            "rejoin_poll": rejoin_poll,
            "auto_join_wait": auto_join_wait,
        },
    )
    async for result in run.results():
        yield result

Networks

HomeNetwork dataclass

HomeNetwork(
    ssid: str, password: str = "", security: WifiSecurity | int | None = None
)

The network a device should join.

security defaults to OPEN for an empty password and WPA2_AES_PSK otherwise. The password is never shown by repr or str, but is part of equality.

RAISES DESCRIPTION
ValueError

If the SSID is empty or over 32 UTF-8 bytes, or the password is over 64 UTF-8 bytes. Nothing is truncated.

MissingCredentialsError

If a secured mode is given with no password.

SoftApNetwork dataclass

SoftApNetwork(ssid: str, serial: Serial | None, bssid: str, rssi: float = 0.0)

A WiFi network seen while scanning, usually a LIFX SoftAP.

ATTRIBUTE DESCRIPTION
ssid

Network name.

TYPE: str

serial

Serial derived from the name, or None for a foreign network.

TYPE: Serial | None

bssid

Lowercase colon-separated hardware address.

TYPE: str

rssi

Signal strength, 0.0 when the backend cannot report one.

TYPE: float

METHOD DESCRIPTION
from_ssid

Build a network from a LIFX SoftAP name.

foreign

Build a network that is not a LIFX SoftAP (no serial).

Methods:

from_ssid classmethod
from_ssid(ssid: str, rssi: float = 0.0) -> SoftApNetwork

Build a network from a LIFX SoftAP name.

RAISES DESCRIPTION
ValueError

If ssid is not a LIFX SoftAP name.

Source code in src/lifx/onboard/models.py
@classmethod
def from_ssid(cls, ssid: str, rssi: float = 0.0) -> SoftApNetwork:
    """Build a network from a LIFX SoftAP name.

    Raises:
        ValueError: If ``ssid`` is not a LIFX SoftAP name.
    """
    serial = Serial.from_softap_ssid(ssid)
    bssid = ":".join(f"{octet:02x}" for octet in LIFX_OUI + serial.value[3:])
    return cls(ssid=ssid, serial=serial, bssid=bssid, rssi=rssi)
foreign classmethod
foreign(ssid: str, bssid: str, rssi: float = 0.0) -> SoftApNetwork

Build a network that is not a LIFX SoftAP (no serial).

Source code in src/lifx/onboard/models.py
@classmethod
def foreign(cls, ssid: str, bssid: str, rssi: float = 0.0) -> SoftApNetwork:
    """Build a network that is not a LIFX SoftAP (no serial)."""
    return cls(ssid=ssid, serial=None, bssid=bssid.lower(), rssi=rssi)

Host WiFi protocols

The caller supplies a Scanner and a Joiner. The three capabilities after them are optional and are found at runtime with isinstance; the Joiner is consulted before the Scanner for each one.

Scanner

Bases: Protocol

Lists the WiFi networks the host can see.

METHOD DESCRIPTION
scan

Return the networks currently visible.

ATTRIBUTE DESCRIPTION
interface

The host interface scanned, for diagnostics.

TYPE: str

Attributes

interface property
interface: str

The host interface scanned, for diagnostics.

Methods:

scan async
scan(
    *, min_rssi: float = 0.0, include_non_lifx: bool = False
) -> list[SoftApNetwork]

Return the networks currently visible.

Only LIFX SoftAPs are returned unless include_non_lifx is set. An empty list with no error is a valid result.

Source code in src/lifx/onboard/protocols.py
async def scan(
    self, *, min_rssi: float = 0.0, include_non_lifx: bool = False
) -> list[SoftApNetwork]:
    """Return the networks currently visible.

    Only LIFX SoftAPs are returned unless ``include_non_lifx`` is set.
    An empty list with no error is a valid result.
    """
    ...

Joiner

Bases: Protocol

Joins the host to a WiFi network.

METHOD DESCRIPTION
join

Join network; a no-op when already joined.

rejoin

Join the network named ssid with password.

Methods:

join async
join(network: SoftApNetwork) -> None

Join network; a no-op when already joined.

Source code in src/lifx/onboard/protocols.py
async def join(self, network: SoftApNetwork) -> None:
    """Join ``network``; a no-op when already joined."""
    ...
rejoin async
rejoin(ssid: str, password: str = '') -> None

Join the network named ssid with password.

Source code in src/lifx/onboard/protocols.py
async def rejoin(self, ssid: str, password: str = "") -> None:
    """Join the network named ``ssid`` with ``password``."""
    ...

CurrentNetworkReporter

Bases: Protocol

Optional capability: reports the network the host is on.

METHOD DESCRIPTION
current_ssid

The SSID the host is associated with, or None when it is not.

Methods:

current_ssid async
current_ssid() -> str | None

The SSID the host is associated with, or None when it is not.

Source code in src/lifx/onboard/protocols.py
async def current_ssid(self) -> str | None:
    """The SSID the host is associated with, or ``None`` when it is not."""
    ...

NetworkForgetter

Bases: Protocol

Optional capability: removes a network from the host's saved networks.

METHOD DESCRIPTION
forget

Forget the saved network named ssid.

Methods:

forget async
forget(ssid: str) -> None

Forget the saved network named ssid.

Source code in src/lifx/onboard/protocols.py
async def forget(self, ssid: str) -> None:
    """Forget the saved network named ``ssid``."""
    ...

Disassociator

Bases: Protocol

Optional capability: drops the host's current association.

METHOD DESCRIPTION
disassociate

Leave the current network without joining another.

Methods:

disassociate async
disassociate() -> None

Leave the current network without joining another.

Source code in src/lifx/onboard/protocols.py
async def disassociate(self) -> None:
    """Leave the current network without joining another."""
    ...

SoftAP control channel

SoftApClient

Bases: Protocol

The control channel the onboarding sequence drives.

SoftApConnection is the real implementation; tests substitute fakes.

METHOD DESCRIPTION
probe

Make one plain TCP connection to the SoftAP and close it.

open

Connect and complete the TLS handshake.

send_access_point

Write the credential message for target.

close

Close the connection; safe to call when it is not open.

ATTRIBUTE DESCRIPTION
address

The SoftAP address this client talks to.

TYPE: str

port

The SoftAP port this client talks to.

TYPE: int

Attributes

address property
address: str

The SoftAP address this client talks to.

port property
port: int

The SoftAP port this client talks to.

Methods:

probe async
probe(*, timeout: float | None = None) -> None

Make one plain TCP connection to the SoftAP and close it.

RAISES DESCRIPTION
SoftApUnreachableError

If the connection fails or timeout elapses first.

Source code in src/lifx/onboard/softap.py
async def probe(self, *, timeout: float | None = None) -> None:
    """Make one plain TCP connection to the SoftAP and close it.

    Raises:
        SoftApUnreachableError: If the connection fails or ``timeout``
            elapses first.
    """
    ...
open async
open() -> None

Connect and complete the TLS handshake.

RAISES DESCRIPTION
SoftApDialError

If the connection or handshake fails or the dial timeout elapses first.

Source code in src/lifx/onboard/softap.py
async def open(self) -> None:
    """Connect and complete the TLS handshake.

    Raises:
        SoftApDialError: If the connection or handshake fails or the dial
            timeout elapses first.
    """
    ...
send_access_point async
send_access_point(target: Serial, network: HomeNetwork) -> None

Write the credential message for target.

RAISES DESCRIPTION
SoftApSendError

If the message cannot be written.

Source code in src/lifx/onboard/softap.py
async def send_access_point(self, target: Serial, network: HomeNetwork) -> None:
    """Write the credential message for ``target``.

    Raises:
        SoftApSendError: If the message cannot be written.
    """
    ...
close async
close() -> None

Close the connection; safe to call when it is not open.

Source code in src/lifx/onboard/softap.py
async def close(self) -> None:
    """Close the connection; safe to call when it is not open."""
    ...

SoftApConnection

SoftApConnection(
    address: str = SOFTAP_ADDRESS,
    port: int = SOFTAP_PORT,
    dial_timeout: float = 10.0,
    legacy_tls: bool = False,
)

A TLS connection to a device's SoftAP.

Use as an async context manager, or call open(), send_access_point() and close() directly. Nothing is ever read from the device.

PARAMETER DESCRIPTION
address

The SoftAP address.

TYPE: str DEFAULT: SOFTAP_ADDRESS

port

The SoftAP port.

TYPE: int DEFAULT: SOFTAP_PORT

dial_timeout

Seconds allowed for the TCP connect plus TLS handshake.

TYPE: float DEFAULT: 10.0

legacy_tls

Pin TLS 1.0 with AES256-SHA for firmware that speaks nothing newer.

TYPE: bool DEFAULT: False

RAISES DESCRIPTION
LegacyTlsUnavailableError

If legacy_tls is set and this host's OpenSSL refuses the configuration.

METHOD DESCRIPTION
probe

Make one plain TCP connection to the SoftAP and close it.

open

Connect to the SoftAP and complete the TLS handshake.

send_access_point

Write the credential message for target and flush it.

close

Close the connection; a no-op when it is not open.

ATTRIBUTE DESCRIPTION
address

The SoftAP address this connection talks to.

TYPE: str

port

The SoftAP port this connection talks to.

TYPE: int

Source code in src/lifx/onboard/softap.py
def __init__(
    self,
    address: str = SOFTAP_ADDRESS,
    port: int = SOFTAP_PORT,
    dial_timeout: float = 10.0,
    legacy_tls: bool = False,
) -> None:
    self._address = address
    self._port = port
    self._dial_timeout = dial_timeout
    self._legacy_tls = legacy_tls
    self._ssl_context = _build_ssl_context(legacy_tls)
    self._writer: asyncio.StreamWriter | None = None

Attributes

address property
address: str

The SoftAP address this connection talks to.

port property
port: int

The SoftAP port this connection talks to.

Methods:

probe async
probe(*, timeout: float | None = None) -> None

Make one plain TCP connection to the SoftAP and close it.

PARAMETER DESCRIPTION
timeout

Seconds to wait for the connection; unbounded when None.

TYPE: float | None DEFAULT: None

RAISES DESCRIPTION
SoftApUnreachableError

If the connection fails or timeout elapses first.

Source code in src/lifx/onboard/softap.py
async def probe(self, *, timeout: float | None = None) -> None:
    """Make one plain TCP connection to the SoftAP and close it.

    Args:
        timeout: Seconds to wait for the connection; unbounded when
            ``None``.

    Raises:
        SoftApUnreachableError: If the connection fails or ``timeout``
            elapses first.
    """
    try:
        _reader, writer = await asyncio.wait_for(
            asyncio.open_connection(
                self._address, self._port, family=socket.AF_INET
            ),
            timeout,
        )
    except (TimeoutError, OSError) as error:
        raise SoftApUnreachableError(
            f"No SoftAP reachable at {self._address}:{self._port}: "
            f"{type(error).__name__}"
        ) from error
    _LOGGER.debug("SoftAP at %s:%s accepted a TCP probe", self._address, self._port)
    writer.close()
    await _wait_closed_quietly(writer)
open async
open() -> None

Connect to the SoftAP and complete the TLS handshake.

RAISES DESCRIPTION
SoftApDialError

If the connection or handshake fails or dial_timeout elapses first.

Source code in src/lifx/onboard/softap.py
async def open(self) -> None:
    """Connect to the SoftAP and complete the TLS handshake.

    Raises:
        SoftApDialError: If the connection or handshake fails or
            ``dial_timeout`` elapses first.
    """
    try:
        _reader, writer = await asyncio.wait_for(
            asyncio.open_connection(
                self._address,
                self._port,
                ssl=self._ssl_context,
                family=socket.AF_INET,
            ),
            self._dial_timeout,
        )
    except (TimeoutError, OSError) as error:
        raise SoftApDialError(
            f"Could not dial SoftAP at {self._address}:{self._port} within "
            f"{self._dial_timeout}s: {type(error).__name__}"
        ) from error
    self._writer = writer
    _LOGGER.debug(
        "Dialed SoftAP at %s:%s over %s",
        self._address,
        self._port,
        writer.get_extra_info("ssl_object").version(),
    )
send_access_point async
send_access_point(target: Serial, network: HomeNetwork) -> None

Write the credential message for target and flush it.

RAISES DESCRIPTION
SoftApSendError

If the connection is not open or the write fails.

Source code in src/lifx/onboard/softap.py
async def send_access_point(self, target: Serial, network: HomeNetwork) -> None:
    """Write the credential message for ``target`` and flush it.

    Raises:
        SoftApSendError: If the connection is not open or the write fails.
    """
    if self._writer is None:
        raise SoftApSendError(
            f"SoftAP connection to {self._address}:{self._port} is not open"
        )
    message = build_access_point_message(target, network)
    try:
        self._writer.write(message)
        await self._writer.drain()
    except OSError as error:
        raise SoftApSendError(
            f"Could not send credentials to SoftAP at "
            f"{self._address}:{self._port}: {type(error).__name__}"
        ) from error
    _LOGGER.debug(
        "Sent %d-byte credential message for %s (SSID %r) to SoftAP at %s:%s",
        len(message),
        target,
        network.ssid,
        self._address,
        self._port,
    )
close async
close() -> None

Close the connection; a no-op when it is not open.

Source code in src/lifx/onboard/softap.py
async def close(self) -> None:
    """Close the connection; a no-op when it is not open."""
    writer, self._writer = self._writer, None
    if writer is None:
        return
    writer.close()
    await _wait_closed_quietly(writer)

build_access_point_message

build_access_point_message(
    target: Serial, network: HomeNetwork, *, source: int | None = None
) -> bytes

Build the 134-byte message that hands a device its home network.

The header is the standard LIFX frame: protocol 1024, addressable set, tagged unset, sequence 0, no acknowledgement or response requested, and the target set to the device's padded serial. The payload is packet 305.

PARAMETER DESCRIPTION
target

The serial of the device being onboarded.

TYPE: Serial

network

The network the device should join.

TYPE: HomeNetwork

source

Frame source; a fresh one is allocated when omitted.

TYPE: int | None DEFAULT: None

RETURNS DESCRIPTION
bytes

The complete header plus payload, ready to write to the SoftAP.

Source code in src/lifx/onboard/softap.py
def build_access_point_message(
    target: Serial, network: HomeNetwork, *, source: int | None = None
) -> bytes:
    """Build the 134-byte message that hands a device its home network.

    The header is the standard LIFX frame: protocol 1024, addressable set,
    tagged unset, sequence 0, no acknowledgement or response requested, and
    the target set to the device's padded serial. The payload is packet 305.

    Args:
        target: The serial of the device being onboarded.
        network: The network the device should join.
        source: Frame source; a fresh one is allocated when omitted.

    Returns:
        The complete header plus payload, ready to write to the SoftAP.
    """
    packet = Wifi.SetAccessPoint(
        interface=WifiInterface.STATION,
        ssid=network.ssid.encode("utf-8"),
        password=network.password.encode("utf-8"),
        security=WifiSecurity(network.security),
    )
    return create_message(
        packet,
        source=allocate_source() if source is None else source,
        target=target.to_protocol(),
        sequence=0,
        ack_required=False,
        res_required=False,
    )

SOFTAP_ADDRESS module-attribute

SOFTAP_ADDRESS = '172.16.0.1'

SOFTAP_PORT module-attribute

SOFTAP_PORT = 56700

Events

OnboardPhase

Bases: Enum

The phase of the onboarding sequence an event or error belongs to.

OnboardEvent dataclass

OnboardEvent(
    type: OnboardEventType,
    phase: OnboardPhase | None,
    serial: Serial | None = None,
    ssid: str | None = None,
    address: str | None = None,
    networks: tuple[SoftApNetwork, ...] = (),
    timeout: float | None = None,
    took: float | None = None,
    error: BaseException | None = None,
)

One step of progress through the onboarding sequence.

ATTRIBUTE DESCRIPTION
type

What happened.

TYPE: OnboardEventType

phase

The phase the event belongs to; None only when a failure has no phase.

TYPE: OnboardPhase | None

serial

The device being onboarded, once known.

TYPE: Serial | None

ssid

The network the event concerns (a SoftAP or a host network).

TYPE: str | None

address

The SoftAP address, for the wait and dial phases.

TYPE: str | None

networks

Every network the scan returned, for DISCOVERED.

TYPE: tuple[SoftApNetwork, ...]

timeout

The budget a phase started with, for the events that open one.

TYPE: float | None

took

Seconds a step took, for the events that close one.

TYPE: float | None

error

The failure, for FAILED.

TYPE: BaseException | None

OnboardEventType

Bases: Enum

What an :class:OnboardEvent reports.

OnboardEventQueue

OnboardEventQueue(maxsize: int = 256)

A bounded queue of :class:OnboardEvent that never blocks the producer.

When the queue is full the oldest event is dropped and :attr:dropped is incremented, the way DeviceWatcher bounds its event iterator. Iterate with async for; the loop ends once :meth:close has been called and every queued event has been consumed. The state machine never closes a queue it was handed, so one queue can serve several runs.

PARAMETER DESCRIPTION
maxsize

The most events held at once; at least 1.

TYPE: int DEFAULT: 256

METHOD DESCRIPTION
put

Queue event, dropping the oldest event first when full.

get_nowait

Pop the oldest queued event, or None if there is none.

close

End iteration once the queued events have been consumed.

ATTRIBUTE DESCRIPTION
dropped

Events dropped because the queue was full.

TYPE: int

Source code in src/lifx/onboard/events.py
def __init__(self, maxsize: int = 256) -> None:
    if maxsize < 1:
        raise ValueError("maxsize must be at least 1")
    self.maxsize = maxsize
    self._queue: deque[OnboardEvent] = deque()
    self._dropped = 0
    self._closed = False
    self._wakeup = asyncio.Event()

Attributes

dropped property
dropped: int

Events dropped because the queue was full.

Methods:

put
put(event: OnboardEvent) -> None

Queue event, dropping the oldest event first when full.

Source code in src/lifx/onboard/events.py
def put(self, event: OnboardEvent) -> None:
    """Queue ``event``, dropping the oldest event first when full."""
    if len(self._queue) >= self.maxsize:
        self._queue.popleft()
        self._dropped += 1
    self._queue.append(event)
    self._wakeup.set()
get_nowait
get_nowait() -> OnboardEvent | None

Pop the oldest queued event, or None if there is none.

Source code in src/lifx/onboard/events.py
def get_nowait(self) -> OnboardEvent | None:
    """Pop the oldest queued event, or ``None`` if there is none."""
    if self._queue:
        return self._queue.popleft()
    return None
close
close() -> None

End iteration once the queued events have been consumed.

Source code in src/lifx/onboard/events.py
def close(self) -> None:
    """End iteration once the queued events have been consumed."""
    self._closed = True
    self._wakeup.set()

Results

Result dataclass

Result(
    serial: Serial | None,
    verified: bool,
    took: float,
    phase: OnboardPhase | None = None,
    error: LifxOnboardError | None = None,
    host_network: str | None = None,
)

What one onboarding run achieved.

onboard() returns a Result on success and raises on failure; the raised error carries the same Result as its result attribute.

ATTRIBUTE DESCRIPTION
serial

The device onboarded, once known.

TYPE: Serial | None

verified

Whether the device was seen on the LAN afterwards.

TYPE: bool

took

Seconds the run took.

TYPE: float

phase

The phase that failed; None on success.

TYPE: OnboardPhase | None

error

The failure; None on success.

TYPE: LifxOnboardError | None

host_network

The network the host ended on: the SSID a successful rejoin() targeted, or the network a CurrentNetworkReporter saw the host land on through auto-join. None when the host never got back.

TYPE: str | None

Exceptions

Every exception derives from LifxOnboardError, which is a LifxError. Each carries the phase that failed and, once a run has started, the result that describes it. LifxOnboardError and each subclass below appear with the phase it normally reports.

LifxError
└── LifxOnboardError
    ├── MissingCredentialsError (also a ValueError)
    ├── InvalidSoftApTargetError   (no phase)
    ├── LegacyTlsUnavailableError  (no phase)
    ├── SoftApNotFoundError        (SCAN)
    ├── SoftApJoinError            (JOIN)
    ├── SoftApWaitTimeoutError     (WAIT)
    ├── HostLeftSoftApError        (WAIT)
    ├── SoftApUnreachableError     (DIAL)
    ├── SoftApDialError            (DIAL)
    ├── SoftApSendError            (CONFIGURE)
    ├── HostRejoinError            (REJOIN)
    └── VerifyTimeoutError         (VERIFY)

LifxOnboardError

LifxOnboardError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: LifxError

Base class for every error raised while onboarding a device.

Messages never contain the home network password.

ATTRIBUTE DESCRIPTION
phase

The phase that failed, when known.

result

The onboarding result describing the failure, when one exists.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(message)
    self.phase = phase
    self.result = result

MissingCredentialsError

MissingCredentialsError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: LifxOnboardError, ValueError

Raised when a secured home network is given without a password.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(message)
    self.phase = phase
    self.result = result

InvalidSoftApTargetError

InvalidSoftApTargetError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when a target is neither a SoftAP name, a serial nor a suffix.

It has no phase: the target is rejected before onboarding starts.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

LegacyTlsUnavailableError

LegacyTlsUnavailableError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when the host's OpenSSL refuses the TLS 1.0 legacy configuration.

The message includes ssl.OPENSSL_VERSION so the failure is attributed to the host rather than the device.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

SoftApNotFoundError

SoftApNotFoundError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when no matching LIFX SoftAP appears within the find timeout.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

SoftApJoinError

SoftApJoinError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when the host cannot join the SoftAP within the find timeout.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

SoftApWaitTimeoutError

SoftApWaitTimeoutError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when the SoftAP never accepts a TCP probe within the wait timeout.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

HostLeftSoftApError

HostLeftSoftApError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when the host is found on another network while waiting.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

SoftApUnreachableError

SoftApUnreachableError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when a plain TCP probe of the SoftAP address does not connect.

The message names the address and port; it never carries credentials.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

SoftApDialError

SoftApDialError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when the TCP connect or TLS handshake to the SoftAP fails.

The message names the address and port; it never carries credentials.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

SoftApSendError

SoftApSendError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when writing the credential message to the SoftAP fails.

The message names the address and port; it never carries credentials.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

HostRejoinError

HostRejoinError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when the host could not be returned to any rejoin target.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

VerifyTimeoutError

VerifyTimeoutError(
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
)

Bases: _PhasedOnboardError

Raised when the device is not seen on the LAN within the verify timeout.

Source code in src/lifx/onboard/errors.py
def __init__(
    self,
    message: str,
    *,
    phase: OnboardPhase | None = None,
    result: Result | None = None,
) -> None:
    super().__init__(
        message,
        phase=self.default_phase if phase is None else phase,
        result=result,
    )

Timing defaults

The defaults were tuned on hardware. Pass a different value to onboard() or bulk_onboard() only when you have measured a reason to.

FIND_TIMEOUT module-attribute

FIND_TIMEOUT = 30.0

FIND_POLL module-attribute

FIND_POLL = 2.0

WAIT_TIMEOUT module-attribute

WAIT_TIMEOUT = 30.0

WAIT_POLL module-attribute

WAIT_POLL = 1.0

DIAL_TIMEOUT module-attribute

DIAL_TIMEOUT = 10.0

REJOIN_TIMEOUT module-attribute

REJOIN_TIMEOUT = 30.0

REJOIN_POLL module-attribute

REJOIN_POLL = 2.0

AUTO_JOIN_WAIT module-attribute

AUTO_JOIN_WAIT = 10.0

VERIFY_TIMEOUT module-attribute

VERIFY_TIMEOUT = 60.0

VERIFY_POLL module-attribute

VERIFY_POLL = 1.0

SCAN_INTERVAL module-attribute

SCAN_INTERVAL = 2.0

Serial helpers

parse_serial

parse_serial(text: str | Serial) -> Serial

Turn a serial, a six-hex suffix or a Serial into a Serial.

Accepts twelve hex characters, or exactly six (the suffix, with the LIFX OUI prepended). :, - and space separators are ignored and case is not significant. A Serial is returned unchanged.

RAISES DESCRIPTION
ValueError

If the text is neither form.

TypeError

If text is not a string or Serial.

Source code in src/lifx/onboard/serials.py
def parse_serial(text: str | Serial) -> Serial:
    """Turn a serial, a six-hex suffix or a ``Serial`` into a ``Serial``.

    Accepts twelve hex characters, or exactly six (the suffix, with the LIFX
    OUI prepended). ``:``, ``-`` and space separators are ignored and case is
    not significant. A ``Serial`` is returned unchanged.

    Raises:
        ValueError: If the text is neither form.
        TypeError: If text is not a string or ``Serial``.
    """
    if isinstance(text, Serial):
        return text
    if not isinstance(text, str):  # type: ignore[reportUnnecessaryIsInstance]
        raise TypeError(f"Serial must be a string, got {type(text).__name__}")
    bare = text.translate(_SEPARATORS)
    if _FULL_PATTERN.fullmatch(bare):
        return Serial.from_string(bare)
    return Serial.from_suffix(bare)

serial_from_softap_ssid module-attribute

serial_from_softap_ssid = Serial.from_softap_ssid

LIFX_OUI module-attribute

LIFX_OUI = b'\xd0s\xd5'

Packet 305 types

WifiInterface and WifiSecurity are re-exported from lifx.onboard for convenience; the protocol layer defines them.

WifiInterface

Bases: IntEnum

Auto-generated enum.

WifiSecurity

Bases: IntEnum

Auto-generated enum.