feat(network): add Wake-on-LAN wake module (type: wol)

[Ulrond]

Closes #216.

What

Adds a network/wake controller for a device — Wake-on-LAN lives here, not in the power seam.

• framework/core/networkModules/wol.py (networkWol) — a single wake() verb that sends the WoL magic packet (6×0xFF + target MAC ×16) to broadcast:port.
• framework/core/networkControl.py (networkControlClass) — dispatches type: "wol", with the same retry behaviour (retryCount / retryDelay) as powerControl.
• Wired into deviceManager via a device network: block → exposed as dut.networkController; also surfaced on testControl as self.networkController.
• Standard-library only (socket) — no new dependencies.

network:
  type: "wol"
  mac: "aa:bb:cc:dd:ee:ff"
  broadcast: "255.255.255.255"   # optional - subnet broadcast for directed WoL
  port: 9                        # optional (7 or 9)

Usage in a suite is deliberately dead-simple:

control = dut.networkController
control.wake()

Why network, not power

Wake-on-LAN is a network (layer-2) action, not a power action: it sends a UDP magic packet, cannot power a device off, and supports none of the power-metering contract (getPowerLevel / getVoltageLevel / getCurrentLevel). Filing it under powerModules mislabelled it and left half the "power switch" contract inapplicable.

So it is re-homed onto a dedicated network controller that mirrors the existing device-controller pattern (remoteController / hdmiCECController / avSyncController). The problem it solves is unchanged: targets that aggressively deep-sleep drop their console when idle and can only be brought back by a magic packet; without this, runs against them need an out-of-band wake step before the session opens.

Behavioural note: waking is now an explicit dut.networkController.wake() rather than riding on powerControl.powerOn(). The seam is designed to grow (e.g. isReachable() / waitForOnline() as a natural companion to wake(); deviceClass.pingTest() already offers ICMP reachability).

Testing

• tests/networkControl_tests.py — builds networkControlClass from config and calls wake().
• Verified: magic packet is correct (102 bytes, 6×0xFF + MAC×16), wake() sends and was captured on loopback, missing / malformed MAC raise ValueError, unknown type is handled gracefully.
• End-to-end: a device network: block produces dut.networkController; powerControl(type:"wol") now correctly reports the type as unknown.
• Woke a real armv7 target on the same broadcast domain.

Docs

• AGENTS.md — directory tree, controller shortcut attributes, and a new §5.2 Network / wake modules (broadened §5 to "Power & Network Control").
• docs/modules/device_manager.md — networkController added to the deviceClass managed objects.

---

Note: the branch name (…power-module) predates the re-home; the code is a network module. First commit adds the initial (power-seam) cut; the second re-homes it to the network seam and reverts the power coupling.

[Copilot]

Pull request overview

Adds a new Wake-on-LAN (WoL) “power switch” implementation and wires it into the existing powerControlClass dispatch so RAFT can wake devices that are asleep/soft-off via a WoL magic packet.

Changes:

• Added powerWol module that constructs and sends a WoL magic packet to a configurable broadcast address/UDP port.
• Added type == "wol" dispatch branch in powerControlClass to instantiate the new module.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
framework/core/powerModules/wol.py	Implements WoL magic-packet creation and UDP broadcast send; includes wake-only semantics for powerOff()/reboot().
framework/core/powerControl.py	Adds import and type: "wol" dispatch branch to construct powerWol.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

[Ulrond]

Updated and ready for review. This revision re-homes Wake-on-LAN from the power seam onto a dedicated network/wake controller (networkControlClass, device network: block, dut.networkController.wake()), reverts the powerModules coupling, and is rebased on latest develop. Docs updated (AGENTS.md §5.2, device_manager.md). Usage is deliberately minimal:

dut.networkController.wake()

@TB-1993 could you take another look and approve when happy? Thanks 🙏

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

framework/core/networkControl.py:59

• If config['type'] is unknown, this constructor only logs an error and leaves self.networkModule as None. A subsequent wake() call will then raise AttributeError when it tries to access self.networkModule.wake. Also, assigning to a local named type shadows the Python built-in.

        self.networkModule = None
        type = config.get("type")
        if type == "wol":
            self.networkModule = networkWol(log, config.get("mac"), config.get("broadcast", "255.255.255.255"), config.get("port", 9))
        else:
            self.log.error("Network controller type [{}] unknown".format(type))

