diff --git a/adafruit_wiznet5k/adafruit_wiznet5k.py b/adafruit_wiznet5k/adafruit_wiznet5k.py index c3d8d41..f858d14 100644 --- a/adafruit_wiznet5k/adafruit_wiznet5k.py +++ b/adafruit_wiznet5k/adafruit_wiznet5k.py @@ -131,6 +131,7 @@ class WIZNET5K: # pylint: disable=too-many-public-methods """Interface for WIZNET5K module. + :param ~busio.SPI spi_bus: The SPI bus the Wiznet module is connected to. :param ~digitalio.DigitalInOut cs: Chip select pin. :param ~digitalio.DigitalInOut rst: Optional reset pin. @@ -139,7 +140,6 @@ class WIZNET5K: # pylint: disable=too-many-public-methods :param str hostname: The desired hostname, with optional {} to fill in MAC. :param int dhcp_timeout: Timeout in seconds for DHCP response. :param bool debug: Enable debugging output. - """ TCP_MODE = const(0x21) @@ -206,9 +206,9 @@ def set_dhcp(self, hostname=None, response_timeout=30): """Initializes the DHCP client and attempts to retrieve and set network configuration from the DHCP server. Returns 0 if DHCP configured, -1 otherwise. + :param str hostname: The desired hostname, with optional {} to fill in MAC. :param int response_timeout: Time to wait for server to return packet, in seconds. - """ if self._debug: print("* Initializing DHCP") @@ -290,8 +290,8 @@ def mac_address(self): @mac_address.setter def mac_address(self, address): """Sets the hardware MAC address. - :param tuple address: Hardware MAC address. + :param tuple address: Hardware MAC address. """ self.write(REG_SHAR, 0x04, address) @@ -311,8 +311,8 @@ def pretty_mac(self, mac): # pylint: disable=no-self-use, invalid-name def remote_ip(self, socket_num): """Returns the IP address of the host who sent the current incoming packet. - :param int socket num: Desired socket. + :param int socket num: Desired socket. """ if socket_num >= self.max_sockets: return self._pbuff @@ -441,15 +441,15 @@ def _read_mr(self): def _write_mr(self, data): """Writes to the mode register (MR). - :param int data: Data to write to the mode register. + :param int data: Data to write to the mode register. """ self.write(REG_MR, 0x04, data) def read(self, addr, callback, length=1, buffer=None): """Reads data from a register address. - :param int addr: Register address. + :param int addr: Register address. """ with self._device as bus_device: if self._chip_type == "w5500": @@ -471,11 +471,11 @@ def read(self, addr, callback, length=1, buffer=None): def write(self, addr, callback, data): """Write data to a register address. + :param int addr: Destination address. :param int callback: Callback reference. :param int data: Data to write, as an integer. :param bytearray data: Data to write, as a bytearray. - """ with self._device as bus_device: if self._chip_type == "w5500": @@ -602,9 +602,10 @@ def get_socket(self): def socket_listen(self, socket_num, port, conn_mode=SNMR_TCP): """Start listening on a socket (default TCP mode). - :parm int socket_num: socket number - :parm int port: port to listen on - :parm int conn_mode: connection mode SNMR_TCP (default) or SNMR_UDP + + :param int socket_num: socket number + :param int port: port to listen on + :param int conn_mode: connection mode SNMR_TCP (default) or SNMR_UDP """ assert self.link_status, "Ethernet cable disconnected!" if self._debug: @@ -631,7 +632,8 @@ def socket_listen(self, socket_num, port, conn_mode=SNMR_TCP): def socket_accept(self, socket_num): """Gets the dest IP and port from an incoming connection. Returns the next socket number so listening can continue - :parm int socket_num: socket number + + :param int socket_num: socket number """ dest_ip = self.remote_ip(socket_num) dest_port = self.remote_port(socket_num) @@ -704,7 +706,6 @@ def socket_disconnect(self, socket_num): def socket_read(self, socket_num, length): """Reads data from a socket into a buffer. Returns buffer. - """ assert self.link_status, "Ethernet cable disconnected!" assert socket_num <= self.max_sockets, "Provided socket exceeds max_sockets." @@ -840,17 +841,13 @@ def socket_write(self, socket_num, buffer, timeout=0): while ( self._read_socket(socket_num, REG_SNIR)[0] & SNIR_SEND_OK ) != SNIR_SEND_OK: - if ( - self.socket_status(socket_num)[0] - in ( - SNSR_SOCK_CLOSED, - SNSR_SOCK_TIME_WAIT, - SNSR_SOCK_FIN_WAIT, - SNSR_SOCK_CLOSE_WAIT, - SNSR_SOCK_CLOSING, - ) - or (timeout and time.monotonic() - stamp > timeout) - ): + if self.socket_status(socket_num)[0] in ( + SNSR_SOCK_CLOSED, + SNSR_SOCK_TIME_WAIT, + SNSR_SOCK_FIN_WAIT, + SNSR_SOCK_CLOSE_WAIT, + SNSR_SOCK_CLOSING, + ) or (timeout and time.monotonic() - stamp > timeout): # self.socket_close(socket_num) return 0 time.sleep(0.01) diff --git a/adafruit_wiznet5k/adafruit_wiznet5k_dhcp.py b/adafruit_wiznet5k/adafruit_wiznet5k_dhcp.py index e5c79ef..edb3e19 100644 --- a/adafruit_wiznet5k/adafruit_wiznet5k_dhcp.py +++ b/adafruit_wiznet5k/adafruit_wiznet5k_dhcp.py @@ -80,6 +80,7 @@ class DHCP: """W5k DHCP Client implementation. + :param eth: Wiznet 5k object :param list mac_address: Hardware MAC. :param str hostname: The desired hostname, with optional {} to fill in MAC. @@ -134,6 +135,7 @@ def __init__( # pylint: disable=too-many-statements def send_dhcp_message(self, state, time_elapsed, renew=False): """Assemble and send a DHCP message packet to a socket. + :param int state: DHCP Message state. :param float time_elapsed: Number of seconds elapsed since DHCP process started :param bool renew: Set True for renew and rebind @@ -470,14 +472,10 @@ def _dhcp_state_machine(self): if self._debug: print("* DHCP: Time to renew lease") - if ( - self._dhcp_state - in ( - STATE_DHCP_DISCOVER, - STATE_DHCP_REQUEST, - ) - and time.monotonic() > (self._start_time + self._response_timeout) - ): + if self._dhcp_state in ( + STATE_DHCP_DISCOVER, + STATE_DHCP_REQUEST, + ) and time.monotonic() > (self._start_time + self._response_timeout): self._dhcp_state = STATE_DHCP_WAIT if self._sock is not None: self._sock.close() diff --git a/adafruit_wiznet5k/adafruit_wiznet5k_dns.py b/adafruit_wiznet5k/adafruit_wiznet5k_dns.py index 84a8791..76ebb6f 100644 --- a/adafruit_wiznet5k/adafruit_wiznet5k_dns.py +++ b/adafruit_wiznet5k/adafruit_wiznet5k_dns.py @@ -58,6 +58,7 @@ def __init__(self, iface, dns_address, debug=False): def gethostbyname(self, hostname): """Translate a host name to IPv4 address format. + :param str hostname: Desired host name to connect to. Returns the IPv4 address as a bytearray if successful, -1 otherwise. diff --git a/adafruit_wiznet5k/adafruit_wiznet5k_ntp.py b/adafruit_wiznet5k/adafruit_wiznet5k_ntp.py index 132b468..9db23d2 100644 --- a/adafruit_wiznet5k/adafruit_wiznet5k_ntp.py +++ b/adafruit_wiznet5k/adafruit_wiznet5k_ntp.py @@ -3,7 +3,7 @@ # SPDX-License-Identifier: MIT """ -`wiznet5k_ntp` +`adafruit_wiznet5k_ntp` ================================================================================ Network Time Protocol (NTP) helper for CircuitPython @@ -27,6 +27,7 @@ class NTP: """ Wiznet5k NTP Client + :param iface: Wiznet 5k object :param str ntp_address: The hostname of the NTP server :param int utc: Numbers of hours to offset time from UTC @@ -50,6 +51,7 @@ def __init__(self, iface, ntp_address, utc, debug=False): def get_time(self): """ Get the time from the NTP server + :return: time in seconds since the epoch """ self._sock.bind((None, 50001)) diff --git a/adafruit_wiznet5k/adafruit_wiznet5k_socket.py b/adafruit_wiznet5k/adafruit_wiznet5k_socket.py index aa9bd16..8d80bbe 100644 --- a/adafruit_wiznet5k/adafruit_wiznet5k_socket.py +++ b/adafruit_wiznet5k/adafruit_wiznet5k_socket.py @@ -64,6 +64,7 @@ def getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0): def gethostbyname(hostname): """Translate a host name to IPv4 address format. The IPv4 address is returned as a string. + :param str hostname: Desired hostname. """ addr = _the_interface.get_host_by_name(hostname) @@ -73,6 +74,7 @@ def gethostbyname(hostname): def is_ipv4(host): """Checks if a host string is an IPv4 address. + :param str host: host's name or ip """ octets = host.split(".", 3) @@ -88,9 +90,9 @@ def is_ipv4(host): class socket: """A simplified implementation of the Python 'socket' class for connecting to a Wiznet5k module. + :param int family: Socket address (and protocol) family. :param int type: Socket type. - """ # pylint: disable=redefined-builtin,unused-argument @@ -162,8 +164,8 @@ def getpeername(self): def inet_aton(self, ip_string): """Convert an IPv4 address from dotted-quad string format. - :param str ip_string: IP Address, as a dotted-quad string. + :param str ip_string: IP Address, as a dotted-quad string. """ self._buffer = b"" self._buffer = [int(item) for item in ip_string.split(".")] @@ -173,6 +175,7 @@ def inet_aton(self, ip_string): def bind(self, address): """Bind the socket to the listen port, if host is specified the interface will be reconfigured to that IP. + :param tuple address: local socket as a (host, port) tuple. """ if address[0] is not None: @@ -191,6 +194,7 @@ def bind(self, address): def listen(self, backlog=None): """Listen on the port specified by bind. + :param backlog: For compatibility but ignored. """ assert self._listen_port is not None, "Use bind to set the port before listen!" @@ -228,6 +232,7 @@ def accept(self): def connect(self, address, conntype=None): """Connect to a remote socket at address. + :param tuple address: Remote socket as a (host, port) tuple. """ assert ( @@ -253,6 +258,7 @@ def connect(self, address, conntype=None): def send(self, data): """Send data to the socket. The socket must be connected to a remote socket. + :param bytearray data: Desired data to send to the socket. """ _the_interface.socket_write(self.socknum, data, self._timeout) @@ -261,6 +267,7 @@ def send(self, data): def sendto(self, data, address): """Send data to the socket. The socket must be connected to a remote socket. + :param bytearray data: Desired data to send to the socket. :param tuple address: Remote socket as a (host, port) tuple. """ @@ -269,6 +276,7 @@ def sendto(self, data, address): def recv(self, bufsize=0, flags=0): # pylint: disable=too-many-branches """Reads some bytes from the connected remote address. + :param int bufsize: Maximum number of bytes to receive. :param int flags: ignored, present for compatibility. """ @@ -327,9 +335,10 @@ def recv(self, bufsize=0, flags=0): # pylint: disable=too-many-branches def recvfrom(self, bufsize=0, flags=0): """Reads some bytes from the connected remote address. + :param int bufsize: Maximum number of bytes to receive. :param int flags: ignored, present for compatibility. - :returns: a tuple (bytes, address) where address is a tuple (ip, port) + :return: a tuple (bytes, address) where address is a tuple (ip, port) """ return ( self.recv(bufsize), @@ -341,10 +350,11 @@ def recvfrom(self, bufsize=0, flags=0): def recv_into(self, buf, nbytes=0, flags=0): """Reads some bytes from the connected remote address info the provided buffer. + :param bytearray buf: Data buffer :param nbytes: Maximum number of bytes to receive :param int flags: ignored, present for compatibility. - :returns: the number of bytes received + :return: the number of bytes received """ if nbytes == 0: nbytes = len(buf) @@ -355,10 +365,11 @@ def recv_into(self, buf, nbytes=0, flags=0): def recvfrom_into(self, buf, nbytes=0, flags=0): """Reads some bytes from the connected remote address info the provided buffer. + :param bytearray buf: Data buffer :param nbytes: Maximum number of bytes to receive :param int flags: ignored, present for compatibility. - :returns a tuple (nbytes, address) where address is a tuple (ip, port) + :return: a tuple (nbytes, address) where address is a tuple (ip, port) """ return ( self.recv_into(buf, nbytes), @@ -371,7 +382,6 @@ def recvfrom_into(self, buf, nbytes=0, flags=0): def readline(self): """Attempt to return as many bytes as we can up to \ but not including '\r\n'. - """ stamp = time.monotonic() while b"\r\n" not in self._buffer: @@ -407,8 +417,8 @@ def available(self): def settimeout(self, value): """Sets socket read timeout. - :param int value: Socket read timeout, in seconds. + :param int value: Socket read timeout, in seconds. """ if value < 0: raise Exception("Timeout period should be non-negative.") @@ -417,6 +427,5 @@ def settimeout(self, value): def gettimeout(self): """Return the timeout in seconds (float) associated with socket operations, or None if no timeout is set. - """ return self._timeout diff --git a/docs/api.rst b/docs/api.rst index bb95d51..d0d6694 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -12,3 +12,12 @@ .. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_dhcp :members: + +.. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_ntp + :members: + +.. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_dns + :members: + +.. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_wsgiserver + :members: