ESP32-S3 BLE iOS Media Controller

published July 22, 2024, last edited February 14, 2025

posted in LCDs & Displays Feather CircuitPython Breakout Boards/ LCDs, LEDs, & Displays Internet of Things - IOT/ Bluefruit / BLE

Save Download

Beginner

Project guide

Overview

Build a BLE media controller for your iOS device with a 3.5in TFT touch screen and a Feather ESP32-S3 running CircuitPython. You can display your iOS media audio track and album information directly on the display.

Touch Controller

You can control your media playback with buttons on the touch screen. Play/pause, change tracks, shuffle, repeat or adjust volume with a simple tap.

ESP32-S3 BLE with CircuitPython

CircuitPython 9.1.0 introduces Bluetooth connectivity for Espressif chips (ESP32 and ESP32-S3). This project utilities BLE libraries for CircuitPython to connect and pair with iOS devices. Media controls allow you to play, pause, skip tracks and adjust volume on your iOS devices.

Desktop Stand

3D print a stand for the 3.5in TFT display. Use M2.5 nylon hardware to secure the display to the 3D printed stand.

Parts

Angled shot of rectangular microcontroller.

Adafruit ESP32-S3 Feather with STEMMA QT / Qwiic

The ESP32-S3 has arrived in Feather format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native...

guides with product

$17.50

In Stock

Add to Cart

Overhead shot of a Black woman's hands with a blue and pinkish-red manicure drawing a heart on a touchscreen breakout.

Adafruit TFT FeatherWing - 3.5" 480x320 Touchscreen for Feathers

Spice up your Feather project with a beautiful 3.5" touchscreen display shield with built in microSD card socket. This TFT display is 3.5" diagonal with a bright 6 white-LED...

guides with product

$39.95

In Stock

Add to Cart

Black Nylon Screw and Stand-off Set with M2.5 Threads, kit box

Black Nylon Machine Screw and Stand-off Set – M2.5 Thread

Totaling 380 pieces, this M2.5 Screw Set is a must-have for your workstation. You'll have enough screws, nuts, and hex standoffs to fuel your maker...

guides with product

$16.95

In Stock

Add to Cart

Angled shot of coiled pink and purple USB cable with USB A and USB C connectors.

Pink and Purple Woven USB A to USB C Cable - 1 meter long

This cable is not only super-fashionable, with a woven pink and purple Blinka-like pattern, it's also made for USB C for our modernized breakout boards, Feathers, and...

Out of Stock

Page last edited July 23, 2024

Text editor powered by tinymce.

CircuitPython

CircuitPython is a derivative of MicroPython designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the CIRCUITPY drive to iterate.

CircuitPython Quickstart

Follow this step-by-step to quickly get CircuitPython running on your board.

Verify which version of the Feather ESP32-S3 you have before downloading CircuitPython below!

Below are links to CircuitPython for the Feather ESP32-S3 8MB No PSRAM and the Feather ESP32-S3 4MB Flash 2MB PSRAM. Be sure to choose the one that matches your board.

Download the latest version of CircuitPython for the Feather ESP32-S3 8MB Flash No PSRAM via circuitpython.org

Download the latest version of CircuitPython for the Feather ESP32-S3 4MB Flash 2MB PSRAM via circuitpython.org

install_circuitpython_on_most_boards_CircuitPython_downloaded.jpg

Click the link above to download the latest CircuitPython UF2 file.

Save it wherever is convenient for you.

Plug your board into your computer, using a known-good data-sync cable, directly, or via an adapter if needed.

Double-click the reset button (highlighted in red above), and you will see the RGB status LED(s) turn green (highlighted in green above). If you see red, try another port, or if you're using an adapter or hub, try without the hub, or different adapter or hub.

For this board, tap reset and wait for the LED to turn purple, and as soon as it turns purple, tap reset again. The second tap needs to happen while the LED is still purple.

If you do not see the LED turning purple, you will need to reinstall the UF2 bootloader. See the Factory Reset page in this guide for details.

If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!

A lot of people end up using charge-only USB cables and it is very frustrating! Make sure you have a USB cable you know is good for data sync.

You will see a new disk drive appear called FTHRS3BOOT.

Drag the adafruit_circuitpython_etc.uf2 file to FTHRS3BOOT.

The BOOT drive will disappear and a new disk drive called CIRCUITPY will appear.

That's it!

Page last edited July 23, 2024

Text editor powered by tinymce.

Code the Media Controller

Once you've finished setting up your ESP32-S3 Feather with CircuitPython, you can access the code and necessary libraries by downloading the Project Bundle.

To do this, click on the Download Project Bundle button in the window below. It will download to your computer as a zipped folder.

Download Project Bundle

Copy Code

