adafruit_wiznet5k

Pure-Python interface for WIZNET 5k ethernet modules.

  • Author(s): WIZnet, Arduino LLC, Bjoern Hartmann, Paul Stoffregen, Brent Rubell, Patrick Van Oosterwijck, Martin Stephens

Implementation Notes

Software and Dependencies:

class adafruit_wiznet5k.adafruit_wiznet5k.WIZNET5K(spi_bus: busio.SPI, cs: digitalio.DigitalInOut, reset: digitalio.DigitalInOut | None = None, is_dhcp: bool = True, mac: MacAddressRaw | str = 'DE:AD:BE:EF:FE:ED', hostname: str | None = None, debug: bool = False)

Interface for WIZNET5K module.

property chip: str

Ethernet controller chip type.

Return str:

The chip type.

get_host_by_name(hostname: str) → bytes

Convert a hostname to a packed 4-byte IP Address.

Parameters:

hostname (str) – The host name to be converted.

Return bytes:

The IPv4 address as a 4 byte array.

Raises:

RuntimeError – If the DNS lookup fails.

get_socket(*, reserve_socket=False) → int

Request, allocate and return a socket from the WIZnet 5k chip.

Cycle through the sockets to find the first available one. If the called with reserve_socket=True, update the list of reserved sockets (intended to be used with socket.socket()). Note that reserved sockets must be released by calling release_socket() once they are no longer needed.

If all sockets are reserved, no sockets are available for DNS calls, etc. Therefore, one socket cannot be reserved. Since socket 0 is the only socket that is capable of operating in MacRAW mode, it is the non-reservable socket.

Parameters:

reserve_socket (bool) – Whether to reserve the socket.

Returns int:

The first available socket.

Raises:

RuntimeError – If no socket is available.

property ifconfig: Tuple[bytes, bytes, bytes, bytes]

Network configuration information.

Return Tuple[bytes, bytes, bytes, bytes]:

The IP address, subnet mask, gateway address and DNS server address.

property ip_address: bytes

Configured IP address for the WIZnet Ethernet hardware.

Return bytes:

IP address as four bytes.

Physical hardware (PHY) connection status.

Whether the WIZnet hardware is physically connected to an Ethernet network.

Return bool:

True if the link is up, False if the link is down.

property mac_address: bytes

The WIZnet Ethernet hardware MAC address.

Return bytes:

Six byte MAC address.

maintain_dhcp_lease() → None

Maintain the DHCP lease.

property max_sockets: int

Maximum number of sockets supported by chip.

Return int:

Maximum supported sockets.

static pretty_ip(ipv4: bytes) → str

Convert a 4 byte IP address to a dotted-quad string for printing.

Parameters:

ipv4 (bytearray) – A four byte IP address.

Return str:

The IP address (a string of the form ‘255.255.255.255’).

Raises:

ValueError – If IP address is not 4 bytes.

static pretty_mac(mac: bytes) → str

Convert a bytes MAC address to a ‘:’ seperated string for display.

Parameters:

mac (bytes) – The MAC address.

Return str:

Mac Address in the form 00:00:00:00:00:00

Raises:

ValueError – If MAC address is not 6 bytes.

property rcr: int

Retry count register.

read_snir(sock: int) → int

Read Socket n Interrupt Register.

read_udp(socket_num: int, length: int) → Tuple[int, bytes]

Read UDP socket’s current message bytes.

Parameters:

  • socket_num (int) – The socket to read data from.

  • length (int) – The number of bytes to read from the socket.

Return Tuple[int, bytes]:

If the read was successful then the first item of the tuple is the length of the data and the second is the data. If the read was unsuccessful then (0, b””) is returned.

Raises:

ValueError – If the socket number is out of range.

release_socket(socket_number)

Update the socket reservation list when a socket is no longer reserved.

Parameters:

socket_number (int) – The socket to release.

Raises:

ValueError – If the socket number is out of range.

remote_ip(socket_num: int) → str

IP address of the host which sent the current incoming packet.

Parameters:

socket_num (int) – ID number of the socket to check.

Return str:

The IPv4 address.

Raises:

ValueError – If the socket number is out of range.

remote_port(socket_num: int) → int

Port number of the host which sent the current incoming packet.

Parameters:

socket_num (int) – ID number of the socket to check.

Return int:

The incoming port number of the socket connection.

Raises:

ValueError – If the socket number is out of range.

property rtr: int

Retry time register.

set_dhcp(hostname: str | None = None) → None

Initialize the DHCP client and attempt to retrieve and set network configuration from the DHCP server.

Parameters:

hostname (Optional[str]) – The desired hostname for the DHCP server with optional {} to fill in the MAC address, defaults to None.

Raises:

RuntimeError – If DHCP lease cannot be established.

