Add Powerline hint to username field description

[iluebbe]

What it does

Adds a note to the username field description in the Fritz integration config flow, mentioning that FRITZ!Powerline devices don't have a username and any value can be entered.

Why

FRITZ!Powerline devices (e.g. 1240E) only support password-based authentication — they have no username concept and accept any value in the username field. When these devices appear via SSDP auto-discovery, users see the config form with a required username field and don't know what to enter.

As discussed with @chemelli74 and @mib1185, a documentation update + a short hint in the data_description is the right approach.

Changes

• strings.json: Update data_description_username to mention Powerline devices

Type of change

• Bugfix (non-breaking change which fixes an issue)

Checklist

• The code change is tested and works locally
• There is no commented out code in this PR

Related to #79343

[home-assistant]

Hi @iluebbe

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[home-assistant]

Hey there @AaronDavidSchneider, @chemelli74, @mib1185, mind taking a look at this pull request as it has been labeled with an integration (fritz) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of fritz can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign fritz Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component, problem in config, problem in device, feature-request) on the pull request.

[Copilot]

Pull request overview

This PR makes the username field optional in the Fritz integration to support FRITZ!Powerline devices, which only support password-based authentication. The underlying fritzconnection library already supports password-only authentication when user=None is passed, automatically retrieving the last logged-in username.

Changes:

• Made username optional in all config flow steps (user, confirm, reauth) by changing from vol.Required to vol.Optional(default="") and using defensive .get() access
• Updated FritzConnection initialization to convert empty username to None to trigger automatic username resolution
• Added comprehensive test coverage for Powerline devices including user flow, SSDP discovery, reauth, and auth error scenarios
• Updated documentation strings to mention Powerline device support

Reviewed changes

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

Show a summary per file

File	Description
homeassistant/components/fritz/config_flow.py	Made username optional in all form steps and added proper defensive access with .get() method
homeassistant/components/fritz/coordinator.py	Pass user=self.username or None to convert empty string to None for automatic username resolution
homeassistant/components/fritz/init.py	Use defensive .get() access when reading username from stored config entries
homeassistant/components/fritz/strings.json	Updated username field description to document Powerline support
tests/components/fritz/test_config_flow.py	Added test cases for Powerline device flows (user, SSDP, reauth, auth error)
tests/components/fritz/const.py	Added MOCK_USER_INPUT_POWERLINE constant for test cases

Stale

[chemelli74]

Hi @iluebbe , your code was clearly written by AI.

And there are some inconsistencies.
As you say, the original library works with user=None, but the description states that it also works with "" and "admin". So, which is the correct version?

Please test all values and report back.

[iluebbe]

Hi @chemelli74, thanks for looking at this!

I tested all cases against a real FRITZ!Powerline 1240E (fritzconnection 1.15.1):

With correct password:

user=	Connect	DeviceInfo	Result
None	OK	OK	✅
""	OK	OK	✅
"admin"	OK	OK	✅
"nonsense"	OK	OK	✅

Without password / wrong password:

user=	Result
None	FritzAuthorizationError ✅
""	FritzAuthorizationError ✅
"admin"	FritzAuthorizationError ✅

The Powerline ignores the username entirely — it only validates the password.

Why user=None in the code:

Looking at fritzconnection's source, user=None triggers the default fallback (line 72-73 in fritzconnection.py):

if user is None:
    user = os.getenv(FRITZ_ENV_USERNAME, FRITZ_USERNAME)  # -> 'dslf-config'

While user="" skips this and passes an empty string directly to HTTPDigestAuth("", password).

Both work for Powerline (since it ignores the username), but user=None is cleaner because it uses fritzconnection's intended fallback path.

Our code path: vol.Optional(default="") → self._username = "" → FritzConnection(user="" or None) → FritzConnection(user=None).

Why this PR is needed:

The current vol.Required(CONF_USERNAME) causes the HA frontend to show the username as a required field and block form submission when left empty. Users setting up a Powerline device don't know what username to enter since the device has no username concept. Making it vol.Optional allows them to leave it empty.

[chemelli74]

Honestly, I would rather update the documentation (https://www.home-assistant.io/integrations/fritz/#username) than modify the code.
Most users will use the Fritz integration to configure a router, and making a required field optional seems wrong to me.

[iluebbe]

@chemelli74 fair point — I agree that making the field optional could confuse router users.

How about a compromise:

1. Update the documentation as you suggest
2. Update data_description for the username field in strings.json to mention Powerline — something like: "Username for the FRITZ!Box. For FRITZ!Powerline devices, enter any value (the device ignores the username)."

This is a strings-only change, no schema modification. The vol.Required stays.

The reason I'd like at least the hint in the config flow: Powerline devices appear via SSDP auto-discovery, so users see the config form without necessarily reading the docs first. A short hint in the field description would prevent confusion.

I'm happy to update the PR accordingly if you agree with this approach.

[chemelli74]

@chemelli74 fair point — I agree that making the field optional could confuse router users.

How about a compromise:

1. Update the documentation as you suggest

Please go ahead

2. Update data_description for the username field in strings.json to mention Powerline — something like: "Username for the FRITZ!Box. For FRITZ!Powerline devices, enter any value (the device ignores the username)."

Maybe we can just have a default here like "admin". What you think @mib1185 ?

[chemelli74]

We are evaluating another approach

[mib1185]

I agree with @chemelli74 we shouldn't make the user name field optional, as it isn't for the majority of the devices. Further I would not set a default user admin as we suggest in the documentation to create a dedicated user, so adding admin as default would be contrary. The documentation of FRITZ! indicates, when the powerline repeater is connected with a FRITZ!Mesh you can use the username and password from the mesh master to log into the powerline repeater, else you have to set a dedicated password, without any username.
So I would suggest, that we just mention this "edge case" in the docs and add a short note to the data description in the strings.json

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[chemelli74]

Suggested change

	"data_description_username": "Username for the FRITZ!Box. FRITZ!Powerline devices do not require a username; enter any value.",
	"data_description_username": "Username for the FRITZ!Box. FRITZ!Powerline devices accept any value.",

[NoRi2909]

That sounds OK to me. If technically correct we could also write "Username for the FRITZ!Box. FRITZ!Powerline devices ignore this information and accept any value."

[chemelli74]

@NoRi2909 can you check if wording makes sense for you please ?

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

[chemelli74]

@iluebbe looking for documentation PR as well ;-)