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:
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: 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.
- 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 link_status: int
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.
- 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:
- Return Union[WriteableBuffer, bytearray]:
Data read from the chip.
- read_udp(socket_num: int, length: int) int | Tuple[int, int | bytearray]
Read UDP socket’s current message bytes.
- Parameters:
- 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.
- 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.
- 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.
- socket_disconnect(socket_num: int) None
Disconnect a TCP or UDP connection.
- Parameters:
socket_num (int) – The socket to close.
- socket_open(socket_num: int, conn_mode: int = 33) int
Open an IP socket.
The socket may connect via TCP or UDP protocols.
- socket_read(socket_num: int, length: int) Tuple[int, int | bytearray]
Read data from a TCP socket.
- Parameters:
- 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]
- 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.
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
- 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.
- parse_dhcp_response() Tuple[int, bytearray]
Parse DHCP response from DHCP server.
- Return Tuple[int, bytearray]:
DHCP packet type and ID.
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.
- 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.