adafruit_espatcontrol.adafruit_espatcontrol

Use the ESP AT command sent to communicate with the Interwebs. Its slow, but works to get data into CircuitPython

Command set: https://www.espressif.com/sites/default/files/documentation/4a-esp8266_at_instruction_set_en.pdf

Examples: https://www.espressif.com/sites/default/files/documentation/4b-esp8266_at_command_examples_en.pdf

  • Author(s): ladyada

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_espatcontrol.adafruit_espatcontrol.ESP_ATcontrol(uart: UART, default_baudrate: int, *, run_baudrate: int | None = None, rts_pin: DigitalInOut | None = None, reset_pin: DigitalInOut | None = None, debug: bool = False, use_cipstatus: bool = False)

A wrapper for AT commands to a connected ESP8266 or ESP32 module to do some very basic internetting. The ESP module must be pre-programmed with AT command firmware, you can use esptool or our CircuitPython miniesptool to upload firmware

at_response(at_cmd: str, timeout: int = 5, retries: int = 3) bytes

Send an AT command, check that we got an OK response, and then cut out the reply lines to return. We can set a variable timeout (how long we’ll wait for response) and how many times to retry before giving up

property baudrate: int

The baudrate of our UART connection

begin() None

Initialize the module by syncing, resetting if necessary, setting up the desired baudrate, turning on single-socket mode, and configuring SSL support. Required before using the module but we dont do in __init__ because this can throw an exception.

property cipmux: int

The IP socket multiplexing setting. 0 for one socket, 1 for multi-socket

connect(secrets: Dict[str, str | int], timeout: int = 15, retries: int = 3) None

Repeatedly try to connect to an access point with the details in the passed in ‘secrets’ dictionary. Be sure ‘ssid’ and ‘password’ are defined in the secrets dict! If ‘timezone’ is set, we’ll also configure SNTP

connect_enterprise(secrets: Dict[str, str | int], timeout: int = 15, retries: int = 3) None

Repeatedly try to connect to an enterprise access point with the details in the passed in ‘secrets’ dictionary. Be sure ‘ssid’,’password’,’username’,’identity’ and ‘method’ are defined in the secrets dict! If ‘timezone’ is set, we’ll also configure SNTP

property conntype: str | None

The configured connection-type

deep_sleep(duration_ms: int) bool

Execute deep-sleep command. Passing zero as argument will put the chip into deep-sleep forever until the RST-pin is pulled low (method hard_reset()). This is the typical use-case for an ESP8266 as coprocessor.

Note that a similar method in the Arduino-libs expects microseconds.

disconnect(timeout: int = 5, retries: int = 3)

Disconnect from the AP. Tries whether connected or not.

echo(echo: bool) None

Set AT command echo on or off

factory_reset() None

Perform a hard reset, then send factory restore settings request

get_version() str | None

Request the AT firmware version string and parse out the version number

hard_reset() None

Perform a hardware reset by toggling the reset pin, if it was defined in the initialization of this object

hw_flow(flag: bool) None

Turn on HW flow control (if available) on to allow data, or off to stop

property is_connected: bool

Initialize module if not done yet, and check if we’re connected to an access point, returns True or False

join_AP(ssid: str, password: str, timeout: int = 15, retries: int = 3) None

Try to join an access point by name and password, will return immediately if we’re already connected and won’t try to reconnect

join_AP_Enterprise(ssid: str, username: str, identity: str, password: str, method: int, timeout: int = 30, retries: int = 3) None

Try to join an Enterprise access point by name and password, will return immediately if we’re already connected and won’t try to reconnect

property local_ip: str | None

Our local IP address as a dotted-quad string

property mode: int | None

What mode we’re in, can be MODE_STATION, MODE_SOFTAP or MODE_SOFTAPSTATION

nslookup(host: str) str | None

Return a dotted-quad IP address strings that matches the hostname

ping(host: str) int | None

Ping the IP or hostname given, returns ms time or None on failure

property remote_AP: List[int | str | None]

The name of the access point we’re connected to, as a string

scan_APs(retries: int = 3) List[List[bytes]] | None

Ask the module to scan for access points and return a list of lists with name, RSSI, MAC addresses, etc

set_autoconnect(autoconnect: bool) None

Set the auto connection status if the wifi connects automatically on powerup

sntp_config(enable: bool, timezone: int | None = None, server: str | None = None) None

Configure the built in ESP SNTP client with a UTC-offset number (timezone) and server as IP or hostname.

property sntp_time: bytes | None

Return a string with time/date information using SNTP, may return 1970 ‘bad data’ on the first few minutes, without warning!

socket_connect(conntype: str, remote: str, remote_port: int, *, keepalive: int = 10, retries: int = 1) bool

Open a socket. conntype can be TYPE_TCP, TYPE_UDP, or TYPE_SSL. Remote can be an IP address or DNS (we’ll do the lookup for you. Remote port is integer port on other side. We can’t set the local port.

Note that this method is usually called by the requests-package, which does not know anything about conntype. So it is mandatory to set the conntype manually before calling this method if the conntype-parameter is not provided.

If requests are done using ESPAT_WiFiManager, the conntype is set there depending on the protocol (http/https).

socket_disconnect() None

Close any open socket, if there is one

socket_receive(timeout: int = 5) bytearray

Check for incoming data over the open socket, returns bytes

socket_send(buffer: bytes, timeout: int = 1) bool

Send data over the already-opened socket, buffer must be bytes

soft_reset(timeout: int = 5) bool

Perform a software reset by AT command. Returns True if we successfully performed, false if failed to reset

property status: int | None

The IP connection status number (see AT+CIPSTATUS datasheet for meaning)

property status_socket: int | None

The Socket connection status number (see AT+CIPSTATE for meaning)

property status_wifi: int | None

The WIFI connection status number (see AT+CWSTATE datasheet for meaning)

sync() bool

Check if we have AT commmand sync by sending plain ATs

property version: str | None

The cached version string retrieved via the AT+GMR command

exception adafruit_espatcontrol.adafruit_espatcontrol.OKError

The exception thrown when we didn’t get acknowledgement to an AT command

A ‘socket’ compatible interface thru the ESP AT command set

adafruit_espatcontrol.adafruit_espatcontrol_socket.getaddrinfo(host: str, port: int, family: int = 0, socktype: int = 0, proto: int = 0, flags: int = 0) List[Tuple[int, int, int, str, Tuple[str, int]]]

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

adafruit_espatcontrol.adafruit_espatcontrol_socket.set_interface(iface: ESP_ATcontrol) None

Helper to set the global internet interface

class adafruit_espatcontrol.adafruit_espatcontrol_socket.socket(family: int = 2, type: int = 1, proto: int = 0, fileno: int | None = None)

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

close() None

Close the socket, after reading whatever remains

connect(address: Tuple[str, int], conntype: str | None = None) None

Connect the socket to the ‘address’ (which should be dotted quad IP). ‘conntype’ is an extra that may indicate SSL or not, depending on the underlying interface

readline() bytes

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

recv(num: int = 0) bytes

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

send(data: bytes) None

Send some data to the socket

settimeout(value: int) None

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