From 304f13a74ee5909321a67cf538d3a50d85de1e82 Mon Sep 17 00:00:00 2001 From: Jim Mussared Date: Mon, 4 Sep 2023 12:50:59 +1000 Subject: [PATCH] docs/library/network: Clarify network.hostname() behaviour. This must be called before the interface connects. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared --- docs/library/network.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/library/network.rst b/docs/library/network.rst index b13c84123c..a14d6192ea 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -171,8 +171,8 @@ The following are functions available in the network module. .. function:: hostname([name]) - Get or set the hostname that will identify this device on the network. It is - applied to all interfaces. + Get or set the hostname that will identify this device on the network. It will + be used by all interfaces. This hostname is used for: * Sending to the DHCP server in the client request. (If using DHCP) @@ -182,6 +182,12 @@ The following are functions available in the network module. If the function is called without parameters, it returns the current hostname. + A change in hostname is typically only applied during connection. For DHCP + this is because the hostname is part of the DHCP client request, and the + implementation of mDNS in most ports only initialises the hostname once + during connection. For this reason, you must set the hostname before + activating/connecting your network interfaces. + The default hostname is typically the name of the board. .. function:: phy_mode([mode])