V2.0.0 Initial Release: Complete Spotify Controller for ESP32 with UI and Album Art Support

.gitignore

@@ -1,2 +1,4 @@
 .pio
 .vscode
+src/compile_time.h
+data/user.ini

README.md

@@ -4,7 +4,23 @@
 
 Spotify controller application for the [ThingPulse Color Kit Grande](https://thingpulse.com/product/esp32-wifi-color-display-kit-grande/).
 
-[![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/)
+<!-- Main image -->
+<a href="./images/HomeView.jpg">
+  <img src="./images/HomeView.jpg" alt="HomeView UI Example" width="600"/>
+</a>
+
+<!-- Thumbnails -->
+<p>
+  <a href="./images/CoverArtView.jpg">
+    <img src="./images/CoverArtView.jpg" alt="Cover View" width="200"/>
+  </a>
+  <a href="./images/ClockView.jpg">
+    <img src="./images/ClockView.jpg" alt="Clock View" width="200"/>
+  </a>
+  <a href="./images/DiagnosticView.jpg">
+    <img src="./images/DiagnosticView.jpg" alt="Diagnostic View" width="200"/>
+  </a>
+</p>
 
 ## Purpose of this project
 
@@ -15,11 +31,53 @@ The currently playing song can be paused, resumed and skipped to the next or pre
 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.
 In order to run this project on your device, you will need to setup an application on your Spotify dashboard (instructions below).
 
-## Features
+ ## Features
 
- - Artwork download
- - Control player on touch screen: play, Pause, next, prev
- - Authentication and authorization (OAuth 2.0 flow) on device.
+- **Spotify Playback Control**
+  - Play, pause, skip to next/previous track from the touch screen
+  - Control playback on any active Spotify Connect device linked to your account (e.g., phone, browser, smart speaker)
+
+- **Album Art Display**
+  - Downloads and displays album artwork via Spotify Web API
+  - Syncs background color with album art
+  - Caches artwork locally for performance
+
+- **Multiple UI Modes**
+  - Home view with track metadata and album art
+  - Cover Art only view
+  - Clock view with time and playback progress
+  - Supports 12-hour and 24-hour time formats
+  - Diagnostics view with system stats and Spotify state
+
+- **OAuth 2.0 Authorization Flow**
+  - Authentication and authorization (OAuth 2.0 flow) on device
+
+- **Designed for ESP32 + TFT Touch**
+  - Built using PlatformIO and Arduino
+  - Touch event handling for UI buttons and screen navigation
+  - Takes advantage of ESP32 dual-core architecture: UI logic runs on one core and background song and album art refreshing runs on the other
+
+- **Extensible Design**
+  - Modular architecture allows easy addition of new Views (UI screens)
+  - Built-in monitoring tools for measuring system performance and UI responsiveness
+  - Structured and tag-based logging system for easier debugging and analysis
+  - Optional `user.ini` file for easy credential and time zone management
+
+
+<!--Design Context Diagram -->
+<a href="./documentation/SCDesign.jpg">
+  <img src="./documentation/SCDesign.jpg" alt="Design" width="600"/>
+</a>
+
+## Using the Spotify Controller
+
+- Tap the **Prev**, **Pause/Play**, and **Next** buttons to control music playback.
+- Tap the **album art** on the Home view to switch to the **Cover Art view**.
+- Tap the **clock** to switch to the **Clock view**.
+- Tap the **network status box** in the lower-right corner to open the **Diagnostics view**.
+- 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. 
+
+> For detailed display logic and diagnostics layout, see `DiagnosticsView.cpp`.
 
 ## Service level promise
 
@@ -37,28 +95,52 @@ See our [instructions](https://docs.thingpulse.com/guides/esp32-color-kit-grande
 
 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
 
-2. Select "My New App"
+2. Select "Create app"
 
    <img src="./images/SpotifyDashboard.png" width="400">
 
 3. Fill out the form. Give your new app a name you can attribute to this project.
 It's safe to select "I don't know" for the type of application.
+Add "http://tp-spotify.local/callback/" to the Redirect URIs section.
+
+   **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.
+
+   <img src="./images/SpotifyCreateApp.png" width="400">
+
+   **Don't forget to save your settings.**
+
+4. Set the unique Client ID and Client Secret as values for the respective variables in `src/spotify.h`.
+
+   <img src="./images/SpotifyClientId.png" width="400">
+
+### Filesystem setup
+
+5. Upload the file system to the device
+
+- Hit the PlatformIO icon on the navigation bar on the left side (alien face).
+
+- 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.
+
+ <img src="./images/platformio-filesystem.png" width="400">
+
+- If startup fails with the following message displayed: "FATAL ERROR - Filesystem Not Initialized", this step was not successful or done.
+
+### User settings
 
-   <img src="./images/SpotifyAppSignUp1.png" width="400">
+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.
 
-4. At the end of the 3 steps click "Submit"
+ <img src="./images/UserSettings.png" width="400">
 
-   <img src="./images/SpotifyppSignUp3.png" width="400">
+See [full user settings documentation](./documentation/UserSettings.md) for details about all available fields, encryption options, and using `user.ini`.
 
-5. Set the unique Client ID and Client Secret as values for the respective variables in `settings.h`.
+ ### Upload code to device
 
-   <img src="./images/SpotifyCredentials.png" width="400">
+ 7. Select the General > Upload and Monitor task. You do this every time you change code or settings.h.
 
-6. Click on "Edit Settings". Add "http://tp-spotify.local/callback/" to the Redirect URIs section.
+  <img src="./images/platformio-task-upload.png" width="400">
 
-   **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.
+See [instructions](https://docs.thingpulse.com/guides/esp32-color-kit-grande/#development-environment) if you encounter problems and need Trouble Shooting tips.
 
-   <img src="./images/SpotifyAppSettings.png" width="400">
+## Tips and Known Issues
 
-7. Don't forget to save your settings.
-   <img src="./images/SpotifyAppSettingsSave.png" width="400">
+To see a list of tips and known issues, see [Tips and Known Issues](./documentation/TipsAndKnownIssues.md).

boards/custom_esp-wrover-kit.json

@@ -0,0 +1,54 @@
+{
+    "_comment": "This is a custom board configuration for an ESP32 with 8MB PSRAM. - Jan 8, 2025.",
+    "build": {
+      "arduino":{
+        "ldscript": "esp32_out.ld"
+      },
+      "core": "esp32",
+      "extra_flags": "-DARDUINO_ESP32_DEV",
+      "f_cpu": "240000000L",
+      "f_flash": "40000000L",
+      "flash_mode": "dio",
+      "hwids": [
+        [
+          "0x0403",
+          "0x6010"
+        ]
+      ],
+      "mcu": "esp32",
+      "variant": "esp32"
+    },
+    "connectivity": [
+      "wifi",
+      "bluetooth",
+      "ethernet",
+      "can"
+    ],
+    "debug": {
+      "default_tool": "ftdi",
+      "onboard_tools": [
+        "ftdi"
+      ],
+      "openocd_board": "esp32-wrover.cfg"
+    },
+    "frameworks": [
+      "arduino",
+      "espidf"
+    ],
+    "name": "Espressif ESP-WROVER-KIT",
+    "upload": {
+      "flash_size": "8MB",
+      "maximum_ram_size": 327680,
+      "maximum_size": 8388608,
+      "protocols": [
+        "esptool",
+        "espota",
+        "ftdi"
+      ],
+      "require_upload_port": true,
+      "speed": 460800
+    },
+    "url": "https://espressif.com/en/products/hardware/esp-wrover-kit/overview",
+    "vendor": "Espressif"
+  }
+

data/user.ini.template

@@ -0,0 +1,34 @@
+;
+; User settings for Spotify Controller.  Make sure to Upload Filesystem
+; Image after updating.
+;
+; ----------------------------------------------------------------------
+; Privacy Levels:
+;    0 - None (credentials in clear text)
+;    1 - Good (encrypted, reusable across devices)
+;    2 - Better (encrypted, tied to this device)
+; ----------------------------------------------------------------------
+[vault]
+privacy_level = 0
+; ----------------------------------------------------------------------
+; WiFi:
+; ----------------------------------------------------------------------
+[wifi]
+ssid = Your WiFi Name Here
+password = Your WiFi Password Here
+; ----------------------------------------------------------------------
+; Spotify:
+; ----------------------------------------------------------------------
+[spotify]
+client_id = Enter your Spotify Client ID here
+client_secret = Enter your Spotify Client Secret here
+; ----------------------------------------------------------------------
+; System Settings:
+; Timezone format - see
+;      https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv
+; For US date and time formatting, include:
+; ui_date_time_format = US
+; ----------------------------------------------------------------------
+[system]
+timezone = CST6CDT,M3.2.0,M11.1.0
+ui_date_time_format = US