adafruit_esp32spi

CircuitPython driver library for using ESP32 as WiFi co-processor using SPI

  • Author(s): ladyada

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_esp32spi.adafruit_esp32spi.ESP_SPIcontrol(spi, cs_pin, ready_pin, reset_pin, gpio0_pin=None, *, debug=False)

A class that will talk to an ESP32 module programmed with special firmware that lets it act as a fast an efficient WiFi co-processor

MAC_address

A bytearray containing the MAC address of the ESP32

ap_listening

Returns if the ESP32 is in access point mode and is listening for connections

connect(secrets)

Connect to an access point using a secrets dictionary that contains a ‘ssid’ and ‘password’ entry

connect_AP(ssid, password, timeout_s=10)

Connect to an access point with given name and password. Will wait until specified timeout seconds and return on success or raise an exception on failure.

Parameters:
  • ssid – the SSID to connect to
  • passphrase – the password of the access point
  • timeout_s – number of seconds until we time out and fail to create AP
create_AP(ssid, password, channel=1, timeout=10)

Create an access point with the given name, password, and channel. Will wait until specified timeout seconds and return on success or raise an exception on failure.

Parameters:
  • ssid (str) – the SSID of the created Access Point. Must be less than 32 chars.
  • password (str) – the password of the created Access Point. Must be 8-63 chars.
  • channel (int) – channel of created Access Point (1 - 14).
  • timeout (int) – number of seconds until we time out and fail to create AP
firmware_version

A string of the firmware version on the ESP32

get_host_by_name(hostname)

Convert a hostname to a packed 4-byte IP address. Returns a 4 bytearray

get_scan_networks()

The results of the latest SSID scan. Returns a list of dictionaries with ‘ssid’, ‘rssi’ and ‘encryption’ entries, one for each AP found

get_socket()

Request a socket from the ESP32, will allocate and return a number that can then be passed to the other socket commands

get_time()

The current unix timestamp

ip_address

Our local IP address

is_connected

Whether the ESP32 is connected to an access point

network_data

A dictionary containing current connection details such as the ‘ip_addr’, ‘netmask’ and ‘gateway’

ping(dest, ttl=250)

Ping a destination IP address or hostname, with a max time-to-live (ttl). Returns a millisecond timing value

pretty_ip(ip)

Converts a bytearray IP address to a dotted-quad string for printing

reset()

Hard reset the ESP32 using the reset pin

rssi

The receiving signal strength indicator for the access point we’re connected to

scan_networks()

Scan for visible access points, returns a list of access point details. Returns a list of dictionaries with ‘ssid’, ‘rssi’ and ‘encryption’ entries, one for each AP found

server_state(socket_num)

Get the state of the ESP32’s internal reference server socket number

set_analog_write(pin, analog_value)

Set the analog output value of pin, using PWM.

Parameters:
  • pin (int) – ESP32 GPIO pin to write to.
  • value (float) – 0=off 1.0=full on
set_digital_write(pin, value)

Set the digital output value of pin.

Parameters:
  • pin (int) – ESP32 GPIO pin to write to.
  • value (bool) – Value for the pin.
set_esp_debug(enabled)

Enable/disable debug mode on the ESP32. Debug messages will be written to the ESP32’s UART.

set_pin_mode(pin, mode)

Set the io mode for a GPIO pin.

Parameters:
  • pin (int) – ESP32 GPIO pin to set.
  • value – direction for pin, digitalio.Direction or integer (0=input, 1=output).
socket_available(socket_num)

Determine how many bytes are waiting to be read on the socket

socket_close(socket_num)

Close a socket using the ESP32’s internal reference number

socket_connect(socket_num, dest, port, conn_mode=0)

Open and verify we connected a socket to a destination IP address or hostname using the ESP32’s internal reference number. By default we use ‘conn_mode’ TCP_MODE but can also use UDP_MODE or TLS_MODE (dest must be hostname for TLS_MODE!)

socket_connected(socket_num)

Test if a socket is connected to the destination, returns boolean true/false

socket_open(socket_num, dest, port, conn_mode=0)

Open a socket to a destination IP address or hostname using the ESP32’s internal reference number. By default we use ‘conn_mode’ TCP_MODE but can also use UDP_MODE or TLS_MODE (dest must be hostname for TLS_MODE!)

socket_read(socket_num, size)

Read up to ‘size’ bytes from the socket number. Returns a bytearray

socket_status(socket_num)

Get the socket connection status, can be SOCKET_CLOSED, SOCKET_LISTEN, SOCKET_SYN_SENT, SOCKET_SYN_RCVD, SOCKET_ESTABLISHED, SOCKET_FIN_WAIT_1, SOCKET_FIN_WAIT_2, SOCKET_CLOSE_WAIT, SOCKET_CLOSING, SOCKET_LAST_ACK, or SOCKET_TIME_WAIT

socket_write(socket_num, buffer)

Write the bytearray buffer to a socket

ssid

The name of the access point we’re connected to

start_scan_networks()

Begin a scan of visible access points. Follow up with a call to ‘get_scan_networks’ for response

start_server(port, socket_num, conn_mode=0, ip=None)

Opens a server on the specified port, using the ESP32’s internal reference number

status

The status of the ESP32 WiFi core. Can be WL_NO_SHIELD or WL_NO_MODULE (not found), WL_IDLE_STATUS, WL_NO_SSID_AVAIL, WL_SCAN_COMPLETED, WL_CONNECTED, WL_CONNECT_FAILED, WL_CONNECTION_LOST, WL_DISCONNECTED, WL_AP_LISTENING, WL_AP_CONNECTED, WL_AP_FAILED

unpretty_ip(ip)

Converts a dotted-quad string to a bytearray IP address

wifi_set_entenable()

Enables WPA2 Enterprise mode

wifi_set_entidentity(ident)

Sets the WPA2 Enterprise anonymous identity

wifi_set_entpassword(password)

Sets the desired WPA2 Enterprise password

wifi_set_entusername(username)

Sets the desired WPA2 Enterprise username

wifi_set_network(ssid)

Tells the ESP32 to set the access point to the given ssid

wifi_set_passphrase(ssid, passphrase)

Sets the desired access point ssid and passphrase

adafruit_esp32spi_socket

A socket compatible interface thru the ESP SPI command set

  • Author(s): ladyada
adafruit_esp32spi.adafruit_esp32spi_socket.getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0)

Given a hostname and a port name, return a ‘socket.getaddrinfo’ compatible list of tuples. Honestly, we ignore anything but host & port

adafruit_esp32spi.adafruit_esp32spi_socket.set_interface(iface)

Helper to set the global internet interface

class adafruit_esp32spi.adafruit_esp32spi_socket.socket(family=2, type=1, proto=0, fileno=None, socknum=None)

A simplified implementation of the Python ‘socket’ class, for connecting through an interface to a remote device

available()

Returns how many bytes of data are available to be read (up to the MAX_PACKET length)

close()

Close the socket, after reading whatever remains

connect(address, conntype=None)

Connect the socket to the ‘address’ (which can be 32bit packed IP or a hostname string). ‘conntype’ is an extra that may indicate SSL or not, depending on the underlying interface

connected()

Whether or not we are connected to the socket

read(size=0)

Read up to ‘size’ bytes from the socket, this may be buffered internally! If ‘size’ isnt specified, return everything in the buffer.

readline()

Attempt to return as many bytes as we can up to but not including ‘ ‘

settimeout(value)

Set the read timeout for sockets, if value is 0 it will block

socknum

The socket number

write(data)

Send some data to the socket