[TB-1993]

Should retries really come from the config. Not the test?

[Ulrond]

thank you read that wrong. This is coming from the config, config.get("retryCount", 1) it just has a default if the config isn't present.

the retry count is a system control not a test control, that's what I required, that would then mean that the hardware we're talking too has a specification, and if it doesn't meet that then it fails... And that's why it's setup this way.

It's not ok for a test to think it knows the specification of the hardware.

[TB-1993]

In this case the hardware is the DUT, right? If that's the case I would expect the retry count to be in the device_config.yml and the test to read it and pass it in at run time. I could be missing something though?

[Ulrond]

Addressed the mechanical review points in 1fc2e62:

• MAC validation now happens at construction (strip whitespace, require 12 hex digits) with a clear field-named ValueError, so a misconfigured MAC fails when the device is built rather than silently at wake() time (covers the non-hex / unclear-error comments).
• _magicPacket → _magic_packet for snake_case consistency; call site updated.
• wake() guards against no configured module (unknown type) → returns a clear error instead of an AttributeError on None.
• The stale comments referencing powerModules/wol.py / powerSwitch.type: "wol" / the old PR title relate to the pre-re-home version; the PR was re-framed to the network: seam (see the updated description).

Still open for a design decision (from @TB-1993's comments) before I change them:

1. Retry mechanism — should retries come from config or the test, and should this use the backoff library rather than the hand-rolled loop? (Also noted: the loop only retries on exceptions, but wake() returns False on send failure, so config retries don't currently fire.)
2. networkController scope — @TB-1993 envisioned this class as the place to interact with network switches (MAC/IP lookup, enable/disable ports, firewalls, …), with WoL as just one method. Happy to reshape it that way.
3. Automated test — replace the manual tests/networkControl_tests.py with a RAFTUnitTestCase so it runs under the suite.

I'll implement these once the direction is agreed.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

framework/core/networkControl.py:95

• networkRetry() currently stops after the first call regardless of the returned value (it only retries on exceptions). Since networkWol.wake() returns False on send errors (it does not raise), retryCount/retryDelay will never be applied for WoL failures. Update networkRetry() to treat a falsy return as a failure and keep retrying until attempts are exhausted.

        for x in range(self.retryCount+1):
            try:
                result = networkMethod()
                break
            except Exception as e:
                self.log.info(f"Could not perform {[networkMethod.__name__]}. Retry count: [{x}] of [{self.retryCount}], delay is [{self.retryDelay}]")
                if x == self.retryCount:
                    raise e
                self.utils.wait(self.retryDelay)
        return result

[Ulrond]

Follow-up on the design threads (39d0dd0):

• Retry — kept config-driven retryCount/retryDelay but no backoff library: a WoL magic packet either lands or it doesn't, so a fixed retry (try up to N times, fixed delay) is the right model, not exponential backoff. Fixed the real bug — networkRetry now retries on a failed send (falsy return), not only on exceptions, so the configured retries actually fire. If you'd rather retries be the test's responsibility entirely, happy to drop them — say the word.
• Automated test — tests/networkControl_tests.py is now a unittest.TestCase (packet correctness, MAC validation, loopback send, unknown-type guard, retry-count), runnable under python3 -m unittest.
• Broader networkController (@TB-1993's switch-interaction vision — MAC/IP lookup, port/firewall control) — tracked as follow-up Broaden networkController into a network-switch interaction class (follow-up to #217) #224 so this PR can land WoL-focused, then grow.

That should clear the outstanding threads bar the two intentional follow-ups. Let me know if the retry direction or anything else needs a different call.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

framework/core/networkControl.py:48

• self.name may be None when no name field is provided in the device network: block, which leads to confusing log messages like wake (None) / wake (None): no network module configured. Consider defaulting it similarly to powerControlClass so logs are informative out of the box (e.g. use mac or type).

        self.name = config.get("name")

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

framework/core/networkControl.py:60

• When the network: block is present but missing type, the log currently says Network controller type [None] unknown, which is ambiguous (missing vs unsupported). Handling the None case explicitly also lets self.name and subsequent wake(...) logs be clearer.

        type = config.get("type")
        if type == "wol":
            self.networkModule = networkWol(log, config.get("mac"), config.get("broadcast", "255.255.255.255"), config.get("port", 9))
        else:
            self.log.error("Network controller type [{}] unknown".format(type))