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: Optional[int] = None, rts_pin: Optional[DigitalInOut] = None, reset_pin: Optional[DigitalInOut] = None, debug: 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, Union[str, int]]) → 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

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() → Optional[str]

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) → 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

property local_ip: Optional[str]

Our local IP address as a dotted-quad string

property mode: Optional[int]

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

nslookup(host: str) → Optional[str]

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

ping(host: str) → Optional[int]

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

property remote_AP: List[Optional[Union[int, str]]]

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

scan_APs(retries: int = 3) → Optional[List[List[bytes]]]

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

sntp_config(enable: bool, timezone: Optional[int] = None, server: Optional[str] = None) → None

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

property sntp_time: Optional[bytes]

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

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() → bool

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

property status: Optional[int]

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

sync() → bool

Check if we have AT commmand sync by sending plain ATs

property version: Optional[str]

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: Optional[int] = 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: Optional[str] = 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