# SPDX-FileCopyrightText: 2024 Liz Clark for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import gc
import board
import displayio
import fourwire
import terminalio
import adafruit_ble
from adafruit_ble.advertising.standard import SolicitServicesAdvertisement
from adafruit_ble_apple_media import AppleMediaService
from adafruit_bitmap_font import bitmap_font
from adafruit_button import Button
from adafruit_display_text import label, wrap_text_to_lines
import adafruit_hx8357
import adafruit_tsc2007

gc.collect()
displayio.release_displays()
small_font = bitmap_font.load_font("/Arial-16.bdf")

# display
spi = board.SPI()
tft_cs = board.D9
tft_dc = board.D10
display_bus = fourwire.FourWire(spi, command=tft_dc, chip_select=tft_cs)
display = adafruit_hx8357.HX8357(display_bus, width=480, height=320)
# touch
i2c = board.I2C()
tsc = adafruit_tsc2007.TSC2007(i2c, invert_x=True, swap_xy=True)
splash = displayio.Group()

def ble_media_command(conn, command):
    gc.collect()
    # print("function started")
    if not conn.paired:
        print("trying to pair")
        conn.pair()
        print("paired")
    # print("connected, getting ready")
    ams = conn[AppleMediaService]
    # print(ams)
    tries = 10
    for i in range(tries):
        try:
            # print("sending..")
            if command != "refresh":
                command(ams)
            time.sleep(2)
            # print("sent")
            song_text = f"{ams.title}"
            song_text = "\n".join(wrap_text_to_lines(song_text, 29))
            song_label.text = song_text
            album_label.text = f"Album: {ams.album}"
            artist_label.text = f"Artist: {ams.artist}"
            app_label.text = f"App: {ams.player_name}"
            if ams.playing:
                buttons[0].label = "Pause"
            elif ams.paused:
                buttons[0].label = "Play"
        except Exception as error: # pylint: disable = broad-except
            print(error)
            # time.sleep(2)
            if i < tries - 1:
                continue
        break
    gc.collect()

connection = None

# commands
commands = [
    lambda ams: ams.toggle_play_pause(),
    lambda ams: ams.next_track(),
    lambda ams: ams.previous_track(),
    lambda ams: ams.advance_repeat_mode(),
    lambda ams: ams.advance_shuffle_mode(),
    lambda ams: ams.volume_up(),
    lambda ams: ams.volume_down(),
]

# colors
RED = (255, 0, 0)
ORANGE = (255, 34, 0)
YELLOW = (255, 170, 0)
GREEN = (0, 255, 0)
CYAN = (0, 255, 255)
BLUE = (0, 0, 255)
VIOLET = (153, 0, 255)
MAGENTA = (255, 0, 51)
PINK = (255, 51, 119)
AQUA = (85, 125, 255)
WHITE = (255, 255, 255)
OFF = (0, 0, 0)

