# Cellular Data for CircuitPython with FONA
## Overview
**Build projects that can transmit and receive data from just about anywhere using cellular data!** Unlike transports that require a router, wires, or a gateway, cellular towers are located just about anywhere people are.
- **If you'd like to learn more about using cellular data in your project** - check out the cellular section in the [All The Internet of Things: Transports guide](https://learn.adafruit.com/alltheiot-transports/cellular-satellite).
We designed a CircuitPython library compatible with the Adafruit FONA cellular modem. This module handles all the complicated modem interfacing for you, so you can bring your IoT projects online quickly.
**In this guide, you will set up and configure a FONA module with a CircuitPython board to connect to the internet over a cellular network. ** We've included examples for using this module to send HTTP requests and connect to MQTT brokers.
## Parts
Adafruit currently offers two types of cellular data transports: 2G/GSM and 3G.
First up are the FONA808 and FONA800 modules which use **2G/GSM** networks. These networks use smaller modules, use less power and will work in any country ("quad-band"). A downside of these networks is they may be shut down in the United States by the end of 2020.
The **Fona3G** module uses a SIM5320 **3G** module which is physically larger than the SIM808 modules, use more power and have an increased data-rate. Unlike 2G/GSM, major carries have not announced any plan to shut down 3G services and you may need to purchase a module specific to the region where you will be operating your FONA projects.
### Adafruit FONA 3G Cellular Breakout
[Adafruit FONA 3G Cellular Breakout](https://www.adafruit.com/product/2696)
For those who want to take it to _the next level_ we now have a 3G Cellular Modem breakout! The FONA 3G has better coverage, GSM backwards-compatibility and even sports a built-in GPS module for geolocation & asset tracking. This all-in-one cellular phone module with that...
Out of Stock
[Buy Now](https://www.adafruit.com/product/2696)
[Related Guides to the Product](https://learn.adafruit.com/products/2696/guides)
You will also need some required accessories to make the FONA work. **These are not included with the FONA shield or breakout!**
**You will need** a Mini SIM card to do anything on the cellular network. If you're in the USA, we suggest picking up the SIM Card from Ting.
- If you're not in the US, or want to use a different cellular network provider, [please see this page for more information about obtaining a FONA-compatible SIM card.](https://learn.adafruit.com/adafruit-fona-808-cellular-plus-gps-breakout/obtaining-a-sim)
**You will need** a LiPoly battery (500mAh or larger) to run the FONA module.
### Lithium Ion Polymer Battery - 3.7v 500mAh
[Lithium Ion Polymer Battery - 3.7v 500mAh](https://www.adafruit.com/product/1578)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 500mAh for a total of about 1.9 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
### Lithium Ion Polymer Battery - 3.7v 1200mAh
[Lithium Ion Polymer Battery - 3.7v 1200mAh](https://www.adafruit.com/product/258)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 1200mAh for a total of about 4.5 Wh. If you need a larger battery,
In Stock
[Buy Now](https://www.adafruit.com/product/258)
[Related Guides to the Product](https://learn.adafruit.com/products/258/guides)
**You will need** a external uFL GSM Antenna, we like this slim sticker-type antenna:
### Slim Sticker-type GSM/Cellular Quad-Band Antenna - 3dBi uFL
[Slim Sticker-type GSM/Cellular Quad-Band Antenna - 3dBi uFL](https://www.adafruit.com/product/1991)
That's one slim cellular antenna! At just 75mm long from tip to tip and and with a thickness of just 2mm, this 3dBi GSM antenna is slim, compact and sensitive, with a 3dBi gain. The antenna juts out from its base with stick-on back so you attach it to an enclosure if...
In Stock
[Buy Now](https://www.adafruit.com/product/1991)
[Related Guides to the Product](https://learn.adafruit.com/products/1991/guides)
If you want to use a SMA antenna instead, you'll want to pick up a uFL to SMA adapter cable.
### Part: uFL to SMA Adapter Cable
quantity: 1
SMA to uFL/u.FL/IPX/IPEX RF Adapter Cable
[uFL to SMA Adapter Cable](https://www.adafruit.com/product/851)
**You will need** a MicroUSB cable for charging the FONA's battery.
### USB cable - USB A to Micro-B
[USB cable - USB A to Micro-B](https://www.adafruit.com/product/592)
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or microcontroller
Approximately 3 feet / 1 meter long
Out of Stock
[Buy Now](https://www.adafruit.com/product/592)
[Related Guides to the Product](https://learn.adafruit.com/products/592/guides)
**You will also need** an external passive GPS antenna.
### Passive GPS Antenna uFL - 9mm x 9mm -2dBi gain
[Passive GPS Antenna uFL - 9mm x 9mm -2dBi gain](https://www.adafruit.com/product/2460)
Wow that's a tiny GPS antenna! This passive antenna is only 9mm x 9mm x 6.5mm in size, with a 50mm long uFL cable. Great for when you want to keep things small.
Comes with a standard uFL connector on the end. [Perfect for our FONA...](https://www.adafruit.com/products/2542)
In Stock
[Buy Now](https://www.adafruit.com/product/2460)
[Related Guides to the Product](https://learn.adafruit.com/products/2460/guides)
# Cellular Data for CircuitPython with FONA
## CircuitPython Setup
## CircuitPython Installation
Some CircuitPython compatible boards come with CircuitPython installed. Others are _CircuitPython-ready_, but need to have it installed. As well, you may want to update the version of CircuitPython already installed on your board. The steps are the same for installing and updating.
- To **install (or update) your CircuitPython board**, [follow this page and come back here when you've successfully installed (or updated) CircuitPython.](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython)
## Install the Mu Editor
This guide requires you to edit and interact with CircuitPython code. While you can use any text editor of your choosing, **Mu** is a simple code editor that works with the Adafruit CircuitPython boards. It's written in Python and works on Windows, MacOS, Linux and Raspberry Pi. The serial console is built right in, so you get immediate feedback from your board's serial output!
Before proceeding, if you'd like to use Mu, **click the button below to install the Mu Editor**. There are versions for PC, mac, and Linux.
[Install Mu Editor](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor)
## Secrets File Setup
Mobile devices like the Adafruit FONA need to be configured with the access point name (APN) identification with your wireless carrier.
We designed this library to use a **secrets.py** file which is in your **CIRCUITPY** drive to hold secret data including the APN configuration.
Your **secrets.py** file should look like this:
```python
# This file is where you keep secret settings, passwords, and tokens!
# If you put them in the code you risk committing that info or sharing it
secrets = {
"apn": "your_apn_name",
"apn_username": "your_apn_username",
"apn_password": "your_apn_password",
}
```
In the **secrets.py** file, set the `apn` to the apn name provided by your cellular network carrier.
- For example, the APN for the Ting network is `wholesale`.
`apn_username` and `apn_password` are optional parameters for authentication. Leave these as-is unless otherwise directed by your network carrier
- If you are unsure about any of these settings, please contact your network carrier for more information.
## CircuitPython Library Installation
First make sure you are running the [latest version of Adafruit CircuitPython](https://circuitpython.org/board/pyportal/) for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from [Adafruit's CircuitPython library bundle](https://github.com/adafruit/Adafruit_CircuitPython_Bundle) matching your version of CircuitPython. The FONA Library requires at least CircuitPython version 4.0.0.
Before continuing, make sure your board's **lib** folder has at least the following files and folders ** ** copied over:
- **adafruit\_fona**
- **adafruit\_bus\_device**
- **adafruit\_requests.mpy**
- **adafruit\_simpleio.mpy**
Once all the files are copied, your **CIRCUITPY** drive should look like the following screenshot:
# Cellular Data for CircuitPython with FONA
## Usage
Warning:
## FONA808 or FONA800 Wiring
If you're using a FONA808 or FONA800 breakout, use the following wiring so that the hardware UART pins are used. Here's an example with the Feather M4:
- **Board 5V** (or **3.3v** ) to **FONA808 VIO**
- **Board GND** to **FONA808 GND**
- **Board GND** to **FONA808 KEY**
- **Board Serial TX** to **FONA808 RX**
- **Board Serial RX** to **FONA808 TX**
- **Board Digital Pin 4** to **FONA808 RST**
## FONA 3G Wiring
If you're using a FONA3G breakout, use the following wiring so that the hardware UART pins are used. Here's an example with the Feather M4:
- **Board** **5V** (or **3.3V** ) to **Fona3G** **Vio**
- **Board GND** to **FONA3G GND**
- **Board GND** to **FONA3G Key**
- **Board RX** to **FONA3G TX**
- **Board TX** to **FONA3G RX**
- **Board Digital 4 Pin** to **Fona3G RST**
## Assembly
Before using the FONA with CircuitPython, **make sure you've attached a LiPoly battery, GPS antenna and GSM antenna to the FONA**.
- If you haven't done this yet, [navigate to this page and come back when you've connected the battery and antennas](https://learn.adafruit.com/adafruit-fona-808-cellular-plus-gps-breakout/assembly-1#attaching-antenna-and-battery-4-7).
**You must also insert a SIM card** to use the FONA with cellular data.
- If you haven't done this yet, [navigate to this page and come back when you've inserted the SIM card](https://learn.adafruit.com/adafruit-fona-808-cellular-plus-gps-breakout/assembly-1#sim-card-4-9).
**Make sure the battery you're using is charged** before running the code below.
Danger:
## Code Usage
Copy the following code to the **code.py** file on your microcontroller.
https://github.com/adafruit/Adafruit_CircuitPython_FONA/blob/main/examples/fona_simpletest.py
**If you're using a FONA808** , you do not need to modify the code below.
**If you're using a FONA3G** , you'll need to comment out the FONA800/FONA808 initialization and un-comment the FONA3G initialization in the code:
```python
# Use this for FONA800 and FONA808
# fona = FONA(uart, rst)
# Use this for FONA3G
fona = FONA3G(uart, rst)
```
**Save the code.py file** and **open the REPL**.
In order, the example code:
Imports APN details from the **secrets.py** file.
```python
# Get GPRS details and more from a secrets.py file
try:
from secrets import secrets
except ImportError:
print("GPRS secrets are kept in secrets.py, please add them there!")
raise
```
Creates a serial UART connection for the FONA and sets up the RST pin.
**NOTE:** You may need to change these pins if you're using a FONA breakout instead of a FONA shield.
```python
# Create a serial connection for the FONA connection
uart = busio.UART(board.TX, board.RX)
rst = digitalio.DigitalInOut(board.D4)
```
Initializes the FONA module. This step may take a few seconds since the module attempts to communicate with and bring up the module.
```python
# Use this for FONA800 and FONA808
fona = FONA(uart, rst)
# Use this for FONA3G
# fona = FONA3G(uart, rst)
```
We use a module called fona\_network to configure the modem. This module automatically determines if the modem connected is a 2G/GSM or 3G/CDMA modem and initializes the modem appropriately.
```python
# Initialize cellular data network
network = network.CELLULAR(
fona, (secrets["apn"], secrets["apn_username"], secrets["apn_password"])
)
```
The code waits for the FONA to attach to the cellular network using the carrier settings.
```python
while not network.is_attached:
print("Attaching to network...")
time.sleep(0.5)
print("Attached!")
```
Once attached, it attempts to connect to the network and bring up the modem. This step may take a while to connect, depending on your cellular reception.
```python
while not network.is_connected:
print("Connecting to network...")
network.connect()
time.sleep(0.5)
print("Network Connected!")
```
Prints out the local IP and attempts to perform an IP address lookup for adafruit.com.
```python
print("My IP address is:", fona.local_ip)
print("IP lookup adafruit.com: %s" % fona.get_host_by_name("adafruit.com"))
```
OK now we're getting to the really interesting part. With a SAMD51 or other large-RAM (well, over 32 KB) device, we can do a lot of neat tricks. Like, for example, we can implement an interface a lot like [requests](http://docs.python-requests.org/en/master/) - which makes getting data _really really easy._
Calling `requests.set_socket` passes requests our fona interface and a socket-like implementation for the FONA.
```python
# Initialize a requests object with a socket and cellular interface
requests.set_socket(cellular_socket, fona)
```
To read in all the text from a web URL, call `requests.get` -
```python
print("Fetching text from", TEXT_URL)
r = requests.get(TEXT_URL)
print("-" * 40)
print(r.text)
print("-" * 40)
r.close()
```
Or, if the data is in structured JSON, you can get the json pre-parsed into a Python dictionary that can be easily queried or traversed. (Again, only for nRF52840, M4 and other high-RAM boards)
```python
print("Fetching json from", JSON_URL)
r = requests.get(JSON_URL)
print("-" * 40)
print(r.json())
print("-" * 40)
r.close()
```
# Cellular Data for CircuitPython with FONA
## Python Docs
## Featured Products
### Adafruit FONA 808 - Mini Cellular GSM + GPS Breakout
[Adafruit FONA 808 - Mini Cellular GSM + GPS Breakout](https://www.adafruit.com/product/2542)
Cellular + GPS tracking, all in one? Oh yes! Introducing Adafruit FONA 808 MiniGSM + GPS, an all-in-one cellular phone module with that lets you add location-tracking, voice, text, SMS and data to your project in an adorable little package. (
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2542)
[Related Guides to the Product](https://learn.adafruit.com/products/2542/guides)
### Adafruit FONA 3G Cellular Breakout
[Adafruit FONA 3G Cellular Breakout](https://www.adafruit.com/product/2696)
For those who want to take it to _the next level_ we now have a 3G Cellular Modem breakout! The FONA 3G has better coverage, GSM backwards-compatibility and even sports a built-in GPS module for geolocation & asset tracking. This all-in-one cellular phone module with that...
Out of Stock
[Buy Now](https://www.adafruit.com/product/2696)
[Related Guides to the Product](https://learn.adafruit.com/products/2696/guides)
### Adafruit FONA 808 Shield - Mini Cellular GSM + GPS for Arduino
[Adafruit FONA 808 Shield - Mini Cellular GSM + GPS for Arduino](https://www.adafruit.com/product/2636)
Cellular + GPS tracking, all in one, for your Arduino? Oh yes! Introducing Adafruit FONA 808 GSM + GPS Shield, an all-in-one cellular phone module with that lets you add location-tracking, voice, text, SMS and data to your project, in Arduino shield format for easy use.
**Please...**
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2636)
[Related Guides to the Product](https://learn.adafruit.com/products/2636/guides)
### Adafruit FONA 800 Shield - Voice/Data Cellular GSM for Arduino
[Adafruit FONA 800 Shield - Voice/Data Cellular GSM for Arduino](https://www.adafruit.com/product/2468)
Ring, Ring! Who's that callin'? It's your Arduino! Introducing Adafruit FONA 800 Shield, an adorable all-in-one cellular phone shield that lets you add voice, text, SMS and data to your project in an easy to use pluggable shield.
This shield fits on top of any classic Arduino...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2468)
[Related Guides to the Product](https://learn.adafruit.com/products/2468/guides)
### Adafruit FONA 800 uFL Shield Starter Pack
[Adafruit FONA 800 uFL Shield Starter Pack](https://www.adafruit.com/product/2523)
Discontinued - **you can grab** [Adafruit FONA 808 Shield - Mini Cellular GSM + GPS for Arduino](https://www.adafruit.com/product/2636) **instead! **
Build your own cellular project and get off the grid with FONA. This pack comes with an uFL-antenna...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2523)
[Related Guides to the Product](https://learn.adafruit.com/products/2523/guides)
### GSM SIM Card from Ting & Adafruit - Data/Voice/Text
[GSM SIM Card from Ting & Adafruit - Data/Voice/Text](https://www.adafruit.com/product/2505)
Adafruit is now a phone company :) Or, well, we've sold [DIY cell phones](https://www.adafruit.com/categories/281) for awhile now but you've never been able to buy your [FONA](https://www.adafruit.com/fona) and a SIM Card all in one place. Now,...
No Longer Stocked
[Buy Now](https://www.adafruit.com/product/2505)
[Related Guides to the Product](https://learn.adafruit.com/products/2505/guides)
### Lithium Ion Polymer Battery - 3.7v 500mAh
[Lithium Ion Polymer Battery - 3.7v 500mAh](https://www.adafruit.com/product/1578)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 500mAh for a total of about 1.9 Wh. If you need a larger (or smaller!) battery,
Out of Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
### Lithium Ion Polymer Battery - 3.7v 1200mAh
[Lithium Ion Polymer Battery - 3.7v 1200mAh](https://www.adafruit.com/product/258)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 1200mAh for a total of about 4.5 Wh. If you need a larger battery,
In Stock
[Buy Now](https://www.adafruit.com/product/258)
[Related Guides to the Product](https://learn.adafruit.com/products/258/guides)
## Related Guides
- [Feather ESP32-S3 TFT CircuitPython Day 2024 Countdown Clock](https://learn.adafruit.com/feather-esp32-s3-tft-circuitpython-day-2024-countdown-clock.md)
- [Adafruit MagTag Project Selector](https://learn.adafruit.com/adafruit-magtag-project-selector.md)
- [Adafruit Feather M4 Express](https://learn.adafruit.com/adafruit-feather-m4-express-atsamd51.md)
- [Screaming Cauldron](https://learn.adafruit.com/screaming-cauldron.md)
- [Matrix Portal New Guide Scroller](https://learn.adafruit.com/matrix-portal-new-guide-scroller.md)
- [Flappy Nyan Cat Game on Fruit Jam and Metro RP2350](https://learn.adafruit.com/flappy-nyan-cat-game-on-metro-rp2350.md)
- [Mini Weather Station ESP32-S3 TFT](https://learn.adafruit.com/mini-weather-station-esp32-s2-tft.md)
- [1D Chomper Tabletop Arcade Game](https://learn.adafruit.com/1d-chomper-tabletop-arcade-game.md)
- [Currying in CircuitPython](https://learn.adafruit.com/partials-in-circuitpython.md)
- [Adafruit CAN Bus BFF](https://learn.adafruit.com/adafruit-can-bus-bff.md)
- [Modal MIDI Keyboard](https://learn.adafruit.com/modal-midi-keyboard.md)
- [Minecraft Turbopad](https://learn.adafruit.com/minecraft-turbopad.md)
- [Musical Walking Stick with Circuit Playground](https://learn.adafruit.com/musical-cane-walking-stick.md)
- [Introducing Adafruit ItsyBitsy M4](https://learn.adafruit.com/introducing-adafruit-itsybitsy-m4.md)
- [Adafruit RP2350 22-pin FPC HSTX to DVI Adapter](https://learn.adafruit.com/adafruit-rp2350-22-pin-fpc-hstx-to-dvi-adapter.md)