Skip to content

Commit 460f396

Browse files
Electric-DiversionsElectric-Diversions
authored
V2.0.0 Initial Release: Complete Spotify Controller for ESP32 with UI and Album Art Support (#1)
* Initial commit for V2.0.0 * Update README and supporting files for 2.0.0 release. * Pin platform to specific version. Minor updates to README and design diagram. * Batch of enhancements and fixes: optional user.ini support, filesystem check, improved Spotify messaging * Add default support for ESP-WROVER-B and dynamic art cache sizing * Use esp-wrover-kit as default board config * Expand README.md documentation. Add details on User Settings. * Cleaned up inline comments and formatting in multiple files * Add config info to Diagnostics view; switch SpotifyArduino to use lateInit() with a global instance * Update custom board comment * Fix issue with ads causing a fatal error. * Add Tips and Known Issues. Minor code cleanup. * Add support for international date/time formatting
1 parent 583d6b6 commit 460f396

File tree

95 files changed

+13046
-4411
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

95 files changed

+13046
-4411
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
.pio
22
.vscode
3+
src/compile_time.h
4+
data/user.ini

‎README.md

Lines changed: 98 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,23 @@
44

55
Spotify controller application for the [ThingPulse Color Kit Grande](https://thingpulse.com/product/esp32-wifi-color-display-kit-grande/).
66

7-
[![Color Kit Grande with sample application: weather station](https://thingpulse.com/wp-content/uploads/2022/10/ThingPulse-Color-Kit-Grand-with-sample-application.jpg)](https://thingpulse.com/product/esp32-wifi-color-display-kit-grande/)
7+
<!-- Main image -->
8+
<a href="./images/HomeView.jpg">
9+
<img src="./images/HomeView.jpg" alt="HomeView UI Example" width="600"/>
10+
</a>
11+
12+
<!-- Thumbnails -->
13+
<p>
14+
<a href="./images/CoverArtView.jpg">
15+
<img src="./images/CoverArtView.jpg" alt="Cover View" width="200"/>
16+
</a>
17+
<a href="./images/ClockView.jpg">
18+
<img src="./images/ClockView.jpg" alt="Clock View" width="200"/>
19+
</a>
20+
<a href="./images/DiagnosticView.jpg">
21+
<img src="./images/DiagnosticView.jpg" alt="Diagnostic View" width="200"/>
22+
</a>
23+
</p>
824

925
## Purpose of this project
1026

@@ -15,11 +31,53 @@ The currently playing song can be paused, resumed and skipped to the next or pre
1531
A full OAuth 2.0 web flow is used to acquire the necessary access and refresh tokens to permit the user to control the player.
1632
In order to run this project on your device, you will need to setup an application on your Spotify dashboard (instructions below).
1733

18-
## Features
34+
## Features
1935

20-
- Artwork download
21-
- Control player on touch screen: play, Pause, next, prev
22-
- Authentication and authorization (OAuth 2.0 flow) on device.
36+
- **Spotify Playback Control**
37+
- Play, pause, skip to next/previous track from the touch screen
38+
- Control playback on any active Spotify Connect device linked to your account (e.g., phone, browser, smart speaker)
39+
40+
- **Album Art Display**
41+
- Downloads and displays album artwork via Spotify Web API
42+
- Syncs background color with album art
43+
- Caches artwork locally for performance
44+
45+
- **Multiple UI Modes**
46+
- Home view with track metadata and album art
47+
- Cover Art only view
48+
- Clock view with time and playback progress
49+
- Supports 12-hour and 24-hour time formats
50+
- Diagnostics view with system stats and Spotify state
51+
52+
- **OAuth 2.0 Authorization Flow**
53+
- Authentication and authorization (OAuth 2.0 flow) on device
54+
55+
- **Designed for ESP32 + TFT Touch**
56+
- Built using PlatformIO and Arduino
57+
- Touch event handling for UI buttons and screen navigation
58+
- Takes advantage of ESP32 dual-core architecture: UI logic runs on one core and background song and album art refreshing runs on the other
59+
60+
- **Extensible Design**
61+
- Modular architecture allows easy addition of new Views (UI screens)
62+
- Built-in monitoring tools for measuring system performance and UI responsiveness
63+
- Structured and tag-based logging system for easier debugging and analysis
64+
- Optional `user.ini` file for easy credential and time zone management
65+
66+
67+
<!--Design Context Diagram -->
68+
<a href="./documentation/SCDesign.jpg">
69+
<img src="./documentation/SCDesign.jpg" alt="Design" width="600"/>
70+
</a>
71+
72+
## Using the Spotify Controller
73+
74+
- Tap the **Prev**, **Pause/Play**, and **Next** buttons to control music playback.
75+
- Tap the **album art** on the Home view to switch to the **Cover Art view**.
76+
- Tap the **clock** to switch to the **Clock view**.
77+
- Tap the **network status box** in the lower-right corner to open the **Diagnostics view**.
78+
- Tap the top-left corner for **Prev**, the top-center for **Pause/Play**, and the top-right for **Next** when using views other than Home.
79+
80+
> For detailed display logic and diagnostics layout, see `DiagnosticsView.cpp`.
2381
2482
## Service level promise
2583

@@ -37,28 +95,52 @@ See our [instructions](https://docs.thingpulse.com/guides/esp32-color-kit-grande
3795

3896
1. Go to [https://developer.spotify.com/dashboard/login](https://developer.spotify.com/dashboard/login) and login to or sign up for the Spotify Developer Dashboard
3997

40-
2. Select "My New App"
98+
2. Select "Create app"
4199

42100
<img src="./images/SpotifyDashboard.png" width="400">
43101

44102
3. Fill out the form. Give your new app a name you can attribute to this project.
45103
It's safe to select "I don't know" for the type of application.
104+
Add "http://tp-spotify.local/callback/" to the Redirect URIs section.
105+
106+
**NOTE** If you are running more than ThingPulse Spotify Remote in the same WiFi network, you should choose a unique name rather than "tp-spotify". Regardless of what you choose it has to reflect what you set for `SPOTIFY_ESPOTIFIER_NODE_NAME` in `spotify.h` in the project.
107+
108+
<img src="./images/SpotifyCreateApp.png" width="400">
109+
110+
**Don't forget to save your settings.**
111+
112+
4. Set the unique Client ID and Client Secret as values for the respective variables in `src/spotify.h`.
113+
114+
<img src="./images/SpotifyClientId.png" width="400">
115+
116+
### Filesystem setup
117+
118+
5. Upload the file system to the device
119+
120+
- Hit the PlatformIO icon on the navigation bar on the left side (alien face).
121+
122+
- Select the Platform > Upload Filesystem Image task. Unless you later erase the flash or modify certain files, you only need to do this once if it succeeds. Pay attention to the output in the VS Code console that opens. If it reports any errors like e.g. if it cannot connect to the board or if stops midway, close VS Code completely, restart it, and then repeat the process.
123+
124+
<img src="./images/platformio-filesystem.png" width="400">
125+
126+
- If startup fails with the following message displayed: "FATAL ERROR - Filesystem Not Initialized", this step was not successful or done.
127+
128+
### User settings
46129

47-
<img src="./images/SpotifyAppSignUp1.png" width="400">
130+
6. The fastest way to get up and running is to open the `src/settings.h` file and adjust the handful of configuration parameters in the "User settings" section at the top. They are all documented inside the file directly. Everything should be self-explanatory. The spotify settings were updated in step 4 above.
48131

49-
4. At the end of the 3 steps click "Submit"
132+
<img src="./images/UserSettings.png" width="400">
50133

51-
<img src="./images/SpotifyppSignUp3.png" width="400">
134+
See [full user settings documentation](./documentation/UserSettings.md) for details about all available fields, encryption options, and using `user.ini`.
52135

53-
5. Set the unique Client ID and Client Secret as values for the respective variables in `settings.h`.
136+
### Upload code to device
54137

55-
<img src="./images/SpotifyCredentials.png" width="400">
138+
7. Select the General > Upload and Monitor task. You do this every time you change code or settings.h.
56139

57-
6. Click on "Edit Settings". Add "http://tp-spotify.local/callback/" to the Redirect URIs section.
140+
<img src="./images/platformio-task-upload.png" width="400">
58141

59-
**NOTE** If you are running more than ThingPulse Spotify Remote in the same WiFi network, you should choose a unique name rather than "tp-spotify". Regardless of what you choose it has to reflect what you set for `SPOTIFY_ESPOTIFIER_NODE_NAME` in `settings.h` in the project.
142+
See [instructions](https://docs.thingpulse.com/guides/esp32-color-kit-grande/#development-environment) if you encounter problems and need Trouble Shooting tips.
60143

61-
<img src="./images/SpotifyAppSettings.png" width="400">
144+
## Tips and Known Issues
62145

63-
7. Don't forget to save your settings.
64-
<img src="./images/SpotifyAppSettingsSave.png" width="400">
146+
To see a list of tips and known issues, see [Tips and Known Issues](./documentation/TipsAndKnownIssues.md).

‎boards/custom_esp-wrover-kit.json

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
{
2+
"_comment": "This is a custom board configuration for an ESP32 with 8MB PSRAM. - Jan 8, 2025.",
3+
"build": {
4+
"arduino":{
5+
"ldscript": "esp32_out.ld"
6+
},
7+
"core": "esp32",
8+
"extra_flags": "-DARDUINO_ESP32_DEV",
9+
"f_cpu": "240000000L",
10+
"f_flash": "40000000L",
11+
"flash_mode": "dio",
12+
"hwids": [
13+
[
14+
"0x0403",
15+
"0x6010"
16+
]
17+
],
18+
"mcu": "esp32",
19+
"variant": "esp32"
20+
},
21+
"connectivity": [
22+
"wifi",
23+
"bluetooth",
24+
"ethernet",
25+
"can"
26+
],
27+
"debug": {
28+
"default_tool": "ftdi",
29+
"onboard_tools": [
30+
"ftdi"
31+
],
32+
"openocd_board": "esp32-wrover.cfg"
33+
},
34+
"frameworks": [
35+
"arduino",
36+
"espidf"
37+
],
38+
"name": "Espressif ESP-WROVER-KIT",
39+
"upload": {
40+
"flash_size": "8MB",
41+
"maximum_ram_size": 327680,
42+
"maximum_size": 8388608,
43+
"protocols": [
44+
"esptool",
45+
"espota",
46+
"ftdi"
47+
],
48+
"require_upload_port": true,
49+
"speed": 460800
50+
},
51+
"url": "https://espressif.com/en/products/hardware/esp-wrover-kit/overview",
52+
"vendor": "Espressif"
53+
}
54+

‎data/DefaultCoverArt.jpg

14.2 KB
Loading

‎data/user.ini.template

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
;
2+
; User settings for Spotify Controller. Make sure to Upload Filesystem
3+
; Image after updating.
4+
;
5+
; ----------------------------------------------------------------------
6+
; Privacy Levels:
7+
; 0 - None (credentials in clear text)
8+
; 1 - Good (encrypted, reusable across devices)
9+
; 2 - Better (encrypted, tied to this device)
10+
; ----------------------------------------------------------------------
11+
[vault]
12+
privacy_level = 0
13+
; ----------------------------------------------------------------------
14+
; WiFi:
15+
; ----------------------------------------------------------------------
16+
[wifi]
17+
ssid = Your WiFi Name Here
18+
password = Your WiFi Password Here
19+
; ----------------------------------------------------------------------
20+
; Spotify:
21+
; ----------------------------------------------------------------------
22+
[spotify]
23+
client_id = Enter your Spotify Client ID here
24+
client_secret = Enter your Spotify Client Secret here
25+
; ----------------------------------------------------------------------
26+
; System Settings:
27+
; Timezone format - see
28+
; https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
29+
; For US date and time formatting, include:
30+
; ui_date_time_format = US
31+
; ----------------------------------------------------------------------
32+
[system]
33+
timezone = CST6CDT,M3.2.0,M11.1.0
34+
ui_date_time_format = US

0 commit comments

Comments
 (0)