network

NetworkManager: connectivity, Wi-Fi and wired state, scanned access points and join progress.

text {
    content = mantle.network:map(function(network)
        if not network.connected then
            return "offline"
        elseif network.ssid == "Ethernet" then
            return "wired"
        end
        local wifi = network.wifi_devices[1] -- the primary interface
        return string.format("%s %d%%", network.ssid or "", wifi and wifi.strength or 0)
    end, ""),
}

State

mantle.network:get() returns NetworkState, nil before the first push. A field marked ? may be absent.

mantle.network’s payload.

AccessPointInfo

One scanned network in available_networks.

JoinError

A failed join, as connect_error.

VpnError

A failed VPN activation, as vpn_error.

VpnInfo

One saved NetworkManager VPN profile in vpns.

VpnKind

vpns[].kind.

VpnSecretRequest

NetworkManager asking for VPN secrets, as vpn_secret.

WifiDeviceInfo

One Wi-Fi interface, with its own scan, join, address and access points. connected means activated here, while the flat connected means a default route; ssid never uses "Ethernet".

Actions

Call each as mantle.network:<action>(arguments...); ? marks an argument you may omit.

Backend

Use scan_device(id), connect_device(ssid, hidden, id) and disconnect_wifi_device(id) to target an entry in wifi_devices. An unknown or removed ID is never switched to another device: all three log a warning and return. Without Wi-Fi hardware, scan and disconnect_wifi do nothing; connect reports an error in the flat connect_error field. A password prompt keeps its selected device through submission and activation. Only one password prompt or join attempt is tracked across all devices. Starting another settles the previous join first.

How do I…

Ask for a Wi-Fi password

A click on an available_networks entry of a wifi_devices interface calls mantle.network:connect(entry.ssid, false); a secured one without a saved profile then sets password_ssid. Show the field while it is set. Escape clears a secure field and keeps it armed, then calls its on_cancel, the place to call cancel_connect:

local asking = mantle.network:map(function(network)
    return network.password_ssid ~= nil
end, false)

return column {
    visible = asking,
    spacing = 6,
    children = {
        text {
            content = mantle.network:map(function(network)
                return network.password_ssid and ("Password for " .. network.password_ssid) or ""
            end, ""),
        },
        textfield {
            width = 240,
            height = 24,
            placeholder = "Password",
            secure_submit = { capability = "network", action = "connect" },
            on_cancel = function() mantle.network:cancel_connect() end,
        },
    },
}

List and toggle a VPN

Which profile counts as the preferred one is the shell’s call; vpns carries what it needs:

local vpns = mantle.network:map(function(network) return network.vpns or {} end, {})

return column {
    spacing = 4,
    children = vpns:map(function(list)
        local rows = {}
        for _, vpn in ipairs(list) do
            rows[#rows + 1] = row {
                on_click = function()
                    if vpn.active or vpn.activating then
                        mantle.network:disconnect_vpn(vpn.uuid)
                    else
                        mantle.network:connect_vpn(vpn.uuid)
                    end
                end,
                children = { text { content = vpn.id .. (vpn.active and " (on)" or "") } },
            }
        end
        return rows
    end),
}

Ask for a VPN secret

NetworkManager’s request sets vpn_secret; show one secure field per entry of fields. cancel_vpn_secret drops the whole request, not one field, and fails the activation. Here a first Escape clears the field and a second cancels. retry is true after rejected secrets:

local request = mantle.network:map(function(network) return network.vpn_secret end)

return column {
    visible = request:map(function(secret) return secret ~= nil end),
    spacing = 6,
    children = request:map(function(secret)
        local rows = {}
        for _, field in ipairs(secret and secret.fields or {}) do
            rows[#rows + 1] = textfield {
                width = 240,
                height = 24,
                placeholder = field,
                secure_submit = { capability = "network", action = "vpn_secret", name = secret.id .. "/" .. field },
                on_cancel = function(cleared)
                    if not cleared then mantle.network:cancel_vpn_secret() end
                end,
            }
        end
        return rows
    end),
}

Know whether a join worked

A failed connect lands in connect_error:

text {
    foreground = "#F38BA8",
    content = mantle.network:map(function(network)
        local failure = network.connect_error
        return failure and (failure.ssid .. ": " .. failure.message) or ""
    end, ""),
}

Gotchas

Source: supervisor/src/capabilities/network/