adafruit_fona

CircuitPython library for the Adafruit FONA cellular module

  • Author(s): ladyada, Brent Rubell

Implementation Notes

Software and Dependencies:

class adafruit_fona.adafruit_fona.FONA(uart: UART, rst: DigitalInOut, ri: DigitalInOut | None = None, debug: bool = False)

CircuitPython FONA module interface.

Parameters:

  • uart (UART) – FONA UART connection.

  • rst (DigitalInOut) – FONA RST pin.

  • ri (DigitalInOut) – Optional FONA Ring Interrupt (RI) pin.

  • debug (bool) – Enable debugging output.

delete_all_sms() → bool

Deletes all SMS messages on the FONA SIM.

delete_sms(sms_slot: int) → bool

Deletes a SMS message from a storage (internal or sim) slot

Parameters:

sms_slot (int) – SMS SIM or FONA memory slot number.

property enable_sms_notification: bool

Checks if SMS notifications are enabled.

factory_reset() → bool

Resets modem to factory configuration.

get_host_by_name(hostname: str) → str | Literal[False]

Converts a hostname to a packed 4-byte IP address.

Parameters:

hostname (str) – Destination server.

get_socket() → int

Obtains a socket, if available.

property gprs: bool

GPRS (General Packet Radio Services) power status.

property gps: int

Module’s GPS status.

property iccid: str

SIM Card’s unique ICCID (Integrated Circuit Card Identifier).

property iemi: str

FONA Module’s IEMI (International Mobile Equipment Identity) number.

property local_ip: str | None

Module’s local IP address, None if not set.

property network_status: int

The status of the cellular network.

num_sms(sim_storage: bool = True) → int

Returns the number of SMS messages stored in memory.

Parameters:

sim_storage (bool) – SMS storage on the SIM, otherwise internal storage on FONA chip.

pretty_ip(ip: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray) → str

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

read_sms(sms_slot: int) → Tuple[str, str]

Reads and parses SMS messages from FONA device. Returns the SMS sender’s phone number and the message contents as a tuple.

Parameters:

sms_slot (int) – SMS SIM or FONA memory slot number.

receive_sms() → Tuple[str, str]

Checks for a message notification from the FONA module, replies back with the a tuple containing (sender, message).

Note:

This method needs to be polled consistently due to the lack of hw-based interrupts in CircuitPython.

remote_ip(sock_num: int) → str

Returns the IP address of the remote server.

Parameters:

sock_num (int) – Desired socket.

reset() → None

Performs a hardware reset on the modem.

property rssi: float

The received signal strength indicator for the cellular network we are connected to.

send_sms(phone_number: int, message: str) → bool

Sends a message SMS to a phone number.

Parameters:

  • phone_number (int) – Destination phone number.

  • message (str) – Message to send to the phone number.

set_gprs(apn: Tuple[str, str | None, str | None] | None = None, enable: bool = True) → bool

Configures and brings up GPRS.

Parameters:

  • apn (tuple) – The APN information

  • enable (bool) – Enables or disables GPRS.

socket_available(sock_num: int) → int

Returns the amount of bytes available to be read from the socket.

Parameters:

sock_num (int) – Desired socket to return bytes available from.

socket_close(sock_num: int) → bool

Close TCP or UDP connection

Parameters:

sock_num (int) – Desired socket number.

socket_connect(sock_num: int, dest: str, port: int, conn_mode: int = micropython.const) → bool

Connects to a destination IP address or hostname. By default, we use conn_mode TCP_MODE but we may also use UDP_MODE.

Parameters:

  • sock_num (int) – Desired socket number

  • dest (str) – Destination dest address.

  • port (int) – Destination dest port.

  • conn_mode (int) – Connection mode (TCP/UDP)

socket_read(sock_num: int, length: int) → bytearray

Read data from the network into a buffer. Returns bytes read.

Parameters:

  • sock_num (int) – Desired socket to read from.

  • length (int) – Desired length to read.

socket_status(sock_num: int) → bool

Returns the socket connection status, False if not connected.

Parameters:

sock_num (int) – Desired socket number.

socket_write(sock_num: int, buffer: bytes, timeout: int = 3000) → bool

Writes bytes to the socket.

Parameters:

  • sock_num (int) – Desired socket number to write to.

  • buffer (bytes) – Bytes to write to socket.

  • timeout (int) – Socket write timeout, in milliseconds.

unpretty_ip(ip: str) → bytes

Converts a dotted-quad string to a bytearray IP address

property version: int

The version of the FONA module. Can be FONA_800_L, FONA_800_H, FONA_808_V1, FONA_808_V2, FONA_3G_A, FONA3G_E.

adafruit_fona_socket

A socket compatible interface with the Adafruit FONA cellular module.

  • Author(s): ladyada, Brent Rubell

adafruit_fona.adafruit_fona_socket.getaddrinfo(host, port: int, family=0, socktype=0, proto=0, flags=0)

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.

adafruit_fona.adafruit_fona_socket.gethostbyname(hostname: str) → str

Translate a host name to IPv4 address format. The IPv4 address is returned as a string.

Parameters:

hostname (str) – Desired hostname.