gc.collect()
spots = [
    {'label': "Play/Pause", 'font': small_font,
     'pos': ((display.width // 2) - 60, display.height - 70),
     'size': (120, 60), 'color': RED,
     'control': lambda: ble_media_command(connection, commands[0])},
    {'label': ">>", 'font': small_font,
     'pos': ((display.width // 2) + 70, display.height - 70),
     'size': (60, 60), 'color': ORANGE,
     'control': lambda: ble_media_command(connection, commands[1])},
    {'label': "<<", 'font': small_font,
     'pos': ((display.width // 2) - 130, display.height - 70),
     'size': (60, 60), 'color': YELLOW,
     'control': lambda: ble_media_command(connection, commands[2])},
    {'label': "Repeat", 'font': terminalio.FONT,
     'pos': (10, 250), 'size': (60, 60), 'color': GREEN,
     'control': lambda: ble_media_command(connection, commands[3])},
    {'label': "Shuffle", 'font': terminalio.FONT,
     'pos': (410, 250), 'size': (60, 60), 'color': CYAN,
     'control': lambda: ble_media_command(connection, commands[4])},
    {'label': "Vol +", 'font': small_font, 'pos': (10, 10), 'size': (60, 120), 'color': BLUE,
     'control': lambda: ble_media_command(connection, commands[5])},
    {'label': "Vol -", 'font': small_font, 'pos': (410, 10), 'size': (60, 120), 'color': VIOLET,
     'control': lambda: ble_media_command(connection, commands[6])},
    {'label': "Refresh", 'font': small_font, 'pos': (70, 10), 'size': (340, display.height - 80),
     'color': None, 'control': lambda: ble_media_command(connection, "refresh")},
    ]

buttons = []
for spot in spots:
    button = Button(x=spot['pos'][0], y=spot['pos'][1],
                    width=spot['size'][0], height=spot['size'][1],
                    label=spot['label'], label_font=spot['font'],
                    style=Button.ROUNDRECT,
                    fill_color=spot['color'],
                    name=spot['label'])
    splash.append(button)
    buttons.append(button)

header_label = label.Label(small_font, text="Now Playing:", color=WHITE)
header_label.anchor_point = (0.5, 0.0)
header_label.anchored_position = (display.width / 2, 10)
splash.append(header_label)

song_label = label.Label(small_font, text=" ", color=WHITE)
song_label.anchor_point = (0.5, 0.0)
song_label.anchored_position = (display.width / 2, 40)
splash.append(song_label)
artist_label = label.Label(small_font, text="Artist: ", color=WHITE)
artist_label.anchor_point = (0.5, 0.0)
artist_label.anchored_position = (display.width / 2, 124)
splash.append(artist_label)
album_label = label.Label(small_font, text="Album: ", color=WHITE)
album_label.anchor_point = (0.5, 0.0)
album_label.anchored_position = (display.width / 2, 154)
splash.append(album_label)
app_label = label.Label(small_font, text="App: ", color=WHITE)
app_label.anchor_point = (0.5, 0.0)
app_label.anchored_position = (display.width / 2, 184)
splash.append(app_label)

touch_state = False

display.root_group = splash

def scale_touch_coordinates(raw_x, raw_y):
    # raw coordinate ranges
    raw_x_min = 275
    raw_x_max = 3900
    raw_y_min = 487
    raw_y_max = 3800
    # scale the raw coordinates to display coordinates
    display_x = (raw_x - raw_x_min) * display.width / (raw_x_max - raw_x_min)
    display_y = (raw_y - raw_y_min) * display.height / (raw_y_max - raw_y_min)
    # clamp values to ensure they stay within display bounds
    display_x = max(0, min(display_x, display.width))
    display_y = max(0, min(display_y, display.height))
    return int(display_x), int(display_y)

gc.collect()
# PyLint can't find BLERadio for some reason so special case it here.
radio = adafruit_ble.BLERadio()  # pylint: disable=no-member
a = SolicitServicesAdvertisement()
a.solicited_services.append(AppleMediaService)
if not radio.connected:
    print("advertising")
    radio.start_advertising(a)
else:
    print("already connected")
    print(radio.connected)
print(gc.mem_free())

while True:
    while not radio.connected:
        pass
    known_notifications = set()
    while radio.connected:
        if tsc.touched and not touch_state:
            gc.collect()
            touch_state = True
            p = tsc.touch
            point = scale_touch_coordinates(p["x"], p["y"])
            connection = radio.connections[0]
            for button in buttons:
                b = buttons.index(button)
                if button.contains(point):
                    print(gc.mem_free())
                    print("Touched", button.name)
                    spots[b]['control']()
        if not tsc.touched and touch_state:
            touch_state = False
    print("disconnected")
    print("advertising")
    radio.start_advertising(a)
    print("reconnected")

# SPDX-FileCopyrightText: 2024 Liz Clark for Adafruit Industries
# SPDX-License-Identifier: MIT

import time
import gc
import board
import displayio
import fourwire
import terminalio
import adafruit_ble
from adafruit_ble.advertising.standard import SolicitServicesAdvertisement
from adafruit_ble_apple_media import AppleMediaService
from adafruit_bitmap_font import bitmap_font
from adafruit_button import Button
from adafruit_display_text import label, wrap_text_to_lines
import adafruit_hx8357
import adafruit_tsc2007

gc.collect()
displayio.release_displays()
small_font = bitmap_font.load_font("/Arial-16.bdf")

# display
spi = board.SPI()
tft_cs = board.D9
tft_dc = board.D10
display_bus = fourwire.FourWire(spi, command=tft_dc, chip_select=tft_cs)
display = adafruit_hx8357.HX8357(display_bus, width=480, height=320)
# touch
i2c = board.I2C()
tsc = adafruit_tsc2007.TSC2007(i2c, invert_x=True, swap_xy=True)
splash = displayio.Group()

def ble_media_command(conn, command):
    gc.collect()
    # print("function started")
    if not conn.paired:
        print("trying to pair")
        conn.pair()
        print("paired")
    # print("connected, getting ready")
    ams = conn[AppleMediaService]
    # print(ams)
    tries = 10
    for i in range(tries):
        try:
            # print("sending..")
            if command != "refresh":
                command(ams)
            time.sleep(2)
            # print("sent")
            song_text = f"{ams.title}"
            song_text = "\n".join(wrap_text_to_lines(song_text, 29))
            song_label.text = song_text
            album_label.text = f"Album: {ams.album}"
            artist_label.text = f"Artist: {ams.artist}"
            app_label.text = f"App: {ams.player_name}"
            if ams.playing:
                buttons[0].label = "Pause"
            elif ams.paused:
                buttons[0].label = "Play"
        except Exception as error: # pylint: disable = broad-except
            print(error)
            # time.sleep(2)
            if i < tries - 1:
                continue
        break
    gc.collect()

connection = None

# commands
commands = [
    lambda ams: ams.toggle_play_pause(),
    lambda ams: ams.next_track(),
    lambda ams: ams.previous_track(),
    lambda ams: ams.advance_repeat_mode(),
    lambda ams: ams.advance_shuffle_mode(),
    lambda ams: ams.volume_up(),
    lambda ams: ams.volume_down(),
]

# colors
RED = (255, 0, 0)
ORANGE = (255, 34, 0)
YELLOW = (255, 170, 0)
GREEN = (0, 255, 0)
CYAN = (0, 255, 255)
BLUE = (0, 0, 255)
VIOLET = (153, 0, 255)
MAGENTA = (255, 0, 51)
PINK = (255, 51, 119)
AQUA = (85, 125, 255)
WHITE = (255, 255, 255)
OFF = (0, 0, 0)

gc.collect()
spots = [
    {'label': "Play/Pause", 'font': small_font,
     'pos': ((display.width // 2) - 60, display.height - 70),
     'size': (120, 60), 'color': RED,
     'control': lambda: ble_media_command(connection, commands[0])},
    {'label': ">>", 'font': small_font,
     'pos': ((display.width // 2) + 70, display.height - 70),
     'size': (60, 60), 'color': ORANGE,
     'control': lambda: ble_media_command(connection, commands[1])},
    {'label': "<<", 'font': small_font,
     'pos': ((display.width // 2) - 130, display.height - 70),
     'size': (60, 60), 'color': YELLOW,
     'control': lambda: ble_media_command(connection, commands[2])},
    {'label': "Repeat", 'font': terminalio.FONT,
     'pos': (10, 250), 'size': (60, 60), 'color': GREEN,
     'control': lambda: ble_media_command(connection, commands[3])},
    {'label': "Shuffle", 'font': terminalio.FONT,
     'pos': (410, 250), 'size': (60, 60), 'color': CYAN,
     'control': lambda: ble_media_command(connection, commands[4])},
    {'label': "Vol +", 'font': small_font, 'pos': (10, 10), 'size': (60, 120), 'color': BLUE,
     'control': lambda: ble_media_command(connection, commands[5])},
    {'label': "Vol -", 'font': small_font, 'pos': (410, 10), 'size': (60, 120), 'color': VIOLET,
     'control': lambda: ble_media_command(connection, commands[6])},
    {'label': "Refresh", 'font': small_font, 'pos': (70, 10), 'size': (340, display.height - 80),
     'color': None, 'control': lambda: ble_media_command(connection, "refresh")},
    ]

buttons = []
for spot in spots:
    button = Button(x=spot['pos'][0], y=spot['pos'][1],
                    width=spot['size'][0], height=spot['size'][1],
                    label=spot['label'], label_font=spot['font'],
                    style=Button.ROUNDRECT,
                    fill_color=spot['color'],
                    name=spot['label'])
    splash.append(button)
    buttons.append(button)

header_label = label.Label(small_font, text="Now Playing:", color=WHITE)
header_label.anchor_point = (0.5, 0.0)
header_label.anchored_position = (display.width / 2, 10)
splash.append(header_label)

song_label = label.Label(small_font, text=" ", color=WHITE)
song_label.anchor_point = (0.5, 0.0)
song_label.anchored_position = (display.width / 2, 40)
splash.append(song_label)
artist_label = label.Label(small_font, text="Artist: ", color=WHITE)
artist_label.anchor_point = (0.5, 0.0)
artist_label.anchored_position = (display.width / 2, 124)
splash.append(artist_label)
album_label = label.Label(small_font, text="Album: ", color=WHITE)
album_label.anchor_point = (0.5, 0.0)
album_label.anchored_position = (display.width / 2, 154)
splash.append(album_label)
app_label = label.Label(small_font, text="App: ", color=WHITE)
app_label.anchor_point = (0.5, 0.0)
app_label.anchored_position = (display.width / 2, 184)
splash.append(app_label)

touch_state = False

display.root_group = splash

def scale_touch_coordinates(raw_x, raw_y):
    # raw coordinate ranges
    raw_x_min = 275
    raw_x_max = 3900
    raw_y_min = 487
    raw_y_max = 3800
    # scale the raw coordinates to display coordinates
    display_x = (raw_x - raw_x_min) * display.width / (raw_x_max - raw_x_min)
    display_y = (raw_y - raw_y_min) * display.height / (raw_y_max - raw_y_min)
    # clamp values to ensure they stay within display bounds
    display_x = max(0, min(display_x, display.width))
    display_y = max(0, min(display_y, display.height))
    return int(display_x), int(display_y)

gc.collect()
# PyLint can't find BLERadio for some reason so special case it here.
radio = adafruit_ble.BLERadio()  # pylint: disable=no-member
a = SolicitServicesAdvertisement()
a.solicited_services.append(AppleMediaService)
if not radio.connected:
    print("advertising")
    radio.start_advertising(a)
else:
    print("already connected")
    print(radio.connected)
print(gc.mem_free())

while True:
    while not radio.connected:
        pass
    known_notifications = set()
    while radio.connected:
        if tsc.touched and not touch_state:
            gc.collect()
            touch_state = True
            p = tsc.touch
            point = scale_touch_coordinates(p["x"], p["y"])
            connection = radio.connections[0]
            for button in buttons:
                b = buttons.index(button)
                if button.contains(point):
                    print(gc.mem_free())
                    print("Touched", button.name)
                    spots[b]['control']()
        if not tsc.touched and touch_state:
            touch_state = False
    print("disconnected")
    print("advertising")
    radio.start_advertising(a)
    print("reconnected")

Upload the Code, Font File, and Libraries to the ESP32-S3 Feather

After downloading the Project Bundle, plug your ESP32-S3 Feather into the computer's USB port with a known good USB data+power cable. You should see a new flash drive appear in the computer's File Explorer or Finder (depending on your operating system) called CIRCUITPY. Unzip the folder and copy the following items to the Feather's CIRCUITPY drive:

lib folder
Arial-16.bdf
code.py

Your ESP32-S3 Feather CIRCUITPY drive should look like this after copying the lib folder, Arial-16.bdf font file and the code.py file.

How the CircuitPython Code Works

The code begins by initializing the display and I2C touch driver.

Download File

Copy Code

# display
spi = board.SPI()
tft_cs = board.D9
tft_dc = board.D10
display_bus = fourwire.FourWire(spi, command=tft_dc, chip_select=tft_cs)
display = adafruit_hx8357.HX8357(display_bus, width=480, height=320)
# touch
i2c = board.I2C()
tsc = adafruit_tsc2007.TSC2007(i2c, invert_x=True, swap_xy=True)
splash = displayio.Group()

# display
spi = board.SPI()
tft_cs = board.D9
tft_dc = board.D10
display_bus = fourwire.FourWire(spi, command=tft_dc, chip_select=tft_cs)
display = adafruit_hx8357.HX8357(display_bus, width=480, height=320)
# touch
i2c = board.I2C()
tsc = adafruit_tsc2007.TSC2007(i2c, invert_x=True, swap_xy=True)
splash = displayio.Group()

Sending BLE Controls

The ble_media_command() function takes care of sending and receiving BLE messages to your Apple device. Whenever the function is called, the now playing information is updated for the text elements on the display.

Download File

Copy Code

def ble_media_command(conn, command):
    gc.collect()
    # print("function started")
    if not conn.paired:
        print("trying to pair")
        conn.pair()
        print("paired")
    # print("connected, getting ready")
    ams = conn[AppleMediaService]
    # print(ams)
    tries = 10
    for i in range(tries):
        try:
            # print("sending..")
            if command != "refresh":
                command(ams)
            time.sleep(2)
            # print("sent")
            song_text = f"{ams.title}"
            song_text = "\n".join(wrap_text_to_lines(song_text, 29))
            song_label.text = song_text
            album_label.text = f"Album: {ams.album}"
            artist_label.text = f"Artist: {ams.artist}"
            app_label.text = f"App: {ams.player_name}"
            if ams.playing:
                buttons[0].label = "Pause"
            elif ams.paused:
                buttons[0].label = "Play"
        except Exception as error: # pylint: disable = broad-except
            print(error)
            # time.sleep(2)
            if i < tries - 1:
                continue
        break
    gc.collect()

def ble_media_command(conn, command):
    gc.collect()
    # print("function started")
    if not conn.paired:
        print("trying to pair")
        conn.pair()
        print("paired")
    # print("connected, getting ready")
    ams = conn[AppleMediaService]
    # print(ams)
    tries = 10
    for i in range(tries):
        try:
            # print("sending..")
            if command != "refresh":
                command(ams)
            time.sleep(2)
            # print("sent")
            song_text = f"{ams.title}"
            song_text = "\n".join(wrap_text_to_lines(song_text, 29))
            song_label.text = song_text
            album_label.text = f"Album: {ams.album}"
            artist_label.text = f"Artist: {ams.artist}"
            app_label.text = f"App: {ams.player_name}"
            if ams.playing:
                buttons[0].label = "Pause"
            elif ams.paused:
                buttons[0].label = "Play"
        except Exception as error: # pylint: disable = broad-except
            print(error)
            # time.sleep(2)
            if i < tries - 1:
                continue
        break
    gc.collect()

List of Commands

The commands list uses lambda to store the Apple Media Service control functions before the BLE connection is established.

Download File

Copy Code

# commands
commands = [
    lambda ams: ams.toggle_play_pause(),
    lambda ams: ams.next_track(),
    lambda ams: ams.previous_track(),
    lambda ams: ams.advance_repeat_mode(),
    lambda ams: ams.advance_shuffle_mode(),
    lambda ams: ams.volume_up(),
    lambda ams: ams.volume_down(),
]

# commands
commands = [
    lambda ams: ams.toggle_play_pause(),
    lambda ams: ams.next_track(),
    lambda ams: ams.previous_track(),
    lambda ams: ams.advance_repeat_mode(),
    lambda ams: ams.advance_shuffle_mode(),
    lambda ams: ams.volume_up(),
    lambda ams: ams.volume_down(),
]

Dictionary of Buttons

The functions are assigned to buttons in the spots dictionary. This allows each button to send an assigned BLE control in the loop alongside the ble_media_command() function. The button labels denote their function and associated BLE control.

The last button, 'Refresh', uses None as the color, making it transparent. If you touch the area of the screen that contains the now playing info, a call is made to only fetch the artist, media, album and app information.

Download File

Copy Code

spots = [
    {'label': "Play/Pause", 'font': small_font,
     'pos': ((display.width // 2) - 60, display.height - 70),
     'size': (120, 60), 'color': RED,
     'control': lambda: ble_media_command(connection, commands[0])},
    {'label': ">>", 'font': small_font,
     'pos': ((display.width // 2) + 70, display.height - 70),
     'size': (60, 60), 'color': ORANGE,
     'control': lambda: ble_media_command(connection, commands[1])},
    {'label': "<<", 'font': small_font,
     'pos': ((display.width // 2) - 130, display.height - 70),
     'size': (60, 60), 'color': YELLOW,
     'control': lambda: ble_media_command(connection, commands[2])},
    {'label': "Repeat", 'font': terminalio.FONT,
     'pos': (10, 250), 'size': (60, 60), 'color': GREEN,
     'control': lambda: ble_media_command(connection, commands[3])},
    {'label': "Shuffle", 'font': terminalio.FONT,
     'pos': (410, 250), 'size': (60, 60), 'color': CYAN,
     'control': lambda: ble_media_command(connection, commands[4])},
    {'label': "Vol +", 'font': small_font, 'pos': (10, 10), 'size': (60, 120), 'color': BLUE,
     'control': lambda: ble_media_command(connection, commands[5])},
    {'label': "Vol -", 'font': small_font, 'pos': (410, 10), 'size': (60, 120), 'color': VIOLET,
     'control': lambda: ble_media_command(connection, commands[6])},
    {'label': "Refresh", 'font': small_font, 'pos': (70, 10), 'size': (340, display.height - 80),
     'color': None, 'control': lambda: ble_media_command(connection, "refresh")},
    ]

spots = [
    {'label': "Play/Pause", 'font': small_font,
     'pos': ((display.width // 2) - 60, display.height - 70),
     'size': (120, 60), 'color': RED,
     'control': lambda: ble_media_command(connection, commands[0])},
    {'label': ">>", 'font': small_font,
     'pos': ((display.width // 2) + 70, display.height - 70),
     'size': (60, 60), 'color': ORANGE,
     'control': lambda: ble_media_command(connection, commands[1])},
    {'label': "<<", 'font': small_font,
     'pos': ((display.width // 2) - 130, display.height - 70),
     'size': (60, 60), 'color': YELLOW,
     'control': lambda: ble_media_command(connection, commands[2])},
    {'label': "Repeat", 'font': terminalio.FONT,
     'pos': (10, 250), 'size': (60, 60), 'color': GREEN,
     'control': lambda: ble_media_command(connection, commands[3])},
    {'label': "Shuffle", 'font': terminalio.FONT,
     'pos': (410, 250), 'size': (60, 60), 'color': CYAN,
     'control': lambda: ble_media_command(connection, commands[4])},
    {'label': "Vol +", 'font': small_font, 'pos': (10, 10), 'size': (60, 120), 'color': BLUE,
     'control': lambda: ble_media_command(connection, commands[5])},
    {'label': "Vol -", 'font': small_font, 'pos': (410, 10), 'size': (60, 120), 'color': VIOLET,
     'control': lambda: ble_media_command(connection, commands[6])},
    {'label': "Refresh", 'font': small_font, 'pos': (70, 10), 'size': (340, display.height - 80),
     'color': None, 'control': lambda: ble_media_command(connection, "refresh")},
    ]

Display Attributes

The buttons are instantiated with entries from the spots dictionary and then added to the splash display group and buttons array.

Download File

Copy Code

buttons = []
for spot in spots:
    button = Button(x=spot['pos'][0], y=spot['pos'][1],
                    width=spot['size'][0], height=spot['size'][1],
                    label=spot['label'], label_font=spot['font'],
                    style=Button.ROUNDRECT,
                    fill_color=spot['color'],
                    name=spot['label'])
    splash.append(button)
    buttons.append(button)

buttons = []
for spot in spots:
    button = Button(x=spot['pos'][0], y=spot['pos'][1],
                    width=spot['size'][0], height=spot['size'][1],
                    label=spot['label'], label_font=spot['font'],
                    style=Button.ROUNDRECT,
                    fill_color=spot['color'],
                    name=spot['label'])
    splash.append(button)
    buttons.append(button)

Text labels are used for the "Now Playing" header and media title, artist title, album title and app name. They are centered on the display using anchor_point and anchored_position.

Download File

Copy Code

header_label = label.Label(small_font, text="Now Playing:", color=WHITE)
header_label.anchor_point = (0.5, 0.0)
header_label.anchored_position = (display.width / 2, 10)
splash.append(header_label)

song_label = label.Label(small_font, text=" ", color=WHITE)
song_label.anchor_point = (0.5, 0.0)
song_label.anchored_position = (display.width / 2, 40)
splash.append(song_label)
artist_label = label.Label(small_font, text="Artist: ", color=WHITE)
artist_label.anchor_point = (0.5, 0.0)
artist_label.anchored_position = (display.width / 2, 124)
splash.append(artist_label)
album_label = label.Label(small_font, text="Album: ", color=WHITE)
album_label.anchor_point = (0.5, 0.0)
album_label.anchored_position = (display.width / 2, 154)
splash.append(album_label)
app_label = label.Label(small_font, text="App: ", color=WHITE)
app_label.anchor_point = (0.5, 0.0)
app_label.anchored_position = (display.width / 2, 184)
splash.append(app_label)

header_label = label.Label(small_font, text="Now Playing:", color=WHITE)
header_label.anchor_point = (0.5, 0.0)
header_label.anchored_position = (display.width / 2, 10)
splash.append(header_label)

song_label = label.Label(small_font, text=" ", color=WHITE)
song_label.anchor_point = (0.5, 0.0)
song_label.anchored_position = (display.width / 2, 40)
splash.append(song_label)
artist_label = label.Label(small_font, text="Artist: ", color=WHITE)
artist_label.anchor_point = (0.5, 0.0)
artist_label.anchored_position = (display.width / 2, 124)
splash.append(artist_label)
album_label = label.Label(small_font, text="Album: ", color=WHITE)
album_label.anchor_point = (0.5, 0.0)
album_label.anchored_position = (display.width / 2, 154)
splash.append(album_label)
app_label = label.Label(small_font, text="App: ", color=WHITE)
app_label.anchor_point = (0.5, 0.0)
app_label.anchored_position = (display.width / 2, 184)
splash.append(app_label)

Scaling Touch

The TSC2007 touch driver has a large range of touch coordinates that aren't necessarily tied to the display coordinates. The scale_touch_coordinates() function scales the TSC2007 coordinates so that they match the display coordinates.

Download File

Copy Code

def scale_touch_coordinates(raw_x, raw_y):
    # raw coordinate ranges
    raw_x_min = 275
    raw_x_max = 3900
    raw_y_min = 487
    raw_y_max = 3800
    # scale the raw coordinates to display coordinates
    display_x = (raw_x - raw_x_min) * display.width / (raw_x_max - raw_x_min)
    display_y = (raw_y - raw_y_min) * display.height / (raw_y_max - raw_y_min)
    # clamp values to ensure they stay within display bounds
    display_x = max(0, min(display_x, display.width))
    display_y = max(0, min(display_y, display.height))
    return int(display_x), int(display_y)

def scale_touch_coordinates(raw_x, raw_y):
    # raw coordinate ranges
    raw_x_min = 275
    raw_x_max = 3900
    raw_y_min = 487
    raw_y_max = 3800
    # scale the raw coordinates to display coordinates
    display_x = (raw_x - raw_x_min) * display.width / (raw_x_max - raw_x_min)
    display_y = (raw_y - raw_y_min) * display.height / (raw_y_max - raw_y_min)
    # clamp values to ensure they stay within display bounds
    display_x = max(0, min(display_x, display.width))
    display_y = max(0, min(display_y, display.height))
    return int(display_x), int(display_y)

Ready for Takeoff

Right before the loop, the BLE connection is advertised and a connection is initialized.

Download File

Copy Code

radio = adafruit_ble.BLERadio()  # pylint: disable=no-member
a = SolicitServicesAdvertisement()
a.solicited_services.append(AppleMediaService)
if not radio.connected:
    print("advertising")
    radio.start_advertising(a)
else:
    print("already connected")
    print(radio.connected)
print(gc.mem_free())

radio = adafruit_ble.BLERadio()  # pylint: disable=no-member
a = SolicitServicesAdvertisement()
a.solicited_services.append(AppleMediaService)
if not radio.connected:
    print("advertising")
    radio.start_advertising(a)
else:
    print("already connected")
    print(radio.connected)
print(gc.mem_free())

The Loop

In the loop, if the touchscreen is touched, its coordinates are scaled to the display coordinates. If one of the buttons is touched, then the associated BLE command is sent with spots[b]['control'](). This is possible because lambda is used in both the commands array and the 'control' entry of the spots dictionary.

If the BLE connection is lost, then the board tries to reconnect by advertising again.

Download File

Copy Code

while True:
    while not radio.connected:
        pass
    known_notifications = set()
    while radio.connected:
        if tsc.touched and not touch_state:
            gc.collect()
            touch_state = True
            p = tsc.touch
            point = scale_touch_coordinates(p["x"], p["y"])
            connection = radio.connections[0]
            for button in buttons:
                b = buttons.index(button)
                if button.contains(point):
                    print(gc.mem_free())
                    print("Touched", button.name)
                    spots[b]['control']()
        if not tsc.touched and touch_state:
            touch_state = False
    print("disconnected")
    print("advertising")
    radio.start_advertising(a)
    print("reconnected")

while True:
    while not radio.connected:
        pass
    known_notifications = set()
    while radio.connected:
        if tsc.touched and not touch_state:
            gc.collect()
            touch_state = True
            p = tsc.touch
            point = scale_touch_coordinates(p["x"], p["y"])
            connection = radio.connections[0]
            for button in buttons:
                b = buttons.index(button)
                if button.contains(point):
                    print(gc.mem_free())
                    print("Touched", button.name)
                    spots[b]['control']()
        if not tsc.touched and touch_state:
            touch_state = False
    print("disconnected")
    print("advertising")
    radio.start_advertising(a)
    print("reconnected")

Page last edited July 23, 2024

Text editor powered by tinymce.

CAD Files

3D Printed Parts

STL files for 3D printing are oriented to print "as-is" on FDM style machines. Parts are designed to 3D print without any support material using PLA filament. Original design source may be downloaded using the links below.

Download CAD Source Files

Download STLs.zip

Build Volume

The parts require a 3D printer with a minimum build volume.

96mm (X) x 74mm (Y) x 94mm (Z)

CAD Assembly

The Feather ESP32-S3 plugs into the socket headers on the back of the 3.5in TFT FeatherWing. M2.5 standoffs are secured to the mounting tabs on the TFT FeatherWing with M2.5 x 6mm long screws. The M2.5 standoffs are secured to the mounting holes on the stand using hex nuts.

Design Source Files

The project assembly was designed in Fusion 360. This can be downloaded in different formats like STEP, STL and more.

Electronic components like Adafruit's boards, displays, connectors and more can be downloaded from the Adafruit CAD parts GitHub Repo.

Page last edited July 23, 2024

Text editor powered by tinymce.

Assembly

Feather Headers

Use a 1x12 and 1x16 male header pins for the Feather ESP32-S3.

A breadboard can help to keep the headers straight while soldering.

Solder all of the male header pins to the Feather ESP32-S3.

Install Feather to TFT Display

Orient the Feather with the 3.5in TFT FeatherWing so the pins line up properly.

Firmly press the pins into the TFT FeatherWing's socket headers.

Hardware

Use the following hardware to secure the 3.5in TFT FeahterWing to the 3D printed stand.

4x M2.5 x 6mm long screws
4x M2.5 x 6mm long M-F hex standoffs
4x M2.5 hex nuts

Install Hardware to TFT Display

Insert the M2.5 x 6mm long screws through the four mounting tabs on the TFT Display.

Insert and fasten the four M2.5 standoffs onto the screws.

Repeat the hardware installation for the four mounting tabs.

Install TFT to Stand

Orient the TFT display with the 3D printed stand so the USB-C port is pointing in the correct direction.

Press the screws from the standoffs through the four mounting holes on the 3D printed stand.

Secure TFT to Stand

Insert and fasten the M2.5 hex nuts onto the standoffs to secure the TFT display to the 3D printed stand.

USB Power

Connect the Feather ESP32-S3 to a 5V 1A power supply to power on the device.

Congratulations on your build!

Page last edited July 23, 2024

Text editor powered by tinymce.

Usage

iOS Bluetooth Devices

To connect to the Feather ESP32-S3 on an iOS device, go to the Setting app and tab on Bluetooth.

Search under the OTHER DEVICES category for a device named CIRCUITPYxxx and tap to start the connection process.

Pairing with Bluetooth

Once the connection has ben established, tap on the Pair button in the Bluetooth Pairing Request dialog.

Connected Bluetooth Device

The CIRCUITPY device will now be connected to your iOS device.

To disconnect the Feather ESP32-S3 from your iOS device, you can tap on the info icon next to the device name and then tap on the Forget This Device button.