adafruit_wiznet5k

Pure-Python interface for WIZNET 5k ethernet modules.

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

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: List[int] | Tuple[int] = (222, 173, 190, 239, 254, 237), hostname: str | None = None, dhcp_timeout: float = 30.0, 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 Union[int, bytes]:

a 4 bytearray.

get_socket(*, reserve_socket=False) → int

Request, allocate and return a socket from the W5k 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 cancel_reservation() 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[bytearray, bytearray, bytearray, Tuple[int, int, int, int]]

Network configuration information.

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

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

property ip_address: bytearray

Configured IP address.

Return bytearray:

IP address as four bytes.

Physical hardware (PHY) connection status.

Return int:

1 if the link is up, 0 if the link is down.

property mac_address: bytearray

Ethernet hardware’s MAC address.

Return bytearray:

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.

pretty_ip(ip: bytearray) → str

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

Parameters:

ip (bytearray) – A four byte IP address.

Return str:

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

pretty_mac(mac: bytearray) → str

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

Parameters:

mac (bytearray) – The MAC address.

Return str:

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

read(addr: int, callback: int, length: int = 1, buffer: WriteableBuffer | None = None) → WriteableBuffer | bytearray

Read data from a register address.

Parameters:

  • addr (int) – Register address to read.

  • callback (int) – Callback reference.

  • length (int) – Number of bytes to read from the register, defaults to 1.

  • buffer (Optional[WriteableBuffer]) – Buffer to read data into, defaults to None.

Return Union[WriteableBuffer, bytearray]:

Data read from the chip.

read_snir(sock: int) → bytearray | None

Read Socket n Status Register.

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

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 Union[int, Tuple[int, Union[int, bytearray]]]:

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 -1 is returned.

static release_socket(socket_number)

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

Parameters:

socket_number (int) – The socket to release.

remote_ip(socket_num: int) → str | bytearray

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

Parameters:

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

Return Union[str, bytearray]:

A four byte IP address.

remote_port(socket_num: int) → int | bytearray

Port of the host which sent the current incoming packet.

Parameters:

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

Return Union[int, bytearray]:

The port number of the socket connection.

set_dhcp(hostname: str | None = None, response_timeout: float = 30) → int

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.

  • response_timeout (float) – Time to wait for server to return packet in seconds, defaults to 30.0.

Return int:

0 if DHCP configured, -1 otherwise.

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

Destination IP 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)).

If errors occur, the destination IP address and / or the destination port may be returned as bytearrays.

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.

socket_close(socket_num: int) → None

Close a socket.

Parameters:

socket_num (int) – The socket to close.

socket_connect(socket_num: int, dest: bytes | bytearray, port: int, conn_mode: int = 33) → int

Open and verify a connection from a socket to a destination IP 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 (Union[bytes, bytearray]) – The destination as a host name or IP address.

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

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

socket_disconnect(socket_num: int) → None

Disconnect a TCP or UDP connection.

Parameters:

socket_num (int) – The socket to close.

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.

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

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.

Return int:

1 if the socket was opened, 0 if not.

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

Read data from a TCP socket.

Parameters:

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

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

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

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 both items equal an error code, 0 for no data waiting and -1 for no connection to the socket.

socket_status(socket_num: int) → bytearray | None

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.

Returns:

Optional[bytearray]

socket_write(socket_num: int, buffer: bytearray, timeout: float = 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 buffer.

sw_reset() → int

Perform a soft-reset on the Wiznet chip.

Perform a soft reset by writing to the chip’s MR register reset bit.

Return int:

0 if the reset succeeds, -1 if not.

unpretty_ip(ip: str) → bytes

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

Parameters:

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

Return bytes:

IP address in four bytes.

write(addr: int, callback: int, data: int | Sequence[int | bytes]) → None

Write data to a register address.

Parameters:

  • addr (int) – Destination address.

  • callback (int) – Callback reference.

  • data (Union[int, Sequence[Union[int, bytes]]]) – Data to write to the register address.

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.

adafruit_wiznet5k_dhcp

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

  • Author(s): Jordan Terrell, Brent Rubell

class adafruit_wiznet5k.adafruit_wiznet5k_dhcp.DHCP(eth: WIZNET5K, mac_address: Sequence[int | bytes], hostname: str | None = None, response_timeout: float = 30.0, debug: bool = False)

W5k DHCP Client implementation.

maintain_dhcp_lease() → None

Maintain DHCP lease

parse_dhcp_response() → Tuple[int, bytearray]

Parse DHCP response from DHCP server.

Return Tuple[int, bytearray]:

DHCP packet type and ID.

request_dhcp_lease() → bool

Request to renew or acquire a DHCP lease.

send_dhcp_message(state: int, time_elapsed: float, renew: bool = False) → None

Assemble and send a DHCP message packet to a socket.

Parameters:

  • state (int) – DHCP Message state.

  • time_elapsed (float) – Number of seconds elapsed since DHCP process started

  • renew (bool) – Set True for renew and rebind, defaults to False

adafruit_wiznet5k_ntp

Network Time Protocol (NTP) helper for CircuitPython

  • Author(s): Brent Rubell, irinakim

Implementation Notes

Hardware: Software and Dependencies:

class adafruit_wiznet5k.adafruit_wiznet5k_ntp.NTP(iface: WIZNET5K, ntp_address: str, utc: float, debug: bool = False)

Wiznet5k NTP Client.

get_time() → struct_time

Get the time from the NTP server.

Return time.struct_time:

The local time.

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.