The Adafruit_CircuitPython_FruitJam library is a helper library based on the Portal Base library. It initializes the built-in hardware peripherals on the Fruit Jam and provides a single interface for project code to access them. It also contains various helpers for fetching and displaying information from internet sources. Similar libraries exist for the Adafruit PyPortal, MagTag, MatrixPortal and other devices.
Using the Fruit Jam library is optional. The examples on other pages in the CircuitPython Essentials section of this guide document interacting more directly with the Fruit Jam hardware peripherals and WiFi capabilities. The Fruit Jam library provides a single point of import and setup for the same capabilities.
The Fruit Jam library handles the internet access and PortalBase helper functions on the FruitJam object. The on-board peripherals on the Fruit Jam, like buttons, NeoPixels, DAC, and SD card, are available using a Peripherals object. If you're not using any of the internet or PortalBase functions you can import and create the Peripherals object directly.
# use Peripherals object without internet helpers from adafruit_fruitjam.peripherals import Peripherals fruitjam_peripherals = Peripherals()
Or, if you are using PortalBase helpers, you can initialize the full FruitJam object and then access fruitjam.peripherals to interact with the built-in hardware.
# use full FruitJam object with PortalBase internet helpers and peripherals from adafruit_fruitjam import FruitJam TEXT_URL = "http://wifitest.adafruit.com/testwifi/index.html" fruitjam = FruitJam(url=TEXT_URL, text_position=(10, 20)) fruitjam_peripherals = fruitjam.peripherals
# SPDX-FileCopyrightText: Copyright (c) 2025 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time
from adafruit_fruitjam.peripherals import Peripherals
colors = [0xFF00FF, 0xFFFF00, 0x00FF00]
fruitjam = Peripherals()
fruitjam.neopixels.brightness = 0.1
while True:
fruitjam.neopixels.fill(colors[0])
time.sleep(0.3)
fruitjam.neopixels.fill(colors[1])
time.sleep(0.3)
fruitjam.neopixels.fill(colors[2])
time.sleep(0.3)
fruitjam.neopixels.fill(0x000000)
for i in range(5):
fruitjam.neopixels[i] = colors[i % len(colors)]
time.sleep(0.1)
Buttons
The 3 built-in button states are available as peripherals.button1, peripherals.button2, and peripherals.button3. There is also the peripherals.any_button_pressed property which will be True if any of the hardware buttons are pressed.
import time
from adafruit_fruitjam.peripherals import Peripherals
fruitjam = Peripherals()
while True:
if fruitjam.any_button_pressed:
print("Button(s) Pressed: ", end="")
if fruitjam.button1:
print("Button 1, ", end="")
if fruitjam.button2:
print("Button 2, ", end="")
if fruitjam.button3:
print("Button 3", end="")
print()
time.sleep(0.01)
Audio
There are several properties and functions that assist with various audio related tasks.
-
peripherals.dac- An instance of the TLV320 driver. Use higher level helpers instead of this unless you want very fine grained control over the DAC behavior, the capabilities of the DAC are extensive and the API is rather complex. -
peripherals.audio- An instance of audiobusio.I2SOut ready to play sounds out of the 3.5mm jack or JST speaker connector on the Fruit Jam -
peripherals.volume- A property holding a float value between0.0and1.0that acts as a high level volume control without having to dive into the more complex DAC volume APIs. -
peripherals.safe_volume_limit- This float property controls the maximum allowed volume. By default it is0.75. Attempting to setperipherals.volumeover the limit results in an exception. You can change the limit by settingperipherals.safe_volume_limitto any desired value between0.0and1.0. Operating above the limit could damage small speakers. -
peripherals.audio_output- A string property that controls where audio will play from."headphone"for the 3.5mm jack and"speaker"for the JST connector. -
peripherals.play_file()- This function matches functionality found in PyPortal and other PortalBase libraries. It plays a .wav file from the attached headphones or speaker(s). -
peripherals.stop_play()- Theplay_file()function accepts await_to_finishboolean argument that isTrueby default. If you passFalsefor that value instead, the function will return immediately freeing up the code to do other things while the wave file is playing. Thestop_play()function can be called to end the playback of a wave file that was started this way. -
peripherals.play_mp3_file()- Similar toplay_file(), but this one is for .mp3 files instead of .wav.
# SPDX-FileCopyrightText: Copyright (c) 2025 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time
import synthio
import adafruit_fruitjam
pobj = adafruit_fruitjam.peripherals.Peripherals(audio_output="headphone")
synth = synthio.Synthesizer(sample_rate=44100)
pobj.audio.play(synth)
VOLUMES = [0.25, 0.35, 0.50, 0.55, 0.60]
C_major_scale = [60, 62, 64, 65, 67, 69, 71, 72, 71, 69, 67, 65, 64, 62, 60]
while True:
print("\n=== Synthio Test ===")
for vol in VOLUMES:
pobj.volume = vol
print(f"Volume: {vol}")
for note in C_major_scale:
synth.press(note)
time.sleep(0.1)
synth.release(note)
time.sleep(0.05)
time.sleep(1.0)
JST Speaker Output Wave Audio Files
Download the .wav files from the examples folder in the Fruit Jam repo and save them inside of CIRCUITPY/wav/, or swap in your own wave audio files on your drive and in the source code.
# SPDX-FileCopyrightText: Copyright (c) 2025 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time
import adafruit_fruitjam
pobj = adafruit_fruitjam.peripherals.Peripherals(audio_output="speaker")
FILES = ["wav/beep.wav", "wav/dip.wav", "wav/rise.wav"]
VOLUMES = [0.25, 0.35, 0.50, 0.55, 0.60]
while True:
print("\n=== Speaker Test ===")
for vol in VOLUMES:
pobj.volume = vol
print(f"Speaker volume: {vol}")
for f in FILES:
print(f" -> {f}")
pobj.play_file(f)
time.sleep(0.2)
time.sleep(1.0)
HSTX/DVI Display Configuration
The peripherals module in the Fruit Jam library provides helper functions for checking the display configuration and requesting changes to the configured resolution and color depth.
get_display_config() will get a tuple containing the width, height, and color depth that the display is currently configured for.
request_display_config() allows accepts desired width, height, and color depth arguments to configure the display. See the PicoDVI section of the Environment Variables docs for supported configuration values
Note that both of these functions are imported from the adafruit_fruitjam.peripherals module, but they do not require an instance of the Peripherals object.
from adafruit_fruitjam.peripherals import request_display_config, get_display_config
print("before: ")
print(get_display_config())
request_display_config(320, 240)
print("after: ")
print(get_display_config())
PortalBase Internet Helpers
The Fruit Jam library inherits all of the internet helpers provided by the PortalBase library. These make it easy to fetch() information from the internet and display it on the screen. Using this functionality it is possible to adapt many projects that were originally made for the PyPortal to work on the Fruit Jam simply by changing PyPortal initialization to FruitJam.
To use the WiFi features, you must set up a settings.toml file as shown on this page.
# SPDX-FileCopyrightText: 2019 Limor Fried for Adafruit Industries
# SPDX-FileCopyrightText: 2025 Tim Cocks for Adafruit Industries
#
# SPDX-License-Identifier: MIT
"""
Quotes example originally for PyPortal adapted for Fruit Jam
"""
import time
import board
from adafruit_fruitjam import FruitJam
from adafruit_fruitjam.peripherals import request_display_config
request_display_config(320, 240)
# Set up where we'll be fetching data from
DATA_SOURCE = "https://www.adafruit.com/api/quotes.php"
QUOTE_LOCATION = [0, 'text']
AUTHOR_LOCATION = [0, 'author']
# the current working directory (where this file is)
cwd = ("/"+__file__).rsplit('/', 1)[0]
fruitjam = FruitJam(url=DATA_SOURCE,
json_path=(QUOTE_LOCATION, AUTHOR_LOCATION),
status_neopixel=board.NEOPIXEL,
default_bg=cwd+"/quote_background.bmp",
text_font=cwd+"/fonts/Arial-ItalicMT-17.bdf",
text_position=((20, 120), # quote location
(5, 200)), # author location
text_color=(0xFFFFFF, # quote text color
0x8080FF), # author text color
text_wrap=(35, # characters to wrap for quote
0), # no wrap for author
text_maxlen=(180, 30), # max text size for quote & author
)
# speed up projects with lots of text by preloading the font!
fruitjam.preload_font()
while True:
try:
value = fruitjam.fetch()
print("Response is", value)
except (ValueError, RuntimeError, ConnectionError, OSError) as e:
print("Some error occured, retrying! -", e)
time.sleep(60)
Page last edited October 27, 2025
Text editor powered by tinymce.