socket_accept(socket_num: int) → Tuple[int, Tuple[str, int]]

Destination IPv4 address and port from an incoming connection.

Return the next socket number so listening can continue, along with the IP address and port of the incoming connection.

Parameters:

socket_num (int) – Socket number with connection to check.

Return Tuple[int, Tuple[Union[str, bytearray], Union[int, bytearray]]]:

If successful, the next (socket number, (destination IP address, destination port)).

Raises:

ValueError – If the socket number is out of range.

socket_available(socket_num: int, sock_type: int = 33) → int

Number of bytes available to be read from the socket.

Parameters:

  • socket_num (int) – Socket to check for available bytes.

  • sock_type (int) – Socket type. Use SNMR_TCP for TCP or SNMR_UDP for UDP, defaults to SNMR_TCP.

Return int:

Number of bytes available to read.

Raises:

  • ValueError – If the socket number is out of range.

  • ValueError – If the number of bytes on a UDP socket is negative.

socket_close(socket_num: int) → None

Close a socket.

Parameters:

socket_num (int) – The socket to close.

Raises:

ValueError – If the socket number is out of range.

socket_connect(socket_num: int, dest: IpAddress4Raw, port: int, conn_mode: int = 33) → int

Open and verify a connection from a socket to a destination IPv4 address or hostname. A TCP connection is made by default. A UDP connection can also be made.

Parameters:

  • socket_num (int) – ID of the socket to be connected.

  • dest (IpAddress4Raw) – The destination as a host name or IP address.

  • port (int) – Port to connect to (0 - 65,535).

  • conn_mode (int) – The connection mode. Use SNMR_TCP for TCP or SNMR_UDP for UDP, defaults to SNMR_TCP.

Raises:

  • ValueError – if the socket number is out of range.

  • ConnectionError – If the connection to the socket cannot be established.

socket_disconnect(socket_num: int) → None

Disconnect a TCP or UDP connection.

Parameters:

socket_num (int) – The socket to close.

Raises:

ValueError – If the socket number is out of range.

socket_listen(socket_num: int, port: int, conn_mode: int = 33) → None

Listen on a socket’s port.

Parameters:

  • socket_num (int) – ID of socket to listen on.

  • port (int) – Port to listen on (0 - 65,535).

  • conn_mode (int) – Connection mode SNMR_TCP for TCP or SNMR_UDP for UDP, defaults to SNMR_TCP.

Raises:
socket_open(socket_num: int, conn_mode: int = 33) → None

Open an IP socket.

The socket may connect via TCP or UDP protocols.

Parameters:

  • socket_num (int) – The socket number to open.

  • conn_mode (int) – The protocol to use. Use SNMR_TCP for TCP or SNMR_UDP for UDP, defaults to SNMR_TCP.

Raises:

  • ValueError – If the socket number is out of range.

  • ConnectionError – If the Ethernet link is down or no connection to socket.

  • RuntimeError – If unable to open a socket in UDP or TCP mode.

socket_read(socket_num: int, length: int) → Tuple[int, bytes]

Read data from a hardware socket. Called directly by TCP socket objects and via read_udp() for UDP socket objects.

Parameters:

  • socket_num (int) – The socket to read data from.

  • length (int) – The number of bytes to read from the socket.

Returns Tuple[int, bytes]:

If the read was successful then the first item of the tuple is the length of the data and the second is the data. If the read was unsuccessful then 0, b”” is returned.

Raises:
socket_status(socket_num: int) → int

Socket connection status.

Can be: SNSR_SOCK_CLOSED, SNSR_SOCK_INIT, SNSR_SOCK_LISTEN, SNSR_SOCK_SYNSENT, SNSR_SOCK_SYNRECV, SNSR_SYN_SOCK_ESTABLISHED, SNSR_SOCK_FIN_WAIT, SNSR_SOCK_CLOSING, SNSR_SOCK_TIME_WAIT, SNSR_SOCK_CLOSE_WAIT, SNSR_LAST_ACK, SNSR_SOCK_UDP, SNSR_SOCK_IPRAW, SNSR_SOCK_MACRAW, SNSR_SOCK_PPOE.

Parameters:

socket_num (int) – ID of socket to check.

Return int:

The connection status.

socket_write(socket_num: int, buffer: bytearray, timeout: float = 0.0) → int

Write data to a socket.

Parameters:

  • socket_num (int) – The socket to write to.

  • buffer (bytearray) – The data to write to the socket.

  • timeout (float) – Write data timeout in seconds, defaults to 0.0 which waits indefinitely.

Return int:

The number of bytes written to the socket.

Raises:
sw_reset() → None

Soft reset and reinitialize the WIZnet chip.

Raises:

RuntimeError – If reset fails.

static unpretty_ip(ipv4: str) → bytes

Convert a dotted-quad string to a four byte IP address.