adafruit_fona.adafruit_fona_socket.htonl(x: int) → int

Convert 32-bit positive integers from host to network byte order.

adafruit_fona.adafruit_fona_socket.htons(x: int) → int

Convert 16-bit positive integers from host to network byte order.

adafruit_fona.adafruit_fona_socket.set_interface(iface: FONA) → None

Helper to set the global internet interface.

class adafruit_fona.adafruit_fona_socket.socket(family: int = micropython.const, type: int = micropython.const, proto: int = 0, fileno: int | None = None, socknum: int | None = None)

A simplified implementation of the Python ‘socket’ class for connecting to a FONA cellular module.

Parameters:

  • family (int) – Socket address (and protocol) family.

  • type (int) – Socket type.

available() → int

Returns how many bytes are available to be read from the socket.

close() → bool

Closes the socket.

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

Connect to a remote socket at address. (The format of address depends on the address family — see above.)

Parameters:

  • address (tuple) – Remote socket as a (host, port) tuple.

  • conn_mode (int) – Connection mode (TCP/UDP)

property connected: bool

Returns whether or not we are connected to the socket.

getpeername() → str

Return the remote address to which the socket is connected.

gettimeout() → int

Return the timeout in seconds (float) associated with socket operations, or None if no timeout is set.

inet_aton(ip_string: str) → bytearray

Convert an IPv4 address from dotted-quad string format.

Parameters:

ip_string (str) – IP Address, as a dotted-quad string.

readline() → Sequence[int]

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

recv(bufsize: int = 0) → Sequence[int]

Reads some bytes from the connected remote address.

Parameters:

bufsize (int) – maximum number of bytes to receive

send(data: bytes) → None

Send data to the socket. The socket must be connected to a remote socket prior to calling this method.

Parameters:

data (bytes) – Desired data to send to the socket.

settimeout(value: int) → None

Sets socket read timeout.

Parameters:

value (int) – Socket read timeout, in seconds.

property socknum: int

Returns the socket object’s socket number.

adafruit_fona_network

Interface for connecting to and interacting with GSM and CDMA cellular networks.

  • Author(s): Brent Rubell

class adafruit_fona.adafruit_fona_network.CELLULAR(fona: FONA, apn: Tuple[str, str | None, str | None])

Interface for connecting to and interacting with GSM and CDMA cellular networks.

Parameters:

  • fona (FONA) – The Adafruit FONA module we are using.

  • apn (tuple) – Tuple containing APN name, (optional) APN username, and APN password.

connect() → None

Connect to cellular network.

disconnect() → None

Disconnect from cellular network.

property iccid: str

Returns the SIM card’s ICCID, as a string.

property imei: str

Returns the modem’s IEMI number, as a string.

property is_attached: bool

Returns if the modem is attached to the network.

property is_connected

Returns if attached to network and an IP Addresss was obtained.

fona_3g

FONA3G cellular module instance.

  • Author(s): ladyada, Brent Rubell

Implementation Notes

Software and Dependencies:

class adafruit_fona.fona_3g.FONA3G(uart: UART, rst: DigitalInOut, ri: DigitalInOut | None = None, debug: bool = False)

FONA 3G module interface.

Parameters:

  • uart (UART) – FONA UART connection.

  • rst (DigitalInOut) – FONA RST pin.

  • ri (DigitalInOut) – Optional FONA Ring Interrupt (RI) pin.

  • debug (bool) – Enable debugging output.

get_host_by_name(hostname: str) → str | Literal[False]

Converts a hostname to a 4-byte IP address.

Parameters:

hostname (str) – Domain name.

get_socket() → int

Returns an unused socket.

property gps: bool

Module’s GPS status.

property local_ip: str | None

Module’s local IP address, None if not set.

remote_ip(sock_num: int) → str

Returns the IP address of the remote connection.

Parameters:

sock_num (int) – Desired socket number

set_baudrate(baudrate: int) → bool

Sets the FONA’s UART baudrate.

set_gprs(apn: Tuple[str, str | None, str | None] | None = None, enable: bool = True) → bool

Configures and brings up GPRS.

Parameters:

  • apn (tuple) – APN configuration settings

  • enable (bool) – Enables or disables GPRS.

socket_connect(sock_num: int, dest: str, port: int, conn_mode: int = 0) → bool

Connects to a destination IP address or hostname. By default, we use conn_mode TCP_MODE but we may also use UDP_MODE.

Parameters:

  • sock_num (int) – Desired socket number

  • dest (str) – Destination dest address.

  • port (int) – Destination dest port.

  • conn_mode (int) – Connection mode (TCP/UDP)

socket_status(sock_num: int) → bool

Returns socket status, True if connected. False otherwise.

Parameters:

sock_num (int) – Desired socket number.

socket_write(sock_num: int, buffer: bytes, timeout: int = 120000) → bool

Writes len(buffer) bytes to the socket.

Parameters:

  • sock_num (int) – Desired socket number to write to.

  • buffer (bytes) – Bytes to write to socket.

  • timeout (int) – Socket write timeout, in milliseconds. Defaults to 120000ms.

property tx_timeout: bool

CIPSEND timeout, in milliseconds.

property ue_system_info: bool

UE System status.