Thoth's Oracle PCB

Thoth's Oracle

Table of Contents:

• Features
• Make your own
• How it works
  • Hardware
  • Software
  • Firmware
• Configuration
• FAQ
• Installation
  • Windows
    • Launch on startup
  • Linux
    • Example
    • GNOME Specific
    • Linux launch on startup
    • Phone Connection
• License

USB operated media display/controller for Windows, Linux(, MacOS WIP).

USB music display helps you keep track of what you are listening to without taking up precious screen space. Thoth's Oracle provides a one stop shop for checking on the current media information and basic controls such as skipping tracks, playing and pausing and adjusting the volume.

Features:

• Software agnostic companion app listens to operating system rather than a specific program like Spotify app or Firefox
  • If OS is aware of media, companion app will be as well
• 320x480 IPS display for maximum readability
• Display the available metadata of current media
  • Thumbnail
  • Title
  • Album
  • Artist
  • Duration and current position
• Basic media control
  • Play/pause
  • Skip track
  • Previous track
  • Mute/unmute
  • Volume control
• Tiltable screen
• Brightness control
• Lightweight companion app (peak RAM usage <80MB, avg <50MB)
• Wallpaper mode to cycle through local images in Wallpaper folder
• Standard components allowing for custom configuration and ease of assembly
  • Hotswappable MX style or Kailh Choc low-profile style switches
  • 6mm rotary potentiometer and encoder
  • 3D printed shell
  • One screw size
  • Small PCB with mostly THT components. Only the hotswap sockets are SMD (hand solderable)

Make your own!

Everything you need to make your own should be in BOM-and-Assembly. Let me know if anything can be improved.

How it works:

Hardware:

• An ESP32-S3 zero controls all of the device inputs and displays information on screen
• ESP32 communicates with PC over USB C OTG connection

Software:

• The software is written in C# for the Windows App.
• Companion app catches changes to focused media broadcast from the operating system.
• On media change, Thoth requests metadata, packages it, then waits for signal from the Oracle that it is ready to receive the data.
• Metadata is packaged as follows with header tag denoting type, size, etc.:
  • System information containing date and time
  • Media duration and position
  • Media text: title, album, artist
  • Thumbnail
• All text is converted to UTF-8.
• Once ready signal is received, Thoth sends a package over serial port, waits for ready signal, then proceeds to next package.
• When input commands are received, Thoth requests the OS completes the action.

Firmware:

• The firmware is written in C.
• All serial communications are handled by Core 1. Core 0 handles all display features running LVGL.
• Thoth's Oracle emits ready signal periodically while idling, and emits control commands as soon as they are inputted by the user.
• When data is received, the header tag is analyzed to know which buffer it should be put in.
• If there is an error with the header tag, all subsequent data is dumped, and firmware waits for a pause in data transmission before resetting header information and buffers, and returning to idle state.
• If no errors are detected, data is placed directly into the correct buffer for further analysis in the case of text data, or displayed immediately for images (rolling effect as image loads).
• Media text starts as one big array of characters, and is split into the three fields using escape characters inserted by companion app.
• The font used is DejaVu-Sans in 16 point, with as much of the character set as is hopefully reasonable to ensure maximum language compatibility, without containing the entire set.
• Once the expected number of bytes is received based on the header tag, the header is reset, Oracle emits a ready signal, then enters idle state.
• If firmware times out before receiving expected data, header tag is reset and device enters idle state.

Configuration:

The following can be configured from companion app or config file

• Which program to listen to
• Port the device is connected to
• Sensitivity of volume knob
• Which output device to control (default, speakers, headphones, etc.)
• Wallpaper mode

FAQ:

Someone ask me something, please.

Installation:

Windows:

Companion app is provided as portable application that doesn't need installation. Just download and extract the software file for your system wherever you want and run it!

Windows launch on startup:

• Right click on .exe and select 'Create shortcut'
• Copy the shortcut to %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup

Linux (Tested on Ubuntu):

• Extract folder to desired location.
• Edit .desktop file to match new location if you want app to appear in Apps list.
• Validate and install

desktop-file-validate thoths_oracle.desktop
desktop-file-install thoths_oracle.desktop

• Check which port Oracle is connected to. It should show up as USB ACM device.
• Verify the device's group permissions are rw and note the group.
• Verify you are part of the group.
• Reboot

Example:

$ sudo dmesg | grep tty
[    0.139832] printk: legacy console [tty0] enabled
[    6.652489] cdc_acm 1-5.2.2:1.0: ttyACM0: USB ACM device
$ sudo chmod g+rw /dev/ttyACM0
$ ls -ld /dev/ttyACM0
crw-rw---- 1 root dialout 166, 0 Dec  2 18:21 /dev/ttyACM0
$ sudo usermod -a -G dialout dominique
$ sudo reboot

GNOME Specific:

GNOME may need an extension such as AppIndicator and KStatusNotifierItem Support to display the menu along the top panel. Otherwise, the program will run normally but all settings will have to be changed through the configuration file.

Linux launch on startup:

Using Startup Applications Preferences:

• Add a new entry named Thoths Oracle.
• If you have installed the .desktop file, set the command to gtk-launch thoths_oracle.desktop
• Otherwise, change the command to the location you extracted Thoth's Oracle in.
  • eg. /home/dominique/Documents/Programs/Thoths_Oracle_linux/Thoths_Oracle
• Add a comment if desired and save.

Phone connection to Linux:

To use audio from phone with all the same features, install GSConnect for GNOME, or KDE Connect for KDE Plasma and follow the instructions to set it up.
Add kdeconnect or gsconnect to config.yaml in MonitoredProgram section.
Next, connect phone (source) to Linux (sink) through bluetooth for audio.
Done!

License:

Thoth's Oracle is licensed under GPL-3.0