Skip to content

Commit d9e255a

Browse files
Update readme and supporting files for 2.0.0 release.
1 parent c9df575 commit d9e255a

15 files changed

+66
-18
lines changed

README.md

Lines changed: 66 additions & 18 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,49 @@ 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+
- Caches artwork locally for performance
43+
44+
- **Multiple UI Modes**
45+
- Home view with track metadata and album art
46+
- Cover Art only view
47+
- Clock view with time and playback progress
48+
- Diagnostics view with system stats and Spotify state
49+
50+
- **OAuth 2.0 Authorization Flow**
51+
- Authentication and authorization (OAuth 2.0 flow) on device
52+
53+
- **Designed for ESP32 + TFT Touch**
54+
- Built using PlatformIO and Arduino
55+
- Touch event handling for UI buttons and screen navigation
56+
- Takes advantage of ESP32 dual-core architecture: UI logic runs on one core, while background tasks (e.g., album art refresh) run on the other
57+
58+
- **Extensible Design**
59+
- Modular architecture allows easy addition of new Views (UI screens)
60+
- Built-in monitoring tools for measuring system performance and UI responsiveness
61+
- Structured and tag-based logging system for easier debugging and analysis
62+
63+
64+
<!--Design Context Diagram -->
65+
<a href="./documentation/SCDesign.jpg">
66+
<img src="./documentation/SCDesign.jpg" alt="Design" width="600"/>
67+
</a>
68+
69+
## Using the Spotify Controller
70+
71+
- Tap the **Prev**, **Pause/Play**, and **Next** buttons to control music playback.
72+
- Tap the **album art** on the Home view to switch to the **Cover Art view**.
73+
- Tap the **clock** to switch to the **Clock view**.
74+
- Tap the **network status box** in the lower-right corner to open the **Diagnostics view**.
75+
76+
> For detailed display logic and diagnostics layout, see `DiagnosticsView.cpp`.
2377
2478
## Service level promise
2579

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

3892
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
3993

40-
2. Select "My New App"
94+
2. Select "Create app"
4195

4296
<img src="./images/SpotifyDashboard.png" width="400">
4397

4498
3. Fill out the form. Give your new app a name you can attribute to this project.
4599
It's safe to select "I don't know" for the type of application.
100+
Add "http://tp-spotify.local/callback/" to the Redirect URIs section.
46101

47-
<img src="./images/SpotifyAppSignUp1.png" width="400">
48-
49-
4. At the end of the 3 steps click "Submit"
50-
51-
<img src="./images/SpotifyppSignUp3.png" width="400">
102+
**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.
52103

53-
5. Set the unique Client ID and Client Secret as values for the respective variables in `settings.h`.
104+
<img src="./images/SpotifyCreateApp.png" width="400">
54105

55-
<img src="./images/SpotifyCredentials.png" width="400">
106+
**Don't forget to save your settings.**
56107

57-
6. Click on "Edit Settings". Add "http://tp-spotify.local/callback/" to the Redirect URIs section.
108+
4. Set the unique Client ID and Client Secret as values for the respective variables in `spotify.h`.
58109

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.
110+
<img src="./images/SpotifyClientId.png" width="400">
60111

61-
<img src="./images/SpotifyAppSettings.png" width="400">
62112

63-
7. Don't forget to save your settings.
64-
<img src="./images/SpotifyAppSettingsSave.png" width="400">

images/ClockView.jpg

957 KB
Loading

images/CoverArtView.jpg

750 KB
Loading

images/DiagnosticView.jpg

710 KB
Loading

images/HomeView.jpg

701 KB
Loading

images/SpotifyAppSettings.png

-149 KB
Binary file not shown.

images/SpotifyAppSettingsSave.png

-23.2 KB
Binary file not shown.

images/SpotifyAppSignUp1.png

-149 KB
Binary file not shown.

images/SpotifyClientId.png

131 KB
Loading

images/SpotifyClientId.png_original

137 KB
Binary file not shown.

0 commit comments

Comments
 (0)