Wireless Profile Sync Settings Management Architecture

This document describes the architecture introduced by the wireless profile synchronization feature in Console. It lets an operator read and toggle two independent Intel® AMT wireless synchronization behaviors on a managed device without rewriting the whole WiFi port configuration:

• Local profile sync — whether the AMT firmware may synchronize WiFi profiles with the local host operating system.
• UEFI profile sync — whether WiFi profiles are shared with the platform UEFI/BIOS (pre-boot) WiFi stack, subject to hardware capability.

1. High-level architecture

Two systems are involved: Console (the management application) and the AMT Device (the managed endpoint). Console exposes a user-facing REST API on one side and talks to the device over WS-Management (WSMAN) on the other, using the Intel® AMT SDK semantics implemented by the go-wsman-messages library. Both sync toggles are driven through the single AMT_WiFiPortConfigurationService instance on the device.

flowchart LR
    Client[REST client] -->|GET / POST profileSync/:guid| ConsoleAPI[Console REST API]
    subgraph Console
        ConsoleAPI --> UseCase[Devices Use Case]
        UseCase --> WSMAN[wsman.Management adapter]
    end
    WSMAN -->|SOAP / XML over HTTPS| Svc
    subgraph Device[Intel® AMT Device]
        Svc[AMT_WiFiPortConfigurationService]
        Caps[AMT_BootCapabilities]
    end
    WSMAN -.UEFI gate.-> Caps

Loading

2. Console interfaces and data

2.1 User-facing API (north-bound)

Console exposes 2 endpoints for this feature, GET/POST.

• REST/JSON endpoints: internal/controller/httpapi/v1/devicemanagement.go
• handlers: internal/controller/httpapi/v1/wifiprofilesync.go
• payload/response types: internal/entity/dto/v1/wifiprofilesync.go

Method	Path	Payload	Handler	Success response
GET	/api/v1/amt/networkSettings/wireless/profileSync/:guid	N/A	getWirelessProfileSync	200 OK + { "localProfileSync": bool , "uefiProfileSync": bool, "uefiProfileSyncSupported": bool}
POST	/api/v1/amt/networkSettings/wireless/profileSync/:guid	WirelessProfileSyncRequest	setWirelessProfileSync	200 OK + { "localProfileSync": bool , "uefiProfileSync": bool, "uefiProfileSyncSupported": bool}

WirelessProfileSyncRequest fields:

Field (JSON)	Type	Binding tag	Validation note
localProfileSync	*bool	N/A	N/A
uefiProfileSync	*bool	N/A	N/A

The request type carries a pointer (*bool) so Console can distinguish "field absent" from false.

2.2 Device interface (south-bound) — Intel AMT SDK

Console talks to the device through the wsman.Management interface in internal/usecase/devices/wsman/interfaces.go, implemented by ConnectionEntry in internal/usecase/devices/wsman/message.go. Each method is a thin wrapper over a go-wsman-messages call. The operations relevant to this feature:

Method	Purpose	SDK / class
GetWiFiPorts()	enumerate/pull WiFi ports; returns ErrNoWiFiPort when none exist	CIM_WiFiPort
GetWiFiPortConfigurationService()	read the current WiFi port configuration service state	AMT_WiFiPortConfigurationService.Get
PutWiFiPortConfigurationService(req)	overwrite the WiFi port configuration service with a full request	AMT_WiFiPortConfigurationService.Put
GetPowerCapabilities()	read boot capabilities; used to gate UEFI sync	AMT_BootCapabilities

The Put requires a complete wifiportconfiguration.WiFiPortConfigurationServiceRequest. The use case never builds one from scratch: buildWiFiPortConfigRequest copies every field verbatim from the current WiFiPortConfigurationServiceResponse and overlays only the two sync-related fields, so unrelated firmware state is not clobbered.

AMT SDK request field	Source
RequestedState, EnabledState, HealthState, ElementName	Copied from current settings
SystemCreationClassName, SystemName, CreationClassName, Name	Copied from current settings
LastConnectedSsidUnderMeControl, NoHostCsmeSoftwarePolicy	Copied from current settings
LocalProfileSynchronizationEnabled	resolved from localProfileSync
UEFIWiFiProfileShareEnabled	resolved from uefiProfileSync

The local sync field is an enum, not a boolean. The use case maps between the REST boolean and the SDK enum:

localProfileSync	LocalProfileSynchronizationEnabled enum
true	LocalUserProfileSynchronizationEnabled (1)
false	LocalSyncDisabled (0)

isLocalProfileSyncEnabled performs the reverse mapping (true only when the state equals LocalUserProfileSynchronizationEnabled). The UEFI field (UEFIWiFiProfileShareEnabled) is already a boolean and maps directly.

3. Business logic layer (Devices Use Case)