Parameters:

ipv4 (str) – IPv4 address (a string of the form ‘255.255.255.255’) to be converted.

Return bytes:

IPv4 address in four bytes.

Raises:

ValueError – If IPv4 address is not 4 bytes.

write_snir(sock: int, data: int) → None

Write to Socket n Interrupt Register.

adafruit_wiznet5k_socket

A socket compatible interface with the Wiznet5k module.

  • Author(s): ladyada, Brent Rubell, Patrick Van Oosterwijck, Adam Cummick, Martin Stephens

adafruit_wiznet5k.adafruit_wiznet5k_socket.getaddrinfo(host: str, port: int, family: int = 0, type: int = 0, proto: int = 0, flags: int = 0) → List[Tuple[int, int, int, str, Tuple[str, int]]]

Translate the host/port argument into a sequence of 5-tuples that contain all the necessary arguments for creating a socket connected to that service.

Parameters:

  • host (str) – a domain name, a string representation of an IPv4 address or None.

  • port (int) – Port number to connect to (0 - 65536).

  • family (int) – Ignored and hardcoded as 0x03 (the only family implemented) by the function.

  • type (int) – The type of socket, either SOCK_STREAM (0x21) for TCP or SOCK_DGRAM (0x02) for UDP, defaults to 0.

  • proto (int) – Unused in this implementation of socket.

  • flags (int) – Unused in this implementation of socket.

Return List[Tuple[int, int, int, str, Tuple[str, int]]]:

Address info entries in the form (family, type, proto, canonname, sockaddr). In these tuples, family, type, proto are meant to be passed to the socket() function. canonname will always be an empty string, sockaddr is a tuple describing a socket address, whose format is (address, port), and is meant to be passed to the socket.connect() method.

adafruit_wiznet5k.adafruit_wiznet5k_socket.getdefaulttimeout() → float | None

Return the default timeout in seconds for new socket objects. A value of None indicates that new socket objects have no timeout. When the socket module is first imported, the default is None.

adafruit_wiznet5k.adafruit_wiznet5k_socket.gethostbyname(hostname: str) → str

Translate a host name to IPv4 address format. The IPv4 address is returned as a string, such as ‘100.50.200.5’. If the host name is an IPv4 address itself it is returned unchanged.

Parameters:

hostname (str) – Hostname to lookup.

Return str:

IPv4 address (a string of the form ‘0.0.0.0’).

adafruit_wiznet5k.adafruit_wiznet5k_socket.htonl(x: int) → int

Convert 32-bit positive integer from host to network byte order.

Parameters:

x (int) – 32-bit positive integer from host.

Return int:

32-bit positive integer in network byte order.

adafruit_wiznet5k.adafruit_wiznet5k_socket.htons(x: int) → int

Convert 16-bit positive integer from host to network byte order.

Parameters:

x (int) – 16-bit positive integer from host.

Return int:

16-bit positive integer in network byte order.

adafruit_wiznet5k.adafruit_wiznet5k_socket.inet_aton(ip_address: str) → bytes

Convert an IPv4 address from dotted-quad string format (for example, “123.45.67.89”) to 32-bit packed binary format, as a bytes object four characters in length. This is useful when conversing with a program that uses the standard C library and needs objects of type struct in_addr, which is the C type for the 32-bit packed binary this function returns.

Parameters:

ip_address (str) – The IPv4 address to convert.

Return bytes:

The converted IPv4 address.

adafruit_wiznet5k.adafruit_wiznet5k_socket.inet_ntoa(ip_address: bytes | bytearray) → str

Convert a 32-bit packed IPv4 address (a bytes-like object four bytes in length) to its standard dotted-quad string representation (for example, ‘123.45.67.89’). This is useful when conversing with a program that uses the standard C library and needs objects of type struct in_addr, which is the C type for the 32-bit packed binary data this function takes as an argument.

Parameters:

ip_address (Union[bytes, bytearray) – The IPv4 address to convert.

Return str:

The converted ip_address:

adafruit_wiznet5k.adafruit_wiznet5k_socket.set_interface(iface: WIZNET5K) → None

Helper to set the global internet interface.

Parameters:

iface (wiznet5k.adafruit_wiznet5k.WIZNET5K) – The ethernet interface.

adafruit_wiznet5k.adafruit_wiznet5k_socket.setdefaulttimeout(_timeout: float | None) → None

Set the default timeout in seconds (float) for new socket objects. When the socket module is first imported, the default is None. See settimeout() for possible values and their respective meanings.

Parameters:

_timeout (Optional[float]) – The default timeout in seconds or None.

class adafruit_wiznet5k.adafruit_wiznet5k_socket.socket(family: int = 3, type: int = 33, proto: int = 0, fileno: int | None = None)

A simplified implementation of the Python ‘socket’ class for connecting to a Wiznet5k module.

exception adafruit_wiznet5k.adafruit_wiznet5k_socket.timeout(msg)

TimeoutError class. An instance of this error will be raised by recv_into() if the timeout has elapsed and we haven’t received any data yet.

adafruit_wiznet5k_dhcp

Pure-Python implementation of Jordan Terrell’s DHCP library v0.3

  • Author(s): Jordan Terrell, Brent Rubell, Martin Stephens

class adafruit_wiznet5k.adafruit_wiznet5k_dhcp.DHCP(eth: WIZNET5K, mac_address: bytes, hostname: str | None = None, debug: bool = False)

Wiznet5k DHCP Client.

Implements a DHCP client using a finite state machine (FSM). This allows the DHCP client to run in a non-blocking mode suitable for CircuitPython.

The DHCP client obtains a lease and maintains it. The process of obtaining the initial lease is run in a blocking mode, as several messages must be exchanged with the DHCP server. Once the lease has been allocated, lease maintenance can be performed in non-blocking mode as nothing needs to be done until it is time to reallocate the lease. Renewing or rebinding is a simpler process which may be repeated periodically until successful. If the lease expires, the client attempts to obtain a new lease in blocking mode when the maintenance routine is run.

These class methods are not designed to be called directly. They should be called via methods in the WIZNET5K class.

Since DHCP uses UDP, messages may be lost. The DHCP protocol uses exponential backoff for retrying. Retries occur after 4, 8, and 16 +/- 1 seconds (the final retry is followed by a wait of 32 seconds) so it takes about a minute to decide that no DHCP server is available.

The DHCP client cannot check whether the allocated IP address is already in use because the ARP protocol is not available. Therefore, it is possible that the IP address allocated by the server has been manually assigned to another device. In most cases, the DHCP server will make this check before allocating an address, but some do not.

The DHCPRELEASE message is not implemented. The DHCP protocol does not require it and DHCP servers can handle disappearing clients and clients that ask for ‘replacement’ IP addresses.

maintain_dhcp_lease(blocking: bool = False) → None

Maintain a DHCP lease. :param bool blocking: Run the DHCP FSM in non-blocking mode.

request_dhcp_lease() → bool

Request acquire a DHCP lease.

Returns bool:

A lease has been acquired.

adafruit_wiznet5k_dns

Pure-Python implementation of the Arduino DNS client for WIZnet 5k-based ethernet modules.

  • Author(s): MCQN Ltd, Brent Rubell, Martin Stephens

class adafruit_wiznet5k.adafruit_wiznet5k_dns.DNS(iface: WIZNET5K, dns_address: str | Tuple[int, int, int, int], debug: bool = False)

W5K DNS implementation.

gethostbyname(hostname: bytes) → int | bytes

DNS look up of a host name.

Parameters:

hostname (bytes) – Host name to connect to.

:return Union[int, bytes] The IPv4 address if successful, -1 otherwise.

adafruit_wiznet5k.adafruit_wiznet5k_dns.getrandbits(k) → x.  Generates an int with k random bits.

adafruit_wiznet5k_wsgiserver

A simple WSGI (Web Server Gateway Interface) server that interfaces with the W5500. Opens a listening port on the W5500 to listen for incoming HTTP Requests and Accepts an Application object that must be callable, which gets called whenever a new HTTP Request has been received.

The Application MUST accept 2 ordered parameters:

  1. environ object (incoming request data)

  2. start_response function. Must be called before the Application

    callable returns, in order to set the response status and headers.

The Application MUST return strings in a list, which is the response data

Requires update_poll being called in the applications main event loop.

For more details about Python WSGI see: https://www.python.org/dev/peps/pep-0333/

  • Author(s): Matt Costi, Patrick Van Oosterwijck

class adafruit_wiznet5k.adafruit_wiznet5k_wsgiserver.WSGIServer(port: int = 80, debug: bool = False, application: callable | None = None)

A simple server that implements the WSGI interface.

finish_response(result: str, client: socket) → None

Called after the application callable returns result data to respond with. Creates the HTTP Response payload from the response_headers and results data, and sends it back to client.

Parameters:

  • result (str) – the data string to send back in the response to the client.

  • client (socket.socket) – the socket to send the response to.

start() → None

Start the server and listen for incoming connections.

Call update_poll in the main loop for the application callable to be invoked on receiving an incoming request.

update_poll() → None

Check for new incoming client requests.

Call this method inside your main event loop to get the server check for new incoming client requests. When a request comes in, the application callable will be invoked.

adafruit_wiznet5k.adafruit_wiznet5k_wsgiserver.set_interface(iface: WIZNET5K) → None

Helper to set the global internet interface.

Parameters:

wiznet5k.adafruit_wiznet5k.WIZNET5K – Ethernet interface.