How psychoducktech/psychos works
Project's Type and Purpose
• PsychOS is firmware for a hardware device (a keyboard-like input platform) that leverages FreeRTOS. It includes features like matrix scanning, rotary encoder handling, display management, USB HID, Bluetooth (BLE) support, buzzer tones, clock functions, and RGB underglow.
• The README confirms that this firmware is tested on the ESP32-S3 and supports several hardware setups. This means the firmware must abstract hardware interactions while managing multiple real-time tasks.
File Structure
• The top-level “source” directory houses all the project code and contains subdirectories for include files and source files.
• The “source/src” directory holds the corresponding C/C++ source files. Notably, there are separate directories for tasks (BLEHandler, buzzer, clock, etc.) and utils. This separation hints at a modular design where each hardware function or feature is implemented as an independent task or utility.
• The presence of configuration files (e.g., platformio.ini) and GitHub workflows for building indicates build automation and CI integration.
Important Architectural Components
a. Core Firmware/RTOS Layer:
• The firmware runs on FreeRTOS, so include a “Task Manager” component that schedules and manages all independent tasks (e.g., matrix scanning, display updates, rotary encoder, USB HID communication).
b. Hardware Abstraction:
• Driver modules under “drivers” (multiplexer, rotary encoder) as the interface between physical hardware (buttons, encoder, display) and the higher-level tasks.
c. Feature Modules:
• Tasks for each major feature: BLE Handler, Display Handler, Command Processor, Host Communication Bridge, Knob Handler, Matrix Scan, RGB Handler, Serial Handler, WPM Counter, etc.
• A component for “Display & Fonts” (under display and fonts) that is responsible for rendering the user interface.
• “Utils” as supporting modules for benchmarking, initialization of BLE/matrix, EEPROM management (NVS), etc.
d. External and Configuration Elements:
• Build/CI pipeline (GitHub workflows, PlatformIO config) as a separate subsection for development integration.
Relationships and Interactions
• Matrix hardware (a multi-key matrix via scanning logic),
• Rotary encoder (for volume control with smooth increment/decrement and a press to mute),
• (using a dedicated display driver, with associated fonts and screen management),
• Buzzers and RGB LED components.
• “Host Communication Bridge” as interfacing with a PC via USB HID (and optionally BLE) to relay the keystrokes and settings.
Additional Details
• How initialization modules in “utils” help set up BLE and matrix scanning—this supports the overall system initialization phase.
• To represent the layering: Hardware Interfaces → Drivers → RTOS Task Manager → Application Logic (features) → External Communication.