Implemented in internal/usecase/devices/wifiprofilesync.go. All 2 use-case methods begin the same way: setupWirelessProfileManagement (shared with WiFi profile management) loads the device by GUID and opens a WSMAN client, then GetWiFiPorts() asserts the device actually has a WiFi interface — returning ErrNoWiFiPort (→ 404 Not Found) otherwise — before any configuration read or write.

GET flow — GetWirelessProfileSync read the current WiFiPortConfigurationService and project out the relevant fields:

sequenceDiagram
    participant C as REST client
    participant API as Console API
    participant UC as Devices Use Case
    participant W as wsman.Management
    participant D as AMT Device

    C->>API: GET profileSync/:guid
    API->>UC: GetWirelessProfileSync(guid)
    UC->>W: setup client + GetWiFiPorts()
    W->>D: Enumerate + Pull CIM_WiFiPort
    alt no WiFi interface
        W-->>UC: ErrNoWiFiPort
        UC-->>API: ErrNoWiFiPort
        API-->>C: 404 Not Found
    else WiFi interface present
        UC->>W: GetWiFiPortConfigurationService()
        W->>D: AMT_WiFiPortConfigurationService.Get
        D-->>W: service state
        UC->>W: GetPowerCapabilities()
        W->>D: AMT_BootCapabilities
        D-->>W: UEFIWiFiCoExistenceAndProfileShare
        UC->>UC: buildProfileSyncResponse
        UC-->>API: dto.WirelessProfileSyncResponse
        API-->>C: 200 OK + { "localProfileSync": bool,<br/>"uefiProfileSync": bool,<br/>"uefiProfileSyncSupported": bool }
    end

Loading

POST flow — SetWirelessProfileSync reads current state, compares it to the requested value, and only issues a Put when they differ (read-before-write). When no change is needed it returns the current value without touching the device:

sequenceDiagram
    participant C as REST client
    participant API as Console API
    participant UC as Devices Use Case
    participant W as wsman.Management
    participant D as AMT Device

    C->>API: POST profileSync/:guid<br/>{ "localProfileSync": true,<br/>"uefiProfileSync": false }
    API->>UC: SetWirelessProfileSync(guid, true)
    UC->>W: setup client + GetWiFiPorts()
    W->>D: Enumerate + Pull CIM_WiFiPort
    alt no WiFi interface
        W-->>UC: ErrNoWiFiPort
        UC-->>API: ErrNoWiFiPort
        API-->>C: 404 Not Found
    else WiFi interface present
        UC->>W: GetWiFiPortConfigurationService()
        W->>D: AMT_WiFiPortConfigurationService.Get
        D-->>W: current state
        UC->>W: GetPowerCapabilities()
        W->>D: AMT_BootCapabilities
        D-->>W: UEFIWiFiCoExistenceAndProfileShare
        alt current == requested
            UC->>UC: buildProfileSyncResponse(current, uefiSupported)
            UC-->>API: current value (no write)
        else current != requested
            UC->>UC: buildWiFiPortConfigRequest(current, localSyncState, uefiSyncState)
            UC->>W: PutWiFiPortConfigurationService(req)
            W->>D: AMT_WiFiPortConfigurationService.Put
            D-->>W: updated state
            UC->>UC: buildProfileSyncResponse(updatedResponse, uefiSupported)
            UC-->>API: updated value
        end
    API-->>C: 200 OK + { "localProfileSync": true,<br/>"uefiProfileSync": false,<br/>"uefiProfileSyncSupported": true }
    end

Loading

Other behaviors:

• Invalid payload — the payload is rejected at bind time and returned as 400 Bad Request.

4. Key files

Area	File
HTTP handlers	internal/controller/httpapi/v1/wifiprofilesync.go
Route registration	internal/controller/httpapi/v1/devicemanagement.go
OpenAPI / Fuego declaration	internal/controller/openapi/devicemanagement.go
DTOs (request/response)	internal/entity/dto/v1/wifiprofilesync.go
Use case (business logic)	internal/usecase/devices/wifiprofilesync.go
Shared WSMAN setup helper	internal/usecase/devices/wifiprofile.go
WS layer interface	internal/controller/ws/v1/interface.go
Use case interface	internal/usecase/devices/interfaces.go
WSMAN interface	internal/usecase/devices/wsman/interfaces.go
WSMAN adapter (SDK calls)	internal/usecase/devices/wsman/message.go
AMT SDK dependency	go-wsman-messages/v2 — amt/wifiportconfiguration, amt/boot
API collection	MPS Postman collection (console_mps_apis.postman_collection.json)
Handler tests	internal/controller/httpapi/v1/wifiprofilesync_test.go
DTO tests	internal/entity/dto/v1/wifiprofilesync_test.go
Use case tests	internal/usecase/devices/wifiprofilesync_test.go