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:
Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
Adafruit’s Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
- 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 = (222, 173, 190, 239, 254, 237), hostname: str | None = None, debug: bool = False)¶
Interface for WIZNET5K module.
- 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.
- property link_status: bool¶
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.
- 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.
- read_udp(socket_num: int, length: int) Tuple[int, bytes] ¶
Read UDP socket’s current message bytes.
- Parameters:
- 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.
- 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:
- 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:
- 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:
- Raises:
ValueError – If the socket number is out of range.
ConnectionError – If the Ethernet link is down.
RuntimeError – If unable to connect to a hardware socket.
- socket_open(socket_num: int, conn_mode: int = 33) None ¶
Open an IP socket.
The socket may connect via TCP or UDP protocols.
- Parameters:
- 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:
- 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:
ValueError – If the socket number is out of range.
ConnectionError – If the Ethernet link is down.
RuntimeError – If the socket connection has been lost.
- 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:
- Return int:
The number of bytes written to the socket.
- Raises:
ConnectionError – If the Ethernet link is down.
ValueError – If the socket number is out of range.
RuntimeError – If the data cannot be sent.
- 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.
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.
- 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, 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.
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.
- 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:
environ object (incoming request data)
- 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.